AudioSample objects are used for playing external audio files (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float). They can be played, pitch-shifted, looped, paused, resumed, and stopped, among other things.

An application may have several AudioSample objects playing at the same time.  In fact, it is possible to create complex timbres by loading several simpler 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.

NOTE: One limitation is that AudioSamples are very expensive in terms of memory. Although it is possible to load whole songs, you should load only smaller files (e.g., a few seconds long). Since AudioSamples can be looped, one may load specially edited loops, and use them to create longer sound artifacts. For example, see here.

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

from music import *

The simplest way to create an AudioSample object is this (where “sound.wav” is stored in the same folder as your program):

 a = AudioSample("sound.wav")

Audio samples may also be created using one of the following functions:

Function	Description
AudioSample(filename)	Creates an audio sample from the filename provided (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float).
AudioSample(filename, actualPitch)	Creates an audio sample from the filename provided (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float). Parameter actualPitch specifies the actual tone of the sound as a MIDI pitch (integer), or frequency in Hz (float) – default is A4 or 440.0.
AudioSample(filename, actualPitch, volume, voices)	Creates an audio sample from the filename provided (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float). Parameter actualPitch specifies the actual tone of the sound as a MIDI pitch (integer), or frequency in Hz (float) – default is A4 or 440.0. Parameter volume specifies how loud (0 to 127) is the audio sample (default is 127).
AudioSample(filename, actualPitch, volume, voices)	Creates an audio sample from the filename provided (supported formats are WAV and AIF — 16, 24 and 32 bit PCM, and 32-bit float). Parameter actualPitch specifies the actual tone of the sound as a MIDI pitch (integer), or frequency in Hz (float) – default is A4 or 440.0. Parameter volume specifies how loud (0 to 127) is the audio sample (default is 127). Parameter voices specifies the number of parallel voices for polyphony (default is 16).

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).

NOTE: All the above functions have an optional parameter, voice – to indicate a particular voice, if desired. For most practical situations this is not necessary to use.

Also, see Play.audio().