AudioSample

The AudioSample class includes functions related to playing audio samples in real-time.  An audio sample is a sound object created from an external audio file (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float), which can be played, looped, paused, resumed, and stopped.  The functions below are intended for building interactive musical instruments and installations.

An application may have several AudioSample objects active at the same time.  It is even possible to create complex timbres by loading several simple sound objects and manipulating them (e.g., change their frequency and/or volume) in real-time.  AudioSample objects open endless timbral possibilities for interactive applications.

This class is included in the music library, so, you need the following in your program:

from music import *

Use the following function to create an AudioSample object:

 a = AudioSample("sound.wav")
Function Description
AudioSample(filename, referencePitch, volume) Creates an audio sample from the audio file specified in filename (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float).  Parameter referencePitch (optional) specifies a MIDI note number or float frequency to be used when changing pitch or frequency during playback (default is A4 or 440.0). Parameter volume (optional) specifies how loud (0 to 127) the audio sample is (default is 127).

Once an audio sample, a, has been created, the following functions are available:

Function Description
a.play()

a.play(start, size)

Play the sample once.  If start and size are provided, the sample is played from millisecond start until millisecond start+size (default is 0 and -1, respectively, meaning from beginning to end).
a.loop()

a.loop(times, start, size)

Repeat the sample indefinitely.  Optional parameters times specifies the number of times to repeat (default is -1, indefinitely).  If start and size are provided, looping occurs between millisecond start and millisecond start+size (default is 0 and -1, respectively, meaning from beginning to end).
a.stop() Stops sample playback immediately.
a.pause() Pauses sample playback (remembers current position for resume).
a.resume() Resumes sample playback (from the paused position).
a.isPlaying() Returns True if the sample is still playing, False otherwise.
a.setPitch(pitch) Sets the sample pitch (0-127) through pitch shifting from sample’s base pitch.
a.getPitch() Returns the sample’s current pitch (it may be different from the default pitch).
a.setFrequency(freq) Sets the sample pitch frequency (in Hz).  This is equivalent to setPitch(), except it provides more granularity (accuracy).  For instance, pitch A4 is the same as frequency 440 Hz.
a.getFrequency() Returns the current playback frequency.
a.setVolume(volume) Sets the volume (amplitude) of the sample (volume ranges from 0 – 127).
a.getVolume() Returns the current volume (amplitude) of the sample (volume ranges from 0 – 127).
a.setPanning(panning) Sets the panning of the sample (panning ranges from 0 – 127).
a.getPanning() Returns the current panning of the sample (panning ranges from 0 – 127).
a.getFrameRate() Returns the sample’s recording rate (e.g., 44100.0 Hz).