CtkBuffer | SuperCollider 3.13.0 Help

Description

Part of the Composer's Tool Kit (CTK) system. See CTK for more details.

CtkBuffers can be used for both real-time and non-real-time (NRT) purposes, and can be used for soundfile playback, DiskIn allocation and to allocate empty buffer space.

NOTE: For real-time use, -load needs to be called on the instance of the CtkBuffer before using it.

Class Methods

CtkBuffer.new(path, size, startFrame: 0, numFrames, numChannels, bufnum, server, channels)

Create new instance of CtkBuffer. Depending on the parameters passed to the new method, different kinds of buffers will be allocated:

If only path is given, the soundfile will be completely loaded into a CtkBuffer for use in UGens such as PlayBuf or BufRd. Size and numChannels will be calculated for you with the SoundFile class.
If path and size is given, a CtkBuffer suitable for use with DiskIn is allocated. The buffer is left open and will be closed when the buffer is freed. Size should be a power of 2 (see the DiskIn helpfile).
If only size is given, an empty buffer is allocated of size; numChannels defaults to 1.

NOTE: There are also creation methods for the more commonly used buffer types.

Arguments:

path	The path to the input sound file.
size	The size of a buffer, usually used when creating empty buffers. It is automatically calculated if this CtkBuffer is used to load a soundfile.
startFrame	The first frame of the soundfile to read. The default is 0, which is the beginning of the file.
numFrames	The number of frames to read. The default is -1, which will read the whole file.
numChannels	The number of channels for the buffer. It is automatically calculated if this CtkBuffer is used to load a soundfile.
bufnum	An explicitly specified buffer number. The default is nil. If nil, a buffer id will be allocated for you.
server	The server on which to allocate the buffer. Defaults to Server.default.
channels	When reading from file, specifies channels to read. It can be a single number or an Array. Nil (the default) reads all channels.

Returns:

a CtkBuffer

CtkBuffer.buffer(size, numChannels, server)

Create an empty CtkBuffer of a given size and numChannels.

Arguments:

size	Size of the buffer.
numChannels	Number of channels of the buffer.
server	The server on which to allocate the buffer.

Returns:

a CtkBuffer

CtkBuffer.playbuf(path, startFrame: 0, numFrames, server, channels)

Create a CtkBuffer suitable for PlayBuf usage.

Arguments:

path	A String representing the path of the soundfile to be read.
startFrame	The first frame of the soundfile to read. The default is 0, which is the beginning of the file.
numFrames	The number of frames to read. The default is -1, which will read the whole file.
server	The server on which to allocate the buffer.
channels	Channels can be nil (read all channels), a single number (read only 1 channel) or and Array of channels.

Returns:

a CtkBuffer

CtkBuffer.diskin(path, size: 32768, startFrame: 0, server, channels)

Create a CtkBuffer suitable for DiskIn usage (see the DiskIn for more information).

Arguments:

path	A String representing the path of the soundfile to be read.
size	Size of the buffer, defaults to 32768
startFrame	The first frame of the soundfile to read. The default is 0, which is the beginning of the file.
server	The server on which to allocate the buffer, defaults to Server.default
channels	Channels can be nil (read all channels), a single number (read only 1 channel) or and Array of channels.

Returns:

a CtkBuffer

CtkBuffer.env(size, env, wavetable: 0, server)

Create a CtkBuffer, filled with values from an Env.

Arguments:

size	Size of the buffer
env	An Env to be loaded into a CtkBuffer.
wavetable	if 0 (default), the CtkBuffer is filled with a Signal; if 1, the CtkBuffer is filled with a Wavetable
server	The server on which to allocate the buffer.

Returns:

a CtkBuffer

CtkBuffer.collection(collection, numChannels: 1, server)

Create a CtkBuffer from a collection, usually a Signal or RawArray.

Arguments:

collection	Values to be loaded into a buffer.
numChannels	The number of channels for the buffer.
server	The server on which to allocate the buffer.

Instance Methods

.load(time, sync: true, onComplete)

Load the CtkBuffer to the server for real-time use.

Arguments:

time	Schedule loading the buffer in 'time' seconds
sync	If true, a messages will post to let you know the buffer has been allocated
onComplete	Action to perform after loading. Useful, for instance, in combination with a condition to wait for the buffer to load.

Discussion:

If other methods have been applied to a CtkBuffer (Wave fill commands or other fill or zero commands), these will be sent after the CtkBuffer has been loaded to the server and the message's time parameter is ignored. If you want to schedule something for the future, do it AFTER calling the load method.

.free(time: 0.0, addMsg: true)

Frees and, if necessary, closes the instance of CtkBuffer. For real-time use.

Arguments:

time	Schedule freeing in 'time' seconds.
addMsg	Add a message to send to the server.

.set(time: 0.0, startPos, values)

Set a value or an Array of values to a CtkBuffer. If using in real-time, the CtkBuffer must be loaded first.

Arguments:

time	In real-time mode, 'time' schedules the set in the future.
startPos	First frame to write values to
values	A single value or an Array to set

.zero(time: 0)

Zero the values in the buffer.

Arguments:

time	In real-time mode, 'time' schedules the zero in the future.

.write(time: 0.0, path, headerFormat: 'aiff', sampleFormat: 'int16', numberOfFrames: -1, startingFrame: 0, action)

Write a buffer to a file at path.

Arguments:

time	In real-time mode, 'time' schedules the write in the future.
path	The path of the output file.
headerFormat	The header format of the output file. Defaults to 'aiff'. See SoundFile: -headerFormat for more info.
sampleFormat	The sample format of the output file. Defaults to 'int16'. See SoundFile: -sampleFormat for more info.
numberOfFrames	The number of frames to write. The defaults is -1 (all frames).
startingFrame	The starting frame of the buffer to write. The default is 0.
action	An action to be executed when the buffer is ready

.openWrite(time: 0.0, path, headerFormat: 'aiff', sampleFormat: 'int16', numberOfFrames: -1, startingFrame: 0, action)

Write a buffer to file at path. This file is left open for use by DiskOut, and will need to have the -closeWrite method applied to the CtkBuffer.

Arguments:

time	In real-time mode, time schedules the openWrite in the future.
path	The path of the output file.
headerFormat	The header format of the output file. Defaults to 'aiff'. See SoundFile: -headerFormat for more info.
sampleFormat	The sample format of the output file. Defaults to 'int16'. See SoundFile: -sampleFormat for more info.
numberOfFrames	The number of frames to write. The defaults is -1 (all frames).
startingFrame	The starting frame of the buffer to write. The default is 0.
action	An action to be executed when the buffer is ready

.closeWrite(time: 0.0, action)

Close and write the header for a file that had been created and left open with openWrite.

Arguments:

time	In real-time mode, 'time' schedules the closeWrite in the future.
action	An action to be executed when the buffer is ready

.fill(time: 0.0, newValue, start: 0, numSamples: 1)

Fill a buffer with newValue starting at sample start for numSamples. From the Server Command Reference: /b_fill: "This is only meant for setting a few samples, not whole buffers or large sections"

Arguments:

time	In real-time mode, 'time' schedules the fill in the future.
newValue	Value to fill the buffer with
start	Sample number to start
numSamples	Number of samples to write

.addTo(aCtkScore)

From superclass: CtkObj

Add this CtkBuffer to a CtkScore for playing or NRT rendering.

NOTE: All buffers are allocated at the beginning of the score. If a CtkScore is played, all CtkBuffers are loaded to the server before performance begins and may cause a delay. All CtkBuffers are freed when performance of a CtkScore is finished.

Arguments:

aCtkScore

A CtkScore to which the CtkBuffer will be added.

.sampleRate

Returns:

sample rate of the buffer

.numChannels

Returns:

the number of channels in a CtkBuffer

.duration

Returns:

the duration of the CtkBuffer, in seconds

.plot(name: "Plot", bounds, minval: -1.0, maxval: 1.0, parent, labels: true)

Plot the buffer.

Arguments:

name
bounds
minval
maxval
parent
labels

.preparePartConv(time: 0.001, buf, fftsize, action)

Preapre buffer of spectra for use with PartConv

Arguments:

time
buf	impulse response buffer
fftsize	spectral convolution partition size
action	An action to be executed when the buffer is ready

Returns:

CtkBuffer for use with PartConv

Wave Fill Commands

See Server Command Reference: Wave Fill Commands for more information.

.gen(time: 0.0, cmd, normalize: 0, wavetable: 0, clear: 1 ... args)

This is the basic template used for the following standard b_gen commands.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
cmd	cmd is one of \sine1, \sine2, \sine3, or \cheby.
normalize	Set to 1 to normalize. The defaults is 0 (don't normalize).
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).
clear	Specifies if the buffer should be cleared before values are set or if new values should add to values previously in the buffer (defaults to 1 to clear values, 0 to add to old ones)
... args	The format of args is dependent on the wave command (see more below).

.sine1(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Args are individual floats that are applied to harmonic partials of a sine wave and can vary in size.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
normalize	Set to 1 to normalize. The defaults is 0 (don't normalize).
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).
clear	Specifies if the buffer should be cleared before values are set or if new values should add to values previously in the buffer (defaults to 1 to clear values, 0 to add to old ones).
... args	Args are individual floats that are applied to harmonic partials of a sine wave and can vary in size, for example: args = 1 - create a wave with only a fundamental frequency. args = 0.2, 1, 0.5, 0.2 - four partials, fundamental has an amplitude of 0.2, first partial's is 1, second partial's is 0.5, and the third partial's is 0.2.

.sine2(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Args are pairs where the first float specifies the frequency of a partial (where 1 is the base frequency of the buffer) and the second value is its amplitude.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
normalize	Set to 1 to normalize. The defaults is 0 (don't normalize).
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).
clear	Specifies if the buffer should be cleared before values are set or if new values should add to values previously in the buffer (defaults to 1 to clear values, 0 to add to old ones).
... args	args are pairs where the first float specifies the frequency of a partial (where 1 is the base frequency of the buffer) and the second value is its amplitude, for example: args = 1, 0.5, 4, 0.2 - fundamental has a strength of 0.5, and the third partial has a strength of 0.2.

.sine3(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Args are sets of three values (similar to -sine2) that correspond to partial frequency, amplitude and phase.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
normalize	Set to 1 to normalize. The defaults is 0 (don't normalize).
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).
clear	Specifies if the buffer should be cleared before values are set or if new values should add to values previously in the buffer (defaults to 1 to clear values, 0 to add to old ones).
... args	Args are sets of three values (similar to -sine2) that correspond to partial frequency, amplitude and phase.

.cheby(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Args can be a series of floats that correspond to a series of chebyshev polynomials.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
normalize	Set to 1 to normalize. The defaults is 0 (don't normalize).
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).
clear	Specifies if the buffer should be cleared before values are set or if new values should add to values previously in the buffer (defaults to 1 to clear values, 0 to add to old ones).
... args	args can be a series of floats that correspond to a series of chebyshev polynomials. The first float is for n = 1, where: cheby(n) = amplitude * cos(n * acos(x))

.fillWithEnv(time: 0.0, env, wavetable: 0.0)

Converts an instance of Env into a Signal or Wavetable, and loads its values to the CtkBuffer.

Arguments:

time	In real-time mode, 'time' schedules this buffer's creation in the future.
env	An Env to be loaded into a CtkBuffer.
wavetable	Specifies whether or not the buffer should use Wavetable format (defaults to 0, set to 1 for Wavetables).

Inherited instance methods

Undocumented instance methods

.collection

.collection = aCollection

.normalize(time: 0.0, newmax: 1.0, asWavetable: false, action)

.read(time: 0.0, path, fileFrameStart: 0, numFrames, bufStartFrame: 0, leaveOpen: false, completionMessage, action)

Examples

Real-time uses

s.boot;
//for use with PlayBuf
a = CtkBuffer.playbuf(Platform.resourceDir +/+ "sounds/a11wlk01.wav").load(sync: true); // load and sync with the server
b = {PlayBuf.ar(1, a)}.play(s);
b.free;
a.free;

// for use with DiskIn
a = CtkBuffer(Platform.resourceDir +/+ "sounds/a11wlk01.wav", 65536).load(sync: true); // load and sync with the server

b = {DiskIn.ar(1, a)}.play(s);

b.free;
a.free;

// for use with delays
a = CtkBuffer(Platform.resourceDir +/+ "sounds/a11wlk01.wav", 65536).load(sync: true); // load and sync with the server
b = CtkBuffer(size: 65536).load(sync: true); // load and sync with the server

(
c = {var play, del;
    play = DiskIn.ar(1, a);
    del = BufDelayN.ar(b, play, 0.25);
    [play, del]
}.play(s);
)

c.free;
a.free;
b.free;

// allocating and setting values
a = CtkBuffer(size: 2048);
a.load(sync: true);
a.set(0.0, 0, Array.fill(1024, {-1.0.rrand(1.0)}));

b = {PlayBuf.ar(1, a, loop: 1)}.play(s);

// change the values in the buffer
a.set(0.0, 1024, Array.fill(1024, {-1.0.rrand(1.0)}));

// zero it out
a.zero;

// refill them
a.set(0.0, 0, Array.fill(1024, {-1.0.rrand(1.0)}));
a.set(0.0, 1024, Array.fill(1024, {0.0.rrand(1.0)}));

b.free;
a.free;

// with Osc, OscN and Shaper with the fill commands

a = CtkBuffer(size: 32768).load(sync: true);
a.sine1(0.0, 1, 1, 1, 0.3);

b = {Osc.ar(a, 440, mul: 0.5)}.play(s);
a.sine1(0.0, 1, 1, 1, 0.3, 0.2, 0.5);
a.sine3(0.0, 1, 1, 1, 1, 0.3, 0.0, 4, 0.2, 0.2, 9, 0.4, 0.5);

b.free;
a.free;

a = CtkBuffer.new(size: 32768).load(sync: true);
a.sine1(0.0, 1, 0, 1, 0.3);

b = {OscN.ar(a, 440, mul: 0.5)}.play(s);
a.sine1(0.0, 1, 0, 1, 0.3, 0.2, 0.5);
a.sine3(0.0, 1, 0, 1, 1, 0.3, 0.0, 4, 0.2, 0.2, 9, 0.4, 0.5);

b.free;
a.free;

a = CtkBuffer(size: 32768);
a.cheby(0.0, 1, 1, 1, 0.3, 0.2, 0.5);
a.load(sync: true);
s.scope;

b = {Shaper.ar(a, SinOsc.ar(440, 0, 0.5), mul: 0.5)}.play(s);

a.cheby(0.0, 1, 1, 1, 1.0, 0.5, 0.2);
a.cheby(0.0, 1, 1, 1, 0.1, 0.5, 1.0);
a.cheby(0.0, 1, 1, 1, 1.0);

b.free;
a.free;

// Test with DiskOut

a = CtkBuffer(size: 32768).load;
// open a file for writing with DiskOut
a.openWrite(0.0, "~/Desktop/test.aiff".standardizePath, 'aiff', 'int16', -1);

b = {var sig =  SinOsc.ar(440, 0, 0.2); DiskOut.ar(a, sig); sig}.play(s);

// let it run for a moment... then kill
b.free;
//close the file
a.closeWrite.free;
// test to make sure it worked
a = CtkBuffer("~/Desktop/test.aiff".standardizePath).load;

b = {PlayBuf.ar(1, a)}.play;

b.free; a.free;

// the fillWithEnv method.
a = CtkBuffer.new(size: 1024).fillWithEnv(env: Env([0, 1, 0], [0.5, 0.5], \sin)).load;
b = {SinOsc.ar(440, 0, 0.2) * BufRd.ar(1, a, Phasor.ar(0.0, 0.01, 0, 1024).poll)}.play(s)

b.free;
a.free;

Uses with CtkScore

(
var play, buf, score, playfun;

score = CtkScore.new;

play = CtkNoteObject(
    SynthDef(\play, {arg buffer, rate = 1, dur, start;
        OffsetOut.ar(0,
            Pan2.ar(
                PlayBuf.ar(1, buffer, BufRateScale.kr(buffer) * rate,
                    startPos: start * BufSampleRate.kr(buffer)) *
                EnvGen.ar(
                    Env([0, 1, 0], [0.5, 0.5], \sin),
                    timeScale: dur)))
        })
    );

buf = CtkBuffer(Platform.resourceDir +/+ "sounds/a11wlk01-44_1.aiff").addTo(score);

//CtkBuffer(size: 1024).set(0.0, 0, Array.fill(1024, {-1.0.rrand(1.0)})).zero(1).addTo(score);

playfun = {arg starttime, gestdur, rateenv;
    var note, now, ratio, rate;
    now = 0;
    while({
        ratio = now / gestdur;
        rate = rateenv[ratio];
        play.new(now + starttime, 0.5)
            .buffer_(buf) // the arg will parse the CtkBuffer and grab its bufnum
            .rate_(CtkControl.env(Env([rate, 1], [1])))
            .dur_(0.5)
            .start_((buf.duration - (0.5 * rate)).rand)
            .addTo(score);
        now = now + 0.2;
        now < gestdur;
        });
    };

playfun.value(0, 20, Env([0.5, 2.0, 1.0], [0.2, 0.8], [3, -5]));

// uncomment to play the score
//[score.notes, score.groups, score.controls, score.messages].postln;
score.play
// uncomment to save the score
//score.saveToFile("~/Desktop/test.sc".standardizePath);
// uncomment to write the score to a soundfile
//score.write("~/Desktop/test.aiff".standardizePath,
//    options: ServerOptions.new.numOutputBusChannels_(2));
)

helpfile source: /Library/Application Support/SuperCollider/downloaded-quarks/Ctk/HelpSource/Classes/CtkBuffer.schelp
link::Classes/CtkBuffer::

CtkBuffer : CtkObj : Object Extension

CtkBuffer.new(path, size, startFrame: 0, numFrames, numChannels, bufnum, server, channels)

Arguments:

Returns:

CtkBuffer.buffer(size, numChannels, server)

Arguments:

Returns:

CtkBuffer.playbuf(path, startFrame: 0, numFrames, server, channels)

Arguments:

Returns:

CtkBuffer.diskin(path, size: 32768, startFrame: 0, server, channels)

Arguments:

Returns:

CtkBuffer.env(size, env, wavetable: 0, server)

Arguments:

Returns:

CtkBuffer.collection(collection, numChannels: 1, server)

Arguments:

.load(time, sync: true, onComplete)

Arguments:

Discussion:

.free(time: 0.0, addMsg: true)

Arguments:

.set(time: 0.0, startPos, values)

Arguments:

.zero(time: 0)

Arguments:

.write(time: 0.0, path, headerFormat: 'aiff', sampleFormat: 'int16', numberOfFrames: -1, startingFrame: 0, action)

Arguments:

.openWrite(time: 0.0, path, headerFormat: 'aiff', sampleFormat: 'int16', numberOfFrames: -1, startingFrame: 0, action)

Arguments:

.closeWrite(time: 0.0, action)

Arguments:

.fill(time: 0.0, newValue, start: 0, numSamples: 1)

Arguments:

.addTo(aCtkScore)

Arguments:

.sampleRate

Returns:

.numChannels

Returns:

.duration

Returns:

.plot(name: "Plot", bounds, minval: -1.0, maxval: 1.0, parent, labels: true)

Arguments:

.preparePartConv(time: 0.001, buf, fftsize, action)

Arguments:

Returns:

.gen(time: 0.0, cmd, normalize: 0, wavetable: 0, clear: 1 ... args)

Arguments:

.sine1(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Arguments:

.sine2(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Arguments:

.sine3(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Arguments:

.cheby(time, normalize: 0, wavetable: 0, clear: 1 ... args)

Arguments:

.fillWithEnv(time: 0.0, env, wavetable: 0.0)

Arguments:

.collection

.collection = aCollection

.normalize(time: 0.0, newmax: 1.0, asWavetable: false, action)

.read(time: 0.0, path, fileFrameStart: 0, numFrames, bufStartFrame: 0, leaveOpen: false, completionMessage, action)

CtkBuffer : CtkObj : Object
Extension