Category: AudioObjectDeveloper

Some objects may require CPU intensive tasks that do not need to execute immediately. For this purpose xAF offers the background process. To enable this functionality the object will override backgroundMethod and hasBackgroundMethod. hasBackgroundMethod needs to return true. Within the method, the object can do whatever it wants. This method will be interrupted by other threads; even the object’s calc method. For this reason, the logic in this method must be implemented in a protective, thread-safe manner.

virtual void CAudioObject::backgroundMethod () {};
virtual bool CAudioObject::hasBackgroundMethod () const
{
    return FALSE;
}

A number of features are planned for debugging and monitoring but currently, live streaming is implemented and described below.

Live streaming of state variable or state memory

To enable live streaming for a particular state variable, below steps needs to be performed by the audio object.

1. The XML section of the state variable has to be updated to convey that state variable is streamable to GTT. The optional variable after the bit converter has to be set to true to enable the state variable streaming.
The code snippet from CTemplate::getXmlObjectTemplate function conveys to GTT that the state variable “State1Value” is enabled for streaming by setting the optional variable after bit converter to true.

2. For uploading data from framework to GTT, the following public functions have to overridden or implemented:

• CAudioObject::getStateMemForLiveStreamingPtr
• CAudioObject::getDataFormatForLiveStreamingPtr

CAudioObject::getStateMemForLiveStreamingPtr () take in 4 arguments representing streamIndext, subBlockId, pointer to hold memory address of the state variable (stateMem) and the number of the bytes to be streamed (len). The streamIndext and subBlockId are passed into the audio object to enable the calculation of which channel of the state variable to be streamed. Based on the calculation done, the audio object has to update the variables stateMem and len. The code snippet from CTemplate::getStateMemForLiveStreamingPtr shows the example implementation. In this example code, subblock is not used for state variable and hence subBlockId has to be always zero. The first state variable (with streamIndex 0) is mute which is not enabled for streaming in XML file. The state variables (streamIndext 1 to 6) is enabled for streaming in XML file and stateMem and len is updated. The len argument of the function getStateMemForLiveStreamingPtr conveys that how many bytes are going to be streamed. If only one float value is going to be streamed then value for len is 4. If n number of float values need to be streamed, then variable len has to be 4 times n. Also, audio object has to make sure that len number of bytes are allocated for the state variable and the starting address is assigned to stateMem variable.

CAudioObject::getDataFormatForLiveStreamingPtr() take in 2 arguments representing streamIndext and subBlockId. The streamIndext and subBlockId are passed into the audio object to return the data format of the state variable to be streamed. The code snippet from CTemplate::getDataFormatForLiveStreamingPtr shows the example implementation. In this example code, subblock is not used for state variable and hence subBlockId has to be always zero. The first state variable (with streamIndex 0) is mute which is not enabled for streaming in XML file. The state variables (streamIndext 1 to 6) is enabled for streaming in XML file and the corresponding data format is returned from this function.

3. Data from framework to GTT is sent based on the value commands per second of the state variable which is sent from GTT.

The framework does the below calculation to decide on which call it needs to send data to GTT.

• Number of blocks per second = SampleRate / BlockLength
• Blocks per message = Number of blocks per second / commands per second

The amount of data to be send is based on the below calculation.

• Bytes per message = Header size + len
  where
  • Header size is 5.
  • len is in bytes.

The framework sends Bytes per message amount of data to GTT for every Blocks per message.

Example #1:
SampleRate = 48000, BlockLength = 64, len = 4 and commands per second = 10

Number of blocks per second = 48000 / 64 = 750
Blocks per message = 750 / 10 = 75
Bytes per message = 5 + 4 = 9
The framework sends 9 bytes of data to GTT for every 75th block.
Bytes per second = (9 * 10) bytes per sec = 90 bytes per sec

Example #2:
SampleRate = 48000, BlockLength = 64, len = 128 and commands per second = 6

Number of blocks per second = 48000 / 64 = 750
Blocks per message = 750 / 6 = 125
Bytes per message = 5 + 128 = 133
The framework sends 133 bytes of data to GTT for every 125th block.
Bytes per second = (133 * 6) bytes per sec = 798 bytes per sec

This guide is intended to help developers in creating audio objects in the Extended Audio Framework (xAF). The framework act as a gateway between the audio object and the outside world.

This guide covers the following topics:

• An overview on how audio objects interact with the framework, including the order in which the framework interacts with the audio object.
• Details on the audio object configuration in the design tool and how to set it up.
• Basic Features and APIs
• Advanced features and APIs.
• An example of a template audio object, which will include a reference implementation for all of the items mentioned above.
• An explanation of how to connect external audio objects to the framework.
• Information on the general guidelines that xAF objects should follow.

Terms and Abbreviations

Terms

• Global Tuning Tool (GTT): Global tuning tool is used to configure the audio algorithm framework seamlessly and intuitively, as well as to tune algorithm.
• Run-Time: When a signal flow is deployed and running on a target device.
• Design time: Design-time is referred when a signal flow is being designed in the GTT signal flow designer. At that point nothing is running on a target device.
• Tuning variables/Tuning parameters: These are the variables within audio objects that are modifiable through a set/parameter file change. These variables are also modifiable from GTT at runtime. For example, a channel gain value within a gain object that can be modified during a set file change is considered a tuning variable.
• State variables / State tuning parameters: These are the variables within audio objects that are modifiable at runtime from GTT or from other embedded code. These variables are not saved in a set / parameter file. For example, a channel volume value within a volume object that can be modified during runtime is considered a state variable.
• Metadata: Metadata is data provided by the object developer to GTT at design time. This data is not used at runtime. It is usually provided in the object toolbox file which is compiled only for GTT. Examples of metadata the object will send GTT are:
  • Description of the object control inputs and outputs
  • What processors the object is supported on
  • What block sizes and sample rates the object can operate at

Abbreviations

xAF: Extendable Audio Framework	BAO: Basic Audio Object
GTT: Global Tuning Tool	SR: Sample Rate
SFD: Signal Flow Designer	BL: Block Length
xTP: Extendable Tuning Protocol	VST: Virtual Studio Technology
HU: Head Unit	AWX: AudioworX

Requirements

This is the document that audio object developers should use as reference when creating audio objects for the xAF framework.

Req. ID	Req. Name	Description	Comment
CASCCGAF-210		Developers guide to create object for xAF document

Design Time Work flow

The work flow during design time is described below. Design time is when the user is creating a signal flow from the Signal Flow Design tool within GTT. These are the interactions that go on between the tool and dll loaded into the tool:

Runtime Workflow

The workflow during runtime between the framework class, CAudioProcessing, and the audio objects base class, CAudioObject, is described below.