Package MSP

buffer~

Store audio samples

Description

Use the buffer~ object as a buffer of memory in which samples are stored to be saved, edited, or referenced.

Discussion

The buffer~ object is used in conjunction with many different objects, including play~ / groove~ (plays the buffer), record~ (records into the buffer), info~ (reports information about the buffer), peek~ (writes into/reads from the buffer like the table object), lookup~ (uses the buffer for waveshaping), cycle~ (specifies a 512-point waveform), and wave~ (specifies a waveform).

Arguments

name[symbol]
optional

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]
optional

After the buffer~ object's name, you may type the name of an audio file to load when the buffer~ is created.

duration[number]ms
optional

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.

channels[int]
optional

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.) buffer~ may have an arbitrary number of channels, only limited by the amount of RAM available. By default, buffer~ has one channel.

Attributes

dither[int]: 0

Enable triangular dithering when writing PCM (integer) files. Possible values:

0 = 'Off' ( Apply no dithering when writing PCM files )
1 = 'Dither' ( Apply triangular dither (TPDF) when writing PCM files )
2 = 'Dither + Noise Shaping' ( Apply triangular dither with noise shaping (HP-TPDF) when writing PCM files )

filetype[symbol]

The audio file format used by the buffer~ object. The default file type is AIFF. Possible values:

'aiff' ( Apple Interchange File Format (default) )
'wave' ( WAVE )
'raw' ( raw )
'au' ( NeXT/Sun )

format[symbol]

The bit depth or sample type of the buffer on disk

For backward compatibility, the following numeric valus can be used to set format, in addition to the symbolic names below:
8 - 8-bit integer
16 - 16-bit integer
24 - 24-bit integer
32 - 32-bit integer Possible values:

'int8' ( 8-bit integer )
'int16' ( 16-bit integer (default) )
'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 )

quantization[int]: 0

Select the quantization rule when writing PCM (integer) files. Possible values:

0 = 'Round' ( Round when quantizing to integer values. )
1 = 'Floor' ( Floor when quantizing to integer values. )

samps[int]

The length of the buffer~ expressed in samples.

size[float]

The length of the buffer~ expressed in milliseconds.

Common Box Attributes

Below is a list of attributes shared by all objects. If you want to change one of these attributes for an object based on the object box, you need to place the word sendbox in front of the attribute name, or use the object's Inspector.

annotation[symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background[int]: 0

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color[4 floats]

Sets the color for the object box outline.

fontface[int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname[symbol]

Sets the object's font.

fontsize[float]

Sets the object's font size (in points). Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden[int]: 0

Toggles whether an object is hidden when the patcher is locked.

hint[symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick[int]: 0

Toggles whether an object ignores mouse clicks in a locked patcher.

jspainterfile[symbol]

JS Painter File

patching_rect[4 floats]: 0. 0. 100. 0.

Sets the position and size of the object in the patcher window.

position[2 floats]
write-only

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation[int]: 0

Sets whether an object belongs to the patcher's presentation.

presentation_rect[4 floats]: 0. 0. 0. 0.

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect[4 floats]
write-only

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size[2 floats]
write-only

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor[4 floats]

Sets the color for the object's text in RGBA format.

textjustification[int]

Sets the justification for the object's text. Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname[symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

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 File Browser to a buffer~ object, the file will be loaded.

apply

The word apply , followed by list consisting of one to three symbols or numbers, will apply a windowing function to the current contents of a buffer~.

The word apply , followed by a single symbol that designates a windowing function, will apply that function to the current contents of the buffer~. Supported functions include triangle, hamming, hanning, blackman, welch, and kaiser. An additional second symbol argument of half (e.g. apply blackman half ) will calculate the function and apply only the second half to the whole buffer~.

Note: The kaiser function requires a second floating point argument that specifies the beta parameter and precedes an optional half argument (e.g. apply kaiser 4.5 half ).

The word apply , followed by the word gain and a floating-point number that specifies a gain value, will scale every sample by the gain coefficient. offset and a floating-point number that specifies a constant value that will be added to every sample in the buffer~.

The word apply , followed by the word getdeltas , will replace every sample value with the a new value representing the difference from the previous sample.

Arguments:
  • function-and-parameters [list]

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

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.

Arguments:
  • start and end times [list]

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

duplicate

The word duplicate , followed by a symbol that specifies the name of a buffer~, will import the contents of the named buffer.

Arguments:
  • buffer-name [symbol]

enumerate

Posts information in the Max Console 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).

fill

The word fill , followed by list consisting of one to three symbols or numbers, specifies how the contents of a buffer~ object will be filled.

The word fill , followed by a single floating-point number, will set every sample in the buffer~ to that value.

The word fill , followed by a symbol that designates a function, will fill the buffer~ with one cycle of that function. Supported functions include sin (sine), cos, (cosine), and sinc. An optional second argument (e.g. fill sin 2 ) can be used to define the number of cycles of the function used to fill the buffer~. An additional optional third argument defines a rational number of cycles with which to fill the buffer~ (e.g. fill cos 1 4 will fill a buffer~ with a quarter cycle of the cosine function).

Note: the sinc function requires two int arguments that specify the number of zero crossings and an additional flag that toggles starting the function at zero (e.g. fill sinc 4 1 ).

Arguments:
  • constant/function [list]

import

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 second argument - a floating point value that specifies the duration of sound, in milliseconds, to be read into buffer~. This duration overrides the current size of the object's sample memory. If the duration is specified by a negative value, buffer~ reads in the entire file and resizes its sample memory and adjusts the number of channels in the file accordingly.
The duration may be followed by a third argument that specifies the number of channels to be read in. If the number of channels is not specified (i.e., if the message includes only offset and duration information), buffer~ reads in the number of channels indicated in the header of the audio file.
If only two arguments are specified, buffer~ imports the number of channels indicated in the header of the audio file. If three arguments are specified, buffer~ imports the number of channels specified by the third argument. If the third argument is 0, buffer~ imports the number of channels indicated in the header of the audio file.

Arguments:
  • filename [list]

importreplace

The word importresize , 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 importreplace is functionally identical to the import message, except that imports are performed with automatic duration and channel resizing enabled by default. Unless otherwise specified, the duration and channel count of the imported file will be used to resize the buffer's internal sample memory.

Arguments:
  • filename [list]

name

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.

Arguments:
  • buffer-name [symbol]

normalize

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.

Arguments:
  • normalization_factor [list]

open

Opens the buffer~ sample display window or brings it to the front if it is already open.

printmodtime

Posts information in the Max Console about when the buffer~ was last modified (i.e. written into, or modified in attributes).

read

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 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 starting time may be followed by a second argument - a floating point value that specifies the duration of sound, in milliseconds, to be read into buffer~. This duration does not override the current size of the object's sample memory. It clears the current buffer~ data, then fills the requested amount at the beginning of the buffer~. However, if the duration is specified by a negative value, buffer~ reads in the entire file and resizes its sample memory.
The duration may be followed by a third integer argument that specifies the number of channels to be read in.
If only two arguments are specified, buffer~ reads in only the number of channels that the buffer~ currently has. If the audio file has more channels than the buffer~ currently has, the audio from all channels will be summed. If three arguments are specified, buffer~ reads the number of channels specified by the third argument. If the third argument is 0, buffer~ reads in the number of channels indicated in the header of the audio file.

Arguments:
  • filename [list]

readagain

Reads sound data from the most recently loaded file (specified in a previous read or replace message).

Arguments:
  • filename [list]

readraw

Reads the contents of an arbitrary file on disk, interpreting the data as audio into the buffer~ object. The arguments determine how buffer~ interprets the data in the file.

The optional arguments are:

  • filename : a filename or filepath to read into buffer~ (default = open file dialog)
  • sample-rate : the sample-rate of the data to be read (default = 44100. )
  • channels : the number of channels of the data to be read (default = 1 )
  • format : the format to read; one of int8 , int16 , int24 , int32 or float32 (default = float32 )
  • byte-offset : the byte offset in the file where reading should begin (default = 0 )
  • duration-in-frames : the total number of samples to read per channel, a value of 0 reads from byte-offset to the end of the file (default = 0 )
  • little-endian-flag : whether to read samples using big-endian ( 0 ) or little-endian ( 0 ) byte order (default = 0 )
Arguments:
  • filename [symbol]
  • sample-rate [float]
  • channels [int]
  • format [symbol]
  • byte-offset [int]
  • duration-in-frames [int]
  • little-endian-flag [int]

replace

The replace message is equivalent to the read message with a negative duration argument.

Arguments:
  • filename [list]

samptype

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

Arguments:
  • sample-type [symbol]

set

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.

Arguments:
  • buffer-name [symbol]

setsize
7.0.0

Sets the length of the sample memory of the buffer in milliseconds. Optional second argument sets the number of channels in the buffer. 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.

Arguments:
  • buffer-size-in-milliseconds [float]
  • number-of-channels [int]

sizeinsamps

The word sizeinsamps , 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.

Arguments:
  • buffer-duration [int]
  • number-of-channels [int]

sr

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.

Arguments:
  • sampling-rate (samples-per-second) [float]

wclose

Closes the buffer~ sample display window if it is open.

write

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 filetype attribute, or the file type of the most recently opened audio file. By default, buffer~ saves in AIFF format.

Arguments:
  • filename [symbol]

writeaiff

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.

Arguments:
  • filename [symbol]

writeflac

Saves the contents of the buffer~ into a FLAC file. A standard Save As dialog is opened for naming the file unless the word writeflac is followed by a symbol, in which case the file is saved in the current default folder, using the symbol as the filename.

Arguments:
  • filename [symbol]

writeraw

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.

The optional arguments are:

  • filename : a filename or filepath to save the raw file (default = open save dialog)
  • format : the format to write; one of int8 , int16 , int24 , int32 or float32 (default = float32 )
  • duration-in-frames : the total number of samples to write per channel (number of channels is determined by the contents of the buffer~ object. A value of 0 writes the entire buffer to disk (default = 0 )
  • little-endian-flag : whether to write samples using big-endian ( 0 ) or little-endian ( 1 ) byte order (default = 0 )
Arguments:
  • filename [symbol]
  • format [symbol]
  • duration-in-frames [int]
  • little-endian-flag [int]

writewave

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.

Arguments:
  • filename [symbol]

Output

bang

Right outlet: A bang is sent out the right outlet of buffer~ when the file read or file write operation is completed.

float

Left outlet: 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 left outlet.

See Also

Name Description
2d.wave~ Two-dimensional wavetable
buffir~ buffer-based FIR filter
cycle~ Sinusoidal 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
polybuffer~ Manage multiple buffer~ objects
record~ Record sound into a buffer
sfplay~ Play audio file from disk
sfrecord~ Record to audio file on disk
stretch~ Ztx-based pitch/time modification of an audio buffer
wave~ Variable size wavetable