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

.collection

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

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

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

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

Zero the values in the buffer.

Arguments:

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

.write

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

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

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

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

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

Plot the buffer.

Arguments:

name
bounds
minval
maxval
parent
labels

.preparePartConv

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

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

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

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

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

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

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).

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: HelpSource/Classes/CtkBuffer.schelp
link::Ctk/Classes/CtkBuffer::

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.

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.

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.

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

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.

CtkBufferExtension

Description

Class Methods

.new

Arguments:

Returns:

.buffer

Arguments:

Returns:

.playbuf

Arguments:

Returns:

.diskin

Arguments:

Returns:

.env

Arguments:

Returns:

.collection

Arguments:

Instance Methods

.load

Arguments:

Discussion:

.free

Arguments:

.set

Arguments:

.zero

Arguments:

.write

Arguments:

.openWrite

Arguments:

.closeWrite

Arguments:

.fill

Arguments:

.addTo

Arguments:

.sampleRate

Returns:

.numChannels

Returns:

.duration

Returns:

.plot

Arguments:

.preparePartConv

Arguments:

Returns:

Wave Fill Commands

.gen

Arguments:

.sine1

Arguments:

.sine2

Arguments:

.sine3

Arguments:

.cheby

Arguments:

.fillWithEnv

Arguments:

Examples

Real-time uses

Uses with CtkScore

CtkBuffer
Extension