HelpSource/Classes/SoundFile.schelp

   1 class:: SoundFile
   2 summary:: sclang soundfile data
   3 related:: Classes/File, Classes/Buffer
   4 categories:: Files
   5
   6 description::
   7 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.
   8
   9 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 link::Classes/Buffer:: helpfile.
  10
  11 code::
  12 (
  13 f = SoundFile.new;
  14 f.openRead(Help.dir +/+ "sounds/a11wlk01.wav");
  15 f.inspect;
  16 f.close;
  17 )
  18 ::
  19
  20 ClassMethods::
  21
  22 method::new
  23 Creates a new SoundFile instance.
  24
  25 method::collect
  26 Returns an link::Classes/Array:: of SoundFile objects whose paths match the pattern. (The associated files are closed. These objects can be used to cue playback buffers)
  27 code::
  28 SoundFile.collect("sounds/*").do { |f| f.path.postln };
  29 ::
  30
  31 method::use
  32 Reads the data of a SoundFile, evaluates the function (passing the file as argument) and closes it again.
  33 code::
  34 SoundFile.use(Help.dir +/+ "sounds/a11wlk01.wav", { |f| f.inspect });
  35 ::
  36
  37 method::normalize
  38 Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
  39
  40 Using this class method (SoundFile.normalize) will automatically open the source file for you. You may also link::#-openRead:: the SoundFile yourself and call link::#-normalize:: on it. In that case, the source path is omitted because the file is already open.
  41
  42 See instance method link::#-normalize:: for more information.
  43
  44 InstanceMethods::
  45
  46 private::prOpenRead, prOpenWrite
  47
  48 subsection::Playback
  49
  50 method::cue
  51 Allocates a buffer and cues the SoundFile for playback. Returns an event parameterized to play that buffer. (See link::Reference/NodeEvent:: for a description of how events can be used to control running synths.) The event responds to strong::play::, strong::stop::, strong::pause::, strong::resume::, keeping both the file and buffer open. The file is closed and the buffer is freed when the event is sent a strong::close:: message.
  52
  53 argument::ev
  54 An link::Classes/Event:: can passed as an argument allowing playback to be customized using the following keys:
  55 table::
  56 ## strong::key:: || strong::default value:: || strong::what it does::
  57 ## bufferSize || 65536 ||
  58 ## firstFrame || 0 || first frame to play
  59 ## lastFrame || nil || last frame to play (nil plays to end of file)
  60 ## out: || 0 || sets output bus
  61 ## server: || Server.default || which server
  62 ## group: || 1 || what target
  63 ## addAction: || 0 || head/tail/before/after
  64 ## amp: || 1 || amplitude
  65 ## instrument: || nil || if nil SoundFile:cue determines the SynthDef (one of diskIn1, diskIn2, ...diskIn16)
  66 ::
  67 Where strong::bufferSize::, strong::firstFrame::, strong::lastFrame:: are for buffer and playback position, and strong::out::, strong::server::, strong::group::, strong::addAction::, strong::amp:: are synth parameters. Here is the default SynthDef used for stereo files:
  68 code::
  69 SynthDef(\diskIn2, { | bufnum, out, gate = 1, sustain, amp = 1, ar = 0, dr = 0.01 |
  70         Out.ar(out, DiskIn.ar(2, bufnum)
  71         * Linen.kr(gate, ar, 1, dr, 2)
  72         * EnvGen.kr(Env.linen(0, sustain - ar - dr max: 0 ,dr),1, doneAction: 2) * amp)
  73 });
  74 ::
  75 The control strong::sustain:: determines playback duration based on the firstFrame and lastFrame. The control strong::gate:: allows early termination of the playback
  76
  77 argument::playNow
  78 This is a link::Classes/Boolean:: that determines whether the file is to be played immediately after cueing.
  79 code::
  80 f = SoundFile.collect("sounds/*");
  81 e = f[1].cue;
  82
  83 e = f[1].cue( (addAction: 2, group: 1) );       // synth will play ahead of the default group
  84 ::
  85
  86 subsection::Read/Write
  87
  88 method::openRead
  89 Read the header of a file. Answers a link::Classes/Boolean:: whether the read was successful. Sets the link::#-numFrames::, link::#-numChannels:: and link::#-sampleRate::. Does strong::not:: set the link::#-headerFormat:: and link::#-sampleFormat::.
  90
  91 argument::pathName
  92 a link::Classes/String:: specifying the path name of the file to read.
  93
  94 method::readData
  95 Reads the sample data of the file into the raw array you supply. You must have already called link::#-openRead::.
  96
  97 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 link::#-channelPeaks:: for example.
  98
  99 argument::rawArray
 100 The raw array must be a link::Classes/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.
 101
 102 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.
 103
 104 method::openWrite
 105 Write the header of a file. Answers a link::Classes/Boolean:: whether the write was successful.
 106
 107 argument::pathName
 108 a link::Classes/String:: specifying the path name of the file to write.
 109
 110 method::writeData
 111 Writes the rawArray to the sample data of the file. You must have already called link::#-openWrite::.
 112
 113 argument::rawArray
 114 The raw array must be a link::Classes/FloatArray:: or link::Classes/Signal::, with all values between -1 and 1 to avoid clipping during playback.
 115 code::
 116 (
 117 f = SoundFile.new.headerFormat_("AIFF").sampleFormat_("int16").numChannels_(1);
 118 f.openWrite("sounds/sfwrite.aiff");
 119         // sawtooth
 120 b = Signal.sineFill(100, (1..20).reciprocal);
 121         // write multiple cycles (441 * 100 = 1 sec worth)
 122 441.do({ f.writeData(b) });
 123 f.close;
 124 )
 125 ::
 126
 127 method::isOpen
 128 answers if the file is open.
 129
 130 method::close
 131 closes the file.
 132
 133 method::duration
 134 the duration in seconds of the file.
 135
 136 subsection::Normalizing
 137
 138 method::normalize
 139 Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
 140
 141 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).
 142
 143 note::
 144 While the normalizer is working, there is no feedback to the user. It will look like SuperCollider is hung, but it will eventually complete the operation. You can set code::threaded:true:: to get feedback but it will take slightly longer to complete.
 145 ::
 146
 147 argument::outPath
 148 a path to the destination file.
 149
 150 argument::newHeaderFormat
 151 the desired header format of the new file; if not specified, the header format of the source file will be used.
 152
 153 argument::newSampleFormat
 154 the desired sample format of the new file; if not specified, the sample format of the source file will be used.
 155
 156 argument::startFrame
 157 an index to the sample frame to start normalizing.
 158
 159 argument::numFrames
 160 the number of sample frames to copy into the destination file (default nil, or entire soundfile).
 161
 162 argument::maxAmp
 163 the desired maximum amplitude. Provide a floating point number or, if desired, an array to specify a different level for each channel.
 164
 165 argument::linkChannels
 166 a link::Classes/Boolean:: specifying whether all channels should be scaled by the same amount. The default is strong::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).
 167
 168 argument::chunkSize
 169 how many samples to read at once (default is 4194304, or 16 MB).
 170
 171 argument::threaded
 172 if true, the normalization runs in a routine so that SC can respond (intermittently) while processing. Prevents OSX beachballing.
 173
 174 subsection::Instance Variables
 175
 176 method::path
 177 Get the pathname of the file. This variable is set via the link::#-openRead:: or link::#-openWrite:: calls.
 178
 179 method::headerFormat
 180 This is a link::Classes/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.
 181
 182 definitionList::
 183 ## read/write header formats:
 184 table::
 185 ## "AIFF" || Apple/SGI AIFF format
 186 ## "WAV","WAVE", "RIFF" || Microsoft WAV format
 187 ## "Sun", "NeXT" || Sun/NeXT AU format
 188 ## "SD2" || Sound Designer 2
 189 ## "IRCAM" || Berkeley/IRCAM/CARL
 190 ## "raw" || no header = raw data
 191 ## "MAT4" || Matlab (tm) V4.2 / GNU Octave 2.0
 192 ## "MAT5" || Matlab (tm) V5.0 / GNU Octave 2.1
 193 ## "PAF" || Ensoniq PARIS file format
 194 ## "SVX" || Amiga IFF / SVX8 / SV16 format
 195 ## "NIST" || Sphere NIST format
 196 ## "VOC" || VOC files
 197 ## "W64" || Sonic Foundry's 64 bit RIFF/WAV
 198 ## "PVF" || Portable Voice Format
 199 ## "XI" || Fasttracker 2 Extended Instrument
 200 ## "HTK" || HMM Tool Kit format
 201 ## "SDS" || Midi Sample Dump Standard
 202 ## "AVR" || Audio Visual Research
 203 ## "FLAC" || FLAC lossless file format
 204 ## "CAF" || Core Audio File format
 205 ::
 206 ::
 207 Additionally, a huge number of other formats are supported read only.
 208
 209 method::sampleFormat
 210 A link::Classes/String:: indicating the format of the sample data which was read by link::#-openRead:: and will be written by link::#-openWrite::. libsndfile determines which header formats support which sample formats. This information is detailed at http://www.mega-nerd.com/libsndfile . The possible header formats are:
 211 definitionList::
 212 ## sample formats:
 213 table::
 214 ## "int8", "int16", "int24", "int32"
 215 ## "mulaw", "alaw",
 216 ## "float"
 217 ::
 218 ::
 219 Not all header formats support all sample formats.
 220
 221 method::numFrames
 222 The number of sample frames in the file.
 223
 224 method::numChannels
 225 The number of channels in the file.
 226
 227 method::sampleRate
 228 The sample rate of the file.