.. _speech_synthesis:

Speech Synthesis
================

The speech synthesis component based on `MaryTTS <http://mary.dfki.de/>`_  is
part of the incremental speech processing toolkit `InproTK <https://bitbucket.org/inpro/inprotk>`_.
At present we have one speech synthesis configuration for each interaction island 
(``/citec/csra/home/kitchen/assistance`` ,  ``/citec/csra/home/hallway/entrance``) 
and an additional location for developer feedback (``/citec/csra/control``). 
The default tts language is German for the interaction islands and
English for the developer feedback.

Related resources
-----------------

Component repository:
 - Browse component repository: `inprotk-conf <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/inprotk-conf/>`_.
 - ``git clone https://projects.cit-ec.uni-bielefeld.de/git/inprotk-conf.git/``

System startup:
 - The speech synthesis can be found in ``lsp-csra-base.sh`` on the ``inpro`` tab.
 - The component script is called ``component_inprotk_synthesis``

Related projects:
 - Browse repository `system-startup <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/system-startup>`_.
 - Browse project `InproTK-DSG <https://bitbucket.org/dsgbielefeld/inprotk>`_.


Interfaces
----------

A say action can be invoked by sending task states to the corresponding scope or
by sending a simple string. In the latter case, the component gives no feedback
about the current state of the say action.

=========================================== ========================================
Scope (Listener)                            Type
=========================================== ========================================
``<location>/saytask``                      `Task State`_
``<location>/SAY``                          `String`_
``<location>/ttsi/SAY``	    	            `TextToSpeechInstruction`_
=========================================== ========================================



The informer gives feedback about the current state of the say task.

=========================================== ========================================
Scope (Informer)                            Type
=========================================== ========================================
``<location>/saytask``                      `Task State`_
=========================================== ========================================

.. _Task State: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-communicationpatterns.html#rst.communicationpatterns.TaskState
.. _String: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html?highlight=string#rst.generic.Value.string
.. _TextToSpeechInstruction:  http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-tts.html#rst.tts.TextToSpeechInstruction



Examples
--------

Change TTS voice
################

Change the voice of the speech synthesis is possible via arguments on `startup <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/system-startup/revisions/master/entry/lsp-csra-base.sh.in>`_ .

=========================================== ======================================== ========================================
Command                                     Arguments                                Default
=========================================== ======================================== ========================================
``-Dinpro.tts.voice=<voice>``               bits3-hsmm, bits1-hsmm, cmu-slt-hsmm     bits1-hsmm
``-Dinpro.tts.language=<language>``         de, en-US                                de
=========================================== ======================================== ========================================


Trigger a say task (in the hallway)
###################################

Trigger a task with TextToSpeechInstruction:

.. code-block:: java
   :emphasize-lines: 3,9,11

    // RSB Informer
    Informer<TextToSpeechInstructionType.TextToSpeechInstruction> informer =
	Factory.getInstance().createInformer("/citec/csra/home/hallway/entrance/ttsi/SAY");
    informer.activate();

    //create a text to speech instruction
    TextToSpeechInstructionType.TextToSpeechInstruction.Builder ttsiBuilder =
	TextToSpeechInstructionType.TextToSpeechInstruction.newBuilder();
    ttsiBuilder.setText("Dieser Text wird gesprochen!");
    ttsiBuilder.setPlaybackOption(TextToSpeechInstructionType.TextToSpeechInstruction.
	PlaybackOption.PLAY);

    //send the text to speech instruction
    informer.send(ttsiBuilder.build());


Trigger a task with TaskState, deprecated:

.. code-block:: java
   :emphasize-lines: 3,11

    // RSB Informer
    Informer<TaskStateType.TaskState> informer = Factory.getInstance().
        createInformer("/citec/csra/home/hallway/entrance/saytask");
    informer.activate();

    // create a task state
    TaskStateType.TaskState.Builder taskBuilder = TaskStateType.TaskState.newBuilder();
    taskBuilder.setOrigin(TaskStateType.TaskState.Origin.SUBMITTER);
    taskBuilder.setState(TaskStateType.TaskState.State.INITIATED);
    taskBuilder.setSerial(1);
    taskBuilder.setPayload(ByteString.copyFromUtf8("Dieser Text wird synthetisiert."));
    taskBuilder.setWireSchema(ByteString.copyFromUtf8("utf-8-string"));

    // send the task state
    informer.send(taskBuilder.build());


Configure own speech recognition
################################

1. Check out the configuration project:

.. code-block:: bash

	git clone -b minimal https://projects.cit-ec.uni-bielefeld.de/git/lsp-csra.inprotk-conf.git


2. Change configurations, e.g., the input scope in the ``iu-config.xml``

.. code-block:: xml
   :emphasize-lines: 2

    <component name="ttsilistener" type="de.unibi.agai.inproapp.module.RsbTtsInstructionListener">
        <property name="scope" value="/citec/csra/home/hallway/entrance/ttsi/SAY"/>
        <property name="synthesisAdaptable" value="aiSS"/>
        <propertylist name="hypChangeListeners">
            <item>aiSS</item>
        </propertylist>
    </component>