========
TTS Tags
========

This page provides an overview on the available tags to add into texts sent to
Navels text-to-speech, e.g.

.. code-block:: python

    robot.say("<lang,de1>Hallo<lang,en1>Hello.<alt,1>Hello.")


----------------------------
Overview of tags for acapela
----------------------------

.. list-table::
   :widths: auto
   :header-rows: 1

   * - Example
     - Explanation

   * - ``<alt,1>``
     - Choose alternative pronunciation for the following word.  Number
       enumerates options.
   * - ``<lang,se1>``
     - Permanently change voice to different language. See
       :ref:`below<lang_details>`.
   * - ``<mrk,20>``
     - Add bookmark to trigger an event via callback. See
       :ref:`below<mrk_details>`.
   * - ``<pau,25>``
     - Pause speech for 25ms
   * - ``<prn,h @ l @ U>``
     - Give phonetic string
   * - ``<rpit,120>``
     - Permanently alter the voice pitch. The number is a percentage of the
       default pitch.
   * - ``<rspd,120>``
     - Permanently set speed in percent
   * - ``<spell,broccoli>``
     - Say letters of given word one by one
   * - ``<vol,120>``
     - Permanently set speech volume (20 to 400). Note that you can also set
       the :ref:`system volume<system_volume>`.
   * - ``<word,I am fine>``
     - Say given words one by one


.. _lang_details:

---------------
Switch language
---------------

If your robot supports multiple languages, you can switch between them by
inserting a tag into the text:

.. code-block:: python

    robot.say("<lang,de1>Hallo<lang,en1>Hello")

Setting a language is permanent until reboot. It resets most other permanent
settings.  Availability of languages depends on your purchase. Navel by default
comes with one language installed. Valid language tags are

* de1: German
* en1: English
* es1: Spanish
* it1: Italian
* nl1: Dutch
* pt1: Portuguese
* sw1: Swedish


--------------------------
Overview of tags for azure
--------------------------

To use the ``azure`` backend, call ``robot.set_speech_backend("azure", ...)``
first.

.. list-table::
   :widths: auto
   :header-rows: 1

   * - Example
     - Explanation

   * - ``<lang,en-US>``
     - Change the language for the following text using an Azure locale such as
       ``en-US``.
   * - ``<rate,+10%>``
     - Set the speaking rate for the following text. For example ``+10%`` or
       ``-15%``.

For the ``azure`` backend, the system parses leading tags until the first non-tag
text. Only ``lang`` and ``rate`` are applied. If the same tag appears multiple
times, the rightmost value wins. Unknown tags are removed and ignored.

.. code-block:: python

    robot.say("<lang,de-DE><rate,-15%><rate,+5%>Guten Morgen zusammen")

This uses ``de-DE`` and ``+5%`` and speaks only ``Guten Morgen zusammen``.


.. _mrk_details:

---------
Bookmarks
---------

This will allow you to register custom callbacks to be called at specific points
during speech.

Registering callbacks
^^^^^^^^^^^^^^^^^^^^^

The :py:meth:`~.Robot.set_bookmark_callback` function can be used to easily
register new callbacks by providing a number and an async function that takes a
single :py:class:`~.Robot` as its only input:

.. code-block:: python
    :linenos:

    import asyncio

    import navel

    async def close_eyes(robot: navel.Robot):
        print("Closing eyes")
        robot.head_eyelids(0, 0)

    async def open_eyes(robot: navel.Robot):
        print("Opening eyes")
        robot.head_eyelids(1, 1)

    async def main():
        async with navel.Robot() as robot:
            robot.set_bookmark_callback(0, close_eyes)
            robot.set_bookmark_callback(1, open_eyes)


    if __name__ == "__main__":
        asyncio.run(main())

.. warning::
    The callback system only supports numbers between 0 and 65535. Additionally,
    we plan to implement some built-in default callbacks using the highest
    numbers in the range, so we suggest to avoid going over 60000 if possible.

.. note::
    Only one callback can be registered per bookmark number. Any subsequent
    calls to ``set_bookmark_callback`` with the same number will replace whatever
    the previous callback was.

If you run the code, you may notice nothing happens yet.
That's to be expected, since we only registered the callbacks without actually
calling them anywhere.

Executing callbacks
^^^^^^^^^^^^^^^^^^^

Callbacks will be automatically executed when the text-to-speech engine reaches
the place in the string where they are placed.

You can add them directly into the text you want the robot to say by using the
format ``"<mrk,#>"``. To see this in action, try adding the following directly
after line 16 from above:

.. code-block:: python

    robot.say("Look, I can <mrk,0>close my eyes, and <mrk,1>open them!")

Using callbacks like this allows you to easily synchronize speech and movement.