🔗 ARA Binding Process – Step by Step
1. Plugin Declaration Phase
When JUCE builds your plugin, it needs to declare ARA capability:
// In your plugin’s JucePluginCharacteristics.h or .jucer settings
#define JucePlugin_Enable_ARA 1
// This tells JUCE to build ARA support into the plugin binary
2. ARA Factory Export
Your plugin must export an ARA factory function:
// In PluginARADocumentController.cpp (which you have)
const ARA::ARAFactory* JUCE_CALLTYPE createARAFactory()
{
return juce::ARADocumentControllerSpecialisation::createARAFactory<GrooveEngineTracksDocumentController>();
}
This is the “entry point” that DAWs call to discover ARA capability.
3. Plugin Inheritance Chain
Your plugin processor must inherit from AudioProcessorARAExtension:
// In PluginProcessor.h
class GrooveEngineTracksAudioProcessor : public juce::AudioProcessor
, public juce::AudioProcessorARAExtension // ← ARA binding!
{
// …
};
4. ARA Binding Sequence (What Happens at Runtime)
When you insert the plugin on a track in Studio One:
1. Studio One loads plugin → Calls createARAFactory()
↓
2. Factory returns ARA capabilities → Studio One sees “this plugin supports ARA”
↓
3. Studio One creates ARA document → Calls your DocumentController constructor
↓
4. Plugin instance created → AudioProcessorARAExtension gets bound to the document
↓
5. isBoundToARA() returns true → Plugin can now access ARA features
5. The Binding Check
You can verify binding status:
// In your plugin code
if (auto* araExtension = dynamic_cast<juce::AudioProcessorARAExtension*>(&audioProcessor))
{
if (araExtension->isBoundToARA())
{
// 🎉 Successfully bound! Can access ARA features
auto* docController = araExtension->getDocumentController();
auto* playbackRenderer = araExtension->getPlaybackRenderer();
}
else
{
// ❌ Not bound – plugin loaded as regular audio effect
}
}
6. What “Binding” Actually Means
Bound = Connected to ARA Document:
– Plugin has access to timeline audio data
– Can read from ARAAudioSource objects
– Receives PlaybackRegion assignments
– Gets timeline sync and transport info
Not Bound = Regular Audio Plugin:
– Only processes live audio buffer
– No access to timeline data
– No waveform display capability
7. DAW-Specific Binding Triggers
Studio One:
– Binding happens when you insert plugin as “Event FX”
– Regular insert = not bound, Event FX = bound
Logic Pro:
– Binding happens automatically for ARA-capable plugins
– Plugin appears in both regular and ARA contexts
Reaper:
– User explicitly chooses “ARA” vs “Normal” mode when inserting
8. Debugging Binding Issues
Common reasons binding fails:
// ❌ Missing ARA factory export
// ❌ Plugin not built with JucePlugin_Enable_ARA = 1
// ❌ Wrong insertion method in DAW
// ❌ Plugin binary not in system directories
// ❌ DocumentController constructor issues
9. Your Plugin’s Binding Status
From your CLAUDE.md, your plugin IS successfully binding:
– ✅ isBoundToARA() returns true
– ✅ DocumentController accessible
– ✅ Audio sources detected (3 sources found)
– ✅ Factory creation working
The binding is working perfectly! The issue you discovered was about track isolation, not binding itself.
10. Visual Confirmation
You can add this debug output to see binding in real-time:
// In your plugin constructor or editor
DBG(“ARA Binding Status: ” + juce::String(araExtension && araExtension->isBoundToARA() ? “BOUND” : “NOT BOUND”));
Key Takeaway: Binding is the DAW’s way of saying “this plugin instance should have access to timeline audio data” rather than just
processing live audio streams. Your plugin is successfully bound – that’s why you can see waveforms at all!
