API Analysis Result Interpretation

Analysis Result Interpretation Guide

The UPSTREAM and ANALYSIS requests returns a JSON object which contains analysis result.
Following table summarizes fields, values and their descriptions of the returned JSON object.

JSON Object Field Description Version Support Notes
{
“status”:”success”, The status of request. Can be “success” or “error”.
“result”:{ The object of analysis results.
  “duration”:”21513.25″, Duration of voice data processed in milliseconds
  “sessionStatus”:”Done”, Session status can be:
“Started” – no analysis data yet produced,
“Processing” – intermediate results , more analysis can be expected,
“Done” – analysis session has ended, the result has an analysis results for whole session.
  “analysisSegments”:[ The array containing analysis segments
  { First analysis segment object. Following fields are  properties of the segment
     “offset”:0, Offset of the segment in milliseconds from the beginning of the session.
     “duration”:10000, Segment duration in milliseconds
     “end”:10000, The end of the segment in milliseconds V4 and above
     “analysis”:{ Analysis object. Contains analysis values for the segment. The content of the object is provided as example. The real fields can vary depending on license type
         “Temper”:{ Temper Object
           “Value”:”21.00″, Value of Temper
           “Group”:”low”, Group of Temper, “ambiguous” – means that value cannot be calculated for the slice ambiguous value: V4 and above
           “Score”:”92.00″, Confidence score of Temper (92 % positive) V4 and above
},
        “Valence”:{ Valence Object. (similar to Temper object)
           “Value”:”23.00″,            Value of Valence
           “Group”:”negative”, Group of Valence, ambiguous – means that value cannot be calculated for the slice ambiguous value: V4 and above
           “Score”:”94.00″, Confidence score of Temper (94 % positive) V4 and above
},
        “Arousal”:{ Arousal Object. (similar to Temper object)
           “Value”:”24.00″, Value of Arousal
           “Group”:”low”, Group of Arousal, ambiguou – means that value cannot be calculated for the slice ambiguou value: V4 and above
           “Score”:”80.00″, Confidence score of Arousal (94 % positive) V4 and above
         },
        “Mood”:{ Mood Object, Contains Mood Group objects
           “Group7”:{ Mood Group 7 Object
           “Primary”:{ Primary mood of Mood Group 7
              “Id”:7, Id of the phrase
              “Phrase”:”Worried” Phrase (Primary Mood Group 7 Phrase)
           },
           “Secondary”:{ Secondary
              “Id”:4, Id of the phrase
              “Phrase”:”Frustrated” Phrase (Secondary Mood Group 7 Phrase)
           }
        },
           “Group11”:{
           “Primary”:{
              “Id”:3,
              “Phrase”:”Defensivness,Anxiety”
           },
           “Secondary”:{
              “Id”:7,
              “Phrase”:”Loneliness,Unfulfillment”
           }
        },
           “Group21”:{
           “Primary”:{
              “Id”:21,
              “Phrase”:”unhappiness”
           },
           “Secondary”:{
              “Id”:16,
              “Phrase”:”loneliness”
           }
        },
        “Composite”:{ Composite Mood Object
           “Primary”:{
              “Id”:274,
              “Phrase”:”Painful communication. High sensitivity.”
           },
          “Secondary”:{
             “Id”:241,
             “Phrase”:”Longing for change. Seeking new fulfillment. Search for warmth.”
           }
        }
      }
    }
  },
{, Following analysis segment objects
……
},
],
 “analysisSummary”:{ The object of analysis summary
  “AnalysisResult”:{ The object of analysis summary results
  “Temper”:{ Temper Summary Object
  “Mode”:”low” Most frequent Temper Group
  “ModePct”:”100.00″ The Percentage of the most frequent Temper group
  },
  “Valence”:{ Valence Summary Object
  “Mode”:”negative” Most frequent Valence Group
  “ModePct”:”100.00″ The Percentage of the most frequent Valence group
  },
  “Arousal”:{ Arousal Summary Object
  “Mode”:”low” Most frequent Arousal Group
  “ModePct”:”100.00″ The Percentage of the most frequent Arousal group
  }
  }
  }
  }
 }

Table of Mood Phrases

Getting a Table of Mood Phrases in your language

The Moods table provides mapping between mood Id (returned in Moods section of analysis result) and a text of the Mood phrases.

Example of mood section with Ids

“Mood”: {
“Group21”: { “Primary”: { “Id”: 1, // will be mapped to “Creative, Passionate”
},
“Secondary”: { “Id”: 7, // will be mapped to “Loneliness, Unfulfillment”
}
},
}

There is no need to fetch this table each time a particular phrase required. In order to reduce network traffic and CPU requirements, the application can pre-load this table into its memory and then use each time when the phrase text is required.

Please be informed that not all languages are supported yet. Please contact Beyond Verbal to get information on how to support the language of your interest.

Moods Request

GET URL: https://apiv3.beyondverbal.com/v3/moods/{groupeName}/{language}

Moods Request Parameters

Name Location (BodyUrlHeader) Optional Explanation
Group name Url No This field specifies the Mood type for which table is requested.
Supported values:
Group11
Group21
Composite
Language Url Yes Requested language according to ISO-639 and ISO-3166 standards. Default en-us
Alternatively you can set required language in standard HTTP Accept-Language header
Auth token Authorization Header No

Example

GET https://apiv3.beyondverbal.com/v3/moods/Group11/

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

OK (200) Response:

[
{“Id”:1,”Phrase”:”Creative, Passionate”},
{“Id”:2,”Phrase”:”Criticism, Cynicism”},
{“Id”:3,”Phrase”:”Defensivness, Anxiety”},
{“Id”:4,”Phrase”:”Friendly, Warm”},
{“Id”:5,”Phrase”:”Hostility, Anger”},
{“Id”:6,”Phrase”:”Leadership, Charisma”},
{“Id”:7,”Phrase”:”Loneliness, Unfulfillment”},
{“Id”:8,”Phrase”:”Love, Happiness”}


]

API Metadata Guide

Using Metadata with Beyond Verbal REST API

Metadata field of the START request allows to attach arbitrary information to each analysis session.

Most common usage of the metadata field is to uniquely identify particular user, device or group of users for later aggregated analysis.
Examples of unique identifiers are: email address, mobile phone number, physical (manufacturer) device ID, facebookId, twitter ID.

Set the clientId field value to your unique identifier. Example

POST https://apiv3.beyondverbal.com/api/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

{
“dataFormat”: {“type”: “WAV”},
“metadata”:{“clientId” : “+991199483679”}
}

Optionally you can also set this id as additional field of metadata object in order to specify it’s origin

Field
email Client email
phone Client phone (mobile)
deviceId Physical device ID
facebookId Facebook Id
trwitterId Twitter Id

 

Example where clientId is a phone number:

 

POST https://apiv3.beyondverbal.com/api/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

{
“dataormat”: {“type”: “WAV”},
“metadata”:{“clientId”: “+991199483679”, “phone” : “+991199483679”}
}

 

Example where the clientId is email:

POST https://apiv3.beyondverbal.com/api/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

{
“dataormat”: {“type”: “WAV”},
“metadata”:{
“clientId”: “someone@someplace.com”,
“email” : “someone@someplace.com”
}
}

NEW! Confidence score

Confidence Score – Feature Description

Starting at API version V4, Beyond Verbal has added a new feature to its API output called confidence score.

This document explains the provision of a corresponding confidence score to each emotion output & how Beyond Verbal’s
user community will benefit.

Along with various emotions outputs (Temper, Valence, Arousal) & their group (e.g. low, med, high), Beyond Verbal is
now providing a corresponding confidence score (from 0 to 100) for each such output.
*See example of the API output in Exhibit A

The confidence score is expressed as a metric that reflects the distributions of likelihoods of the identified
emotion output group (e.g. low arousal).

Using this confidence metric, Beyond Verbal will now return the value “unknown” when the confidence score of an
emotion group does not exceed a predetermined threshold. Accordingly, Beyond Verbal excludes speech segments when
they have been deemed to be unanalyzable (e.g. due to audio quality issues like excessive background noise).

By excluding unanalyzable samples, Beyond Verbal will filter out ambiguous & weak speech segments, thereby
significantly improving overall emotions analytics accuracy & performance.

Additionally, the provision of the confidence score empowers our users to use this parameter during API integration &
when customizing their own application logic. For example, on the user’s end, the application can exclude any Beyond
Verbal output with a confidence score below a specific threshold e.g. 65. This may be helpful in use cases where
there is a large voice data set & emotions analytics accuracy is more important than granularity/frequency of
analysis.

Beyond Verbal’s API output overall accuracy ranges from 70% for more ambiguous speech segments to above 90% for more
unambiguous & high quality speech segments.

When Beyond Verbal API users setup & adjust their own confidence score filter rules, the following approximate rule
of thumb should be helpful to clarify the expected impact on accuracy at varying levels of confidence:

Accuracy increases approximately 4-5% for a 10-point increase of the selection threshold. For example, rejecting
samples with confidence score below 70 leads to an increase in Beyond Verbal engine accuracy of 5%.

Therefore, depending on the use case & user’s preference for accuracy over total number of analyzed segments, by
filtering out segments with lower confidence scores, user can achieve accuracy in the 90% range.

User community feedback is always welcomed via api@beyondverbal.com.

Exhibit A

Example of API output including Score
confidence_score1

Beyond Verbal API Terms and Conditions

This Agreement sets forth the terms and conditions concerning the use of Beyond Verbal Communication, Ltd’s (herein after “the Company”) Emotions Analytics API (herein after “the API”)

The Company is willing to grant the License (as defined below) to the Licensee, upon and subject to the terms and conditions of this agreement.

NOW, THEREFORE, the parties agree as follows:

The Terms and Conditions (the “Terms” or the “Agreement“) shall govern your usage of the API in all respects (the “Usage“). Please read and confirm the Terms and Conditions prior to downloading and using the API. By Accepting these condition you agree to be bound by the terms and conditions of this Agreement, and this will be a legally binding agreement between you and The Company governed by the laws of England and Wales.

If you do not agree with any of the terms and condition contained in this Agreement, please do not install nor use the API. If you do not agree with any of the terms and conditions contained in this Agreement and have already downloaded the API, please uninstall it now.

You may find additional technical terms and information with respect to the API at http://www.beyondverbal.com/api/, all of which are subject to change from time to time. It is your sole responsibility to ensure that you are familiar with the latest terms and conditions.

References in this Agreement to “you” or “your” refer to both you and any person or entity on whose behalf you act, if any.

1. Grant of License Key

  1. The Company grants you a license key to use the API, on a personal, worldwide, non-exclusive, non-transferable, non-assignable, non-sub licensable and revocable basis subject to the terms and conditions set forth in these Terms (the “Key“) and solely for the purpose of analyzing speakers emotions from the voice within your application, solution or device.(“Applications“)
  2. Your use of the API is subject to the Terms and Conditions of this agreement entered into effect between you and The Company located at 125 Yigal Alon Street, 67443, Tel Aviv, Israel.
  3. The Company’s Technology is protected by various intellectual property laws and other property rights and laws of the United States and other countries.
  4. You will not acquire any right, title or interest in and to the Company’s, trademarks, or any other intellectual property owned or licensed by The Company, by entering into this Agreement or otherwise by the Usage.
  5. You represent that you have full power and authority to accept these Terms and Conditions. If you are accepting the Terms and Conditions on behalf of your employer, you represent that you have full legal authority to bind your employer to these Terms and Conditions.
  6. In order to use the API, you must check the box to indicate your agreement to the terms and conditions of the API and sign up for a Developer Account, by which you express your acceptance and agreement to these Terms and Conditions.
  7. If you do not agree to the Terms and Conditions, The Company will not grant you the Key to use the API.
  8. The Company reserves the right to make changes to the Terms and Conditions from time to time and at its sole discretion and will make available a copy of the most recent Terms and Conditions on http://www.beyondverbal.com/api/. Your continued use of the API following such changes to the Terms and Conditions constitutes your acceptance of the updated Terms and Conditions.
  9. The Company, in its sole and absolute discretion, may choose to alter, suspend or cease any aspect and/or component of the API or discontinue any service that may be available by the API entirely and to its sole discretion. In such event, The Company shall make reasonably commercial efforts to notify you of such change, by a prior notice to the email address you provided when registering your Developer Account for the API. You shall maintain accurate details of your registered email address in your Developer Account during the course of this Agreement, failure to do so may result in a cancellation of your granted API Key.
  10. You shall not charge others to use or access the API directly, but you may charge others to use or access your Applications.
  11. All rights not expressly granted hereunder are reserved by The Company and its licensors retain all ownership of the API.

2. Use of The API

You agree to use the API solely for the following purposes:

  1. That are permitted by the Terms and Conditions;
  2. That are permitted by any applicable third party contract, law or regulation in the relevant jurisdictions; and
  3. That comply with all applicable policies and guidelines made available by The Company.

3. Limits of Usage & Fees

  1. In order to access and use the API, you must register for a Developer Account. You agree that any information you give to The Company in connection with your The Company Developer Account or use of the API will be accurate and up to date.
  2. The Company will provide you with an application identification key (“the API Key”) which you will incorporate into your application or service.
  3. You may only create a single Emotions Analytics API Key and may not transfer it to any third party or allow usage thereof by any third party without the prior written consent of The Company.
  4. The company will grant you 1 month free access (at no consideration) limited to no more than 100 x 1 minute sessions per 24 Hours or maximum 3000 x 1 minute session per month, (“API Usage Limits“).
  5. For the avoidance of doubt audio recordings may not exceed 3 consecutive minutes.
  6. The Company may charge you for using the API in the future, in its sole and absolute discretion. If The Company so decides, it shall provide you with a notice prior to the respective change in these Terms and Conditions, to the email you provided when registering for the API.

4. Your Obligations And Restrictions

  1. You agree to:
    1. Comply with all terms and Conditions of the The Company Privacy Policyand all the Emotions Analytics API Documentation.
    2. Not violate the rights of any third party in connection with your use of the API.
    3. Comply with all applicable laws, including but not limited to data protection and privacy laws, which may affect your use of the API.
    4. Retain sole responsibility for receiving and securing clear, express consent from your users, granting you permission to access and/or record their voice files.
    5. Comply with the Attribution requirements as set forth in Section 5.
  2. Any breach of the restrictions set forth in this Agreement will immediately terminate your right to use the API as set forth in these Terms and Conditions. You are restricted from and will not assist or enable others to:
    1. Hide your identity when accessing the API
    2. Copy, modify, reverse engineer, decompile or otherwise attempt to extract the source code of The Company service or any part thereof.
    3. Use any of the API features to violate applicable laws, any third-party right, including any breach of confidence, copyright, trademark, patent, trade secret, moral right, privacy right, right of publicity, or any other intellectual property or proprietary right.
    4. Use the API in connection with or in promotion of products or services that constitute or promote spyware, adware, viruses, worms, defects, Trojan horses or any other malicious code or otherwise in a manner that is abusive.
    5. Use the API in a manner that will negatively impact the stability of The Company’s website, mobile apps or third party licensees of the API or its Brand name.
    6. Wrap, sell, lease, distribute or sublicense access and rights to use The Company’s Technology.
    7. Sell, lease, distribute, or sublicense the data obtained from the API for use by a third-party service.
    8. Access the API in order to monitor its availability or functionality, or for any other competitive purpose. This does not restrict Licensee from developing Emotions Analytics for Licensee’s business.
    9. Collect or store any of The Company’s application user data or make any attempt to obtain it.
    10. Use the API to violate the security of any computer network, mobile device, social networks, crack passwords or security encryption codes.
    11. Use the API for any illegal or unauthorized purpose (international users agree to comply with laws in their jurisdiction regarding online conduct and acceptable content).
    12. Take any action that imposes, or may impose in our sole discretion, an unreasonable or disproportionately large load on The Company’s technology infrastructure.
    13. Attempt to gain unauthorized access to The Company’s or any third party’s computer systems, mobile devices or networks connected to the API or to other users’ accounts on social networks through hacking, password mining or any other means.
    14. Use the API in violation of the Terms and Conditions.

5. Attribution

  1. The Company grants you a revocable worldwide, royalty-free, non-transferable, non-assignable, non-sub licensable, and non-exclusive license to display The Company’s logo, trademarks, trade names, service marks, and other distinctive brand features (“The Company Brand”) solely for the purpose of attributing your authorized use of the API in connection with your application or service.
  2. You shall not remove any copyright, trademark, proprietary right, disclaimer or other warning notice included in or embedded in any part of the API.

6. Marketing Rights

  1. At your sole discretion, you may agree to grant The Company a revocable, worldwide, royalty-free, non-transferable, and non-exclusive license to use your brand, logo, trademarks, trade names, service marks, and other distinctive features to publicize or advertise your use of the API provided that such a grant was given in written format to Beyond Verbal Communication Ltd.
  2. You represent and warrant to The Company that in the event that such a grant was given, the granter have all the rights, power, and authority necessary to grant the above rights and licenses and will bear the full consequences legal or other in the event that you did not have the adequate rights, power and authority in this regard.

 

7. Support

  1. On the date hereof, the API is provided with limited maintenance and support services.
  2. The Company has the sole discretion to terminate this maintenance and support without any notice to you and at any time it so deems necessary.
  3. For any queries please send a mail to support@beyondverbal.com and one of our technical members will get back to you within due course.

 

8. Warranty

THE API IS PROVIDED “AS IS” AND ON AN “AS AVAILABLE” BASIS WITH ALL FAULTS, WITH NO WARRANTY, STATUTORY, EXPRESS OR IMPLIED, OF ANY KIND, AND THE COMPANY EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR REQUIREMENTS, AVAILABILITY, SECURITY, TITLE AND/OR NON-INFRINGEMENT. YOUR USE OF THE API IS SOLELY AT YOUR OWN DISCRETION AND RISK, AND YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE THAT RESULTS FROM THE USE OF THE API, INCLUDING, BUT NOT LIMITED TO, ANY DAMAGE TO ANY OF YOUR EQUIPMENT OR LOSS OF DATA. THE COMPANY DOES NOT REPRESENT OR WARRANT THAT THE API IS FREE OF INACCURACIES, ERRORS, BUGS, OR INTERRUPTIONS, OR IS RELIABLE, ACCURATE, UPDATED, COMPLETE, SECURE, AVAILABLE AT ALL TIMES OR OTHERWISE VALID.

 

THE COMPANY FURTHER DISCLAIMS ALL REPRESENTATIONS OR WARRANTY THAT DEFECTS IN THE OPERATION OR FUNCTIONALITY OF ANY SOFTWARE OR APPLICATION PROVIDED TO YOU AS PART OF THE USAGE WILL BE CORRECTED AND THAT ANY CONTENT OR APPLICATION AVAILABLE AT OR THROUGH THE COMPANY IS FREE OF VIRUSES OR OTHER HARMFUL COMPONENTS. NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY ANY THE COMPANY EMPLOYEE, REPRESENTATIVE OR DISTRIBUTOR OR OTHERWISE BY THE API SHALL CREATE ANY WARRANTY FOR THE API, ITS USAGE OR OTHERWISE, AND YOU MAY NOT RELY ON ANY SUCH INFORMATION OR ADVICE. THE COMPANY AND ITS LICENSORS EXPLICITLY DISCLAIM ANY AND ALL WARRANTIES WITH RESPECT TO THE API.

9. Limited Liability

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE COMPANY AND/OR ANYONE ON ITS BEHALF (INCLUDING WITHOUT LIMITATION ITS AFFILIATES, DIRECTORS, EMPLOYEES, LICENSORS OR PARTNERS) OR IN RELATION THEREWITH, SHALL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO YOU OR TO ANYONE ELSE FOR YOUR INSTALLATION AND/OR USE OF THE API, OR RELIANCE ON ANY USAGE MADE WITH IT, FOR ANY DIRECT, INDIRECT, INCIDENTAL, PUNITIVE, CONSEQUENTIAL, SPECIAL OR EXEMPLARY DAMAGES OF ANY KIND, ARISING OUT OF OR IN CONNECTION WITH USE OF THE API (INCLUDING WITHOUT LIMITATION THE COST OF COVER, DAMAGES ARISING FROM LOSS OF DATA, USE, PROFITS OR GOODWILL AND ANY OTHER INTANGIBLE LOSS), WHETHER BASED ON BREACH OF CONTRACT, BREACH OF WARRANTY, TORT (INCLUDING NEGLIGENCE, PRODUCT LIABILITY OR OTHERWISE), OR ANY OTHER PECUNIARY LOSS, WHETHER OR NOT THE COMPANY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY ARISING OUT OF THIS AGREEMENT.

UNDER NO CIRCUMSTANCES SHALL THE COMPANY BE LIABLE TO YOU FOR ANY AMOUNT OR ANY CLAIM.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. IF YOU RESIDE IN SUCH A JURISDICTION, THE ABOVE LIMITATIONS SHALL APPLY TO YOU TO THE FULLEST EXTENT PERMITTED UNDER APPLICABLE LAW.

THE COMPANY EXPRESSLY REPRESENTS THAT IT SHALL NOT BE LIABLE FOR: ANY LOSS OR DAMAGE AS A RESULT OF INACCURATE INFORMATION; ANY CHANGES IT MAY MAKE TO THE API OR USAGE THEREOF; ANY PERMANENT OR TEMPORARY CESSATION IN THE PROVISION OF THE USAGE (OR ANY FEATURES WITHIN IT) AND EMOTIONS ANALYTICS API; ANY DELETION OF, CORRUPTION OF, OR FAILURE TO STORE ANY CONTENT AND OTHER COMMUNICATIONS DATA MAINTAINED OR TRANSMITTED BY OR THROUGH YOUR USAGE; ANY VIRUSES (REGARDLESS OF THE SOURCE OF ORIGINATION); ANY LOSS OF DATA OR DAMAGE TO ANY OF YOUR EQUIPMENT, APPLICATION, PRODUCT OR SERVICE THAT YOU MAY BE OPERATING THROUGH THE API FROM HARMFUL COMPONENTS THAT MAY BE DOWNLOADED TO YOUR EQUIPMENT IN THE COURSE OF SUCH USAGE.

YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM THE INSTALLATION AND/OR USAGE OF THE API, BY YOU.

 

10. Confidentiality

During the term of this Agreement, the Company may disclose to you (the “Receiving Party”) information in connection with the performance of this Agreement, including, without limitation, information concerning the Company’s business, business relationships, business plans, contacts, products, services, content, technical data, trade secrets, proprietary information, customer or advertiser lists, marketing plans, financial documents or data, all such information of or about the Company shall be “Confidential Information”.

You shall use the Confidential Information of the Company solely to perform your obligations under this Agreement, and all Confidential Information shall remain the sole property of the Company. You acknowledge that the disclosure or unauthorized use of any such Confidential Information may cause irreparable damage to the Company. You shall at all times maintain in the strictest confidence and shall not make any use of (except for the purposes of this Agreement) such Confidential Information, and shall take every reasonable precaution to protect the confidentiality of the Confidential Information, treating such information with at least the same degree of care it would give to protecting your own confidential business information and in any event no less than a reasonable degree of care.

You may disclose Confidential Information only to your employees, officers, directors, or third party contractors who have a need to know such Confidential Information  solely to perform your obligations under this Agreement and who are subject to legally enforceable obligations in respect of the Confidential Information that are no less restrictive or extensive than those imposed on you by this Agreement.

Confidential Information shall not include information disclosed which: (i) the Receiving Party can demonstrate by independent documented evidence, was already known to it at the time of its receipt hereunder; (ii) is or becomes generally available to the public other than by means of the Receiving Party’s breach of its obligations under this Agreement; (iii) is independently obtained from a third party whose disclosure violates no duty of confidentiality, as can be demonstrated by independent documented evidence; or (iv) is disclosed pursuant to applicable law or regulation or by operation of law, provided that the Receiving Party may disclose only such information as is legally required, and provided further that the Receiving Party shall provide reasonable notice to the Company of such requirement and a reasonable opportunity to object to such disclosure.

This Section 10 shall survive termination of this Agreement for any reason.

11. Indemnification

To the maximum extent permitted by applicable law, you agree to defend, indemnify and hold harmless The Company and anyone acting on its behalf, including without limitation its subsidiaries, agents, managers, partners, and other affiliated companies, and, without limitation, their employees, contractors, agents, officers and directors, from and against any and all claims, damages, obligations, losses, liabilities, costs or debt, and expenses (including but not limited to, attorney’s fees) arising from or in any way related to: (i) your Usage of (and misuse) and access to the use of the Emotions Analytics  API, including any data or content transmitted, sent or received by you (also in the event that such data or content were, at any time during the Usage, lost, deleted or corrupted in any manner preventing you from using such data or content); (ii) your violation of these Terms; (iii) your violation of any third-party right, including without limitation any right of privacy, publicity rights or intellectual property rights; (iv) your violation of any law, rule or regulation of United States or any other country; (v) any other party’s access and use of the API in connection with your Usage; or (vi) any claim or damages that arise as a result of your submission to The Company of any Content (as defined below).

 

12. Termination

  1. These Terms and conditions will continue to apply and govern your use of the API until terminated by either party as set forth herein.
  2. You may terminate your legal agreement with The Company by providing written notice to The Company at info@beyondverbal.com and by removing the API code from your Application.
  3. The Company will terminate this agreement and suspend any use of its Emotions Analytics API in the event that it has discovers or suspects breach of any of the Terms and Conditions as set out in this Agreement.
  4. In the event that you apply the API for unlawful or unethical uses, the Company may suspend your usage of the API or terminate these Terms and Conditions with immediate effect. Unethical or unlawful uses will be determined in the sole and absolute discretion of the Company. The Company will shall not be held liable for any damages caused to you and/or to any third party as a result of such termination and any such liability shall be borne solely by you.
  5. The Company may, at any time and without any reason, in its sole and absolute discretion, terminate its agreement with you or cease to provide any or all of the API and related services (if any) with 60 days prior notice. The Company may, in any event that it regards as a breach of these Terms and Conditions in its sole and absolute discretion, terminate your Developer Account, in addition to all other remedies available to it pursuant to these Terms and Conditions and any applicable law.

 

13. Content

By inputting or submitting content to the API, or sending us information in connection with the Usage (“Content“), you automatically represent and warrant to The Company that the owner of such Content has expressly granted The Company a royalty-free, perpetual, irrevocable, worldwide nonexclusive license to use, reproduce, create derivative works from, collect, store, modify, transmit, use for research purposes, perform and display the Content for The Company’s routine operations. The Company may combine any Content you provide with information from other users to create aggregated data (“Aggregated Data“) The Company represents that Aggregated Data will not contain any personally identifiable information. Aggregated Data shall be the property of The Company. The Company retains the right to disclose Aggregated Data to third parties. The Company will not contact your users who exclusively disclosed their contact details to The Company via your use of the API. The Company will, as soon as reasonably practical, delete the personally identifiable information of any of your users unless that information is separately procured by The Company.

You hereby acknowledge that we use third party vendors and hosting partners to provide the necessary hardware, software, networking, storage, and related technology required to use the API. The technical processing and transmission of any Content in connection with the Usage, may be transferred unencrypted and involve (a) transmissions over various networks and in various media; and (b) changes and adaptations to Content to conform and adapt to technical requirements of connecting networks, devices, services or media.

If you have contributed your Content to The Company, you recognize that violation of these Terms and Conditions may result in loss of access to your Content. The Company does not pre-screen Content. However, The Company and its designees have the right (but not the obligation) in their sole discretion to block or restrict access to or the availability of, or to disable, any Content that is available via the Usage. Without limiting the foregoing, The Company and its designees may disable, restrict access to or the availability of, any Content that violates these Terms and Conditions, any applicable law or is otherwise objectionable. You shall evaluate, and bear all risks associated with, the use and sharing of any Content, including any reliance on the accuracy, integrity, quality or usefulness of such Content.

 

14. General Terms

  1. You agree that The Company may provide you with notices, including those regarding changes to the Terms and Conditions, by email, regular mail, or postings on the webpage on The Company’s website related to the API.
  2. You agree that if The Company may use all content which it has obtained through your use of the API for research and development purposes and by agreeing to these Terms and Conditions you are giving your full consent.
  3. Any application which uses the API needs our prior written approval, before being used by third parties and or becomes available for public use (production).
  4. You agree that The Company has a strict non-exclusivity policy concerning usage of the API, and will not grant exclusivity, to any extend, to any Licensee. In addition to the aforementioned,  The Company reserves, at its soles discretion and right, to grant a Licensee exclusivity, which will allow The Company to suspense any other licensed key, which is in breach of such an exclusive right.”
  5. You agree that if The Company does not exercise or enforce any legal right or remedy available to it under the Terms and Conditions (or any applicable law), The Company will not be deemed to have waived its rights or remedies, and those rights and remedies will still be available to The Company. Any waiver of any provision of these Terms and Conditions will be effective only if The Company expressly states in a signed writing that it is waiving a specified term of these Terms and Conditions.
  6. If it is determined by a competent court of law that any provision of these Terms and Conditions is invalid, then that provision will be removed from the Terms and Conditions without affecting the rest of the Terms and Conditions. The remaining provisions of the Terms and Conditions will continue to be valid and enforceable.
  7. The Terms and Conditions or any part thereof may be assigned by The Company to any other party as it deems necessary and will inure to the benefit of The Company, its successors, and assigns.
  8. The Terms and Conditions, and your relationship with The Company under the Terms and Conditions, are governed by the laws of England and Wales, without regard to its conflict of law’s provisions. You and The Company agree to submit to the exclusive, personal jurisdiction of the federal or state courts of the laws of England and Wales, to resolve any legal matter arising from or related to the Terms and Conditions. Notwithstanding the above, you acknowledge and agree that The Company is entitled to apply for injunctive remedies (or an equivalent type of urgent legal relief) and/or monetary remedies in any jurisdiction.
  9. These Terms constitute the whole legal agreement between you and The Company in connection with, and govern your use of the API. These Terms and Conditions completely replace and supersede any prior agreements between you and The Company, written or oral, in connection with the API.
  10. We have no special relationship with or fiduciary duty to you. This Agreement does not create any partnership or joint venture between you and The Company.
  11. If you have any queries or feedback regarding the service, please provide feedback via info@beyondverbal.com. You’re only other remedy with respect to any dissatisfaction with (i) the Usage, (ii) the Terms, (iii) any policy or practice of The Company in operating the API, or (iv) any content or information transmitted through the Usage, is to terminate this agreement and your use of the API.
  12. These Terms apply to all current features and to new features that are or may be added to the existing the API. It is your responsibility to check the Terms and Conditions periodically for changes on our website. Continued use of the API after any such changes shall constitute your consent to such changes.

To sign Terms & Conditions – download here

About Beyond Verbal

Beyond Verbal Communication, Ltd. (Beyond Verbal) commercializes patented technology that extracts a person’s full set of emotions and character traits in real time, based on raw voice recordings as the person speaks. Core research, based on the understanding that it’s not what we say, but HOW we say it, has been ongoing by a team of physics, operations research, decision-making and neuropsychology scientists for more than 20 years. Covering over a million emotionally tagged voices in more than 40 different languages, this research has led to discoveries which form the basis of a new field – what we call Emotions Analytics – which introduces a whole new dimension of emotional understanding and has the potential to transform the way we understand wellness, as well as the way we interact with machines and with each other.

Output Definition

Guide to Moods and Attitudes

Understanding Beyond Verbal’s engine emotional definitions

Chapter 1 – Introduction

The Emotions Analytics engine of Beyond Verbal takes raw voice input and analyses it for mood and attitude. What exactly is provided depends on your license key.

  • The Emotions Analytics engine measures the speaker’s current mood. It requires at least 13 seconds of continuous voice to render an emotional analysis. For more information please refer to our recording guidelines.
  • The outputs are distributed into moods and attitude outputs, as listed below within this document.

Chapter 2 – Attitude Outputs

The Emotions Analytics engine measures the speaker’s emotional state during the analyzed voice section intro three separate attitude outputs: Temper, Valence, and Arousal. They are all measured on a scale of 0 to 100.

2.1         Temper

Temper reflects a speaker’s temperament or emotional state ranging from gloomy or depressive at the low-end, embracive and friendly in the mid-range, and confrontational or aggressive at the high-end of the scale.

The temper output is divided into two distinct measurements:

  • Continuous Scale ranging from 0 to 100, representing a temperament shift from depressive at the low end to aggressive at the high end.
  • Temper groups which consist of three distinct groups: Low, Med, High

2.1.1      High Temper

High temper occur when the speaker experiences and expresses aggressive emotions, such as active resistance, anger, hatred, hostility, aggressiveness, forceful commandment and/or arrogance.

Aggressive emotions may have different levels of intensity, and may even be combined, to an extent, with embracive feelings (but not depressive feelings). The Temper scale present this ambiguity as a score that increases the more intensive and “pure” the aggressive emotions are.

2.1.2      Medium Temper

Medium temper occur when the speaker experience and expresses the following three types of emotions:

  • Embracive “positive” emotions, communicated in a warm and friendly manner, such as positivity, empathy, acceptance, friendliness, closeness, kindness, affection, love, calmness, and motivation.
  • Self-controlled “neutral” emotions communicated in a “matter-of-fact” intonation.
  • No significant emotions are evident in the speaker’s voice.

As medium emotions populate the middle of the spectrum, they may contain elements of depressive or aggressive emotions (but not both). The Temper score represent this ambiguity as the score varies for the mid-range towards one of the ends.

2.1.3      Low Temper

Low temper occur when the speaker experiences and expresses depressive emotions in an inhibited fashion, such as sadness, pain, suffering, insult, inferiority, self-blame, self-criticism, regret, fear, anxiety and concern (can also be interpreted as fatigued). It is as though the speaker is waning, growing smaller or pulling back.

Depressive emotions can be expressed in different levels of intensity and may even be combined, to an extent, with embracive feelings (but not aggressive).

2.2         Valence

*BETA

Valence is an output which measures speaker’s level of negativity / positivity.

The Valence output is divided into two distinct measurements:

  • Continuous Scale ranging from 0 to 100, representing a valence shift from negative attitude at the lower part of the scale to a positive attitude at the higher part of the same scale.

Valence groups which consist of three distinct groups: Negative, Neutral and Positive.

definition_02

There are three possible and distinct Valence groups:

  • Negative Valence. The speaker’s voice conveys emotional pain and weakness or aggressive and antagonistic emotions.
  • Neutral Valence. The speaker’s voice conveys no preference and comes across as self-control or neutral.
  • Positive Valence. The speaker’s voice conveys affection, love, acceptance and openness.

 

2.3         Arousal

Arousal is an output that measures a speaker’s degree of energy ranging from tranquil, bored or sleepy to excited and highly energetic. Arousal can also correspond to similar concepts such as involvement and stimulation.

definition_03

The Arousal output is divided into two distinct measurements:

  • Continuous Scale ranging from 0 to 100, representing a shift from tranquil at the lower part of the scale to excited at the higher part of the same scale.
  • Arousal groups which consist of three distinct groups: Low, Mid and High.

There are three possible and distinct Arousal groups:

  • Low Arousal, conveys low levels of alertness and can be registered in cases of sadness, comfort, relief or sleepiness.
  • Mid Arousal, conveys a medium level of alertness and can be registered in cases of normal conduct, indifference or self-control.
  • High Arousal, conveys a high level of alertness such as excitement, surprise, passionate communication, extreme happiness or anger.

 

Chapter 3 – Mood Groups

Mood groups are an indicator of a speaker’s emotional state during the analyzed voice section.

There are 432 combined emotions which are grouped into eleven main mood groups. Mood groups are distinct outputs and not measured in a scale.

 

3.1         Aggressive / Confrontational Mood Groups

  • Supremacy and Arrogance. This group is typified by feelings of power, superiority, ascendancy, self-importance or self-entitlement. The feelings can range from a feeling of superiority to a tendency to assert control when dealing with others.
  • Hostility and Anger. This group has negative emotions of antagonism, enmity or unfriendliness that can be directed against individuals, entities, objects or ideas. The feelings can range from aversion and offensiveness to open aggressiveness and incitement.
  • Criticism and Cynicism. This group is typified by a feeling of general distrust or skepticism. The feelings can also be described as scornful and jaded negativity.

3.2         Self-Control Mood Group

  • Self-control and practicality. This group is typified by feelings of controlled emotions, behaviors and desires. The feelings can range from self-restraint to irrelevance.

3.3         Embracive Mood Groups

  • Leadershipand Charisma. This group is typified by feelings of power, vision and motivation. The feelings can range from protectiveness, communication of ideas or ideology with an underline of motivation.
  • Creativeness and Passion. This group is typified by a feeling of eagerness and/or desire. The feelings can range from desire, want and craving with an underline of action to achieve goals. These emotions are highly correlated with vivid imagination, hopes and dreams.
  • Friendliness and Warm. This group is typified by positive feelings and pleasant accommodation. The feelings include approval, empathy and hospitability. The group can also include feelings of being approved or wanted by others (“being part of a team”) as well as being receptive to another person, idea or item.
  • Love and Happiness. This group is typified by long term happiness, affiliation and pleasurable sensation. The group also includes feelings of strong affection for another person, idea or item as well as arising out of kinship or personal ties.

3.4         Depressive / Gloomy Mood Groups

  • Loneliness and Unfulfillment. This group is typified by feelings of inadequacy, lack of worth, disappointment or failure.
  • Sadness and Sorrow. This group is typified by emotional pain such as unhappiness, self-pity and powerlessness.
  • Defensiveness and Anxiety. This group is typified by negative emotions of fear, worry and uneasiness. The group also includes low self-esteem and can also often be accompanied by inner turmoil and restlessness.

API Quick Integration Guide

Getting started with Beyond Verbal’s REST API

PURPOSE

This Quick Reference Guide is made to help you get up and running using Beyond Verbal’s Emotions Analytics REST API (API).

Using the API you will:

  1. Send the voice samples to Beyond Verbal cloud-based Emotions Analytics engine
    for analysis.
  2. Receive the analysis back from the API.

To obtain better understanding of the data received back from the API, please take a moment to browse our Analysis Result Interpretation guide.
To better understand how to create and record good-quality, emotionally effective voice inputs please refer to our Voice Input Guidelines for Analysis by Beyond Verbal REST API guide.

THE ESSENTIALS PROCESSES OF WORKING WITH OUR API

Each of the below callouts represents a separate step in the process of working with our API. These steps are described in further details – each in a separately dedicated chapter. Feel free to browse the guide in full or jump directly to the chapters that interest you the most.

img01

AUTHENTICATION

Use this request to acquire an authentication token from the API Key. This token needs to be sent with each subsequent request to the analysis server.

The Authentication Token must be sent as an Authorization field in the HTTP request header.

Authentication Request Parameters

Name Location (Body URL Header) Optional Default value Explanation
grant_type Body No client_credentials Client requests an access token.
apiKey Body No Your API key The API key you received from Beyond Verbal.
Content-Type Header No x-www-form-urlencoded Default Internet media type.

 

Example: Get token request

POST https://token.beyondverbal.com/token
Content-Type:application/x-www-form-urlencoded

grant_type=client_credentials&apikey=**********

Example: Response token

{
“access_token”:”21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8″,
“token_type”:”bearer”,
“expires_in”:172799
}

You must use the received authentication token in all subsequent requests.

Example: Using the token

POST https://apiv3.beyondverbal.com/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

This token may be reused for multiple sessions.

START

Use this request to initialize an analysis session.

Define the type of audio file you will send (wav or pcm). If the format is pcm, also provide the channels, sample rate, and bits per sample (in a wav file these parameters are read from the header).

Optionally, you can send metadata about the client, such as clientId or deviceId. See “Metadata Guide” for more details.

Example: Simple request header

{ dataFormat: { type:”WAV” } , metadata:{ ClientID:”12345” } }

Start Request

Method: POST

URL: https://apiv3.beyondverbal.com/v3/recording/start

Start Request Parameters

 

Name Location
(Body URL Header)
Optional Default value Explanation Example
dataFormat Body Yes

dataFormat: {type: “WAV”}

Information about the data stream that will
be sent to the server (using recording / call).

For file with WAV header
dataFormat:{ type:”WAV” }

For Raw PCM file
dataFormat : {
“type”: “pcm”,
“channels”: 1,
“sample_rate”: 8000,
“bits_per_sample”: 16 }

metadata Body Yes metadata: {}

Metadata information describing
user/ client/ device/ session.
For more details see “Metadata” on page 9.

metadata:

{ clientId: “someUser123@gmail.com”,
deviceId: “121332423423”, phone: “1718-555-555”
}

displayLang Body Yes displayLang: “en-us” Language used for the result.
If the requested language is not supported,
an error is returned.
Note that “en-us” is always supported.
 
Auth token Authorization Header No     Bearer XXX_TOKEN_XXX

Example: Start request (including token)

POST https://apiv3.beyondverbal.com/v3/recording/start

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

{
“dataFormat”: {“type”: “WAV”},
“metadata”: {“clientId”: “12345”}
}

Start Response

Example: OK Response (200)

{status: “success”, recordingId: “someGUID”}

The recordingId field is used to access a particular session that was created.

Example: Error Response (4xx)

{status: “failure”, reason: “This is optional text explaining the error”}

UPSTREAM

Use this request to send a voice input to the server for analysis. The response contains the analysis for the whole file.

Note: The response to this request is returned only when the whole body has been received and analyzed by the server. This may take a long time; thus to receive intermediate analysis results use the ANALYSIS request.

Upstream Request

Method: POST

URL: https://apiv3.beyondverbal.com/v3/recording/{recordingId}

Upstream Request Parameters

Name Location (Body URL Header) Optional Explanation
recordingId URL No Unique identifier of recording. Provided in the recordingId field of the START response.
Auth token Authorization Header No See “Authentication”
Sample Data Body No

Post your audio samples as the body of this HTTP message.

 Note: Http “Content-Length” header

If the length of your sample is unknown in advance (real-time streaming), use a Chunked Transfer Encoding. See (http://en.wikipedia.org/wiki/Chunked_transfer_encoding for details.

Example: Upstream request

POST https://apiv3.beyondverbal.com/v3/recording/{recordingId}

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Upstream Response

The response is a JSON object containing an array of the analysis results for whole analysis session.

Example: OK Response (200)

{
status: “success”
recordingId: “someGUID”,
result: {
duration: 295096,
sessionStatus: “Done”,
analysisSegments: [
{
“offset”: 1586,
“duration”: 23201,
“analysis”: {…}
}
]
}
}

ANALYSIS

Use this request to fetch the analysis for a particular offset (segment) of the analysis session. You can issue this request in parallel with the UPSTREAM request in order to receive intermediate analysis.

Analysis Request

Method: GET

URL: https://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=n

Analysis Request Parameters

Name Location (Body URL Header) Optional Explanation
recordingId URL No Unique identifier of recording. Provided in the recordingId field of the START response.
fromMs URL Yes Filters out any analysis older than the given value.
Auth token Authorization Header No See “Authentication”

Example: Initial analysis request

This example requests an analysis from the beginning of the recording session (fromMS=0).

GET https://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=0

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Analysis Response

The response is a JSON object containing an array of all the analysis segments from the fromFS, offset from the beginning of the session, until the current moment in time. This moment is the duration. The value of duration indicates the beginning of the next analysis segment.

Example: Analysis OK response (200)

{
status: “success”
recordingId: “someGUID”,
result: {
duration: 295096,
sessionStatus: “Done”,
analysisSegments: […]
}
}

Subsequent Analysis Request

In the next analysis request, increase fromMS to the next offset, that is the duration received in the response, to receive only the most recent analysis.

Example: Subsequent analysis request

This example requests an analysis from where the previous recording session finished (fromMS=295096).

GEThttps://apiv3.beyondverbal.com/v3/recording/{recordingId}/analysis?fromMs=295096

Authorization: Bearer 21G2BA4iZJavSJQbsyuppWmfSMLgLn-**gDTCfguhzGa_k8

Continue with such requests until the session is completed (session status = done).
Note that you can request additional analysis requests for up to 24 hours after the session started. The analysis data is cached for 24 hours.

Emotions Analytics Version 4 Beta API

We are excited to announce the official release of Version 4 Beta Emotions Analytics API.

Among the improved features:

  • Reduced Analysis Time – After the first 10 second analysis is given, a new analysis is generated every 5 seconds.
    Click here to see our Voice Input Guidelines
  • Improved Accuracy for Temper, Valence and Arousal
  • New: Confidence Score – measures our confidence in the given analysis. Click here to read more about the confidence
    score
  • New: End field – In addition to the “offset” and “duration” we have added an end field for each segment time. Click
    here to read more about our Analysis Result Interpretation Guide

Must reads – just to get you started.

  • Voice Input Guidelines: Gives you all the information you need to record good audio which can be analyzed by our engines.
  • Quick Integration Guide: Contains all the technical guidance you need to start using our API.
  • Output Definition: Getting the data is one thing, it is another to understand it. Read our output definitions document to make sense of all our emotional outputs – it’s the sensible thing to do 😉

Additional (and useful) reads:

Sign up for your free API trial now.