The ARA API is designed to be consistent, simple-to-use and very flexible. It tries not to rely on any assumptions about the actual implementation on either side.
Various parts of the API are optional, allowing both ARA-capable hosts and plug-ins to only support those aspects of ARA that are meaningful within their particular context. Each side should strive to make as much of its functionality available to the other side as possible, but should not make any assumption about how exactly that functionality will actually be used.
A good example for this pattern is the exchange of analysis results: if asked for it, the plug-in will deliver all data it can possibly derive via its analysis capabilities, but building features like audio-to-MIDI conversion or synchronizing and quantizing live recordings based on the plug-in's analysis is entirely up to the host - it may come up with features that the plug-in's creators never thought of.
Each implementation of ARA relies on an established plug-in standard that is used as a companion standard to the ARA API. Currently, VST3 and Audio Units are supported. The companion API defines all the usual tasks for audio plug-ins such as discovering and loading plug-in binaries, configuring and executing both realtime and offline rendering, providing a user interface for the plug-in and so on.
Lightweight extensions to the companion API then provide access to the additional ARA-specific functions for managing the ARA model, providing plug-ins with random access to the audio data, etc. These ARA interfaces are defined generically and are independent of the companion API in use, allowing developers to decouple the bulk of their ARA-related codebase from the particular companion API they are supporting.
The companion API itself will still be used strictly according to its definitions and rules, ARA does not abuse or re-define its features.
The decision to design ARA as such an extension to various established plug-in standards was made to keep the implementation efforts for both hosts and plug-ins adopting ARA as small as possible. It serves this purpose well on the technical side, but it unfortunately also blurs the lines what an ARA-enabled plug-in actually is and how it should be used.
An ARA-enabled plug-in is not simply an established realtime plug-in with some extra features, but rather a whole new breed of plug-in that has different capabilities and constraints. Both hosts and plug-ins must reflect this distinction in their implementations and conceptually separate an ARA-enabled plug-in from its non-ARA-enabled counterpart: Although they live in the same binary, each version is to be treated as a separate and incompatible plug-in.
Hosts can provide both versions next to each other and let the user choose which to insert (e.g. Logic Pro X), or can automatically prefer the ARA-enabled version if the insert point is suitable for ARA (i.e. first in chain) and fall back to the non-ARA version otherwise (e.g. Studio One). Other hosts (e.g. Cubase) implement explicit ARA and non-ARA plug-in insert points.
The Melodyne online manual provides a comprehensive description of various ARA host behaviors.
The distinction between ARA and non-ARA variant also extends to persistency: settings from the ARA version cannot be loaded by the non-ARA version and vice versa. Host documents must encode this distinction accordingly in order to be properly restorable. Documents created before the adoption of ARA must keep using the non-ARA variant.
There are several other, more subtle semantic distinctions between ARA and non-ARA plug-in usage, they will be noted throughout this document and in the ARA headers.
For highest compatibility with existing code and to work with all established plug-in formats, the ARA interface is defined in C99, making it easy to interface with other programming languages as needed.
Because of its widespread use, extra effort was put into convenient C++11 compatibility (namespaces, constants definitions, calling conventions). The supporting library code wraps the ARA API into C++11 classes and utilities.
The ARA API itself does not depend on a certain compiler or OS version.
The ARA library code heavily relies on C++11 and is therefore set up to compile with Xcode 8 for Mac OS X 10.9 or higher and with Microsoft Visual Studio 2017 for Windows 8.1 or higher.
We've also experimented with compiling the ARA SDK on Linux (Ubuntu 18.0.4) using gcc 8.3 and clang 7.0 with the provided CMake files - see ARA_Examples/CMakeLists.txt for more details.
While largely agnostic to the underlying platform, only x86 and x86-64 compatible systems are currently tested and supported. ARM64 will be supported in a future update.
In order to provide a compiler-independent binary-compatible API, ARA needs to use types with defined sizes. It does so by specifying typedefs for all data types used in the API. These typedefs are set up depending on the compiler in use to ensure compatible data type sizes.
There are some implications of this: for one, enum types cannot be used in the API directly, because their size is implementation-dependent. Instead, for each enum a matching integer type is introduced in the API, which must always carry values from the enumeration only.
Along the same lines, we're not using stdbool.h, but rather define a fixed-sized ARABool for the API.
Most structs in the ARA API contain a member indicating their size. This is used to provide a simple versioning scheme for extending the API in a backwards-compatible way. Later revisions can append new members at the end of the struct and define default behavior that is to be assumed whenever the struct does not yet contain the new members at runtime.
Basing the versioning on the size of the struct rather than defining abstract API version numbers has the advantage of more readable code, because as a programmer you don't need to know which version of the struct contains which fields. Instead, you explicitly check for the presence of a given field by comparing the struct size, which is close to what -respondsToSelector: allows for in Objective-C and similar to COM's queryInterface().
In addition to this backwards-compatible versioning via struct sizes, ARA also features API generations, which allow for incompatible API changes should the need arise.
For more information, see the Versioned Structs and API Generations, respectively, of the API reference.
While written in C, ARA uses an object-oriented design that can be easily bridged to and from C++ and other object oriented languages. ARA objects are identified at runtime using strongly typed, opaque references called ARA...Ref for plug-in objects and ARA...HostRef for host objects. These references are pointer-sized identifiers bound to a certain object class.
In typical implementations such as in the accompanying example code, the ARA references hold the C++ this pointer, but it also may contain an index into an array of structs or whatever else fits the given implementation.
Each ARA...Ref only has a meaning on the plug-in side; on the host side it is an opaque token that is simply passed along whenever calling into the plug-in. The same principle applies the other way around for ARA...HostRef. For example, objects that represent areas of audio playback are referred to on the plug-in side via a ARAPlaybackRegionRef, whereas the equivalent objects in the host are referred to via a ARAPlaybackRegionHostRef.
Actual ARA object instances are never shared between the host and the plug-in. Instead, the host uses dedicated functions to create ARA objects on the plug-in side, which are then addressed using their opaque ARA...Ref, and vice versa (ARA...HostRef). Amongst other benefits, this allows for running the plug-ins and the host in separate address spaces.
The caller of the creation function is responsible for properly managing the life time of the ARARef / ARAHostRef. and its associated ARA object by calling a matching destruction function when appropriate. Typically, this is easy to implement because both the host and the plug-in already have a life-time management for their internal model objects in place, and the additional management of the corresponding objects on the other side can be directly coupled to this existing code.
Following the Model-View-Controller pattern, ARA distinguishes between abstract model objects that are hardly more than "plain-old-data" types and operational controller objects that manipulate those model objects and the relationships between them.
Defining the API boundary at controller level and representing the model objects with abstract tokens allows for maximum flexibility when interfacing ARA with a given code base: instead of having to code a set of predefined ARA model classes, existing infrastructure can be leveraged to represent the ARA model data with only minimal glue code at controller level translating between the ARA abstractions and the existing implementation.
The interface of any given controller object is expressed as a set of function pointers, which are defined according to the class of the object. This matches the concept of e.g. the vtable in C++, but there is no direct binary compatibility because vtables contain private, language and compiler implementation dependent data. Instead, ARA defines simple C structs containing the function pointers.
For an example of a simple interface, see the ARAPlaybackControllerInterface.
In the established plug-in standards, no model data is shared between the individual plug-in instances. This works well because the access to the audio data or the timing information is always limited to the small window of the current realtime rendering block.
With ARA however, this window is lifted and thus much more information is exchanged between the host and the plug-ins. Creating copies of this potentially memory-intense information for each plug-in instance is too expensive, so ARA avoids this by establishing the concept of a document which contains the model graph and is shared between compatible plug-in instances. ARA documents typically represent a "song" or "project" within the host, and hosts can support multiple documents simultaneously.
The ARA document is not managed by any of the plug-in instances, but rather by a new, separate entity called the ARA document controller in a 1:1 relationship. The document controller is the gateway to the ARA model graph - when plug-in instances are created via the companion API to perform tasks such as rendering audio or displaying model data in the UI, they will use the document controller to access the model graph.
It is possible to use an ARA document controller without any accompanying plug-in instance, e.g. when utilizing the analysis capabilities of a plug-in like Melodyne to extract tempo information from a set of audio files in a background batch process. Using a companion plug-in instance without binding it to a document controller on the other hand will disable all its ARA features because the plug-in will have no access to model data for rendering or display.
To create instances of an ARA document controller, the plug-in provides a static factory. Besides creating actual controller instances, the factory also provides meta information about the controller that is needed e.g. to find the right controller class when loading archives or to find out whether a given controller class is capable of performing a particular background analysis that the host wants to make use of.
If ARA wasn't using established plug-in APIs, then this factory would be the starting point for the contract between plug-in and host. With the companion plug-in APIs in place, ARA adds a call to retrieve the matching ARA factory for a given companion plug-in instance. By supporting this call, a plug-in also indicates towards the host that it is capable of ARA in the first place.
Where the companion API allows for it, ARA further defines an additional entry into the binary to access the factory independently from any plug-in instances. This may be the preferred method of discovery where available.
Once the ARADocumentController is established, the host interacts with it to publish the model graph it wants the ARA plug-in instances to process. This graph exposes the relevant subset of host model objects to the plug-in, and each of these objects is mirrored inside the plug-in. The connection between the host and the plug-in representation of each object is established via the opaque ARA object references discussed above.
The structure of the ARA model graph is entirely controlled by the host: creating and removing objects or changing connections between them is never done by the plug-in, only by the host.
The following provides an overview of the ARA model graph:
The root object of the ARA model graph is the ARADocument, managed by an ARADocumentController in a 1:1 relationship as discussed above.
Each ARADocument can hold a set of ARAAudioSources, representing sampled audio data (such as an audio file) owned by the host. The audio source sample data should be considered immutable - while updating it is technically possible, doing so will typically invalidate all dependent data in the plug-in, described below.
The sample data will usually be analyzed by the ARA-enabled plug-in as needed to accomplish its tasks. The host also has the option to explicitly trigger any analysis it may need to implement certain features.
Note that plug-ins may feature a user interface to fine-tune analysis parameters or to manually override any incorrect analysis results. For an example of this, see Melodyne's online manual.
Based on the audio source analysis, the plug-in will create an internal representation of the content which is the foundation for any edits that the user can apply to the material. These subsequent edits are plug-in-specific and controlled through the plug-in UI exclusively. Their associated states are encapsulated in ARAAudioModification objects which are opaque towards the host.
Each audio modifications can be thought of as mini-arrangement of the sample data of the underlying audio source - it contains the actual creative work of the user.
Because of the tight coupling with the analysis of the underlying audio source samples, audio modification states are typically invalidated whenever these samples are updated, resulting in a loss of productive work. Modifying the audio source samples should therefore be avoided whenever possible.
Note that while an audio source covers a limited time range, an audio modification is conceptually unlimited in time - the user freely can re-arrange the audio source data, and in that process it's possible to copy&paste data before the start or behind the end of the original audio source. The host should therefore allow the user to "resize" audio modifications arbitrarily to cover any time range.
It is possible to create more than one audio modification per audio source, so that the user can create various musical variations of the same audio source material.
A comparable pattern is already established in many advanced MIDI editors: when duplicating MIDI data inside an arrangement, the user often has the option to either create an alias that will reflect all later edits applied to the original data, or to create an individual copy of the data that will no longer be influenced by changes to the original. In terms of the ARA model, an individual copy would be represented by a new audio modification being created ("cloned"), whereas an alias would simply refer to the original modification.
To arrange the modified audio within the song, the host will create ARAPlaybackRegions which describe segments of audio modifications that are to be rendered in a specific timing context. Playback regions can be augmented with specific transformations like time-stretching and content based fades, as detailed later on. Such a playback region usually matches objects termed "audio region" or "audio event" in current DAWs.
Playback regions can be grouped by the host into ARARegionSequences - typically this grouping is done according to their arrangement in the song, i.e which "track" or "lane" the regions are on in the song.
The term region sequence was chosen so it will not collide with the many different usages of the term "track" across existing DAWs: channels in the mixer, lanes in the arrangement, hierarchies/folders of such lanes, or even entire songs.
In their arrangements, host usually define a musical map describing changes in tempo and scale or chord progressions. ARA encapsulates this data in an object called an ARAMusicalContext . Each region sequence (and therefore each region contained in the sequence) is associated with a musical context.
The following screenshot demonstrates how Logic Pro maps its internal model to the ARA model graph.
The ARA objects discussed have explicit and well-defined properties that are initialized by the host upon creation - these properties may be updated at any time as long as the updates occur within an edit cycle. For example, hosts may use an edit cycle to update the start and end time of a playback region or the color of a region sequence.
Both plug-in and host also have internal data structures that contain much more information about the object, such as the results of the analysis of an audio source inside the plug-in or the signatures of a song timeline inside the host. This content information may or may not be present, and the internal format for it may be completely different in each program.
To exchange this information between plug-in and host ARA establishes content readers, which are temporary objects used to iterate content information in a normalized format. They will be detailed in a later section of this document.
The structure of the model graph and the properties of the objects therein are directly controlled by the host via the document controller, and it also directly notifies the plug-in about whenever it needs to update content information due to user edits in the host.
If the content on the plug-in side is modified, the plug-in must notify the host accordingly - the host polls for these updates when it is idle.
A key feature of ARA is the ability to exchange information about the musical content of ARA objects. This communication can work both ways - for example the host can ask a plug-in to execute an analysis of an audio source and then query its results, but it also can provide the plug-in with information about the audio source up-front, such as the tempo map used when recording the audio.
Most importantly, the host uses this API facility to describe the content of the musical context in which the playback regions will be rendered in.
To suit the very different capabilities and needs of the various plug-ins and hosts, ARA defines a set of content types that may or may not be supported by either the plug-in or the host. Due to the sequential nature of music, each content type is encoded as a series of content events in time. Each event is represented by a particular ARA content struct associated with the content type.
The most prominent example of an content type are musical notes, which can be described via start, length, average volume and pitch just like MIDI does. ARA defines a basic note event type like so:
typedef struct ARAContentNote
{
// average frequency in Hz, kARAInvalidFrequency if note has no defined pitch (percussive)
float frequency;
// index corresponding to MIDI note number (or kARAInvalidPitchNumber)
ARAPitchNumber pitchNumber;
// normalized level: 0.0f (weak) <= level <= 1.0f (strong)
// This value is scaled according to human perception
float volume;
// time marking the beginning of the note (aka "note on" in MIDI), relative to
// the start of the described object (audio source/playback region)
ARATimePosition startPosition;
// time marking the musical/quantization anchor of the note,
// relative to the start of the note
ARATimeDuration attackDuration;
// time marking the release point of the note (aka "note off" in MIDI),
// relative to the start of the note
ARATimeDuration noteDuration;
// time marking the end of the entire sound of the note (end of release phase),
// relative to the start of the note
ARATimeDuration signalDuration;
} ARAContentNote;
The amount of data used to represent content information can be very large. ARA therefore does not transfer all information about all events in a single transaction. Instead, it leverages the common iterator pattern by defining content event readers.
Code that wants to read certain content information can use a reader object bound to a given ARA model object, content type and time range. This pulling is done in small and fast transactions.
To keep the amount of transferred data small, the data structs returned by the content reader are not versioned like other ARA structs. Extending the data provided by the content readers in a new version of ARA will instead be done by simply adding new content types.
Besides providing (or not providing) the actual information, it is possible to also specify a quality for it, named "content grade". This is particularly useful when trying to resolve potentially conflicting information such as a plug-in detecting a tempo of 140 bpm when the host claims a tempo of 120 bpm.
For example, when making up some default value for initializing model data without any correlation to the actual music, such as assuming a default tempo of 120 bpm for a new song, this information would be accordingly qualified as "initial".
If the values are then determined via an analysis of the material, the grade would be upgraded to "analyzed". If modified by the user, it would become "adjusted".
There is an even higher grade of quality called "approved" which is typically not achieved by normal editing. Instead, this would be used by content creators to explicitly mark the current state of information as "correct" to prevent further adjustments by end-users.
It may be surprising at first that events are counted using an ARAInt32, not an ARASize data type which would extend to 64 bit on the according platforms. However this was done to emphasize that these events are entities that the user must be able to comprehend and manually edit, so 32 bits are way beyond the upper limits applicable here.
As explained above, the structure of the ARA model graph is exclusively controlled by the host. Plug-ins will augment the ARA model graph with their internal application specific model data. Changes to this internal data may be explicitly triggered by user edits in the plug-in UI or may happen automatically, i.e when applying the results of an audio source analysis that has been executed in the background.
To prevent collisions between these various sources for changes to the graph, ARA requires that changes to the model graph must be applied serially on the main thread (either by applying them on the main thread or by blocking the main thread while applying it from a different thread).
Furthermore, edits by the host must be grouped into explicit edit cycles during which the plug-ins can suppress any pending internal edits, which is important to keep the undo history in both the host and the plug-in consistent.
Here's a code example illustrating the use of an edit cycle if the user renames the current ARA document:
// start the edit cycle araDocumentController->beginEditing (); // update the document name ARADocumentProperties documentProperties; documentProperties.structSize = ARA_IMPLEMENTED_STRUCT_SIZE (ARADocumentProperties, name); documentProperties.name = "Updated Document Name"; araDocumentController->updateDocumentProperties (&documentProperties); // end the edit cycle araDocumentController->endEditing ();
Using edit cycles has a number of further benefits. First of all, it defines an explicit window of time (i.e. anytime outside the editing cycle), where both the host and the plug-in are guaranteed to be in sync, and render results thus are well-defined. This is important if a plug-in has some sort of lag between changing the model graph and actually making the results audible, e.g. because it has to update large caches - the plug-in will not return from endEditing() until these updates are finished.
Edit cycles also allow plug-ins to optimize performance when there are interdependencies between ARA objects - updates of their internal model data may be delayed until the end of the editing cycle when the new ARA graph is fully known to suppress unneccessary intermediate calculations.
Consequently, hosts should take care to group all related graph changes into a single edit cycle where possible instead of implementing multiple edit cycles which each contain only a subset of the changes..
Further, plug-in implementations may have to take special action from beginEditing() and endEditing() to ensure that any ongoing realtime or offline rendering can still access a consistent graph despite the ARA model being edited concurrently.
Note that access to audio source samples can be enabled or disabled outside of an edit cycle because this is considered a controller operation not a model edit - see the audio access section for more information.
When archiving an ARA model graph, three interconnected parts must be preserved: the host internal data, the resulting ARA graph structure shared between host and plug-in, and the plug-in internal data that is attached to it. As discussed above, the ARA graph structure is described using runtime object references. When restoring an ARA archive, hosts will first restore their internal model, then re-create the ARA graph. Once these ARA objects are created, the plug-in will restore their internal data.
Since the runtime references have changed since the graph was stored, the plug-in needs a way to map stored state into the newly created objects. The host therefore must define a unique persistent ID for each persistent ARA object in that object's properties. Both host and plug-in must save this ID alongside their respective data structures and use it when restoring the graph.
To preserve storage space and ease the implementation, only those ARA objects are persistent that contain information that can be modified in the plug-in. For example, the musical context is defined and edited on the host side only. Therefore it can always be re-created from the host state when loading the document. The same goes for playback regions and region sequences.
On the other hand, audio source state containing the analysis results, and audio modification state containing the user edits need to be persistent.
ARA model graphs may be rather huge when including the internal data on both sides, thus the ARA API was designed to deal with large archives efficiently. To avoid high temporary memory peaks, the data is not necessarily transmitted in one large data block. Instead, ARA uses a simple stream-like API that allows to read/write data in smaller chunks.
The stream should be both read and written in a consecutive order whenever possible. In some cases however, repositioning is inevitable, so the host must support it.
Because of its size and complexity, loading and storing an ARA graph may take a noticeable amount of time. Therefore ARA allows for displaying a progress for both processes.
Note that because all model data is stored in the ARA model graph, the persistent data returned per plug-in instance via the companion API will be nearly empty when ARA is enabled. Those companion archives can contain UI settings needed to reload the interface, but no model data.
More details about persistency are provided in later chapters of this document: Managing ARA Archives lays out how to deal with versioning and migration of ARA plug-in archives, and Partial Persistency describes the ARA 2 enhancements that enable hosts to selectively store or restore specific document objects rather than full documents, allowing for features like drag and drop of ARA objects between different host documents.
A prerequisite for properly implementing ARA is understanding the signal flow in an ARA-enabled host. Before diving into the specifics of this, let's take a look at the typical playback signal flow in hosts without ARA.
From a user's perspective, sections of audio files are arranged along a timeline. These snippets are usually called "region" or "clip" - we're using the term region here. The arrangement includes optional per-region transformations of the audio signal, such as level processing (region gain, fades), time stretching and pitch shifting. Additionally, sample rate conversion may need to be applied if the audio file does not match the playback sample rate.
The regions are typically grouped onto playback tracks, and the resulting track outputs are then fed into a realtime effects processing and mixing engine.
The following diagram illustrates a typical host implementation of these processing steps:
To optimize performance, the processing is usually distributed across a variety of threads with different constraints. The actual implementation differs widely between hosts, but typical host architectures assign threads according to the tasks outlined above:
All user interactions are processed on the main thread, and the model graph is maintained there accordingly. The graphical user interface is also updated from this thread.
If the host needs to execute heavy-weight calculations such as the analysis of audio material or an "offline bounce", it may offload these operations onto background worker threads to keep the main thread and user interface responsive.
The main thread will interrupt these low priority threads as needed to establish a fluid user experience. It depends on the actual host implementation which of tasks are scheduled on the main thread and which are executed by background threads.
The CPU critical realtime audio processing during playback is normally handled by a set of dedicated high priority render threads. These render threads may interrupt all other threads at any point, but the render calls of each plug-in instance are only called from a single render thread at any time.
In order to reliably meet their realtime constraints, these render threads must adhere to appropriate coding practices - most notably they must not be waiting for any shared resources such as system memory allocations.
To achieve low latency when processing live input signals, small audio buffers must be used and the rendering must happen as close as possible to the current playback time position.
Playback signals on the other hand can be rendered with much larger buffers and ahead of time, which considerably decreases CPU usage and makes the processing less vulnerable to dropouts. In fact, they can be rendered so early that they may not even need to obey strict realtime requirements.
Host accordingly tend to split the rendering between two groups of rendering threads: the semi-realtime playback track processing threads and the realtime effect processing and mixing threads.
In addition to these rendering threads, hosts typically create another thread dedicated entirely to load the audio file data from disk as needed for rendering.
This thread has to know in advance what data will be needed for rendering "soon", so that it has enough time to fetch it. This information is typically provided by some sort of sequencer that parses the model and handles the timely scheduling of such audio I/O requests. The scheduling may be executed on a dedicated thread or integrated into the track processing threads.
While common plug-ins operate on blocks of realtime signal that can change arbitrarily between each render call, ARA-enabled plug-ins have no realtime inputs. Instead, they rely on random access to a conceptually static input signal (which can be deliberately updated by the host if needed.)
They are therefore perfectly suited to be processed by the track processing threads of the render engine instead of the "traditional" realtime effect processing and mixing threads.
Depending on their capabilities and configuration, ARA-enabled plug-ins will replace some of the region transformations applied by the host, such as time stretching or sample rate conversion.
Since the region transformation performed by the ARA-enabled plug-in can include any arbitrary rearrangement of the original audio signal, the plug-in also is responsible for scheduling proper audio source sample reading ahead of time, while delegating the actual I/O operation to the host. The host will no longer stream the files through its playback engine.
Due to that setup, an ARA-enabled plug-in needs to be the first plug-in in any serial rendering chain. It is inserted before any other operation associated with the "region"/"event" (such as fades, volume or mute) are applied. This may not be possible to easily implemented for all region operations that the host allows for (i.e. reversing the audio signal) - in that case, the affected operations must either be bounced to the audio source before adding the ARA plug-in, or disabled while ARA is in use.
As discussed above when introducing the ARA model graph, frequent updating audio source samples while ARA is in use should be avoided to prevent re-analysis and potential loss of any related user edits.
To that extent, it is not feasible to stack ARA effects without freezing/bouncing all but the top-of-stack effects.
The way ARA is injected into the signal flow also has implications on the bypass behavior. If a host bypasses the rendering of an ARA-enabled plug-in, it will need to take care of applying the time stretching as described in the playback region on its own in order not to mess up the timing when bypass is invoked.
This may or may not be possible depending on the host's capabilities. ARA-enabled plug-ins should thus consider following Melodyne's example and implement a dedicated ARA "compare-with-original" mode. While in compare mode, Melodyne preserves the playback region time transformations, but bypasses any user edits stored in the audio modification. Accordingly applying the time stretching to the original audio source material allows the user to compare its edited version with the original in the context of the song.
In addition to their arrangement-based playback processing, ARA-enabled plug-ins can also create preview signals to guide users when editing the transformations in the UI. This could be playing a metronome click when editing timing while the host playback is stopped, or playing back the note currently dragged up and down by the user so that the current target pitch can be heard.
This obviously is a realtime process which needs to be handled in the mixer, not at track playback level. To allow optimizing for these different rendering tasks, separate render entities are needed. ARA 2 actively supports this by introducing explicit roles that hosts can assign to the companion API plug-in instances that perform the rendering.
Beside the two rendering duties discussed above, there are two more fundamental tasks that ARA-enabled plug-ins must implement: exchanging model data with the host, and providing a UI for the user to edit the plug-in specific arrangement transformations.
While the model is entirely ARA-specific and accordingly maintained through the ARA document controller, the rendering and the UI are implemented via companion API plug-in instances. These instances are toggled into ARA mode by "binding" them to an ARA document controller and its associated model. When binding, the host also assigns the specific roles that it wants the ARA plug-in instance to assume:
The roles also define the semantics of how to use the related companion API calls (see detailed API documentation).
For example, ARA playback renderes do not operate on realtime input - this is true both for the actual audio signal and for realtime parameter changes - since ARA is an offline API at its heart, any companion API parameters should not be used when ARA is active.
Depending on the host architecture, any plug-in instance may be assigend any combination of roles. A very natural setup keeps all three responsibilities completely separate, meaning each plug-in instance is assigned a single specific role. This is the case in the ARA implementation in Cubase/Nuendo:
Here's another example that closely resembles the original ARA 1 implementation in Studio One, where each plug-in instance assumes all three roles:
Comparing this host architecture to the previous one, the most important difference is that in the first architecture the playback rendering can be done in non-realtime, "offline" mode, whereas the in the second example it must be performed in realtime - ARA-enabled plug-ins need to deal properly with both modes.
A key feature of ARA is the multi-threaded, high-performance access from the plug-in to the samples of the host's ARAAudioSource. The API provides a synchronous (and thus potentially blocking) service that is well-suited for UI operations from the main thread or for background analysis jobs.
However these calls must not be used from realtime threads because they have an undefined execution time. Instead, plug-ins have to implement a non-realtime caching thread that fetches the audio source samples ahead of time so that they are available when the realtime renderer needs them, just like the host does internally for the non-ARA signal paths.
To ease the host implementation of the required multi-threaded audio access, ARA defines audio reader objects. Each of the audio readers may only be used by one thread at a time, so its interface is single-threaded. The plug-in will create as many audio readers as it has threads that need to read a given audio source concurrently.
Accessing the audio sources may not be possible at all times - for example when loading documents, the host may need to prepare some internal resources before samples can be provided. To manage such needs, the plug-in's document controller provides a synchronous call enableAudioSourceSamplesAccess().
While access is disabled, the plug-in must not use any of the audio readers. This specifically implies that when access is turned off, the plug-in must block the call until all reader threads have acknowledged this.