Playing sound files
================================

Psiexp uses Unix commands **afplay** and **sox** to play sound files.

To play a file, use :func:`system` to execute an **afplay** or **sox** command.

.. note::

   These commands can also be used in the macOS Terminal application.
   **afplay** is standard with macOS.  **sox** is included with Psiexp.
   To make the **sox** command available in Terminal windows,
   add the following line to your .bash_profile ::

      PATH=/Applications/Psiexp.app/Contents/Resources/libpsiexp/bin:$PATH

**Using afplay**

   here are two ways to play *soundFile.wav*::

      system("afplay soundFile.wav");
      system(sprintf("afplay %s", "soundFile.wav"));

**Using sox**

   With sox, you can modify how the sound is played::

      system("sox soundFile.wav -d");  # play sound file
      system("sox soundFile.wav -d pitch -100"); # lower pitch by 100 cents
      system("sox soundFile.wav -d trim 0 1.5"); # only play first 1.5 seconds

   Sox is very powerful and complicated.  Documentation can be
   found `here <http://sox.sourceforge.net/sox.html>`_

**Asynchronous use**

   The above commands wait until the sound file has finished playing before responding to any user interface events.  To avoid this, use the :func:`readPipe` call::


        player = readPipe(sprintf("sox -q \"%s\" -d", filename))

   This returns immediately, and when this process is finished an event will be generated of type eof and source player