buffer~

Redraws the contents of the buffer~ object's waveform display window. You can open the display window by double-clicking on the buffer~ object.

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.

When an audio file is dragged from the Max File Browser to a buffer~ object, the file will be loaded.

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.

• function-and-parameters [list]
  

Erases the contents of buffer~.

Erases the contents of the buffer like the clear message, but performs the clear as a low-priority task.

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.

• start and end times [list]
  

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.

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

• buffer-name [symbol]
  

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

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

• constant/function [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 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.

• filename [list]
  

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.

• filename [list]
  

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.

• buffer-name [symbol]
  

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.

• normalization_factor [list]
  

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

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

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.

• filename [list]
  

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

• filename [list]
  

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 )

• filename [symbol]
  
• sample-rate [float]
  
• channels [int]
  
• format [symbol]
  
• byte-offset [int]
  
• duration-in-frames [int]
  
• little-endian-flag [int]
  

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

• filename [list]
  

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

• sample-type [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.

• buffer-name [symbol]
  

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.

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

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.

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

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.

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

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

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.

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

• filename [symbol]
  

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.

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

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 )

• filename [symbol]
  
• format [symbol]
  
• duration-in-frames [int]
  
• little-endian-flag [int]
  

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.

• filename [symbol]