@hussmartinez/audio-sdk 0.4.0 → 0.6.0

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