AudioSample

AudioSample objects are used for playing external audio files. 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.

Also, see Play.audio().

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.

Creating an AudioSample

You can create an AudioSample using the following functions:

AudioSample(filename)

AudioSample(filename, actualPitch, volume, voices)

Parameter	Type	Default	Description
`filename`	`str`	required	The audio file to load (a WAV or AIF file).
`actualPitch`	`int or float`	`A4`	The recorded sound's own pitch, as a MIDI pitch from 0 to 127, or a frequency in hertz (8.17 to 12600.0). Defaults to A4 (440 Hz).
`volume`	`int`	`127`	How loud the sample is, from 0 to 127.
`voices`	`int`	`16`	How many voices can play at once, for polyphony.

For example,

sample = AudioSample("sound.wav")

where "sound.wav" is stored in the same folder as your program.

Functions

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

Function	Description
`sample.play()`	Play the sample once.
`sample.loop()`	Play the sample over and over.
`sample.stop()`	Stop the sample playing.
`sample.pause()`	Pause the sample, remembering where it is.
`sample.resume()`	Resume the sample from where it was paused.
`sample.isPlaying()`	Report whether the sample is currently playing.
`sample.isPaused()`	Report whether the sample is currently paused.
`sample.getPitch()`	Return the sample's current playback pitch.
`sample.setPitch(pitch)`	Set the sample's playback pitch, pitch-shifting it from its base pitch.
`sample.getFrequency()`	Return the sample's current playback frequency.
`sample.setFrequency(freq)`	Set the sample's playback frequency, pitch-shifting it.
`sample.getPanning()`	Return the sample's stereo position.
`sample.setPanning(panning)`	Set the sample's stereo position.
`sample.getVolume()`	Return how loud the sample is.
`sample.setVolume(volume)`	Set how loud the sample is.
`sample.getFrameRate()`	Return the sample's recording rate.

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.