.. _hookah:

Hookah
=====================

Hookah provides an RSB interface for audio input and output via the Motu devices (see :ref:`audio_hardware`) and conversion to different audio formats. 


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

Component repository:
 - `Browse component repository <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/audiofeatures/revisions/master/show/hookah>`_.
 - ``git clone https://projects.cit-ec.uni-bielefeld.de/git/lsp-csra.audiofeatures.git`` (subfolder ``hookah/``)

System startup:
 - The start script ``start_hookah.sh`` can be found in the ``scripts/`` directory. It will basically execute ``audioserver.py`` in ``hookah/``.
 - The component script is called ``component_start_on_aud`` and needs to be started with ``AUDSCRIPT=hookah`` set.
 - Dependencies: ``spreaddaemon_AUD`` and ``jack``
 
Related projects:
 - :ref:`guiro` (radio mockup/RSB media player)
 - :ref:`batcry` (ultrasound speaker wake-up)
 - :ref:`foe` (*Friend of the Eardrum*)
 - :ref:`JackOnJackOff` (Jack watchdog)

Configuration:
 - The current configuration can be found in `${prefix}/etc/hooka_config.json <file:///vol/csra/releases/trusty/lsp-csra-nightly/etc/hookah_config.json>`_ or in the `repository <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/audiofeatures/revisions/master/entry/hookah/hookah_config.json>`_.
 - When looking up scopes in the config, don't forget to add the proper infix and either the ID or the format. So an input configuration of ``/citec/csra/home/hallway/entrance/asc10`` becomes something like ``/citec/csra/home/hallway/entrance/asc10/audio/in/16bit/16000Hz/LE`` or ``/citec/csra/home/hallway/entrance/asc10/audio/in/default``.
 
Interfaces
-----------------

Audio sinks and sources are provided according to the configuration file in ``hookah/hookah_config.json``. This needs to be changed on ``AUD`` and ``scripts/releaseme.sh`` run before the changes take effect. In future, the config will be automatically generated from the device manager state.

For the config entry you need to know which channel the speaker or microphone is connected to. This information can be largely deduced from the `cabling overview <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/wiki/Audiocabling>`_. The channel number for a microphone connected to input channel :math:`c` on device :math:`d` is just :math:`(d-1) \cdot 8+c`, where :math:`1 \leq c \leq 8` and :math:`1 \leq d \leq 4` (in English, this means that the 8 input channels each of the 4 Motu devices has are patched in the order you'd expect). The speaker config is slightly more complicated than that and currently there is no real alternative to checking the routing matrix manually because the special cases change so frequently that this documentation would be outdated by the time you read it. For this, check `http://8m-1.local./#routing`_ on ``AUD``.

============================================== ========================================
Scope (Listener)                               Type        
============================================== ========================================
 ``/<basescope>/audio/out/<id>``               `Soundchunk`_
 Example: ``/citec/csra/home/hallway/entrance/ad10/audio/out/marytts`` `Soundchunk`_
============================================== ========================================

The ``<id>`` is a unique string only used by that specific application or informer to prevent conflicts. It is configured in the JSON config mentioned above. Multiple sources sending to the same output channel will be mixed together, as long as they use different IDs. If they use the same ID, the Soundchunks will be queued one after the other, which will probably not be the expected behavior.

=============================================================== ========================================
Scope (Informer)                            Type       
=============================================================== ========================================
 ``/<basescope>/audio/in/<bitdepth>bit/<samplerate>Hz/[LE|BE]`` `Soundchunk`_
 Example: ``/citec/csra/home/hallway/entrance/asc10/audio/in/16bit/16000Hz/LE``    `Soundchunk`_
=============================================================== ========================================

.. _Soundchunk: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-audition.html#message-soundchunk

For some of the currently used scopes see `the wiki <https://projects.cit-ec.uni-bielefeld.de/projects/integrationgroup/wiki/Architecture_Notes#Audio-Subsystem>`_.

Network Time Provider
---------------------
**This feature is currently non-functional because the main gstreamer pipelines no longer provide a clock at all**

For remote live sinks or sources that need to be synchronized with their Hookah counterpart (or with each other), Hookah provides a `GStreamer network clock <https://developer.gnome.org/gstreamer-libs/stable/GstNetTimeProvider.html>`_ on port 65084. There is `documentation <https://developer.gnome.org/gstreamer-libs/stable/GstNetClientClock.html>`_ on how to use it in your C code. Python uses the ``from gi.repository import GstNet`` import and function name conversions as usual. As far as I can tell, it is not possible to force a ``gst-launch`` pipeline to use such a clock though.


TODO
--------------

 - Configuration guide
 - Known problems, especially scheduling-wise
 - Python autodoc
 - ...