zzkt/rsc3
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rsc3/doc-schelp/Help-3.12.2/Classes/SoundFile.html

294 lines
32 KiB
HTML
Raw Permalink Normal View History

docs (scm, schelp, scrbl & html)
2022-08-24 13:53:18 +00:00
<!doctype html><html lang='en'><head><title>SoundFile | SuperCollider 3.9.3 Help</title>
<link rel='stylesheet' href='./../scdoc.css' type='text/css' />
<link rel='stylesheet' href='./../frontend.css' type='text/css' />
<link rel='stylesheet' href='./../custom.css' type='text/css' />
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />
<script>
var helpRoot = './..';
var scdoc_title = 'SoundFile';
var scdoc_sc_version = '3.9.3';
</script>
<script src='./../scdoc.js' type='text/javascript'></script>
<script src='./../docmap.js' type='text/javascript'></script>
<script src='./../prettify.js' type='text/javascript'></script>
<script src='./../lang-sc.js' type='text/javascript'></script>
</head>
<body onload='fixTOC();prettyPrint()'>
<div id='toc'>
<div id='toctitle'>SoundFile:</div>
<span class='toc_search'>Filter: <input id='toc_search'></span><ul class='toc'><li class='toc1'><a href='#description'>Description</a></li>
<ul class='toc'></ul><li class='toc1'><a href='#classmethods'>Class methods</a></li>
<ul class='toc'><li class='toc3'><a href='#*new'>new</a> </li>
<li class='toc3'><a href='#*openRead'>openRead</a> </li>
<li class='toc3'><a href='#*openWrite'>openWrite</a> </li>
<li class='toc3'><a href='#*collect'>collect</a> </li>
<li class='toc3'><a href='#*use'>use</a> </li>
<li class='toc3'><a href='#*normalize'>normalize</a> </li>
<li class='toc2'><a href='#Inherited%20class%20methods'>Inherited class methods</a></li>
<li class='toc2'><a href='#Undocumented%20class%20methods'>Undocumented class methods</a></li>
<ul class='toc'><li class='toc3'><a href='#*closeAll'>closeAll</a> </li>
<li class='toc3'><a href='#*collectIntoBuffers'>collectIntoBuffers</a> </li>
<li class='toc3'><a href='#*groupNormalize'>groupNormalize</a> </li>
<li class='toc3'><a href='#*openFiles'>openFiles</a> </li>
</ul></ul><li class='toc1'><a href='#instancemethods'>Instance methods</a></li>
<ul class='toc'><li class='toc2'><a href='#Playback'>Playback</a></li>
<ul class='toc'><li class='toc3'><a href='#-cue'>cue</a> </li>
</ul><li class='toc2'><a href='#Read/Write'>Read/Write</a></li>
<ul class='toc'><li class='toc3'><a href='#-openRead'>openRead</a> </li>
<li class='toc3'><a href='#-readData'>readData</a> </li>
<li class='toc3'><a href='#-openWrite'>openWrite</a> </li>
<li class='toc3'><a href='#-writeData'>writeData</a> </li>
<li class='toc3'><a href='#-isOpen'>isOpen</a> </li>
<li class='toc3'><a href='#-close'>close</a> </li>
<li class='toc3'><a href='#-duration'>duration</a> </li>
</ul><li class='toc2'><a href='#Normalizing'>Normalizing</a></li>
<ul class='toc'><li class='toc3'><a href='#-normalize'>normalize</a> </li>
</ul><li class='toc2'><a href='#Instance%20Variables'>Instance Variables</a></li>
<ul class='toc'><li class='toc3'><a href='#-path'>path</a> </li>
<li class='toc3'><a href='#-headerFormat'>headerFormat</a> </li>
<li class='toc3'><a href='#-sampleFormat'>sampleFormat</a> </li>
<li class='toc3'><a href='#-numFrames'>numFrames</a> </li>
<li class='toc3'><a href='#-numChannels'>numChannels</a> </li>
<li class='toc3'><a href='#-sampleRate'>sampleRate</a> </li>
</ul><li class='toc2'><a href='#Inherited%20instance%20methods'>Inherited instance methods</a></li>
<li class='toc2'><a href='#Undocumented%20instance%20methods'>Undocumented instance methods</a></li>
<ul class='toc'><li class='toc3'><a href='#-asBuffer'>asBuffer</a> </li>
<li class='toc3'><a href='#-asEvent'>asEvent</a> </li>
<li class='toc3'><a href='#-channelPeaks'>channelPeaks</a> </li>
<li class='toc3'><a href='#-fileptr'>fileptr</a> </li>
<li class='toc3'><a href='#-info'>info</a> </li>
<li class='toc3'><a href='#-play'>play</a> </li>
<li class='toc3'><a href='#-readHeaderAsString'>readHeaderAsString</a> </li>
<li class='toc3'><a href='#-scaleAndWrite'>scaleAndWrite</a> </li>
<li class='toc3'><a href='#-seek'>seek</a> </li>
<li class='toc3'><a href='#-toCSV'>toCSV</a> </li>
</ul></ul><li class='toc1'><a href='#examples'>Examples</a></li>
<ul class='toc'></ul></ul></div><div class='contents'>
<div id='menubar'></div>
<div class='header'>
<div id='label'>
<span id='folder'>Classes</span>
| <span id='categories'><a href='./../Browse.html#Files'>Files</a></span>
</div><h1>SoundFile<span id='superclasses'> : <a href="../Classes/Object.html">Object</a></span>
</h1>
<div id='summary'>sclang soundfile data</div>
</div>
<div class='subheader'>
<div id='filename'>Source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Files/SoundFile.sc' title='/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Files/SoundFile.sc'>SoundFile.sc</a></div><div id='related'>See also: <a href="./../Classes/File.html">File</a>, <a href="./../Classes/Buffer.html">Buffer</a></div>
</div>
<h2><a class='anchor' name='description'>Description</a></h2>
<p>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.
<p>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 <a href="./../Classes/Buffer.html">Buffer</a> helpfile.<pre class='code prettyprint lang-sc'>(
f = SoundFile.new;
f.openRead(Platform.resourceDir +/+ "sounds/a11wlk01.wav");
f.inspect;
f.close;
)</pre>
<p>When reading a sound file, the headerFormat, sampleFormat, numChannels and numFrames variables will be set according to the file on disk.
<p>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 <a href="./../Classes/SoundFile.html#*openWrite">SoundFile: *openWrite</a>, or by using <a href="./../Classes/SoundFile.html#-headerFormat">SoundFile: -headerFormat</a>, <a href="./../Classes/SoundFile.html#-sampleFormat">SoundFile: -sampleFormat</a>, <a href="./../Classes/SoundFile.html#-numChannels">SoundFile: -numChannels</a> and <a href="./../Classes/SoundFile.html#-sampleRate">SoundFile: -sampleRate</a> <em>before</em> calling <a href="./../Classes/SoundFile.html#-openWrite">SoundFile: -openWrite</a>.<h2><a class='anchor' name='classmethods'>Class Methods</a></h2>
<h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*new' href='./../Overviews/Methods.html#new'>new</a>(<span class='argstr'>pathName</span>)</h3>
<div class='method'>
<p>Creates a new SoundFile instance.</div><h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*openRead' href='./../Overviews/Methods.html#openRead'>openRead</a>(<span class='argstr'>pathName</span>)</h3>
<div class='method'>
<p>Try to open the audio file at the given path.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>pathName<td class='argumentdesc'>
<p>Full path to the sound file. Use <a href="./../Classes/String.html#-standardizePath">String: -standardizePath</a> to resolve home-folder shortcuts such as <code>~</code>.</table><h4>Returns:</h4>
<div class='returnvalue'>
<p>A new SoundFile instance if successful, or <code class='code prettyprint lang-sc'>nil</code> if file open failed. User code should check for <code class='code prettyprint lang-sc'>nil</code> before doing anything with the SoundFile object.</div></div><h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*openWrite' href='./../Overviews/Methods.html#openWrite'>openWrite</a>(<span class='argstr'>pathName</span>, <span class='argstr'>headerFormat</span>, <span class='argstr'>sampleFormat</span>, <span class='argstr'>numChannels</span>, <span class='argstr'>sampleRate</span>)</h3>
<div class='method'>
<p>Try to create an audio file at the given path. Note that there is no <code class='code prettyprint lang-sc'>numFrames</code> argument: the number of frames is counted after writing data into the file.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>pathName<td class='argumentdesc'>
<p>Full path to the sound file. Use <a href="./../Classes/String.html#-standardizePath">String: -standardizePath</a> to resolve home-folder shortcuts such as <code>~</code>.<tr><td class='argumentname'>headerFormat<td class='argumentdesc'>
<p>A string for the sound file format. Valid strings are listed at <a href="./../Classes/SoundFile.html#-headerFormat">SoundFile: -headerFormat</a>. If not given, the default <code class='code prettyprint lang-sc'>"AIFF"</code> is used.<tr><td class='argumentname'>sampleFormat<td class='argumentdesc'>
<p>A string for the sample format. Valid strings are listed at <a href="./../Classes/SoundFile.html#-sampleFormat">SoundFile: -sampleFormat</a>. If not given, the default <code class='code prettyprint lang-sc'>"float"</code> is used.<tr><td class='argumentname'>numChannels<td class='argumentdesc'>
<p>An integer number of channels (1 by default).<tr><td class='argumentname'>sampleRate<td class='argumentdesc'>
<p>An integer sample rate (44100 by default).</table><h4>Returns:</h4>
<div class='returnvalue'>
<p>A new SoundFile instance if successful, or <code class='code prettyprint lang-sc'>nil</code> if file open failed. User code should check for <code class='code prettyprint lang-sc'>nil</code> before doing anything with the SoundFile object.</div></div><h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*collect' href='./../Overviews/Methods.html#collect'>collect</a>(<span class='argstr'>path: "sounds/*"</span>)</h3>
<div class='method'>
<p>Returns an <a href="./../Classes/Array.html">Array</a> of SoundFile objects whose paths match the pattern. (The associated files are closed. These objects can be used to cue playback buffers)<pre class='code prettyprint lang-sc'>SoundFile.collect("sounds/*").do { |f| f.path.postln };</pre>
</div><h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*use' href='./../Overviews/Methods.html#use'>use</a>(<span class='argstr'>path</span>, <span class='argstr'>function</span>)</h3>
<div class='method'>
<p>Reads the data of a SoundFile, evaluates the function (passing the file as argument) and closes it again.<pre class='code prettyprint lang-sc'>SoundFile.use(Platform.resourceDir +/+ "sounds/a11wlk01.wav", { |f| f.inspect });</pre>
</div><h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*normalize' href='./../Overviews/Methods.html#normalize'>normalize</a>(<span class='argstr'>path</span>, <span class='argstr'>outPath</span>, <span class='argstr'>newHeaderFormat</span>, <span class='argstr'>newSampleFormat</span>, <span class='argstr'>startFrame: 0</span>, <span class='argstr'>numFrames</span>, <span class='argstr'>maxAmp: 1</span>, <span class='argstr'>linkChannels: true</span>, <span class='argstr'>chunkSize: 4194304</span>, <span class='argstr'>threaded: false</span>)</h3>
<div class='method'>
<p>Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
<p>Using this class method (SoundFile.normalize) will automatically open the source file for you. You may also <a href="#-openRead">-openRead</a> the SoundFile yourself and call <a href="#-normalize">-normalize</a> on it. In that case, the source path is omitted because the file is already open.
<p>See instance method <a href="#-normalize">-normalize</a> for more information.</div><h3><a class='anchor' name='Inherited%20class%20methods'>Inherited class methods</a></h3>
<div id='inheritedclassmets'></div><h3><a class='anchor' name='Undocumented%20class%20methods'>Undocumented class methods</a></h3>
<h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*closeAll' href='./../Overviews/Methods.html#closeAll'>closeAll</a></h3>
<h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*collectIntoBuffers' href='./../Overviews/Methods.html#collectIntoBuffers'>collectIntoBuffers</a>(<span class='argstr'>path: "sounds/*"</span>, <span class='argstr'>server</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*groupNormalize' href='./../Overviews/Methods.html#groupNormalize'>groupNormalize</a>(<span class='argstr'>paths</span>, <span class='argstr'>outDir</span>, <span class='argstr'>newHeaderFormat</span>, <span class='argstr'>newSampleFormat</span>, <span class='argstr'>maxAmp: 1</span>, <span class='argstr'>chunkSize: 4194304</span>, <span class='argstr'>threaded: true</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>SoundFile.</span><a class='method-name' name='*openFiles' href='./../Overviews/Methods.html#openFiles'>openFiles</a></h3>
<h2><a class='anchor' name='instancemethods'>Instance Methods</a></h2>
<h3><a class='anchor' name='Playback'>Playback</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-cue' href='./../Overviews/Methods.html#cue'>cue</a>(<span class='argstr'>ev</span>, <span class='argstr'>playNow: false</span>, <span class='argstr'>closeWhenDone: false</span>)</h3>
<div class='method'>
<p>Allocates a buffer and cues the SoundFile for playback. Returns an event parameterized to play that buffer. (See <a href="./../Reference/NodeEvent.html">NodeEvent</a> for a description of how events can be used to control running synths.) The event responds to <strong>play</strong>, <strong>stop</strong>, <strong>pause</strong>, <strong>resume</strong>, keeping both the file and buffer open. The file is closed and the buffer is freed when the event is sent a <strong>close</strong> message.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>ev<td class='argumentdesc'>
<p>An <a href="./../Classes/Event.html">Event</a> can passed as an argument allowing playback to be customized using the following keys:<table>
<tr><td><strong>key</strong><td><strong>default value</strong><td><strong>what it does</strong><tr><td>bufferSize<td>65536<td><tr><td>firstFrame<td>0<td>first frame to play<tr><td>lastFrame<td>nil<td>last frame to play (nil plays to end of file)<tr><td>out:<td>0<td>sets output bus<tr><td>server:<td>Server.default<td>which server<tr><td>group:<td>1<td>what target<tr><td>addAction:<td>0<td>head/tail/before/after<tr><td>amp:<td>1<td>amplitude<tr><td>instrument:<td>nil<td>if nil SoundFile:cue determines the SynthDef (one of diskIn1, diskIn2, ...diskIn16)</table>
<p>Where <strong>bufferSize</strong>, <strong>firstFrame</strong>, <strong>lastFrame</strong> are for buffer and playback position, and <strong>out</strong>, <strong>server</strong>, <strong>group</strong>, <strong>addAction</strong>, <strong>amp</strong> are synth parameters. Here is the default SynthDef used for stereo files:<pre class='code prettyprint lang-sc'>SynthDef(\diskIn2, { | bufnum, out, gate = 1, sustain, amp = 1, ar = 0, dr = 0.01 |
Out.ar(out, DiskIn.ar(2, bufnum)
* Linen.kr(gate, ar, 1, dr, 2)
* EnvGen.kr(Env.linen(0, sustain - ar - dr max: 0 ,dr),1, doneAction: Done.freeSelf) * amp)
});</pre>
<p>The control <strong>sustain</strong> determines playback duration based on the firstFrame and lastFrame. The control <strong>gate</strong> allows early termination of the playback<tr><td class='argumentname'>playNow<td class='argumentdesc'>
<p>This is a <a href="./../Classes/Boolean.html">Boolean</a> that determines whether the file is to be played immediately after cueing.<pre class='code prettyprint lang-sc'>f = SoundFile.collect("sounds/*");
e = f[1].cue;
e = f[1].cue( (addAction: 2, group: 1) ); // synth will play ahead of the default group</pre>
<tr><td class='argumentname'>closeWhenDone<td class='argumentdesc'>
<p>A flag to indicate wether the <code class='code prettyprint lang-sc'>SoundFile</code> will be closed after it's done playing. Default is False.</table></div><h3><a class='anchor' name='Read/Write'>Read/Write</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-openRead' href='./../Overviews/Methods.html#openRead'>openRead</a>(<span class='argstr'>pathName</span>)</h3>
<div class='method'>
<p>Read the header of a file. Answers a <a href="./../Classes/Boolean.html">Boolean</a> whether the read was successful. Sets the <a href="#-numFrames">-numFrames</a>, <a href="#-numChannels">-numChannels</a> and <a href="#-sampleRate">-sampleRate</a>. Does <strong>not</strong> set the <a href="#-headerFormat">-headerFormat</a> and <a href="#-sampleFormat">-sampleFormat</a>.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>pathName<td class='argumentdesc'>
<p>a <a href="./../Classes/String.html">String</a> specifying the path name of the file to read.</table></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-readData' href='./../Overviews/Methods.html#readData'>readData</a>(<span class='argstr'>rawArray</span>)</h3>
<div class='method'>
<p>Reads the sample data of the file into the raw array you supply. You must have already called <a href="#-openRead">-openRead</a>.
<p>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 <a href="#-channelPeaks">-channelPeaks</a> for example.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>rawArray<td class='argumentdesc'>
<p>The raw array must be a <a href="./../Classes/FloatArray.html">FloatArray</a>. 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.
<p>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.</table></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-openWrite' href='./../Overviews/Methods.html#openWrite'>openWrite</a>(<span class='argstr'>pathName</span>)</h3>
<div class='method'>
<p>Write the header of a file. Answers a <a href="./../Classes/Boolean.html">Boolean</a> whether the write was successful.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>pathName<td class='argumentdesc'>
<p>a <a href="./../Classes/String.html">String</a> specifying the path name of the file to write.</table></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-writeData' href='./../Overviews/Methods.html#writeData'>writeData</a>(<span class='argstr'>rawArray</span>)</h3>
<div class='method'>
<p>Writes the rawArray to the sample data of the file. You must have already called <a href="#-openWrite">-openWrite</a>.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>rawArray<td class='argumentdesc'>
<p>The raw array must be a <a href="./../Classes/FloatArray.html">FloatArray</a> or <a href="./../Classes/Signal.html">Signal</a>, with all values between -1 and 1 to avoid clipping during playback.<pre class='code prettyprint lang-sc'>(
f = SoundFile.new.headerFormat_("AIFF").sampleFormat_("int16").numChannels_(1);
f.openWrite("sounds/sfwrite.aiff");
// sawtooth
b = Signal.sineFill(100, (1..20).reciprocal);
// write multiple cycles (441 * 100 = 1 sec worth)
441.do({ f.writeData(b) });
f.close;
)</pre>
</table></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-isOpen' href='./../Overviews/Methods.html#isOpen'>isOpen</a></h3>
<div class='method'>
<p>answers if the file is open.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-close' href='./../Overviews/Methods.html#close'>close</a></h3>
<div class='method'>
<p>closes the file.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-duration' href='./../Overviews/Methods.html#duration'>duration</a></h3>
<div class='method'>
<p>the duration in seconds of the file.</div><h3><a class='anchor' name='Normalizing'>Normalizing</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-normalize' href='./../Overviews/Methods.html#normalize'>normalize</a>(<span class='argstr'>outPath</span>, <span class='argstr'>newHeaderFormat</span>, <span class='argstr'>newSampleFormat</span>, <span class='argstr'>startFrame: 0</span>, <span class='argstr'>numFrames</span>, <span class='argstr'>maxAmp: 1</span>, <span class='argstr'>linkChannels: true</span>, <span class='argstr'>chunkSize: 4194304</span>, <span class='argstr'>threaded: false</span>)</h3>
<div class='method'>
<p>Normalizes a soundfile to a level set by the user. The normalized audio will be written into a second file.
<p>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).<div class='note'><span class='notelabel'>NOTE:</span> 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 class='code prettyprint lang-sc'>threaded:true</code> to get feedback but it will take slightly longer to complete.</div><h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>outPath<td class='argumentdesc'>
<p>a path to the destination file.<tr><td class='argumentname'>newHeaderFormat<td class='argumentdesc'>
<p>the desired header format of the new file; if not specified, the header format of the source file will be used.<tr><td class='argumentname'>newSampleFormat<td class='argumentdesc'>
<p>the desired sample format of the new file; if not specified, the sample format of the source file will be used.<tr><td class='argumentname'>startFrame<td class='argumentdesc'>
<p>an index to the sample frame to start normalizing.<tr><td class='argumentname'>numFrames<td class='argumentdesc'>
<p>the number of sample frames to copy into the destination file (default nil, or entire soundfile).<tr><td class='argumentname'>maxAmp<td class='argumentdesc'>
<p>the desired maximum amplitude. Provide a floating point number or, if desired, an array to specify a different level for each channel.<tr><td class='argumentname'>linkChannels<td class='argumentdesc'>
<p>a <a href="./../Classes/Boolean.html">Boolean</a> specifying whether all channels should be scaled by the same amount. The default is <strong>true</strong>, 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).<tr><td class='argumentname'>chunkSize<td class='argumentdesc'>
<p>how many samples to read at once (default is 4194304, or 16 MB).<tr><td class='argumentname'>threaded<td class='argumentdesc'>
<p>if true, the normalization runs in a routine so that SC can respond (intermittently) while processing. Prevents macOS beachballing.</table></div><h3><a class='anchor' name='Instance%20Variables'>Instance Variables</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-path' href='./../Overviews/Methods.html#path'>path</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-path' href='./../Overviews/Methods.html#path'>path</a> = value</h3>
<div class='method'>
<p>Get the pathname of the file. This variable is set via the <a href="#-openRead">-openRead</a> or <a href="#-openWrite">-openWrite</a> calls.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-headerFormat' href='./../Overviews/Methods.html#headerFormat'>headerFormat</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-headerFormat' href='./../Overviews/Methods.html#headerFormat'>headerFormat</a> = value</h3>
<div class='method'>
<p>This is a <a href="./../Classes/String.html">String</a> 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.<dl>
<dt>read/write header formats:<dd><table>
<tr><td>"AIFF"<td>Apple/SGI AIFF format<tr><td>"WAV","WAVE", "RIFF"<td>Microsoft WAV format<tr><td>"Sun", "NeXT"<td>Sun/NeXT AU format<tr><td>"SD2"<td>Sound Designer 2<tr><td>"IRCAM"<td>Berkeley/IRCAM/CARL<tr><td>"raw"<td>no header = raw data<tr><td>"MAT4"<td>Matlab (tm) V4.2 / GNU Octave 2.0<tr><td>"MAT5"<td>Matlab (tm) V5.0 / GNU Octave 2.1<tr><td>"PAF"<td>Ensoniq PARIS file format<tr><td>"SVX"<td>Amiga IFF / SVX8 / SV16 format<tr><td>"NIST"<td>Sphere NIST format<tr><td>"VOC"<td>VOC files<tr><td>"W64"<td>Sonic Foundry's 64 bit RIFF/WAV<tr><td>"PVF"<td>Portable Voice Format<tr><td>"XI"<td>Fasttracker 2 Extended Instrument<tr><td>"HTK"<td>HMM Tool Kit format<tr><td>"SDS"<td>Midi Sample Dump Standard<tr><td>"AVR"<td>Audio Visual Research<tr><td>"FLAC"<td>FLAC lossless file format<tr><td>"CAF"<td>Core Audio File format</table>
</dl>
<p>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 W64 (or CAF on macOS).</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-sampleFormat' href='./../Overviews/Methods.html#sampleFormat'>sampleFormat</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-sampleFormat' href='./../Overviews/Methods.html#sampleFormat'>sampleFormat</a> = value</h3>
<div class='method'>
<p>A <a href="./../Classes/String.html">String</a> indicating the format of the sample data which was read by <a href="#-openRead">-openRead</a> and will be written by <a href="#-openWrite">-openWrite</a>. libsndfile determines which header formats support which sample formats. This information is detailed at <a href="http://www.mega-nerd.com/libsndfile">http://www.mega-nerd.com/libsndfile</a> . The possible header formats are:<dl>
<dt>sample formats:<dd><table>
<tr><td>"int8", "int16", "int24", "int32"<tr><td>"mulaw", "alaw",<tr><td>"float"</table>
</dl>
<p>Not all header formats support all sample formats.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-numFrames' href='./../Overviews/Methods.html#numFrames'>numFrames</a></h3>
<div class='method'>
<p>The number of sample frames in the file.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-numChannels' href='./../Overviews/Methods.html#numChannels'>numChannels</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-numChannels' href='./../Overviews/Methods.html#numChannels'>numChannels</a> = value</h3>
<div class='method'>
<p>The number of channels in the file.</div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-sampleRate' href='./../Overviews/Methods.html#sampleRate'>sampleRate</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-sampleRate' href='./../Overviews/Methods.html#sampleRate'>sampleRate</a> = value</h3>
<div class='method'>
<p>The sample rate of the file.</div><h3><a class='anchor' name='Inherited%20instance%20methods'>Inherited instance methods</a></h3>
<div id='inheritedinstmets'></div><h3><a class='anchor' name='Undocumented%20instance%20methods'>Undocumented instance methods</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-asBuffer' href='./../Overviews/Methods.html#asBuffer'>asBuffer</a>(<span class='argstr'>server</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-asEvent' href='./../Overviews/Methods.html#asEvent'>asEvent</a>(<span class='argstr'>type: 'allocRead'</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-channelPeaks' href='./../Overviews/Methods.html#channelPeaks'>channelPeaks</a>(<span class='argstr'>startFrame: 0</span>, <span class='argstr'>numFrames</span>, <span class='argstr'>chunkSize: 1048576</span>, <span class='argstr'>threaded: false</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-fileptr' href='./../Overviews/Methods.html#fileptr'>fileptr</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-fileptr' href='./../Overviews/Methods.html#fileptr'>fileptr</a> = value</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-info' href='./../Overviews/Methods.html#info'>info</a>(<span class='argstr'>path</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-play' href='./../Overviews/Methods.html#play'>play</a>(<span class='argstr'>ev</span>, <span class='argstr'>playNow: true</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-readHeaderAsString' href='./../Overviews/Methods.html#readHeaderAsString'>readHeaderAsString</a></h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-scaleAndWrite' href='./../Overviews/Methods.html#scaleAndWrite'>scaleAndWrite</a>(<span class='argstr'>outFile</span>, <span class='argstr'>scale</span>, <span class='argstr'>startFrame</span>, <span class='argstr'>numFrames</span>, <span class='argstr'>chunkSize</span>, <span class='argstr'>threaded: false</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-seek' href='./../Overviews/Methods.html#seek'>seek</a>(<span class='argstr'>offset: 0</span>, <span class='argstr'>origin: 0</span>)</h3>
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-toCSV' href='./../Overviews/Methods.html#toCSV'>toCSV</a>(<span class='argstr'>outpath</span>, <span class='argstr'>headers</span>, <span class='argstr'>delim: ","</span>, <span class='argstr'>append: false</span>, <span class='argstr'>func</span>, <span class='argstr'>action</span>)</h3>
<h2><a class='anchor' name='examples'>Examples</a></h2>
<pre class='code prettyprint lang-sc'>// Writing a sound file, long form:
// Set the format variables before calling 'openWrite'
// The Boolean answer from 'openWrite' tells you if it's safe to proceed
(
f = SoundFile(PathName.tmp +/+ "sf-help.wav");
f.headerFormat = "WAV";
f.sampleFormat = "int16";
if(f.openWrite) {
f.writeData(Signal.sineFill(1024, [1]));
f.close;
} {
"Failed to open %".format(f.path).warn;
};
)
// Or, short form: Class method 'openWrite'
// f is nil if the file couldn't be opened
(
var p = PathName.tmp +/+ "sf-help.wav";
f = SoundFile.openWrite(p, "WAV", "int16");
if(f.notNil) {
f.writeData(Signal.sineFill(1024, [1]));
f.close;
} {
"Failed to open %".format(p).warn;
};
)
// Reading the file
f = SoundFile.openRead(PathName.tmp +/+ "sf-help.wav");
f.sampleFormat;
// To get data, create a FloatArray or Signal first
d = FloatArray.newClear(f.numFrames);
f.readData(d);
d.plot;
f.close;
s.boot;
// It's a proper audio file -- server can load it
b = Buffer.read(s, PathName.tmp +/+ "sf-help.wav");
// It's a sinewave...
a = { (PlayBuf.ar(1, b, rate: 440 * 1024/44100, loop: 1) * 0.1).dup }.play;
a.free;
b.free;
File.delete(PathName.tmp +/+ "sf-help.wav");</pre>
<p><div class='doclink'>helpfile source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/SoundFile.schelp'>/Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/SoundFile.schelp</a><br>link::Classes/SoundFile::<br></div></div></body></html>
Reference in a new issue Copy permalink