..  _guiro:

Guiro (Radio/Media Player)
==========================

`Güiro  <https://en.wikipedia.org/wiki/G%C3%BCiro>`_ is a component that plays local audio files.
It uses a vlc running locally on ``AUD`` and does not depend on nor makes use of :ref:`hookah`.

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

Component repository
~~~~~~~~~~~~~~~~~~~~

``https://projects.cit-ec.uni-bielefeld.de/git/lsp-csra.audiofeatures.git``, startup file is ``scripts/start_guiro.sh`` and subfolder is ``Guiro/``

System startup
~~~~~~~~~~~~~~~~~

* The component script is called ``component_start_on_aud`` and needs to be started with ``AUDSCRIPT=guiro`` set.
* In the base vdemo, start ``spreaddaemon_AUD`` in the ``base`` tab and in the supplementary vdemo, start ``Guiro`` in the ``sandbox`` tab (alternatively, in the``study-addressing-apartment`` vdemo, start ``Radio``).

Interfaces
-----------------

``/home/audio/control/radio/`` provides a simple API with just a ``play()`` and a ``stop()`` RPC.
For ``play()``, the string parameter denotes the file to play.
Both absolute and relative paths work, with relative paths being relative to the ``Guiro/`` directory.
It is also possible to send stream URLs; all strings starting with ``http://`` or ``https://`` will be regarded as such.

=========================================== ===================== ==================
 Scope (Local Server) + Method               Argument Type         Return Type
=========================================== ===================== ==================
 ``/home/audio/control/radio/play()``        string                bool
 ``/home/audio/control/radio/stop()``        string (ignored)      bool
=========================================== ===================== ==================


Examples
--------------

Former versions of Guiro allowed simultaneous playback of multiple files.
The file name doubled as a handle on the playback instance. It is therefore
good practice, even though absolutely unnecessary, to use the filename for
``stop()``, too. This way, you won't have to change your code if the behavior
should ever change again.

.. code-block:: python
   :emphasize-lines: 5,6,8

    import rsb, logging, time
    if __name__ == '__main__':
        logging.basicConfig()
        filename = 'cheerleader-full.ogg'
        with rsb.createRemoteServer('/home/audio/control/radio') as server:
            server.play(filename)
            time.sleep(5)
            server.stop(filename)