.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/40_sychronize_sound_and_trigger.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_generated_tutorials_40_sychronize_sound_and_trigger.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_tutorials_40_sychronize_sound_and_trigger.py:


=============================
Synchronize sound and trigger
=============================

Often, a trigger must be emitted simultenously with a sound onset, with as little delay
and jitter as possible. With ``stimuli``, similarly to ``psychtoolbox``, the key concept
is to schedule the sound.

First, let's have a look at our default device latency.

.. GENERATED FROM PYTHON SOURCE LINES 12-23

.. code-block:: Python



    import sounddevice as sd

    from stimuli.audio import SoundAM
    from stimuli.time import sleep
    from stimuli.trigger import MockTrigger

    idx = sd.default.device["output"]
    print(f"Low-latency (s): {sd.query_devices()[idx]['default_low_output_latency']}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Low-latency (s): 0.008684807256235827




.. GENERATED FROM PYTHON SOURCE LINES 25-28

Next, we can schedule a sound with the argument ``when`` which will use the clock
provided in the argument ``clock`` to schedule the sound. Then, we wait for this
duration to elapse before sending the trigger.

.. GENERATED FROM PYTHON SOURCE LINES 28-41

.. code-block:: Python


    trigger = MockTrigger()  # replace with your trigger object
    sound = SoundAM(
        frequency_carrier=1000,
        frequency_modulation=40,
        method="dsbsc",
        volume=10,
        duration=1,
    )
    sound.play(when=0.5, blocking=False)
    sleep(0.5)
    trigger.signal(1)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [mock.signal] INFO: Mock set to 1.




.. GENERATED FROM PYTHON SOURCE LINES 42-68

A quick measurement on a dual-boot Windows/Linux computer connected to a USB Crimson 3
soundcard shows that the delay and jitter of ``stimuli`` are similar to
``psychtoolbox`` on linux.

.. image:: ../../_static/performance.png
   :align: center

On different computers with different soundcards, the performance may vary. For
instance, with on-board soundcards on Linux, both psychtoolbox and stimuli are usually
perfectly synchronized with the trigger. In the end, the performance should always be
measured on the target system.

.. code-block:: python

    from stimuli.audio import Tone
    from stimuli.time import sleep
    from stimuli.trigger import ParallelPortTrigger

    sound = Tone(frequency=440, volume=100, duration=0.3)
    trigger = ParallelPortTrigger("/dev/parport0")

    for k in range(10):
        sound.play(when=0.2)
        sleep(0.2)
        trigger.signal(1)
        sleep(0.5)


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.716 seconds)

**Estimated memory usage:**  147 MB


.. _sphx_glr_download_generated_tutorials_40_sychronize_sound_and_trigger.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 40_sychronize_sound_and_trigger.ipynb <40_sychronize_sound_and_trigger.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 40_sychronize_sound_and_trigger.py <40_sychronize_sound_and_trigger.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 40_sychronize_sound_and_trigger.zip <40_sychronize_sound_and_trigger.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_