0: SPEECH RECORDER ELEMENT ==========================

ELEMENT DESCRIPTION
--------------------------------
 SPEECH RECORDER is a visual element allowing you to record voice in WAV, OGG, WAV, WEBM or PCM format on all desktop devices and browsers (with exception of iOS, where due to browser policy restrictions it works only in Safari browser). After recording, the element stored the file in the app's storage and returns the file URL.

STEP-BY-STEP SETUP
--------------------------------
 1) Drap and drop up the visual element SPEECH RECORDER in your app.

 2) Select the SPEECH RECORDER element, in APPEARANCE section, configure the following fields :
 
 FIELDS :
 - ENABLE AUTO-BINDING PARENT ELEMENT'S THING : If selected, SPEECH RECORDER will update the parent elements thing, evaluating to a FILE, once the recording will be ready.
 - MAX FILE SIZE : Limits the file size of the recording (Megabytes).
 - FILE UPLOAD ENABLED : Must be set to yes.
 - CHANNELS : Select the number of channels to record.
 - FORMAT : Output format of the recording. Valid values are WAV | OGG | PCM | WEBM | MP3.
 - BACKGROUND WHEN OFF : Recorder background color when recording is off.
 - BACKGROUND WHEN ON : Recorder background color when recording is on.
 - RECORDER WHEN OFF : Recorder color when recording is off.
 - RECORDER WHEN ON : Recorder color when recording is on.

 3) Integrate the logic into your application using the following SPEECH RECORDER, states and actions:

 EVENTS :
 - RECORD CAPTURED : Triggered when the record has been captured.
 - RECORD ENCOUNTERED ERROR : Triggered when the record has encountered an error. The "ERROR MESSAGE" is then exposed as element STATE.
 
 EXPOSED STATES:
 Use any element able to show/process the data of interest (such as a Group with a Text field) stored within the result of the following states of the SPEECH RECORDER element :
 - DURATION : Duration of the recording.
 - RECORDING : Returns yes while recording.
 - FILE SIZE : Size of the recording in bytes.
 - SAVING : Returns yes while recording is being saved to the app's storage.
 - PAUSED : Returns yes while paused.
 - RECORDING FILE : URL of the recording file, saved to the app's storage.
 - ERROR MESSAGE : Contains the error message upon "RECORDER ENCOUNTERS AN ERROR" event.

 ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
   - START - STOP
   - PAUSE - RESUME
   - CANCEL RECORDING

 4)  Then, implement either one the of the following actions to trigger the speech transcription.

1 : START & GET SPEECH TOXICITY (ASYNC)
==========================================

ACTION DESCRIPTION
--------------------------------
 START SPEECH TOXICITY JOB starts a speech toxicity assessment job from a FLAC, MP3, MP4, Ogg, WebM, AMR, or WAV file stored in AWS S3.

STEP-BY-STEP SETUP
--------------------------------
The steps from 0) to 1) can be automatically performed by using this deployment template:
 https://console.aws.amazon.com/cloudformation/home?#/stacks/create/review?stackName=BubbleTranscribe&templateURL=https://bubble-resources.s3.amazonaws.com/deployment-assets/CloudFormation-AWSTranscribeAsync.yaml

 0) Sign-up for AWS TRANSCRIBE : https://console.aws.amazon.com/transcribe/home?p=rkn&cp=bn&ad=c

 1) Create your AWS TRANSCRIBE API KEY & SECRET and attach the AWS TRANSCRIBE FULL ACCESS and S3 READ ONLY policies: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

   Write down your:
     - KEY & KEY SECRET
     - AWS SERVICE ENDPOINT REGION

 2) In the Plugin Settings, enter the following :
     - AWS TRANSCRIBE API KEY & SECRET
     - AWS SERVICE ENDPOINT REGION (if not provided, default endpoint is "us-east-1").

 3) Set-up in your workflow an action returning the BUCKET and KEY of your file to analyze.
   a) If you do not already have such action, install the plugin "AWS S3 & SQS UTILITIES"
   b) Create a AWS S3 BUCKET that will be used to store the file to analyze: https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html
   c) Set up the "PUT FILE TO S3" action in the workflow.
     Inputs Fields:
       - FILE URL TO STORE : The file URL from the Bubble.io uploader, or a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext). The file must be accessible through the HTTPS protocol.
      - AWS S3 BUCKET NAME : Bucket Name to which the file will be saved.
      - AWS S3 FILE NAME : Path & File Name to save to. The format must be [path/]filename.ext.
           Example 1: path1/path2/filename.ext.
           Example 2: filename.ext if the file is at the root of the bucket.

 4) Set up the "START SPEECH TOXICITY JOB" action in the workflow.
   Inputs Fields:
   - AWS S3 BUCKET NAME : AWS S3 bucket name from which the input file will be read.
   - AWS S3 FILE NAME : AWS S3 file name for the input file. Enter here the file from the Bubble.io file, or a Protocol-relative URLs (//server/filename.ext), or a HTTPS URL (https://server/filename.ext). The supported file formats are FLAC, MP3, MP4, Ogg, WebM, AMR, or WAV.
       Example 1 : path1/path2/filename.ext.
       Example 2 : filename.ext if the file is at the root of the bucket.
   Output Fields:
     - JOBID : ID of the Job, to be reused in the "GET SPEECH TOXICITY RESULTS".

 5) Set up the action “GET SPEECH TOXICITY RESULTS" action in a RECURRING (Do every x seconds) workflow to continuously poll AWS TRANSCRIBE job status.
   Inputs Fields :
     - OUTPUT FIELD: Must always be set to "TOXICITY RESULTS (TRANSCRIBE)"
     - JOBID : ID of the job to poll, returned by "SSTART SPEECH TOXICITY JOB" action.
   Output Fields :
     - TRANSCRIPTION JOB STATUS : Possible values are QUEUED, IN_PROGRESS, FAILED, COMPLETED.
     - RESULTS:  Returns a list of toxicity results upon COMPLETED TRANSCRIPTION JOB STATUS. Each transcript is associated with a start time, end time along with toxicity score for each category.

IMPLEMENTATION EXAMPLE
======================
 Feel free to browse the app editor in the Service URL for an implementation example.

ADDITIONAL INFORMATION
======================

> Supported languages: https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html#table-language-matrix
> AWS TRANSCRIBE service limits : https://docs.aws.amazon.com/transcribe/latest/dg/limits-guidelines.html#limits
> AWS services availability per region : https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/
> AWS Service endpoints list : https://docs.aws.amazon.com/general/latest/gr/rande.html

TROUBLESHOOTING
================
 Any plugin related error will be posted to the the Logs tab, "Server logs" section of your App Editor.
 Make sure that "Plugin server side output" and "Plugin server side output" is selected in "Show Advanced".

 > Server Logs Details: https://manual.bubble.io/core-resources/bubbles-interface/logs-tab#server-logs

PERFORMANCE CONSIDERATIONS
===========================

GENERAL
-------------
 The largest usable file size depends on the capacity units your app can use on Bubble.io (see Capacity Boost or Professional Plan, the highest limit being capped by Bubble.io's Workflow Action maximum execution time to perform the response parsing operation.


QUESTIONS ?
===========
 Contact us at [email protected] for any additional feature you would require or support question