buffer~

Store audio samples

Description

buffer~ works as a buffer of memory in which samples are stored to be saved, edited, or referenced in conjunction with many different objects, including play~ / groove~ (to play the buffer), record~ (records into the buffer), info~ (to report information about the buffer), peek~ (to write into/read from the buffer like the table object), lookup~ (to use the buffer for waveshaping), cycle~ (to specify a 512-point waveform), and wave~ (to specify a waveform).

Arguments

Name Type Opt Description
buffer-object-name symbol Obligatory. The first argument is a name used by other objects to refer to the buffer~ to access its contents.

For information about using named objects in Max for Live, click here.
filename symbol opt After the buffer~ object's name, you may type the name of an audio file to load when the buffer~ is created.
buffer-duration (milliseconds) float or int opt After the optional filename argument, a duration may be provided, in milliseconds, to set the size of the buffer~, which limits the amount of sound that will be stored in it. (A new duration can be specified as part of a read message, however.) If no duration is typed in, the buffer~ has no sample memory. It does not, however, limit the size of an audio file that can be read in.
number-of-channels int opt After the duration, an additional argument may be typed in to specify the number of audio channels to be stored in the buffer~. (This is to tell buffer~ how much memory to allocate initially; however, if an audio file with more channels is read in, buffer~ will allocate more memory for the additional channels.) The maximum number of channels buffer~ can hold is four. By default, buffer~ has one channel.

Messages

bang Redraws the contents of the buffer~ object's waveform display window. You can open the display window by double-clicking on the buffer~ object.
(remote) The contents of buffer~ can be altered by the peek~ and record~ objects or referenced/played-back by the 2d.wave~, play~, wave~, groove~, buffir~, cycle~, and lookup~ objects.
(drag) When an audio file is dragged from the Max 5 File Browser to a buffer~ object, the file will be loaded.
clear Erases the contents of buffer~.
clearlow Erases the contents of the buffer like the clear message, but performs the clear as a low-priority task.
crop start and end times [list]
The crop message, followed by two numbers that specify start and end time in milliseconds, will trim the audio data in the buffer. It resizes the buffer~ to the selection length.
(mouse) Double-clicking on buffer~ opens a display window where you can view the contents of the buffer~. When the user clicks or drags with the mouse in the buffer~ object's editing window, the cursor's time location in the buffer~, in milliseconds, is sent out the outlet.
filetype file-type-code [symbol]
The word filetype, followed by symbol which specifies an audio file format, sets the file type used by the buffer~ object. The default file type is AIFF.Supported file types are identified as follows:

aiff- Apple Interchange File Format (default)
wave- WAVE
raw- raw
au- NeXT/Sun
format bit-depth/sample-type [list]
The word format followed by a number or a symbol will set the bit-depth or sample-type of the buffer.

Numerical values are:
8 - 8-bit integer
16 - 16-bit integer
24 - 24-bit integer
32 - 32-bit integer

Symbol values used to set bit-depth or sample type are:
int8 - 8-bit integer
int16 - 16-bit integer
int24 - 24-bit integer
int32 - 32-bit integer
float32 - 32-bit floating-point
float64 - 64-bit floating-point
mulaw - 8-bit mu-law encoding
alaw - 8-bit a-law encoding
enumerate Posts information in the Max window identifying all buffer~ objects which reference the same data stored in the buffer~ object which received the enumerate message.(The labelling information: "(this one)", will appear next to the address of the buffer~ object which received the enumerate message).
import filename [list]
The word import, followed by a filename, reads that file into buffer~ immediately if it exists in Max's search path without opening the Open Document dialog box. Without a filename, import brings up an Open Document dialog box allowing you to choose a file. The imported file retains the sampling rate and word size of the original file, but looping points and markers are not imported. The filename may be followed by a float indicating a starting time in the file, in milliseconds, to begin reading. (The beginning of the file is 0.)

The buffer~ object uses QuickTime to convert a media file (including MP3 files) into the sample memory of a buffer~, and requires that QuickTime be installed on your system. If you are using Max on Windows, we recommend that you install QuickTime and choose a complete install of all optional components.

Since the import message uses QuickTime, which specifies units of time for all files as 1/600 of a second rather than milliseconds, importing is not guaranteed to start at the specified offset with millisecond accuracy. The starting time may be followed by a float duration, in milliseconds, of sound to be read into buffer~. This duration overrides the current size of the object's sample memory. If the duration is negative, buffer~ reads in the entire file and resizes its sample memory accordingly. If duration argument is zero or not present, the buffer~ object's sample memory is not resized if the audio file is larger than the current sample memory size. The duration may be followed by a number of channels to be read in. If the number of channels is not specified, buffer~ reads in the number of channels indicated in the header of the audio file. Whether or not the number of channels is specified in the read message, the previous number of channels in a buffer~ is changed to the number of channels read from the file.
name buffer-object-name [symbol]
The word name, followed by a symbol, changes the name by which other objects such as cycle~, groove~, lookup~, peek~, play~, record~, and wave~ can refer to the buffer~. Objects that were referring to the buffer~ under its old name lose their connection to it. Every buffer~ object should be given a unique name; if you give a buffer~ object a name that already belongs to another buffer~, that name will no longer be associated with the buffer~ that first had it.
open Opens the buffer~ sample display window or brings it to the front if it is already open.
normalize normalization_factor [list]
The word normalize, followed by a floating point number, will scale the sample values in the buffer~ object so that the highest peak matches the value given by the argument. This can cause either amplification or attenuation of the audio, but in either case, every value is scaled.
printmodtime Posts information in the Max window about when the buffer~ was last modified (i.e. written into, or modified in attributes).
read filename [list]
Reads an AIFF, Next/Sun, or WAV file into the sample memory of the buffer~. The word read, followed by a filename, reads that file into buffer~ immediately if it exists in Max's search path without opening the Open Document dialog box. Without a filename, read brings up a standard Open Document dialog box allowing you to choose a file. The filename may be followed by a float indicating a starting time in the file, in milliseconds, to begin reading. (The beginning of the file is 0.) The starting time may be followed by a float duration, in milliseconds, of sound to be read into buffer~. This duration overrides the current size of the object's sample memory. If the duration is negative, buffer~ reads in the entire file and resizes its sample memory accordingly. If duration argument is zero or not present, the buffer~ object's sample memory is not resized if the audio file is larger than the current sample memory size. The duration may be followed by a number of channels to be read in. If the number of channels is not specified, buffer~ reads in the number of channels indicated in the header of the audio file. Whether or not the number of channels is specified in the read message, the previous number of channels in a buffer~ is changed to the number of channels read from the file.
samptype sample-type [symbol]
In left inlet: The word samptype, followed by a symbol, specifies the sample type to use when interpreting an audio file's sample data (thus overriding the audio file's actual sample type). This is sometimes called "header munging."

The following types of sample data are supported:

int8- 8-bit integer
int16- 16-bit integer
int24- 24-bit integer
int32- 32-bit integer
float32- 32-bit floating-point
float64- 64-bit floating-point
mulaw- 8-bit "mu"-law encoding
alaw- 8-bit a-law encoding
set buffer-object-name [symbol]
The word set, followed by a symbol, changes the name by which other objects such as cycle~, groove~, lookup~, peek~, play~, record~, and wave~ can refer to the buffer~. Objects that were referring to the buffer~ under its old name lose their connection to it. Every buffer~ object should be given a unique name; if you give a buffer~ object a name that already belongs to another buffer~, that name will no longer be associated with the buffer~ that first had it.
size buffer-duration (milliseconds) [float]
buffer-duration (milliseconds) [int]
The word size, followed by a duration in milliseconds, sets the size of the buffer~ object's sample memory. This limits the amount of data that can be stored, unless this size limitation is overridden by a replace message or a duration argument in a read message.
sizeinsamps buffer-duration (samples) [int]
buffer-duration (samples) [int]
The word size, followed by a duration in samples, sets the size of the buffer~ object's sample memory. This limits the amount of data that can be stored, unless this size limitation is overridden by a replace message or a duration argument in a read message.
sr sampling-rate (samples-per-second) [float]
The word sr, followed by a sampling rate, sets the buffer~ object's sampling rate. By default, the sampling rate is the current output sampling rate, or the sampling rate of the most recently loaded audio file.
readagain filename [list]
Reads sound data from the most recently loaded file (specified in a previous read or replace message).
replace filename [list]
Same as the read message with a negative duration argument. replace, followed by a symbol, treats the symbol as a filename located in Max's file search path. If no argument is present, buffer~ opens a standard open file dialog showing available audio files. Additional arguments specify starting time, duration, and number of channels as with the read message.
wclose Closes the buffer~ sample display window if it is open.
write filename [symbol]
Saves the contents of buffer~ into an audio file. A standard file dialog is opened for naming the file unless the word write is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename. Unless you change the format with the Format pop-up menu in the standard Save As dialog box, the file will be saved in the format specified by the most recently received filetype message, or the file type of the most recently opened audio file. By default, buffer~ saves in AIFF format.
writeaiff filename [symbol]
Saves the contents of the buffer~ as an AIFF file. A standard Save As dialog is opened for naming the file unless the word writeaiff is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename.
writeau filename [symbol]
Saves the contents of the buffer~ as a NeXT/Sun file. A standard Save As dialog is opened for naming the file unless the word writeau is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename.
writeraw filename [symbol]
Saves the contents of the buffer~ as a raw file with no header. The default sample format is 16-bit, but the output sample format can be set with the samptype message. A standard Save As dialog is opened for naming the file unless the word writeraw is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename.
writewave filename [symbol]
Saves the contents of the buffer~ into a WAV file. A standard Save As dialog is opened for naming the file unless the word writewave is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename.

Information for box attributes common to all objects

Output

float: When the user clicks or drags with the mouse in the buffer~ object's editing window, the cursor's time location in the buffer~, in milliseconds, is sent out the outlet.

Examples

buffer~ can be used as a waveform table for an oscillator or as a sample buffer

See Also

Name Description
2d.wave~ Two-dimensional wavetable
buffir~ buffer-based FIR filter
cycle~ Table lookup oscillator
groove~ Variable-rate looping sample playback
info~ Report information about a sample
lookup~ Transfer function lookup table
peek~ Read and write sample values
play~ Position-based sample playback
poke~ Write sample values to a buffer by index
record~ Record sound into a buffer
sfplay~ Play audio file from disk
sfrecord~ Record to audio file on disk
wave~ Variable size wavetable
MSP Tutorial 3: Wavetable Oscillator MSP Tutorial 3: Wavetable Oscillator
MSP Tutorial 12: Waveshaping MSP Tutorial 12: Waveshaping
MSP Tutorial 13: Recording and Playback MSP Tutorial 13: Recording and Playback
MSP Tutorial 14: Playback with Loops MSP Tutorial 14: Playback with Loops
MSP Tutorial 15: Variable-length Wavetable MSP Tutorial 15: Variable-length Wavetable
MSP Tutorial 20: MIDI Sampler Control MSP Tutorial 20: MIDI Sampler Control
MSP Tutorial 25: Using the FFT MSP Tutorial 25: Using the FFT