===========
Audio
===========

Mekanimo uses :term:`Pygame's <Pygame>` mixer module for playing sound files.  You can see the full documentation for the mixer module at http://www.pygame.org/docs/ref/mixer.html.  Sound files can be in OGG (Vorbis) or uncompressed WAV format. If you wish to create your own sound effects we highly recommend Audacity which can be downloaded from http://audacity.sourceforge.net/.

Playing sound
==============
The most common use of sound in Mekanimo is playing sound files when an event triggers an action.  

.. code-block:: python

    # Play sound when circle1 collides with ANYTHING.
    circle1.bind(COLLISION, system.evtHandler, ANYTHING, PLAYSOUND, 
                 **{'sound': 'bird_chirp1', 'volume': 0.40})

The same sound file can be played programmatically as shown below.
                 
.. code-block:: python

    system.playSound(groupName='bird', soundName='chirp1', volume=.4)
    
You can repeat the sound by providing the optional `repeat` argument.  By default, sound is played with no repetition.

.. code-block:: python

    system.playSound(groupName='bird', soundName='chirp1, volume=.4, repeat=1)
    
If you would like to play a file not included with Mekanimo's sound library you can use the optional `filePath` argument.

.. code-block:: python

    system.playSound(groupName=None, soundName=None, volume=.4, repeat=3, filePath='c://mySounds//lasergun.wav')
                 
Adding your own sound effects
=============================
If you would like to add your sound effects so that they would appear with the Mekanimo's sound library, you can add your files to the `Sounds` subdirectory in the installation directory.  By convention sound files are named with group name and sound name separated by an underscore.