CtkBuffer:
Filter:
Ctk/Classes (extension) | Libraries > CTK

CtkBuffer
ExtensionExtension

Representation of a buffer for CTK objects
 

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

.new

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

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

.buffer

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

.playbuf

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

.diskin

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

.env

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

.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

Uses with CtkScore