The SoundFile class is used to check the size, format, channels etc. when the sclang client needs this information about a SoundFile. Soundfile data can be read and modified. Soundfile data can also be read and written incrementally, so with properly designed code, there is no restriction on the file size.
In most cases you will wish to send commands to the server to get it to load SoundFiles directly into Buffers. You will not need to use this class for this. See the Buffer helpfile.
When reading a sound file, the headerFormat, sampleFormat, numChannels and numFrames variables will be set according to the file on disk.
When creating a new SoundFile, the format will be monophonic, 44.1 kHz, AIFF, floating-point by default. Users may override the defaults by passing the desired format strings to SoundFile: *openWrite, or by using SoundFile: -headerFormat, SoundFile: -sampleFormat, SoundFile: -numChannels and SoundFile: -sampleRate before calling SoundFile: -openWrite.
Creates a new SoundFile instance.
Try to open the audio file at the given path.
| pathName |
Full path to the sound file. Use String: -standardizePath to resolve home-folder shortcuts such as |
A new SoundFile instance if successful, or nil if file open failed. User code should check for nil before doing anything with the SoundFile object.
Try to create an audio file at the given path. Note that there is no numFrames argument: the number of frames is counted after writing data into the file.
| pathName |
Full path to the sound file. Use String: -standardizePath to resolve home-folder shortcuts such as |
| headerFormat |
A string for the sound file format. Valid strings are listed at SoundFile: -headerFormat. If not given, the default |
| sampleFormat |
A string for the sample format. Valid strings are listed at SoundFile: -sampleFormat. If not given, the default |
| numChannels |
An integer number of channels (1 by default). |
| sampleRate |
An integer sample rate (44100 by default). |
A new SoundFile instance if successful, or nil if file open failed. User code should check for nil before doing anything with the SoundFile object.
Returns an Array of SoundFile objects whose paths match the pattern. (The associated files are closed. These objects can be used to cue playback buffers)
Reads the data of a SoundFile, evaluates the function (passing the file as argument) and closes it again.
Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
Using this class method (SoundFile.normalize) will automatically open the source file for you. You may also -openRead the SoundFile yourself and call -normalize on it. In that case, the source path is omitted because the file is already open.
See instance method -normalize for more information.
Allocates a buffer and cues the SoundFile for playback. Returns an event parameterized to play that buffer. (See NodeEvent for a description of how events can be used to control running synths.) The event responds to play, stop, pause, resume, keeping the buffer open. The buffer is closed when the event is sent a close message.
| ev |
An Event can passed as an argument allowing playback to be customized using the following keys:
Where bufferSize, firstFrame, lastFrame are for buffer and playback position, and out, server, group, addAction, amp are synth parameters. Here is the default SynthDef used for stereo files: The control sustainTime determines playback duration based on the firstFrame and lastFrame. The control gate allows early termination of the playback | ||||||||||||||||||||||||||||||
| playNow |
This is a Boolean that determines whether the file is to be played immediately after cueing. | ||||||||||||||||||||||||||||||
| closeWhenDone |
A flag to indicate whether the buffer will be closed after playback is finished. Default is False. |
Read the header of a file. Answers a Boolean whether the read was successful. Sets the -numFrames, -numChannels and -sampleRate. Does not set the -headerFormat and -sampleFormat.
| pathName |
a String specifying the path name of the file to read. |
Reads the sample data of the file into the raw array you supply. You must have already called -openRead.
When you reach EOF, the array's size will be 0. Checking the array size is an effective termination condition when looping through a sound file. See the method -channelPeaks for example.
| rawArray |
The raw array must be a FloatArray. Regardless of the sample format of the file, the array will be populated with floating point values. For integer formats, the floats will all be in the range -1..1. The size of the FloatArray determines the maximum number of single samples (not sample frames) that will be read. If there are not enough samples left in the file, the size of the array after the readData call will be less than the original size. |
Write the header of a file. Answers a Boolean whether the write was successful.
| pathName |
a String specifying the path name of the file to write. |
Writes the rawArray to the sample data of the file. You must have already called -openWrite.
| rawArray |
The raw array must be a FloatArray or Signal, with all values between -1 and 1 to avoid clipping during playback. |
answers if the file is open.
closes the file.
the duration in seconds of the file.
Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
The normalizer may be used to convert a soundfile from one sample format to another (e.g., to take a floating point soundfile produced by SuperCollider and produce an int16 or int24 soundfile suitable for use in other applications).
threaded:true to get feedback but it will take slightly longer to complete.| outPath |
a path to the destination file. |
| newHeaderFormat |
the desired header format of the new file; if not specified, the header format of the source file will be used. |
| newSampleFormat |
the desired sample format of the new file; if not specified, the sample format of the source file will be used. |
| startFrame |
an index to the sample frame to start normalizing. |
| numFrames |
the number of sample frames to copy into the destination file (default nil, or entire soundfile). |
| maxAmp |
the desired maximum amplitude. Provide a floating point number or, if desired, an array to specify a different level for each channel. |
| linkChannels |
a Boolean specifying whether all channels should be scaled by the same amount. The default is true, meaning that the peak calculation will be based on the largest sample in any channel. If false, each channel's peak will be calculated independently and all channels will be scaled to maxAmp (this would alter the relative loudness of each channel). |
| chunkSize |
how many samples to read at once (default is 4194304, or 16 MB). |
| threaded |
if true, the normalization runs in a routine so that SC can respond (intermittently) while processing. Prevents macOS beachballing. |
Get the pathname of the file. This variable is set via the -openRead or -openWrite calls.
This is a String indicating the header format which was read by openRead and will be written by openWrite. In order to write a file with a certain header format you set this variable.
| header | description | filename extensions | notes |
| "AIFF" | Apple/SGI AIFF format | .aif, .aiff | |
| "WAV","WAVE", "RIFF" | Microsoft WAV format | .wav, .wave | |
| "Sun", "NeXT" | Sun/NeXT AU format | .au, .snd | |
| "SD2" | Sound Designer 2 | .sd2 | |
| "IRCAM" | Berkeley/IRCAM/CARL | .sf | |
| "raw" | no header = raw data | ||
| "MAT4" | Matlab (tm) V4.2 / GNU Octave 2.0 | .mat4 | |
| "MAT5" | Matlab (tm) V5.0 / GNU Octave 2.1 | .mat5 | |
| "PAF" | Ensoniq PARIS file format | .paf | |
| "SVX" | Amiga IFF / SVX8 / SV16 format | .svx | |
| "NIST" | Sphere NIST format | .nist, .sph | |
| "VOC" | VOC files | .voc | |
| "W64" | Sonic Foundry's 64 bit RIFF/WAV | .w64 | supports files larger than 4GB |
| "PVF" | Portable Voice Format | .pvf | |
| "XI" | Fasttracker 2 Extended Instrument | .xm | |
| "HTK" | HMM Tool Kit format | .htk | |
| "SDS" | Midi Sample Dump Standard | .sds | |
| "AVR" | Audio Visual Research | .avr | |
| "FLAC" | FLAC lossless file format | .flac | |
| "CAF" | Core Audio File format | .caf | supports files larger than 4GB |
| "RF64" | RF64 WAV format | .wav | supports files larger than 4GB |
| "OGG" | Xiph OGG container | .ogg | use .ogg extension for the "vorbis" format (see below) |
| "MPEG" | MPEG container | .mp1, .mp2, .mp3 | file extension depends on the format (see below) |
Additionally, a huge number of other formats are supported read only. Please note that WAV file support is limited to 4GB. For output of multiple channels or very long recordings we suggest to use RF64, W64, or CAF (on macOS).
A String indicating the format of the sample data which was read by -openRead and will be written by -openWrite. libsndfile determines which header formats support which sample formats. This information is detailed at http://www.mega-nerd.com/libsndfile . The possible sample formats are:
| format | notes | supported headers (partial list) |
| "int8", "int16", "int24", "int32" | integer formats | "AIFF", "WAV", "RF64", "W64", "CAF", "FLAC" |
| "float" | floating-point format (won't clip above 0dB) | "AIFF", "WAV", "RF64", "W64", "CAF" |
| "mulaw", "alaw" | U-law and A-law encoding | "WAV", "W64" |
| "vorbis" | "Vorbis" compressed format | "OGG" |
| "mp1", "mp2", "mp3" | MPEG Layer I, II, and III compressed formats | "MPEG" (see NOTE below) |
Not all header formats support all sample formats.
MPEG formats requires libsndfile library that supports it. This library is included in SuperCollider's macOS and Windows release builds version 3.13 and up. However, on platforms where system installation of libsndfile is used (e.g. Linux), or when building SC locally, MPEG support requires libsndfile version 1.1.0 or higher and that the library was built with the MPEG functionality enabled.Currently there's no way to control the quality (bitrate) when writing OGG vorbis and MPEG files - the default bitrate set in libsndfile is used.
The number of sample frames in the file.
The number of channels in the file.
The sample rate of the file.