========
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
----------------

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

   * - Example
     - Explanation

   * - ``<alt,1>``
     - Choose alternative pronounciation 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.  Availablilty 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


.. _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.