-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathARAAudioFileChunks.h
180 lines (163 loc) · 10.6 KB
/
ARAAudioFileChunks.h
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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
//------------------------------------------------------------------------------
//! \file ARAAudioFileChunks.h
//! definition of the audio file chunks related to ARA partial persistency
//! \project ARA API Specification
//! \copyright Copyright (c) 2018-2025, Celemony Software GmbH, All Rights Reserved.
//! Developed in cooperation with PreSonus Software Ltd.
//! \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 ARAAudioFileChunks_h
#define ARAAudioFileChunks_h
#include "ARAInterface.h"
#if defined(__cplusplus) && !(ARA_DOXYGEN_BUILD)
namespace ARA
{
extern "C"
{
#endif
/***************************************************************************************************/
//! @defgroup ARAAudioFileChunks ARA Audio File Chunks
//!
//! To allow for distributing persistent ARA audio source state information together with the
//! underlying audio file in a way that is transparent to the plug-ins and can be supported by all
//! hosts, ARA 2.0 defines a format for embedding such states into standardized audio file chunks.
//! From there, they can be imported into any ARA document using @ref Partial_Document_Persistency.
//! \br
//! The most obvious use case for this is that it enables audio content providers to ship audio
//! files with properly validated, ready-to-use audio source analysis for multiple plug-ins (or
//! incompatible versions of a plug-in if needed).
//! For example, this allows for loading polyphonic audio loops into Melodyne without time-consuming
//! analysis and very quickly adjusting them to follow the song key and chord progression, making
//! the published audio material much more versatile to use in various productions.
//! Other scenarios where such file chunks are used include exporting data from one plug-in to
//! another, or adding ARA objects to a host document via dragging and dropping audio files from
//! a plug-in that either generates these files on the fly (e.g. export of layers in SpectraLayers)
//! or copies them from a built-in sound library.
//! \br
//! The ARA chunk should be evaluated by the host both when adding a new audio file to the
//! arrangement and when applying a new/different ARA plug-in for a region/file already used in
//! the arrangement.
//! Note that after loading the data, ARA content readers can be used to extract more information
//! about the audio source - such as tempo map, time and key signatures, etc.
//! \br
//! Plug-in vendors shall optimize the encoding of the audio source state information for audio file
//! chunks according to very different criteria compared to encoding the same state for regular
//! ARA song document archives:
//! The audio file states are going to be widely distributed and will be used over a long period
//! of time in very different contexts, whereas song documents are typically only used on a single
//! machine for a rather short time. Audio file archives therefore should emphasize small data size
//! over en-/decoding speed - encoding is only done once, and decoding only happens for a single
//! audio source at a time (compared to hundreds of audio sources in a typical song archive).
//! Even more important, audio file archives are likely going to be used across a wide range of
//! products versions and shall be stable across a long time. The encoding should therefore be as
//! much backwards compatible as possible, potentially even using different encoding based on the
//! current state of the audio source: if e.g. a particular non-backwards compatible feature of
//! the plug-in is not used in the given state, the plug-in can choose an older format to store
//! the data than if that particular feature was utilized.
//! For these reasons, audio file chunks will typically not use the ARAFactory::documentArchiveID
//! but instead one of the IDs listed in ARAFactory::compatibleDocumentArchiveIDs.
//! \br
//! Creating audio file chunks may not be meaningful nor supported for any given plug-in. If for
//! example the plug-in does not perform any costly analysis and has no relevant editable audio
//! source state, there is no reason to create audio file chunks for it. Therefore, creating such
//! chunks is currently done only through dedicated authoring tools (such as Melodyne's standalone
//! version) and not directly available in ARA host applications.
//! \br
//! Covering both AIFF and WAVE formats, ARA stores its data by extending iXML chunks as specified
//! here: http://www.ixml.info
//! Inside the iXML document, there's a custom tag \<ARA\> that encloses a dictionary of audio
//! source archives, encoded as array tagged \<audioSources\>. Each entry in the array is intended
//! for a different plug-in (or incompatible version of a plug-in) and contains the tag
//! \<documentArchiveID\> which also functions as the key for the dictionary, and associated data
//! which includes the actual binary archive and meta information, for example:
//! \code{.xml}
//! <ARA>
//! <audioSources>
//! <audioSource>
//! <documentArchiveID>com.celemony.ara.audiosourcedescription.13</documentArchiveID>
//! <openAutomatically>false</openAutomatically>
//! <suggestedPlugIn>
//! <plugInName>Melodyne</plugInName>
//! <lowestSupportedVersion>5.0.0</lowestSupportedVersion>
//! <manufacturerName>Celemony</manufacturerName>
//! <informationURL>https://www.celemony.com</informationURL>
//! </suggestedPlugIn>
//! <persistentID>59D4874F-FA5A-4FE8-BAC6-0E8BC5F6184A</persistentID>
//! <archiveData>TW9pbiBEdQ==</archiveData>
//! </audioSource>
//! <!-- ... potentially more archives keyed by different documentArchiveIDs here ... -->
//! </audioSources>
//! </ARA>
//! \endcode
//! @{
#if defined(__cplusplus)
//! Name of the XML element that contains the vendor-specific iXML sub-tree for ARA.
constexpr auto kARAXMLName_ARAVendorKeyword { "ARA" };
//! Name of the XML element that contains the dictionary of audio source archives inside the ARA sub-tree.
constexpr auto kARAXMLName_AudioSources { "audioSources" };
//! Name of each XML element inside the dictionary of audio source archives.
constexpr auto kARAXMLName_AudioSource { "audioSource" };
//! Name of the XML element inside an audio source archive that acts as unique dictionary key
//! for the list of audio source archives and identifies the opaque archive content.
//! string value, see ARAFactory::documentArchiveID and ARAFactory::compatibleDocumentArchiveIDs.
constexpr auto kARAXMLName_DocumentArchiveID { "documentArchiveID" };
//! Name of the XML element inside an audio source archive that indicates whether the host should
//! immediately load the archive data into a new audio source object and create an audio modification
//! and playback region for it, or else import the audio file without ARA initially and only load
//! the ARA archive later on demand when the user manually requests it by adding a matching plug-in.
//! boolean value ("true" or "false").
constexpr auto kARAXMLName_OpenAutomatically { "openAutomatically" };
//! Name of the XML element inside an audio source archive that provides user-readable information
//! about the plug-in for which the archive was originally created. This can be used for proper
//! error messages, e.g. if openAutomatically is true but no plug-in compatible with the archive's
//! given documentArchiveID is installed.
constexpr auto kARAXMLName_SuggestedPlugIn { "suggestedPlugIn" };
//! Name of the XML element inside an audio source archive that encodes the persistent ID that
//! was assigned to the audio source when creating the archive. When loading the archive, the
//! plug-in will use this persistent ID to find the target object to extract the state to.
//! string value, see ARAAudioSourceProperties::persistentID, see ARARestoreObjectsFilter.
constexpr auto kARAXMLName_PersistentID { "persistentID" };
//! Name of the XML element inside an audio source archive that encodes the actual binary data
//! of the archive in Base64 format, with the possible addition of line feeds as allowed by MIME.
//! Note that it is preferred to encode without line feeds, but decoders must handle both cases.
//! string value, see ARAArchivingControllerInterface, see https://tools.ietf.org/html/rfc4648.
constexpr auto kARAXMLName_ArchiveData { "archiveData" };
//! Name of the XML element inside a suggested plug-in element that encodes the plug-in name as string.
constexpr auto kARAXMLName_PlugInName { "plugInName" };
//! Name of the XML element inside a suggested plug-in element that encodes the minimum version
//! of the plug-in that is compatible with this archive as string.
constexpr auto kARAXMLName_LowestSupportedVersion { "lowestSupportedVersion" };
//! Name of the XML element inside a suggested plug-in element that encodes the plug-in manufacturer as string.
constexpr auto kARAXMLName_ManufacturerName { "manufacturerName" };
//! Name of the XML element inside a suggested plug-in element that encodes the plug-in information URL as string.
constexpr auto kARAXMLName_InformationURL { "informationURL" };
#else
#define kARAXMLName_ARAVendorKeyword "ARA"
#define kARAXMLName_AudioSources "audioSources"
#define kARAXMLName_AudioSource "audioSource"
#define kARAXMLName_DocumentArchiveID "documentArchiveID"
#define kARAXMLName_OpenAutomatically "openAutomatically"
#define kARAXMLName_SuggestedPlugIn "suggestedPlugIn"
#define kARAXMLName_PersistentID "persistentID"
#define kARAXMLName_ArchiveData "archiveData"
#define kARAXMLName_PlugInName "plugInName"
#define kARAXMLName_LowestSupportedVersion "lowestSupportedVersion"
#define kARAXMLName_ManufacturerName "manufacturerName"
#define kARAXMLName_InformationURL "informationURL"
#endif
//! @}
#if defined(__cplusplus) && !(ARA_DOXYGEN_BUILD)
} // extern "C"
} // namespace ARA
#endif
#endif // ARAAudioFileChunks_h