A newer version of Max is available. Click here to access the latest version of this document.

sfplay~

Play audio file from disk

Description

sfplay~ plays AIFF, NeXT/SUN(.au), WAVE, and Raw Data files of 1-32 tracks from disk. To play a file, you send sfplay~ the open message, then send it a 1 to start and a 0 to stop. open takes an argument to specify a filename in the search path. You can also create additional cues with the preload message. These can reference other files, all of which are simultaneously accessible. The open message sets the "current" file: the one that plays back from the beginning when 1 is sent and is used as the default for the preload message. sfplay~ can also connect to the cues defined in an sflist~ object. Since multiple sfplay~ objects can reference the same sflist~, this allows you to store a global list of cues.

Arguments

Name Type Opt Description
sflist-object-name symbol opt If the first argument is a symbol, it names an sflist~ that the sfplay~ object will use for playing cues. If no symbol argument is given, sfplay~ plays its own internally defined cues.
number-of-output-channels int opt Sets the number of output channels, which determines the number of signal outlets that the sfplay~ object will have. The maximum number of channels is 28. The default is 1. If the audio file being played has more output channels than the sfplay~ object, higher-numbered channels will not be played. If the audio file has fewer channels, the signals coming from the extra outlets of sfplay~ will be 0.

An additional optional argument can be used to specify the disk buffer size in samples. If this argument has a value of 0, the default disk buffer size will be used.

An additional optional argument can be used to create outlets to the sfplay~ object which display positioning information. Specifying a final argument of 1 creates a single outlet to the left of the rightmost "bang on finish or halt" outlet which outputs a signal value which corresponds to the current playback position in milliseconds.

Like all MSP audio signals, this playback position is a 32-bit single precision floating-point signal. If greater precision is desired, specifying a final argument of 2 creates a second outlet which outputs a second 32-bit single precision floating-point signal containing the single precision roundoff error. Together these signals provide near double precision floating-point accuracy. (Note: after several minutes a single precision floating-point value is no longer sample accurate) Using the two signals together with objects such as the unsupported Max/ MSP high resolution signal processing objects like hr.+~ , one may perform sample-accurate calculations based on file position
object-reference-name symbol opt If the last argument is a symbol, it specifies a name by which other objects can refer to the sfplay~ object to access its contents.

Messages

int start/stop-playback-of-cue-number [int]
 In left inlet: If a file has been opened with the open message, 1 begins playback (of the most recently opened file), and 0 stops playback. Numbers greater than 1 trigger cues that have been defined with the preload message, or that were defined based on the saved state of the sfplay~ object. When the file is played, the audio data in the file is sent out the signal outlets according to the number of channels the object has. When the cue is completed or sfplay~ is stopped with a 0, a bang is sent out the right outlet. If the object is currently assigned to an sflist~ object (using the set message or with a typed-in argument), an int will trigger cues stored in the sflist~ object rather than inside the sfplay~. To reset sfplay~ to use its own cues, send it the set message with no arguments.
float playback-rate [float]
 In right inlet: Defines the playback rate of an audio file. A value of 1.0 plays the audio file at normal speed. A playback rate of -1 plays the audio file backwards at normal speed. A playback rate of 2 plays the audio file at twice the normal speed. A playback rate of .5 plays the audio file at half the normal speed.
list cues [list]
 In left inlet: Gives a set of cues for sfplay~ to play, one after the other. The maximum number of cues is in a list is 128. Cue numbers (set using the preload message) can be any integer greater than or equal to 2.If a cue number in a list has not been defined, it is skipped and the next cue, if any, is tried. If the object is currently assigned to an sflist~ object, a list uses cues stored in the sflist~ object. Otherwise, cues stored inside the sfplay~ object are used.
anything sflist-object-name and cue-number [list]
 In left inlet: If the name of an sflist~ object is sent to sfplay~, followed by a number, the numbered cue from the sflist~ is played if it exists.
(mouse) Double-clicking on buffer~ opens a display window where you can view the contents of the buffer~. object that the sfplay~ object references.
(drag) When an audio file is dragged from the Max 5 File Browser to an sfplay~ object, the file will be loaded.
clear cue-numbers [list]
 In left inlet: The word clear with no arguments clears all defined cues. After a clear message is received, only the number 1 will play anything (assuming there's an open file). The word clear followed by one or more cue numbers removes them from the sfplay~ object's cue list.
fclose filename [symbol]
 In left inlet: The word fclose, followed by the name of an open file, closes the file and removes all cues associated with it. The word fclose by itself closes the current file.
embed saving-preference-flag (0 or nonzero) [int]
 In left inlet: The message embed, followed by any non-zero integer, causes sfplay~ to save all of its defined cues and the name of the current open file when the patcher file is saved. The message embed0 keeps sfplay~ from saving this information when the patcher is saved. By default, the current file name and the cue information is not saved in sfplay~ when the patcher is saved. If an sfplay~ object is saved with stored cues, they will all be preloaded when the patcher containing the object is loaded.
loop looping-flag (0 or 1) [int]
 In left inlet: The word loop, followed by 1, turns on looping. loop 0 turns off looping. By default, looping is off.
loopone cue-number [int]
 In left inlet: The word loopone, followed by a cue-number, will set only the cue specified to loop.
offset sample-start-offset (bytes) [int]
 In left inlet: The word offset, followed by a number, specifies the sample start offset in bytes. The default value is 0. This value useful for aligning samples and avoiding playback of header information.
open filename [symbol]
 In left inlet: followed by the name of an AIFF, WAV, NeXT/Sun, or raw format audio file or CD-audio track, opens the file for playback and makes it the current file. The word open, followed by a filename, opens the file if it exists in Max's search path. Without a filename, open brings up a standard open file dialog allowing you to choose a file. When a file is opened, its beginning is read into memory, and until another file is opened, you can play the file from the beginning by sending sfplay~ the message 1. When the open message is received, the previous current file, if any, remains open and can be referred to by name when defining a cue with the preload message. If any cues were defined that used the previous current file, they are still valid even if the file is no longer current.
openraw filename [symbol]
 In left inlet: The openraw message functions exactly like open, but allows you to open any type of file for playback and make it the current file. The openraw message assumes that the file being opened is a 16-bit stereo file sampled at a rate of 44100 Hz, and assumes that there is no header information to ignore (i.e., an offset of 0). The file types can be explicitly specified using the samptype, offset, srate, and srchans messages.
name object-reference-name [symbol]
 The word name, followed by a symbol, changes the name by which other objects such as sfinfo~ can refer to the sfplay~ object. Objects that were referring to the sfplay~ under its old name lose their connection to it. Every sfplay~ object should be given a unique name; if you give an sfplay~ object a name that already belongs to another sfplay~ object, that name will no longer be associated with the sfplay~ object that first had it.
modout modulo-output-flag (0 or 1) [int]
 In left inlet: The word modout, followed by 1, turns on modulo output. If the number of channels in a audio file is less than the number of outputs for the sfplay~ object, the sfplay~ object will reduplicate the audio file's channels across all of sfplay~ object's outputs (rather than outputting zero) if modulo output is enabled. For example, a mono audio file loaded into an sfplay~ object with two outputs will be played with the mono channel sent out both outputs of the object if modulo output is enabled. Similarly a stereo audio file will be played on an sfplay~ object with four outlets with the left channel played on outputs 1 and 3, while the right will be played on outputs 2 and 4. The message modout 0 disables this feature.
pause In left inlet: The pause message causes the audio file playback to pause at its current playback position. Playback can be restarted with the resume message.
preload cue-number filename start-time end-time directional-flag playback-speed [list]
 In left inlet: Defines a cue - an integer greater than or equal to 2 - to refer to a specific region of a file. When that cue number is subsequently received, sfplay~ plays that region of that file. Cue number 1 is always the beginning of the current file - the file last opened with the open message - and cannot be modified with the preload message.

There are a number of forms for the preload message. The word preload is followed by an obligatory cue number between 2 and 32767. If the cue number is followed by a filename - a file that is currently open or one that is in Max's search path - that cue number will henceforth play the specified file. Note that a file need not have been explicitly opened with the open message in order to be used in a cue. If no filename is specified, the currently open file is used.

After the optional filename, an optional start time in milliseconds can be specified. If no start time is specified, the beginning of the file is used as the cue start point. After the start time, an end time in milliseconds can be specified. If no end time is specified, or the end time is 0, the cue will play to the end of the file. If the end time is less than the start time, the cue is defined but will not play. Eventually it may be possible to define cues that play in reverse.

After the start and/or end time arguments, a optional directional buffer flag is used to enable reverse playback of stored cues. Setting this flag to 1 enables reverse cue playback. The default setting is 0 (bidirectional buffering off).

A final optional argument is used to set the playback speed. A float value sets the sfplay~ object's playback speed relative to the object's global playback speed -- set set by either the speed message or the sfplay~ object's right inlet. The default value is 1.

Each cue that is defined requires approximately 40K of memory per sfplay~ channel at the default buffer size (40320), with bidirectional buffering turned off. With bidirectional buffering turned on, the amount of memory per cue is doubled.

The preload message is always deferred to low priority. The pause, resume, and int messages are not. If you have problems with these messages arriving before you want them to in overdrive mode (i.e., before you've preloaded the most recent cue), use the defer object.
print In left inlet: Prints information about the state of the object, plus a list of all the currently defined cues.
resume In left inlet: If playback was paused, playback resumes from the paused point in the file.
samptype sample-type [symbol]
bit-depth [int]
 		In left inlet: The word samptype, followed by a symbol, specifies the sample type to use when interpreting the audio file's sample data (thus overriding the audio file's actual sample type). This is sometimes called "header munging." When reading files in response to the openraw message, the assumed sample type is 16-bit integer. Modifications using samptype make no changes to the file on disk.

The following types of sample data are supported:

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
seek start-time (milliseconds) [float]
end-time (milliseconds) [float]
 		In left inlet: The word seek, followed by a start time in milliseconds, moves to the specified position in the current file and begins playing. After the start time, an optional end time can be specified, which will set a point for playback to stop. The seek message is intended to allow you to preview and adjust the start and end points of a cue.

NOTE: The seek message is always deferred to low priority. If you have problems with these messages arriving before you want them to in overdrive mode (i.e. before you've finished seeking to a new location), then use the defer object.
set sflist-object-name [symbol]
 In left inlet: The message set, followed by a name of an sflist~ object, will cause sfplay~ to play cues stored in the sflist~ when it receives an int or list. The message set with no arguments resets sfplay~ to use its own internally defined cues when receiving an int or list.
signal In left inlet: An input signal may be used for the sample-accurate triggering of prestored cues. When a signal value is received in the left inlet, the integer portion of the signal value is monitored. When the integer portion of the input signal changes to a value equal to the index of a prestored cue, that cue is triggered. Negative values are ignored.
speed playback-rate [float]
 In left inlet: The word speed, followed by a number, sets an overall multiplier on the playback rate of all cues played by the object. A value of 1.0 (the default) plays all cues at normal speed. A playback rate of -1 plays all cues backward at normal speed. A playback rate of 2 plays the cues at twice their defined speed. A playback rate of 0.5 plays cues at half their defined speed. For example, if a cue has a playback rate of 2, and the speed is set to 3, the cue will play back at 6 times the normal speed.
srate sampling-rate (Hz) [float]
 In left inlet: The word srate, followed by a number, specifies the sampling rate (Hertz) at which to interpret the audio file's sample data (thus overriding the audio file's actual sampling rate). This is sometimes called "header munging." When reading files in response to the openraw message, the assumed sampling rate is 44,100 Hz. Modifications using srate make no changes to the file on disk.
srcchans number-of-channels [int]
 In left inlet: The word srcchans, followed by a number, specifies the number of channels in which to interpret the audio file's sample data (thus overriding the audio file's actual number of channels). This is sometimes called "header munging." When reading files in response to the openraw message, the assumed number of channels is 2. Modifications using srcchans make no changes to the file on disk.

Attributes

Name Type g/s Description
audiofile symbol Specifies the name/pathname of an audio file to be loaded by the sfplay~ object.

Information for box attributes common to all objects

Output

bang: Out right outlet: When the file is done playing, or when playback is stopped with a 0 message, a bang is sent out.
signal: There is one signal outlet for each of the sfplay~ object's specified output channels (set by or as an argument to the sfplay~ object) that sends out the audio data of the corresponding channel of the audio file when a cue number is received in the inlet. (The left outlet plays channel 1, and so on.)

If the optional output position argument is specified, there will be one or two signal outputs following the channel outputs whose signal outputs display positioning information. If the argument is 1, a single outlet to the left of the rightmost "bang on finish or halt" outputs a signal containing the current playback position in milliseconds. Specifying a final argument of 2 creates a second outlet which outputs a signal containing the playback position single precision roundoff error in milliseconds (see Arguments for a more detailed description of the sfplay~ object's position outlets).

Examples

Audio files can be played from the hard disk without loading the whole file into memory

See Also

Name Description
buffer~ Store audio samples
groove~ Variable-rate looping sample playback
play~ Position-based sample playback
sfinfo~ Report audio file information
sflist~ Store audio file cues
sfrecord~ Record to audio file on disk
MSP Tutorial 16: Record and Play Audio Files MSP Tutorial 16: Record and Play Audio Files