0: ELEVENLABS - TEXT-TO-SPEECH STREAMING (FRONT-END DESKTOP & NATIVE MOBILE) ELEMENT ======================================================================================

ELEMENT DESCRIPTION
----------------------------------
 ELEVENLABS - TEXT-TO-SPEECH STREAMING (FRONT-END DESKTOP & NATIVE MOBILE) provides ultra-realistic voice-generated audio streaming, enabling real-time text-to-speech such as chatbots, agents, LLMs, websites, apps use cases.

 Your generated PUBLIC ACCESS KEY key is safe to expose, as it is locked to your BUBBLE APP URL's domain and exchanged for your ELEVENLABS API KEY provided during registration.


STEP-BY-STEP SETUP
--------------------------------
 0) Register on ELEVENLABS and get your ELEVENLABS API KEY on https://elevenlabs.io

 1) Register on plugins.wiseable.io. Create a new Credential which associates your BUBBLE APP URL and your ELEVENLABS API KEY.
  The registration service will generate your PUBLIC ACCESS KEY. This key serves as a secure proxy for your real API key. It allows your application to communicate with the service without exposing your real API key. Since this PUBLIC ACCESS KEY is explicitly tied to your registered BUBBLE APP URL, it can only be used from that domain, ensuring that even if the key is publicly visible, it remains safe and cannot be misused by unauthorized sources.

 2) In the Plugin Settings, enter your PUBLIC ACCESS KEY generated at the previous step.

 3) In order to select the voice to generate speech, create a dropdown element with the provided data type "GET VOICES LIST (ELEVENLABS)" and as "CHOICES SOURCES", use the dynamic source "GET DATA FROM AN EXTERNAL API" and select as API PROVIDER the API "ELEVENLABS - GET VOICES LIST". Filter those according to your use-case and select as "OPTION CAPTION" the name of the voice.

 4) Add an element supporting input text.

 5) Add the ELEVENLABS - TEXT-TO-SPEECH STREAMING (FRONT-END DESKTOP & NATIVE MOBILE) to the page on which Text-to-Speech must be performed and configure its properties.

 FIELDS :
 - DISPLAY AUDIO CONTROLS : Display or hide audio controls.
 - OUTPUT FORMAT : Output format of the generated audio. Must be one of the SUPPORTED FORMATS element state.
 - OPTIMIZE STREAMING LATENCY : You can turn on latency optimizations at some cost of quality. The best possible final latency varies by model. Possible values: 0 - default mode (no latency optimizations) 1 - normal latency optimizations (about 50% of possible latency improvement of option 3) 2 - strong latency optimizations (about 75% of possible latency improvement of option 3) 3 - max latency optimizations 4 - max latency optimizations, but also with text normalizer turned off for even more latency savings (best latency, but can mispronounce eg numbers and dates).

 6) Integrate the logic into your application using the following ELEVENLABS - TEXT-TO-SPEECH STREAMING (FRONT-END DESKTOP & NATIVE MOBILE) states and actions:

 EVENTS :
 - ERROR : Event triggered when an error occurs.
 - END OF STREAM : Event triggered when Stream has finished to download.
 - AUDIO FILE UPLOADED (FRONT-END DESKTOP ONLY) : Event triggers when the Audio File has been successfully uploaded, triggered using SAVE AUDIO action.

 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 TEXT-TO-SPEECH STREAMING :
 - SUPPORTED FORMATS : List of audio formats supported by the browser.
 - ERROR : Error message upon Error event trigger.
 - PLAYER STATUS : Return the player status. Valid values are ready | playing | paused | stopped | ended
 - CURRENT PLAYER SEEK TIME : Return the current player seek time in seconds.
 - TOTAL DURATION : Return the total duration of the audio in seconds.
 - AUDIO FILE URL (FRONT-END DESKTOP ONLY) : Return the Audio File URL upon AUDIO FILE UPLOADED event.


 ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
   - PAUSE AUDIO : Pause the audio stream.
   - RESUME AUDIO : Resume the audio stream.
   - SEEK AUDIO : Seek to a specific time in the audio stream.
  Inputs Fields :
       - SEEK TIME : Seek to a specific time in the audio stream.
   - GENERATE SPEECH : Generate speech from input.
  Inputs Fields :
       - VOICE : The unique ID for a ELEVENLABS or Cloned Voice.
       - INPUT : From Play.HT: To ensure fair usage, this streaming endpoint is subject to more strict rate-limits and also limits the text size it may take as input. Input text provided to the streaming endpoint may contain at most 20 sentences. A sentence is defined as a sequence of at least 35 characters separated by a punctuation character (., ? or !). Maximum text length is 2000 characters.
       - MODEL : Identifier of the model that will be used, you can query them using GET /v1/models. The model needs to have support for text to speech, you can check this using the can_do_text_to_speech property.
       - TITLE : Title of the media.
       - ARTIST : Artist of the media.
       - ALBUM : Album of the media.
       - COVERT ART : Covert Art image of the media.
   - SAVE AUDIO FILE (FRONT-END DESKTOP ONLY) : Save the latest audio output.
the can_do_text_to_speech property.
       - FILE NAME : File Name, without extension, of the audio file to save.
       - PRIVATE : Set to yes to set this file to private. ATTACHED TO must be provided to specify the thing to attach this audio file to.
       - ATTACHED TO : Unique ID of the thing to attach the Audio File to.


1 : GET VOICES LIST
=======================================

DATA API DESCRIPTION
--------------------------------
GET VOICES LIST gets the full list of stock ELEVENLABS Voices.

STEP-BY-STEP SETUP
--------------------------------
 1) In order to select the voice to generate speech, create a dropdown element with the provided data type "GET VOICES LIST (ELEVENLABS)" and as "CHOICES SOURCES"
 2) Use the dynamic source "GET DATA FROM AN EXTERNAL API" and select as API PROVIDER the API "ELEVENLABS - GET ELEVENLABS VOICES LIST". Filter those according to your use-case and select as "OPTION CAPTION" the name of the voice.

   Output Fields: List of Voices, containing for each their description attributes.

2 : GET MODELS LIST
=======================================

DATA API DESCRIPTION
--------------------------------
GET MODELS LIST gets the full list of stock ELEVENLABS Models.

STEP-BY-STEP SETUP
--------------------------------
 1) In order to select the model to generate speech, create a dropdown element with the provided data type "GET MODELS LIST (ELEVENLABS)" and as "CHOICES SOURCES"
 2) Use the dynamic source "GET DATA FROM AN EXTERNAL API" and select as API PROVIDER the API "ELEVENLABS - GET MODELS LIST". Filter those according to your use-case and select as "OPTION CAPTION" the name of the voice.

   Output Fields: List of Models, containing for each their description attributes.

2 : CREATE VOICE CLONE
=======================================

ACTION DESCRIPTION
--------------------------------
CREATE VOICE CLONE creates an instant voice clone by providing an URL for a sample audio file.
The cloned voice will be based on the characteristics of the provided audio file.

STEP-BY-STEP SETUP
--------------------------------
 1)  Set up the "CREATE VOICE CLONE" action in the workflow.

   Inputs Fields :
     - URL : Protocol-relative URL (//server/path/file.ext) from Bubble Uploader or Bubble Storage of the audio file selected as the source for the voice clone.
     - VOICE NAME : The name for this new cloned voice.

   Output Fields:
     - ID : ID of the new cloned voice.

3 : DELETE CLONED VOICE
=======================================

ACTION DESCRIPTION
--------------------------------
DELETE CLONED VOICE deletes a cloned voice created by the user using the provided the VOICE ID

STEP-BY-STEP SETUP
--------------------------------
 1)  Set up the "DELETE CLONED VOICE" action in the workflow.

   Inputs Fields :
     - VOICE ID : The ID of the cloned voice to be deleted. This ID is retrieved via GET VOICES LIST action.

   Output Fields:
     - STATUS : Operation results.


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

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
===========================
 N/A

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