@hussmartinez/audio-sdk 0.6.0 → 0.7.1
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 +135 -2
- 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.js +1 -2657
- package/dist/index.js.map +1 -1
- package/dist/lazy/inline-worker-bmtdPTgx.js +30 -0
- package/dist/lazy/{inline-worker-D8bxbE-Q.js.map → inline-worker-bmtdPTgx.js.map} +1 -1
- package/dist/react.d.ts +1957 -3
- package/dist/react.js +1 -0
- package/dist/shared/AudioEditor-_EPL0XcW.js +2801 -0
- package/dist/shared/AudioEditor-_EPL0XcW.js.map +1 -0
- package/dist/shared/text-2gfztfJE.js +2663 -0
- package/dist/shared/text-2gfztfJE.js.map +1 -0
- package/dist/styles.css +329 -0
- package/package.json +9 -5
- package/dist/lazy/inline-worker-D8bxbE-Q.js +0 -30
package/dist/react.d.ts
CHANGED
|
@@ -1,12 +1,1966 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* React editor of the audio SDK: `AudioEditor`, its building blocks and
|
|
2
|
+
* React editor of the audio SDK: `AudioEditor`, its building blocks and
|
|
3
|
+
* hooks (docs/adr/0005, docs/adr/0006).
|
|
3
4
|
*
|
|
4
5
|
* @remarks
|
|
5
6
|
* A client entry: it starts with `"use client"`, which the build keeps
|
|
6
|
-
* (ADR 0007)
|
|
7
|
-
*
|
|
7
|
+
* (ADR 0007), and does nothing on import. On a server, the editor renders
|
|
8
|
+
* its empty state, with no engine, worker or `AudioContext`. React and React
|
|
9
|
+
* DOM 18.3 or later are optional peer dependencies, and `@hussmartinez/ui`
|
|
10
|
+
* gives its controls: load its stylesheet before this package's.
|
|
8
11
|
*
|
|
9
12
|
* @packageDocumentation
|
|
10
13
|
*/
|
|
11
14
|
|
|
15
|
+
import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
|
|
16
|
+
import { ForwardRefExoticComponent } from 'react';
|
|
17
|
+
import { MessageOverrides } from '@hussmartinez/sdk-core';
|
|
18
|
+
import { Messages } from '@hussmartinez/sdk-core';
|
|
19
|
+
import { ReactNode } from 'react';
|
|
20
|
+
import { RefAttributes } from 'react';
|
|
21
|
+
import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
|
|
22
|
+
import { SdkError } from '@hussmartinez/sdk-core';
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Adds an empty track at an index.
|
|
26
|
+
*
|
|
27
|
+
* @public
|
|
28
|
+
*/
|
|
29
|
+
declare interface AudioAddTrackCommand {
|
|
30
|
+
readonly type: "audio.addTrack";
|
|
31
|
+
/**
|
|
32
|
+
* The new track's key. `session.execute` gives one from
|
|
33
|
+
* `session.createKey()` when it's left out; a stored command, and the
|
|
34
|
+
* format, always carry it.
|
|
35
|
+
*/
|
|
36
|
+
readonly key?: string;
|
|
37
|
+
readonly index: number;
|
|
38
|
+
readonly name?: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Options every port call accepts.
|
|
43
|
+
*
|
|
44
|
+
* @public
|
|
45
|
+
*/
|
|
46
|
+
declare interface AudioCallOptions {
|
|
47
|
+
/**
|
|
48
|
+
* Cancels the call. It then rejects with an `AudioError` whose code is
|
|
49
|
+
* `ABORTED`, `TIMEOUT`, or the code of an `SdkError` given as the abort
|
|
50
|
+
* reason, such as `PROCESSING_TIME_EXCEEDED`.
|
|
51
|
+
*/
|
|
52
|
+
readonly signal?: AbortSignal;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* A clip on a track (docs/adr/0006): a range of a source, starting on the
|
|
57
|
+
* timeline frame `at`. A clip's position is stored, so an edit on one track
|
|
58
|
+
* leaves every other clip where it is.
|
|
59
|
+
*
|
|
60
|
+
* @public
|
|
61
|
+
*/
|
|
62
|
+
declare interface AudioClip extends AudioClipBody {
|
|
63
|
+
/** The timeline frame the clip starts on. */
|
|
64
|
+
readonly at: number;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* A range of a source with its gain and fades: a clip without its place on
|
|
69
|
+
* the timeline, which is what version 1 of the plan called a clip.
|
|
70
|
+
*
|
|
71
|
+
* @public
|
|
72
|
+
*/
|
|
73
|
+
declare interface AudioClipBody {
|
|
74
|
+
/** Stable across edits, so selection and waveform tiles follow a clip that moves. */
|
|
75
|
+
readonly key: string;
|
|
76
|
+
/** The id of the source the clip plays. */
|
|
77
|
+
readonly source: string;
|
|
78
|
+
/** The first source frame the clip plays, inclusive. */
|
|
79
|
+
readonly start: number;
|
|
80
|
+
/** The source frame the clip stops before, exclusive. */
|
|
81
|
+
readonly end: number;
|
|
82
|
+
/** The clip's gain in decibels. 0 leaves it unchanged. */
|
|
83
|
+
readonly gainDb: number;
|
|
84
|
+
readonly fadeIn: AudioFade;
|
|
85
|
+
readonly fadeOut: AudioFade;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* One track's part of {@link AudioReplaceClipsCommand}.
|
|
90
|
+
*
|
|
91
|
+
* @public
|
|
92
|
+
*/
|
|
93
|
+
declare interface AudioClipsEdit {
|
|
94
|
+
readonly track: string;
|
|
95
|
+
/** The first clip of the run to replace. */
|
|
96
|
+
readonly index: number;
|
|
97
|
+
/** How many clips the run has. */
|
|
98
|
+
readonly count: number;
|
|
99
|
+
/** What takes the run's place. */
|
|
100
|
+
readonly clips: readonly AudioClip[];
|
|
101
|
+
/** Frames every clip after the run moves by: negative is earlier. */
|
|
102
|
+
readonly shift: number;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The codecs the probe recognises (ADR 0001). `pcm` covers integer and
|
|
107
|
+
* floating-point samples in WAV and AIFF.
|
|
108
|
+
*
|
|
109
|
+
* @public
|
|
110
|
+
*/
|
|
111
|
+
declare type AudioCodec = "pcm" | "mp3" | "aac" | "alac" | "opus" | "vorbis" | "flac";
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* An edit to the plan (docs/adr/0003, docs/adr/0006): the user's commands,
|
|
115
|
+
* and the inverses that only undo runs, which aren't part of the portable
|
|
116
|
+
* format. Commands are plain, structured-cloneable data, never carry
|
|
117
|
+
* samples, and each has an exact inverse, which is how undo works
|
|
118
|
+
* (ADR 0010, ADR 0029).
|
|
119
|
+
*
|
|
120
|
+
* @public
|
|
121
|
+
*/
|
|
122
|
+
declare type AudioCommand = AudioUserCommand | AudioRestoreClipsCommand | AudioUpdateClipsCommand | AudioPlaceClipsCommand | AudioReplaceClipsCommand | AudioRestoreTracksCommand;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The containers the probe recognises (ADR 0001).
|
|
126
|
+
*
|
|
127
|
+
* @public
|
|
128
|
+
*/
|
|
129
|
+
declare type AudioContainer = "wav" | "aiff" | "flac" | "ogg" | "mp3" | "adts" | "mp4" | "webm";
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Options for `AudioEngine.decode`.
|
|
133
|
+
*
|
|
134
|
+
* @public
|
|
135
|
+
*/
|
|
136
|
+
declare interface AudioDecodeOptions extends AudioProgressOptions {
|
|
137
|
+
/**
|
|
138
|
+
* The sample rate to return the audio at, in hertz, when it isn't the
|
|
139
|
+
* probe's: the engine converts it, as the session asks for a recording
|
|
140
|
+
* inserted at another rate than its own (docs/adr/0006). The result then
|
|
141
|
+
* has `Math.ceil(frames × sampleRate / probe.sampleRate)` frames, which
|
|
142
|
+
* cover the same time.
|
|
143
|
+
*/
|
|
144
|
+
readonly sampleRate?: number;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Removes a range of time from the named tracks, trimming the clips at its
|
|
149
|
+
* edges. With `ripple`, later clips on those tracks move earlier by the
|
|
150
|
+
* range's length; without, silence stays.
|
|
151
|
+
*
|
|
152
|
+
* @public
|
|
153
|
+
*/
|
|
154
|
+
declare interface AudioDeleteRangeCommand {
|
|
155
|
+
readonly type: "audio.deleteRange";
|
|
156
|
+
readonly start: number;
|
|
157
|
+
readonly end: number;
|
|
158
|
+
readonly tracks: readonly string[];
|
|
159
|
+
readonly ripple: boolean;
|
|
160
|
+
/**
|
|
161
|
+
* By track key: the key of the part after the range, on a track where the
|
|
162
|
+
* range lies inside one clip. A track that doesn't need its key ignores it.
|
|
163
|
+
* `session.execute` gives a key to every track named without one.
|
|
164
|
+
*/
|
|
165
|
+
readonly newKeys?: Readonly<Record<string, string>>;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The audio editor (docs/adr/0005, docs/adr/0006): a recording's tracks on
|
|
170
|
+
* a timeline, with playback, over one editing session, entirely on the
|
|
171
|
+
* device. It makes the SDK's own engine, processor and output for any you
|
|
172
|
+
* don't pass.
|
|
173
|
+
*
|
|
174
|
+
* Load `ui`'s stylesheet, then this package's, once:
|
|
175
|
+
*
|
|
176
|
+
* @example
|
|
177
|
+
* ```tsx
|
|
178
|
+
* import "@hussmartinez/ui/styles.css";
|
|
179
|
+
* import "@hussmartinez/audio-sdk/styles.css";
|
|
180
|
+
* import { AudioEditor } from "@hussmartinez/audio-sdk/react";
|
|
181
|
+
*
|
|
182
|
+
* <AudioEditor initialFile={file} onChange={(plan) => save(plan)} />
|
|
183
|
+
* ```
|
|
184
|
+
*
|
|
185
|
+
* @public
|
|
186
|
+
*/
|
|
187
|
+
export declare const AudioEditor: ForwardRefExoticComponent<AudioEditorProps & RefAttributes<AudioEditorHandle>>;
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* What a host can do with the editor through its ref.
|
|
191
|
+
*
|
|
192
|
+
* @public
|
|
193
|
+
*/
|
|
194
|
+
export declare interface AudioEditorHandle {
|
|
195
|
+
/** Opens a recording, replacing the current one once it has opened. */
|
|
196
|
+
open(file: Blob): Promise<void>;
|
|
197
|
+
/** Adds a recording on a new track, or on `options.track`. */
|
|
198
|
+
insert(file: Blob, options?: AudioInsertOptions): Promise<void>;
|
|
199
|
+
undo(): void;
|
|
200
|
+
redo(): void;
|
|
201
|
+
play(): Promise<void>;
|
|
202
|
+
pause(): void;
|
|
203
|
+
/** Moves the playhead to a timeline frame. */
|
|
204
|
+
seek(frame: number): void;
|
|
205
|
+
/**
|
|
206
|
+
* Exports the plan as it is now, for a host's own export button, without
|
|
207
|
+
* the editor's dialog: through the editor's processor, or the host's
|
|
208
|
+
* `processor`. It resolves with the file, the mix's peak and how many
|
|
209
|
+
* frames were clamped, and never downloads anything or calls `onExport`.
|
|
210
|
+
* It fails as `session.export` does, and throws `TypeError` when there's
|
|
211
|
+
* no processor.
|
|
212
|
+
*/
|
|
213
|
+
export(options?: AudioSessionExportOptions): Promise<AudioRenderResult>;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* The type of {@link audioEditorMessages}.
|
|
218
|
+
*
|
|
219
|
+
* @public
|
|
220
|
+
*/
|
|
221
|
+
export declare type AudioEditorMessageCatalogue = typeof audioEditorMessages;
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* A host's overrides of the editor's text, keyed as in
|
|
225
|
+
* {@link audioEditorMessages}.
|
|
226
|
+
*
|
|
227
|
+
* @public
|
|
228
|
+
*/
|
|
229
|
+
export declare type AudioEditorMessageOverrides = MessageOverrides<AudioEditorMessageCatalogue>;
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* The text the editor uses.
|
|
233
|
+
*
|
|
234
|
+
* @public
|
|
235
|
+
*/
|
|
236
|
+
export declare type AudioEditorMessages = Messages<AudioEditorMessageCatalogue>;
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* The editor's English catalogue: the SDK's messages, `ui`'s for its own
|
|
240
|
+
* components, and the editor's text, as one catalogue for one `Messages`
|
|
241
|
+
* object (sdk-core ADR 0046). A host overrides any of it, such as `ui`'s
|
|
242
|
+
* `fileDropZone.choose`, through the editor's `messages` prop.
|
|
243
|
+
*
|
|
244
|
+
* @public
|
|
245
|
+
*/
|
|
246
|
+
export declare const audioEditorMessages: {
|
|
247
|
+
readonly "editor.label": "Audio editor";
|
|
248
|
+
readonly "editor.empty": "Drop an audio file here, or choose one. It stays on your device.";
|
|
249
|
+
readonly "editor.opening": "Opening the recording";
|
|
250
|
+
readonly "editor.inserting": "Adding the recording";
|
|
251
|
+
readonly "editor.cancel": "Cancel";
|
|
252
|
+
readonly "editor.opened": "Recording opened.";
|
|
253
|
+
readonly "editor.inserted": "Recording added.";
|
|
254
|
+
readonly "editor.notices": "Notices";
|
|
255
|
+
readonly "editor.dismiss": "Dismiss";
|
|
256
|
+
readonly "editor.historyTrimmed": "The earliest edits can no longer be undone, to make room for the recordings.";
|
|
257
|
+
readonly "timeline.label": "Timeline";
|
|
258
|
+
readonly "timeline.summary": {
|
|
259
|
+
readonly $plural: "count";
|
|
260
|
+
} & {
|
|
261
|
+
readonly one: "{count} track, {duration} long.";
|
|
262
|
+
readonly other: "{count} tracks, {duration} long.";
|
|
263
|
+
};
|
|
264
|
+
readonly "timeline.playhead": "Playhead";
|
|
265
|
+
readonly "timeline.track": "Track {index}";
|
|
266
|
+
readonly "timeline.track.named": "Track {index}, {name}";
|
|
267
|
+
readonly "timeline.lane": "{track}";
|
|
268
|
+
readonly "timeline.lane.muted": "{track}, muted";
|
|
269
|
+
readonly "timeline.lane.silenced": "{track}, silenced by solo";
|
|
270
|
+
readonly "timeline.lane.ripple": "{lane}, later clips move when the selection is deleted";
|
|
271
|
+
readonly "timeline.selection": "Selected {start} to {end} on {tracks}";
|
|
272
|
+
readonly "track.ripple": "Ripple";
|
|
273
|
+
readonly "tracks.every": "every track";
|
|
274
|
+
readonly "tracks.count": {
|
|
275
|
+
readonly $plural: "count";
|
|
276
|
+
} & {
|
|
277
|
+
readonly one: "{count} track";
|
|
278
|
+
readonly other: "{count} tracks";
|
|
279
|
+
};
|
|
280
|
+
readonly "timeline.clips": "Clips on {track}";
|
|
281
|
+
readonly "timeline.clip": "Clip {index} of {count} on {track}, {start} to {end}";
|
|
282
|
+
readonly "timeline.clip.named": "{name}, clip {index} of {count} on {track}, {start} to {end}";
|
|
283
|
+
readonly "timeline.clip.gain": "Clip {index} of {count} on {track}, {start} to {end}, {gain, number} dB";
|
|
284
|
+
readonly "timeline.clip.named.gain": "{name}, clip {index} of {count} on {track}, {start} to {end}, {gain, number} dB";
|
|
285
|
+
readonly "toolbar.label": "Tools";
|
|
286
|
+
readonly "toolbar.file": "File";
|
|
287
|
+
readonly "toolbar.history": "History";
|
|
288
|
+
readonly "toolbar.tracks": "Tracks";
|
|
289
|
+
readonly "toolbar.clips": "Clip";
|
|
290
|
+
readonly "toolbar.range": "Selection";
|
|
291
|
+
readonly "toolbar.view": "Zoom";
|
|
292
|
+
readonly "toolbar.withKeys": "{label} ({keys})";
|
|
293
|
+
readonly "tools.open": "Open";
|
|
294
|
+
readonly "tools.insert": "Add recording";
|
|
295
|
+
readonly "tools.export": "Export";
|
|
296
|
+
readonly "tools.undo": "Undo";
|
|
297
|
+
readonly "tools.redo": "Redo";
|
|
298
|
+
readonly "tools.addTrack": "Add track";
|
|
299
|
+
readonly "tools.removeTrack": "Remove track";
|
|
300
|
+
readonly "tools.moveTrackUp": "Move track up";
|
|
301
|
+
readonly "tools.moveTrackDown": "Move track down";
|
|
302
|
+
readonly "tools.mute": "Mute track";
|
|
303
|
+
readonly "tools.split": "Split at the playhead";
|
|
304
|
+
readonly "tools.delete": "Delete";
|
|
305
|
+
readonly "tools.trimStart": "Trim the start to the playhead";
|
|
306
|
+
readonly "tools.trimEnd": "Trim the end to the playhead";
|
|
307
|
+
readonly "tools.moveEarlier": "Move the clip earlier";
|
|
308
|
+
readonly "tools.moveLater": "Move the clip later";
|
|
309
|
+
readonly "tools.moveToTrackAbove": "Move the clip to the track above";
|
|
310
|
+
readonly "tools.moveToTrackBelow": "Move the clip to the track below";
|
|
311
|
+
readonly "tools.setStart": "Start the selection at the playhead";
|
|
312
|
+
readonly "tools.setEnd": "End the selection at the playhead";
|
|
313
|
+
readonly "tools.clearSelection": "Clear the selection";
|
|
314
|
+
readonly "tools.ripple": "Ripple";
|
|
315
|
+
readonly "tools.fadeIn": "Fade in";
|
|
316
|
+
readonly "tools.fadeOut": "Fade out";
|
|
317
|
+
readonly "tools.zoomIn": "Zoom in";
|
|
318
|
+
readonly "tools.zoomOut": "Zoom out";
|
|
319
|
+
readonly "tools.zoomFit": "Fit to width";
|
|
320
|
+
readonly "tools.playPause": "Play or pause";
|
|
321
|
+
readonly "tools.start": "Go to the start";
|
|
322
|
+
readonly "tools.end": "Go to the end";
|
|
323
|
+
readonly "track.rename": "{track}, rename";
|
|
324
|
+
readonly "track.mute": "Mute";
|
|
325
|
+
readonly "track.solo": "Solo";
|
|
326
|
+
readonly "track.gain": "Gain";
|
|
327
|
+
readonly "track.gainValue": "{gain, number} dB";
|
|
328
|
+
readonly "rename.title": "Rename the track";
|
|
329
|
+
readonly "rename.name": "Name";
|
|
330
|
+
readonly "rename.description": "Leave it empty for no name.";
|
|
331
|
+
readonly "rename.save": "Rename";
|
|
332
|
+
readonly "announce.undone": "Undone.";
|
|
333
|
+
readonly "announce.redone": "Redone.";
|
|
334
|
+
readonly "announce.trackAdded": "Track added.";
|
|
335
|
+
readonly "announce.trackRemoved": "{track} removed.";
|
|
336
|
+
readonly "announce.trackMoved": "{track} moved.";
|
|
337
|
+
readonly "announce.muted": "{track} muted.";
|
|
338
|
+
readonly "announce.unmuted": "{track} unmuted.";
|
|
339
|
+
readonly "announce.soloed": "{track} soloed.";
|
|
340
|
+
readonly "announce.unsoloed": "{track} no longer soloed.";
|
|
341
|
+
readonly "announce.split": "Split at {time}.";
|
|
342
|
+
readonly "announce.noClipToSplit": "There's no clip on {track} at the playhead to split.";
|
|
343
|
+
readonly "announce.clipDeleted": "Clip deleted.";
|
|
344
|
+
readonly "announce.clipMovedTo": "Clip moved to {track}.";
|
|
345
|
+
readonly "announce.trimmed": "The clip is now {time} to {end}.";
|
|
346
|
+
readonly "announce.noRoom": "There's no room for the clip there.";
|
|
347
|
+
readonly "announce.refused": "That edit isn't possible.";
|
|
348
|
+
readonly "announce.selected": "Selected {time} to {end} on {tracks}.";
|
|
349
|
+
readonly "announce.selectionCleared": "Selection cleared.";
|
|
350
|
+
readonly "announce.rangeDeleted": "Deleted {time} to {end} from {tracks}.";
|
|
351
|
+
readonly "announce.rangeDeleted.ripple": "Deleted {time} to {end} from {tracks}. Later clips there moved earlier.";
|
|
352
|
+
readonly "announce.rippleOn": "Ripple on: deleting a range closes the gap.";
|
|
353
|
+
readonly "announce.rippleOff": "Ripple off: deleting a range leaves silence.";
|
|
354
|
+
readonly "announce.nothingInRange": "There's no audio in the selection to change.";
|
|
355
|
+
readonly "announce.rangeGain": "{time} to {end} on {tracks} set to {gain, number} dB.";
|
|
356
|
+
readonly "announce.fadedIn": "Fade in from {time} to {end} on {tracks}.";
|
|
357
|
+
readonly "announce.fadedOut": "Fade out from {time} to {end} on {tracks}.";
|
|
358
|
+
readonly "announce.noRoomForFade": "The clip has no room for that fade: shorten its other fade first.";
|
|
359
|
+
readonly "announce.clipFadedIn": "The clip fades in over {time}. Set its length in the inspector.";
|
|
360
|
+
readonly "announce.clipFadedOut": "The clip fades out over {time}. Set its length in the inspector.";
|
|
361
|
+
readonly "inspector.clip": "Clip on {track}";
|
|
362
|
+
readonly "inspector.recording": "Recording";
|
|
363
|
+
readonly "inspector.selection": "Selection";
|
|
364
|
+
readonly "inspector.selectionGain": "Gain of the selection, in decibels";
|
|
365
|
+
readonly "inspector.start": "Start";
|
|
366
|
+
readonly "inspector.gain": "Gain";
|
|
367
|
+
readonly "inspector.gainExact": "Gain, in decibels";
|
|
368
|
+
readonly "inspector.fadeIn": "Fade in, in seconds";
|
|
369
|
+
readonly "inspector.fadeOut": "Fade out, in seconds";
|
|
370
|
+
readonly "inspector.fadeInCurve": "Fade in curve";
|
|
371
|
+
readonly "inspector.fadeOutCurve": "Fade out curve";
|
|
372
|
+
readonly "inspector.curve.linear": "Linear";
|
|
373
|
+
readonly "inspector.curve.equalPower": "Equal power";
|
|
374
|
+
readonly "inspector.length": "Length";
|
|
375
|
+
readonly "inspector.sampleRate": "Sample rate";
|
|
376
|
+
readonly "inspector.sampleRateValue": "{rate, number} Hz";
|
|
377
|
+
readonly "inspector.tracks": "Tracks";
|
|
378
|
+
readonly "inspector.masterGain": "Master gain";
|
|
379
|
+
readonly "inspector.masterGainExact": "Master gain, in decibels";
|
|
380
|
+
readonly "inspector.channels": "Channels";
|
|
381
|
+
readonly "inspector.mono": "Mono";
|
|
382
|
+
readonly "inspector.stereo": "Stereo";
|
|
383
|
+
readonly "inspector.channelCount": "{count} channels";
|
|
384
|
+
readonly "metadata.title": "Title";
|
|
385
|
+
readonly "metadata.artist": "Artist";
|
|
386
|
+
readonly "metadata.album": "Album";
|
|
387
|
+
readonly "metadata.year": "Year";
|
|
388
|
+
readonly "metadata.comment": "Comment";
|
|
389
|
+
readonly "export.title": "Export";
|
|
390
|
+
readonly "export.description": "Write the recording to a WAV file on your device.";
|
|
391
|
+
readonly "export.summary": "What will be written";
|
|
392
|
+
readonly "export.audio": "{length} long, at {rate, number} Hz, {channels}.";
|
|
393
|
+
readonly "export.muted": "{track} is muted, so it won't be in the file.";
|
|
394
|
+
readonly "export.silenced": "{track} isn't soloed, so it won't be in the file.";
|
|
395
|
+
readonly "export.silent": "{track} won't be heard in the file.";
|
|
396
|
+
readonly "export.nothingHeard": "Every track with audio is muted or silenced by a solo, so there's nothing to export.";
|
|
397
|
+
readonly "export.metadata": "Written to the file: {fields}.";
|
|
398
|
+
readonly "export.noMetadata": "No metadata is written to the file.";
|
|
399
|
+
readonly "export.private": "Only the mix and this metadata are written. Nothing leaves your device.";
|
|
400
|
+
readonly "export.format": "Format";
|
|
401
|
+
readonly "export.formats.pcm16": "16-bit, {size, fileSize}";
|
|
402
|
+
readonly "export.formats.pcm24": "24-bit, {size, fileSize}";
|
|
403
|
+
readonly "export.formats.float32": "32-bit float, {size, fileSize}";
|
|
404
|
+
readonly "export.cancel": "Cancel";
|
|
405
|
+
readonly "export.confirm": "Export";
|
|
406
|
+
readonly "export.progress": "Exporting";
|
|
407
|
+
readonly "export.stop": "Stop";
|
|
408
|
+
readonly "export.done": "Done";
|
|
409
|
+
readonly "export.download": "Download";
|
|
410
|
+
readonly "export.ready": "The WAV file is ready: {size, fileSize}.";
|
|
411
|
+
readonly "export.cancelled": "Export stopped.";
|
|
412
|
+
readonly "export.clipped": "The mix went {db, number} dB over full scale, so {frames, number} frames were clipped.";
|
|
413
|
+
readonly "export.lower": "Lower the master gain by {db, number} dB and export again";
|
|
414
|
+
readonly "export.unavailable": "This editor has nothing to export with.";
|
|
415
|
+
readonly "transport.label": "Playback";
|
|
416
|
+
readonly "transport.play": "Play";
|
|
417
|
+
readonly "transport.pause": "Pause";
|
|
418
|
+
readonly "transport.start": "Back to the start";
|
|
419
|
+
readonly "transport.time": "{position} / {duration}";
|
|
420
|
+
readonly "colorField.swatches": "swatches";
|
|
421
|
+
readonly "dialog.close": "Close";
|
|
422
|
+
readonly "fileDropZone.choose": "Choose a file";
|
|
423
|
+
readonly "fileDropZone.chooseMultiple": "Choose files";
|
|
424
|
+
readonly "fileDropZone.hint": "or drop it here";
|
|
425
|
+
readonly "fileDropZone.hintMultiple": "or drop them here";
|
|
426
|
+
readonly "progress.label": "Progress";
|
|
427
|
+
readonly "reorderableList.moved": "{label} moved to position {position} of {count}";
|
|
428
|
+
readonly "spinner.label": "Loading";
|
|
429
|
+
readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
|
|
430
|
+
readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
|
|
431
|
+
readonly "errors.INVALID_AUDIO": "This file isn't valid audio, or it's too damaged to open.";
|
|
432
|
+
readonly "errors.UNSUPPORTED_FORMAT": "This audio format isn't supported. Try converting the file to WAV, then open it again.";
|
|
433
|
+
readonly "errors.DECODE_FAILED": "This browser can't play this kind of audio. Try another browser, or convert the file to WAV.";
|
|
434
|
+
readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
|
|
435
|
+
readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an audio project.";
|
|
436
|
+
readonly "errors.DURATION_TOO_LONG": "This recording is {actual, duration} long, which is over the {maximum, duration} limit.";
|
|
437
|
+
readonly "errors.TOO_MANY_CHANNELS": "This recording has {actual, number} channels, which is over the {maximum, number}-channel limit.";
|
|
438
|
+
readonly "errors.SAMPLE_RATE_TOO_HIGH": "This recording's sample rate is {actual, number} Hz, which is over the {maximum, number} Hz limit.";
|
|
439
|
+
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.";
|
|
440
|
+
readonly "errors.TOO_MANY_CLIPS": {
|
|
441
|
+
readonly $plural: "maximum";
|
|
442
|
+
} & {
|
|
443
|
+
readonly one: "A recording can have {maximum} clip. Join or delete clips, and try again.";
|
|
444
|
+
readonly other: "A recording can have up to {maximum} clips. Join or delete clips, and try again.";
|
|
445
|
+
};
|
|
446
|
+
readonly "errors.TOO_MANY_TRACKS": {
|
|
447
|
+
readonly $plural: "maximum";
|
|
448
|
+
} & {
|
|
449
|
+
readonly one: "A recording can have {maximum} track. Remove a track, and try again.";
|
|
450
|
+
readonly other: "A recording can have up to {maximum} tracks. Remove a track, and try again.";
|
|
451
|
+
};
|
|
452
|
+
readonly "warnings.maxDuration": "This recording is {actual, duration} long, and may be slow to open and edit.";
|
|
453
|
+
readonly "warnings.maxChannels": "This recording has {actual, number} channels, and may be slow to edit.";
|
|
454
|
+
readonly "warnings.maxSampleRate": "This recording's sample rate is {actual, number} Hz, and it may be slow to edit.";
|
|
455
|
+
readonly "warnings.maxSessionSize": "The open recordings use {actual, fileSize} of memory. Clearing the undo history frees memory.";
|
|
456
|
+
readonly "warnings.maxClips": {
|
|
457
|
+
readonly $plural: "actual";
|
|
458
|
+
} & {
|
|
459
|
+
readonly one: "This recording has {actual} clip. Many clips may be slow to play and export.";
|
|
460
|
+
readonly other: "This recording has {actual} clips. Many clips may be slow to play and export.";
|
|
461
|
+
};
|
|
462
|
+
readonly "warnings.maxTracks": {
|
|
463
|
+
readonly $plural: "actual";
|
|
464
|
+
} & {
|
|
465
|
+
readonly one: "This recording has {actual} track. Many tracks may be slow to play and export.";
|
|
466
|
+
readonly other: "This recording has {actual} tracks. Many tracks may be slow to play and export.";
|
|
467
|
+
};
|
|
468
|
+
readonly "errors.UNSUPPORTED_ENVIRONMENT.autoplay-blocked": "The browser didn't let sound start. Press Play to start it.";
|
|
469
|
+
readonly "errors.DURATION_TOO_LONG.plan-too-long": "This would make the recording {actual, duration} long, which is over the {maximum, duration} limit.";
|
|
470
|
+
readonly "warnings.truncated": "This recording looks incomplete, perhaps from an interrupted recording or download. It opened with the audio it holds.";
|
|
471
|
+
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
472
|
+
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
473
|
+
readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
|
|
474
|
+
readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
|
|
475
|
+
readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
|
|
476
|
+
readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
|
|
477
|
+
readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
|
|
478
|
+
readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
|
|
479
|
+
readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
|
|
480
|
+
readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
|
|
481
|
+
readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
|
|
482
|
+
readonly "errors.TOO_MANY_FILES": {
|
|
483
|
+
readonly $plural: "maximum";
|
|
484
|
+
} & {
|
|
485
|
+
readonly one: "You can add {maximum} file at a time.";
|
|
486
|
+
readonly other: "You can add up to {maximum} files at a time.";
|
|
487
|
+
};
|
|
488
|
+
readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
|
|
489
|
+
readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
|
|
490
|
+
readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
|
|
491
|
+
readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
|
|
492
|
+
readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
|
|
493
|
+
readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
|
|
494
|
+
readonly "keys.control": "Ctrl";
|
|
495
|
+
readonly "keys.alt": "Alt";
|
|
496
|
+
readonly "keys.shift": "Shift";
|
|
497
|
+
readonly "keys.meta": "Meta";
|
|
498
|
+
readonly "keys.apple.control": "\u2303";
|
|
499
|
+
readonly "keys.apple.alt": "\u2325";
|
|
500
|
+
readonly "keys.apple.shift": "\u21E7";
|
|
501
|
+
readonly "keys.apple.meta": "\u2318";
|
|
502
|
+
readonly "keys.space": "Space";
|
|
503
|
+
readonly "keys.enter": "Enter";
|
|
504
|
+
readonly "keys.escape": "Esc";
|
|
505
|
+
readonly "keys.tab": "Tab";
|
|
506
|
+
readonly "keys.delete": "Delete";
|
|
507
|
+
readonly "keys.backspace": "Backspace";
|
|
508
|
+
readonly "keys.arrowUp": "\u2191";
|
|
509
|
+
readonly "keys.arrowDown": "\u2193";
|
|
510
|
+
readonly "keys.arrowLeft": "\u2190";
|
|
511
|
+
readonly "keys.arrowRight": "\u2192";
|
|
512
|
+
readonly "keys.home": "Home";
|
|
513
|
+
readonly "keys.end": "End";
|
|
514
|
+
readonly "keys.pageUp": "Page Up";
|
|
515
|
+
readonly "keys.pageDown": "Page Down";
|
|
516
|
+
};
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* The parts of the editor that `classNames` can target.
|
|
520
|
+
*
|
|
521
|
+
* @public
|
|
522
|
+
*/
|
|
523
|
+
export declare type AudioEditorPart = "root" | "toolbar" | "notices" | "stage" | "timeline" | "transport" | "inspector";
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* Props of {@link AudioEditor}: the provider's, and the editor's own.
|
|
527
|
+
*
|
|
528
|
+
* @public
|
|
529
|
+
*/
|
|
530
|
+
export declare interface AudioEditorProps extends Omit<AudioEditorProviderProps, "children"> {
|
|
531
|
+
/** A recording opened when the editor mounts. */
|
|
532
|
+
readonly initialFile?: Blob;
|
|
533
|
+
/**
|
|
534
|
+
* Called with the plan whenever it changes: when a recording opens or is
|
|
535
|
+
* added, after every edit, and after undo and redo.
|
|
536
|
+
*/
|
|
537
|
+
readonly onChange?: (plan: AudioPlan) => void;
|
|
538
|
+
/**
|
|
539
|
+
* The colour scheme, as `ui`'s `data-hm-theme`: `"light"`, `"dark"`, or
|
|
540
|
+
* `"system"` to follow the device. Without it, the editor follows the
|
|
541
|
+
* page's theme.
|
|
542
|
+
*/
|
|
543
|
+
readonly theme?: "light" | "dark" | "system";
|
|
544
|
+
/**
|
|
545
|
+
* The level of the editor's headings, from 2 to 6, so they fit the
|
|
546
|
+
* host's outline: the inspector's, for now. Defaults to 2.
|
|
547
|
+
*/
|
|
548
|
+
readonly headingLevel?: AudioHeadingLevel;
|
|
549
|
+
/**
|
|
550
|
+
* The name an export is downloaded under, without its extension, such as
|
|
551
|
+
* the name of the file being edited. Without it, the recording's title is
|
|
552
|
+
* used, or else `recording`. See {@link AudioExportDialogProps.fileName}.
|
|
553
|
+
*/
|
|
554
|
+
readonly fileName?: string;
|
|
555
|
+
/**
|
|
556
|
+
* Takes an export's file instead of the download, such as to upload it or
|
|
557
|
+
* save it the host's own way. The export dialog closes once it's called.
|
|
558
|
+
* See {@link AudioExportDialogProps.onExport}.
|
|
559
|
+
*/
|
|
560
|
+
readonly onExport?: (blob: Blob, result: AudioRenderResult) => void;
|
|
561
|
+
/** Extra classes on the root. */
|
|
562
|
+
readonly className?: string;
|
|
563
|
+
/** Extra classes on the editor's parts. */
|
|
564
|
+
readonly classNames?: Readonly<Partial<Record<AudioEditorPart, string>>>;
|
|
565
|
+
/**
|
|
566
|
+
* Leaves out the editor's own look: its layout and colours, and `ui`'s
|
|
567
|
+
* `hm-text` on the root. `ui`'s components keep theirs.
|
|
568
|
+
*/
|
|
569
|
+
readonly unstyled?: boolean;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* Holds one editing session and its playback for the editor's parts
|
|
574
|
+
* (docs/adr/0005): the session, the output kept in step with it by
|
|
575
|
+
* `connectOutput`, and the editor's text. It makes the SDK's own engine,
|
|
576
|
+
* processor and output for any you don't pass, and releases those when it
|
|
577
|
+
* unmounts; ones you pass stay yours.
|
|
578
|
+
*
|
|
579
|
+
* StrictMode mounts twice in development: the release waits a moment, and a
|
|
580
|
+
* second mount cancels it, so the editor keeps one session and at most one
|
|
581
|
+
* `AudioContext`.
|
|
582
|
+
*
|
|
583
|
+
* @public
|
|
584
|
+
*/
|
|
585
|
+
export declare function AudioEditorProvider(props: AudioEditorProviderProps): ReactNode;
|
|
586
|
+
|
|
587
|
+
/**
|
|
588
|
+
* Props of {@link AudioEditorProvider}.
|
|
589
|
+
*
|
|
590
|
+
* @public
|
|
591
|
+
*/
|
|
592
|
+
export declare interface AudioEditorProviderProps {
|
|
593
|
+
/** Replaces the SDK's engine. You keep owning one you pass: the editor never destroys it. */
|
|
594
|
+
readonly engine?: AudioEngine;
|
|
595
|
+
/** Replaces the SDK's processor for exports. You keep owning it. */
|
|
596
|
+
readonly processor?: AudioProcessor;
|
|
597
|
+
/** Replaces the SDK's playback output. You keep owning it. */
|
|
598
|
+
readonly output?: AudioOutput;
|
|
599
|
+
/** The limits files and edits are checked against (docs/adr/0004). */
|
|
600
|
+
readonly filePolicy?: AudioFilePolicyOverrides;
|
|
601
|
+
/**
|
|
602
|
+
* Where the application serves the package's `dist/assets/`, to self-host
|
|
603
|
+
* the worker of the engine and the processor the editor makes.
|
|
604
|
+
*/
|
|
605
|
+
readonly assetsUrl?: string | URL;
|
|
606
|
+
/** Text overrides. */
|
|
607
|
+
readonly messages?: AudioEditorMessageOverrides;
|
|
608
|
+
/** The locale numbers, sizes and durations are formatted for. Defaults to `en`. */
|
|
609
|
+
readonly locale?: string;
|
|
610
|
+
/** Anonymous usage events: never file names, samples or metadata. */
|
|
611
|
+
readonly onEvent?: (event: AudioSessionEvent) => void;
|
|
612
|
+
/**
|
|
613
|
+
* Which tools are present, by id, in order, such as
|
|
614
|
+
* `["audio.undo", "audio.redo", "audio.add-track"]`. All of them by
|
|
615
|
+
* default. A tool that's left out has no button and no shortcut.
|
|
616
|
+
*/
|
|
617
|
+
readonly tools?: readonly string[];
|
|
618
|
+
/**
|
|
619
|
+
* The toolbar's groups, by tool id. By default: files, history, tracks
|
|
620
|
+
* and zoom, from the present tools.
|
|
621
|
+
*/
|
|
622
|
+
readonly toolbar?: readonly (readonly string[])[];
|
|
623
|
+
readonly children?: ReactNode;
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
/**
|
|
627
|
+
* The port for reading audio files: probe a file's headers, decode it, and
|
|
628
|
+
* build its waveform overview (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
629
|
+
* adapter probes and parses in its worker and decodes compressed formats
|
|
630
|
+
* with Web Audio; hosts can pass their own to the editor's `engine` prop, and
|
|
631
|
+
* every implementation must pass the engine's contract tests.
|
|
632
|
+
*
|
|
633
|
+
* The engine doesn't apply the file policy: the session checks the probe
|
|
634
|
+
* against it between `probe` and `decode` (ADR 0004).
|
|
635
|
+
*
|
|
636
|
+
* Failures reject with `AudioError`: `INVALID_AUDIO` for a malformed file,
|
|
637
|
+
* `UNSUPPORTED_FORMAT` for one the probe can't bound, `DECODE_FAILED` when
|
|
638
|
+
* the browser can't decode it, and sdk-core's codes for cancellation and
|
|
639
|
+
* worker failures.
|
|
640
|
+
*
|
|
641
|
+
* @public
|
|
642
|
+
*/
|
|
643
|
+
declare interface AudioEngine {
|
|
644
|
+
/**
|
|
645
|
+
* Reads a file's headers and walks its packets, without decoding it. It
|
|
646
|
+
* reads the file through the `Blob`, never all at once.
|
|
647
|
+
*/
|
|
648
|
+
probe(file: Blob, options?: AudioCallOptions): Promise<AudioProbe>;
|
|
649
|
+
/**
|
|
650
|
+
* Decodes a probed file at the probe's channel count, and at the probe's
|
|
651
|
+
* sample rate unless `options.sampleRate` asks for another, which the
|
|
652
|
+
* engine converts the audio to. A result longer than the probe's bound
|
|
653
|
+
* plus its tolerance rejects with `INVALID_AUDIO`; a shorter one is
|
|
654
|
+
* returned as it is.
|
|
655
|
+
*/
|
|
656
|
+
decode(file: Blob, probe: AudioProbe, options?: AudioDecodeOptions): Promise<DecodedAudio>;
|
|
657
|
+
/**
|
|
658
|
+
* Builds a waveform overview of decoded audio. The audio isn't modified or
|
|
659
|
+
* kept.
|
|
660
|
+
*/
|
|
661
|
+
peaks(audio: DecodedAudio, options?: AudioCallOptions): Promise<AudioPeaks>;
|
|
662
|
+
/** Releases the engine and its worker. Pending calls reject, and later calls throw. */
|
|
663
|
+
destroy(): Promise<void>;
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* The error `@hussmartinez/audio-sdk` throws and rejects with, with a stable
|
|
668
|
+
* `code`, structured `details` and the underlying error as `cause`. Show
|
|
669
|
+
* users the text for its code from {@link audioMessages}, never its
|
|
670
|
+
* `message`, which is for developers and may contain text from the file.
|
|
671
|
+
*
|
|
672
|
+
* @example
|
|
673
|
+
* ```ts
|
|
674
|
+
* try {
|
|
675
|
+
* await session.open(file);
|
|
676
|
+
* } catch (error) {
|
|
677
|
+
* if (isAudioError(error, "DECODE_FAILED")) {
|
|
678
|
+
* suggestConvertingToWav();
|
|
679
|
+
* } else {
|
|
680
|
+
* show(messages.error(error));
|
|
681
|
+
* }
|
|
682
|
+
* }
|
|
683
|
+
* ```
|
|
684
|
+
*
|
|
685
|
+
* @public
|
|
686
|
+
*/
|
|
687
|
+
declare class AudioError extends SdkError<AudioErrorCode> {
|
|
688
|
+
/** Always `"AudioError"`, which survives minification and worker boundaries. */
|
|
689
|
+
readonly name = "AudioError";
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
/**
|
|
693
|
+
* Error codes of `@hussmartinez/audio-sdk`: sdk-core's own codes, such as
|
|
694
|
+
* `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the audio SDK's
|
|
695
|
+
* (ADR 0004). They never change meaning once released.
|
|
696
|
+
*
|
|
697
|
+
* - `INVALID_AUDIO`: the file is malformed, its headers claim more audio than
|
|
698
|
+
* its packets carry, or it decodes to more than its bound allows.
|
|
699
|
+
* - `UNSUPPORTED_FORMAT`: the container or codec isn't recognised, the file's
|
|
700
|
+
* packets can't be walked to a bound, or the browser can't decode at its
|
|
701
|
+
* sample rate.
|
|
702
|
+
* - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
|
|
703
|
+
* usually because it lacks the codec. `details.codec` names it.
|
|
704
|
+
* - `INVALID_COMMAND`: an edit command doesn't apply to the clip plan, such
|
|
705
|
+
* as a range outside its source or an unknown clip key.
|
|
706
|
+
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
707
|
+
* valid in its format.
|
|
708
|
+
* - `DURATION_TOO_LONG`: a file, or the plan an edit would give, exceeds the
|
|
709
|
+
* `maxDuration` limit.
|
|
710
|
+
* - `TOO_MANY_CHANNELS`: a file exceeds the `maxChannels` limit.
|
|
711
|
+
* - `SAMPLE_RATE_TOO_HIGH`: a file exceeds the `maxSampleRate` limit.
|
|
712
|
+
* - `SESSION_TOO_LARGE`: the decoded audio the session holds exceeds the
|
|
713
|
+
* `maxSessionSize` limit.
|
|
714
|
+
* - `TOO_MANY_CLIPS`: the plan exceeds the `maxClips` limit, over all its
|
|
715
|
+
* tracks.
|
|
716
|
+
* - `TOO_MANY_TRACKS`: the plan exceeds the `maxTracks` limit.
|
|
717
|
+
*
|
|
718
|
+
* Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
|
|
719
|
+
* value and the `unit`. Other codes' `details` name the container, codec or
|
|
720
|
+
* sample rate involved, never data from the file.
|
|
721
|
+
*
|
|
722
|
+
* @public
|
|
723
|
+
*/
|
|
724
|
+
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";
|
|
725
|
+
|
|
726
|
+
/**
|
|
727
|
+
* The export dialog (docs/adr/0005, docs/adr/0006). Export is irreversible,
|
|
728
|
+
* so it shows a summary first: the length, the sample rate and channels,
|
|
729
|
+
* which tracks will be heard and which a mute or a solo leaves out, the
|
|
730
|
+
* metadata that will be written, and each format's size. Then a progress
|
|
731
|
+
* bar that can stop the export, and a download button, which gets focus.
|
|
732
|
+
* When the mix went over full scale, it says by how much, and offers to
|
|
733
|
+
* lower the master gain by that and export again.
|
|
734
|
+
*
|
|
735
|
+
* It opens with the Export tool. Whatever closes it, such as Escape or
|
|
736
|
+
* Done, stops its export and resets it, so it reopens fresh; a result that
|
|
737
|
+
* arrives after that is dropped. Unmounting stops the export too. Inside an
|
|
738
|
+
* {@link AudioEditorProvider}.
|
|
739
|
+
*
|
|
740
|
+
* @public
|
|
741
|
+
*/
|
|
742
|
+
export declare function AudioExportDialog(props: AudioExportDialogProps): ReactNode;
|
|
743
|
+
|
|
744
|
+
/**
|
|
745
|
+
* Props of {@link AudioExportDialog}.
|
|
746
|
+
*
|
|
747
|
+
* @public
|
|
748
|
+
*/
|
|
749
|
+
export declare interface AudioExportDialogProps {
|
|
750
|
+
/**
|
|
751
|
+
* Takes the exported file instead of the dialog's download button: the
|
|
752
|
+
* dialog closes once it's called. `result` says how loud the mix was, and
|
|
753
|
+
* how many frames were clamped to full scale.
|
|
754
|
+
*/
|
|
755
|
+
readonly onExport?: (blob: Blob, result: AudioRenderResult) => void;
|
|
756
|
+
/**
|
|
757
|
+
* The downloaded file's name, without its extension, such as
|
|
758
|
+
* `"Interview"`. Without it, the recording's title is used, or else
|
|
759
|
+
* `recording`. It's cleaned as the family cleans a file name (pdf-sdk ADR
|
|
760
|
+
* 0009): the last path segment, without control or bidirectional
|
|
761
|
+
* formatting characters or characters Windows refuses, and at most 128
|
|
762
|
+
* characters. Then an audio extension is dropped, as the export adds its
|
|
763
|
+
* own.
|
|
764
|
+
*/
|
|
765
|
+
readonly fileName?: string;
|
|
766
|
+
readonly className?: string;
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
/**
|
|
770
|
+
* The file an export produces. WAV is the only container so far (ADR 0001).
|
|
771
|
+
*
|
|
772
|
+
* @public
|
|
773
|
+
*/
|
|
774
|
+
declare interface AudioExportFormat {
|
|
775
|
+
readonly container: "wav";
|
|
776
|
+
/** Defaults to `pcm16`. */
|
|
777
|
+
readonly sampleFormat?: AudioSampleFormat_2;
|
|
778
|
+
}
|
|
779
|
+
|
|
780
|
+
/**
|
|
781
|
+
* A fade at one end of a clip. `frames: 0` is no fade.
|
|
782
|
+
*
|
|
783
|
+
* @public
|
|
784
|
+
*/
|
|
785
|
+
declare interface AudioFade {
|
|
786
|
+
readonly frames: number;
|
|
787
|
+
readonly curve: AudioFadeCurve;
|
|
788
|
+
}
|
|
789
|
+
|
|
790
|
+
/**
|
|
791
|
+
* The shape of a fade: `linear` changes the gain at a constant rate, and
|
|
792
|
+
* `equalPower` keeps the perceived loudness steadier, which suits crossfades.
|
|
793
|
+
*
|
|
794
|
+
* @public
|
|
795
|
+
*/
|
|
796
|
+
declare type AudioFadeCurve = "linear" | "equalPower";
|
|
797
|
+
|
|
798
|
+
/**
|
|
799
|
+
* A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
|
|
800
|
+
* the audio SDK's limits. `Infinity` disables a maximum, which removes a
|
|
801
|
+
* protection against hostile files, or disables a warning. Unknown limit
|
|
802
|
+
* names throw `TypeError` when the policy is resolved.
|
|
803
|
+
*
|
|
804
|
+
* @example
|
|
805
|
+
* ```ts
|
|
806
|
+
* // Long recordings: raise the decoded and session sizes together.
|
|
807
|
+
* const filePolicy: AudioFilePolicyOverrides = {
|
|
808
|
+
* maxDecodedSize: 2e9,
|
|
809
|
+
* maxSessionSize: { maximum: 3e9, warning: 1.5e9 },
|
|
810
|
+
* };
|
|
811
|
+
* ```
|
|
812
|
+
*
|
|
813
|
+
* @public
|
|
814
|
+
*/
|
|
815
|
+
declare type AudioFilePolicyOverrides = FilePolicyOverrides<AudioLimitDefinitions>;
|
|
816
|
+
|
|
817
|
+
/**
|
|
818
|
+
* A heading level for the editor's headings, below the page's own `h1`.
|
|
819
|
+
*
|
|
820
|
+
* @public
|
|
821
|
+
*/
|
|
822
|
+
export declare type AudioHeadingLevel = 2 | 3 | 4 | 5 | 6;
|
|
823
|
+
|
|
824
|
+
/**
|
|
825
|
+
* The plan's commands and reducer (docs/adr/0003, docs/adr/0006).
|
|
826
|
+
*
|
|
827
|
+
* Edits are of two kinds. **Clip edits never move another clip:** they fail
|
|
828
|
+
* with `clips-overlap` rather than push a neighbour. **Time edits add or
|
|
829
|
+
* remove time on the tracks they name,** and move everything after it on
|
|
830
|
+
* those tracks.
|
|
831
|
+
*/
|
|
832
|
+
/**
|
|
833
|
+
* Adds clips to a track, each at its own `at`, in free space.
|
|
834
|
+
*
|
|
835
|
+
* @public
|
|
836
|
+
*/
|
|
837
|
+
declare interface AudioInsertClipsCommand {
|
|
838
|
+
readonly type: "audio.insertClips";
|
|
839
|
+
readonly track: string;
|
|
840
|
+
/** The clips, in any order, with keys the plan doesn't have. */
|
|
841
|
+
readonly clips: readonly AudioClip[];
|
|
842
|
+
}
|
|
843
|
+
|
|
844
|
+
/**
|
|
845
|
+
* Options for {@link AudioSession.insert}.
|
|
846
|
+
*
|
|
847
|
+
* @public
|
|
848
|
+
*/
|
|
849
|
+
declare interface AudioInsertOptions extends AudioOpenOptions {
|
|
850
|
+
/**
|
|
851
|
+
* The key of the track the recording goes on, where it needs free space.
|
|
852
|
+
* Without it, the recording gets a new track of its own, below the
|
|
853
|
+
* others: laying one recording under another is the common case.
|
|
854
|
+
*/
|
|
855
|
+
readonly track?: string;
|
|
856
|
+
/** The timeline frame the recording starts on. Defaults to 0. */
|
|
857
|
+
readonly at?: number;
|
|
858
|
+
}
|
|
859
|
+
|
|
860
|
+
/**
|
|
861
|
+
* Opens `frames` of silence at a timeline frame on the named tracks. A clip
|
|
862
|
+
* that lies across the frame is split there, and everything after moves
|
|
863
|
+
* later.
|
|
864
|
+
*
|
|
865
|
+
* @public
|
|
866
|
+
*/
|
|
867
|
+
declare interface AudioInsertTimeCommand {
|
|
868
|
+
readonly type: "audio.insertTime";
|
|
869
|
+
readonly at: number;
|
|
870
|
+
readonly frames: number;
|
|
871
|
+
readonly tracks: readonly string[];
|
|
872
|
+
/**
|
|
873
|
+
* By track key: the key of the second part of a clip the frame splits.
|
|
874
|
+
* `session.execute` gives a key to every track named without one.
|
|
875
|
+
*/
|
|
876
|
+
readonly newKeys?: Readonly<Record<string, string>>;
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
/**
|
|
880
|
+
* The editor's inspector (docs/adr/0005, docs/adr/0006): with a range
|
|
881
|
+
* selected, its gain; otherwise the selected clip's start, gain and fades,
|
|
882
|
+
* set exactly; with neither, the recording's facts, its master gain, its
|
|
883
|
+
* channels and its metadata. Each
|
|
884
|
+
* change is one undo step: a field's when it's committed, with Enter or by
|
|
885
|
+
* leaving it, and a slider's when it's let go. Inside an
|
|
886
|
+
* {@link AudioEditorProvider}.
|
|
887
|
+
*
|
|
888
|
+
* @public
|
|
889
|
+
*/
|
|
890
|
+
export declare function AudioInspector({ className, headingLevel }: AudioInspectorProps): ReactNode;
|
|
891
|
+
|
|
892
|
+
/**
|
|
893
|
+
* Props of {@link AudioInspector}.
|
|
894
|
+
*
|
|
895
|
+
* @public
|
|
896
|
+
*/
|
|
897
|
+
export declare interface AudioInspectorProps {
|
|
898
|
+
readonly className?: string;
|
|
899
|
+
/**
|
|
900
|
+
* The level of the inspector's heading, from 2 to 6, so it fits the
|
|
901
|
+
* host's outline. Defaults to 2.
|
|
902
|
+
*/
|
|
903
|
+
readonly headingLevel?: AudioHeadingLevel;
|
|
904
|
+
}
|
|
905
|
+
|
|
906
|
+
/**
|
|
907
|
+
* Removes everything outside a range, on every track, and moves what's kept to the start.
|
|
908
|
+
*
|
|
909
|
+
* @public
|
|
910
|
+
*/
|
|
911
|
+
declare interface AudioKeepRangeCommand {
|
|
912
|
+
readonly type: "audio.keepRange";
|
|
913
|
+
readonly start: number;
|
|
914
|
+
readonly end: number;
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
/**
|
|
918
|
+
* The type of {@link audioLimitDefinitions}.
|
|
919
|
+
*
|
|
920
|
+
* @public
|
|
921
|
+
*/
|
|
922
|
+
declare type AudioLimitDefinitions = typeof audioLimitDefinitions;
|
|
923
|
+
|
|
924
|
+
/**
|
|
925
|
+
* The audio SDK's limit definitions: sdk-core's core limits with audio
|
|
926
|
+
* defaults, plus six for audio (ADR 0004, docs/adr/0006).
|
|
927
|
+
*
|
|
928
|
+
* | Limit | Code | Default maximum | Default warning |
|
|
929
|
+
* |---|---|---|---|
|
|
930
|
+
* | `maxFileSize` | `FILE_TOO_LARGE` | 1 GB | 250 MB |
|
|
931
|
+
* | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
|
|
932
|
+
* | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
|
|
933
|
+
* | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
|
|
934
|
+
* | `maxDuration` | `DURATION_TOO_LONG` | 3 hours | 1 hour |
|
|
935
|
+
* | `maxChannels` | `TOO_MANY_CHANNELS` | 8 | none |
|
|
936
|
+
* | `maxSampleRate` | `SAMPLE_RATE_TOO_HIGH` | 192 kHz | none |
|
|
937
|
+
* | `maxSessionSize` | `SESSION_TOO_LARGE` | 1.5 GB | 750 MB |
|
|
938
|
+
* | `maxClips` | `TOO_MANY_CLIPS` | 2,000 | none |
|
|
939
|
+
* | `maxTracks` | `TOO_MANY_TRACKS` | 16 | none |
|
|
940
|
+
*
|
|
941
|
+
* Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 32-bit
|
|
942
|
+
* floats: frames × channels × 4 bytes. `maxDuration` is in milliseconds, and
|
|
943
|
+
* `maxSampleRate` is in hertz. `maxDuration` bounds each file, and the plan's
|
|
944
|
+
* length too: positions are free, so no file's limit keeps a clip from being
|
|
945
|
+
* placed hours in. `maxClips` counts the clips of every track together.
|
|
946
|
+
*
|
|
947
|
+
* @public
|
|
948
|
+
*/
|
|
949
|
+
declare const audioLimitDefinitions: {
|
|
950
|
+
readonly maxFileSize: {
|
|
951
|
+
readonly default: 1000000000;
|
|
952
|
+
readonly warning: 250000000;
|
|
953
|
+
readonly code: "FILE_TOO_LARGE";
|
|
954
|
+
readonly unit: "bytes";
|
|
955
|
+
};
|
|
956
|
+
readonly maxDecodedSize: {
|
|
957
|
+
readonly default: 1000000000;
|
|
958
|
+
readonly warning: 400000000;
|
|
959
|
+
readonly code: "DECODED_SIZE_TOO_LARGE";
|
|
960
|
+
readonly unit: "bytes";
|
|
961
|
+
};
|
|
962
|
+
readonly maxDuration: {
|
|
963
|
+
readonly code: "DURATION_TOO_LONG";
|
|
964
|
+
readonly unit: "milliseconds";
|
|
965
|
+
readonly default: number;
|
|
966
|
+
readonly warning: number;
|
|
967
|
+
};
|
|
968
|
+
readonly maxChannels: {
|
|
969
|
+
readonly code: "TOO_MANY_CHANNELS";
|
|
970
|
+
readonly unit: "count";
|
|
971
|
+
readonly default: 8;
|
|
972
|
+
};
|
|
973
|
+
readonly maxSampleRate: {
|
|
974
|
+
readonly code: "SAMPLE_RATE_TOO_HIGH";
|
|
975
|
+
readonly unit: "hertz";
|
|
976
|
+
readonly default: 192000;
|
|
977
|
+
};
|
|
978
|
+
readonly maxSessionSize: {
|
|
979
|
+
readonly code: "SESSION_TOO_LARGE";
|
|
980
|
+
readonly unit: "bytes";
|
|
981
|
+
readonly default: 1500000000;
|
|
982
|
+
readonly warning: 750000000;
|
|
983
|
+
};
|
|
984
|
+
readonly maxClips: {
|
|
985
|
+
readonly code: "TOO_MANY_CLIPS";
|
|
986
|
+
readonly unit: "count";
|
|
987
|
+
readonly default: 2000;
|
|
988
|
+
};
|
|
989
|
+
readonly maxTracks: {
|
|
990
|
+
readonly code: "TOO_MANY_TRACKS";
|
|
991
|
+
readonly unit: "count";
|
|
992
|
+
readonly default: 16;
|
|
993
|
+
};
|
|
994
|
+
readonly maxFiles: {
|
|
995
|
+
readonly code: "TOO_MANY_FILES";
|
|
996
|
+
readonly unit: "count";
|
|
997
|
+
readonly default: 20;
|
|
998
|
+
};
|
|
999
|
+
readonly maxProcessingTime: {
|
|
1000
|
+
readonly code: "PROCESSING_TIME_EXCEEDED";
|
|
1001
|
+
readonly unit: "milliseconds";
|
|
1002
|
+
readonly default: 120000;
|
|
1003
|
+
};
|
|
1004
|
+
};
|
|
1005
|
+
|
|
1006
|
+
/**
|
|
1007
|
+
* The names of the audio SDK's limits.
|
|
1008
|
+
*
|
|
1009
|
+
* @public
|
|
1010
|
+
*/
|
|
1011
|
+
declare type AudioLimitName = keyof AudioLimitDefinitions;
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* A load in progress: an open or an insert, and how far it is.
|
|
1015
|
+
*
|
|
1016
|
+
* @public
|
|
1017
|
+
*/
|
|
1018
|
+
export declare interface AudioLoad {
|
|
1019
|
+
readonly kind: "open" | "insert";
|
|
1020
|
+
/** From 0 to 1. */
|
|
1021
|
+
readonly fraction: number;
|
|
1022
|
+
}
|
|
1023
|
+
|
|
1024
|
+
/**
|
|
1025
|
+
* Metadata that export writes into the file (ADR 0001).
|
|
1026
|
+
*
|
|
1027
|
+
* @public
|
|
1028
|
+
*/
|
|
1029
|
+
declare interface AudioMetadata {
|
|
1030
|
+
readonly title: string;
|
|
1031
|
+
readonly artist: string;
|
|
1032
|
+
readonly album: string;
|
|
1033
|
+
readonly year: string;
|
|
1034
|
+
readonly comment: string;
|
|
1035
|
+
}
|
|
1036
|
+
|
|
1037
|
+
/**
|
|
1038
|
+
* Moves clips by a signed number of frames, and to another track when one is named.
|
|
1039
|
+
*
|
|
1040
|
+
* @public
|
|
1041
|
+
*/
|
|
1042
|
+
declare interface AudioMoveClipsCommand {
|
|
1043
|
+
readonly type: "audio.moveClips";
|
|
1044
|
+
readonly keys: readonly string[];
|
|
1045
|
+
/** Frames to move by: negative is earlier. */
|
|
1046
|
+
readonly by: number;
|
|
1047
|
+
/** The track every clip moves to. Without it, each stays on its own. */
|
|
1048
|
+
readonly track?: string;
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
/**
|
|
1052
|
+
* Moves a track to an index of the resulting plan.
|
|
1053
|
+
*
|
|
1054
|
+
* @public
|
|
1055
|
+
*/
|
|
1056
|
+
declare interface AudioMoveTrackCommand {
|
|
1057
|
+
readonly type: "audio.moveTrack";
|
|
1058
|
+
readonly key: string;
|
|
1059
|
+
readonly to: number;
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* The session's warnings, as one notice above the timeline (docs/adr/0005):
|
|
1064
|
+
* a long recording, a truncated file, a large session, and that the
|
|
1065
|
+
* earliest edits can no longer be undone. Each can be dismissed, and doesn't
|
|
1066
|
+
* come back for the same source. Inside an {@link AudioEditorProvider}.
|
|
1067
|
+
*
|
|
1068
|
+
* @public
|
|
1069
|
+
*/
|
|
1070
|
+
export declare function AudioNotices({ className }: AudioNoticesProps): ReactNode;
|
|
1071
|
+
|
|
1072
|
+
/**
|
|
1073
|
+
* Props of {@link AudioNotices}.
|
|
1074
|
+
*
|
|
1075
|
+
* @public
|
|
1076
|
+
*/
|
|
1077
|
+
export declare interface AudioNoticesProps {
|
|
1078
|
+
readonly className?: string;
|
|
1079
|
+
}
|
|
1080
|
+
|
|
1081
|
+
/**
|
|
1082
|
+
* Options for {@link AudioSession.insert}.
|
|
1083
|
+
*
|
|
1084
|
+
* @public
|
|
1085
|
+
*/
|
|
1086
|
+
declare interface AudioOpenOptions extends AudioProgressOptions {
|
|
1087
|
+
/**
|
|
1088
|
+
* A name for the recording, to show people, such as its file's. It wins
|
|
1089
|
+
* over a `File`'s own name, which is used without it. It's cleaned as
|
|
1090
|
+
* pdf-sdk ADR 0009 decides, and kept on the source in `snapshot.sources`,
|
|
1091
|
+
* never in events, the plan or a document.
|
|
1092
|
+
*/
|
|
1093
|
+
readonly name?: string;
|
|
1094
|
+
}
|
|
1095
|
+
|
|
1096
|
+
/**
|
|
1097
|
+
* The port for playback (ADR 0002, ADR 0003, ADR 0008). Playback is a
|
|
1098
|
+
* function of the plan and the playhead: loading a changed plan or seeking
|
|
1099
|
+
* while playing reschedules from the current position. The SDK's own
|
|
1100
|
+
* adapter plays through Web Audio; tests use a fake with a manual clock.
|
|
1101
|
+
*
|
|
1102
|
+
* Positions are frames on the plan's timeline, from 0 to the plan's length.
|
|
1103
|
+
*
|
|
1104
|
+
* @public
|
|
1105
|
+
*/
|
|
1106
|
+
declare interface AudioOutput {
|
|
1107
|
+
getSnapshot(): AudioOutputSnapshot;
|
|
1108
|
+
/**
|
|
1109
|
+
* Calls the listener after every change of state, and whenever the
|
|
1110
|
+
* playhead jumps, but not as it moves while playing. Returns a function
|
|
1111
|
+
* that unsubscribes. Like every method here, it works detached from the
|
|
1112
|
+
* object.
|
|
1113
|
+
*/
|
|
1114
|
+
subscribe(listener: () => void): () => void;
|
|
1115
|
+
/** The playhead, a whole number of frames, read from the audio clock while playing. */
|
|
1116
|
+
position(): number;
|
|
1117
|
+
/**
|
|
1118
|
+
* Sets what plays: the plan and the decoded sources its clips refer to.
|
|
1119
|
+
* While playing, playback continues from the current position with the
|
|
1120
|
+
* new plan. A playhead past the new plan's end moves to its end.
|
|
1121
|
+
*/
|
|
1122
|
+
load(plan: AudioPlan, sources: ReadonlyMap<string, DecodedAudio>): void;
|
|
1123
|
+
/**
|
|
1124
|
+
* Plays from the playhead, or from the start when the playhead is at the
|
|
1125
|
+
* end. The first call may need a user gesture, as browsers' autoplay rules
|
|
1126
|
+
* require. When playback reaches the end, the state becomes `stopped` and
|
|
1127
|
+
* the playhead stays at the end.
|
|
1128
|
+
*/
|
|
1129
|
+
play(): Promise<void>;
|
|
1130
|
+
/** Pauses, keeping the playhead. */
|
|
1131
|
+
pause(): void;
|
|
1132
|
+
/** Stops, and moves the playhead to the start. */
|
|
1133
|
+
stop(): void;
|
|
1134
|
+
/** Moves the playhead, clamped to the plan. While playing, playback continues from there. */
|
|
1135
|
+
seek(frame: number): void;
|
|
1136
|
+
/** Stops playback and releases the audio device. Later calls throw. */
|
|
1137
|
+
destroy(): Promise<void>;
|
|
1138
|
+
}
|
|
1139
|
+
|
|
1140
|
+
/**
|
|
1141
|
+
* The output's state, for `useSyncExternalStore`. A new object on every
|
|
1142
|
+
* change of state, and whenever the playhead jumps: a seek, a stop, or a
|
|
1143
|
+
* plan that moves it. The playhead isn't in it, because it changes on every
|
|
1144
|
+
* audio frame (ADR 0003); read it with {@link AudioOutput.position}, or
|
|
1145
|
+
* follow it with `watchPlayhead`.
|
|
1146
|
+
*
|
|
1147
|
+
* @public
|
|
1148
|
+
*/
|
|
1149
|
+
declare interface AudioOutputSnapshot {
|
|
1150
|
+
readonly state: AudioOutputState;
|
|
1151
|
+
}
|
|
1152
|
+
|
|
1153
|
+
/**
|
|
1154
|
+
* Whether the output is playing.
|
|
1155
|
+
*
|
|
1156
|
+
* @public
|
|
1157
|
+
*/
|
|
1158
|
+
declare type AudioOutputState = "stopped" | "playing" | "paused";
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* One level of a waveform overview: the lowest and highest sample of each
|
|
1162
|
+
* bucket of frames, per channel.
|
|
1163
|
+
*
|
|
1164
|
+
* @public
|
|
1165
|
+
*/
|
|
1166
|
+
declare interface AudioPeakLevel {
|
|
1167
|
+
/** How many frames each bucket covers. */
|
|
1168
|
+
readonly framesPerBucket: number;
|
|
1169
|
+
/** For each channel, the minimum and maximum sample of each bucket. */
|
|
1170
|
+
readonly channels: readonly {
|
|
1171
|
+
readonly min: Float32Array;
|
|
1172
|
+
readonly max: Float32Array;
|
|
1173
|
+
}[];
|
|
1174
|
+
}
|
|
1175
|
+
|
|
1176
|
+
/**
|
|
1177
|
+
* A source's waveform overview, a min/max pyramid at several zoom levels,
|
|
1178
|
+
* computed once so that drawing the waveform never scans samples (ADR 0002).
|
|
1179
|
+
* Levels are ordered from the finest to the coarsest.
|
|
1180
|
+
*
|
|
1181
|
+
* @public
|
|
1182
|
+
*/
|
|
1183
|
+
declare interface AudioPeaks {
|
|
1184
|
+
readonly levels: readonly AudioPeakLevel[];
|
|
1185
|
+
}
|
|
1186
|
+
|
|
1187
|
+
/**
|
|
1188
|
+
* Puts clips on tracks and positions. Undo's, for a move, and its own inverse.
|
|
1189
|
+
*
|
|
1190
|
+
* @public
|
|
1191
|
+
*/
|
|
1192
|
+
declare interface AudioPlaceClipsCommand {
|
|
1193
|
+
readonly type: "audio.placeClips";
|
|
1194
|
+
readonly entries: readonly {
|
|
1195
|
+
readonly key: string;
|
|
1196
|
+
readonly track: string;
|
|
1197
|
+
readonly at: number;
|
|
1198
|
+
}[];
|
|
1199
|
+
}
|
|
1200
|
+
|
|
1201
|
+
/**
|
|
1202
|
+
* The session's document (docs/adr/0003, docs/adr/0006): tracks of clips
|
|
1203
|
+
* positioned in time, over immutable sources, mixed on playback and export,
|
|
1204
|
+
* with the metadata. Every position and length is a whole number of frames
|
|
1205
|
+
* at `sampleRate`.
|
|
1206
|
+
*
|
|
1207
|
+
* @public
|
|
1208
|
+
*/
|
|
1209
|
+
declare interface AudioPlan {
|
|
1210
|
+
/** The session's sample rate, from its first source. */
|
|
1211
|
+
readonly sampleRate: number;
|
|
1212
|
+
/** The session's channel count: its first source's, raised by a wider one. */
|
|
1213
|
+
readonly channels: number;
|
|
1214
|
+
/** The master gain in decibels, applied to the mix. */
|
|
1215
|
+
readonly gainDb: number;
|
|
1216
|
+
/** From top to bottom. A plan always has at least one. */
|
|
1217
|
+
readonly tracks: readonly AudioTrack[];
|
|
1218
|
+
readonly metadata: AudioMetadata;
|
|
1219
|
+
}
|
|
1220
|
+
|
|
1221
|
+
/**
|
|
1222
|
+
* What the probe learned about a file before anything decodes it (ADR 0001,
|
|
1223
|
+
* ADR 0004). Limits are checked against it.
|
|
1224
|
+
*
|
|
1225
|
+
* @public
|
|
1226
|
+
*/
|
|
1227
|
+
declare interface AudioProbe {
|
|
1228
|
+
readonly container: AudioContainer;
|
|
1229
|
+
readonly codec: AudioCodec;
|
|
1230
|
+
/** The sample rate the decoder will output, which can differ from the header's, as for Opus. */
|
|
1231
|
+
readonly sampleRate: number;
|
|
1232
|
+
/** The channel count the decoder will output, which can differ from the header's. */
|
|
1233
|
+
readonly channels: number;
|
|
1234
|
+
/**
|
|
1235
|
+
* The most frames the decoder can output, at {@link AudioProbe.sampleRate}
|
|
1236
|
+
* and {@link AudioProbe.channels}: the exact length of an uncompressed
|
|
1237
|
+
* file, or the sum over every packet of a compressed one, never a count
|
|
1238
|
+
* declared in a header. A packet that could decode to more channels, or
|
|
1239
|
+
* at a lower rate that's then resampled, counts as the frames that cover
|
|
1240
|
+
* it, so `frameBound × channels × 4` bounds the decoded bytes.
|
|
1241
|
+
*/
|
|
1242
|
+
readonly frameBound: number;
|
|
1243
|
+
/**
|
|
1244
|
+
* The expected length in frames: a header's count when it's within
|
|
1245
|
+
* {@link AudioProbe.frameBound}, otherwise the bound itself.
|
|
1246
|
+
*/
|
|
1247
|
+
readonly expectedFrames: number;
|
|
1248
|
+
/**
|
|
1249
|
+
* For a truncated uncompressed file, as from an interrupted recording or
|
|
1250
|
+
* download, the frames its header declares. The file opens with the
|
|
1251
|
+
* frames it holds, which are fewer; hosts can say that it's incomplete.
|
|
1252
|
+
* Compressed files whose headers claim more than their packets carry fail
|
|
1253
|
+
* instead (docs/adr/0001).
|
|
1254
|
+
*/
|
|
1255
|
+
readonly declaredFrames?: number;
|
|
1256
|
+
/**
|
|
1257
|
+
* How many frames beyond {@link AudioProbe.frameBound} a decoder may
|
|
1258
|
+
* legitimately return, such as one or two codec frames for encoder delay,
|
|
1259
|
+
* priming or pre-skip. A longer result fails with `INVALID_AUDIO`.
|
|
1260
|
+
*/
|
|
1261
|
+
readonly frameTolerance: number;
|
|
1262
|
+
}
|
|
1263
|
+
|
|
1264
|
+
/**
|
|
1265
|
+
* The port for exporting: mix a plan's audible tracks, with their clips'
|
|
1266
|
+
* gain and fades, and encode the result (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
1267
|
+
* adapter renders and encodes in its worker, block by block; hosts can pass
|
|
1268
|
+
* their own to the editor's `processor` prop, and every implementation must
|
|
1269
|
+
* pass the processor's contract tests.
|
|
1270
|
+
*
|
|
1271
|
+
* Failures reject with `AudioError` for cancellation and worker failures,
|
|
1272
|
+
* `TypeError` for a clip whose source isn't in the job, and `RangeError` for
|
|
1273
|
+
* a clip outside its source.
|
|
1274
|
+
*
|
|
1275
|
+
* @public
|
|
1276
|
+
*/
|
|
1277
|
+
declare interface AudioProcessor {
|
|
1278
|
+
/**
|
|
1279
|
+
* Mixes and encodes a plan, up to where its last audible clip ends. Every
|
|
1280
|
+
* sample is clamped to full scale before it's quantised, so a mix above
|
|
1281
|
+
* full scale clips rather than wrapping around, and the result says how
|
|
1282
|
+
* far over it went. The sources aren't modified.
|
|
1283
|
+
*/
|
|
1284
|
+
render(job: AudioRenderJob, options?: AudioProgressOptions): Promise<AudioRenderResult>;
|
|
1285
|
+
/** Releases the processor and its worker. Pending calls reject, and later calls throw. */
|
|
1286
|
+
destroy(): Promise<void>;
|
|
1287
|
+
}
|
|
1288
|
+
|
|
1289
|
+
/**
|
|
1290
|
+
* Options for long calls, which report how far they've got.
|
|
1291
|
+
*
|
|
1292
|
+
* @public
|
|
1293
|
+
*/
|
|
1294
|
+
declare interface AudioProgressOptions extends AudioCallOptions {
|
|
1295
|
+
/**
|
|
1296
|
+
* Called with the fraction done, from 0 to 1. It only moves forward, and
|
|
1297
|
+
* it's called with 1 before the call resolves.
|
|
1298
|
+
*/
|
|
1299
|
+
readonly onProgress?: (fraction: number) => void;
|
|
1300
|
+
}
|
|
1301
|
+
|
|
1302
|
+
/**
|
|
1303
|
+
* What an event says about a recording: its format and size, never its
|
|
1304
|
+
* name or contents.
|
|
1305
|
+
*
|
|
1306
|
+
* @public
|
|
1307
|
+
*/
|
|
1308
|
+
declare interface AudioRecordingFacts {
|
|
1309
|
+
/** Rounded to two significant figures. */
|
|
1310
|
+
readonly durationSeconds: number;
|
|
1311
|
+
readonly sampleRate: number;
|
|
1312
|
+
readonly channels: number;
|
|
1313
|
+
readonly container: AudioSourceInfo["container"];
|
|
1314
|
+
readonly codec: AudioSourceInfo["codec"];
|
|
1315
|
+
readonly truncated: boolean;
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1318
|
+
/**
|
|
1319
|
+
* Removes clips, on any tracks, leaving silence where they were.
|
|
1320
|
+
*
|
|
1321
|
+
* @public
|
|
1322
|
+
*/
|
|
1323
|
+
declare interface AudioRemoveClipsCommand {
|
|
1324
|
+
readonly type: "audio.removeClips";
|
|
1325
|
+
readonly keys: readonly string[];
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/**
|
|
1329
|
+
* Removes tracks, with their clips. A plan keeps at least one track.
|
|
1330
|
+
*
|
|
1331
|
+
* @public
|
|
1332
|
+
*/
|
|
1333
|
+
declare interface AudioRemoveTracksCommand {
|
|
1334
|
+
readonly type: "audio.removeTracks";
|
|
1335
|
+
readonly keys: readonly string[];
|
|
1336
|
+
}
|
|
1337
|
+
|
|
1338
|
+
/**
|
|
1339
|
+
* One export: a plan, the decoded sources its clips refer to, and the
|
|
1340
|
+
* output format. The plan's metadata goes into the file.
|
|
1341
|
+
*
|
|
1342
|
+
* @public
|
|
1343
|
+
*/
|
|
1344
|
+
declare interface AudioRenderJob {
|
|
1345
|
+
readonly plan: AudioPlan;
|
|
1346
|
+
/** The decoded sources, by id. Every clip's source must be here. */
|
|
1347
|
+
readonly sources: ReadonlyMap<string, DecodedAudio>;
|
|
1348
|
+
readonly format: AudioExportFormat;
|
|
1349
|
+
}
|
|
1350
|
+
|
|
1351
|
+
/**
|
|
1352
|
+
* What an export gives: the file, and what clamping did to the mix
|
|
1353
|
+
* (docs/adr/0006). A mix of full-scale tracks goes over full scale; export
|
|
1354
|
+
* clamps it rather than changing levels nobody asked to change, and says so
|
|
1355
|
+
* here, so an editor can offer to lower the master gain.
|
|
1356
|
+
*
|
|
1357
|
+
* @public
|
|
1358
|
+
*/
|
|
1359
|
+
declare interface AudioRenderResult {
|
|
1360
|
+
/** The encoded file. */
|
|
1361
|
+
readonly blob: Blob;
|
|
1362
|
+
/**
|
|
1363
|
+
* The mix's peak before clamping, in decibels relative to full scale:
|
|
1364
|
+
* above 0 means it clipped, by that much. `-Infinity` for silence.
|
|
1365
|
+
*/
|
|
1366
|
+
readonly peakDb: number;
|
|
1367
|
+
/** How many frames had a sample over full scale, which was clamped. */
|
|
1368
|
+
readonly clippedFrames: number;
|
|
1369
|
+
}
|
|
1370
|
+
|
|
1371
|
+
/**
|
|
1372
|
+
* On each named track, replaces a run of neighbouring clips, then moves
|
|
1373
|
+
* every clip after the run by `shift` frames. Undo's, for a split and for
|
|
1374
|
+
* the time edits, and its own inverse: a ripple that moved a thousand clips
|
|
1375
|
+
* is undone by one number.
|
|
1376
|
+
*
|
|
1377
|
+
* @public
|
|
1378
|
+
*/
|
|
1379
|
+
declare interface AudioReplaceClipsCommand {
|
|
1380
|
+
readonly type: "audio.replaceClips";
|
|
1381
|
+
readonly edits: readonly AudioClipsEdit[];
|
|
1382
|
+
}
|
|
1383
|
+
|
|
1384
|
+
/**
|
|
1385
|
+
* Puts removed clips back on their tracks. A clip's `at` says where. Undo's, for a removal.
|
|
1386
|
+
*
|
|
1387
|
+
* @public
|
|
1388
|
+
*/
|
|
1389
|
+
declare interface AudioRestoreClipsCommand {
|
|
1390
|
+
readonly type: "audio.restoreClips";
|
|
1391
|
+
readonly entries: readonly {
|
|
1392
|
+
readonly track: string;
|
|
1393
|
+
readonly clip: AudioClip;
|
|
1394
|
+
}[];
|
|
1395
|
+
}
|
|
1396
|
+
|
|
1397
|
+
/**
|
|
1398
|
+
* Puts removed tracks back at their indexes, with their clips and settings. Undo's.
|
|
1399
|
+
*
|
|
1400
|
+
* @public
|
|
1401
|
+
*/
|
|
1402
|
+
declare interface AudioRestoreTracksCommand {
|
|
1403
|
+
readonly type: "audio.restoreTracks";
|
|
1404
|
+
/** Each track, and the index it takes in the resulting plan, in increasing order. */
|
|
1405
|
+
readonly entries: readonly {
|
|
1406
|
+
readonly index: number;
|
|
1407
|
+
readonly track: AudioTrack;
|
|
1408
|
+
}[];
|
|
1409
|
+
}
|
|
1410
|
+
|
|
1411
|
+
/**
|
|
1412
|
+
* How samples are stored in an exported WAV file (ADR 0001).
|
|
1413
|
+
*
|
|
1414
|
+
* @public
|
|
1415
|
+
*/
|
|
1416
|
+
declare type AudioSampleFormat_2 = "pcm16" | "pcm24" | "float32";
|
|
1417
|
+
|
|
1418
|
+
/**
|
|
1419
|
+
* A selected range of the timeline, on some tracks (docs/adr/0006): frames
|
|
1420
|
+
* from `start` inclusive to `end` exclusive, and the keys of the tracks it
|
|
1421
|
+
* covers, in plan order.
|
|
1422
|
+
*
|
|
1423
|
+
* @public
|
|
1424
|
+
*/
|
|
1425
|
+
declare interface AudioSelection {
|
|
1426
|
+
readonly start: number;
|
|
1427
|
+
readonly end: number;
|
|
1428
|
+
/** The tracks the range covers, at least one. */
|
|
1429
|
+
readonly tracks: readonly string[];
|
|
1430
|
+
}
|
|
1431
|
+
|
|
1432
|
+
/**
|
|
1433
|
+
* The recording being edited, as a framework-agnostic store (ADR 0008,
|
|
1434
|
+
* ADR 0029): a clip plan over decoded sources, edited with commands, with
|
|
1435
|
+
* undo and redo (docs/adr/0003). React binds to it with
|
|
1436
|
+
* `useSyncExternalStore`, and the element binds to the same store.
|
|
1437
|
+
*
|
|
1438
|
+
* @public
|
|
1439
|
+
*/
|
|
1440
|
+
declare interface AudioSession {
|
|
1441
|
+
/** The current snapshot, the same object until something changes. */
|
|
1442
|
+
getSnapshot(): AudioSessionSnapshot;
|
|
1443
|
+
/** Calls the listener after every change. Returns a function that unsubscribes. */
|
|
1444
|
+
subscribe(listener: () => void): () => void;
|
|
1445
|
+
/**
|
|
1446
|
+
* Opens a recording, replacing the current one and its history once it
|
|
1447
|
+
* has opened. The file is checked against the file policy before it's
|
|
1448
|
+
* read, and its probe before it's decoded. Rejects with an `AudioError`,
|
|
1449
|
+
* which the snapshot also holds; the current recording, if any, stays
|
|
1450
|
+
* open.
|
|
1451
|
+
*/
|
|
1452
|
+
open(file: Blob, options?: AudioOpenOptions): Promise<void>;
|
|
1453
|
+
/**
|
|
1454
|
+
* Adds another recording, as one undoable step: on a new track of its
|
|
1455
|
+
* own, below the others, or on the track `options.track` names, where it
|
|
1456
|
+
* needs free space. It starts at `options.at`, or at the start. A
|
|
1457
|
+
* recording at another sample rate is converted to the session's, and its
|
|
1458
|
+
* source says so in `resampledFrom`; one with more channels than the plan
|
|
1459
|
+
* raises the plan's channel count to its own, in the same step. If the
|
|
1460
|
+
* sources held would then exceed `maxSessionSize`, the session first drops
|
|
1461
|
+
* history steps, in sdk-core's `dropOrder`, as far as needed to release
|
|
1462
|
+
* sources only they refer to, and sets `historyTrimmed`. If even that
|
|
1463
|
+
* isn't enough, it rejects with `SESSION_TOO_LARGE` and changes nothing.
|
|
1464
|
+
*/
|
|
1465
|
+
insert(file: Blob, options?: AudioInsertOptions): Promise<void>;
|
|
1466
|
+
/**
|
|
1467
|
+
* Runs one command, or several as one undoable step. A command that
|
|
1468
|
+
* doesn't apply throws `AudioError` with `INVALID_COMMAND`, and one that
|
|
1469
|
+
* would exceed a limit throws its code: `TOO_MANY_CLIPS` for `maxClips`,
|
|
1470
|
+
* `TOO_MANY_TRACKS` for `maxTracks`, and `DURATION_TOO_LONG` when the plan
|
|
1471
|
+
* would become longer than `maxDuration`. Any of them changes
|
|
1472
|
+
* nothing. The commands are copied, so changing them afterwards has no
|
|
1473
|
+
* effect.
|
|
1474
|
+
*/
|
|
1475
|
+
execute(commands: AudioCommand | readonly AudioCommand[]): void;
|
|
1476
|
+
/**
|
|
1477
|
+
* Runs `fn`, and records the commands it executes as one undoable step,
|
|
1478
|
+
* for gestures such as dragging a trim handle.
|
|
1479
|
+
*/
|
|
1480
|
+
group<T>(fn: () => T): T;
|
|
1481
|
+
/**
|
|
1482
|
+
* A key no track or clip has, in the plan or the history, for commands
|
|
1483
|
+
* that create them, such as `newKey` in `audio.splitClip` or `key` in
|
|
1484
|
+
* `audio.addTrack`.
|
|
1485
|
+
*/
|
|
1486
|
+
createKey(): string;
|
|
1487
|
+
undo(): void;
|
|
1488
|
+
redo(): void;
|
|
1489
|
+
/**
|
|
1490
|
+
* Selects a range of the timeline on the tracks named, or on every track
|
|
1491
|
+
* without `tracks`, clamped to the plan, or clears the selection with
|
|
1492
|
+
* `undefined`. An empty range clears it too, as does one that names no
|
|
1493
|
+
* track the plan has.
|
|
1494
|
+
*/
|
|
1495
|
+
select(range: {
|
|
1496
|
+
readonly start: number;
|
|
1497
|
+
readonly end: number;
|
|
1498
|
+
readonly tracks?: readonly string[];
|
|
1499
|
+
} | undefined): void;
|
|
1500
|
+
/** A source's waveform overview, or `undefined` for a source the session doesn't hold. */
|
|
1501
|
+
getPeaks(source: string): AudioPeaks | undefined;
|
|
1502
|
+
/**
|
|
1503
|
+
* A source's decoded audio, for playback, or `undefined` for a source the
|
|
1504
|
+
* session doesn't hold. Don't modify it: sources never change.
|
|
1505
|
+
*/
|
|
1506
|
+
getAudio(source: string): DecodedAudio | undefined;
|
|
1507
|
+
/**
|
|
1508
|
+
* Mixes and encodes the plan's audible tracks as they are now, with the
|
|
1509
|
+
* session's `processor`, under `maxProcessingTime`. It returns the file
|
|
1510
|
+
* with the mix's peak and the frames that clipped, and never downloads
|
|
1511
|
+
* it: the host decides what to do with it. Edits made while it runs don't
|
|
1512
|
+
* change it. Rejects with `INVALID_COMMAND` and the reason `no-recording`,
|
|
1513
|
+
* `empty-plan` or `nothing-audible` when there's nothing to export, and
|
|
1514
|
+
* throws `TypeError` when the session has no processor.
|
|
1515
|
+
*/
|
|
1516
|
+
export(options?: AudioSessionExportOptions): Promise<AudioRenderResult>;
|
|
1517
|
+
/** Closes the recording and releases its sources. */
|
|
1518
|
+
close(): Promise<void>;
|
|
1519
|
+
}
|
|
1520
|
+
|
|
1521
|
+
/**
|
|
1522
|
+
* Anonymous usage events, for a host's analytics (docs/adr/0003). They
|
|
1523
|
+
* never contain file names, samples or metadata values. Durations are in
|
|
1524
|
+
* seconds, rounded to two significant figures, such as 3,500 for 3,456.7,
|
|
1525
|
+
* so that an exact length can't fingerprint a recording.
|
|
1526
|
+
*
|
|
1527
|
+
* @public
|
|
1528
|
+
*/
|
|
1529
|
+
declare type AudioSessionEvent = ({
|
|
1530
|
+
readonly type: "recording_opened" | "recording_inserted";
|
|
1531
|
+
} & AudioRecordingFacts) | {
|
|
1532
|
+
readonly type: "recording_exported";
|
|
1533
|
+
readonly durationSeconds: number;
|
|
1534
|
+
readonly sampleRate: number;
|
|
1535
|
+
readonly channels: number;
|
|
1536
|
+
readonly sampleFormat: AudioSampleFormat_2;
|
|
1537
|
+
} | {
|
|
1538
|
+
readonly type: "recording_closed";
|
|
1539
|
+
} | {
|
|
1540
|
+
readonly type: "command";
|
|
1541
|
+
readonly commands: readonly AudioCommand["type"][];
|
|
1542
|
+
} | {
|
|
1543
|
+
readonly type: "undo";
|
|
1544
|
+
} | {
|
|
1545
|
+
readonly type: "redo";
|
|
1546
|
+
} | {
|
|
1547
|
+
readonly type: "failed";
|
|
1548
|
+
readonly operation: "open" | "insert" | "command" | "export";
|
|
1549
|
+
readonly code: string;
|
|
1550
|
+
};
|
|
1551
|
+
|
|
1552
|
+
/**
|
|
1553
|
+
* Options for {@link AudioSession.export}.
|
|
1554
|
+
*
|
|
1555
|
+
* @public
|
|
1556
|
+
*/
|
|
1557
|
+
declare interface AudioSessionExportOptions extends AudioProgressOptions {
|
|
1558
|
+
/** The file to write. Defaults to 16-bit PCM WAV. */
|
|
1559
|
+
readonly format?: AudioExportFormat;
|
|
1560
|
+
}
|
|
1561
|
+
|
|
1562
|
+
/**
|
|
1563
|
+
* The session's state at one moment (docs/adr/0003). Snapshots are
|
|
1564
|
+
* immutable: every change makes a new one, so `useSyncExternalStore` and
|
|
1565
|
+
* other subscribers can compare them by identity. The playhead isn't here:
|
|
1566
|
+
* it belongs to `AudioOutput`, which moves it sixty times a second.
|
|
1567
|
+
*
|
|
1568
|
+
* @public
|
|
1569
|
+
*/
|
|
1570
|
+
declare interface AudioSessionSnapshot {
|
|
1571
|
+
readonly status: AudioSessionStatus;
|
|
1572
|
+
/** The recording being edited, or `undefined` when none is open. */
|
|
1573
|
+
readonly plan: AudioPlan | undefined;
|
|
1574
|
+
/** The sources the session holds: those the plan uses, and those undo or redo can bring back. */
|
|
1575
|
+
readonly sources: readonly AudioSourceInfo[];
|
|
1576
|
+
readonly canUndo: boolean;
|
|
1577
|
+
readonly canRedo: boolean;
|
|
1578
|
+
/**
|
|
1579
|
+
* Whether undo steps were dropped since the recording opened, to make
|
|
1580
|
+
* room for an insert within `maxSessionSize`. Editors say so, because the
|
|
1581
|
+
* earliest edits can no longer be undone (ADR 0010).
|
|
1582
|
+
*/
|
|
1583
|
+
readonly historyTrimmed: boolean;
|
|
1584
|
+
/** Whether a recording is being opened or inserted. */
|
|
1585
|
+
readonly busy: boolean;
|
|
1586
|
+
/** Why the last open or insert failed. Show its text by its code. */
|
|
1587
|
+
readonly error: AudioError | undefined;
|
|
1588
|
+
readonly warnings: readonly AudioWarning[];
|
|
1589
|
+
/**
|
|
1590
|
+
* The decoded bytes of every source the session holds, which the
|
|
1591
|
+
* `maxSessionSize` limit counts: frames × channels × 4.
|
|
1592
|
+
*/
|
|
1593
|
+
readonly sessionBytes: number;
|
|
1594
|
+
/** The selected range of the timeline. View state: not undoable, and never in events. */
|
|
1595
|
+
readonly selection: AudioSelection | undefined;
|
|
1596
|
+
}
|
|
1597
|
+
|
|
1598
|
+
/**
|
|
1599
|
+
* What the session is doing.
|
|
1600
|
+
*
|
|
1601
|
+
* - `empty`: no recording is open.
|
|
1602
|
+
* - `opening`: a recording is being opened, replacing any other.
|
|
1603
|
+
* - `ready`: a recording is open.
|
|
1604
|
+
* - `error`: no recording is open, because the last open failed; `error`
|
|
1605
|
+
* says why. A failed open while a recording is open keeps it, with the
|
|
1606
|
+
* status `ready` and `error` set.
|
|
1607
|
+
*
|
|
1608
|
+
* @public
|
|
1609
|
+
*/
|
|
1610
|
+
declare type AudioSessionStatus = "empty" | "opening" | "ready" | "error";
|
|
1611
|
+
|
|
1612
|
+
/**
|
|
1613
|
+
* Sets the plan's channel count.
|
|
1614
|
+
*
|
|
1615
|
+
* @public
|
|
1616
|
+
*/
|
|
1617
|
+
declare interface AudioSetChannelsCommand {
|
|
1618
|
+
readonly type: "audio.setChannels";
|
|
1619
|
+
readonly channels: number;
|
|
1620
|
+
}
|
|
1621
|
+
|
|
1622
|
+
/**
|
|
1623
|
+
* Sets a clip's fade in or fade out. Together, the two must fit in the clip.
|
|
1624
|
+
*
|
|
1625
|
+
* @public
|
|
1626
|
+
*/
|
|
1627
|
+
declare interface AudioSetFadeCommand {
|
|
1628
|
+
readonly type: "audio.setFade";
|
|
1629
|
+
readonly key: string;
|
|
1630
|
+
readonly edge: "in" | "out";
|
|
1631
|
+
readonly frames: number;
|
|
1632
|
+
readonly curve: AudioFadeCurve;
|
|
1633
|
+
}
|
|
1634
|
+
|
|
1635
|
+
/**
|
|
1636
|
+
* Sets the gain of clips.
|
|
1637
|
+
*
|
|
1638
|
+
* @public
|
|
1639
|
+
*/
|
|
1640
|
+
declare interface AudioSetGainCommand {
|
|
1641
|
+
readonly type: "audio.setGain";
|
|
1642
|
+
readonly keys: readonly string[];
|
|
1643
|
+
readonly gainDb: number;
|
|
1644
|
+
}
|
|
1645
|
+
|
|
1646
|
+
/**
|
|
1647
|
+
* Sets the master gain.
|
|
1648
|
+
*
|
|
1649
|
+
* @public
|
|
1650
|
+
*/
|
|
1651
|
+
declare interface AudioSetMasterGainCommand {
|
|
1652
|
+
readonly type: "audio.setMasterGain";
|
|
1653
|
+
readonly gainDb: number;
|
|
1654
|
+
}
|
|
1655
|
+
|
|
1656
|
+
/**
|
|
1657
|
+
* Sets one metadata field.
|
|
1658
|
+
*
|
|
1659
|
+
* @public
|
|
1660
|
+
*/
|
|
1661
|
+
declare interface AudioSetMetadataCommand {
|
|
1662
|
+
readonly type: "audio.setMetadata";
|
|
1663
|
+
readonly field: keyof AudioMetadata;
|
|
1664
|
+
readonly value: string;
|
|
1665
|
+
}
|
|
1666
|
+
|
|
1667
|
+
/**
|
|
1668
|
+
* Sets the fields given of a track, at least one.
|
|
1669
|
+
*
|
|
1670
|
+
* @public
|
|
1671
|
+
*/
|
|
1672
|
+
declare interface AudioSetTrackCommand {
|
|
1673
|
+
readonly type: "audio.setTrack";
|
|
1674
|
+
readonly key: string;
|
|
1675
|
+
readonly name?: string;
|
|
1676
|
+
readonly gainDb?: number;
|
|
1677
|
+
readonly muted?: boolean;
|
|
1678
|
+
readonly soloed?: boolean;
|
|
1679
|
+
}
|
|
1680
|
+
|
|
1681
|
+
/**
|
|
1682
|
+
* A source the session holds, without its samples: what the snapshot shows
|
|
1683
|
+
* (ADR 0003).
|
|
1684
|
+
*
|
|
1685
|
+
* @public
|
|
1686
|
+
*/
|
|
1687
|
+
declare interface AudioSourceInfo {
|
|
1688
|
+
/** Unique within the session, and never reused, even after the source is released. */
|
|
1689
|
+
readonly id: string;
|
|
1690
|
+
readonly sampleRate: number;
|
|
1691
|
+
readonly channels: number;
|
|
1692
|
+
/** The length in frames: the decoded length, capped at the probe's bound (ADR 0004). */
|
|
1693
|
+
readonly frames: number;
|
|
1694
|
+
readonly container: AudioContainer;
|
|
1695
|
+
readonly codec: AudioCodec;
|
|
1696
|
+
/**
|
|
1697
|
+
* The file's own sample rate, in hertz, when the source was converted to
|
|
1698
|
+
* the session's as it was inserted (docs/adr/0006). `sampleRate` and
|
|
1699
|
+
* `frames` describe the converted audio.
|
|
1700
|
+
*/
|
|
1701
|
+
readonly resampledFrom?: number;
|
|
1702
|
+
/**
|
|
1703
|
+
* The name the host gave the recording, or its file's name, to show
|
|
1704
|
+
* people, cleaned as pdf-sdk ADR 0009 decides: its last path segment, with
|
|
1705
|
+
* no control or bidirectional formatting characters, none that Windows
|
|
1706
|
+
* refuses, no leading dots or surrounding space, in NFC, and at most
|
|
1707
|
+
* {@link MAX_SOURCE_NAME_LENGTH} code points. It's never in events, the
|
|
1708
|
+
* plan or a document. Show it as text, never as HTML.
|
|
1709
|
+
*/
|
|
1710
|
+
readonly name?: string;
|
|
1711
|
+
}
|
|
1712
|
+
|
|
1713
|
+
/**
|
|
1714
|
+
* Splits a clip in two at a timeline frame strictly inside it. The first
|
|
1715
|
+
* part keeps the key and the fade in; the second takes `newKey` and the
|
|
1716
|
+
* fade out.
|
|
1717
|
+
*
|
|
1718
|
+
* @public
|
|
1719
|
+
*/
|
|
1720
|
+
declare interface AudioSplitClipCommand {
|
|
1721
|
+
readonly type: "audio.splitClip";
|
|
1722
|
+
readonly key: string;
|
|
1723
|
+
readonly at: number;
|
|
1724
|
+
/**
|
|
1725
|
+
* The second part's key. `session.execute` gives one from
|
|
1726
|
+
* `session.createKey()` when it's left out; a stored command, and the
|
|
1727
|
+
* format, always carry it.
|
|
1728
|
+
*/
|
|
1729
|
+
readonly newKey?: string;
|
|
1730
|
+
}
|
|
1731
|
+
|
|
1732
|
+
/**
|
|
1733
|
+
* The editor's stage (docs/adr/0005): the empty state, a drop zone with a
|
|
1734
|
+
* button to choose a file, so dropping is never the only way; an open or an
|
|
1735
|
+
* insert in progress, with a Cancel button; a failed one, by its error's
|
|
1736
|
+
* text; and, once a recording is open, a line saying how many tracks and
|
|
1737
|
+
* how long, and the timeline. Inside an
|
|
1738
|
+
* {@link AudioEditorProvider}.
|
|
1739
|
+
*
|
|
1740
|
+
* @public
|
|
1741
|
+
*/
|
|
1742
|
+
export declare function AudioStage({ className }: AudioStageProps): ReactNode;
|
|
1743
|
+
|
|
1744
|
+
/**
|
|
1745
|
+
* Props of {@link AudioStage}.
|
|
1746
|
+
*
|
|
1747
|
+
* @public
|
|
1748
|
+
*/
|
|
1749
|
+
export declare interface AudioStageProps {
|
|
1750
|
+
readonly className?: string;
|
|
1751
|
+
}
|
|
1752
|
+
|
|
1753
|
+
/**
|
|
1754
|
+
* The editor's timeline (docs/adr/0006), on `ui`'s `Timeline`: one lane per
|
|
1755
|
+
* track, with its name in a header that stays in view, its waveform drawn
|
|
1756
|
+
* from the peaks, and its clips where they sit in time; the playhead as a
|
|
1757
|
+
* slider over all of them, in 10 ms steps and seconds with Page Up and Page
|
|
1758
|
+
* Down. Its zoom is the editor's, which the toolbar's zoom tools change.
|
|
1759
|
+
* Inside an {@link AudioEditorProvider}.
|
|
1760
|
+
*
|
|
1761
|
+
* @public
|
|
1762
|
+
*/
|
|
1763
|
+
export declare function AudioTimeline({ className }: AudioTimelineProps): ReactNode;
|
|
1764
|
+
|
|
1765
|
+
/**
|
|
1766
|
+
* Props of {@link AudioTimeline}.
|
|
1767
|
+
*
|
|
1768
|
+
* @public
|
|
1769
|
+
*/
|
|
1770
|
+
export declare interface AudioTimelineProps {
|
|
1771
|
+
readonly className?: string;
|
|
1772
|
+
}
|
|
1773
|
+
|
|
1774
|
+
/**
|
|
1775
|
+
* The editor's toolbar (docs/adr/0005): a `ui` Toolbar of the present
|
|
1776
|
+
* tools, in the groups the `toolbar` prop sets. Each button has the tool's
|
|
1777
|
+
* label, its shortcuts as `aria-keyshortcuts`, and a tooltip with the keys.
|
|
1778
|
+
* A tool that can't run now stays in the keyboard order, with
|
|
1779
|
+
* `aria-disabled`. Inside an {@link AudioEditorProvider}.
|
|
1780
|
+
*
|
|
1781
|
+
* @public
|
|
1782
|
+
*/
|
|
1783
|
+
export declare function AudioToolbar({ className }: AudioToolbarProps): ReactNode;
|
|
1784
|
+
|
|
1785
|
+
/**
|
|
1786
|
+
* Props of {@link AudioToolbar}.
|
|
1787
|
+
*
|
|
1788
|
+
* @public
|
|
1789
|
+
*/
|
|
1790
|
+
export declare interface AudioToolbarProps {
|
|
1791
|
+
readonly className?: string;
|
|
1792
|
+
}
|
|
1793
|
+
|
|
1794
|
+
/**
|
|
1795
|
+
* One track: clips in time order that never overlap, with the track's
|
|
1796
|
+
* name, gain, mute and solo (docs/adr/0006).
|
|
1797
|
+
*
|
|
1798
|
+
* @public
|
|
1799
|
+
*/
|
|
1800
|
+
declare interface AudioTrack {
|
|
1801
|
+
/** Stable across edits. Tracks and clips share one namespace of keys. */
|
|
1802
|
+
readonly key: string;
|
|
1803
|
+
/**
|
|
1804
|
+
* The name people gave it, at most {@link MAX_TRACK_NAME_LENGTH} code
|
|
1805
|
+
* points. Empty means none, and an editor shows "Track 2". It's
|
|
1806
|
+
* untrusted text: render it as text, never as HTML.
|
|
1807
|
+
*/
|
|
1808
|
+
readonly name: string;
|
|
1809
|
+
/** The track's gain in decibels. */
|
|
1810
|
+
readonly gainDb: number;
|
|
1811
|
+
readonly muted: boolean;
|
|
1812
|
+
readonly soloed: boolean;
|
|
1813
|
+
/** Sorted by `at`, each ending at or before the next one starts. */
|
|
1814
|
+
readonly clips: readonly AudioClip[];
|
|
1815
|
+
}
|
|
1816
|
+
|
|
1817
|
+
/**
|
|
1818
|
+
* The editor's transport (docs/adr/0005): play and pause, back to the
|
|
1819
|
+
* start, and the time as `0:12.40 / 1:05.00`. When the browser won't start
|
|
1820
|
+
* sound, as under an autoplay rule, it says that sound needs a press of
|
|
1821
|
+
* Play, next to the button. Inside an {@link AudioEditorProvider}.
|
|
1822
|
+
*
|
|
1823
|
+
* @public
|
|
1824
|
+
*/
|
|
1825
|
+
export declare function AudioTransport({ className }: AudioTransportProps): ReactNode;
|
|
1826
|
+
|
|
1827
|
+
/**
|
|
1828
|
+
* Props of {@link AudioTransport}.
|
|
1829
|
+
*
|
|
1830
|
+
* @public
|
|
1831
|
+
*/
|
|
1832
|
+
export declare interface AudioTransportProps {
|
|
1833
|
+
readonly className?: string;
|
|
1834
|
+
}
|
|
1835
|
+
|
|
1836
|
+
/**
|
|
1837
|
+
* Changes the range of its source a clip plays. The audio stays where it is
|
|
1838
|
+
* on the timeline: moving `start` moves the clip's `at` by the same amount.
|
|
1839
|
+
* Fades that no longer fit are shortened in proportion.
|
|
1840
|
+
*
|
|
1841
|
+
* @public
|
|
1842
|
+
*/
|
|
1843
|
+
declare interface AudioTrimClipCommand {
|
|
1844
|
+
readonly type: "audio.trimClip";
|
|
1845
|
+
readonly key: string;
|
|
1846
|
+
readonly start: number;
|
|
1847
|
+
readonly end: number;
|
|
1848
|
+
}
|
|
1849
|
+
|
|
1850
|
+
/**
|
|
1851
|
+
* Sets clips, matched by key, to states with every field given. Undo's, for a trim, a gain or a fade.
|
|
1852
|
+
*
|
|
1853
|
+
* @public
|
|
1854
|
+
*/
|
|
1855
|
+
declare interface AudioUpdateClipsCommand {
|
|
1856
|
+
readonly type: "audio.updateClips";
|
|
1857
|
+
readonly clips: readonly AudioClip[];
|
|
1858
|
+
}
|
|
1859
|
+
|
|
1860
|
+
/**
|
|
1861
|
+
* The edits a user makes: `hm-audio-command` version 2
|
|
1862
|
+
* (docs/formats/hm-audio-plan.md).
|
|
1863
|
+
*
|
|
1864
|
+
* @public
|
|
1865
|
+
*/
|
|
1866
|
+
declare type AudioUserCommand = AudioInsertClipsCommand | AudioRemoveClipsCommand | AudioTrimClipCommand | AudioSplitClipCommand | AudioMoveClipsCommand | AudioSetGainCommand | AudioSetFadeCommand | AudioDeleteRangeCommand | AudioKeepRangeCommand | AudioInsertTimeCommand | AudioAddTrackCommand | AudioRemoveTracksCommand | AudioMoveTrackCommand | AudioSetTrackCommand | AudioSetMasterGainCommand | AudioSetChannelsCommand | AudioSetMetadataCommand;
|
|
1867
|
+
|
|
1868
|
+
/**
|
|
1869
|
+
* Something the user should know about the recordings open, though they
|
|
1870
|
+
* opened (docs/adr/0004). Show its text from `warnings.<limit>`, or from
|
|
1871
|
+
* `warnings.truncated`, in the message catalogue, with its fields as
|
|
1872
|
+
* parameters.
|
|
1873
|
+
*
|
|
1874
|
+
* - `limit`: a value at or above a limit's warning threshold, but within its
|
|
1875
|
+
* maximum. `source` names the recording it's about, unless it's about the
|
|
1876
|
+
* whole session, as `maxSessionSize` and `maxClips` are.
|
|
1877
|
+
* - `truncated`: an uncompressed recording holds fewer frames than its
|
|
1878
|
+
* header declares, as after an interrupted recording or download. It
|
|
1879
|
+
* opened with the frames it holds.
|
|
1880
|
+
*
|
|
1881
|
+
* @public
|
|
1882
|
+
*/
|
|
1883
|
+
declare type AudioWarning = {
|
|
1884
|
+
readonly type: "limit";
|
|
1885
|
+
readonly limit: AudioLimitName;
|
|
1886
|
+
readonly actual: number;
|
|
1887
|
+
readonly source?: string;
|
|
1888
|
+
} | {
|
|
1889
|
+
readonly type: "truncated";
|
|
1890
|
+
readonly source: string;
|
|
1891
|
+
/** The frames the recording holds. */
|
|
1892
|
+
readonly frames: number;
|
|
1893
|
+
/** The frames its header declares. */
|
|
1894
|
+
readonly declaredFrames: number;
|
|
1895
|
+
};
|
|
1896
|
+
|
|
1897
|
+
/**
|
|
1898
|
+
* Decoded audio, as 32-bit float samples per channel. A Web Audio
|
|
1899
|
+
* `AudioBuffer` is one, and tests can supply their own.
|
|
1900
|
+
*
|
|
1901
|
+
* @public
|
|
1902
|
+
*/
|
|
1903
|
+
declare interface DecodedAudio {
|
|
1904
|
+
readonly sampleRate: number;
|
|
1905
|
+
/** The length in frames. */
|
|
1906
|
+
readonly length: number;
|
|
1907
|
+
readonly numberOfChannels: number;
|
|
1908
|
+
/** The samples of one channel. The caller must not modify them. */
|
|
1909
|
+
getChannelData(channel: number): Float32Array;
|
|
1910
|
+
}
|
|
1911
|
+
|
|
1912
|
+
/**
|
|
1913
|
+
* The editor's text: the SDK's catalogue with `ui`'s and the host's
|
|
1914
|
+
* overrides. Inside an {@link AudioEditorProvider}.
|
|
1915
|
+
*
|
|
1916
|
+
* @public
|
|
1917
|
+
*/
|
|
1918
|
+
export declare function useAudioMessages(): AudioEditorMessages;
|
|
1919
|
+
|
|
1920
|
+
/**
|
|
1921
|
+
* The editor's playback output, and its snapshot: whether it's stopped,
|
|
1922
|
+
* playing or paused. Inside an {@link AudioEditorProvider}.
|
|
1923
|
+
*
|
|
1924
|
+
* @public
|
|
1925
|
+
*/
|
|
1926
|
+
export declare function useAudioOutput(): UseAudioOutputResult;
|
|
1927
|
+
|
|
1928
|
+
/**
|
|
1929
|
+
* What {@link useAudioOutput} gives.
|
|
1930
|
+
*
|
|
1931
|
+
* @public
|
|
1932
|
+
*/
|
|
1933
|
+
export declare interface UseAudioOutputResult {
|
|
1934
|
+
readonly output: AudioOutput;
|
|
1935
|
+
readonly snapshot: AudioOutputSnapshot;
|
|
1936
|
+
}
|
|
1937
|
+
|
|
1938
|
+
/**
|
|
1939
|
+
* The playhead, in whole frames, through `watchPlayhead`: it re-renders the
|
|
1940
|
+
* component on animation frames while playing, and when the playhead jumps,
|
|
1941
|
+
* so only components that show the time pay for it. Inside an
|
|
1942
|
+
* {@link AudioEditorProvider}.
|
|
1943
|
+
*
|
|
1944
|
+
* @public
|
|
1945
|
+
*/
|
|
1946
|
+
export declare function useAudioPlayhead(): number;
|
|
1947
|
+
|
|
1948
|
+
/**
|
|
1949
|
+
* The editor's session, and its snapshot, which re-renders the component on
|
|
1950
|
+
* every change. Inside an {@link AudioEditorProvider}.
|
|
1951
|
+
*
|
|
1952
|
+
* @public
|
|
1953
|
+
*/
|
|
1954
|
+
export declare function useAudioSession(): UseAudioSessionResult;
|
|
1955
|
+
|
|
1956
|
+
/**
|
|
1957
|
+
* What {@link useAudioSession} gives.
|
|
1958
|
+
*
|
|
1959
|
+
* @public
|
|
1960
|
+
*/
|
|
1961
|
+
export declare interface UseAudioSessionResult {
|
|
1962
|
+
readonly session: AudioSession;
|
|
1963
|
+
readonly snapshot: AudioSessionSnapshot;
|
|
1964
|
+
}
|
|
1965
|
+
|
|
12
1966
|
export { }
|