<commit_before>.. module:: info.mindtrove
   :synopsis: Namespace for the JSonic client.

The JavaScript API
==================

The client implements a JavaScript interface allowing web applications to speak text, play sounds, change playback properties, queue commands, manage independent audio channels, and cache results for low-latency playback.

The JSonic interface
--------------------

.. class:: JSonic

   .. method:: constructor(args)
   
      :param args: 
      :type args: object
   
   .. method:: addObserver(func, channel, actions)
   
      :param func: 
      :type func: function
      :param channel: 
      :type channel: string
      :param actions: 
      :type actions: array
      :return:
      :rtype: object
   
   .. method:: getEngines()
   
      :rtype:
   
   .. method:: getEngineInfo(id)
   
      :param id: 
      :type id: string
      :rtype:

   .. method:: getProperty(args)
   
      :param args: 
      :type args: object
      :rtype:
      
   .. method:: play(args)

      :param args: 
      :type args: object
      :rtype:
   
   .. method:: removeObserver(token)

      :param token: 
      :type token: object
      :rtype:

   .. method:: reset(args)

      :param args: 
      :type args: object
      :rtype:
   
   .. method:: say(args)
   
      :param args: 
      :type args: object
      :rtype:

   .. method:: setProperty(args)

      :param args: 
      :type args: object
      :rtype:
   
   .. method:: stop(args)

      :param args: 
      :type args: object
      :rtype:

.. class:: JSonicDeferred
   
   .. method:: addAfter(func)
   
   .. method:: addBefore(func)
   
   .. method:: anyAfter(func)
   
   .. method:: anyBefore(func)
   
   .. method:: errAfter(func)
   
   .. method:: errBefore(func)

Example code
------------

The following examples assume an :class:`info.mindtrove.JSonic` instance with caching disabled by default exists in local variable `js`.

Speaking text
~~~~~~~~~~~~~

To say an utterance on the :const:`default` channel and not cache the result, do the following:

.. sourcecode:: javascript

   js.say({text : "This is some text to speak."});

To say an utterance on the same channel and cache the result for lower latency, do the following:

.. sourcecode:: javascript

   js.say({text : "This is some text to speak.", cache : true});

To queue two sequential utterances on the :const:`default` channel, do the following:

.. sourcecode:: javascript<commit_msg>Continued doc of js api<commit_after>.. module:: info.mindtrove
   :synopsis: Namespace for the JSonic client.

The JavaScript API
==================

The client implements a JavaScript interface allowing web applications to speak text, play sounds, change playback properties, queue commands, manage independent audio channels, and cache results for low-latency playback.

The JSonic interface
--------------------

.. class:: JSonic

   .. method:: constructor(args)
   
      :param args: 
      :type args: object
   
   .. method:: addObserver(func, channel, actions)
   
      :param func: Callback function
      :type func: function(notice)
      :param channel: Name of the channel to observe. Defaults to :const:`default` if not defined.
      :type channel: string
      :param actions: List of string :ref:`action <action>` names to observe. Defaults to all actions if not defined.
      :type actions: array
      :return: Token to use to unregister the callback later using :meth:`removeObserver`
      :rtype: object
   
   .. method:: getEngines()
   
      :rtype: :class:`dojo.Deferred`
   
   .. method:: getEngineInfo(id)
   
      :param id: 
      :type id: string
      :rtype: :class:`dojo.Deferred`

   .. method:: getProperty(args)
   
      :param args: Object with the following properties:
         
         name (required)
            String name of the :ref:`property <property>` to get 

         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.
         
      :type args: object
      :rtype: :class:`dojo.Deferred`
      
   .. method:: play(args)

      :param args: Object with the following properties:

         url (required)
            String URL of the sound to play. Either :const:`.ogg` or :const:`.mp3` will be appeneded to the end of the URL depending on which format the browser supports.
         
         cache (optional)
            Boolean true to cache the sound audio node in memory for faster playback in the future, false to avoid caching. Defaults to false if not specified.
      
         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.
      
      :type args: object
      :rtype: :class:`info.mindtrove.JSonicDeferred`
   
   .. method:: removeObserver(token)

      :param token: Token returned when registering the observer with :meth:`addObserver`
      :type token: object
      :rtype: :const:`undefined`

   .. method:: reset(args)

      :param args: Object with the following properties:
      
         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.
      
      :type args: object
      :rtype: :class:`info.mindtrove.JSonicDeferred`
   
   .. method:: say(args)
   
      :param args: Object with the following properties:
      
         text (required)
            String text to speak.
         
         cache (optional)
            Boolean true to cache the sound audio node in memory and the utterance file URL in localStorage for faster playback in the future, false to avoid caching. Defaults to false if not specified.

         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.
      
      :type args: object
      :rtype: :class:`info.mindtrove.JSonicDeferred`

   .. method:: setProperty(args)

      :param args: Object with the following properties:
         
         name (required)
            String name of the :ref:`property <property>` to set
            
         value (required)
            Value to set for the :ref:`property <property>` where the type is dependent on the property name
            
         immediate (optional)
            Boolean true to execute the change immediately instead of queuing the command, false to queue the property change like all other commands. Defaults to false if not specified.

         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.
         
      :type args: object
      :rtype: :class:`dojo.Deferred`
   
   .. method:: stop(args)

      :param args: Object with the following properties:

         channel (optional)
            String name of the channel. Defaults to :const:`default` if not specified.

      :type args: object
      :rtype: :class:`info.mindtrove.JSonicDeferred`

.. class:: JSonicDeferred
   
   .. method:: addAfter(func)
   
   .. method:: addBefore(func)
   
   .. method:: anyAfter(func)
   
   .. method:: anyBefore(func)
   
   .. method:: errAfter(func)
   
   .. method:: errBefore(func)

.. _action:

Callback actions
----------------

.. describe:: action : started-speech

   :param channel:
   :param url:
   :param name:

.. describe:: action : finished-speech

   :param channel:
   :param url:
   :param name:
   :param completed:

.. describe:: action : started-say

   :param channel:
   :param url:
   :param name:

.. describe:: action : finished-say

   :param channel:
   :param url:
   :param name:
   :param completed:

.. describe:: action : error

   :param channel:
   :param name:
   :param description:

.. _property:

Supported properties
--------------------

pitch
   todo

rate
   todo
   
voice
   todo

volume
   todo

Example code
------------

The following examples assume an :class:`info.mindtrove.JSonic` instance with caching disabled by default exists in local variable `js`.

Speaking text
~~~~~~~~~~~~~

To say an utterance on the :const:`default` channel and not cache the result, do the following:

.. sourcecode:: javascript

   js.say({text : "This is some text to speak."});

To say an utterance on the same channel and cache the result for lower latency, do the following:

.. sourcecode:: javascript

   js.say({text : "This is some text to speak.", cache : true});

To queue two sequential utterances on the :const:`default` channel, do the following:

.. sourcecode:: javascript
{'fraction_non_alphanumeric': 0.10966520761859695, 'fraction_numerical': 0.0001183011948420679, 'mean_word_length': 2.376198083067093, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2294260', 'n_tokens_mistral': 2361, 'n_tokens_neox': 2269, 'n_words': 886}