FoaEncoderKernel:
Filter:
atk-sc3/Classes (extension) | Libraries > Ambisonic Toolkit > Matrix & Kernel > FOA

FoaEncoderKernel
ExtensionExtension

First Order Ambisonic (FOA) encoder kernels

Description

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

You can review the overall design specifications of the ATK's kernels sets, here, and details on the individual encoder kernels, here.

NOTE: The ATK kernels are required for kernel encoding. Please see Atk: Installation of ATK dependencies for instructions.

Class Methods

.newSuper

Ambisonic Super Stereo encoder.1

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

Ambisonic UHJ stereo encoder.2

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 recordings3 for periphonic (2D) audition.

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

.newSpread

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

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.

Instance Methods

Information

.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 OrderChannel OrderingChannel Normalisation
1stGerzon (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:

.subjectID

Answers the subjectID of the decoder

Discussion:

.dim

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

Discussion:

.numChannels

Answers the number of input channels.

Discussion:

.dirChannels

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

Discussion:

.directions

A synonym for -dirChannels

.numInputs

A synonym for -numChannels

.dirInputs

A synonym for -dirChannels

.numOutputs

Answers the number of outputs for the decoder. 3 for 2D and 4 for 3D.

.dirOutputs

A convenience method providing polymorphism with FoaDecoderKernel: -dirOutputs.

Returns:

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

Kernel

.kernel

Answers the encoder kernel.

Discussion:

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

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

Examples

Encoding-FOA

[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: HelpSource/Classes/FoaEncoderKernel.schelp
link::atk-sc3/Classes/FoaEncoderKernel::