@hussmartinez/audio-sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +133 -2
- package/dist/assets/audio/audio.worker.js +1 -0
- package/dist/element.d.ts +12 -0
- package/dist/element.js +0 -0
- package/dist/index.d.ts +1412 -0
- package/dist/index.js +1453 -0
- package/dist/index.js.map +1 -0
- package/dist/lazy/inline-worker-CkUV_wKW.js +30 -0
- package/dist/lazy/inline-worker-CkUV_wKW.js.map +1 -0
- package/dist/react.d.ts +12 -0
- package/dist/react.js +1 -0
- package/dist/styles.css +9 -0
- package/package.json +110 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,1412 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Headless core of the audio SDK: contracts, errors, the document session and
|
|
3
|
+
* operations.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* This entry is server-safe: it has no React and touches no DOM on import, so
|
|
7
|
+
* Server Components and Node can import it (ADR 0004, ADR 0007).
|
|
8
|
+
*
|
|
9
|
+
* @packageDocumentation
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { FilePolicy } from '@hussmartinez/sdk-core';
|
|
13
|
+
import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
|
|
14
|
+
import { Limits } from '@hussmartinez/sdk-core';
|
|
15
|
+
import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
|
|
16
|
+
import { SdkError } from '@hussmartinez/sdk-core';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The name of the clip plan's portable format (sdk-core ADR 0045).
|
|
20
|
+
*
|
|
21
|
+
* @public
|
|
22
|
+
*/
|
|
23
|
+
export declare const AUDIO_PLAN_FORMAT = "hm-audio-plan";
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* The version of {@link AUDIO_PLAN_FORMAT} this release writes, and the
|
|
27
|
+
* latest it reads.
|
|
28
|
+
*
|
|
29
|
+
* @public
|
|
30
|
+
*/
|
|
31
|
+
export declare const AUDIO_PLAN_VERSION = 1;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A content-addressed reference to binary data, such as a source's file
|
|
35
|
+
* (sdk-core ADR 0045). Documents never inline bytes.
|
|
36
|
+
*
|
|
37
|
+
* @public
|
|
38
|
+
*/
|
|
39
|
+
export declare interface AudioAssetReference {
|
|
40
|
+
/** `sha256:` and the lowercase hex SHA-256 of the bytes. */
|
|
41
|
+
readonly asset: string;
|
|
42
|
+
/** The bytes' media type, such as `audio/wav`, in lowercase. */
|
|
43
|
+
readonly mediaType: string;
|
|
44
|
+
/** The size of the bytes. */
|
|
45
|
+
readonly size: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Options every port call accepts.
|
|
50
|
+
*
|
|
51
|
+
* @public
|
|
52
|
+
*/
|
|
53
|
+
export declare interface AudioCallOptions {
|
|
54
|
+
/**
|
|
55
|
+
* Cancels the call. It then rejects with an `AudioError` whose code is
|
|
56
|
+
* `ABORTED`, `TIMEOUT`, or the code of an `SdkError` given as the abort
|
|
57
|
+
* reason, such as `PROCESSING_TIME_EXCEEDED`.
|
|
58
|
+
*/
|
|
59
|
+
readonly signal?: AbortSignal;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* One piece of a source, played in the plan (ADR 0003).
|
|
64
|
+
*
|
|
65
|
+
* @public
|
|
66
|
+
*/
|
|
67
|
+
export declare interface AudioClip {
|
|
68
|
+
/** Stable across edits, so selection and waveform tiles follow a clip that moves. */
|
|
69
|
+
readonly key: string;
|
|
70
|
+
/** The id of the source the clip plays. */
|
|
71
|
+
readonly source: string;
|
|
72
|
+
/** The first source frame the clip plays, inclusive. */
|
|
73
|
+
readonly start: number;
|
|
74
|
+
/** The source frame the clip stops before, exclusive. */
|
|
75
|
+
readonly end: number;
|
|
76
|
+
/** The clip's gain in decibels. 0 leaves it unchanged. */
|
|
77
|
+
readonly gainDb: number;
|
|
78
|
+
readonly fadeIn: AudioFade;
|
|
79
|
+
readonly fadeOut: AudioFade;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Why a clip isn't valid within its source, as a stable token: a value of
|
|
84
|
+
* `details.reason` on `INVALID_COMMAND` (sdk-core ADR 0045).
|
|
85
|
+
*
|
|
86
|
+
* - `invalid-frames`: a position or fade length isn't a non-negative whole
|
|
87
|
+
* number of frames.
|
|
88
|
+
* - `clip-too-short`: the clip is shorter than one frame.
|
|
89
|
+
* - `clip-outside-source`: it ends after its source's last frame.
|
|
90
|
+
* - `gain-out-of-range`: the gain isn't a finite number from
|
|
91
|
+
* {@link MIN_GAIN_DB} to {@link MAX_GAIN_DB}.
|
|
92
|
+
* - `fades-too-long`: its fades together are longer than the clip.
|
|
93
|
+
*
|
|
94
|
+
* @public
|
|
95
|
+
*/
|
|
96
|
+
export declare type AudioClipProblem = "invalid-frames" | "clip-too-short" | "clip-outside-source" | "gain-out-of-range" | "fades-too-long";
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The codecs the probe recognises (ADR 0001). `pcm` covers integer and
|
|
100
|
+
* floating-point samples in WAV and AIFF.
|
|
101
|
+
*
|
|
102
|
+
* @public
|
|
103
|
+
*/
|
|
104
|
+
export declare type AudioCodec = "pcm" | "mp3" | "aac" | "alac" | "opus" | "vorbis" | "flac";
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* An edit to the clip plan (docs/adr/0003). Commands are plain,
|
|
108
|
+
* structured-cloneable data, never carry samples, and each has an exact
|
|
109
|
+
* inverse, which is how undo works (ADR 0010, ADR 0029).
|
|
110
|
+
*
|
|
111
|
+
* @public
|
|
112
|
+
*/
|
|
113
|
+
export declare type AudioCommand = AudioInsertClipsCommand | AudioRemoveClipsCommand | AudioRestoreClipsCommand | AudioReplaceClipsCommand | AudioUpdateClipsCommand | AudioDeleteRangeCommand | AudioTrimClipCommand | AudioSplitClipCommand | AudioMoveClipsCommand | AudioReorderClipsCommand | AudioSetGainCommand | AudioSetFadeCommand | AudioSetMetadataCommand;
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Why the reducer refused a command, as a stable token: `details.reason` on
|
|
117
|
+
* `INVALID_COMMAND`, which hosts and conformance vectors compare instead of
|
|
118
|
+
* the message (sdk-core ADR 0045). Tokens never change meaning once
|
|
119
|
+
* released.
|
|
120
|
+
*
|
|
121
|
+
* - The clip's own problems, {@link AudioClipProblem}.
|
|
122
|
+
* - `malformed-command`: the command isn't shaped as its type says, such as
|
|
123
|
+
* a list that isn't one, or a clip without a key or source.
|
|
124
|
+
* - `unknown-command`: its `type` isn't one of {@link AudioCommand}'s.
|
|
125
|
+
* - `unknown-source`: a clip names a source the session doesn't hold.
|
|
126
|
+
* - `invalid-fade-curve`: a fade's curve isn't `linear` or `equalPower`.
|
|
127
|
+
* - `no-clips`: the command needs at least one clip, and names none.
|
|
128
|
+
* - `duplicate-key`: it names a clip twice, or gives two new clips one key.
|
|
129
|
+
* - `key-taken`: a new clip's key is already in the plan.
|
|
130
|
+
* - `unknown-clip`: it names a clip the plan doesn't have.
|
|
131
|
+
* - `frame-outside-plan`: a timeline frame is outside the plan.
|
|
132
|
+
* - `empty-range`: a range is shorter than one frame.
|
|
133
|
+
* - `not-inside-clip`: a split frame isn't strictly inside its clip.
|
|
134
|
+
* - `new-key-required`: it cuts a clip in two without the new part's key.
|
|
135
|
+
* - `invalid-index`: an index or a run of clips is outside the plan.
|
|
136
|
+
* - `empty-change`: it would change nothing at all.
|
|
137
|
+
* - `invalid-order`: a new order doesn't list every clip exactly once.
|
|
138
|
+
* - `invalid-edge`: a fade's edge isn't `in` or `out`.
|
|
139
|
+
* - `unknown-metadata-field`: the metadata has no such field.
|
|
140
|
+
* - `metadata-too-long`: a metadata value is over {@link MAX_METADATA_LENGTH}
|
|
141
|
+
* characters.
|
|
142
|
+
*
|
|
143
|
+
* The session adds `no-recording`, for a command with no recording open,
|
|
144
|
+
* and `not-plain-data`, for a command that can't be cloned.
|
|
145
|
+
*
|
|
146
|
+
* @public
|
|
147
|
+
*/
|
|
148
|
+
export declare type AudioCommandRejection = AudioClipProblem | "malformed-command" | "unknown-command" | "unknown-source" | "invalid-fade-curve" | "no-clips" | "duplicate-key" | "key-taken" | "unknown-clip" | "frame-outside-plan" | "empty-range" | "not-inside-clip" | "new-key-required" | "invalid-index" | "empty-change" | "invalid-order" | "invalid-edge" | "unknown-metadata-field" | "metadata-too-long" | "no-recording" | "not-plain-data";
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* The containers the probe recognises (ADR 0001).
|
|
152
|
+
*
|
|
153
|
+
* @public
|
|
154
|
+
*/
|
|
155
|
+
export declare type AudioContainer = "wav" | "aiff" | "flac" | "ogg" | "mp3" | "adts" | "mp4" | "webm";
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Removes the timeline range from `start` to `end`, trimming the clips at
|
|
159
|
+
* its edges. A range inside one clip splits it: the part after the range
|
|
160
|
+
* takes `newKey`.
|
|
161
|
+
*
|
|
162
|
+
* @public
|
|
163
|
+
*/
|
|
164
|
+
export declare interface AudioDeleteRangeCommand {
|
|
165
|
+
readonly type: "audio.deleteRange";
|
|
166
|
+
/** The first timeline frame removed, inclusive. */
|
|
167
|
+
readonly start: number;
|
|
168
|
+
/** The timeline frame the range stops before, exclusive. */
|
|
169
|
+
readonly end: number;
|
|
170
|
+
/** The key of the part after the range, when the range is inside one clip. Required only then. */
|
|
171
|
+
readonly newKey?: string;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Why a plan document was refused, as a stable token: `details.reason` on
|
|
176
|
+
* the error (sdk-core ADR 0045).
|
|
177
|
+
*
|
|
178
|
+
* - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
|
|
179
|
+
* format, and `unknown-format-version`, a later version than this release
|
|
180
|
+
* reads.
|
|
181
|
+
* - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
|
|
182
|
+
* shaped as the schema says; `unknown-source`, a clip whose source the
|
|
183
|
+
* document doesn't list; `duplicate-key`, two clips with one key;
|
|
184
|
+
* `invalid-fade-curve` and `metadata-too-long`, as for commands; and a
|
|
185
|
+
* clip's own problems, {@link AudioClipProblem}.
|
|
186
|
+
*
|
|
187
|
+
* @public
|
|
188
|
+
*/
|
|
189
|
+
export declare type AudioDocumentRejection = AudioClipProblem | "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "duplicate-key" | "invalid-fade-curve" | "metadata-too-long";
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The port for reading audio files: probe a file's headers, decode it, and
|
|
193
|
+
* build its waveform overview (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
194
|
+
* adapter probes and parses in its worker and decodes compressed formats
|
|
195
|
+
* with Web Audio; hosts can pass their own to the editor's `engine` prop, and
|
|
196
|
+
* every implementation must pass the engine's contract tests.
|
|
197
|
+
*
|
|
198
|
+
* The engine doesn't apply the file policy: the session checks the probe
|
|
199
|
+
* against it between `probe` and `decode` (ADR 0004).
|
|
200
|
+
*
|
|
201
|
+
* Failures reject with `AudioError`: `INVALID_AUDIO` for a malformed file,
|
|
202
|
+
* `UNSUPPORTED_FORMAT` for one the probe can't bound, `DECODE_FAILED` when
|
|
203
|
+
* the browser can't decode it, and sdk-core's codes for cancellation and
|
|
204
|
+
* worker failures.
|
|
205
|
+
*
|
|
206
|
+
* @public
|
|
207
|
+
*/
|
|
208
|
+
export declare interface AudioEngine {
|
|
209
|
+
/**
|
|
210
|
+
* Reads a file's headers and walks its packets, without decoding it. It
|
|
211
|
+
* reads the file through the `Blob`, never all at once.
|
|
212
|
+
*/
|
|
213
|
+
probe(file: Blob, options?: AudioCallOptions): Promise<AudioProbe>;
|
|
214
|
+
/**
|
|
215
|
+
* Decodes a probed file at the probe's sample rate and channel count. A
|
|
216
|
+
* result longer than the probe's bound plus its tolerance rejects with
|
|
217
|
+
* `INVALID_AUDIO`; a shorter one is returned as it is.
|
|
218
|
+
*/
|
|
219
|
+
decode(file: Blob, probe: AudioProbe, options?: AudioProgressOptions): Promise<DecodedAudio>;
|
|
220
|
+
/**
|
|
221
|
+
* Builds a waveform overview of decoded audio. The audio isn't modified or
|
|
222
|
+
* kept.
|
|
223
|
+
*/
|
|
224
|
+
peaks(audio: DecodedAudio, options?: AudioCallOptions): Promise<AudioPeaks>;
|
|
225
|
+
/** Releases the engine and its worker. Pending calls reject, and later calls throw. */
|
|
226
|
+
destroy(): Promise<void>;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* Options for {@link createAudioEngine}.
|
|
231
|
+
*
|
|
232
|
+
* @public
|
|
233
|
+
*/
|
|
234
|
+
export declare interface AudioEngineOptions {
|
|
235
|
+
/**
|
|
236
|
+
* Milliseconds without calls after which the worker stops. It starts again
|
|
237
|
+
* on the next call. Defaults to sdk-core's 30 seconds.
|
|
238
|
+
*/
|
|
239
|
+
readonly idleTimeout?: number;
|
|
240
|
+
/**
|
|
241
|
+
* Where the application serves the package's `dist/assets/` directory, to
|
|
242
|
+
* load the worker from its own origin instead of a `blob:` URL. The worker
|
|
243
|
+
* is then `audio/audio.worker.js` there, and a Content Security Policy
|
|
244
|
+
* needs `worker-src 'self'` and no `blob:` (docs/adr/0002). Copy
|
|
245
|
+
* `dist/assets` again after every upgrade: a worker from another version
|
|
246
|
+
* is refused with `WORKER_START_FAILED`. By default the worker is inlined.
|
|
247
|
+
*/
|
|
248
|
+
readonly assetsUrl?: string | URL;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* The error `@hussmartinez/audio-sdk` throws and rejects with, with a stable
|
|
253
|
+
* `code`, structured `details` and the underlying error as `cause`. Show
|
|
254
|
+
* users the text for its code from {@link audioMessages}, never its
|
|
255
|
+
* `message`, which is for developers and may contain text from the file.
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* ```ts
|
|
259
|
+
* try {
|
|
260
|
+
* await session.open(file);
|
|
261
|
+
* } catch (error) {
|
|
262
|
+
* if (isAudioError(error, "DECODE_FAILED")) {
|
|
263
|
+
* suggestConvertingToWav();
|
|
264
|
+
* } else {
|
|
265
|
+
* show(messages.error(error));
|
|
266
|
+
* }
|
|
267
|
+
* }
|
|
268
|
+
* ```
|
|
269
|
+
*
|
|
270
|
+
* @public
|
|
271
|
+
*/
|
|
272
|
+
export declare class AudioError extends SdkError<AudioErrorCode> {
|
|
273
|
+
/** Always `"AudioError"`, which survives minification and worker boundaries. */
|
|
274
|
+
readonly name = "AudioError";
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* Error codes of `@hussmartinez/audio-sdk`: sdk-core's own codes, such as
|
|
279
|
+
* `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the audio SDK's
|
|
280
|
+
* (ADR 0004). They never change meaning once released.
|
|
281
|
+
*
|
|
282
|
+
* - `INVALID_AUDIO`: the file is malformed, its headers claim more audio than
|
|
283
|
+
* its packets carry, or it decodes to more than its bound allows.
|
|
284
|
+
* - `UNSUPPORTED_FORMAT`: the container or codec isn't recognised, the file's
|
|
285
|
+
* packets can't be walked to a bound, or the browser can't decode at its
|
|
286
|
+
* sample rate.
|
|
287
|
+
* - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
|
|
288
|
+
* usually because it lacks the codec. `details.codec` names it.
|
|
289
|
+
* - `INVALID_COMMAND`: an edit command doesn't apply to the clip plan, such
|
|
290
|
+
* as a range outside its source or an unknown clip key.
|
|
291
|
+
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
292
|
+
* valid in its format.
|
|
293
|
+
* - `DURATION_TOO_LONG`: a file exceeds the `maxDuration` limit.
|
|
294
|
+
* - `TOO_MANY_CHANNELS`: a file exceeds the `maxChannels` limit.
|
|
295
|
+
* - `SAMPLE_RATE_TOO_HIGH`: a file exceeds the `maxSampleRate` limit.
|
|
296
|
+
* - `SESSION_TOO_LARGE`: the decoded audio the session holds exceeds the
|
|
297
|
+
* `maxSessionSize` limit.
|
|
298
|
+
* - `TOO_MANY_CLIPS`: the clip plan exceeds the `maxClips` limit.
|
|
299
|
+
*
|
|
300
|
+
* Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
|
|
301
|
+
* value and the `unit`. Other codes' `details` name the container, codec or
|
|
302
|
+
* sample rate involved, never data from the file.
|
|
303
|
+
*
|
|
304
|
+
* @public
|
|
305
|
+
*/
|
|
306
|
+
export declare type AudioErrorCode = SdkCoreErrorCode | "INVALID_AUDIO" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "DURATION_TOO_LONG" | "TOO_MANY_CHANNELS" | "SAMPLE_RATE_TOO_HIGH" | "SESSION_TOO_LARGE" | "TOO_MANY_CLIPS";
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* The file an export produces. WAV is the only container so far (ADR 0001).
|
|
310
|
+
*
|
|
311
|
+
* @public
|
|
312
|
+
*/
|
|
313
|
+
export declare interface AudioExportFormat {
|
|
314
|
+
readonly container: "wav";
|
|
315
|
+
/** Defaults to `pcm16`. */
|
|
316
|
+
readonly sampleFormat?: AudioSampleFormat_2;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* A fade at one end of a clip. `frames: 0` is no fade.
|
|
321
|
+
*
|
|
322
|
+
* @public
|
|
323
|
+
*/
|
|
324
|
+
export declare interface AudioFade {
|
|
325
|
+
readonly frames: number;
|
|
326
|
+
readonly curve: AudioFadeCurve;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* The shape of a fade: `linear` changes the gain at a constant rate, and
|
|
331
|
+
* `equalPower` keeps the perceived loudness steadier, which suits crossfades.
|
|
332
|
+
*
|
|
333
|
+
* @public
|
|
334
|
+
*/
|
|
335
|
+
export declare type AudioFadeCurve = "linear" | "equalPower";
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* A resolved file policy for the audio SDK. Violations throw
|
|
339
|
+
* {@link AudioError}.
|
|
340
|
+
*
|
|
341
|
+
* @public
|
|
342
|
+
*/
|
|
343
|
+
export declare type AudioFilePolicy = FilePolicy<AudioLimitDefinitions>;
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
|
|
347
|
+
* the audio SDK's limits. `Infinity` disables a maximum, which removes a
|
|
348
|
+
* protection against hostile files, or disables a warning. Unknown limit
|
|
349
|
+
* names throw `TypeError` when the policy is resolved.
|
|
350
|
+
*
|
|
351
|
+
* @example
|
|
352
|
+
* ```ts
|
|
353
|
+
* // Long recordings: raise the decoded and session sizes together.
|
|
354
|
+
* const filePolicy: AudioFilePolicyOverrides = {
|
|
355
|
+
* maxDecodedSize: 2e9,
|
|
356
|
+
* maxSessionSize: { maximum: 3e9, warning: 1.5e9 },
|
|
357
|
+
* };
|
|
358
|
+
* ```
|
|
359
|
+
*
|
|
360
|
+
* @public
|
|
361
|
+
*/
|
|
362
|
+
export declare type AudioFilePolicyOverrides = FilePolicyOverrides<AudioLimitDefinitions>;
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* Inserts clips at a timeline frame. When the frame falls inside a clip,
|
|
366
|
+
* that clip is split there: its first part keeps its key, and its second
|
|
367
|
+
* part takes `splitKey`.
|
|
368
|
+
*
|
|
369
|
+
* @public
|
|
370
|
+
*/
|
|
371
|
+
export declare interface AudioInsertClipsCommand {
|
|
372
|
+
readonly type: "audio.insertClips";
|
|
373
|
+
/** The timeline frame to insert at, from 0 to the plan's length. */
|
|
374
|
+
readonly at: number;
|
|
375
|
+
/** The clips, in order, with keys the plan doesn't have. */
|
|
376
|
+
readonly clips: readonly AudioClip[];
|
|
377
|
+
/** The key of the second part of a clip that `at` splits. Required only then. */
|
|
378
|
+
readonly splitKey?: string;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* Options for {@link AudioSession.insert}.
|
|
383
|
+
*
|
|
384
|
+
* @public
|
|
385
|
+
*/
|
|
386
|
+
export declare interface AudioInsertOptions extends AudioProgressOptions {
|
|
387
|
+
/**
|
|
388
|
+
* The timeline frame to insert at, splitting the clip there if it's inside
|
|
389
|
+
* one. Defaults to the end.
|
|
390
|
+
*/
|
|
391
|
+
readonly at?: number;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* The type of {@link audioLimitDefinitions}.
|
|
396
|
+
*
|
|
397
|
+
* @public
|
|
398
|
+
*/
|
|
399
|
+
export declare type AudioLimitDefinitions = typeof audioLimitDefinitions;
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* The audio SDK's limit definitions: sdk-core's core limits with audio
|
|
403
|
+
* defaults, plus five for audio (ADR 0004).
|
|
404
|
+
*
|
|
405
|
+
* | Limit | Code | Default maximum | Default warning |
|
|
406
|
+
* |---|---|---|---|
|
|
407
|
+
* | `maxFileSize` | `FILE_TOO_LARGE` | 1 GB | 250 MB |
|
|
408
|
+
* | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
|
|
409
|
+
* | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
|
|
410
|
+
* | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
|
|
411
|
+
* | `maxDuration` | `DURATION_TOO_LONG` | 3 hours | 1 hour |
|
|
412
|
+
* | `maxChannels` | `TOO_MANY_CHANNELS` | 8 | none |
|
|
413
|
+
* | `maxSampleRate` | `SAMPLE_RATE_TOO_HIGH` | 192 kHz | none |
|
|
414
|
+
* | `maxSessionSize` | `SESSION_TOO_LARGE` | 1.5 GB | 750 MB |
|
|
415
|
+
* | `maxClips` | `TOO_MANY_CLIPS` | 2,000 | none |
|
|
416
|
+
*
|
|
417
|
+
* Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 32-bit
|
|
418
|
+
* floats: frames × channels × 4 bytes. `maxDuration` is in milliseconds, and
|
|
419
|
+
* `maxSampleRate` is in hertz.
|
|
420
|
+
*
|
|
421
|
+
* @public
|
|
422
|
+
*/
|
|
423
|
+
export declare const audioLimitDefinitions: {
|
|
424
|
+
readonly maxFileSize: {
|
|
425
|
+
readonly default: 1000000000;
|
|
426
|
+
readonly warning: 250000000;
|
|
427
|
+
readonly code: "FILE_TOO_LARGE";
|
|
428
|
+
readonly unit: "bytes";
|
|
429
|
+
};
|
|
430
|
+
readonly maxDecodedSize: {
|
|
431
|
+
readonly default: 1000000000;
|
|
432
|
+
readonly warning: 400000000;
|
|
433
|
+
readonly code: "DECODED_SIZE_TOO_LARGE";
|
|
434
|
+
readonly unit: "bytes";
|
|
435
|
+
};
|
|
436
|
+
readonly maxDuration: {
|
|
437
|
+
readonly code: "DURATION_TOO_LONG";
|
|
438
|
+
readonly unit: "milliseconds";
|
|
439
|
+
readonly default: number;
|
|
440
|
+
readonly warning: number;
|
|
441
|
+
};
|
|
442
|
+
readonly maxChannels: {
|
|
443
|
+
readonly code: "TOO_MANY_CHANNELS";
|
|
444
|
+
readonly unit: "count";
|
|
445
|
+
readonly default: 8;
|
|
446
|
+
};
|
|
447
|
+
readonly maxSampleRate: {
|
|
448
|
+
readonly code: "SAMPLE_RATE_TOO_HIGH";
|
|
449
|
+
readonly unit: "hertz";
|
|
450
|
+
readonly default: 192000;
|
|
451
|
+
};
|
|
452
|
+
readonly maxSessionSize: {
|
|
453
|
+
readonly code: "SESSION_TOO_LARGE";
|
|
454
|
+
readonly unit: "bytes";
|
|
455
|
+
readonly default: 1500000000;
|
|
456
|
+
readonly warning: 750000000;
|
|
457
|
+
};
|
|
458
|
+
readonly maxClips: {
|
|
459
|
+
readonly code: "TOO_MANY_CLIPS";
|
|
460
|
+
readonly unit: "count";
|
|
461
|
+
readonly default: 2000;
|
|
462
|
+
};
|
|
463
|
+
readonly maxFiles: {
|
|
464
|
+
readonly code: "TOO_MANY_FILES";
|
|
465
|
+
readonly unit: "count";
|
|
466
|
+
readonly default: 20;
|
|
467
|
+
};
|
|
468
|
+
readonly maxProcessingTime: {
|
|
469
|
+
readonly code: "PROCESSING_TIME_EXCEEDED";
|
|
470
|
+
readonly unit: "milliseconds";
|
|
471
|
+
readonly default: 120000;
|
|
472
|
+
};
|
|
473
|
+
};
|
|
474
|
+
|
|
475
|
+
/**
|
|
476
|
+
* The names of the audio SDK's limits.
|
|
477
|
+
*
|
|
478
|
+
* @public
|
|
479
|
+
*/
|
|
480
|
+
export declare type AudioLimitName = keyof AudioLimitDefinitions;
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* The audio SDK's limits, ready to resolve a host's `filePolicy`. Violations
|
|
484
|
+
* are thrown as {@link AudioError}, with `details` naming the limit.
|
|
485
|
+
*
|
|
486
|
+
* @example
|
|
487
|
+
* ```ts
|
|
488
|
+
* const policy = audioLimits.resolve(props.filePolicy);
|
|
489
|
+
* policy.check("maxChannels", channels); // throws AudioError("TOO_MANY_CHANNELS") above 8
|
|
490
|
+
* ```
|
|
491
|
+
*
|
|
492
|
+
* @public
|
|
493
|
+
*/
|
|
494
|
+
export declare const audioLimits: Limits<AudioLimitDefinitions>;
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* The type of {@link audioMessages}, for typing a host's overrides with
|
|
498
|
+
* `MessageOverrides<AudioMessageCatalogue>`.
|
|
499
|
+
*
|
|
500
|
+
* @public
|
|
501
|
+
*/
|
|
502
|
+
export declare type AudioMessageCatalogue = typeof audioMessages;
|
|
503
|
+
|
|
504
|
+
/**
|
|
505
|
+
* The audio SDK's English message catalogue: sdk-core's messages, and text
|
|
506
|
+
* for every {@link AudioErrorCode} and every limit's warning. Pass it to
|
|
507
|
+
* `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
|
|
508
|
+
* overrides. The editor's text joins it as the editor arrives.
|
|
509
|
+
*
|
|
510
|
+
* Error text is looked up by code, with the error's `details` as
|
|
511
|
+
* parameters, and never taken from `error.message` (ADR 0019).
|
|
512
|
+
*
|
|
513
|
+
* @example
|
|
514
|
+
* ```ts
|
|
515
|
+
* const messages = createMessages(audioMessages, { locale: "en", overrides: props.messages });
|
|
516
|
+
* messages.error(error); // "This recording has 12 channels, which is over the 8-channel limit."
|
|
517
|
+
* messages.t("warnings.maxSessionSize", { actual: 800e6 });
|
|
518
|
+
* ```
|
|
519
|
+
*
|
|
520
|
+
* @public
|
|
521
|
+
*/
|
|
522
|
+
export declare const audioMessages: {
|
|
523
|
+
readonly "errors.INVALID_AUDIO": "This file isn't valid audio, or it's too damaged to open.";
|
|
524
|
+
readonly "errors.UNSUPPORTED_FORMAT": "This audio format isn't supported. Try converting the file to WAV, then open it again.";
|
|
525
|
+
readonly "errors.DECODE_FAILED": "This browser can't play this kind of audio. Try another browser, or convert the file to WAV.";
|
|
526
|
+
readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
|
|
527
|
+
readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an audio project.";
|
|
528
|
+
readonly "errors.DURATION_TOO_LONG": "This recording is {actual, duration} long, which is over the {maximum, duration} limit.";
|
|
529
|
+
readonly "errors.TOO_MANY_CHANNELS": "This recording has {actual, number} channels, which is over the {maximum, number}-channel limit.";
|
|
530
|
+
readonly "errors.SAMPLE_RATE_TOO_HIGH": "This recording's sample rate is {actual, number} Hz, which is over the {maximum, number} Hz limit.";
|
|
531
|
+
readonly "errors.SESSION_TOO_LARGE": "The open recordings would use {actual, fileSize} of memory, which is over the {maximum, fileSize} limit. Remove a recording, or clear the undo history, and try again.";
|
|
532
|
+
readonly "errors.TOO_MANY_CLIPS": {
|
|
533
|
+
readonly $plural: "maximum";
|
|
534
|
+
} & {
|
|
535
|
+
readonly one: "A recording can have {maximum} clip. Join or delete clips, and try again.";
|
|
536
|
+
readonly other: "A recording can have up to {maximum} clips. Join or delete clips, and try again.";
|
|
537
|
+
};
|
|
538
|
+
readonly "warnings.maxDuration": "This recording is {actual, duration} long, and may be slow to open and edit.";
|
|
539
|
+
readonly "warnings.maxChannels": "This recording has {actual, number} channels, and may be slow to edit.";
|
|
540
|
+
readonly "warnings.maxSampleRate": "This recording's sample rate is {actual, number} Hz, and it may be slow to edit.";
|
|
541
|
+
readonly "warnings.maxSessionSize": "The open recordings use {actual, fileSize} of memory. Clearing the undo history frees memory.";
|
|
542
|
+
readonly "warnings.maxClips": {
|
|
543
|
+
readonly $plural: "actual";
|
|
544
|
+
} & {
|
|
545
|
+
readonly one: "This recording has {actual} clip. Many clips may be slow to play and export.";
|
|
546
|
+
readonly other: "This recording has {actual} clips. Many clips may be slow to play and export.";
|
|
547
|
+
};
|
|
548
|
+
readonly "warnings.truncated": "This recording looks incomplete, perhaps from an interrupted recording or download. It opened with the audio it holds.";
|
|
549
|
+
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
550
|
+
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
551
|
+
readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
|
|
552
|
+
readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
|
|
553
|
+
readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
|
|
554
|
+
readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
|
|
555
|
+
readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
|
|
556
|
+
readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
|
|
557
|
+
readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
|
|
558
|
+
readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
|
|
559
|
+
readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
|
|
560
|
+
readonly "errors.TOO_MANY_FILES": {
|
|
561
|
+
readonly $plural: "maximum";
|
|
562
|
+
} & {
|
|
563
|
+
readonly one: "You can add {maximum} file at a time.";
|
|
564
|
+
readonly other: "You can add up to {maximum} files at a time.";
|
|
565
|
+
};
|
|
566
|
+
readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
|
|
567
|
+
readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
|
|
568
|
+
readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
|
|
569
|
+
readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
|
|
570
|
+
readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
|
|
571
|
+
readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
|
|
572
|
+
readonly "keys.control": "Ctrl";
|
|
573
|
+
readonly "keys.alt": "Alt";
|
|
574
|
+
readonly "keys.shift": "Shift";
|
|
575
|
+
readonly "keys.meta": "Meta";
|
|
576
|
+
readonly "keys.apple.control": "\u2303";
|
|
577
|
+
readonly "keys.apple.alt": "\u2325";
|
|
578
|
+
readonly "keys.apple.shift": "\u21E7";
|
|
579
|
+
readonly "keys.apple.meta": "\u2318";
|
|
580
|
+
readonly "keys.space": "Space";
|
|
581
|
+
readonly "keys.enter": "Enter";
|
|
582
|
+
readonly "keys.escape": "Esc";
|
|
583
|
+
readonly "keys.tab": "Tab";
|
|
584
|
+
readonly "keys.delete": "Delete";
|
|
585
|
+
readonly "keys.backspace": "Backspace";
|
|
586
|
+
readonly "keys.arrowUp": "\u2191";
|
|
587
|
+
readonly "keys.arrowDown": "\u2193";
|
|
588
|
+
readonly "keys.arrowLeft": "\u2190";
|
|
589
|
+
readonly "keys.arrowRight": "\u2192";
|
|
590
|
+
readonly "keys.home": "Home";
|
|
591
|
+
readonly "keys.end": "End";
|
|
592
|
+
readonly "keys.pageUp": "Page Up";
|
|
593
|
+
readonly "keys.pageDown": "Page Down";
|
|
594
|
+
};
|
|
595
|
+
|
|
596
|
+
/**
|
|
597
|
+
* Metadata that export writes into the file (ADR 0001).
|
|
598
|
+
*
|
|
599
|
+
* @public
|
|
600
|
+
*/
|
|
601
|
+
export declare interface AudioMetadata {
|
|
602
|
+
readonly title: string;
|
|
603
|
+
readonly artist: string;
|
|
604
|
+
readonly album: string;
|
|
605
|
+
readonly year: string;
|
|
606
|
+
readonly comment: string;
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
/**
|
|
610
|
+
* Moves clips, keeping their relative order, so that the first of them
|
|
611
|
+
* ends up at index `to` of the resulting plan.
|
|
612
|
+
*
|
|
613
|
+
* @public
|
|
614
|
+
*/
|
|
615
|
+
export declare interface AudioMoveClipsCommand {
|
|
616
|
+
readonly type: "audio.moveClips";
|
|
617
|
+
readonly keys: readonly string[];
|
|
618
|
+
readonly to: number;
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/**
|
|
622
|
+
* The port for playback (ADR 0002, ADR 0003, ADR 0008). Playback is a
|
|
623
|
+
* function of the plan and the playhead: loading a changed plan or seeking
|
|
624
|
+
* while playing reschedules from the current position. The SDK's own
|
|
625
|
+
* adapter plays through Web Audio; tests use a fake with a manual clock.
|
|
626
|
+
*
|
|
627
|
+
* Positions are frames on the plan's timeline, from 0 to the plan's length.
|
|
628
|
+
*
|
|
629
|
+
* @public
|
|
630
|
+
*/
|
|
631
|
+
export declare interface AudioOutput {
|
|
632
|
+
getSnapshot(): AudioOutputSnapshot;
|
|
633
|
+
/** Calls the listener after every change of state. Returns a function that unsubscribes. */
|
|
634
|
+
subscribe(listener: () => void): () => void;
|
|
635
|
+
/** The playhead, in frames, read from the audio clock. */
|
|
636
|
+
position(): number;
|
|
637
|
+
/**
|
|
638
|
+
* Sets what plays: the plan and the decoded sources its clips refer to.
|
|
639
|
+
* While playing, playback continues from the current position with the
|
|
640
|
+
* new plan. A playhead past the new plan's end moves to its end.
|
|
641
|
+
*/
|
|
642
|
+
load(plan: AudioPlan, sources: ReadonlyMap<string, DecodedAudio>): void;
|
|
643
|
+
/**
|
|
644
|
+
* Plays from the playhead, or from the start when the playhead is at the
|
|
645
|
+
* end. The first call may need a user gesture, as browsers' autoplay rules
|
|
646
|
+
* require. When playback reaches the end, the state becomes `stopped` and
|
|
647
|
+
* the playhead stays at the end.
|
|
648
|
+
*/
|
|
649
|
+
play(): Promise<void>;
|
|
650
|
+
/** Pauses, keeping the playhead. */
|
|
651
|
+
pause(): void;
|
|
652
|
+
/** Stops, and moves the playhead to the start. */
|
|
653
|
+
stop(): void;
|
|
654
|
+
/** Moves the playhead, clamped to the plan. While playing, playback continues from there. */
|
|
655
|
+
seek(frame: number): void;
|
|
656
|
+
/** Stops playback and releases the audio device. Later calls throw. */
|
|
657
|
+
destroy(): Promise<void>;
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
/**
|
|
661
|
+
* The output's state, for `useSyncExternalStore`. A new object on every
|
|
662
|
+
* change. The playhead isn't in it, because it changes on every audio frame
|
|
663
|
+
* (ADR 0003); read it with {@link AudioOutput.position}.
|
|
664
|
+
*
|
|
665
|
+
* @public
|
|
666
|
+
*/
|
|
667
|
+
export declare interface AudioOutputSnapshot {
|
|
668
|
+
readonly state: AudioOutputState;
|
|
669
|
+
}
|
|
670
|
+
|
|
671
|
+
/**
|
|
672
|
+
* Whether the output is playing.
|
|
673
|
+
*
|
|
674
|
+
* @public
|
|
675
|
+
*/
|
|
676
|
+
export declare type AudioOutputState = "stopped" | "playing" | "paused";
|
|
677
|
+
|
|
678
|
+
/**
|
|
679
|
+
* One level of a waveform overview: the lowest and highest sample of each
|
|
680
|
+
* bucket of frames, per channel.
|
|
681
|
+
*
|
|
682
|
+
* @public
|
|
683
|
+
*/
|
|
684
|
+
export declare interface AudioPeakLevel {
|
|
685
|
+
/** How many frames each bucket covers. */
|
|
686
|
+
readonly framesPerBucket: number;
|
|
687
|
+
/** For each channel, the minimum and maximum sample of each bucket. */
|
|
688
|
+
readonly channels: readonly {
|
|
689
|
+
readonly min: Float32Array;
|
|
690
|
+
readonly max: Float32Array;
|
|
691
|
+
}[];
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/**
|
|
695
|
+
* A source's waveform overview, a min/max pyramid at several zoom levels,
|
|
696
|
+
* computed once so that drawing the waveform never scans samples (ADR 0002).
|
|
697
|
+
* Levels are ordered from the finest to the coarsest.
|
|
698
|
+
*
|
|
699
|
+
* @public
|
|
700
|
+
*/
|
|
701
|
+
export declare interface AudioPeaks {
|
|
702
|
+
readonly levels: readonly AudioPeakLevel[];
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
/**
|
|
706
|
+
* The session's document: clips played back to back on one track, over
|
|
707
|
+
* immutable sources, with the metadata (ADR 0003). Every position and length
|
|
708
|
+
* is a whole number of frames at `sampleRate`.
|
|
709
|
+
*
|
|
710
|
+
* @public
|
|
711
|
+
*/
|
|
712
|
+
export declare interface AudioPlan {
|
|
713
|
+
/** The session's sample rate, from its first source. */
|
|
714
|
+
readonly sampleRate: number;
|
|
715
|
+
/** The session's channel count, from its first source. */
|
|
716
|
+
readonly channels: number;
|
|
717
|
+
readonly clips: readonly AudioClip[];
|
|
718
|
+
readonly metadata: AudioMetadata;
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/**
|
|
722
|
+
* The clip plan as portable JSON: `hm-audio-plan` version 1, which
|
|
723
|
+
* `formats/hm-audio-plan/v1.schema.json` describes (docs/formats/hm-audio-plan.md).
|
|
724
|
+
* Every position is a whole number of frames, and sources are named by the
|
|
725
|
+
* ids their clips use.
|
|
726
|
+
*
|
|
727
|
+
* @public
|
|
728
|
+
*/
|
|
729
|
+
export declare interface AudioPlanDocument {
|
|
730
|
+
readonly format: typeof AUDIO_PLAN_FORMAT;
|
|
731
|
+
readonly version: typeof AUDIO_PLAN_VERSION;
|
|
732
|
+
readonly sampleRate: number;
|
|
733
|
+
readonly channels: number;
|
|
734
|
+
readonly sources: Readonly<Record<string, AudioPlanDocumentSource>>;
|
|
735
|
+
readonly clips: readonly AudioClip[];
|
|
736
|
+
readonly metadata: AudioMetadata;
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/**
|
|
740
|
+
* A source, as a plan document records it: its length, which its clips must
|
|
741
|
+
* lie within, and, once documents travel with their files, its content.
|
|
742
|
+
*
|
|
743
|
+
* @public
|
|
744
|
+
*/
|
|
745
|
+
export declare interface AudioPlanDocumentSource {
|
|
746
|
+
/** The source's length in frames, at the plan's sample rate. */
|
|
747
|
+
readonly frames: number;
|
|
748
|
+
readonly asset?: AudioAssetReference;
|
|
749
|
+
}
|
|
750
|
+
|
|
751
|
+
/**
|
|
752
|
+
* What the probe learned about a file before anything decodes it (ADR 0001,
|
|
753
|
+
* ADR 0004). Limits are checked against it.
|
|
754
|
+
*
|
|
755
|
+
* @public
|
|
756
|
+
*/
|
|
757
|
+
export declare interface AudioProbe {
|
|
758
|
+
readonly container: AudioContainer;
|
|
759
|
+
readonly codec: AudioCodec;
|
|
760
|
+
/** The sample rate the decoder will output, which can differ from the header's, as for Opus. */
|
|
761
|
+
readonly sampleRate: number;
|
|
762
|
+
/** The channel count the decoder will output, which can differ from the header's. */
|
|
763
|
+
readonly channels: number;
|
|
764
|
+
/**
|
|
765
|
+
* The most frames the decoder can output, at {@link AudioProbe.sampleRate}
|
|
766
|
+
* and {@link AudioProbe.channels}: the exact length of an uncompressed
|
|
767
|
+
* file, or the sum over every packet of a compressed one, never a count
|
|
768
|
+
* declared in a header. A packet that could decode to more channels, or
|
|
769
|
+
* at a lower rate that's then resampled, counts as the frames that cover
|
|
770
|
+
* it, so `frameBound × channels × 4` bounds the decoded bytes.
|
|
771
|
+
*/
|
|
772
|
+
readonly frameBound: number;
|
|
773
|
+
/**
|
|
774
|
+
* The expected length in frames: a header's count when it's within
|
|
775
|
+
* {@link AudioProbe.frameBound}, otherwise the bound itself.
|
|
776
|
+
*/
|
|
777
|
+
readonly expectedFrames: number;
|
|
778
|
+
/**
|
|
779
|
+
* For a truncated uncompressed file, as from an interrupted recording or
|
|
780
|
+
* download, the frames its header declares. The file opens with the
|
|
781
|
+
* frames it holds, which are fewer; hosts can say that it's incomplete.
|
|
782
|
+
* Compressed files whose headers claim more than their packets carry fail
|
|
783
|
+
* instead (docs/adr/0001).
|
|
784
|
+
*/
|
|
785
|
+
readonly declaredFrames?: number;
|
|
786
|
+
/**
|
|
787
|
+
* How many frames beyond {@link AudioProbe.frameBound} a decoder may
|
|
788
|
+
* legitimately return, such as one or two codec frames for encoder delay,
|
|
789
|
+
* priming or pre-skip. A longer result fails with `INVALID_AUDIO`.
|
|
790
|
+
*/
|
|
791
|
+
readonly frameTolerance: number;
|
|
792
|
+
}
|
|
793
|
+
|
|
794
|
+
/**
|
|
795
|
+
* The port for exporting: render a plan's clips, with their gain and fades,
|
|
796
|
+
* and encode the result (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
797
|
+
* adapter renders and encodes in its worker, block by block; hosts can pass
|
|
798
|
+
* their own to the editor's `processor` prop, and every implementation must
|
|
799
|
+
* pass the processor's contract tests.
|
|
800
|
+
*
|
|
801
|
+
* Failures reject with `AudioError` for cancellation and worker failures,
|
|
802
|
+
* `TypeError` for a clip whose source isn't in the job, and `RangeError` for
|
|
803
|
+
* a clip outside its source.
|
|
804
|
+
*
|
|
805
|
+
* @public
|
|
806
|
+
*/
|
|
807
|
+
export declare interface AudioProcessor {
|
|
808
|
+
/**
|
|
809
|
+
* Renders and encodes a plan. Every sample is clamped to full scale before
|
|
810
|
+
* it's quantised, so a gain above full scale clips rather than wrapping
|
|
811
|
+
* around. The sources aren't modified.
|
|
812
|
+
*/
|
|
813
|
+
render(job: AudioRenderJob, options?: AudioProgressOptions): Promise<Blob>;
|
|
814
|
+
/** Releases the processor and its worker. Pending calls reject, and later calls throw. */
|
|
815
|
+
destroy(): Promise<void>;
|
|
816
|
+
}
|
|
817
|
+
|
|
818
|
+
/**
|
|
819
|
+
* Options for long calls, which report how far they've got.
|
|
820
|
+
*
|
|
821
|
+
* @public
|
|
822
|
+
*/
|
|
823
|
+
export declare interface AudioProgressOptions extends AudioCallOptions {
|
|
824
|
+
/**
|
|
825
|
+
* Called with the fraction done, from 0 to 1. It only moves forward, and
|
|
826
|
+
* it's called with 1 before the call resolves.
|
|
827
|
+
*/
|
|
828
|
+
readonly onProgress?: (fraction: number) => void;
|
|
829
|
+
}
|
|
830
|
+
|
|
831
|
+
/**
|
|
832
|
+
* What an event says about a recording: its format and size, never its
|
|
833
|
+
* name or contents.
|
|
834
|
+
*
|
|
835
|
+
* @public
|
|
836
|
+
*/
|
|
837
|
+
export declare interface AudioRecordingFacts {
|
|
838
|
+
readonly durationSeconds: number;
|
|
839
|
+
readonly sampleRate: number;
|
|
840
|
+
readonly channels: number;
|
|
841
|
+
readonly container: AudioSourceInfo["container"];
|
|
842
|
+
readonly codec: AudioSourceInfo["codec"];
|
|
843
|
+
readonly truncated: boolean;
|
|
844
|
+
}
|
|
845
|
+
|
|
846
|
+
/**
|
|
847
|
+
* Removes clips. Their sources stay, so undo can bring them back.
|
|
848
|
+
*
|
|
849
|
+
* @public
|
|
850
|
+
*/
|
|
851
|
+
export declare interface AudioRemoveClipsCommand {
|
|
852
|
+
readonly type: "audio.removeClips";
|
|
853
|
+
readonly keys: readonly string[];
|
|
854
|
+
}
|
|
855
|
+
|
|
856
|
+
/**
|
|
857
|
+
* One export: a plan, the decoded sources its clips refer to, and the
|
|
858
|
+
* output format. The plan's metadata goes into the file.
|
|
859
|
+
*
|
|
860
|
+
* @public
|
|
861
|
+
*/
|
|
862
|
+
export declare interface AudioRenderJob {
|
|
863
|
+
readonly plan: AudioPlan;
|
|
864
|
+
/** The decoded sources, by id. Every clip's source must be here. */
|
|
865
|
+
readonly sources: ReadonlyMap<string, DecodedAudio>;
|
|
866
|
+
readonly format: AudioExportFormat;
|
|
867
|
+
}
|
|
868
|
+
|
|
869
|
+
/**
|
|
870
|
+
* Puts every clip in a new order, given as every key exactly once. It's
|
|
871
|
+
* what undoing a move runs.
|
|
872
|
+
*
|
|
873
|
+
* @public
|
|
874
|
+
*/
|
|
875
|
+
export declare interface AudioReorderClipsCommand {
|
|
876
|
+
readonly type: "audio.reorderClips";
|
|
877
|
+
readonly order: readonly string[];
|
|
878
|
+
}
|
|
879
|
+
|
|
880
|
+
/**
|
|
881
|
+
* Replaces `count` clips from `index` with `clips`. It's what undoing an
|
|
882
|
+
* insert, a split or a range deletion runs: those change a run of
|
|
883
|
+
* neighbouring clips.
|
|
884
|
+
*
|
|
885
|
+
* @public
|
|
886
|
+
*/
|
|
887
|
+
export declare interface AudioReplaceClipsCommand {
|
|
888
|
+
readonly type: "audio.replaceClips";
|
|
889
|
+
readonly index: number;
|
|
890
|
+
readonly count: number;
|
|
891
|
+
readonly clips: readonly AudioClip[];
|
|
892
|
+
}
|
|
893
|
+
|
|
894
|
+
/**
|
|
895
|
+
* Puts removed clips back at their indexes, with every field as it was.
|
|
896
|
+
* It's what undoing a removal runs.
|
|
897
|
+
*
|
|
898
|
+
* @public
|
|
899
|
+
*/
|
|
900
|
+
export declare interface AudioRestoreClipsCommand {
|
|
901
|
+
readonly type: "audio.restoreClips";
|
|
902
|
+
/** Each clip, and the index it takes in the resulting plan, in increasing order. */
|
|
903
|
+
readonly entries: readonly {
|
|
904
|
+
readonly index: number;
|
|
905
|
+
readonly clip: AudioClip;
|
|
906
|
+
}[];
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
/**
|
|
910
|
+
* How samples are stored in an exported WAV file (ADR 0001).
|
|
911
|
+
*
|
|
912
|
+
* @public
|
|
913
|
+
*/
|
|
914
|
+
declare type AudioSampleFormat_2 = "pcm16" | "pcm24" | "float32";
|
|
915
|
+
export { AudioSampleFormat_2 as AudioSampleFormat }
|
|
916
|
+
|
|
917
|
+
/**
|
|
918
|
+
* A range of the timeline, in frames: `start` inclusive and `end`
|
|
919
|
+
* exclusive, at least one frame long.
|
|
920
|
+
*
|
|
921
|
+
* @public
|
|
922
|
+
*/
|
|
923
|
+
export declare interface AudioSelection {
|
|
924
|
+
readonly start: number;
|
|
925
|
+
readonly end: number;
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The recording being edited, as a framework-agnostic store (ADR 0008,
|
|
930
|
+
* ADR 0029): a clip plan over decoded sources, edited with commands, with
|
|
931
|
+
* undo and redo (docs/adr/0003). React binds to it with
|
|
932
|
+
* `useSyncExternalStore`, and the element binds to the same store.
|
|
933
|
+
*
|
|
934
|
+
* @public
|
|
935
|
+
*/
|
|
936
|
+
export declare interface AudioSession {
|
|
937
|
+
/** The current snapshot, the same object until something changes. */
|
|
938
|
+
getSnapshot(): AudioSessionSnapshot;
|
|
939
|
+
/** Calls the listener after every change. Returns a function that unsubscribes. */
|
|
940
|
+
subscribe(listener: () => void): () => void;
|
|
941
|
+
/**
|
|
942
|
+
* Opens a recording, replacing the current one and its history once it
|
|
943
|
+
* has opened. The file is checked against the file policy before it's
|
|
944
|
+
* read, and its probe before it's decoded. Rejects with an `AudioError`,
|
|
945
|
+
* which the snapshot also holds; the current recording, if any, stays
|
|
946
|
+
* open.
|
|
947
|
+
*/
|
|
948
|
+
open(file: Blob, options?: AudioProgressOptions): Promise<void>;
|
|
949
|
+
/**
|
|
950
|
+
* Inserts another recording at a timeline frame, as one undoable step. It
|
|
951
|
+
* must have the session's sample rate; resampling comes later. If the
|
|
952
|
+
* sources held would then exceed `maxSessionSize`, the session first drops
|
|
953
|
+
* history steps, in sdk-core's `dropOrder`, as far as needed to release
|
|
954
|
+
* sources only they refer to, and sets `historyTrimmed`. If even that
|
|
955
|
+
* isn't enough, it rejects with `SESSION_TOO_LARGE` and changes nothing.
|
|
956
|
+
*/
|
|
957
|
+
insert(file: Blob, options?: AudioInsertOptions): Promise<void>;
|
|
958
|
+
/**
|
|
959
|
+
* Runs one command, or several as one undoable step. A command that
|
|
960
|
+
* doesn't apply throws `AudioError` with `INVALID_COMMAND`, and one that
|
|
961
|
+
* would exceed `maxClips` throws `TOO_MANY_CLIPS`; either changes
|
|
962
|
+
* nothing. The commands are copied, so changing them afterwards has no
|
|
963
|
+
* effect.
|
|
964
|
+
*/
|
|
965
|
+
execute(commands: AudioCommand | readonly AudioCommand[]): void;
|
|
966
|
+
/**
|
|
967
|
+
* Runs `fn`, and records the commands it executes as one undoable step,
|
|
968
|
+
* for gestures such as dragging a trim handle.
|
|
969
|
+
*/
|
|
970
|
+
group<T>(fn: () => T): T;
|
|
971
|
+
/**
|
|
972
|
+
* A clip key no clip has, in the plan or the history, for commands that
|
|
973
|
+
* create clips, such as `newKey` in `audio.splitClip`.
|
|
974
|
+
*/
|
|
975
|
+
createKey(): string;
|
|
976
|
+
undo(): void;
|
|
977
|
+
redo(): void;
|
|
978
|
+
/**
|
|
979
|
+
* Selects a range of the timeline, clamped to the plan, or clears the
|
|
980
|
+
* selection with `undefined`. An empty range clears it too.
|
|
981
|
+
*/
|
|
982
|
+
select(range: AudioSelection | undefined): void;
|
|
983
|
+
/** A source's waveform overview, or `undefined` for a source the session doesn't hold. */
|
|
984
|
+
getPeaks(source: string): AudioPeaks | undefined;
|
|
985
|
+
/** Closes the recording and releases its sources. */
|
|
986
|
+
close(): Promise<void>;
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
/**
|
|
990
|
+
* Anonymous usage events, for a host's analytics (docs/adr/0003). They
|
|
991
|
+
* never contain file names, samples or metadata values. Durations are in
|
|
992
|
+
* seconds.
|
|
993
|
+
*
|
|
994
|
+
* @public
|
|
995
|
+
*/
|
|
996
|
+
export declare type AudioSessionEvent = ({
|
|
997
|
+
readonly type: "recording_opened" | "recording_inserted";
|
|
998
|
+
} & AudioRecordingFacts) | {
|
|
999
|
+
readonly type: "recording_closed";
|
|
1000
|
+
} | {
|
|
1001
|
+
readonly type: "command";
|
|
1002
|
+
readonly commands: readonly AudioCommand["type"][];
|
|
1003
|
+
} | {
|
|
1004
|
+
readonly type: "undo";
|
|
1005
|
+
} | {
|
|
1006
|
+
readonly type: "redo";
|
|
1007
|
+
} | {
|
|
1008
|
+
readonly type: "failed";
|
|
1009
|
+
readonly operation: "open" | "insert" | "command";
|
|
1010
|
+
readonly code: string;
|
|
1011
|
+
};
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* Options for {@link createAudioSession}.
|
|
1015
|
+
*
|
|
1016
|
+
* @public
|
|
1017
|
+
*/
|
|
1018
|
+
export declare interface AudioSessionOptions {
|
|
1019
|
+
/** Probes, decodes and builds waveform peaks, such as `createAudioEngine()`. */
|
|
1020
|
+
readonly engine: AudioEngine;
|
|
1021
|
+
/** Limits for untrusted files (docs/adr/0004). Unknown names throw. */
|
|
1022
|
+
readonly filePolicy?: AudioFilePolicyOverrides;
|
|
1023
|
+
/** Receives anonymous usage events. Errors it throws are ignored. */
|
|
1024
|
+
readonly onEvent?: (event: AudioSessionEvent) => void;
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
/**
|
|
1028
|
+
* The session's state at one moment (docs/adr/0003). Snapshots are
|
|
1029
|
+
* immutable: every change makes a new one, so `useSyncExternalStore` and
|
|
1030
|
+
* other subscribers can compare them by identity. The playhead isn't here:
|
|
1031
|
+
* it belongs to `AudioOutput`, which moves it sixty times a second.
|
|
1032
|
+
*
|
|
1033
|
+
* @public
|
|
1034
|
+
*/
|
|
1035
|
+
export declare interface AudioSessionSnapshot {
|
|
1036
|
+
readonly status: AudioSessionStatus;
|
|
1037
|
+
/** The recording being edited, or `undefined` when none is open. */
|
|
1038
|
+
readonly plan: AudioPlan | undefined;
|
|
1039
|
+
/** The sources the session holds: those the plan uses, and those undo or redo can bring back. */
|
|
1040
|
+
readonly sources: readonly AudioSourceInfo[];
|
|
1041
|
+
readonly canUndo: boolean;
|
|
1042
|
+
readonly canRedo: boolean;
|
|
1043
|
+
/**
|
|
1044
|
+
* Whether undo steps were dropped since the recording opened, to make
|
|
1045
|
+
* room for an insert within `maxSessionSize`. Editors say so, because the
|
|
1046
|
+
* earliest edits can no longer be undone (ADR 0010).
|
|
1047
|
+
*/
|
|
1048
|
+
readonly historyTrimmed: boolean;
|
|
1049
|
+
/** Whether a recording is being opened or inserted. */
|
|
1050
|
+
readonly busy: boolean;
|
|
1051
|
+
/** Why the last open or insert failed. Show its text by its code. */
|
|
1052
|
+
readonly error: AudioError | undefined;
|
|
1053
|
+
readonly warnings: readonly AudioWarning[];
|
|
1054
|
+
/**
|
|
1055
|
+
* The decoded bytes of every source the session holds, which the
|
|
1056
|
+
* `maxSessionSize` limit counts: frames × channels × 4.
|
|
1057
|
+
*/
|
|
1058
|
+
readonly sessionBytes: number;
|
|
1059
|
+
/** The selected range of the timeline. View state: not undoable, and never in events. */
|
|
1060
|
+
readonly selection: AudioSelection | undefined;
|
|
1061
|
+
}
|
|
1062
|
+
|
|
1063
|
+
/**
|
|
1064
|
+
* What the session is doing.
|
|
1065
|
+
*
|
|
1066
|
+
* - `empty`: no recording is open.
|
|
1067
|
+
* - `opening`: a recording is being opened, replacing any other.
|
|
1068
|
+
* - `ready`: a recording is open.
|
|
1069
|
+
* - `error`: no recording is open, because the last open failed; `error`
|
|
1070
|
+
* says why. A failed open while a recording is open keeps it, with the
|
|
1071
|
+
* status `ready` and `error` set.
|
|
1072
|
+
*
|
|
1073
|
+
* @public
|
|
1074
|
+
*/
|
|
1075
|
+
export declare type AudioSessionStatus = "empty" | "opening" | "ready" | "error";
|
|
1076
|
+
|
|
1077
|
+
/**
|
|
1078
|
+
* Sets a clip's fade in or fade out. Together, the two fades must fit in
|
|
1079
|
+
* the clip.
|
|
1080
|
+
*
|
|
1081
|
+
* @public
|
|
1082
|
+
*/
|
|
1083
|
+
export declare interface AudioSetFadeCommand {
|
|
1084
|
+
readonly type: "audio.setFade";
|
|
1085
|
+
readonly key: string;
|
|
1086
|
+
readonly edge: "in" | "out";
|
|
1087
|
+
/** The fade's length in frames. 0 removes it. */
|
|
1088
|
+
readonly frames: number;
|
|
1089
|
+
readonly curve: AudioFadeCurve;
|
|
1090
|
+
}
|
|
1091
|
+
|
|
1092
|
+
/**
|
|
1093
|
+
* Sets the gain of clips.
|
|
1094
|
+
*
|
|
1095
|
+
* @public
|
|
1096
|
+
*/
|
|
1097
|
+
export declare interface AudioSetGainCommand {
|
|
1098
|
+
readonly type: "audio.setGain";
|
|
1099
|
+
readonly keys: readonly string[];
|
|
1100
|
+
/** Decibels, from `MIN_GAIN_DB` to `MAX_GAIN_DB`. */
|
|
1101
|
+
readonly gainDb: number;
|
|
1102
|
+
}
|
|
1103
|
+
|
|
1104
|
+
/**
|
|
1105
|
+
* Sets one metadata field, which export writes into the file.
|
|
1106
|
+
*
|
|
1107
|
+
* @public
|
|
1108
|
+
*/
|
|
1109
|
+
export declare interface AudioSetMetadataCommand {
|
|
1110
|
+
readonly type: "audio.setMetadata";
|
|
1111
|
+
readonly field: keyof AudioMetadata;
|
|
1112
|
+
/** At most {@link MAX_METADATA_LENGTH} characters. */
|
|
1113
|
+
readonly value: string;
|
|
1114
|
+
}
|
|
1115
|
+
|
|
1116
|
+
/**
|
|
1117
|
+
* A source the session holds, without its samples: what the snapshot shows
|
|
1118
|
+
* (ADR 0003).
|
|
1119
|
+
*
|
|
1120
|
+
* @public
|
|
1121
|
+
*/
|
|
1122
|
+
export declare interface AudioSourceInfo {
|
|
1123
|
+
readonly id: string;
|
|
1124
|
+
readonly sampleRate: number;
|
|
1125
|
+
readonly channels: number;
|
|
1126
|
+
/** The length in frames: the decoded length, capped at the probe's bound (ADR 0004). */
|
|
1127
|
+
readonly frames: number;
|
|
1128
|
+
readonly container: AudioContainer;
|
|
1129
|
+
readonly codec: AudioCodec;
|
|
1130
|
+
}
|
|
1131
|
+
|
|
1132
|
+
/**
|
|
1133
|
+
* Splits a clip in two at a timeline frame inside it. The first part keeps
|
|
1134
|
+
* the clip's key and fade in, and the second takes `newKey` and the fade out.
|
|
1135
|
+
*
|
|
1136
|
+
* @public
|
|
1137
|
+
*/
|
|
1138
|
+
export declare interface AudioSplitClipCommand {
|
|
1139
|
+
readonly type: "audio.splitClip";
|
|
1140
|
+
readonly key: string;
|
|
1141
|
+
/** A timeline frame strictly inside the clip. */
|
|
1142
|
+
readonly at: number;
|
|
1143
|
+
readonly newKey: string;
|
|
1144
|
+
}
|
|
1145
|
+
|
|
1146
|
+
/**
|
|
1147
|
+
* Changes the range of its source a clip plays. Fades that no longer fit
|
|
1148
|
+
* are shortened in proportion.
|
|
1149
|
+
*
|
|
1150
|
+
* @public
|
|
1151
|
+
*/
|
|
1152
|
+
export declare interface AudioTrimClipCommand {
|
|
1153
|
+
readonly type: "audio.trimClip";
|
|
1154
|
+
readonly key: string;
|
|
1155
|
+
/** The first source frame, inclusive. */
|
|
1156
|
+
readonly start: number;
|
|
1157
|
+
/** The source frame the clip stops before, exclusive. */
|
|
1158
|
+
readonly end: number;
|
|
1159
|
+
}
|
|
1160
|
+
|
|
1161
|
+
/**
|
|
1162
|
+
* Sets clips to new states, matched by key, with every field given. It's
|
|
1163
|
+
* what undoing a trim, a gain or a fade runs.
|
|
1164
|
+
*
|
|
1165
|
+
* @public
|
|
1166
|
+
*/
|
|
1167
|
+
export declare interface AudioUpdateClipsCommand {
|
|
1168
|
+
readonly type: "audio.updateClips";
|
|
1169
|
+
readonly clips: readonly AudioClip[];
|
|
1170
|
+
}
|
|
1171
|
+
|
|
1172
|
+
/**
|
|
1173
|
+
* Something the user should know about the recordings open, though they
|
|
1174
|
+
* opened (docs/adr/0004). Show its text from `warnings.<limit>`, or from
|
|
1175
|
+
* `warnings.truncated`, in the message catalogue, with its fields as
|
|
1176
|
+
* parameters.
|
|
1177
|
+
*
|
|
1178
|
+
* - `limit`: a value at or above a limit's warning threshold, but within its
|
|
1179
|
+
* maximum. `source` names the recording it's about, unless it's about the
|
|
1180
|
+
* whole session, as `maxSessionSize` and `maxClips` are.
|
|
1181
|
+
* - `truncated`: an uncompressed recording holds fewer frames than its
|
|
1182
|
+
* header declares, as after an interrupted recording or download. It
|
|
1183
|
+
* opened with the frames it holds.
|
|
1184
|
+
*
|
|
1185
|
+
* @public
|
|
1186
|
+
*/
|
|
1187
|
+
export declare type AudioWarning = {
|
|
1188
|
+
readonly type: "limit";
|
|
1189
|
+
readonly limit: AudioLimitName;
|
|
1190
|
+
readonly actual: number;
|
|
1191
|
+
readonly source?: string;
|
|
1192
|
+
} | {
|
|
1193
|
+
readonly type: "truncated";
|
|
1194
|
+
readonly source: string;
|
|
1195
|
+
/** The frames the recording holds. */
|
|
1196
|
+
readonly frames: number;
|
|
1197
|
+
/** The frames its header declares. */
|
|
1198
|
+
readonly declaredFrames: number;
|
|
1199
|
+
};
|
|
1200
|
+
|
|
1201
|
+
/**
|
|
1202
|
+
* A clip's length in frames.
|
|
1203
|
+
*
|
|
1204
|
+
* @public
|
|
1205
|
+
*/
|
|
1206
|
+
export declare function clipLength(clip: AudioClip): number;
|
|
1207
|
+
|
|
1208
|
+
/**
|
|
1209
|
+
* Where each clip starts on the timeline, in frames. It's derived from the
|
|
1210
|
+
* clips before it, never stored, so it can't disagree with them (ADR 0003).
|
|
1211
|
+
*
|
|
1212
|
+
* @public
|
|
1213
|
+
*/
|
|
1214
|
+
export declare function clipOffsets(plan: AudioPlan): readonly number[];
|
|
1215
|
+
|
|
1216
|
+
/**
|
|
1217
|
+
* Creates the SDK's audio engine (docs/adr/0001, docs/adr/0002). It probes
|
|
1218
|
+
* files in its worker: WAV and AIFF, FLAC (native or in Ogg), MP3, AAC in
|
|
1219
|
+
* ADTS, AAC or ALAC in MP4, Opus or Vorbis in Ogg, and Opus, Vorbis, FLAC
|
|
1220
|
+
* or AAC in WebM and Matroska, walking every frame of a compressed file to
|
|
1221
|
+
* bound its decoded length. It parses WAV and AIFF block by block into an
|
|
1222
|
+
* `AudioBuffer`, building the waveform overview as it goes. It decodes
|
|
1223
|
+
* compressed files with the browser's own decoder, on the page, under
|
|
1224
|
+
* sdk-core ADR 0031's rules: only probed files, a fresh buffer, the output
|
|
1225
|
+
* checked against the probe's bound, errors by code, and the time limit of
|
|
1226
|
+
* the caller's signal. Other containers fail with `UNSUPPORTED_FORMAT`.
|
|
1227
|
+
*
|
|
1228
|
+
* Nothing starts until the first call. By default the worker is inlined,
|
|
1229
|
+
* which needs `worker-src blob:` in a Content Security Policy; with
|
|
1230
|
+
* `assetsUrl` it loads from your own origin, which needs `worker-src 'self'`
|
|
1231
|
+
* instead. Either way it makes no requests of its own.
|
|
1232
|
+
*
|
|
1233
|
+
* @example
|
|
1234
|
+
* ```ts
|
|
1235
|
+
* const engine = createAudioEngine();
|
|
1236
|
+
* const probe = await engine.probe(file);
|
|
1237
|
+
* policy.check("maxDuration", (probe.frameBound / probe.sampleRate) * 1000);
|
|
1238
|
+
* const audio = await engine.decode(file, probe, { onProgress });
|
|
1239
|
+
* ```
|
|
1240
|
+
*
|
|
1241
|
+
* @public
|
|
1242
|
+
*/
|
|
1243
|
+
export declare function createAudioEngine(options?: AudioEngineOptions): AudioEngine;
|
|
1244
|
+
|
|
1245
|
+
/**
|
|
1246
|
+
* Creates an {@link AudioSession}. Pass the engine to use; the headless core
|
|
1247
|
+
* doesn't choose one.
|
|
1248
|
+
*
|
|
1249
|
+
* @example
|
|
1250
|
+
* ```ts
|
|
1251
|
+
* const session = createAudioSession({ engine: createAudioEngine() });
|
|
1252
|
+
* await session.open(file);
|
|
1253
|
+
* const [clip] = session.getSnapshot().plan?.clips ?? [];
|
|
1254
|
+
* session.execute({ type: "audio.setGain", keys: [clip.key], gainDb: -3 });
|
|
1255
|
+
* session.undo();
|
|
1256
|
+
* ```
|
|
1257
|
+
*
|
|
1258
|
+
* @public
|
|
1259
|
+
*/
|
|
1260
|
+
export declare function createAudioSession(options: AudioSessionOptions): AudioSession;
|
|
1261
|
+
|
|
1262
|
+
/**
|
|
1263
|
+
* Converts decibels to a linear gain factor.
|
|
1264
|
+
*
|
|
1265
|
+
* @public
|
|
1266
|
+
*/
|
|
1267
|
+
export declare function dbToGain(db: number): number;
|
|
1268
|
+
|
|
1269
|
+
/**
|
|
1270
|
+
* Decoded audio, as 32-bit float samples per channel. A Web Audio
|
|
1271
|
+
* `AudioBuffer` is one, and tests can supply their own.
|
|
1272
|
+
*
|
|
1273
|
+
* @public
|
|
1274
|
+
*/
|
|
1275
|
+
export declare interface DecodedAudio {
|
|
1276
|
+
readonly sampleRate: number;
|
|
1277
|
+
/** The length in frames. */
|
|
1278
|
+
readonly length: number;
|
|
1279
|
+
readonly numberOfChannels: number;
|
|
1280
|
+
/** The samples of one channel. The caller must not modify them. */
|
|
1281
|
+
getChannelData(channel: number): Float32Array;
|
|
1282
|
+
}
|
|
1283
|
+
|
|
1284
|
+
/**
|
|
1285
|
+
* Metadata with every field empty.
|
|
1286
|
+
*
|
|
1287
|
+
* @public
|
|
1288
|
+
*/
|
|
1289
|
+
export declare const EMPTY_METADATA: AudioMetadata;
|
|
1290
|
+
|
|
1291
|
+
/**
|
|
1292
|
+
* Every position and length in the model is a whole number of frames, at the
|
|
1293
|
+
* session's sample rate (ADR 0003). A frame is one sample on every channel.
|
|
1294
|
+
* Seconds appear only at the edges: in the UI and in events.
|
|
1295
|
+
*/
|
|
1296
|
+
/**
|
|
1297
|
+
* Converts frames to seconds, for display and events.
|
|
1298
|
+
*
|
|
1299
|
+
* @param frames - A whole number of frames.
|
|
1300
|
+
* @param sampleRate - Frames per second.
|
|
1301
|
+
* @public
|
|
1302
|
+
*/
|
|
1303
|
+
export declare function framesToSeconds(frames: number, sampleRate: number): number;
|
|
1304
|
+
|
|
1305
|
+
/**
|
|
1306
|
+
* The gain at one frame of a clip, from its gain and its fades: the single
|
|
1307
|
+
* definition of the envelope, which export applies per sample and playback
|
|
1308
|
+
* samples into the clip's `GainNode` (ADR 0001).
|
|
1309
|
+
*
|
|
1310
|
+
* A fade in starts at silence on the clip's first frame, and a fade out
|
|
1311
|
+
* reaches silence on its last frame.
|
|
1312
|
+
*
|
|
1313
|
+
* @param clip - The clip.
|
|
1314
|
+
* @param frame - A frame within the clip, from 0 to its length minus one.
|
|
1315
|
+
* @public
|
|
1316
|
+
*/
|
|
1317
|
+
export declare function gainAt(clip: AudioClip, frame: number): number;
|
|
1318
|
+
|
|
1319
|
+
/**
|
|
1320
|
+
* Checks whether a value is an {@link AudioError}, optionally with a given
|
|
1321
|
+
* code.
|
|
1322
|
+
*
|
|
1323
|
+
* Unlike `instanceof`, it recognises errors from another copy of this
|
|
1324
|
+
* package or another realm, and errors rebuilt after crossing a worker
|
|
1325
|
+
* boundary.
|
|
1326
|
+
*
|
|
1327
|
+
* @param value - Any thrown value.
|
|
1328
|
+
* @param code - When given, the error must also have this code.
|
|
1329
|
+
* @public
|
|
1330
|
+
*/
|
|
1331
|
+
export declare function isAudioError<Code extends AudioErrorCode = AudioErrorCode>(value: unknown, code?: Code): value is AudioError & {
|
|
1332
|
+
readonly code: Code;
|
|
1333
|
+
};
|
|
1334
|
+
|
|
1335
|
+
/**
|
|
1336
|
+
* The highest clip gain, in decibels: enough to normalize a very quiet
|
|
1337
|
+
* recording, while every gain stays a finite factor.
|
|
1338
|
+
*
|
|
1339
|
+
* @public
|
|
1340
|
+
*/
|
|
1341
|
+
export declare const MAX_GAIN_DB = 120;
|
|
1342
|
+
|
|
1343
|
+
/**
|
|
1344
|
+
* The longest metadata value, in UTF-16 code units, so that history steps
|
|
1345
|
+
* stay small.
|
|
1346
|
+
*
|
|
1347
|
+
* @public
|
|
1348
|
+
*/
|
|
1349
|
+
export declare const MAX_METADATA_LENGTH = 1000;
|
|
1350
|
+
|
|
1351
|
+
/**
|
|
1352
|
+
* The lowest clip gain, in decibels: far below audibility, so it serves as
|
|
1353
|
+
* silence.
|
|
1354
|
+
*
|
|
1355
|
+
* @public
|
|
1356
|
+
*/
|
|
1357
|
+
export declare const MIN_GAIN_DB = -120;
|
|
1358
|
+
|
|
1359
|
+
/**
|
|
1360
|
+
* No fade.
|
|
1361
|
+
*
|
|
1362
|
+
* @public
|
|
1363
|
+
*/
|
|
1364
|
+
export declare const NO_FADE: AudioFade;
|
|
1365
|
+
|
|
1366
|
+
/**
|
|
1367
|
+
* The plan's length in frames: the sum of its clips' lengths.
|
|
1368
|
+
*
|
|
1369
|
+
* @public
|
|
1370
|
+
*/
|
|
1371
|
+
export declare function planLength(plan: AudioPlan): number;
|
|
1372
|
+
|
|
1373
|
+
/**
|
|
1374
|
+
* Reads a plan document, such as one parsed from JSON, checking it as
|
|
1375
|
+
* {@link AudioPlanDocument}'s schema does and more: every clip must lie
|
|
1376
|
+
* within a source the document lists, and keys must be unique. Unknown
|
|
1377
|
+
* fields are refused, never dropped.
|
|
1378
|
+
*
|
|
1379
|
+
* @param value - The parsed JSON.
|
|
1380
|
+
* @returns The plan, and its sources by id.
|
|
1381
|
+
* @throws `AudioError` with `UNSUPPORTED_FORMAT` for another format or a
|
|
1382
|
+
* later version, and `INVALID_DOCUMENT` for anything else that's wrong,
|
|
1383
|
+
* with a {@link AudioDocumentRejection} as `details.reason`.
|
|
1384
|
+
* @public
|
|
1385
|
+
*/
|
|
1386
|
+
export declare function readAudioPlanDocument(value: unknown): {
|
|
1387
|
+
readonly plan: AudioPlan;
|
|
1388
|
+
readonly sources: Readonly<Record<string, AudioPlanDocumentSource>>;
|
|
1389
|
+
};
|
|
1390
|
+
|
|
1391
|
+
/**
|
|
1392
|
+
* Converts seconds to the nearest whole frame, for input from the UI, such
|
|
1393
|
+
* as a typed trim point.
|
|
1394
|
+
*
|
|
1395
|
+
* @param seconds - A time in seconds.
|
|
1396
|
+
* @param sampleRate - Frames per second.
|
|
1397
|
+
* @public
|
|
1398
|
+
*/
|
|
1399
|
+
export declare function secondsToFrames(seconds: number, sampleRate: number): number;
|
|
1400
|
+
|
|
1401
|
+
/**
|
|
1402
|
+
* Writes a plan as an {@link AudioPlanDocument}, plain JSON-ready data.
|
|
1403
|
+
*
|
|
1404
|
+
* @param plan - The plan.
|
|
1405
|
+
* @param sources - The sources by id, with at least every source the plan's
|
|
1406
|
+
* clips use. They're written as given.
|
|
1407
|
+
* @throws `TypeError` if a clip's source is missing from `sources`.
|
|
1408
|
+
* @public
|
|
1409
|
+
*/
|
|
1410
|
+
export declare function toAudioPlanDocument(plan: AudioPlan, sources: Readonly<Record<string, AudioPlanDocumentSource>>): AudioPlanDocument;
|
|
1411
|
+
|
|
1412
|
+
export { }
|