# Sound Processing Utilities

## Class

`sounds.Sound`([inFile, inData, inRate]) | Class for working with sound in Python.

### Methods

`sounds.Sound.info`() | Return information about the sound.
`sounds.Sound.play`() | Play a sound-file.
`sounds.Sound.readSound`(inFile) | Read data from a sound-file.
`sounds.Sound.setData`(data, rate) | Set the properties of a Sound-object.
`sounds.Sound.summary`() | Display information about the sound.
`sounds.Sound.writeWav`([fullOutFile]) | Write sound data to a WAV-file.

## Details

Python module to read, play, and write sound data. For flexibility, FFMPEG is used for non-WAV files.

You can obtain it for free from
  http://ffmpeg.org
Mac users should best get binaries from
  - http://www.evermeet.cx/ffmpeg/ffmpeg-2.1.4.7z
  - http://www.evermeet.cx/ffplay/ffplay-2.1.4.7z

Note that FFMPEG must be installed externally! Please install ffmpeg/ffplay in the following directory:

> - Windows: “C:\Program Files\ffmpeg\bin\”
> - Mac: “/usr/local/bin/” (is already included in the default paths of the Mac terminal.)
> - Linux: “/usr/bin/”

Compatible with Python 2.x and 3.x

class `sounds.``Sound`(inFile=None, inData=None, inRate=None)

  Class for working with sound in Python.

  A Sound object can be initialized
    - by giving a filename
    - by providing “int16” data and a rate
    - without giving any parameter; in that case the user is prompted to select an infile

  Parameters: | inFile : string path- and file-name of infile, if you get the sound from a file. inData: array manually generated sound data; requires “inRate” to be set, too. inRate: integer sample rate; required if “inData” are entered.
  Returns: | None : No return value. Initializes the Sound-properties.

  Notes

  For non WAV-files, the file is first converted to WAV using FFMPEG, and then read in. A warning is generated, to avoid unintentional deletion of existing WAV-files.

  SoundProperties:
    - source
    - data
    - rate
    - numChannels
    - totalSamples
    - duration
    - bitsPerSample

  Examples

      >>> from thLib.sounds import Sound
      >>> mySound1 = Sound()
      >>> mySound2 = Sound('test.wav')
      >>>
      >>> rate = 22050
      >>> dt = 1./rate
      >>> freq = 440
      >>> t = np.arange(0,0.5,dt)
      >>> x = np.sin(2*np.pi*freq * t)
      >>> amp = 2**13
      >>> sounddata = np.int16(x*amp)
      >>> mySound3 = Sound(inData=sounddata, inRate=rate)

  `info`()

    Return information about the sound.

    Parameters: | None :
    Returns: | source : name of inFile rate : sampleRate numChannels : number of channels totalSamples : number of total samples duration : duration [sec] bitsPerSample : bits per sample

    Examples

        >>> mySound = Sound()
        >>> mySound.readSound('test.wav')
        >>> info = mySound.info()
        >>> (source, rate, numChannels, totalSamples, duration, bitsPerSample) = mySound.info()

  `play`()

    Play a sound-file.

    Parameters: | None :
    Returns: | None :

    Notes

    On “Windows” the module “winsound” is used; on other platforms, the sound is played using “ffplay” from FFMPEG.

    Examples

        >>> mySound = Sound()
        >>> mySound.readSound('test.wav')
        >>> mySound.play()

  `readSound`(inFile)

    Read data from a sound-file.

    Parameters: | inFile : string path- and file-name of infile
    Returns: | None : No return value. Sets the property “data” of the object.

    Notes

    - For non WAV-files, the file is first converted to WAV using FFMPEG, and then read in.

    Examples

        >>> mySound = Sound()
        >>> mySound.readSound('test.wav')

  `setData`(data, rate)

    Set the properties of a Sound-object.

  `summary`()

    Display information about the sound.

    Parameters: | None :
    Returns: | None :

    Examples

        >>> mySound = Sound()
        >>> mySound.readSound('test.wav')
        >>> mySound.summary()

  `writeWav`(fullOutFile=None)

    Write sound data to a WAV-file.

    Parameters: | fullOutFile : string Path- and file-name of the outfile. If none is given, the user is asked interactively to choose a folder/name for the outfile.
    Returns: | None :

    Examples

        >>> mySound = Sound()
        >>> mySound.readSound('test.wav')
        >>> mySound.writeWav()

`sounds.``main`()

  Main function, to test the module