SpatialRender | SuperCollider 3.13.0 Help

Description

A SuperCollider implementation of a Spatial Render. It reads OSC messages in SpatDIF format (from SSWorld or any other Sound Scene Simulator), as well as audio streams from Jack, and renders the corresponding audio.

Three different audio spatialization techniques are available, which can be changed on the fly:

Ambisonics Up to full 3rd order. Decoding is provided externally by the AmbDec software.
WARNING: AmbDec must be installed in the system in order to get the proper spatialized audio. The SpatialRender manages internally the connexions
VBAP Thanks to the VBAP implementation
Binaural Provided by the wonderful Ambisonic Toolkit, first encodes in HOA and then decodes using the HRTF models

It also handles internally a SpatDifLogger with autosaving features for recording the incoming messages.

See 3Dj for a deeper insight into the concepts.

Class Methods

.new

Create a instance of SpatialRender.

Default render parameters are \binaural decoder, \listen head, hrtfID 1002

Arguments:

server

Reference to the server

spatDifLoggerPath

String with the path to the folder in which save the log files.

If nil, the default path "~/.local/share/SuperCollider/SpatialRender" will be used

Discussion:

When a SpatialRender is instanciated, the server is (re)booted, in order to load VBAP and Binaural Buffers.

It also sets the SuperCollider output number to 24 (this parameter is accesible in the variable numAudioOutputs), and sets the required Jack connexions.

Instance Methods

Spatializatoin Techniques

.spatialTechnique

Get the current spatialization technique.

.setSpatializationTechnique

Set the desired spatialization technique. The possible values are either \ambisonics, \binaural or \vbap.

It manages internally the required Jack connexions (and eventually AmbDec instanciation/quit)

Ambisonics

.ambisonicsParameters

Get a Dictionary with the form (sourceName -> [order, shape] )

.setAmbisonicsParameters

If ambisonics is the current spatialization technique, configure its properties.

Arguments:

source	A `Symbol` with the name of one source, or `nil` for applying to all sources NOTE: Notice that, in ambisonics, each source can be encoded in a different order, and with a different shape
order	`Integer` with the desired order. For the moment, between 0 and 3. Default to 3.
shape	One of the following `\point` classical punctual source. Default `\ring` arbitrary width ring-type surface around a virtual sphere's surface `\extended` arbitrary squared surface around a virtual sphere's surface `\meridian` a half meridian shape
internal	Private use

Binaural

.binauralDecoder

Get the current binaural decoder type

.binauralSubjectID

Get the current subject ID for the binaural model used

.setBinauralDecoder

Configure the binaural model, if \binaural is the current spatialization technique.

decoderType should be one of these: \spherical, \listen or \cipic. subjectID is the integer holding the subject code.

NOTE: subjectID number are not consecutive. Please check the reference

For more information about binaural decoders, check FoaDecoderKernel.

Vbap

.vbapSpeakerArray

Get the current vbap speaker configuration

.vbapSpeakerBuffer

Get the current vbap speaker buffer

.vbapNumSpeakers

get the current number of speakers in vbap

.setVbapParameters

Set the vbap speaker configuration.

speakerArray is an instance of VBAPSpeakerArray

Rendering Parameters

.setMaximumAttenuation

Set the maximum attenuation used used for the distance attenuation function. Default to 0.000016.

.setMaximumDistance

Set the maximum source distance used for the distance attenuation function. Default to 62500 m.

.setReferenceDistance

Set the reference distance used for the distance attenuation function. Default to 1 m.

.absorptionModel

.setAbsorptionModel

Select the air absorption model. The possible values are 0 for no model, 1 for standard model, or \default. Default to 1.

Check http://redmine.spatdif.org/attachments/download/105/SpatDIF-specs-V0.3.pdf, Appendix F

.attenuationModel

.setAttenuationModel

Select the distance attenuation model. Possible values are 0 for no model, 1 for higher attenuation model, 2 for lower attenuation model, or \default. Default to 2.

Check http://redmine.spatdif.org/attachments/download/105/SpatDIF-specs-V0.3.pdf, Appendix F

Network Communication

.worldAddresses

Get the list of all Classes/SSWorld addresses where to send back the scene information (in case of SpatDifPlayer playback) or remote control. Multiple addresses are allowed.

At instanciation, the only address available will be NetAddr: -localAddr. It is responsability of the user to provide a correct address, when working in remote.

.addWorldAddress

Add a NetAddress to the SpatialRender: -worldAddresses list.

.removeWorldAddress

Remove a NetAddress from the SpatialRender: -worldAddresses list.

Returns:

The removed NetAddress if succesful, or nil if not.

.resendToWorld

Get/set whether scene information will be resended to all associated SSWorld, when there is no SpatDifPlayer playback.

By default it will be false. User should set it only for remote visualization.

Control

.sourceNames

Get a List with all source names

.receiverFunctions

Get a Dictionary in the form [sourceName -> OSCReceiver function associated]

SpatDIF Logger

A SpatDifLogger instance is provided with the Spatial Render. It is recommended to control it from the following methods.

.spatDifLoggerPath

Get the current path for the SpatDIF log file.

.spatDifLoggerFilename

Get the complete file name for the SpatDIF log file.

.logOSC

Set wheter the SpatDifLogger is active or inactive.

.autosaveOSC

Activate or deactivate the autosave functionality of the log file. Default to true.

.autosavePeriod

Get/set the period between consecutive autosavings of the log file. Default to 10 s.

SpatDIF Player

A SpatDifPlayer instance is provided with the Spatial Render. It is recommended to control it from the following methods.

.spatDifPlayer_load

Load the content of a OSC-SpatDIF file and prepare it for playback.

Arguments:

aFile

String with the path to the file.

.spatDifPlayer_start

Start playback from the beggining of the document.

Arguments:

loop	Set the looping. 1 for one-shot, 2 for two repetitions... inf for eternal repeat

.spatDifPlayer_play

Starts playback from where it was paused last time.

.spatDifPlayer_pause

Pauses playback. Next call to SpatialRender: -spatDifPlayer_play will start from where it was paused.

.spatDifPlayer_stop

Stop playback. Next call to SpatialRender: -spatDifPlayer_play will start from the beginning

.spatDifPlayer_reset

Next call to SpatialRender: -spatDifPlayer_play will start from the beginning

.spatDifPlayer_isPlaying

Answer whether the player is currently playing. See SpatDifPlayer: -isPlaying

.spatDifPlayer_verbose

If true, it will print all sended messages.

Other

.verbose

If verbose is set to true, outcoming messages will be printed

.close

Close all OSCResponders, free all synths, close the OSC Logger file.

.server

Get the used server

Examples

// instanciate a Spatial Render
r=SpatialRender.new(s);

//create a sound scene
(
w = SSWorld([20,20,10]).showView;
o = SSObject(w,loc:[2,0,0],channel:0).setMotion(\orbit)
)

// NOTICE that, even if the object's radius is 1, the render is receiving 2.
// This is because SSWorld adjusts internally the minimum radius to the sweetSpotSize:
w.sweetSpotSize
w.setSweetSpotSize(1)

// by default, the render is verbose. we can change it...
r.verbose_(false)

// each object has a SuperCollider input associated...
o.channel // will answer 0 (default)

// ...which can be setted at any time
o.setChannel(1)

// now, connect something to the second SuperCollider input and listen
// (remember to use headphones, we are using binaural for the moment)

// ......

// // // // // // SPATDIF LOG AND PLAYBACK // // // // // //

// let's say we liked the sound scene we just produced.
// everything is logged in...
r.spatDifLoggerFilename
// ...because the log option is by default set to true
r.logOSC

// we can stop the scene
w.pause;

// and playback it (remember to save the file first!)
(
r.spatDifLogger.save;
r.spatDifPlayer_load(r.spatDifLoggerFilename);
r.spatDifPlayer_start
)

// looping is also allowed
r.spatDifPlayer_start(inf)
r.spatDifPlayer_start(3)

// spatDifPlayer is verbose by default
r.spatDifPlayer.verbose
r.spatDifPlayer_verbose(false)

// and usual task controls provided
r.spatDifPlayer.pause
r.spatDifPlayer_play
r.spatDifPlayer_reset
r.spatDifPlayer_isPlaying

r.spatDifPlayer_stop

// // // // // // RENDERING PARAMETERS // // // // // //

// we have some options for the distance cues: air absorption and distance attenuation

// let's put another source and listen to them
(
o.setMotion(\static);
o.stop;
o.loc_([2,0,0]);
SSObject(w,loc:[5,0,0],channel:1);
)

// there are two absorption models: 0 (no absorption) and 1 (lpf)
r.absorptionModel
r.setAbsorptionModel(0)

// and 3 attenuation models: 0 (no attenuation), and 1 and 2 (around 1/r^2)
r.attenuationModel
r.setAttenuationModel(0)

// we can also control the attenuation parameters
r.setMaximumAttenuation(0.0002)
r.setMaximumDistance(100);
r.setReferenceDistance(0.5)

// see the SpatialRender helpfile for more information about

// // // // // // SPATIALIZATION PARAMETERS // // // // // //

///// BINAURAL (HTRF)

// there are three different possible spatialization techniques

// by default, the one used is binaural (provided by ATK)
r.spatialTechnique

// we can see the decoder parameters
r.binauralDecoder // \cipic model, ID 65

// and set them. Search the one that most match your perception
r.setBinauralDecoder(\cipic,131)
r.setBinauralDecoder(\listen,1030)
r.setBinauralDecoder(\spherical,0005)

// see FoaDecoderKernel for more info about binaural decoding

///// VBAP

r.setSpatializationTechnique(\vbap)

// by default, a 5.1 speaker array is provided
r.vbapNumSpeakers
r.vbapSpeakerArray
r.vbapSpeakerBuffer

// we can set the speaker array.
// remember that the given speaker order is the output channels order
r.setVbapParameters(VBAPSpeakerArray.new(2,[45,135,-135,-45])) //quad

//// AMBISONICS

// we provide a custom set of ambisonic encoders, up to 3rd order
// decoding is managed by AmbDec

r.setSpatializationTechnique(\ambisonics)
// an instance of AmbDec appeared. Select your choice decoding configuration there

// also the Jack/SC/AmbDec connexions are managed internally. take a look..

// when using ambisonics, every source can have a different order and shape..
r.ambisonicsParameters

// .. thus, we can set them individually or together
r.setAmbisonicsParameters(order:1)
r.setAmbisonicsParameters(\0,order:2)

// source shape should be changed from SSWorld in order to visualize it
w.getObject(\0).shape_(\extended).dAzimuth_(pi/2).dElevation_(pi/4)
w.getObject(\1).shape_(\ring).locSph_(ele:pi/8)
w.getObject(\1).shape_(\meridian).locSph_([3,pi,0])

helpfile source: HelpSource/Classes/SpatialRender.schelp
link::3Dj/Classes/SpatialRender::

SpatialRenderExtension

.new

Arguments:

Discussion:

.spatialTechnique

.setSpatializationTechnique

.ambisonicsParameters

.setAmbisonicsParameters

Arguments:

.binauralDecoder

.binauralSubjectID

.setBinauralDecoder

.vbapSpeakerArray

.vbapSpeakerBuffer

.vbapNumSpeakers

.setVbapParameters

.setMaximumAttenuation

.setMaximumDistance

.setReferenceDistance

.absorptionModel

.setAbsorptionModel

.attenuationModel

.setAttenuationModel

.worldAddresses

.addWorldAddress

.removeWorldAddress

Returns:

.resendToWorld

.sourceNames

.receiverFunctions

.spatDifLoggerPath

.spatDifLoggerFilename

.logOSC

.autosaveOSC

.autosavePeriod

.spatDifPlayer_load

Arguments:

.spatDifPlayer_start

Arguments:

.spatDifPlayer_play

.spatDifPlayer_pause

.spatDifPlayer_stop

.spatDifPlayer_reset

.spatDifPlayer_isPlaying

.spatDifPlayer_verbose

.verbose

.close

.server

SpatialRender
Extension