@hussmartinez/audio-sdk 0.5.0 → 0.7.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/README.md +105 -22
- package/dist/assets/audio/audio.worker.js +1 -1
- package/dist/element.d.ts +1010 -1
- package/dist/element.js +121 -0
- package/dist/element.js.map +1 -0
- package/dist/index.d.ts +761 -149
- package/dist/index.js +321 -1782
- package/dist/index.js.map +1 -1
- package/dist/lazy/inline-worker-CVcXmYih.js +30 -0
- package/dist/lazy/{inline-worker-CR5UIkzK.js.map → inline-worker-CVcXmYih.js.map} +1 -1
- package/dist/react.d.ts +1957 -3
- package/dist/react.js +1 -0
- package/dist/shared/AudioEditor-C9yohR_Z.js +2801 -0
- package/dist/shared/AudioEditor-C9yohR_Z.js.map +1 -0
- package/dist/shared/text-CgDrmmTa.js +2663 -0
- package/dist/shared/text-CgDrmmTa.js.map +1 -0
- package/dist/styles.css +329 -0
- package/formats/hm-audio-command/v2.schema.json +381 -0
- package/formats/hm-audio-plan/v2.schema.json +226 -0
- package/package.json +10 -6
- package/dist/lazy/inline-worker-CR5UIkzK.js +0 -30
package/dist/index.d.ts
CHANGED
|
@@ -12,9 +12,19 @@
|
|
|
12
12
|
import { FilePolicy } from '@hussmartinez/sdk-core';
|
|
13
13
|
import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
|
|
14
14
|
import { Limits } from '@hussmartinez/sdk-core';
|
|
15
|
+
import { Messages } from '@hussmartinez/sdk-core';
|
|
15
16
|
import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
|
|
16
17
|
import { SdkError } from '@hussmartinez/sdk-core';
|
|
17
18
|
|
|
19
|
+
/**
|
|
20
|
+
* The tracks that sound: those that aren't muted and, when any track is
|
|
21
|
+
* soloed, are soloed themselves. It's the one definition that playback,
|
|
22
|
+
* export and an editor's dimming all follow.
|
|
23
|
+
*
|
|
24
|
+
* @public
|
|
25
|
+
*/
|
|
26
|
+
export declare function audibleTracks(plan: AudioPlan): readonly AudioTrack[];
|
|
27
|
+
|
|
18
28
|
/**
|
|
19
29
|
* The name of the clip plan's portable format (sdk-core ADR 0045).
|
|
20
30
|
*
|
|
@@ -24,11 +34,59 @@ export declare const AUDIO_PLAN_FORMAT = "hm-audio-plan";
|
|
|
24
34
|
|
|
25
35
|
/**
|
|
26
36
|
* The version of {@link AUDIO_PLAN_FORMAT} this release writes, and the
|
|
27
|
-
* latest it reads.
|
|
37
|
+
* latest it reads. It reads version 1 too, by migrating it.
|
|
38
|
+
*
|
|
39
|
+
* @public
|
|
40
|
+
*/
|
|
41
|
+
export declare const AUDIO_PLAN_VERSION = 2;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The SDK's own adapters, made together: what a session and its playback
|
|
45
|
+
* need. You own them: the session never destroys what it's given, so call
|
|
46
|
+
* {@link AudioAdapters.destroy} after closing the session.
|
|
47
|
+
*
|
|
48
|
+
* @public
|
|
49
|
+
*/
|
|
50
|
+
export declare interface AudioAdapters {
|
|
51
|
+
readonly engine: AudioEngine;
|
|
52
|
+
readonly processor: AudioProcessor;
|
|
53
|
+
readonly output: AudioOutput;
|
|
54
|
+
/** Destroys the engine, the processor and the output, waiting for each. */
|
|
55
|
+
destroy(): Promise<void>;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Options for {@link createAudioAdapters}.
|
|
60
|
+
*
|
|
61
|
+
* @public
|
|
62
|
+
*/
|
|
63
|
+
export declare interface AudioAdaptersOptions {
|
|
64
|
+
/**
|
|
65
|
+
* Where the application serves the package's `dist/assets/` directory, for
|
|
66
|
+
* the engine's and the processor's worker alike (docs/adr/0002). By
|
|
67
|
+
* default the worker is inlined.
|
|
68
|
+
*/
|
|
69
|
+
readonly assetsUrl?: string | URL;
|
|
70
|
+
/** Milliseconds without calls after which each worker stops. Defaults to sdk-core's 30 seconds. */
|
|
71
|
+
readonly idleTimeout?: number;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Adds an empty track at an index.
|
|
28
76
|
*
|
|
29
77
|
* @public
|
|
30
78
|
*/
|
|
31
|
-
export declare
|
|
79
|
+
export declare interface AudioAddTrackCommand {
|
|
80
|
+
readonly type: "audio.addTrack";
|
|
81
|
+
/**
|
|
82
|
+
* The new track's key. `session.execute` gives one from
|
|
83
|
+
* `session.createKey()` when it's left out; a stored command, and the
|
|
84
|
+
* format, always carry it.
|
|
85
|
+
*/
|
|
86
|
+
readonly key?: string;
|
|
87
|
+
readonly index: number;
|
|
88
|
+
readonly name?: string;
|
|
89
|
+
}
|
|
32
90
|
|
|
33
91
|
/**
|
|
34
92
|
* A content-addressed reference to binary data, such as a source's file
|
|
@@ -60,11 +118,24 @@ export declare interface AudioCallOptions {
|
|
|
60
118
|
}
|
|
61
119
|
|
|
62
120
|
/**
|
|
63
|
-
*
|
|
121
|
+
* A clip on a track (docs/adr/0006): a range of a source, starting on the
|
|
122
|
+
* timeline frame `at`. A clip's position is stored, so an edit on one track
|
|
123
|
+
* leaves every other clip where it is.
|
|
124
|
+
*
|
|
125
|
+
* @public
|
|
126
|
+
*/
|
|
127
|
+
export declare interface AudioClip extends AudioClipBody {
|
|
128
|
+
/** The timeline frame the clip starts on. */
|
|
129
|
+
readonly at: number;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* A range of a source with its gain and fades: a clip without its place on
|
|
134
|
+
* the timeline, which is what version 1 of the plan called a clip.
|
|
64
135
|
*
|
|
65
136
|
* @public
|
|
66
137
|
*/
|
|
67
|
-
export declare interface
|
|
138
|
+
export declare interface AudioClipBody {
|
|
68
139
|
/** Stable across edits, so selection and waveform tiles follow a clip that moves. */
|
|
69
140
|
readonly key: string;
|
|
70
141
|
/** The id of the source the clip plays. */
|
|
@@ -95,6 +166,37 @@ export declare interface AudioClip {
|
|
|
95
166
|
*/
|
|
96
167
|
export declare type AudioClipProblem = "invalid-frames" | "clip-too-short" | "clip-outside-source" | "gain-out-of-range" | "fades-too-long";
|
|
97
168
|
|
|
169
|
+
/**
|
|
170
|
+
* One track's part of {@link AudioReplaceClipsCommand}.
|
|
171
|
+
*
|
|
172
|
+
* @public
|
|
173
|
+
*/
|
|
174
|
+
export declare interface AudioClipsEdit {
|
|
175
|
+
readonly track: string;
|
|
176
|
+
/** The first clip of the run to replace. */
|
|
177
|
+
readonly index: number;
|
|
178
|
+
/** How many clips the run has. */
|
|
179
|
+
readonly count: number;
|
|
180
|
+
/** What takes the run's place. */
|
|
181
|
+
readonly clips: readonly AudioClip[];
|
|
182
|
+
/** Frames every clip after the run moves by: negative is earlier. */
|
|
183
|
+
readonly shift: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Version 1 of the plan (docs/adr/0003): one track of clips played back to
|
|
188
|
+
* back. The package reads version 1 documents and commands, and migrates
|
|
189
|
+
* them to version 2 (docs/adr/0006, docs/formats/hm-audio-plan.md). It
|
|
190
|
+
* writes version 2 only.
|
|
191
|
+
*/
|
|
192
|
+
/**
|
|
193
|
+
* A clip of a version 1 plan: a range of a source, with no position of its
|
|
194
|
+
* own. Its place was the sum of the lengths of the clips before it.
|
|
195
|
+
*
|
|
196
|
+
* @public
|
|
197
|
+
*/
|
|
198
|
+
export declare type AudioClipV1 = AudioClipBody;
|
|
199
|
+
|
|
98
200
|
/**
|
|
99
201
|
* The codecs the probe recognises (ADR 0001). `pcm` covers integer and
|
|
100
202
|
* floating-point samples in WAV and AIFF.
|
|
@@ -104,13 +206,15 @@ export declare type AudioClipProblem = "invalid-frames" | "clip-too-short" | "cl
|
|
|
104
206
|
export declare type AudioCodec = "pcm" | "mp3" | "aac" | "alac" | "opus" | "vorbis" | "flac";
|
|
105
207
|
|
|
106
208
|
/**
|
|
107
|
-
* An edit to the
|
|
108
|
-
*
|
|
109
|
-
*
|
|
209
|
+
* An edit to the plan (docs/adr/0003, docs/adr/0006): the user's commands,
|
|
210
|
+
* and the inverses that only undo runs, which aren't part of the portable
|
|
211
|
+
* format. Commands are plain, structured-cloneable data, never carry
|
|
212
|
+
* samples, and each has an exact inverse, which is how undo works
|
|
213
|
+
* (ADR 0010, ADR 0029).
|
|
110
214
|
*
|
|
111
215
|
* @public
|
|
112
216
|
*/
|
|
113
|
-
export declare type AudioCommand =
|
|
217
|
+
export declare type AudioCommand = AudioUserCommand | AudioRestoreClipsCommand | AudioUpdateClipsCommand | AudioPlaceClipsCommand | AudioReplaceClipsCommand | AudioRestoreTracksCommand;
|
|
114
218
|
|
|
115
219
|
/**
|
|
116
220
|
* Why the reducer refused a command, as a stable token: `details.reason` on
|
|
@@ -118,35 +222,40 @@ export declare type AudioCommand = AudioInsertClipsCommand | AudioRemoveClipsCom
|
|
|
118
222
|
* the message (sdk-core ADR 0045). Tokens never change meaning once
|
|
119
223
|
* released.
|
|
120
224
|
*
|
|
121
|
-
* -
|
|
122
|
-
* - `malformed-command`: the command isn't shaped as its type says
|
|
123
|
-
* a list that isn't one, or a clip without a key or source.
|
|
225
|
+
* - A clip's own problems, {@link AudioClipProblem}.
|
|
226
|
+
* - `malformed-command`: the command isn't shaped as its type says.
|
|
124
227
|
* - `unknown-command`: its `type` isn't one of {@link AudioCommand}'s.
|
|
125
228
|
* - `unknown-source`: a clip names a source the session doesn't hold.
|
|
126
229
|
* - `invalid-fade-curve`: a fade's curve isn't `linear` or `equalPower`.
|
|
127
|
-
* - `no-clips`: the command needs at least one
|
|
128
|
-
* - `duplicate-key`: it names a clip twice, or
|
|
129
|
-
*
|
|
130
|
-
* - `
|
|
131
|
-
* - `
|
|
230
|
+
* - `no-clips`, `no-tracks`: the command needs at least one, and names none.
|
|
231
|
+
* - `duplicate-key`: it names a clip or a track twice, or two things would
|
|
232
|
+
* share a key.
|
|
233
|
+
* - `key-taken`: a new clip's or track's key is already in the plan.
|
|
234
|
+
* - `unknown-clip`, `unknown-track`: it names one the plan doesn't have.
|
|
235
|
+
* - `frame-outside-plan`: a timeline frame is outside the plan, or a clip
|
|
236
|
+
* would start before the timeline does.
|
|
132
237
|
* - `empty-range`: a range is shorter than one frame.
|
|
133
238
|
* - `not-inside-clip`: a split frame isn't strictly inside its clip.
|
|
134
239
|
* - `new-key-required`: it cuts a clip in two without the new part's key.
|
|
135
|
-
* - `invalid-index`: an index or a run
|
|
136
|
-
* - `empty-change`:
|
|
137
|
-
* - `invalid-order`: a new order doesn't list every clip exactly once.
|
|
240
|
+
* - `invalid-index`: an index or a run is outside the plan or the track.
|
|
241
|
+
* - `empty-change`: `audio.setTrack` sets nothing.
|
|
138
242
|
* - `invalid-edge`: a fade's edge isn't `in` or `out`.
|
|
139
243
|
* - `unknown-metadata-field`: the metadata has no such field.
|
|
140
|
-
* - `metadata-too-long`: a metadata value is over
|
|
141
|
-
* code points
|
|
244
|
+
* - `metadata-too-long`, `name-too-long`: a metadata value is over
|
|
245
|
+
* {@link MAX_METADATA_LENGTH} code points, or a track's name over
|
|
246
|
+
* {@link MAX_TRACK_NAME_LENGTH}.
|
|
247
|
+
* - `clips-overlap`: a clip would start before the one before it has ended.
|
|
248
|
+
* - `clips-out-of-order`: a list of a track's clips isn't in time order.
|
|
249
|
+
* - `last-track`: it would leave the plan without a track.
|
|
142
250
|
*
|
|
143
251
|
* The session adds `no-recording`, for a command or an export with no
|
|
144
|
-
* recording open, `not-plain-data`, for a command that can't be cloned,
|
|
145
|
-
* `empty-plan`, for an export of a plan with no clips
|
|
252
|
+
* recording open, `not-plain-data`, for a command that can't be cloned,
|
|
253
|
+
* `empty-plan`, for an export of a plan with no clips, and
|
|
254
|
+
* `nothing-audible`, for an export in which no track with clips sounds.
|
|
146
255
|
*
|
|
147
256
|
* @public
|
|
148
257
|
*/
|
|
149
|
-
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-
|
|
258
|
+
export declare type AudioCommandRejection = AudioClipProblem | "malformed-command" | "unknown-command" | "unknown-source" | "invalid-fade-curve" | "no-clips" | "no-tracks" | "duplicate-key" | "key-taken" | "unknown-clip" | "unknown-track" | "frame-outside-plan" | "empty-range" | "not-inside-clip" | "new-key-required" | "invalid-index" | "empty-change" | "invalid-edge" | "unknown-metadata-field" | "metadata-too-long" | "name-too-long" | "clips-overlap" | "clips-out-of-order" | "last-track" | "no-recording" | "not-plain-data" | "empty-plan" | "nothing-audible";
|
|
150
259
|
|
|
151
260
|
/**
|
|
152
261
|
* The containers the probe recognises (ADR 0001).
|
|
@@ -156,20 +265,40 @@ export declare type AudioCommandRejection = AudioClipProblem | "malformed-comman
|
|
|
156
265
|
export declare type AudioContainer = "wav" | "aiff" | "flac" | "ogg" | "mp3" | "adts" | "mp4" | "webm";
|
|
157
266
|
|
|
158
267
|
/**
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
268
|
+
* Options for `AudioEngine.decode`.
|
|
269
|
+
*
|
|
270
|
+
* @public
|
|
271
|
+
*/
|
|
272
|
+
export declare interface AudioDecodeOptions extends AudioProgressOptions {
|
|
273
|
+
/**
|
|
274
|
+
* The sample rate to return the audio at, in hertz, when it isn't the
|
|
275
|
+
* probe's: the engine converts it, as the session asks for a recording
|
|
276
|
+
* inserted at another rate than its own (docs/adr/0006). The result then
|
|
277
|
+
* has `Math.ceil(frames × sampleRate / probe.sampleRate)` frames, which
|
|
278
|
+
* cover the same time.
|
|
279
|
+
*/
|
|
280
|
+
readonly sampleRate?: number;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Removes a range of time from the named tracks, trimming the clips at its
|
|
285
|
+
* edges. With `ripple`, later clips on those tracks move earlier by the
|
|
286
|
+
* range's length; without, silence stays.
|
|
162
287
|
*
|
|
163
288
|
* @public
|
|
164
289
|
*/
|
|
165
290
|
export declare interface AudioDeleteRangeCommand {
|
|
166
291
|
readonly type: "audio.deleteRange";
|
|
167
|
-
/** The first timeline frame removed, inclusive. */
|
|
168
292
|
readonly start: number;
|
|
169
|
-
/** The timeline frame the range stops before, exclusive. */
|
|
170
293
|
readonly end: number;
|
|
171
|
-
|
|
172
|
-
readonly
|
|
294
|
+
readonly tracks: readonly string[];
|
|
295
|
+
readonly ripple: boolean;
|
|
296
|
+
/**
|
|
297
|
+
* By track key: the key of the part after the range, on a track where the
|
|
298
|
+
* range lies inside one clip. A track that doesn't need its key ignores it.
|
|
299
|
+
* `session.execute` gives a key to every track named without one.
|
|
300
|
+
*/
|
|
301
|
+
readonly newKeys?: Readonly<Record<string, string>>;
|
|
173
302
|
}
|
|
174
303
|
|
|
175
304
|
/**
|
|
@@ -181,13 +310,16 @@ export declare interface AudioDeleteRangeCommand {
|
|
|
181
310
|
* reads.
|
|
182
311
|
* - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
|
|
183
312
|
* shaped as the schema says; `unknown-source`, a clip whose source the
|
|
184
|
-
* document doesn't list; `duplicate-key`,
|
|
185
|
-
* `
|
|
186
|
-
*
|
|
313
|
+
* document doesn't list; `duplicate-key`, a key used twice among tracks
|
|
314
|
+
* and clips; `clips-overlap` and `clips-out-of-order`, a track whose
|
|
315
|
+
* clips aren't in time order without overlap; `no-tracks`, a plan with
|
|
316
|
+
* none; `invalid-fade-curve`, `metadata-too-long`, `name-too-long` and
|
|
317
|
+
* `gain-out-of-range`, as for commands; and a clip's own problems,
|
|
318
|
+
* {@link AudioClipProblem}.
|
|
187
319
|
*
|
|
188
320
|
* @public
|
|
189
321
|
*/
|
|
190
|
-
export declare type AudioDocumentRejection = AudioClipProblem | "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "duplicate-key" | "invalid-fade-curve" | "metadata-too-long";
|
|
322
|
+
export declare type AudioDocumentRejection = AudioClipProblem | "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "duplicate-key" | "invalid-fade-curve" | "metadata-too-long" | "name-too-long" | "clips-overlap" | "clips-out-of-order" | "no-tracks";
|
|
191
323
|
|
|
192
324
|
/**
|
|
193
325
|
* The port for reading audio files: probe a file's headers, decode it, and
|
|
@@ -213,11 +345,13 @@ export declare interface AudioEngine {
|
|
|
213
345
|
*/
|
|
214
346
|
probe(file: Blob, options?: AudioCallOptions): Promise<AudioProbe>;
|
|
215
347
|
/**
|
|
216
|
-
* Decodes a probed file at the probe's
|
|
217
|
-
*
|
|
218
|
-
*
|
|
348
|
+
* Decodes a probed file at the probe's channel count, and at the probe's
|
|
349
|
+
* sample rate unless `options.sampleRate` asks for another, which the
|
|
350
|
+
* engine converts the audio to. A result longer than the probe's bound
|
|
351
|
+
* plus its tolerance rejects with `INVALID_AUDIO`; a shorter one is
|
|
352
|
+
* returned as it is.
|
|
219
353
|
*/
|
|
220
|
-
decode(file: Blob, probe: AudioProbe, options?:
|
|
354
|
+
decode(file: Blob, probe: AudioProbe, options?: AudioDecodeOptions): Promise<DecodedAudio>;
|
|
221
355
|
/**
|
|
222
356
|
* Builds a waveform overview of decoded audio. The audio isn't modified or
|
|
223
357
|
* kept.
|
|
@@ -291,12 +425,15 @@ export declare class AudioError extends SdkError<AudioErrorCode> {
|
|
|
291
425
|
* as a range outside its source or an unknown clip key.
|
|
292
426
|
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
293
427
|
* valid in its format.
|
|
294
|
-
* - `DURATION_TOO_LONG`: a file
|
|
428
|
+
* - `DURATION_TOO_LONG`: a file, or the plan an edit would give, exceeds the
|
|
429
|
+
* `maxDuration` limit.
|
|
295
430
|
* - `TOO_MANY_CHANNELS`: a file exceeds the `maxChannels` limit.
|
|
296
431
|
* - `SAMPLE_RATE_TOO_HIGH`: a file exceeds the `maxSampleRate` limit.
|
|
297
432
|
* - `SESSION_TOO_LARGE`: the decoded audio the session holds exceeds the
|
|
298
433
|
* `maxSessionSize` limit.
|
|
299
|
-
* - `TOO_MANY_CLIPS`: the
|
|
434
|
+
* - `TOO_MANY_CLIPS`: the plan exceeds the `maxClips` limit, over all its
|
|
435
|
+
* tracks.
|
|
436
|
+
* - `TOO_MANY_TRACKS`: the plan exceeds the `maxTracks` limit.
|
|
300
437
|
*
|
|
301
438
|
* Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
|
|
302
439
|
* value and the `unit`. Other codes' `details` name the container, codec or
|
|
@@ -304,7 +441,27 @@ export declare class AudioError extends SdkError<AudioErrorCode> {
|
|
|
304
441
|
*
|
|
305
442
|
* @public
|
|
306
443
|
*/
|
|
307
|
-
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";
|
|
444
|
+
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" | "TOO_MANY_TRACKS";
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* The user-facing text for an error: the catalogue's text for its code and
|
|
448
|
+
* `details.reason` together, `errors.<CODE>.<reason>`, when there is one,
|
|
449
|
+
* and otherwise `messages.error(error)`, the text for its code. So a blocked
|
|
450
|
+
* `play()` says that sound needs a press of Play, rather than that the
|
|
451
|
+
* browser lacks a feature (point 9 of #54).
|
|
452
|
+
*
|
|
453
|
+
* sdk-core's `messages.error()` may take over this fallback for the family;
|
|
454
|
+
* until then, use this one.
|
|
455
|
+
*
|
|
456
|
+
* @example
|
|
457
|
+
* ```ts
|
|
458
|
+
* const messages = createMessages(audioMessages, { locale: "en" });
|
|
459
|
+
* showError(audioErrorText(messages, error));
|
|
460
|
+
* ```
|
|
461
|
+
*
|
|
462
|
+
* @public
|
|
463
|
+
*/
|
|
464
|
+
export declare function audioErrorText(messages: Messages<AudioMessageCatalogue>, error: unknown): string;
|
|
308
465
|
|
|
309
466
|
/**
|
|
310
467
|
* The file an export produces. WAV is the only container so far (ADR 0001).
|
|
@@ -363,20 +520,34 @@ export declare type AudioFilePolicy = FilePolicy<AudioLimitDefinitions>;
|
|
|
363
520
|
export declare type AudioFilePolicyOverrides = FilePolicyOverrides<AudioLimitDefinitions>;
|
|
364
521
|
|
|
365
522
|
/**
|
|
366
|
-
*
|
|
367
|
-
*
|
|
368
|
-
*
|
|
523
|
+
* How {@link watchPlayhead} waits for the next frame to draw: the page's
|
|
524
|
+
* `requestAnimationFrame` by default.
|
|
525
|
+
*
|
|
526
|
+
* @public
|
|
527
|
+
*/
|
|
528
|
+
export declare interface AudioFrameScheduler {
|
|
529
|
+
request(callback: () => void): unknown;
|
|
530
|
+
cancel(handle: unknown): void;
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
/**
|
|
534
|
+
* The plan's commands and reducer (docs/adr/0003, docs/adr/0006).
|
|
535
|
+
*
|
|
536
|
+
* Edits are of two kinds. **Clip edits never move another clip:** they fail
|
|
537
|
+
* with `clips-overlap` rather than push a neighbour. **Time edits add or
|
|
538
|
+
* remove time on the tracks they name,** and move everything after it on
|
|
539
|
+
* those tracks.
|
|
540
|
+
*/
|
|
541
|
+
/**
|
|
542
|
+
* Adds clips to a track, each at its own `at`, in free space.
|
|
369
543
|
*
|
|
370
544
|
* @public
|
|
371
545
|
*/
|
|
372
546
|
export declare interface AudioInsertClipsCommand {
|
|
373
547
|
readonly type: "audio.insertClips";
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
/** The clips, in order, with keys the plan doesn't have. */
|
|
548
|
+
readonly track: string;
|
|
549
|
+
/** The clips, in any order, with keys the plan doesn't have. */
|
|
377
550
|
readonly clips: readonly AudioClip[];
|
|
378
|
-
/** The key of the second part of a clip that `at` splits. Required only then. */
|
|
379
|
-
readonly splitKey?: string;
|
|
380
551
|
}
|
|
381
552
|
|
|
382
553
|
/**
|
|
@@ -384,14 +555,47 @@ export declare interface AudioInsertClipsCommand {
|
|
|
384
555
|
*
|
|
385
556
|
* @public
|
|
386
557
|
*/
|
|
387
|
-
export declare interface AudioInsertOptions extends
|
|
558
|
+
export declare interface AudioInsertOptions extends AudioOpenOptions {
|
|
388
559
|
/**
|
|
389
|
-
* The
|
|
390
|
-
*
|
|
560
|
+
* The key of the track the recording goes on, where it needs free space.
|
|
561
|
+
* Without it, the recording gets a new track of its own, below the
|
|
562
|
+
* others: laying one recording under another is the common case.
|
|
391
563
|
*/
|
|
564
|
+
readonly track?: string;
|
|
565
|
+
/** The timeline frame the recording starts on. Defaults to 0. */
|
|
392
566
|
readonly at?: number;
|
|
393
567
|
}
|
|
394
568
|
|
|
569
|
+
/**
|
|
570
|
+
* Opens `frames` of silence at a timeline frame on the named tracks. A clip
|
|
571
|
+
* that lies across the frame is split there, and everything after moves
|
|
572
|
+
* later.
|
|
573
|
+
*
|
|
574
|
+
* @public
|
|
575
|
+
*/
|
|
576
|
+
export declare interface AudioInsertTimeCommand {
|
|
577
|
+
readonly type: "audio.insertTime";
|
|
578
|
+
readonly at: number;
|
|
579
|
+
readonly frames: number;
|
|
580
|
+
readonly tracks: readonly string[];
|
|
581
|
+
/**
|
|
582
|
+
* By track key: the key of the second part of a clip the frame splits.
|
|
583
|
+
* `session.execute` gives a key to every track named without one.
|
|
584
|
+
*/
|
|
585
|
+
readonly newKeys?: Readonly<Record<string, string>>;
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* Removes everything outside a range, on every track, and moves what's kept to the start.
|
|
590
|
+
*
|
|
591
|
+
* @public
|
|
592
|
+
*/
|
|
593
|
+
export declare interface AudioKeepRangeCommand {
|
|
594
|
+
readonly type: "audio.keepRange";
|
|
595
|
+
readonly start: number;
|
|
596
|
+
readonly end: number;
|
|
597
|
+
}
|
|
598
|
+
|
|
395
599
|
/**
|
|
396
600
|
* The type of {@link audioLimitDefinitions}.
|
|
397
601
|
*
|
|
@@ -401,7 +605,7 @@ export declare type AudioLimitDefinitions = typeof audioLimitDefinitions;
|
|
|
401
605
|
|
|
402
606
|
/**
|
|
403
607
|
* The audio SDK's limit definitions: sdk-core's core limits with audio
|
|
404
|
-
* defaults, plus
|
|
608
|
+
* defaults, plus six for audio (ADR 0004, docs/adr/0006).
|
|
405
609
|
*
|
|
406
610
|
* | Limit | Code | Default maximum | Default warning |
|
|
407
611
|
* |---|---|---|---|
|
|
@@ -414,10 +618,13 @@ export declare type AudioLimitDefinitions = typeof audioLimitDefinitions;
|
|
|
414
618
|
* | `maxSampleRate` | `SAMPLE_RATE_TOO_HIGH` | 192 kHz | none |
|
|
415
619
|
* | `maxSessionSize` | `SESSION_TOO_LARGE` | 1.5 GB | 750 MB |
|
|
416
620
|
* | `maxClips` | `TOO_MANY_CLIPS` | 2,000 | none |
|
|
621
|
+
* | `maxTracks` | `TOO_MANY_TRACKS` | 16 | none |
|
|
417
622
|
*
|
|
418
623
|
* Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 32-bit
|
|
419
624
|
* floats: frames × channels × 4 bytes. `maxDuration` is in milliseconds, and
|
|
420
|
-
* `maxSampleRate` is in hertz.
|
|
625
|
+
* `maxSampleRate` is in hertz. `maxDuration` bounds each file, and the plan's
|
|
626
|
+
* length too: positions are free, so no file's limit keeps a clip from being
|
|
627
|
+
* placed hours in. `maxClips` counts the clips of every track together.
|
|
421
628
|
*
|
|
422
629
|
* @public
|
|
423
630
|
*/
|
|
@@ -461,6 +668,11 @@ export declare const audioLimitDefinitions: {
|
|
|
461
668
|
readonly unit: "count";
|
|
462
669
|
readonly default: 2000;
|
|
463
670
|
};
|
|
671
|
+
readonly maxTracks: {
|
|
672
|
+
readonly code: "TOO_MANY_TRACKS";
|
|
673
|
+
readonly unit: "count";
|
|
674
|
+
readonly default: 16;
|
|
675
|
+
};
|
|
464
676
|
readonly maxFiles: {
|
|
465
677
|
readonly code: "TOO_MANY_FILES";
|
|
466
678
|
readonly unit: "count";
|
|
@@ -536,6 +748,12 @@ export declare const audioMessages: {
|
|
|
536
748
|
readonly one: "A recording can have {maximum} clip. Join or delete clips, and try again.";
|
|
537
749
|
readonly other: "A recording can have up to {maximum} clips. Join or delete clips, and try again.";
|
|
538
750
|
};
|
|
751
|
+
readonly "errors.TOO_MANY_TRACKS": {
|
|
752
|
+
readonly $plural: "maximum";
|
|
753
|
+
} & {
|
|
754
|
+
readonly one: "A recording can have {maximum} track. Remove a track, and try again.";
|
|
755
|
+
readonly other: "A recording can have up to {maximum} tracks. Remove a track, and try again.";
|
|
756
|
+
};
|
|
539
757
|
readonly "warnings.maxDuration": "This recording is {actual, duration} long, and may be slow to open and edit.";
|
|
540
758
|
readonly "warnings.maxChannels": "This recording has {actual, number} channels, and may be slow to edit.";
|
|
541
759
|
readonly "warnings.maxSampleRate": "This recording's sample rate is {actual, number} Hz, and it may be slow to edit.";
|
|
@@ -546,6 +764,14 @@ export declare const audioMessages: {
|
|
|
546
764
|
readonly one: "This recording has {actual} clip. Many clips may be slow to play and export.";
|
|
547
765
|
readonly other: "This recording has {actual} clips. Many clips may be slow to play and export.";
|
|
548
766
|
};
|
|
767
|
+
readonly "warnings.maxTracks": {
|
|
768
|
+
readonly $plural: "actual";
|
|
769
|
+
} & {
|
|
770
|
+
readonly one: "This recording has {actual} track. Many tracks may be slow to play and export.";
|
|
771
|
+
readonly other: "This recording has {actual} tracks. Many tracks may be slow to play and export.";
|
|
772
|
+
};
|
|
773
|
+
readonly "errors.UNSUPPORTED_ENVIRONMENT.autoplay-blocked": "The browser didn't let sound start. Press Play to start it.";
|
|
774
|
+
readonly "errors.DURATION_TOO_LONG.plan-too-long": "This would make the recording {actual, duration} long, which is over the {maximum, duration} limit.";
|
|
549
775
|
readonly "warnings.truncated": "This recording looks incomplete, perhaps from an interrupted recording or download. It opened with the audio it holds.";
|
|
550
776
|
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
551
777
|
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
@@ -608,17 +834,45 @@ export declare interface AudioMetadata {
|
|
|
608
834
|
}
|
|
609
835
|
|
|
610
836
|
/**
|
|
611
|
-
* Moves clips
|
|
612
|
-
* ends up at index `to` of the resulting plan.
|
|
837
|
+
* Moves clips by a signed number of frames, and to another track when one is named.
|
|
613
838
|
*
|
|
614
839
|
* @public
|
|
615
840
|
*/
|
|
616
841
|
export declare interface AudioMoveClipsCommand {
|
|
617
842
|
readonly type: "audio.moveClips";
|
|
618
843
|
readonly keys: readonly string[];
|
|
844
|
+
/** Frames to move by: negative is earlier. */
|
|
845
|
+
readonly by: number;
|
|
846
|
+
/** The track every clip moves to. Without it, each stays on its own. */
|
|
847
|
+
readonly track?: string;
|
|
848
|
+
}
|
|
849
|
+
|
|
850
|
+
/**
|
|
851
|
+
* Moves a track to an index of the resulting plan.
|
|
852
|
+
*
|
|
853
|
+
* @public
|
|
854
|
+
*/
|
|
855
|
+
export declare interface AudioMoveTrackCommand {
|
|
856
|
+
readonly type: "audio.moveTrack";
|
|
857
|
+
readonly key: string;
|
|
619
858
|
readonly to: number;
|
|
620
859
|
}
|
|
621
860
|
|
|
861
|
+
/**
|
|
862
|
+
* Options for {@link AudioSession.insert}.
|
|
863
|
+
*
|
|
864
|
+
* @public
|
|
865
|
+
*/
|
|
866
|
+
declare interface AudioOpenOptions extends AudioProgressOptions {
|
|
867
|
+
/**
|
|
868
|
+
* A name for the recording, to show people, such as its file's. It wins
|
|
869
|
+
* over a `File`'s own name, which is used without it. It's cleaned as
|
|
870
|
+
* pdf-sdk ADR 0009 decides, and kept on the source in `snapshot.sources`,
|
|
871
|
+
* never in events, the plan or a document.
|
|
872
|
+
*/
|
|
873
|
+
readonly name?: string;
|
|
874
|
+
}
|
|
875
|
+
|
|
622
876
|
/**
|
|
623
877
|
* The port for playback (ADR 0002, ADR 0003, ADR 0008). Playback is a
|
|
624
878
|
* function of the plan and the playhead: loading a changed plan or seeking
|
|
@@ -631,9 +885,14 @@ export declare interface AudioMoveClipsCommand {
|
|
|
631
885
|
*/
|
|
632
886
|
export declare interface AudioOutput {
|
|
633
887
|
getSnapshot(): AudioOutputSnapshot;
|
|
634
|
-
/**
|
|
888
|
+
/**
|
|
889
|
+
* Calls the listener after every change of state, and whenever the
|
|
890
|
+
* playhead jumps, but not as it moves while playing. Returns a function
|
|
891
|
+
* that unsubscribes. Like every method here, it works detached from the
|
|
892
|
+
* object.
|
|
893
|
+
*/
|
|
635
894
|
subscribe(listener: () => void): () => void;
|
|
636
|
-
/** The playhead,
|
|
895
|
+
/** The playhead, a whole number of frames, read from the audio clock while playing. */
|
|
637
896
|
position(): number;
|
|
638
897
|
/**
|
|
639
898
|
* Sets what plays: the plan and the decoded sources its clips refer to.
|
|
@@ -660,8 +919,10 @@ export declare interface AudioOutput {
|
|
|
660
919
|
|
|
661
920
|
/**
|
|
662
921
|
* The output's state, for `useSyncExternalStore`. A new object on every
|
|
663
|
-
* change
|
|
664
|
-
*
|
|
922
|
+
* change of state, and whenever the playhead jumps: a seek, a stop, or a
|
|
923
|
+
* plan that moves it. The playhead isn't in it, because it changes on every
|
|
924
|
+
* audio frame (ADR 0003); read it with {@link AudioOutput.position}, or
|
|
925
|
+
* follow it with `watchPlayhead`.
|
|
665
926
|
*
|
|
666
927
|
* @public
|
|
667
928
|
*/
|
|
@@ -676,6 +937,32 @@ export declare interface AudioOutputSnapshot {
|
|
|
676
937
|
*/
|
|
677
938
|
export declare type AudioOutputState = "stopped" | "playing" | "paused";
|
|
678
939
|
|
|
940
|
+
/**
|
|
941
|
+
* The lowest and highest sample of each column of a waveform, over every
|
|
942
|
+
* channel, as {@link peakColumns} gives them.
|
|
943
|
+
*
|
|
944
|
+
* @public
|
|
945
|
+
*/
|
|
946
|
+
export declare interface AudioPeakColumns {
|
|
947
|
+
readonly min: Float32Array<ArrayBuffer>;
|
|
948
|
+
readonly max: Float32Array<ArrayBuffer>;
|
|
949
|
+
}
|
|
950
|
+
|
|
951
|
+
/**
|
|
952
|
+
* Options for {@link peakColumns}: the source frames to draw, and how many
|
|
953
|
+
* columns to draw them in.
|
|
954
|
+
*
|
|
955
|
+
* @public
|
|
956
|
+
*/
|
|
957
|
+
export declare interface AudioPeakColumnsOptions {
|
|
958
|
+
/** The first source frame, inclusive. */
|
|
959
|
+
readonly from: number;
|
|
960
|
+
/** The source frame to stop before. */
|
|
961
|
+
readonly to: number;
|
|
962
|
+
/** How many columns, such as device pixels, a whole number from 1. */
|
|
963
|
+
readonly columns: number;
|
|
964
|
+
}
|
|
965
|
+
|
|
679
966
|
/**
|
|
680
967
|
* One level of a waveform overview: the lowest and highest sample of each
|
|
681
968
|
* bucket of frames, per channel.
|
|
@@ -704,26 +991,44 @@ export declare interface AudioPeaks {
|
|
|
704
991
|
}
|
|
705
992
|
|
|
706
993
|
/**
|
|
707
|
-
*
|
|
708
|
-
*
|
|
709
|
-
*
|
|
994
|
+
* Puts clips on tracks and positions. Undo's, for a move, and its own inverse.
|
|
995
|
+
*
|
|
996
|
+
* @public
|
|
997
|
+
*/
|
|
998
|
+
export declare interface AudioPlaceClipsCommand {
|
|
999
|
+
readonly type: "audio.placeClips";
|
|
1000
|
+
readonly entries: readonly {
|
|
1001
|
+
readonly key: string;
|
|
1002
|
+
readonly track: string;
|
|
1003
|
+
readonly at: number;
|
|
1004
|
+
}[];
|
|
1005
|
+
}
|
|
1006
|
+
|
|
1007
|
+
/**
|
|
1008
|
+
* The session's document (docs/adr/0003, docs/adr/0006): tracks of clips
|
|
1009
|
+
* positioned in time, over immutable sources, mixed on playback and export,
|
|
1010
|
+
* with the metadata. Every position and length is a whole number of frames
|
|
1011
|
+
* at `sampleRate`.
|
|
710
1012
|
*
|
|
711
1013
|
* @public
|
|
712
1014
|
*/
|
|
713
1015
|
export declare interface AudioPlan {
|
|
714
1016
|
/** The session's sample rate, from its first source. */
|
|
715
1017
|
readonly sampleRate: number;
|
|
716
|
-
/** The session's channel count
|
|
1018
|
+
/** The session's channel count: its first source's, raised by a wider one. */
|
|
717
1019
|
readonly channels: number;
|
|
718
|
-
|
|
1020
|
+
/** The master gain in decibels, applied to the mix. */
|
|
1021
|
+
readonly gainDb: number;
|
|
1022
|
+
/** From top to bottom. A plan always has at least one. */
|
|
1023
|
+
readonly tracks: readonly AudioTrack[];
|
|
719
1024
|
readonly metadata: AudioMetadata;
|
|
720
1025
|
}
|
|
721
1026
|
|
|
722
1027
|
/**
|
|
723
|
-
* The
|
|
724
|
-
* `formats/hm-audio-plan/
|
|
725
|
-
* Every position is a whole number of
|
|
726
|
-
* ids their clips use.
|
|
1028
|
+
* The plan as portable JSON: `hm-audio-plan` version 2, which
|
|
1029
|
+
* `formats/hm-audio-plan/v2.schema.json` describes
|
|
1030
|
+
* (docs/formats/hm-audio-plan.md). Every position is a whole number of
|
|
1031
|
+
* frames, and sources are named by the ids their clips use.
|
|
727
1032
|
*
|
|
728
1033
|
* @public
|
|
729
1034
|
*/
|
|
@@ -732,8 +1037,9 @@ export declare interface AudioPlanDocument {
|
|
|
732
1037
|
readonly version: typeof AUDIO_PLAN_VERSION;
|
|
733
1038
|
readonly sampleRate: number;
|
|
734
1039
|
readonly channels: number;
|
|
1040
|
+
readonly gainDb: number;
|
|
735
1041
|
readonly sources: Readonly<Record<string, AudioPlanDocumentSource>>;
|
|
736
|
-
readonly
|
|
1042
|
+
readonly tracks: readonly AudioTrack[];
|
|
737
1043
|
readonly metadata: AudioMetadata;
|
|
738
1044
|
}
|
|
739
1045
|
|
|
@@ -749,6 +1055,18 @@ export declare interface AudioPlanDocumentSource {
|
|
|
749
1055
|
readonly asset?: AudioAssetReference;
|
|
750
1056
|
}
|
|
751
1057
|
|
|
1058
|
+
/**
|
|
1059
|
+
* A version 1 plan: clips played back to back on one track.
|
|
1060
|
+
*
|
|
1061
|
+
* @public
|
|
1062
|
+
*/
|
|
1063
|
+
export declare interface AudioPlanV1 {
|
|
1064
|
+
readonly sampleRate: number;
|
|
1065
|
+
readonly channels: number;
|
|
1066
|
+
readonly clips: readonly AudioClipV1[];
|
|
1067
|
+
readonly metadata: AudioMetadata;
|
|
1068
|
+
}
|
|
1069
|
+
|
|
752
1070
|
/**
|
|
753
1071
|
* What the probe learned about a file before anything decodes it (ADR 0001,
|
|
754
1072
|
* ADR 0004). Limits are checked against it.
|
|
@@ -793,8 +1111,8 @@ export declare interface AudioProbe {
|
|
|
793
1111
|
}
|
|
794
1112
|
|
|
795
1113
|
/**
|
|
796
|
-
* The port for exporting:
|
|
797
|
-
* and encode the result (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
1114
|
+
* The port for exporting: mix a plan's audible tracks, with their clips'
|
|
1115
|
+
* gain and fades, and encode the result (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
798
1116
|
* adapter renders and encodes in its worker, block by block; hosts can pass
|
|
799
1117
|
* their own to the editor's `processor` prop, and every implementation must
|
|
800
1118
|
* pass the processor's contract tests.
|
|
@@ -807,11 +1125,12 @@ export declare interface AudioProbe {
|
|
|
807
1125
|
*/
|
|
808
1126
|
export declare interface AudioProcessor {
|
|
809
1127
|
/**
|
|
810
|
-
*
|
|
811
|
-
* it's quantised, so a
|
|
812
|
-
* around
|
|
1128
|
+
* Mixes and encodes a plan, up to where its last audible clip ends. Every
|
|
1129
|
+
* sample is clamped to full scale before it's quantised, so a mix above
|
|
1130
|
+
* full scale clips rather than wrapping around, and the result says how
|
|
1131
|
+
* far over it went. The sources aren't modified.
|
|
813
1132
|
*/
|
|
814
|
-
render(job: AudioRenderJob, options?: AudioProgressOptions): Promise<
|
|
1133
|
+
render(job: AudioRenderJob, options?: AudioProgressOptions): Promise<AudioRenderResult>;
|
|
815
1134
|
/** Releases the processor and its worker. Pending calls reject, and later calls throw. */
|
|
816
1135
|
destroy(): Promise<void>;
|
|
817
1136
|
}
|
|
@@ -865,7 +1184,7 @@ export declare interface AudioRecordingFacts {
|
|
|
865
1184
|
}
|
|
866
1185
|
|
|
867
1186
|
/**
|
|
868
|
-
* Removes clips
|
|
1187
|
+
* Removes clips, on any tracks, leaving silence where they were.
|
|
869
1188
|
*
|
|
870
1189
|
* @public
|
|
871
1190
|
*/
|
|
@@ -874,6 +1193,16 @@ export declare interface AudioRemoveClipsCommand {
|
|
|
874
1193
|
readonly keys: readonly string[];
|
|
875
1194
|
}
|
|
876
1195
|
|
|
1196
|
+
/**
|
|
1197
|
+
* Removes tracks, with their clips. A plan keeps at least one track.
|
|
1198
|
+
*
|
|
1199
|
+
* @public
|
|
1200
|
+
*/
|
|
1201
|
+
export declare interface AudioRemoveTracksCommand {
|
|
1202
|
+
readonly type: "audio.removeTracks";
|
|
1203
|
+
readonly keys: readonly string[];
|
|
1204
|
+
}
|
|
1205
|
+
|
|
877
1206
|
/**
|
|
878
1207
|
* One export: a plan, the decoded sources its clips refer to, and the
|
|
879
1208
|
* output format. The plan's metadata goes into the file.
|
|
@@ -888,45 +1217,65 @@ export declare interface AudioRenderJob {
|
|
|
888
1217
|
}
|
|
889
1218
|
|
|
890
1219
|
/**
|
|
891
|
-
*
|
|
892
|
-
*
|
|
1220
|
+
* What an export gives: the file, and what clamping did to the mix
|
|
1221
|
+
* (docs/adr/0006). A mix of full-scale tracks goes over full scale; export
|
|
1222
|
+
* clamps it rather than changing levels nobody asked to change, and says so
|
|
1223
|
+
* here, so an editor can offer to lower the master gain.
|
|
893
1224
|
*
|
|
894
1225
|
* @public
|
|
895
1226
|
*/
|
|
896
|
-
export declare interface
|
|
897
|
-
|
|
898
|
-
readonly
|
|
1227
|
+
export declare interface AudioRenderResult {
|
|
1228
|
+
/** The encoded file. */
|
|
1229
|
+
readonly blob: Blob;
|
|
1230
|
+
/**
|
|
1231
|
+
* The mix's peak before clamping, in decibels relative to full scale:
|
|
1232
|
+
* above 0 means it clipped, by that much. `-Infinity` for silence.
|
|
1233
|
+
*/
|
|
1234
|
+
readonly peakDb: number;
|
|
1235
|
+
/** How many frames had a sample over full scale, which was clamped. */
|
|
1236
|
+
readonly clippedFrames: number;
|
|
899
1237
|
}
|
|
900
1238
|
|
|
901
1239
|
/**
|
|
902
|
-
*
|
|
903
|
-
*
|
|
904
|
-
*
|
|
1240
|
+
* On each named track, replaces a run of neighbouring clips, then moves
|
|
1241
|
+
* every clip after the run by `shift` frames. Undo's, for a split and for
|
|
1242
|
+
* the time edits, and its own inverse: a ripple that moved a thousand clips
|
|
1243
|
+
* is undone by one number.
|
|
905
1244
|
*
|
|
906
1245
|
* @public
|
|
907
1246
|
*/
|
|
908
1247
|
export declare interface AudioReplaceClipsCommand {
|
|
909
1248
|
readonly type: "audio.replaceClips";
|
|
910
|
-
readonly
|
|
911
|
-
readonly count: number;
|
|
912
|
-
readonly clips: readonly AudioClip[];
|
|
1249
|
+
readonly edits: readonly AudioClipsEdit[];
|
|
913
1250
|
}
|
|
914
1251
|
|
|
915
1252
|
/**
|
|
916
|
-
* Puts removed clips back
|
|
917
|
-
* It's what undoing a removal runs.
|
|
1253
|
+
* Puts removed clips back on their tracks. A clip's `at` says where. Undo's, for a removal.
|
|
918
1254
|
*
|
|
919
1255
|
* @public
|
|
920
1256
|
*/
|
|
921
1257
|
export declare interface AudioRestoreClipsCommand {
|
|
922
1258
|
readonly type: "audio.restoreClips";
|
|
923
|
-
/** Each clip, and the index it takes in the resulting plan, in increasing order. */
|
|
924
1259
|
readonly entries: readonly {
|
|
925
|
-
readonly
|
|
1260
|
+
readonly track: string;
|
|
926
1261
|
readonly clip: AudioClip;
|
|
927
1262
|
}[];
|
|
928
1263
|
}
|
|
929
1264
|
|
|
1265
|
+
/**
|
|
1266
|
+
* Puts removed tracks back at their indexes, with their clips and settings. Undo's.
|
|
1267
|
+
*
|
|
1268
|
+
* @public
|
|
1269
|
+
*/
|
|
1270
|
+
export declare interface AudioRestoreTracksCommand {
|
|
1271
|
+
readonly type: "audio.restoreTracks";
|
|
1272
|
+
/** Each track, and the index it takes in the resulting plan, in increasing order. */
|
|
1273
|
+
readonly entries: readonly {
|
|
1274
|
+
readonly index: number;
|
|
1275
|
+
readonly track: AudioTrack;
|
|
1276
|
+
}[];
|
|
1277
|
+
}
|
|
1278
|
+
|
|
930
1279
|
/**
|
|
931
1280
|
* How samples are stored in an exported WAV file (ADR 0001).
|
|
932
1281
|
*
|
|
@@ -936,14 +1285,17 @@ declare type AudioSampleFormat_2 = "pcm16" | "pcm24" | "float32";
|
|
|
936
1285
|
export { AudioSampleFormat_2 as AudioSampleFormat }
|
|
937
1286
|
|
|
938
1287
|
/**
|
|
939
|
-
* A range of the timeline,
|
|
940
|
-
* exclusive,
|
|
1288
|
+
* A selected range of the timeline, on some tracks (docs/adr/0006): frames
|
|
1289
|
+
* from `start` inclusive to `end` exclusive, and the keys of the tracks it
|
|
1290
|
+
* covers, in plan order.
|
|
941
1291
|
*
|
|
942
1292
|
* @public
|
|
943
1293
|
*/
|
|
944
1294
|
export declare interface AudioSelection {
|
|
945
1295
|
readonly start: number;
|
|
946
1296
|
readonly end: number;
|
|
1297
|
+
/** The tracks the range covers, at least one. */
|
|
1298
|
+
readonly tracks: readonly string[];
|
|
947
1299
|
}
|
|
948
1300
|
|
|
949
1301
|
/**
|
|
@@ -966,10 +1318,14 @@ export declare interface AudioSession {
|
|
|
966
1318
|
* which the snapshot also holds; the current recording, if any, stays
|
|
967
1319
|
* open.
|
|
968
1320
|
*/
|
|
969
|
-
open(file: Blob, options?:
|
|
1321
|
+
open(file: Blob, options?: AudioOpenOptions): Promise<void>;
|
|
970
1322
|
/**
|
|
971
|
-
*
|
|
972
|
-
*
|
|
1323
|
+
* Adds another recording, as one undoable step: on a new track of its
|
|
1324
|
+
* own, below the others, or on the track `options.track` names, where it
|
|
1325
|
+
* needs free space. It starts at `options.at`, or at the start. A
|
|
1326
|
+
* recording at another sample rate is converted to the session's, and its
|
|
1327
|
+
* source says so in `resampledFrom`; one with more channels than the plan
|
|
1328
|
+
* raises the plan's channel count to its own, in the same step. If the
|
|
973
1329
|
* sources held would then exceed `maxSessionSize`, the session first drops
|
|
974
1330
|
* history steps, in sdk-core's `dropOrder`, as far as needed to release
|
|
975
1331
|
* sources only they refer to, and sets `historyTrimmed`. If even that
|
|
@@ -979,7 +1335,9 @@ export declare interface AudioSession {
|
|
|
979
1335
|
/**
|
|
980
1336
|
* Runs one command, or several as one undoable step. A command that
|
|
981
1337
|
* doesn't apply throws `AudioError` with `INVALID_COMMAND`, and one that
|
|
982
|
-
* would exceed
|
|
1338
|
+
* would exceed a limit throws its code: `TOO_MANY_CLIPS` for `maxClips`,
|
|
1339
|
+
* `TOO_MANY_TRACKS` for `maxTracks`, and `DURATION_TOO_LONG` when the plan
|
|
1340
|
+
* would become longer than `maxDuration`. Any of them changes
|
|
983
1341
|
* nothing. The commands are copied, so changing them afterwards has no
|
|
984
1342
|
* effect.
|
|
985
1343
|
*/
|
|
@@ -990,17 +1348,24 @@ export declare interface AudioSession {
|
|
|
990
1348
|
*/
|
|
991
1349
|
group<T>(fn: () => T): T;
|
|
992
1350
|
/**
|
|
993
|
-
* A
|
|
994
|
-
* create
|
|
1351
|
+
* A key no track or clip has, in the plan or the history, for commands
|
|
1352
|
+
* that create them, such as `newKey` in `audio.splitClip` or `key` in
|
|
1353
|
+
* `audio.addTrack`.
|
|
995
1354
|
*/
|
|
996
1355
|
createKey(): string;
|
|
997
1356
|
undo(): void;
|
|
998
1357
|
redo(): void;
|
|
999
1358
|
/**
|
|
1000
|
-
* Selects a range of the timeline
|
|
1001
|
-
*
|
|
1359
|
+
* Selects a range of the timeline on the tracks named, or on every track
|
|
1360
|
+
* without `tracks`, clamped to the plan, or clears the selection with
|
|
1361
|
+
* `undefined`. An empty range clears it too, as does one that names no
|
|
1362
|
+
* track the plan has.
|
|
1002
1363
|
*/
|
|
1003
|
-
select(range:
|
|
1364
|
+
select(range: {
|
|
1365
|
+
readonly start: number;
|
|
1366
|
+
readonly end: number;
|
|
1367
|
+
readonly tracks?: readonly string[];
|
|
1368
|
+
} | undefined): void;
|
|
1004
1369
|
/** A source's waveform overview, or `undefined` for a source the session doesn't hold. */
|
|
1005
1370
|
getPeaks(source: string): AudioPeaks | undefined;
|
|
1006
1371
|
/**
|
|
@@ -1009,14 +1374,15 @@ export declare interface AudioSession {
|
|
|
1009
1374
|
*/
|
|
1010
1375
|
getAudio(source: string): DecodedAudio | undefined;
|
|
1011
1376
|
/**
|
|
1012
|
-
*
|
|
1013
|
-
* `processor`, under `maxProcessingTime`. It returns the file
|
|
1014
|
-
*
|
|
1015
|
-
*
|
|
1016
|
-
*
|
|
1377
|
+
* Mixes and encodes the plan's audible tracks as they are now, with the
|
|
1378
|
+
* session's `processor`, under `maxProcessingTime`. It returns the file
|
|
1379
|
+
* with the mix's peak and the frames that clipped, and never downloads
|
|
1380
|
+
* it: the host decides what to do with it. Edits made while it runs don't
|
|
1381
|
+
* change it. Rejects with `INVALID_COMMAND` and the reason `no-recording`,
|
|
1382
|
+
* `empty-plan` or `nothing-audible` when there's nothing to export, and
|
|
1017
1383
|
* throws `TypeError` when the session has no processor.
|
|
1018
1384
|
*/
|
|
1019
|
-
export(options?: AudioSessionExportOptions): Promise<
|
|
1385
|
+
export(options?: AudioSessionExportOptions): Promise<AudioRenderResult>;
|
|
1020
1386
|
/** Closes the recording and releases its sources. */
|
|
1021
1387
|
close(): Promise<void>;
|
|
1022
1388
|
}
|
|
@@ -1129,8 +1495,17 @@ export declare interface AudioSessionSnapshot {
|
|
|
1129
1495
|
export declare type AudioSessionStatus = "empty" | "opening" | "ready" | "error";
|
|
1130
1496
|
|
|
1131
1497
|
/**
|
|
1132
|
-
* Sets
|
|
1133
|
-
*
|
|
1498
|
+
* Sets the plan's channel count.
|
|
1499
|
+
*
|
|
1500
|
+
* @public
|
|
1501
|
+
*/
|
|
1502
|
+
export declare interface AudioSetChannelsCommand {
|
|
1503
|
+
readonly type: "audio.setChannels";
|
|
1504
|
+
readonly channels: number;
|
|
1505
|
+
}
|
|
1506
|
+
|
|
1507
|
+
/**
|
|
1508
|
+
* Sets a clip's fade in or fade out. Together, the two must fit in the clip.
|
|
1134
1509
|
*
|
|
1135
1510
|
* @public
|
|
1136
1511
|
*/
|
|
@@ -1138,7 +1513,6 @@ export declare interface AudioSetFadeCommand {
|
|
|
1138
1513
|
readonly type: "audio.setFade";
|
|
1139
1514
|
readonly key: string;
|
|
1140
1515
|
readonly edge: "in" | "out";
|
|
1141
|
-
/** The fade's length in frames. 0 removes it. */
|
|
1142
1516
|
readonly frames: number;
|
|
1143
1517
|
readonly curve: AudioFadeCurve;
|
|
1144
1518
|
}
|
|
@@ -1151,22 +1525,44 @@ export declare interface AudioSetFadeCommand {
|
|
|
1151
1525
|
export declare interface AudioSetGainCommand {
|
|
1152
1526
|
readonly type: "audio.setGain";
|
|
1153
1527
|
readonly keys: readonly string[];
|
|
1154
|
-
/** Decibels, from `MIN_GAIN_DB` to `MAX_GAIN_DB`. */
|
|
1155
1528
|
readonly gainDb: number;
|
|
1156
1529
|
}
|
|
1157
1530
|
|
|
1158
1531
|
/**
|
|
1159
|
-
* Sets
|
|
1532
|
+
* Sets the master gain.
|
|
1533
|
+
*
|
|
1534
|
+
* @public
|
|
1535
|
+
*/
|
|
1536
|
+
export declare interface AudioSetMasterGainCommand {
|
|
1537
|
+
readonly type: "audio.setMasterGain";
|
|
1538
|
+
readonly gainDb: number;
|
|
1539
|
+
}
|
|
1540
|
+
|
|
1541
|
+
/**
|
|
1542
|
+
* Sets one metadata field.
|
|
1160
1543
|
*
|
|
1161
1544
|
* @public
|
|
1162
1545
|
*/
|
|
1163
1546
|
export declare interface AudioSetMetadataCommand {
|
|
1164
1547
|
readonly type: "audio.setMetadata";
|
|
1165
1548
|
readonly field: keyof AudioMetadata;
|
|
1166
|
-
/** At most {@link MAX_METADATA_LENGTH} code points. */
|
|
1167
1549
|
readonly value: string;
|
|
1168
1550
|
}
|
|
1169
1551
|
|
|
1552
|
+
/**
|
|
1553
|
+
* Sets the fields given of a track, at least one.
|
|
1554
|
+
*
|
|
1555
|
+
* @public
|
|
1556
|
+
*/
|
|
1557
|
+
export declare interface AudioSetTrackCommand {
|
|
1558
|
+
readonly type: "audio.setTrack";
|
|
1559
|
+
readonly key: string;
|
|
1560
|
+
readonly name?: string;
|
|
1561
|
+
readonly gainDb?: number;
|
|
1562
|
+
readonly muted?: boolean;
|
|
1563
|
+
readonly soloed?: boolean;
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1170
1566
|
/**
|
|
1171
1567
|
* A source the session holds, without its samples: what the snapshot shows
|
|
1172
1568
|
* (ADR 0003).
|
|
@@ -1182,40 +1578,81 @@ export declare interface AudioSourceInfo {
|
|
|
1182
1578
|
readonly frames: number;
|
|
1183
1579
|
readonly container: AudioContainer;
|
|
1184
1580
|
readonly codec: AudioCodec;
|
|
1581
|
+
/**
|
|
1582
|
+
* The file's own sample rate, in hertz, when the source was converted to
|
|
1583
|
+
* the session's as it was inserted (docs/adr/0006). `sampleRate` and
|
|
1584
|
+
* `frames` describe the converted audio.
|
|
1585
|
+
*/
|
|
1586
|
+
readonly resampledFrom?: number;
|
|
1587
|
+
/**
|
|
1588
|
+
* The name the host gave the recording, or its file's name, to show
|
|
1589
|
+
* people, cleaned as pdf-sdk ADR 0009 decides: its last path segment, with
|
|
1590
|
+
* no control or bidirectional formatting characters, none that Windows
|
|
1591
|
+
* refuses, no leading dots or surrounding space, in NFC, and at most
|
|
1592
|
+
* {@link MAX_SOURCE_NAME_LENGTH} code points. It's never in events, the
|
|
1593
|
+
* plan or a document. Show it as text, never as HTML.
|
|
1594
|
+
*/
|
|
1595
|
+
readonly name?: string;
|
|
1185
1596
|
}
|
|
1186
1597
|
|
|
1187
1598
|
/**
|
|
1188
|
-
* Splits a clip in two at a timeline frame inside it. The first
|
|
1189
|
-
* the
|
|
1599
|
+
* Splits a clip in two at a timeline frame strictly inside it. The first
|
|
1600
|
+
* part keeps the key and the fade in; the second takes `newKey` and the
|
|
1601
|
+
* fade out.
|
|
1190
1602
|
*
|
|
1191
1603
|
* @public
|
|
1192
1604
|
*/
|
|
1193
1605
|
export declare interface AudioSplitClipCommand {
|
|
1194
1606
|
readonly type: "audio.splitClip";
|
|
1195
1607
|
readonly key: string;
|
|
1196
|
-
/** A timeline frame strictly inside the clip. */
|
|
1197
1608
|
readonly at: number;
|
|
1198
|
-
|
|
1609
|
+
/**
|
|
1610
|
+
* The second part's key. `session.execute` gives one from
|
|
1611
|
+
* `session.createKey()` when it's left out; a stored command, and the
|
|
1612
|
+
* format, always carry it.
|
|
1613
|
+
*/
|
|
1614
|
+
readonly newKey?: string;
|
|
1199
1615
|
}
|
|
1200
1616
|
|
|
1201
1617
|
/**
|
|
1202
|
-
*
|
|
1203
|
-
*
|
|
1618
|
+
* One track: clips in time order that never overlap, with the track's
|
|
1619
|
+
* name, gain, mute and solo (docs/adr/0006).
|
|
1620
|
+
*
|
|
1621
|
+
* @public
|
|
1622
|
+
*/
|
|
1623
|
+
export declare interface AudioTrack {
|
|
1624
|
+
/** Stable across edits. Tracks and clips share one namespace of keys. */
|
|
1625
|
+
readonly key: string;
|
|
1626
|
+
/**
|
|
1627
|
+
* The name people gave it, at most {@link MAX_TRACK_NAME_LENGTH} code
|
|
1628
|
+
* points. Empty means none, and an editor shows "Track 2". It's
|
|
1629
|
+
* untrusted text: render it as text, never as HTML.
|
|
1630
|
+
*/
|
|
1631
|
+
readonly name: string;
|
|
1632
|
+
/** The track's gain in decibels. */
|
|
1633
|
+
readonly gainDb: number;
|
|
1634
|
+
readonly muted: boolean;
|
|
1635
|
+
readonly soloed: boolean;
|
|
1636
|
+
/** Sorted by `at`, each ending at or before the next one starts. */
|
|
1637
|
+
readonly clips: readonly AudioClip[];
|
|
1638
|
+
}
|
|
1639
|
+
|
|
1640
|
+
/**
|
|
1641
|
+
* Changes the range of its source a clip plays. The audio stays where it is
|
|
1642
|
+
* on the timeline: moving `start` moves the clip's `at` by the same amount.
|
|
1643
|
+
* Fades that no longer fit are shortened in proportion.
|
|
1204
1644
|
*
|
|
1205
1645
|
* @public
|
|
1206
1646
|
*/
|
|
1207
1647
|
export declare interface AudioTrimClipCommand {
|
|
1208
1648
|
readonly type: "audio.trimClip";
|
|
1209
1649
|
readonly key: string;
|
|
1210
|
-
/** The first source frame, inclusive. */
|
|
1211
1650
|
readonly start: number;
|
|
1212
|
-
/** The source frame the clip stops before, exclusive. */
|
|
1213
1651
|
readonly end: number;
|
|
1214
1652
|
}
|
|
1215
1653
|
|
|
1216
1654
|
/**
|
|
1217
|
-
* Sets clips
|
|
1218
|
-
* what undoing a trim, a gain or a fade runs.
|
|
1655
|
+
* Sets clips, matched by key, to states with every field given. Undo's, for a trim, a gain or a fade.
|
|
1219
1656
|
*
|
|
1220
1657
|
* @public
|
|
1221
1658
|
*/
|
|
@@ -1224,6 +1661,14 @@ export declare interface AudioUpdateClipsCommand {
|
|
|
1224
1661
|
readonly clips: readonly AudioClip[];
|
|
1225
1662
|
}
|
|
1226
1663
|
|
|
1664
|
+
/**
|
|
1665
|
+
* The edits a user makes: `hm-audio-command` version 2
|
|
1666
|
+
* (docs/formats/hm-audio-plan.md).
|
|
1667
|
+
*
|
|
1668
|
+
* @public
|
|
1669
|
+
*/
|
|
1670
|
+
export declare type AudioUserCommand = AudioInsertClipsCommand | AudioRemoveClipsCommand | AudioTrimClipCommand | AudioSplitClipCommand | AudioMoveClipsCommand | AudioSetGainCommand | AudioSetFadeCommand | AudioDeleteRangeCommand | AudioKeepRangeCommand | AudioInsertTimeCommand | AudioAddTrackCommand | AudioRemoveTracksCommand | AudioMoveTrackCommand | AudioSetTrackCommand | AudioSetMasterGainCommand | AudioSetChannelsCommand | AudioSetMetadataCommand;
|
|
1671
|
+
|
|
1227
1672
|
/**
|
|
1228
1673
|
* Something the user should know about the recordings open, though they
|
|
1229
1674
|
* opened (docs/adr/0004). Show its text from `warnings.<limit>`, or from
|
|
@@ -1254,19 +1699,41 @@ export declare type AudioWarning = {
|
|
|
1254
1699
|
};
|
|
1255
1700
|
|
|
1256
1701
|
/**
|
|
1257
|
-
*
|
|
1702
|
+
* The user-facing text for one of the snapshot's warnings, from
|
|
1703
|
+
* `warnings.<limit>` or `warnings.truncated`, with the parameters each needs
|
|
1704
|
+
* (point 12 of #54). A limit's name is known only at run time, which
|
|
1705
|
+
* `messages.t()` can't type, so this does it once.
|
|
1706
|
+
*
|
|
1707
|
+
* @example
|
|
1708
|
+
* ```ts
|
|
1709
|
+
* for (const warning of snapshot.warnings) show(audioWarningText(messages, warning));
|
|
1710
|
+
* ```
|
|
1711
|
+
*
|
|
1712
|
+
* @public
|
|
1713
|
+
*/
|
|
1714
|
+
export declare function audioWarningText(messages: Messages<AudioMessageCatalogue>, warning: AudioWarning): string;
|
|
1715
|
+
|
|
1716
|
+
/**
|
|
1717
|
+
* The clip that plays a timeline frame on a track, or `undefined` in
|
|
1718
|
+
* silence.
|
|
1719
|
+
*
|
|
1720
|
+
* @public
|
|
1721
|
+
*/
|
|
1722
|
+
export declare function clipAt(track: AudioTrack, frame: number): AudioClip | undefined;
|
|
1723
|
+
|
|
1724
|
+
/**
|
|
1725
|
+
* The timeline frame a clip stops before.
|
|
1258
1726
|
*
|
|
1259
1727
|
* @public
|
|
1260
1728
|
*/
|
|
1261
|
-
export declare function
|
|
1729
|
+
export declare function clipEnd(clip: AudioClip): number;
|
|
1262
1730
|
|
|
1263
1731
|
/**
|
|
1264
|
-
*
|
|
1265
|
-
* clips before it, never stored, so it can't disagree with them (ADR 0003).
|
|
1732
|
+
* A clip's length in frames.
|
|
1266
1733
|
*
|
|
1267
1734
|
* @public
|
|
1268
1735
|
*/
|
|
1269
|
-
export declare function
|
|
1736
|
+
export declare function clipLength(clip: AudioClipBody): number;
|
|
1270
1737
|
|
|
1271
1738
|
/**
|
|
1272
1739
|
* Keeps an output playing what the session holds (docs/adr/0003), so an
|
|
@@ -1297,6 +1764,27 @@ export declare function clipOffsets(plan: AudioPlan): readonly number[];
|
|
|
1297
1764
|
*/
|
|
1298
1765
|
export declare function connectOutput(session: AudioSession, output: AudioOutput): () => void;
|
|
1299
1766
|
|
|
1767
|
+
/**
|
|
1768
|
+
* Creates the SDK's engine, processor and output with one set of options,
|
|
1769
|
+
* so a self-hosted worker's `assetsUrl` is given once (docs/adr/0006).
|
|
1770
|
+
* Nothing starts until it's used: no worker, and no `AudioContext` until
|
|
1771
|
+
* the first `play()`.
|
|
1772
|
+
*
|
|
1773
|
+
* @example
|
|
1774
|
+
* ```ts
|
|
1775
|
+
* const adapters = createAudioAdapters({ assetsUrl: "/audio-sdk/" });
|
|
1776
|
+
* const session = createAudioSession({ engine: adapters.engine, processor: adapters.processor });
|
|
1777
|
+
* const disconnect = connectOutput(session, adapters.output);
|
|
1778
|
+
* // …
|
|
1779
|
+
* disconnect();
|
|
1780
|
+
* await session.close();
|
|
1781
|
+
* await adapters.destroy();
|
|
1782
|
+
* ```
|
|
1783
|
+
*
|
|
1784
|
+
* @public
|
|
1785
|
+
*/
|
|
1786
|
+
export declare function createAudioAdapters(options?: AudioAdaptersOptions): AudioAdapters;
|
|
1787
|
+
|
|
1300
1788
|
/**
|
|
1301
1789
|
* Creates the SDK's audio engine (docs/adr/0001, docs/adr/0002). It probes
|
|
1302
1790
|
* files in its worker: WAV and AIFF, FLAC (native or in Ogg), MP3, AAC in
|
|
@@ -1309,6 +1797,10 @@ export declare function connectOutput(session: AudioSession, output: AudioOutput
|
|
|
1309
1797
|
* checked against the probe's bound, errors by code, and the time limit of
|
|
1310
1798
|
* the caller's signal. Other containers fail with `UNSUPPORTED_FORMAT`.
|
|
1311
1799
|
*
|
|
1800
|
+
* Asked for another sample rate than a file's, it converts the decoded
|
|
1801
|
+
* audio in its worker, block by block, with a windowed sinc, so every
|
|
1802
|
+
* browser gives the same samples (docs/adr/0006).
|
|
1803
|
+
*
|
|
1312
1804
|
* Nothing starts until the first call. By default the worker is inlined,
|
|
1313
1805
|
* which needs `worker-src blob:` in a Content Security Policy; with
|
|
1314
1806
|
* `assetsUrl` it loads from your own origin, which needs `worker-src 'self'`
|
|
@@ -1335,11 +1827,18 @@ export declare function createAudioEngine(options?: AudioEngineOptions): AudioEn
|
|
|
1335
1827
|
* - **One `AudioContext`,** created on the first `play()`, which should be
|
|
1336
1828
|
* a user gesture, as browsers' autoplay rules require. If the context
|
|
1337
1829
|
* doesn't run within two seconds, `play()` rejects with
|
|
1338
|
-
* `UNSUPPORTED_ENVIRONMENT
|
|
1830
|
+
* `UNSUPPORTED_ENVIRONMENT` and `details.reason` `"autoplay-blocked"`,
|
|
1831
|
+
* and the output stays as it was.
|
|
1339
1832
|
* - **Each clip is an `AudioBufferSourceNode`** on its source, through a
|
|
1340
1833
|
* `GainNode` automated from `gainAt`, so playback follows the envelope
|
|
1341
1834
|
* export applies. Sources mix into the plan's channels by Web Audio's
|
|
1342
1835
|
* speaker rules, as export does.
|
|
1836
|
+
* - **Each track is a `GainNode`** its clips feed, at the track's gain, or
|
|
1837
|
+
* at silence when it's muted or left out by a solo, and the tracks feed
|
|
1838
|
+
* one at the master gain. Loading a plan that differs only in those
|
|
1839
|
+
* levels moves the nodes there over 5 ms, and reschedules nothing, so a
|
|
1840
|
+
* mute, a solo or a gain is heard at once, without a gap or a click
|
|
1841
|
+
* (docs/adr/0006).
|
|
1343
1842
|
* - **The playhead** is read from the audio clock by `position()`, which a
|
|
1344
1843
|
* view polls on animation frames; it isn't in the snapshot.
|
|
1345
1844
|
*
|
|
@@ -1362,21 +1861,24 @@ export declare function createAudioEngine(options?: AudioEngineOptions): AudioEn
|
|
|
1362
1861
|
export declare function createAudioOutput(): AudioOutput;
|
|
1363
1862
|
|
|
1364
1863
|
/**
|
|
1365
|
-
* Creates the SDK's processor (docs/adr/0003): it
|
|
1366
|
-
* with their gain and fades,
|
|
1864
|
+
* Creates the SDK's processor (docs/adr/0003, docs/adr/0006): it mixes a
|
|
1865
|
+
* plan's audible tracks, with their clips' gain and fades, the tracks' gains
|
|
1866
|
+
* and the master gain, and encodes the mix as a WAV file, in its own
|
|
1367
1867
|
* worker, block by block. The page sends each block's source samples, at
|
|
1368
1868
|
* most 2¹⁶ frames per channel, and collects the encoded blocks into a
|
|
1369
1869
|
* `Blob` of parts, so an export never holds the whole file in one buffer.
|
|
1370
1870
|
*
|
|
1371
1871
|
* Sources with another channel count mix into the plan's by Web Audio's
|
|
1372
|
-
* speaker rules, as playback does.
|
|
1872
|
+
* speaker rules, as playback does. Tracks sum at unity. Samples are clamped
|
|
1873
|
+
* to full scale, and the result gives the mix's peak and how many frames
|
|
1874
|
+
* were clamped;
|
|
1373
1875
|
* 16-bit and 24-bit PCM round half away from zero, without dither. Files
|
|
1374
1876
|
* whose sizes don't fit 32 bits are written as RF64.
|
|
1375
1877
|
*
|
|
1376
1878
|
* @example
|
|
1377
1879
|
* ```ts
|
|
1378
1880
|
* const processor = createAudioProcessor();
|
|
1379
|
-
* const
|
|
1881
|
+
* const { blob, peakDb, clippedFrames } = await processor.render(
|
|
1380
1882
|
* { plan, sources, format: { container: "wav", sampleFormat: "pcm24" } },
|
|
1381
1883
|
* { signal, onProgress },
|
|
1382
1884
|
* );
|
|
@@ -1394,7 +1896,7 @@ export declare function createAudioProcessor(options?: AudioProcessorOptions): A
|
|
|
1394
1896
|
* ```ts
|
|
1395
1897
|
* const session = createAudioSession({ engine: createAudioEngine() });
|
|
1396
1898
|
* await session.open(file);
|
|
1397
|
-
* const [clip] = session.getSnapshot().plan?.clips ?? [];
|
|
1899
|
+
* const [clip] = session.getSnapshot().plan?.tracks[0]?.clips ?? [];
|
|
1398
1900
|
* session.execute({ type: "audio.setGain", keys: [clip.key], gainDb: -3 });
|
|
1399
1901
|
* session.undo();
|
|
1400
1902
|
* ```
|
|
@@ -1432,6 +1934,21 @@ export declare interface DecodedAudio {
|
|
|
1432
1934
|
*/
|
|
1433
1935
|
export declare const EMPTY_METADATA: AudioMetadata;
|
|
1434
1936
|
|
|
1937
|
+
/**
|
|
1938
|
+
* A timeline position as an editor shows it (docs/adr/0005): minutes,
|
|
1939
|
+
* seconds and hundredths, as `0:12.40`, with hours from an hour on, as
|
|
1940
|
+
* `1:02:05.00` (point 11 of #54). Hundredths are rounded down, so the time
|
|
1941
|
+
* shown is never ahead of what's heard. The digits and separators are the
|
|
1942
|
+
* same in every locale, as a timecode's are.
|
|
1943
|
+
*
|
|
1944
|
+
* @param frames - A non-negative whole number of frames.
|
|
1945
|
+
* @param sampleRate - Frames per second, a positive whole number.
|
|
1946
|
+
* @throws `RangeError` for frames or a rate that aren't whole numbers, or a
|
|
1947
|
+
* rate of 0.
|
|
1948
|
+
* @public
|
|
1949
|
+
*/
|
|
1950
|
+
export declare function formatTimecode(frames: number, sampleRate: number): string;
|
|
1951
|
+
|
|
1435
1952
|
/**
|
|
1436
1953
|
* Every position and length in the model is a whole number of frames, at the
|
|
1437
1954
|
* session's sample rate (ADR 0003). A frame is one sample on every channel.
|
|
@@ -1458,7 +1975,7 @@ export declare function framesToSeconds(frames: number, sampleRate: number): num
|
|
|
1458
1975
|
* @param frame - A frame within the clip, from 0 to its length minus one.
|
|
1459
1976
|
* @public
|
|
1460
1977
|
*/
|
|
1461
|
-
export declare function gainAt(clip:
|
|
1978
|
+
export declare function gainAt(clip: AudioClipBody, frame: number): number;
|
|
1462
1979
|
|
|
1463
1980
|
/**
|
|
1464
1981
|
* Checks whether a value is an {@link AudioError}, optionally with a given
|
|
@@ -1494,6 +2011,52 @@ export declare const MAX_GAIN_DB = 120;
|
|
|
1494
2011
|
*/
|
|
1495
2012
|
export declare const MAX_METADATA_LENGTH = 1000;
|
|
1496
2013
|
|
|
2014
|
+
/**
|
|
2015
|
+
* The longest source name, in Unicode code points. A longer one is cut,
|
|
2016
|
+
* never in the middle of a character. The same as pdf-sdk's (its ADR 0009),
|
|
2017
|
+
* since a name may become a download's.
|
|
2018
|
+
*
|
|
2019
|
+
* @public
|
|
2020
|
+
*/
|
|
2021
|
+
export declare const MAX_SOURCE_NAME_LENGTH = 128;
|
|
2022
|
+
|
|
2023
|
+
/**
|
|
2024
|
+
* The longest track name, in Unicode code points, as JSON Schema's
|
|
2025
|
+
* `maxLength` counts them (sdk-core ADR 0045).
|
|
2026
|
+
*
|
|
2027
|
+
* @public
|
|
2028
|
+
*/
|
|
2029
|
+
export declare const MAX_TRACK_NAME_LENGTH = 100;
|
|
2030
|
+
|
|
2031
|
+
/**
|
|
2032
|
+
* Migrates a version 1 command to the version 2 commands with the same
|
|
2033
|
+
* effect, on the plan a version 1 document migrates to: its first track
|
|
2034
|
+
* holds what version 1's single track held.
|
|
2035
|
+
*
|
|
2036
|
+
* Version 1's commands closed gaps as they went, and version 2's clip edits
|
|
2037
|
+
* never move another clip. So an edit that changed a clip's length, or the
|
|
2038
|
+
* clips' order, becomes that edit with the time edits that close or open
|
|
2039
|
+
* the gap: `audio.insertTime`, and `audio.deleteRange` with `ripple`. Run
|
|
2040
|
+
* the result as one undo step.
|
|
2041
|
+
*
|
|
2042
|
+
* A command the plan can't take is returned as the nearest version 2
|
|
2043
|
+
* command, which the reducer then refuses, or refused here with
|
|
2044
|
+
* `INVALID_COMMAND` when it names clips the plan doesn't have.
|
|
2045
|
+
*
|
|
2046
|
+
* @public
|
|
2047
|
+
*/
|
|
2048
|
+
export declare function migrateAudioCommand(command: unknown, plan: AudioPlan): AudioUserCommand[];
|
|
2049
|
+
|
|
2050
|
+
/**
|
|
2051
|
+
* Migrates a version 1 plan: one track, unnamed, at 0 dB, holding the clips
|
|
2052
|
+
* back to back from the start, as version 1 played them, under a master
|
|
2053
|
+
* gain of 0 dB. It's pure and total: every version 1 plan has exactly one
|
|
2054
|
+
* version 2 plan.
|
|
2055
|
+
*
|
|
2056
|
+
* @public
|
|
2057
|
+
*/
|
|
2058
|
+
export declare function migratePlan(plan: AudioPlanV1): AudioPlan;
|
|
2059
|
+
|
|
1497
2060
|
/**
|
|
1498
2061
|
* The lowest clip gain, in decibels: far below audibility, so it serves as
|
|
1499
2062
|
* silence.
|
|
@@ -1502,6 +2065,15 @@ export declare const MAX_METADATA_LENGTH = 1000;
|
|
|
1502
2065
|
*/
|
|
1503
2066
|
export declare const MIN_GAIN_DB = -120;
|
|
1504
2067
|
|
|
2068
|
+
/**
|
|
2069
|
+
* The length of what sounds, in frames: where the last clip on any audible
|
|
2070
|
+
* track ends. It's what an export writes, so a muted track never pads the
|
|
2071
|
+
* file with silence (docs/adr/0006).
|
|
2072
|
+
*
|
|
2073
|
+
* @public
|
|
2074
|
+
*/
|
|
2075
|
+
export declare function mixLength(plan: AudioPlan): number;
|
|
2076
|
+
|
|
1505
2077
|
/**
|
|
1506
2078
|
* No fade.
|
|
1507
2079
|
*
|
|
@@ -1510,20 +2082,35 @@ export declare const MIN_GAIN_DB = -120;
|
|
|
1510
2082
|
export declare const NO_FADE: AudioFade;
|
|
1511
2083
|
|
|
1512
2084
|
/**
|
|
1513
|
-
*
|
|
2085
|
+
* A waveform's columns, drawn from a source's peaks, never from its samples
|
|
2086
|
+
* (point 13 of #54, docs/adr/0005): for each of `columns` equal parts of the
|
|
2087
|
+
* source frames from `from` to `to`, the lowest and highest sample of every
|
|
2088
|
+
* channel, from the level of the overview whose buckets best fit a column.
|
|
2089
|
+
* Levels step by four, so a column reads at most a few buckets, and drawing
|
|
2090
|
+
* costs the same for an hour as for a minute. Frames past the source's end
|
|
2091
|
+
* are silent, 0.
|
|
2092
|
+
*
|
|
2093
|
+
* @throws `RangeError` for frames that aren't whole numbers from 0 with
|
|
2094
|
+
* `from` before `to`, or `columns` that isn't a whole number from 1.
|
|
2095
|
+
* @public
|
|
2096
|
+
*/
|
|
2097
|
+
export declare function peakColumns(peaks: AudioPeaks, options: AudioPeakColumnsOptions): AudioPeakColumns;
|
|
2098
|
+
|
|
2099
|
+
/**
|
|
2100
|
+
* The plan's length in frames: where the last clip on any track ends.
|
|
2101
|
+
* Silence before the first clip is part of the plan.
|
|
1514
2102
|
*
|
|
1515
2103
|
* @public
|
|
1516
2104
|
*/
|
|
1517
2105
|
export declare function planLength(plan: AudioPlan): number;
|
|
1518
2106
|
|
|
1519
2107
|
/**
|
|
1520
|
-
* Reads a plan document
|
|
1521
|
-
*
|
|
1522
|
-
*
|
|
1523
|
-
*
|
|
2108
|
+
* Reads a plan document of version 1 or 2, and returns a multitrack plan:
|
|
2109
|
+
* a version 1 document migrates with {@link migratePlan}. It checks what
|
|
2110
|
+
* the schemas do and more: every clip lies within a source the document
|
|
2111
|
+
* lists, each track's clips are in time order and don't overlap, and keys
|
|
2112
|
+
* are unique. Unknown fields are refused, never dropped.
|
|
1524
2113
|
*
|
|
1525
|
-
* @param value - The parsed JSON.
|
|
1526
|
-
* @returns The plan, and its sources by id.
|
|
1527
2114
|
* @throws `AudioError` with `UNSUPPORTED_FORMAT` for another format or a
|
|
1528
2115
|
* later version, and `INVALID_DOCUMENT` for anything else that's wrong,
|
|
1529
2116
|
* with a {@link AudioDocumentRejection} as `details.reason`.
|
|
@@ -1545,14 +2132,39 @@ export declare function readAudioPlanDocument(value: unknown): {
|
|
|
1545
2132
|
export declare function secondsToFrames(seconds: number, sampleRate: number): number;
|
|
1546
2133
|
|
|
1547
2134
|
/**
|
|
1548
|
-
* Writes a plan as
|
|
2135
|
+
* Writes a multitrack plan as a version 2 document, plain JSON-ready data.
|
|
1549
2136
|
*
|
|
1550
|
-
* @param plan - The plan.
|
|
1551
|
-
* @param sources - The sources by id, with at least every source the plan's
|
|
1552
|
-
* clips use. They're written as given.
|
|
1553
2137
|
* @throws `TypeError` if a clip's source is missing from `sources`.
|
|
1554
2138
|
* @public
|
|
1555
2139
|
*/
|
|
1556
2140
|
export declare function toAudioPlanDocument(plan: AudioPlan, sources: Readonly<Record<string, AudioPlanDocumentSource>>): AudioPlanDocument;
|
|
1557
2141
|
|
|
2142
|
+
/**
|
|
2143
|
+
* A track's length in frames: where its last clip ends.
|
|
2144
|
+
*
|
|
2145
|
+
* @public
|
|
2146
|
+
*/
|
|
2147
|
+
export declare function trackLength(track: AudioTrack): number;
|
|
2148
|
+
|
|
2149
|
+
/**
|
|
2150
|
+
* Follows an output's playhead (point 8 of #54), without a framework: calls
|
|
2151
|
+
* `listener` with the playhead, in whole frames, now, whenever it jumps, as
|
|
2152
|
+
* after a seek or a stop, and on every animation frame while playing. It
|
|
2153
|
+
* calls only when the frame differs from the last one it gave, and asks for
|
|
2154
|
+
* no frames while nothing plays. Returns a function that stops it.
|
|
2155
|
+
*
|
|
2156
|
+
* It reads the page's `requestAnimationFrame` when it's called, never on
|
|
2157
|
+
* import, so the entry stays server-safe.
|
|
2158
|
+
*
|
|
2159
|
+
* @example
|
|
2160
|
+
* ```ts
|
|
2161
|
+
* const stop = watchPlayhead(output, (frame) => {
|
|
2162
|
+
* playhead.textContent = formatTimecode(frame, plan.sampleRate);
|
|
2163
|
+
* });
|
|
2164
|
+
* ```
|
|
2165
|
+
*
|
|
2166
|
+
* @public
|
|
2167
|
+
*/
|
|
2168
|
+
export declare function watchPlayhead(output: AudioOutput, listener: (frame: number) => void, frames?: AudioFrameScheduler): () => void;
|
|
2169
|
+
|
|
1558
2170
|
export { }
|