BufferTool holds additional information about buffers and manipulates them
superclass: Object
This class acts as a wrapper for a Buffer. Multiple instances can point at the same Buffer, so that one Buffer may have multiple BufferTools representing grains.
Accessing Instance Variables
The following variables have getter methods.
server - Returns the Buffer's Server object.
bufnum - Returns the buffer number of the corresponding server-side buffer. In normal use you should not need to access this value, since instances of Buffer can be used directly as UGen inputs or Synth args.
numFrames - Returns the number of sample frames in the corresponding server-side buffer. Note that multichannel buffers interleave their samples, so when dealing with indices in methods like get and getn, the actual number of available values is numFrames * numChannels.
startFrame - Returns the start frame of this particular instance
endFrame - Returns the end frame of this particular instance
dur - Returns the duration of this particular instance, in seconds
numChannels - Returns the number of channels in the corresponding server-side buffer.
sampleRate - Returns the sample rate of the corresponding server-side buffer.
buf - Returns the Buffer object associatied with this BufferTool
amp - Can be used to hold an amplitude for playback. This is useful for when BufferTools from different buffers are together in a single array
synthDefName - Can be used to hold an synthDef name for playback. This is useful for when BufferTools from different buffers are together in a single array, especially if mono and stereo are mixed together.
s.boot;
b = BufferTool.alloc(s,8.0,2);
b.bufnum.postln;
b.free;
Creation with Immediate Memory Allocation
*alloc(server, dur, numChannels, sampleRate, action, class)
Create a Buffer, return a BufferTool and immediately allocate the required memory on the server. The buffer's values will be initialised to 0.0.
server - The server on which to allocate the buffer. The default is the default Server.
dur - The duration of the desired buffer
numChannels - The number of channels for the Buffer. The default is 1.
sampleRate - The sample rate for the Buffer. The default is 44100.
action - A function to be evaluated after the allocation is completed.
class - The class to use when the bufer is allocated, in case you have a subclass of Buffer that you would like to use. This is useful for people using BBCutBuffers, for example. The default is Buffer.
// Allocate 8 second stereo buffer
s.boot;
b = BufferTool.alloc(s, 8.0, 2);
b.free;
*open(server, path, action, class)
Allocate a buffer and immediately read a soundfile into it. This method sends a query message as a completion message so that the Buffer's instance variables will be updated automatically. N.B. You cannot rely on the buffer's instance variables being instantly updated, as there is a small amount of latency involved. action will be evaluated upon receipt of the reply to the query, so use this in cases where access to instance variables is needed.
server - The server on which to allocate the buffer.
path - A String representing the path of the soundfile to be read.
action - A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this BufferTool as an argument.
class - The class to use when the bufer is read, in case you have a subclass of Buffer that you would like to use. This is useful for people using BBCutBuffers, for example. The default is Buffer.
// read a soundfile
s.boot;
b = BufferTool.open(s, "sounds/a11wlk01.wav");
// now play it
(
x = SynthDef(\help_Buffer, { arg out = 0, bufnum;
Out.ar( out,
PlayBuf.ar(1, bufnum, BufRateScale.kr(bufnum))
)
}).play(s,[\bufnum, b.bufnum]);
)
x.free; b.free;
// with an action function
(
b = BufferTool.open(s, "sounds/a11wlk01.wav", action: { arg buffer;
("After update:" + buffer.numFrames).postln;
x = { PlayBuf.ar(1, buffer.bufnum, BufRateScale.kr(buffer.bufnum)) }.play;
});
)
x.free; b.free;
Creation from an existing BufferTool or Buffer
*grain(server, buffer, startFrame, endFrame, sampleRate, synthDefName, bufnum, bufamp class)
Create and return a new BufferTool object, from an existing Buffer or BufferTool.
server - The server on which to allocate the buffer. The default is the default Server.
buffer - The frame number that the BufferTool starts on.
startFrame - The frame number that the BufferTool starts on. This can also be inferred from the buffer.
endFrame - The frame number that the BufferTool ends on. This can also be inferred from the buffer.
sampleRate - The sampleRate for the Buffer. This can also be inferred from the buffer.
synthDefName - A symbol for the synthdef that would be used with this BufferTool (see above). This is optional.
bufnum - The number of the bufnum of the associated buffer. This can also be inferred from the buffer.
bufamp - An amplitude that might be used to play the buffer. This is optinal.
class - The class of the buffer object. This may be useful to people using BBCutBuffers. This defaults to Buffer.
s.boot;
b = Buffer.alloc(s, 44100 * 8.0, 2);
c = BufferTool.grain(s, b);
b.query;
c.buf.query;
b.free; c.free;
Non-Real Time Instance Methods
findPitch(threshold, action);
A simple non-realtime method for finding the pitch of a BufferTool. The result can be found in this BufferTool's instance variable pitch.
threshold - Amplitude threshold.
action - A Function to be evaluated once the pitch has been found and this BufferTool's instance variables have been updated. The function will be passed this BufferTool as an argument. The pitch instance variable is set immeditately before the action is evaluated.
s.boot;
b = BufferTool.open(s, "sounds/a11wlk01.wav");
(
b.findPitch(action: {
("pitch is" + b.pitch).postln;
x = {SinOsc.ar(b.pitch)}.play;
});
)
x.free; b.free;
prepareWords(threshold, length, take_last, min, border_on_zero_crossing, action);
A non-realtime algorythm for finding pauses in speech. It works best in English. This creates an array of BufferTools, (each pointing at the source Buffer) with startFrame, endFrame, etc all decribing individual words. This result can be found in this BufferTool's instance variable grains. This method might also work with any sounds that have pauses.
threshold - The amplitude thehold for what is loud enough to be an utterance.
length - The number of frames of the shortest allowable pause between words.
take_last - A boolean which indicates if the end of the Buffer should be made into a grain or discarded.
min - The shortest allowable word or sound, in frames. The deafault is 4410.
border_on_zero_crossing - A boolean which indicates if the borders of grains should fall on zero crossings. If true, the border is the closest zero crossing before the sample reaches the threshold. If false, the border is on the sample that is at or oever the threshold. This defaults to false.
action - A Function to be evaluated once the grains have been found and this BufferTool's instance variables have been updated. The function will be passed this BufferTool as an argument. The grains instance variable is set immeditately before the action is evaluated.
s.boot;
b = BufferTool.open(s, "sounds/a11wlk01.wav");
SynthDescLib.global.read;
(
b.prepareWords(0.3, 20000, true, action: {
("number of words found:" + b.grains.size).postln;
x = Synth.new(b.synthDefName, args:
[\bufbum, b.bufnum,
\startFrame, b.grains[3].startFrame,
\grainDur, b.grains[3].dur]).play;
});
)
x.free; b.free;
Instance Methods
calc_grains_size(size, max_dur)
A method to create grains. Returns an array of BufferTools and sets this BufferTool's instance variable grains to hold the same array.
size - The size of each grain in samples.
max_dur - The total duration of the resultant array of grains. If set to nil, then the array is equal to the duration of this BufferTool.
calc_grains_size_range(min, max, max_dur)
Create grains that very in size between in the min and the max. Returns an array of BufferTools and sets this BufferTool's instance variable grains to hold the same array.
min - The smallest grain size, in samples.
max - The largest grain size in samples.
max_dur - The total duration of the resultant array of grains. If set to nil, then the array is equal to the duration of this BufferTool.
calc_grains_dur(dur)
A method to create grains. Returns an array of BufferTools and sets this BufferTool's instance variable grains to hold the same array.
dur - The duration of each grain in seconds.
calc_grains_dur_range(min_dur, max_dur)
Create grains that very in size between in the min and the max. Returns an array of BufferTools and sets this BufferTool's instance variable grains to hold the same array.
min_dur - The smallest grain duration, in seconds.
max_dur - The largest grain duration in seconds.
calc_grains_num(num, max_dur)
A method to create grains. Returns an array of BufferTools and sets this BufferTool's instance variable grains to hold the same array.
num - The number of grains to create.
max_dur - The total duration of the resultant array of grains. If set to nil, then the array is equal to the duration of this BufferTool.
calc_grains_dur_arr(dur_arr, recurse)
A method to create grains. Sets this BufferTool's instance variable grains to hold the array of grains of the sizes described in the first argument. Returns an array of subgrains.
dur_arr - An array of durations to use to create grains. The method repeats the array durations until it granulates the entire BufferTool.
recurse - The number of equaly sized pieces to chop each grain into. For example, 2 will chop each grain in half. the method returns an array of all the smaller grains. To get the ones described by the dur_arr, either set this to one or look in the BufferTool's grains variable.
free(completionMessage)
Release the buffer's memory on the server and return the bufferID back to the server's buffer number allocator for future reuse. Note that mulitple BufferTools may refer to the same buffer and do not call this unless you mean to quit using all of them.
completionMessage - A valid OSC message or a Function which will return one. A Function will be passed the contained Buffer as an argument when evaluated.