FoaDecoderKernel

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

Inherits from: Object

Description

Generates decoding kernels required by the Ambisonic Toolkit's first order decoder, FoaDecode.

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

Class Methods

*newUHJ (kernelSize: 512, server, sampleRate, score)

Ambisonic UHJ stereo decoder.¹

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:

For production work targeting stereo output, the authors advise using UHJ, as Ambisonic UHJ stereo is the native Ambisonic stereo format.

*newSpherical (subjectID: 4, server, sampleRate, score)

Synthetic spherical head model HRTF² decoder, equalised for the diffuse field.

Arguments:

subjectID	0 to 9
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:

-newSpherical models a sphere only, and is equivalent to placing a pair of spaced, sphere baffled microphones in the soundfield. With no pinnae and no body, elevation cues are not present.

The subjectID argument varies to suit listener head width, with 0 the smallest and 9 the largest head. The user is advised to audition to find a suitable choice.

*newListen (subjectID: 1002, server, sampleRate, score)

Measured HRTF decoder, with measurements from IRCAM's Listen HRTF database ³ equalised for the diffuse field.

Arguments:

subjectID	1002 to 1059 (51 in total) WARNING: subjectIDs are not entirely contiguous.
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 user is advised to audition subjectIDs to find a suitable choice. If an invalid subjectID is chosen, valid choices are returned.

// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newListen(0)

// make sure you scroll up to see the resulting valid subjects!

*newCIPIC (subjectID: 21, server, sampleRate, score)

Measured HRTF decoder, with measurements from the University of California Davis' CIPIC HRTF database ⁴ equalised for the diffuse field.

Arguments:

subjectID	3 to 165 (45 in total) WARNING: subjectIDs are not entirely contiguous.
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 CIPIC HRTF database provides two KEMAR dummy measurements. subjectID = 21 is the large pinnae dummy and subjectID = 165 is the small pinnae dummy.

The user is advised to audition subjectIDs to find a suitable choice. If an invalid subjectID is chosen, valid choices are returned.

// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newCIPIC(0)

// make sure you scroll up to see the resulting valid subjects!

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:

'decoder'

-op

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

-kind

Answers the kind of decoder

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kind

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kind

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

-subjectID

Answers the subjectID of the decoder

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.subjectID

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.subjectID

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

-dim

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

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newSpherical

// inspect
~decoder.dim

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dim

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

-numChannels

Answers the number of loudspeaker (or headphone) feeds (output channels).

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.numChannels

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

-dirChannels

Answers the direction of loudspeaker (or headphone) feeds, with angles in radians.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.dirChannels.raddeg

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dirChannels.raddeg

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

-kernel

Answers the decoder kernel.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernel

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernel

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

-kernelSize

Answers the kernelSize.

Discussion:

Use of FoaDecoderKernel introduces a delay to the decoded 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.

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernelSize

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

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

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

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernelSize

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

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

// don't forget to free!!
~decoder.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 FoaDecode: *ar is no longer in use!

Returns:

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

Inherited instance methods

Examples

Please see FoaDecode: Examples.

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

[2] - See: R. O. Duda, "Modeling head related transfer functions," in Proceedings of the Twenty-Seventh Annual Asilomar Conference on Signals, Systems and Computers, Asilomar, CA, 1993.

[3] - See: http://recherche.ircam.fr/equipes/salles/listen/

[4] - See: http://interface.cipic.ucdavis.edu/sound/hrtf.html

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

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

FoaDecoderKernelExtension

Description

Class Methods

*newUHJ (kernelSize: 512, server, sampleRate, score)

Arguments:

Discussion:

*newSpherical (subjectID: 4, server, sampleRate, score)

Arguments:

Discussion:

*newListen (subjectID: 1002, server, sampleRate, score)

Arguments:

Discussion:

*newCIPIC (subjectID: 21, 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:

-numOutputs

-dirOutputs

-numInputs

-dirInputs

Returns:

Inherited instance methods

Examples

FoaDecoderKernel
Extension