=============
Azure TTS
=============

Navel's Python SDK can use Microsoft Azure as a text-to-speech backend for
scripts that need cloud-generated voices. This gives researchers access to a
large Azure voice catalog with support for more than 70 languages, including
multilingual voices and optional speaking styles.

Azure TTS requires an Azure Speech resource, a matching resource key and region,
and an internet connection from the robot. The SDK sends the text to Azure,
receives synthesized audio, and plays it through Navel's normal TTS audio
device.

.. warning::
    Azure Speech is a billed cloud service. Do not put account keys into source
    control or share them in notebooks, papers, screenshots, or issue reports.

-------------------------
Create the Azure resource
-------------------------

You need an Azure account with an active subscription and an Azure AI Speech
resource. After the resource has been deployed, open the resource's **Keys and
Endpoint** page and copy one of the keys. Also note the resource's region
identifier, for example ``germanywestcentral``. These are the values passed as
``speech_key`` and ``speech_region`` when calling
``set_speech_backend("azure", ...)``.

More info: https://learn.microsoft.com/en-us/azure/ai-services/Speech-Service/language-support?tabs=tts


If you prefer the Azure CLI, the equivalent minimal setup is:

.. code-block:: console

    az login
    az account set --subscription "<SUBSCRIPTION_ID>"
    az group create \
        --name "<RESOURCE_GROUP>" \
        --location "germanywestcentral"
    az cognitiveservices account create \
        --name "<RESOURCE_NAME>" \
        --resource-group "<RESOURCE_GROUP>" \
        --kind "SpeechServices" \
        --sku "S0" \
        --location "germanywestcentral" \
        --yes
    az cognitiveservices account keys list \
        --name "<RESOURCE_NAME>" \
        --resource-group "<RESOURCE_GROUP>" \
        --query "key1" \
        -o tsv

-----------------
Use Azure TTS
-----------------

The Azure backend is selected from Python with
:py:meth:`navel.Robot.set_speech_backend`. The SDK package already depends on
the Azure Speech SDK.

Create a script such as ``azure_speak.py``:

.. code-block:: python
    :linenos:

    #!/usr/bin/env python3

    import asyncio

    import navel


    async def main():
        async with navel.Robot() as robot:
            robot.set_speech_backend(
                "azure",
                speech_key="<your Azure Speech key>",
                speech_region="germanywestcentral",
                locale="de-DE",
                voice_name="zh-CN-XiaoyouMultilingualNeural",
            )
            await robot.say("Hallo, ich spreche mit Azure Text-to-Speech.")


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

Run it on the robot:

.. code-block:: console

    python3 azure_speak.py

To use a different voice, change both ``locale`` and ``voice_name`` to a
supported Azure Speech voice. Azure text-to-speech supports more than 70
languages, and the voice list changes over time, so use Microsoft's language
and voice support page when choosing a voice for a study.

The Azure backend also accepts optional ``style`` and ``pitch`` arguments:

.. code-block:: python

    robot.set_speech_backend(
        "azure",
        speech_key="<your Azure Speech key>",
        speech_region="germanywestcentral",
        locale="de-DE",
        voice_name="zh-CN-XiaoyouMultilingualNeural",
        style="chat",
        pitch="+14%",
    )

These are the relevant parameters for Azure TTS:

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

   * - Parameter
     - Value
   * - ``backend``
     - ``"azure"`` to use Azure TTS, or ``"acapela"``
   * - ``speech_key``
     - One key from the Azure Speech resource's **Keys and Endpoint** page
   * - ``speech_region``
     - The Azure region identifier for the Speech resource, for example
       ``germanywestcentral``
   * - ``locale``
     - The BCP-47 locale for the selected voice, for example ``en-US``
   * - ``voice_name``
     - The Azure voice name, for example ``zh-CN-XiaoyouMultilingualNeural``
   * - ``style``
     - Optional Azure speaking style supported by the selected voice
   * - ``pitch``
     - Optional pitch adjustment, for example ``+14%``