flucoma-sc/release-packaging/HelpSource/Classes/FluidBufCompose.schelp

TITLE:: FluidBufCompose
SUMMARY:: Buffer Compositing Utility
CATEGORIES:: Libraries>FluidDecomposition, UGens>Buffer
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, Classes/Buffer


DESCRIPTION::
A FluidBufCompose object provides a flexible utility for combining the contents of buffers on the server. It can be used for thing like mixing down multichannel buffers, or converting from left-right stereo to mid-side. We use it extensively in our example code.

At its most simple, the object copies the content of a source buffer into a destination buffer. The flexibility comes from the various flags controlling which portions and channels of the sources to use, and by applying gains (which can be positive or negative) to the source data and the portion of the destination that would be overwritten.

It is part of the Fluid Decomposition Toolkit of the FluCoMa project. footnote::
This  was made possible thanks to the FluCoMa project ( http://www.flucoma.org/ ) funded by the European Research Council ( https://erc.europa.eu/ ) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 725899).::

The algorithm takes a srcBuf, and writes the information at the provided dstBuf. These buffer arguments can all point to the same buffer, which gives great flexibility in transforming and reshaping.


CLASSMETHODS::

METHOD:: process
	This method triggers the compositing.

ARGUMENT:: server
	The server on which the buffers to be processed are allocated.

ARGUMENT:: srcBufNum
	The bufNum of the source buffer.

ARGUMENT:: startAt
	The starting point (in samples) from which to copy in the source buffer.

ARGUMENT:: nFrames
	The duration (in samples) to copy from the source buffer.

ARGUMENT:: startChan
	The first channel from which to copy in the source buffer.

ARGUMENT:: nChans
	The number of channels from which to copy in the source buffer. This parameter will wrap around the number of channels in the source buffer.

ARGUMENT:: srcGain
	The gain applied to the samples to be copied from the source buffer.

ARGUMENT:: dstBufNum
	The bufNum of the destination buffer.

ARGUMENT:: dstStartAt
	The time offset (in samples) in the destination buffer to start writing the source at. The destination buffer will be resized if the portion to copy is overflowing.

ARGUMENT:: dstStartChan
	The channel offest in the destination buffer to start writing the source at. The destination buffer will be resized if the number of channels to copy is overflowing.

ARGUMENT:: dstGain
	The gain applied to the samples in the region of the destination buffer over which the source is to be copied. The default value of 0. would overwrite completely, and a value of 1.0 would sum the source to the material that was present.

RETURNS::
	Nothing, as the various destination buffers are declared in the function call.

DISCUSSION::
	It is important to understand the rules used for determining the final desintinaiton buffer dimensions to get the most out of this object. If needs be, the destination buffer will be resized to the maxima of the requsted source numFrames and numChannels. Frames will be written up to the limit of actually available samples (meaning you can create zero padding); channels  will be written modulo the available channels, taking into account the channel offsets, meaning you can have channels repeat or loop into the source buffer's channels. See the examples below.

EXAMPLES::

code::
// load some buffers
(
b = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-AaS-SynthTwoVoices-M.wav");
c = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SA-UprightPianoPedalWide.wav");
d = Buffer.new(s);
)

// with basic params (basic summing of each full buffer in all dimensions)
FluidBufCompose.process(s, srcBufNum: b.bufnum,  dstBufNum: d.bufnum);
FluidBufCompose.process(s, srcBufNum: c.bufnum,  dstBufNum: d.bufnum, dstGain: 1.0);
d.query;
d.play;

//constructing a mono buffer, with a quiet punch from the synth, with a choked piano resonance from the left channel
d.free; d = Buffer.new(s);
FluidBufCompose.process(s, srcBufNum: b.bufnum, nFrames: 9000, srcGain: 0.5, dstBufNum: d.bufnum);
FluidBufCompose.process(s, srcBufNum: c.bufnum, startAt:30000, nFrames:44100, nChans:1, srcGain:0.9, dstBufNum: d.bufnum, dstGain: 1.0);
d.query;
d.play;

//constructing a stereo buffer, with the end of the mono synth in both channels, with a piano resonance in swapped stereo
d.free; d = Buffer.new(s);
FluidBufCompose.process(s, srcBufNum: b.bufnum, startAt: 441000, nChans: 2, srcGain: 0.6, dstBufNum: d.bufnum);
FluidBufCompose.process(s, srcBufNum: c.bufnum, nFrames: 78000, startChan: 1, nChans: 2, srcGain: 0.5, dstStartAt: 22050, dstBufNum: d.bufnum,  dstGain: 1.0);
d.query;
d.play;

//constructing a one second buffer: the first second of each buffer, the mono synth on the right, the piano on the left
d.free; d = Buffer.new(s);
FluidBufCompose.process(s, srcBufNum: b.bufnum, nFrames: 44100, nChans: 1, dstStartChan: 1, dstBufNum: d.bufnum);
FluidBufCompose.process(s, srcBufNum: c.bufnum, nFrames:44100, nChans:1, dstBufNum: d.bufnum,  dstGain: 1.0);
d.query;
d.play;
::

	STRONG::A more complex example: using composition as an Mid-Side filtering process::

	CODE::
// load a stereo buffer and initialise the many destinations
(
b = Buffer.read(s,File.realpath(FluidBufCompose.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SA-UprightPianoPedalWide.wav");
c = Buffer.new(s);
d = Buffer.new(s);
e = Buffer.new(s);
f = Buffer.new(s);
)

// encode the mid (in c) and the side (in d)
(
FluidBufCompose.process(s,b.bufnum, nChans: 1, srcGain: -3.0.dbamp, dstBufNum: c.bufnum);
FluidBufCompose.process(s,b.bufnum, nChans: 1, srcGain: -3.0.dbamp, dstBufNum: d.bufnum);
FluidBufCompose.process(s,b.bufnum, nChans: 1, srcGain: -3.0.dbamp, startChan: 1, dstBufNum: c.bufnum,  dstGain: 1.0);
FluidBufCompose.process(s,b.bufnum, nChans: 1, srcGain: -3.0.dbamp * -1.0, startChan: 1, dstBufNum: d.bufnum,  dstGain: 1.0);
)

// (optional) compare auraly the stereo with the MS
c.query;d.query;
b.play;
{PlayBuf.ar(1,[c.bufnum,d.bufnum])}.play;

// The geeky bit: copy the side (buffer d) on itself with specific amplitudes and delays, in effect applying a FIR filter through expensive convolution

// Important: do either of the 3 options below

// option 1: apply a high pass on the side, with a cutoff of nyquist / 4
e.free; e = Buffer.new(s);
(
[1.0, -1.0].do({ arg x,y;
	FluidBufCompose.process(s, d.bufnum, srcGain: x, dstStartAt: y, dstBufNum: e.bufnum, dstGain: 1.0);
});
)

// option 2: apply a high pass on the side, with a cutoff of nyquist / 10
e.free; e = Buffer.new(s);
(
[0.8, -0.32, -0.24, -0.16, -0.08].do({ arg x,y;
	FluidBufCompose.process(s, d.bufnum, srcGain: x, dstStartAt: y, dstBufNum: e.bufnum, dstGain: 1.0);
});
)

// option 3: apply a high pass on the side, with a cutoff of nyquist / 100
e.free; e = Buffer.new(s);
(
[0.982494, -0.066859, -0.064358, -0.061897, -0.059477, -0.057098, -0.054761, -0.052466, -0.050215, -0.048007, -0.045843, -0.043724, -0.041649, -0.03962, -0.037636, -0.035697, -0.033805, -0.031959, -0.030159, -0.028406, -0.026699, -0.025038, -0.023425, -0.021857, -0.020337].do({ arg x,y;
	FluidBufCompose.process(s, d.bufnum, srcGain: x, dstStartAt: y, dstBufNum: e.bufnum, dstGain: 1.0);
});
)

// play the high-passed side buffer
e.query;
e.play;
// if you want to try the other filters, do not forget to clear the destination buffer since it will add programmatically onto itself and would not create the expected frequency response

// decode the MS back to stereo
(
FluidBufCompose.process(s,c.bufnum, nChans: 2, srcGain: -3.0.dbamp, dstBufNum: f.bufnum);
FluidBufCompose.process(s,e.bufnum, srcGain: -3.0.dbamp, dstBufNum: f.bufnum,  dstGain: 1.0);
FluidBufCompose.process(s,e.bufnum, srcGain: -3.0.dbamp * -1.0, dstBufNum: f.bufnum, dstStartChan: 1, dstGain: 1.0);
)

// query and play
f.query;
f.play;

// compare with the original
b.play;
::