.. CS116 documentation master file, created by
   sphinx-quickstart on Mon Mar  4 10:37:08 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Sound
=====

We represent sounds as a **list** of `SoundSample <sound_sample.html>`_ objects.


Example Usage
-------------

.. code:: python
   
   # Create a Sound object called 'sound' with 256 samples.
   sound = Sound(256)
   
   # Find its length. This will be 256.
   length = sound.getLength()
   
   # Load a sound from a file.
   otherSound = Sound('media/always.wav')
   
   # Play it.
   otherSound.play()
   
   # Open it in the interactive sound explorer.
   otherSound.explore()
   
   # Get its samples.
   samples = otherSound.getSamples()
   
   # Print the first sample's value.
   samp = samples[0]
   print(samp.getValue())

Initialization
--------------

To initialize a silent sound with a given number *n* of samples:

.. py:function:: Sound.Sound(self, n)

   :param int n: number of samples long the sound will be.

-------------------------

To initialize from a file:

.. py:function:: Sound.Sound(self, filename)

   :param string filename: the filename of the sound file.
   
.. code:: python
   
   # Loads the picture 'beach.png' that lives in the 'media' folder.
   p = Picture('media/beach.png')


Methods
-------

Play the sound.

.. py:function:: Sound.play(self)

.. code:: python

   sound.play()

See a visual representation of the sound in the interactive sound explorer.

.. py:function:: Sound.explore(self)

.. code:: python

   sound.explore()

Write your sound to a wav file.

.. py:function:: Sound.write(self, filename)
   
   :param string filename: filename for the written file.

.. code::

   sound.write('mysound.wav')
   

Getters
-------

Return the length of a sound.

.. py:function:: Sound.getLength(self)

.. code:: python

   length = sound.getLength()

Return the list of samples.

.. py:function:: Sound.getSamples(self)

.. code:: python

   samples = sound.getSamples()

Return the sample at *index*.

.. py:function:: Sound.getSample(self, index)

   :param int index: the index of the desired sample.

.. code:: python

   aSample = sound.getSample(0)
   
   samples = sound.getSamples()
   anotherSample = samples[0]
   
   # This will print True.
   print(aSample.getValue() == anotherSample.getValue())

.. toctree
