ara2-bridge-sys 0.1.7

Raw FFI bindings for Celemony ARA2 SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//------------------------------------------------------------------------------
//! \file       ARACLAP.h
//!             Celemony extension to the CLAP SDK to integrate ARA into CLAP plug-ins
//! \project    ARA API Specification
//! \copyright  Copyright (c) 2022-2025, Celemony Software GmbH, All Rights Reserved.
//!             Developed in cooperation with Timo Kaluza (defiantnerd)
//! \license    Licensed under the Apache License, Version 2.0 (the "License");
//!             you may not use this file except in compliance with the License.
//!             You may obtain a copy of the License at
//!
//!               http://www.apache.org/licenses/LICENSE-2.0
//!
//!             Unless required by applicable law or agreed to in writing, software
//!             distributed under the License is distributed on an "AS IS" BASIS,
//!             WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//!             See the License for the specific language governing permissions and
//!             limitations under the License.
//------------------------------------------------------------------------------

#ifndef ARACLAP_h
#define ARACLAP_h


#include "ARAInterface.h"

#include "clap/clap.h"

#if defined(__cplusplus)
extern "C"
{
#endif

//! @defgroup Companion_APIs Companion APIs
//! @{

//! @defgroup CLAP CLAP
//! @{

//! Factory ID for retrieving the clap_ara_factory_t extension from clap_plugin_entry_t.get_factory()
static CLAP_CONSTEXPR const char CLAP_EXT_ARA_FACTORY[] = "org.ara-audio.ara.factory/2";

// The latest draft is 100% compatible.
// This compat ID may be removed in 2026.
ARA_DRAFT static CLAP_CONSTEXPR const char CLAP_EXT_ARA_FACTORY_COMPAT[] = "org.ara-audio.ara.factory.draft/2";

//! Extension ID for retrieving the clap_ara_plugin_extension_t from clap_plugin_t.get_extension()
static CLAP_CONSTEXPR const char CLAP_EXT_ARA_PLUGINEXTENSION[] = "org.ara-audio.ara.pluginextension/2";

// The latest draft is 100% compatible.
// This compat ID may be removed in 2026.
ARA_DRAFT static CLAP_CONSTEXPR const char CLAP_EXT_ARA_PLUGINEXTENSION_COMPAT[] = "org.ara-audio.ara.pluginextension.draft/2";

//! Add this feature if your plugin supports ARA.
//! This allows hosts to detect ARA early on in the setup phase.
#define CLAP_PLUGIN_FEATURE_ARA_SUPPORTED "ara:supported"


//! Add this feature if your plugin requires ARA to operate (will not work as normal insert plug-in).
//! This allows non-ARA CLAP hosts to suppress the plug-in since it cannot be used there.
#define CLAP_PLUGIN_FEATURE_ARA_REQUIRED "ara:required"



/***************************************************************************************************/
//! Extension interface to connect to ARA at CLAP factory level.
//! The host can pass CLAP_EXT_ARA_FACTORY to clap_plugin_entry_t.get_factory() to directly obtain an
//! ARAFactory, which allows for creating and maintaining the model independently of any clap_plugin_t
//! instances, enabling tasks such as automatic tempo detection or audio-to-MIDI conversion.
//! For rendering and editing the model however, there must be an associated clap_plugin_t provided in
//! the same binary - the descriptor for which is returned at the same index as the related ARAFactory.

typedef struct clap_ara_factory
{
    //! Get the number of ARA factories (i.e. ARA-capable plug.-ins) available.
    //! Note that the regular clap_plugin_factory can contain more plug-ins if these do not support
    //! ARA - make no assumption about items returned here being related to the items returned there
    //! in terms of count or order.
    uint32_t(CLAP_ABI *get_factory_count)(const struct clap_ara_factory *factory);

    //! Get the ARA factory for the plug-in at the given index.
    //! The returned pointer must remain valid until clap_plugin_entry_t.deinit() is called.
    //! The returned ARAFactory must be equal to the ARAFactory returned from instances of the
    //! associated CLAP plug-in through their clap_ara_plugin_extension_t.get_factory().
    const ARA_NAMESPACE ARAFactory *(CLAP_ABI *get_ara_factory)(const struct clap_ara_factory *factory, uint32_t index);

    //! Get the ID of the CLAP plug-in associated with the ARA factory for the given index.
    //! The plug-in must be in the same binary.
    //! The returned pointer must remain valid until clap_plugin_entry_t.deinit is called.
    const char *(CLAP_ABI *get_plugin_id)(const struct clap_ara_factory *factory, uint32_t index);
} clap_ara_factory_t;


/***************************************************************************************************/
//! Extension interface to connect to ARA at CLAP plug-in level.
//! This interface provides access to the ARA specific extension of a CLAP plug-in.
//! Return an pointer to a clap_ara_plugin_extension_t when clap_plugin_t.get_extension() is called
//! with CLAP_EXT_ARA_PLUGINEXTENSION.

typedef struct clap_ara_plugin_extension
{
    //! Access the ARAFactory associated with this plug-in.
    const ARA_NAMESPACE ARAFactory *(CLAP_ABI *get_factory)(const clap_plugin_t *plugin);

    //! Bind the CLAP instance to an ARA document controller, switching it from "normal" operation
    //! to ARA mode with the assigned roles, and exposing the ARA plug-in extension.
    //! \p knownRoles encodes all roles that the host considered in its implementation and will explicitly
    //! assign to some plug-in instance(s), while \p assignedRoles describes the roles that this specific
    //! instance will fulfill.
    //! This may be called only once during the lifetime of the CLAP plug-in, before the first call
    //! to clap_plugin_t.activate() or clap_host_state_t.load() or other processing related extensions
    //! or the creation of the GUI.
    //! The ARA document controller must remain valid as long as the plug-in is in use - rendering,
    //! showing its UI, etc. However, when tearing down the plug-in, the actual order for deleting
    //! the clap_plugin_t instance and for deleting ARA document controller is undefined.
    //! Plug-ins must handle both potential destruction orders to allow for a simpler reference
    //! counting implementation on the host side.
    const ARA_NAMESPACE ARAPlugInExtensionInstance *(CLAP_ABI *bind_to_document_controller)
                                                        (const clap_plugin_t                     *plugin,
                                                         ARA_NAMESPACE ARADocumentControllerRef   documentControllerRef,
                                                         ARA_NAMESPACE ARAPlugInInstanceRoleFlags knownRoles,
                                                         ARA_NAMESPACE ARAPlugInInstanceRoleFlags assignedRoles);
} clap_ara_plugin_extension_t;

//! @}

//! @}

#if defined(__cplusplus)
}   // extern "C"
#endif

#endif // ARACLAP_h