FoaEncoderKernel

Source: /usr/local/share/SuperCollider/Extensions/SC3plugins/ATK/Classes/ATKMatrix.sc

Inherits from: Object

Description

Generates encoding kernels required by the Ambisonic Toolkit's first order encoder, FoaEncode.

NOTE: The ATK kernels are required for kernel encoding. Please see the instructions here for installation.

Class Methods

*newSuper (kernelSize, server, sampleRate, score)

Ambisonic Super Stereo encoder.¹

Arguments:

kernelSize	256, 512, 1024, 2048, 4096, 8192
server	Server on which to load kernel.
sampleRate	The sample rate defaults to `nil` and is usually supplied by the running server. In NRT, you can specify a sampleRate to avoid booting a server.
score	Default is `nil` for most real time usages. When using NRT, you can supply a score (a Score or a CtkScore) onto which the kernels will be added, which lets you bypass booting a server.

Discussion:

The Super Stereo encoding technique is the classic method for encoding stereophonic signals into B-format.

*newUHJ (kernelSize, server, sampleRate, score)

Ambisonic UHJ stereo encoder.²

Arguments:

kernelSize	256, 512, 1024, 2048, 4096, 8192
server	Server on which to load kernel.
sampleRate	The sample rate defaults to `nil` and is usually supplied by the running server. In NRT, you can specify a sampleRate to avoid booting a server.
score	Default is `nil` for most real time usages. When using NRT, you can supply a score (a Score or a CtkScore) onto which the kernels will be added, which lets you bypass booting a server.

Discussion:

The UHJ encoder offers access to numerous published recordings³ for periphonic (2D) audition.

NOTE: For optimal performance, use a dual-band decoder ( 'dual' ) for monitoring. See discussion here.

*newSpread (subjectID: 6, kernelSize: 2048, server, sampleRate, score)

Frequency spreading mono encoder.

Arguments:

subjectID	0 to 12. Specifies the number of bands per octave of the frequency spreader. 0 returns 1 band per octave, etc.
kernelSize	512, 1024, 2048, 4096, 8192, 16384
server	Server on which to load kernel.
sampleRate	The sample rate defaults to `nil` and is usually supplied by the running server. In NRT, you can specify a sampleRate to avoid booting a server.
score	Default is `nil` for most real time usages. When using NRT, you can supply a score (a Score or a CtkScore) onto which the kernels will be added, which lets you bypass booting a server.

Discussion:

The frequency spreading technique encodes a monophonic signal into B-format by smoothly rotating the signal across the soundfield sphere, by frequency.

NOTE: As the number of bands per octaves increases, more time domain artefacts are introduced. This is usually heard as smearing in time.

*newDiffuse (subjectID: 3, kernelSize: 2048, server, sampleRate, score)

Frequency diffusion mono encoder.

Arguments:

subjectID	0 to 5. Specifies the amount of phase dispersion of the frequency diffuser. 0 is low, 5 is high.
kernelSize	512, 1024, 2048, 4096, 8192, 16384
server	Server on which to load kernel.
sampleRate	The sample rate defaults to `nil` and is usually supplied by the running server. In NRT, you can specify a sampleRate to avoid booting a server.
score	Default is `nil` for most real time usages. When using NRT, you can supply a score (a Score or a CtkScore) onto which the kernels will be added, which lets you bypass booting a server.

Discussion:

The frequency diffusion technique encodes a monophonic signal into B-format by randomising the phase of the signal across the soundfield sphere, by frequency.

NOTE: As the diffusion increases, more time domain artefacts are introduced. This is usually heard as smearing in time.

Inherited class methods

Instance Methods

-set

Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.

Answers 'FOA', aka traditional B-format:

Ambisonic Order Channel Ordering Channel Normalisation
1st Gerzon (aka Furse-Malham) MaxN

-type

Returns:

'encoder'

-op

Answers 'kernel', i.e. the type of operation used to compute the resulting signals.

-kind

Answers the kind of encoder

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.kind

// don't forget to free!!
~encoder.free

-subjectID

Answers the subjectID of the decoder

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.subjectID

// don't forget to free!!
~encoder.free

-dim

Answers the number of decoder dimensions: 2D or 3D.

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.dim

// don't forget to free!!
~encoder.free

-numChannels

Answers the number of input channels.

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.numChannels

// don't forget to free!!
~encoder.free

-dirChannels

Answers the direction of input channels, with angles in radians.

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newSuper

// inspect
~encoder.dirChannels.raddeg

// don't forget to free!!
~encoder.free

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.dirChannels.raddeg

// don't forget to free!!
~encoder.free

-kernel

Answers the encoder kernel.

Discussion:

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.kernel

// don't forget to free!!
~encoder.free

-kernelSize

Answers the kernelSize.

Discussion:

Use of FoaEncoderKernel introduces a delay to the encoded B-format signal.

The total delay, in samples, can be calculated as (kernelSize-1)/2 + kernelSize - blockSize, where blockSize is the number of samples in one control period of the Server in use.

// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newUHJ

// inspect
~encoder.kernelSize

// calculate delay in samples
(~encoder.kernelSize-1)/2 + ~encoder.kernelSize - s.options.blockSize

// calculate delay in seconds
((~encoder.kernelSize-1)/2 + ~encoder.kernelSize - s.options.blockSize) / s.sampleRate

// don't forget to free!!
~encoder.free

-free

Free the kernel.

Discussion:

Release the kernel buffer's memory on the server and return the bufferID back to the server's buffer number allocator for future reuse.

WARNING: Only free the kernel when the FoaEncode: *ar is no longer in use!

Returns:

for 2D: [ inf, inf, inf ]
for 3D: [ inf, inf, inf , inf ]

Inherited instance methods

Examples

Please see FoaEncode: Examples.

[1] - See: https://en.wikipedia.org/wiki/Ambisonic_UHJ_format#Super_stereo

[2] - See: http://en.wikipedia.org/wiki/Ambisonic_UHJ_format

[3] - Nimbus Records' primary output is in Ambisonic UHJ. See: http://en.wikipedia.org/wiki/Nimbus_Records And: http://www.wyastone.co.uk/index.php

helpfile source: /usr/local/share/SuperCollider/Extensions/SC3plugins/ATK/HelpSource/Classes/FoaEncoderKernel.schelp
link::Classes/FoaEncoderKernel::
sc version: 3.9dev

Ambisonic Order	Channel Ordering	Channel Normalisation
1st	Gerzon (aka Furse-Malham)	MaxN

FoaEncoderKernelExtension

Description

Class Methods

*newSuper (kernelSize, server, sampleRate, score)

Arguments:

Discussion:

*newUHJ (kernelSize, server, sampleRate, score)

Arguments:

Discussion:

*newSpread (subjectID: 6, kernelSize: 2048, server, sampleRate, score)

Arguments:

Discussion:

*newDiffuse (subjectID: 3, kernelSize: 2048, server, sampleRate, score)

Arguments:

Discussion:

Inherited class methods

Instance Methods

-set

-type

Returns:

-op

-kind

Discussion:

-subjectID

Discussion:

-dim

Discussion:

-numChannels

Discussion:

-dirChannels

Discussion:

-kernel

Discussion:

-kernelSize

Discussion:

-free

Discussion:

-numInputs

-dirInputs

-numOutputs

-dirOutputs

Returns:

Inherited instance methods

Examples

FoaEncoderKernel
Extension