@hussmartinez/audio-sdk 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/assets/audio/audio.worker.js +1 -1
- package/dist/index.d.ts +401 -6
- package/dist/index.js +1085 -79
- package/dist/index.js.map +1 -1
- package/dist/lazy/inline-worker-CkUV_wKW.js +30 -0
- package/dist/lazy/{inline-worker-CexEKodJ.js.map → inline-worker-CkUV_wKW.js.map} +1 -1
- package/package.json +8 -5
- package/dist/lazy/inline-worker-CexEKodJ.js +0 -30
package/dist/index.d.ts
CHANGED
|
@@ -15,6 +15,36 @@ import { Limits } from '@hussmartinez/sdk-core';
|
|
|
15
15
|
import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
|
|
16
16
|
import { SdkError } from '@hussmartinez/sdk-core';
|
|
17
17
|
|
|
18
|
+
/**
|
|
19
|
+
* The name of the clip plan's portable format (sdk-core ADR 0045).
|
|
20
|
+
*
|
|
21
|
+
* @public
|
|
22
|
+
*/
|
|
23
|
+
export declare const AUDIO_PLAN_FORMAT = "hm-audio-plan";
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* The version of {@link AUDIO_PLAN_FORMAT} this release writes, and the
|
|
27
|
+
* latest it reads.
|
|
28
|
+
*
|
|
29
|
+
* @public
|
|
30
|
+
*/
|
|
31
|
+
export declare const AUDIO_PLAN_VERSION = 1;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A content-addressed reference to binary data, such as a source's file
|
|
35
|
+
* (sdk-core ADR 0045). Documents never inline bytes.
|
|
36
|
+
*
|
|
37
|
+
* @public
|
|
38
|
+
*/
|
|
39
|
+
export declare interface AudioAssetReference {
|
|
40
|
+
/** `sha256:` and the lowercase hex SHA-256 of the bytes. */
|
|
41
|
+
readonly asset: string;
|
|
42
|
+
/** The bytes' media type, such as `audio/wav`, in lowercase. */
|
|
43
|
+
readonly mediaType: string;
|
|
44
|
+
/** The size of the bytes. */
|
|
45
|
+
readonly size: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
18
48
|
/**
|
|
19
49
|
* Options every port call accepts.
|
|
20
50
|
*
|
|
@@ -49,6 +79,22 @@ export declare interface AudioClip {
|
|
|
49
79
|
readonly fadeOut: AudioFade;
|
|
50
80
|
}
|
|
51
81
|
|
|
82
|
+
/**
|
|
83
|
+
* Why a clip isn't valid within its source, as a stable token: a value of
|
|
84
|
+
* `details.reason` on `INVALID_COMMAND` (sdk-core ADR 0045).
|
|
85
|
+
*
|
|
86
|
+
* - `invalid-frames`: a position or fade length isn't a non-negative whole
|
|
87
|
+
* number of frames.
|
|
88
|
+
* - `clip-too-short`: the clip is shorter than one frame.
|
|
89
|
+
* - `clip-outside-source`: it ends after its source's last frame.
|
|
90
|
+
* - `gain-out-of-range`: the gain isn't a finite number from
|
|
91
|
+
* {@link MIN_GAIN_DB} to {@link MAX_GAIN_DB}.
|
|
92
|
+
* - `fades-too-long`: its fades together are longer than the clip.
|
|
93
|
+
*
|
|
94
|
+
* @public
|
|
95
|
+
*/
|
|
96
|
+
export declare type AudioClipProblem = "invalid-frames" | "clip-too-short" | "clip-outside-source" | "gain-out-of-range" | "fades-too-long";
|
|
97
|
+
|
|
52
98
|
/**
|
|
53
99
|
* The codecs the probe recognises (ADR 0001). `pcm` covers integer and
|
|
54
100
|
* floating-point samples in WAV and AIFF.
|
|
@@ -66,6 +112,41 @@ export declare type AudioCodec = "pcm" | "mp3" | "aac" | "alac" | "opus" | "vorb
|
|
|
66
112
|
*/
|
|
67
113
|
export declare type AudioCommand = AudioInsertClipsCommand | AudioRemoveClipsCommand | AudioRestoreClipsCommand | AudioReplaceClipsCommand | AudioUpdateClipsCommand | AudioDeleteRangeCommand | AudioTrimClipCommand | AudioSplitClipCommand | AudioMoveClipsCommand | AudioReorderClipsCommand | AudioSetGainCommand | AudioSetFadeCommand | AudioSetMetadataCommand;
|
|
68
114
|
|
|
115
|
+
/**
|
|
116
|
+
* Why the reducer refused a command, as a stable token: `details.reason` on
|
|
117
|
+
* `INVALID_COMMAND`, which hosts and conformance vectors compare instead of
|
|
118
|
+
* the message (sdk-core ADR 0045). Tokens never change meaning once
|
|
119
|
+
* released.
|
|
120
|
+
*
|
|
121
|
+
* - The clip's own problems, {@link AudioClipProblem}.
|
|
122
|
+
* - `malformed-command`: the command isn't shaped as its type says, such as
|
|
123
|
+
* a list that isn't one, or a clip without a key or source.
|
|
124
|
+
* - `unknown-command`: its `type` isn't one of {@link AudioCommand}'s.
|
|
125
|
+
* - `unknown-source`: a clip names a source the session doesn't hold.
|
|
126
|
+
* - `invalid-fade-curve`: a fade's curve isn't `linear` or `equalPower`.
|
|
127
|
+
* - `no-clips`: the command needs at least one clip, and names none.
|
|
128
|
+
* - `duplicate-key`: it names a clip twice, or gives two new clips one key.
|
|
129
|
+
* - `key-taken`: a new clip's key is already in the plan.
|
|
130
|
+
* - `unknown-clip`: it names a clip the plan doesn't have.
|
|
131
|
+
* - `frame-outside-plan`: a timeline frame is outside the plan.
|
|
132
|
+
* - `empty-range`: a range is shorter than one frame.
|
|
133
|
+
* - `not-inside-clip`: a split frame isn't strictly inside its clip.
|
|
134
|
+
* - `new-key-required`: it cuts a clip in two without the new part's key.
|
|
135
|
+
* - `invalid-index`: an index or a run of clips is outside the plan.
|
|
136
|
+
* - `empty-change`: it would change nothing at all.
|
|
137
|
+
* - `invalid-order`: a new order doesn't list every clip exactly once.
|
|
138
|
+
* - `invalid-edge`: a fade's edge isn't `in` or `out`.
|
|
139
|
+
* - `unknown-metadata-field`: the metadata has no such field.
|
|
140
|
+
* - `metadata-too-long`: a metadata value is over {@link MAX_METADATA_LENGTH}
|
|
141
|
+
* characters.
|
|
142
|
+
*
|
|
143
|
+
* The session adds `no-recording`, for a command with no recording open,
|
|
144
|
+
* and `not-plain-data`, for a command that can't be cloned.
|
|
145
|
+
*
|
|
146
|
+
* @public
|
|
147
|
+
*/
|
|
148
|
+
export declare type AudioCommandRejection = AudioClipProblem | "malformed-command" | "unknown-command" | "unknown-source" | "invalid-fade-curve" | "no-clips" | "duplicate-key" | "key-taken" | "unknown-clip" | "frame-outside-plan" | "empty-range" | "not-inside-clip" | "new-key-required" | "invalid-index" | "empty-change" | "invalid-order" | "invalid-edge" | "unknown-metadata-field" | "metadata-too-long" | "no-recording" | "not-plain-data";
|
|
149
|
+
|
|
69
150
|
/**
|
|
70
151
|
* The containers the probe recognises (ADR 0001).
|
|
71
152
|
*
|
|
@@ -90,6 +171,23 @@ export declare interface AudioDeleteRangeCommand {
|
|
|
90
171
|
readonly newKey?: string;
|
|
91
172
|
}
|
|
92
173
|
|
|
174
|
+
/**
|
|
175
|
+
* Why a plan document was refused, as a stable token: `details.reason` on
|
|
176
|
+
* the error (sdk-core ADR 0045).
|
|
177
|
+
*
|
|
178
|
+
* - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
|
|
179
|
+
* format, and `unknown-format-version`, a later version than this release
|
|
180
|
+
* reads.
|
|
181
|
+
* - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
|
|
182
|
+
* shaped as the schema says; `unknown-source`, a clip whose source the
|
|
183
|
+
* document doesn't list; `duplicate-key`, two clips with one key;
|
|
184
|
+
* `invalid-fade-curve` and `metadata-too-long`, as for commands; and a
|
|
185
|
+
* clip's own problems, {@link AudioClipProblem}.
|
|
186
|
+
*
|
|
187
|
+
* @public
|
|
188
|
+
*/
|
|
189
|
+
export declare type AudioDocumentRejection = AudioClipProblem | "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "duplicate-key" | "invalid-fade-curve" | "metadata-too-long";
|
|
190
|
+
|
|
93
191
|
/**
|
|
94
192
|
* The port for reading audio files: probe a file's headers, decode it, and
|
|
95
193
|
* build its waveform overview (ADR 0001, ADR 0003, ADR 0008). The SDK's own
|
|
@@ -190,6 +288,8 @@ export declare class AudioError extends SdkError<AudioErrorCode> {
|
|
|
190
288
|
* usually because it lacks the codec. `details.codec` names it.
|
|
191
289
|
* - `INVALID_COMMAND`: an edit command doesn't apply to the clip plan, such
|
|
192
290
|
* as a range outside its source or an unknown clip key.
|
|
291
|
+
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
292
|
+
* valid in its format.
|
|
193
293
|
* - `DURATION_TOO_LONG`: a file exceeds the `maxDuration` limit.
|
|
194
294
|
* - `TOO_MANY_CHANNELS`: a file exceeds the `maxChannels` limit.
|
|
195
295
|
* - `SAMPLE_RATE_TOO_HIGH`: a file exceeds the `maxSampleRate` limit.
|
|
@@ -203,7 +303,7 @@ export declare class AudioError extends SdkError<AudioErrorCode> {
|
|
|
203
303
|
*
|
|
204
304
|
* @public
|
|
205
305
|
*/
|
|
206
|
-
export declare type AudioErrorCode = SdkCoreErrorCode | "INVALID_AUDIO" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "DURATION_TOO_LONG" | "TOO_MANY_CHANNELS" | "SAMPLE_RATE_TOO_HIGH" | "SESSION_TOO_LARGE" | "TOO_MANY_CLIPS";
|
|
306
|
+
export declare type AudioErrorCode = SdkCoreErrorCode | "INVALID_AUDIO" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "DURATION_TOO_LONG" | "TOO_MANY_CHANNELS" | "SAMPLE_RATE_TOO_HIGH" | "SESSION_TOO_LARGE" | "TOO_MANY_CLIPS";
|
|
207
307
|
|
|
208
308
|
/**
|
|
209
309
|
* The file an export produces. WAV is the only container so far (ADR 0001).
|
|
@@ -278,6 +378,19 @@ export declare interface AudioInsertClipsCommand {
|
|
|
278
378
|
readonly splitKey?: string;
|
|
279
379
|
}
|
|
280
380
|
|
|
381
|
+
/**
|
|
382
|
+
* Options for {@link AudioSession.insert}.
|
|
383
|
+
*
|
|
384
|
+
* @public
|
|
385
|
+
*/
|
|
386
|
+
export declare interface AudioInsertOptions extends AudioProgressOptions {
|
|
387
|
+
/**
|
|
388
|
+
* The timeline frame to insert at, splitting the clip there if it's inside
|
|
389
|
+
* one. Defaults to the end.
|
|
390
|
+
*/
|
|
391
|
+
readonly at?: number;
|
|
392
|
+
}
|
|
393
|
+
|
|
281
394
|
/**
|
|
282
395
|
* The type of {@link audioLimitDefinitions}.
|
|
283
396
|
*
|
|
@@ -303,7 +416,7 @@ export declare type AudioLimitDefinitions = typeof audioLimitDefinitions;
|
|
|
303
416
|
*
|
|
304
417
|
* Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 32-bit
|
|
305
418
|
* floats: frames × channels × 4 bytes. `maxDuration` is in milliseconds, and
|
|
306
|
-
* `maxSampleRate`
|
|
419
|
+
* `maxSampleRate` is in hertz.
|
|
307
420
|
*
|
|
308
421
|
* @public
|
|
309
422
|
*/
|
|
@@ -333,7 +446,7 @@ export declare const audioLimitDefinitions: {
|
|
|
333
446
|
};
|
|
334
447
|
readonly maxSampleRate: {
|
|
335
448
|
readonly code: "SAMPLE_RATE_TOO_HIGH";
|
|
336
|
-
readonly unit: "
|
|
449
|
+
readonly unit: "hertz";
|
|
337
450
|
readonly default: 192000;
|
|
338
451
|
};
|
|
339
452
|
readonly maxSessionSize: {
|
|
@@ -411,7 +524,8 @@ export declare const audioMessages: {
|
|
|
411
524
|
readonly "errors.UNSUPPORTED_FORMAT": "This audio format isn't supported. Try converting the file to WAV, then open it again.";
|
|
412
525
|
readonly "errors.DECODE_FAILED": "This browser can't play this kind of audio. Try another browser, or convert the file to WAV.";
|
|
413
526
|
readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
|
|
414
|
-
readonly "errors.
|
|
527
|
+
readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an audio project.";
|
|
528
|
+
readonly "errors.DURATION_TOO_LONG": "This recording is {actual, duration} long, which is over the {maximum, duration} limit.";
|
|
415
529
|
readonly "errors.TOO_MANY_CHANNELS": "This recording has {actual, number} channels, which is over the {maximum, number}-channel limit.";
|
|
416
530
|
readonly "errors.SAMPLE_RATE_TOO_HIGH": "This recording's sample rate is {actual, number} Hz, which is over the {maximum, number} Hz limit.";
|
|
417
531
|
readonly "errors.SESSION_TOO_LARGE": "The open recordings would use {actual, fileSize} of memory, which is over the {maximum, fileSize} limit. Remove a recording, or clear the undo history, and try again.";
|
|
@@ -421,7 +535,7 @@ export declare const audioMessages: {
|
|
|
421
535
|
readonly one: "A recording can have {maximum} clip. Join or delete clips, and try again.";
|
|
422
536
|
readonly other: "A recording can have up to {maximum} clips. Join or delete clips, and try again.";
|
|
423
537
|
};
|
|
424
|
-
readonly "warnings.maxDuration": "This recording is long, and may be slow to open and edit.";
|
|
538
|
+
readonly "warnings.maxDuration": "This recording is {actual, duration} long, and may be slow to open and edit.";
|
|
425
539
|
readonly "warnings.maxChannels": "This recording has {actual, number} channels, and may be slow to edit.";
|
|
426
540
|
readonly "warnings.maxSampleRate": "This recording's sample rate is {actual, number} Hz, and it may be slow to edit.";
|
|
427
541
|
readonly "warnings.maxSessionSize": "The open recordings use {actual, fileSize} of memory. Clearing the undo history frees memory.";
|
|
@@ -431,6 +545,7 @@ export declare const audioMessages: {
|
|
|
431
545
|
readonly one: "This recording has {actual} clip. Many clips may be slow to play and export.";
|
|
432
546
|
readonly other: "This recording has {actual} clips. Many clips may be slow to play and export.";
|
|
433
547
|
};
|
|
548
|
+
readonly "warnings.truncated": "This recording looks incomplete, perhaps from an interrupted recording or download. It opened with the audio it holds.";
|
|
434
549
|
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
435
550
|
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
436
551
|
readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
|
|
@@ -603,6 +718,36 @@ export declare interface AudioPlan {
|
|
|
603
718
|
readonly metadata: AudioMetadata;
|
|
604
719
|
}
|
|
605
720
|
|
|
721
|
+
/**
|
|
722
|
+
* The clip plan as portable JSON: `hm-audio-plan` version 1, which
|
|
723
|
+
* `formats/hm-audio-plan/v1.schema.json` describes (docs/formats/hm-audio-plan.md).
|
|
724
|
+
* Every position is a whole number of frames, and sources are named by the
|
|
725
|
+
* ids their clips use.
|
|
726
|
+
*
|
|
727
|
+
* @public
|
|
728
|
+
*/
|
|
729
|
+
export declare interface AudioPlanDocument {
|
|
730
|
+
readonly format: typeof AUDIO_PLAN_FORMAT;
|
|
731
|
+
readonly version: typeof AUDIO_PLAN_VERSION;
|
|
732
|
+
readonly sampleRate: number;
|
|
733
|
+
readonly channels: number;
|
|
734
|
+
readonly sources: Readonly<Record<string, AudioPlanDocumentSource>>;
|
|
735
|
+
readonly clips: readonly AudioClip[];
|
|
736
|
+
readonly metadata: AudioMetadata;
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/**
|
|
740
|
+
* A source, as a plan document records it: its length, which its clips must
|
|
741
|
+
* lie within, and, once documents travel with their files, its content.
|
|
742
|
+
*
|
|
743
|
+
* @public
|
|
744
|
+
*/
|
|
745
|
+
export declare interface AudioPlanDocumentSource {
|
|
746
|
+
/** The source's length in frames, at the plan's sample rate. */
|
|
747
|
+
readonly frames: number;
|
|
748
|
+
readonly asset?: AudioAssetReference;
|
|
749
|
+
}
|
|
750
|
+
|
|
606
751
|
/**
|
|
607
752
|
* What the probe learned about a file before anything decodes it (ADR 0001,
|
|
608
753
|
* ADR 0004). Limits are checked against it.
|
|
@@ -683,6 +828,21 @@ export declare interface AudioProgressOptions extends AudioCallOptions {
|
|
|
683
828
|
readonly onProgress?: (fraction: number) => void;
|
|
684
829
|
}
|
|
685
830
|
|
|
831
|
+
/**
|
|
832
|
+
* What an event says about a recording: its format and size, never its
|
|
833
|
+
* name or contents.
|
|
834
|
+
*
|
|
835
|
+
* @public
|
|
836
|
+
*/
|
|
837
|
+
export declare interface AudioRecordingFacts {
|
|
838
|
+
readonly durationSeconds: number;
|
|
839
|
+
readonly sampleRate: number;
|
|
840
|
+
readonly channels: number;
|
|
841
|
+
readonly container: AudioSourceInfo["container"];
|
|
842
|
+
readonly codec: AudioSourceInfo["codec"];
|
|
843
|
+
readonly truncated: boolean;
|
|
844
|
+
}
|
|
845
|
+
|
|
686
846
|
/**
|
|
687
847
|
* Removes clips. Their sources stay, so undo can bring them back.
|
|
688
848
|
*
|
|
@@ -754,6 +914,166 @@ export declare interface AudioRestoreClipsCommand {
|
|
|
754
914
|
declare type AudioSampleFormat_2 = "pcm16" | "pcm24" | "float32";
|
|
755
915
|
export { AudioSampleFormat_2 as AudioSampleFormat }
|
|
756
916
|
|
|
917
|
+
/**
|
|
918
|
+
* A range of the timeline, in frames: `start` inclusive and `end`
|
|
919
|
+
* exclusive, at least one frame long.
|
|
920
|
+
*
|
|
921
|
+
* @public
|
|
922
|
+
*/
|
|
923
|
+
export declare interface AudioSelection {
|
|
924
|
+
readonly start: number;
|
|
925
|
+
readonly end: number;
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The recording being edited, as a framework-agnostic store (ADR 0008,
|
|
930
|
+
* ADR 0029): a clip plan over decoded sources, edited with commands, with
|
|
931
|
+
* undo and redo (docs/adr/0003). React binds to it with
|
|
932
|
+
* `useSyncExternalStore`, and the element binds to the same store.
|
|
933
|
+
*
|
|
934
|
+
* @public
|
|
935
|
+
*/
|
|
936
|
+
export declare interface AudioSession {
|
|
937
|
+
/** The current snapshot, the same object until something changes. */
|
|
938
|
+
getSnapshot(): AudioSessionSnapshot;
|
|
939
|
+
/** Calls the listener after every change. Returns a function that unsubscribes. */
|
|
940
|
+
subscribe(listener: () => void): () => void;
|
|
941
|
+
/**
|
|
942
|
+
* Opens a recording, replacing the current one and its history once it
|
|
943
|
+
* has opened. The file is checked against the file policy before it's
|
|
944
|
+
* read, and its probe before it's decoded. Rejects with an `AudioError`,
|
|
945
|
+
* which the snapshot also holds; the current recording, if any, stays
|
|
946
|
+
* open.
|
|
947
|
+
*/
|
|
948
|
+
open(file: Blob, options?: AudioProgressOptions): Promise<void>;
|
|
949
|
+
/**
|
|
950
|
+
* Inserts another recording at a timeline frame, as one undoable step. It
|
|
951
|
+
* must have the session's sample rate; resampling comes later. If the
|
|
952
|
+
* sources held would then exceed `maxSessionSize`, the session first drops
|
|
953
|
+
* history steps, in sdk-core's `dropOrder`, as far as needed to release
|
|
954
|
+
* sources only they refer to, and sets `historyTrimmed`. If even that
|
|
955
|
+
* isn't enough, it rejects with `SESSION_TOO_LARGE` and changes nothing.
|
|
956
|
+
*/
|
|
957
|
+
insert(file: Blob, options?: AudioInsertOptions): Promise<void>;
|
|
958
|
+
/**
|
|
959
|
+
* Runs one command, or several as one undoable step. A command that
|
|
960
|
+
* doesn't apply throws `AudioError` with `INVALID_COMMAND`, and one that
|
|
961
|
+
* would exceed `maxClips` throws `TOO_MANY_CLIPS`; either changes
|
|
962
|
+
* nothing. The commands are copied, so changing them afterwards has no
|
|
963
|
+
* effect.
|
|
964
|
+
*/
|
|
965
|
+
execute(commands: AudioCommand | readonly AudioCommand[]): void;
|
|
966
|
+
/**
|
|
967
|
+
* Runs `fn`, and records the commands it executes as one undoable step,
|
|
968
|
+
* for gestures such as dragging a trim handle.
|
|
969
|
+
*/
|
|
970
|
+
group<T>(fn: () => T): T;
|
|
971
|
+
/**
|
|
972
|
+
* A clip key no clip has, in the plan or the history, for commands that
|
|
973
|
+
* create clips, such as `newKey` in `audio.splitClip`.
|
|
974
|
+
*/
|
|
975
|
+
createKey(): string;
|
|
976
|
+
undo(): void;
|
|
977
|
+
redo(): void;
|
|
978
|
+
/**
|
|
979
|
+
* Selects a range of the timeline, clamped to the plan, or clears the
|
|
980
|
+
* selection with `undefined`. An empty range clears it too.
|
|
981
|
+
*/
|
|
982
|
+
select(range: AudioSelection | undefined): void;
|
|
983
|
+
/** A source's waveform overview, or `undefined` for a source the session doesn't hold. */
|
|
984
|
+
getPeaks(source: string): AudioPeaks | undefined;
|
|
985
|
+
/** Closes the recording and releases its sources. */
|
|
986
|
+
close(): Promise<void>;
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
/**
|
|
990
|
+
* Anonymous usage events, for a host's analytics (docs/adr/0003). They
|
|
991
|
+
* never contain file names, samples or metadata values. Durations are in
|
|
992
|
+
* seconds.
|
|
993
|
+
*
|
|
994
|
+
* @public
|
|
995
|
+
*/
|
|
996
|
+
export declare type AudioSessionEvent = ({
|
|
997
|
+
readonly type: "recording_opened" | "recording_inserted";
|
|
998
|
+
} & AudioRecordingFacts) | {
|
|
999
|
+
readonly type: "recording_closed";
|
|
1000
|
+
} | {
|
|
1001
|
+
readonly type: "command";
|
|
1002
|
+
readonly commands: readonly AudioCommand["type"][];
|
|
1003
|
+
} | {
|
|
1004
|
+
readonly type: "undo";
|
|
1005
|
+
} | {
|
|
1006
|
+
readonly type: "redo";
|
|
1007
|
+
} | {
|
|
1008
|
+
readonly type: "failed";
|
|
1009
|
+
readonly operation: "open" | "insert" | "command";
|
|
1010
|
+
readonly code: string;
|
|
1011
|
+
};
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* Options for {@link createAudioSession}.
|
|
1015
|
+
*
|
|
1016
|
+
* @public
|
|
1017
|
+
*/
|
|
1018
|
+
export declare interface AudioSessionOptions {
|
|
1019
|
+
/** Probes, decodes and builds waveform peaks, such as `createAudioEngine()`. */
|
|
1020
|
+
readonly engine: AudioEngine;
|
|
1021
|
+
/** Limits for untrusted files (docs/adr/0004). Unknown names throw. */
|
|
1022
|
+
readonly filePolicy?: AudioFilePolicyOverrides;
|
|
1023
|
+
/** Receives anonymous usage events. Errors it throws are ignored. */
|
|
1024
|
+
readonly onEvent?: (event: AudioSessionEvent) => void;
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
/**
|
|
1028
|
+
* The session's state at one moment (docs/adr/0003). Snapshots are
|
|
1029
|
+
* immutable: every change makes a new one, so `useSyncExternalStore` and
|
|
1030
|
+
* other subscribers can compare them by identity. The playhead isn't here:
|
|
1031
|
+
* it belongs to `AudioOutput`, which moves it sixty times a second.
|
|
1032
|
+
*
|
|
1033
|
+
* @public
|
|
1034
|
+
*/
|
|
1035
|
+
export declare interface AudioSessionSnapshot {
|
|
1036
|
+
readonly status: AudioSessionStatus;
|
|
1037
|
+
/** The recording being edited, or `undefined` when none is open. */
|
|
1038
|
+
readonly plan: AudioPlan | undefined;
|
|
1039
|
+
/** The sources the session holds: those the plan uses, and those undo or redo can bring back. */
|
|
1040
|
+
readonly sources: readonly AudioSourceInfo[];
|
|
1041
|
+
readonly canUndo: boolean;
|
|
1042
|
+
readonly canRedo: boolean;
|
|
1043
|
+
/**
|
|
1044
|
+
* Whether undo steps were dropped since the recording opened, to make
|
|
1045
|
+
* room for an insert within `maxSessionSize`. Editors say so, because the
|
|
1046
|
+
* earliest edits can no longer be undone (ADR 0010).
|
|
1047
|
+
*/
|
|
1048
|
+
readonly historyTrimmed: boolean;
|
|
1049
|
+
/** Whether a recording is being opened or inserted. */
|
|
1050
|
+
readonly busy: boolean;
|
|
1051
|
+
/** Why the last open or insert failed. Show its text by its code. */
|
|
1052
|
+
readonly error: AudioError | undefined;
|
|
1053
|
+
readonly warnings: readonly AudioWarning[];
|
|
1054
|
+
/**
|
|
1055
|
+
* The decoded bytes of every source the session holds, which the
|
|
1056
|
+
* `maxSessionSize` limit counts: frames × channels × 4.
|
|
1057
|
+
*/
|
|
1058
|
+
readonly sessionBytes: number;
|
|
1059
|
+
/** The selected range of the timeline. View state: not undoable, and never in events. */
|
|
1060
|
+
readonly selection: AudioSelection | undefined;
|
|
1061
|
+
}
|
|
1062
|
+
|
|
1063
|
+
/**
|
|
1064
|
+
* What the session is doing.
|
|
1065
|
+
*
|
|
1066
|
+
* - `empty`: no recording is open.
|
|
1067
|
+
* - `opening`: a recording is being opened, replacing any other.
|
|
1068
|
+
* - `ready`: a recording is open.
|
|
1069
|
+
* - `error`: no recording is open, because the last open failed; `error`
|
|
1070
|
+
* says why. A failed open while a recording is open keeps it, with the
|
|
1071
|
+
* status `ready` and `error` set.
|
|
1072
|
+
*
|
|
1073
|
+
* @public
|
|
1074
|
+
*/
|
|
1075
|
+
export declare type AudioSessionStatus = "empty" | "opening" | "ready" | "error";
|
|
1076
|
+
|
|
757
1077
|
/**
|
|
758
1078
|
* Sets a clip's fade in or fade out. Together, the two fades must fit in
|
|
759
1079
|
* the clip.
|
|
@@ -777,7 +1097,7 @@ export declare interface AudioSetFadeCommand {
|
|
|
777
1097
|
export declare interface AudioSetGainCommand {
|
|
778
1098
|
readonly type: "audio.setGain";
|
|
779
1099
|
readonly keys: readonly string[];
|
|
780
|
-
/** Decibels, from
|
|
1100
|
+
/** Decibels, from `MIN_GAIN_DB` to `MAX_GAIN_DB`. */
|
|
781
1101
|
readonly gainDb: number;
|
|
782
1102
|
}
|
|
783
1103
|
|
|
@@ -849,6 +1169,35 @@ export declare interface AudioUpdateClipsCommand {
|
|
|
849
1169
|
readonly clips: readonly AudioClip[];
|
|
850
1170
|
}
|
|
851
1171
|
|
|
1172
|
+
/**
|
|
1173
|
+
* Something the user should know about the recordings open, though they
|
|
1174
|
+
* opened (docs/adr/0004). Show its text from `warnings.<limit>`, or from
|
|
1175
|
+
* `warnings.truncated`, in the message catalogue, with its fields as
|
|
1176
|
+
* parameters.
|
|
1177
|
+
*
|
|
1178
|
+
* - `limit`: a value at or above a limit's warning threshold, but within its
|
|
1179
|
+
* maximum. `source` names the recording it's about, unless it's about the
|
|
1180
|
+
* whole session, as `maxSessionSize` and `maxClips` are.
|
|
1181
|
+
* - `truncated`: an uncompressed recording holds fewer frames than its
|
|
1182
|
+
* header declares, as after an interrupted recording or download. It
|
|
1183
|
+
* opened with the frames it holds.
|
|
1184
|
+
*
|
|
1185
|
+
* @public
|
|
1186
|
+
*/
|
|
1187
|
+
export declare type AudioWarning = {
|
|
1188
|
+
readonly type: "limit";
|
|
1189
|
+
readonly limit: AudioLimitName;
|
|
1190
|
+
readonly actual: number;
|
|
1191
|
+
readonly source?: string;
|
|
1192
|
+
} | {
|
|
1193
|
+
readonly type: "truncated";
|
|
1194
|
+
readonly source: string;
|
|
1195
|
+
/** The frames the recording holds. */
|
|
1196
|
+
readonly frames: number;
|
|
1197
|
+
/** The frames its header declares. */
|
|
1198
|
+
readonly declaredFrames: number;
|
|
1199
|
+
};
|
|
1200
|
+
|
|
852
1201
|
/**
|
|
853
1202
|
* A clip's length in frames.
|
|
854
1203
|
*
|
|
@@ -893,6 +1242,23 @@ export declare function clipOffsets(plan: AudioPlan): readonly number[];
|
|
|
893
1242
|
*/
|
|
894
1243
|
export declare function createAudioEngine(options?: AudioEngineOptions): AudioEngine;
|
|
895
1244
|
|
|
1245
|
+
/**
|
|
1246
|
+
* Creates an {@link AudioSession}. Pass the engine to use; the headless core
|
|
1247
|
+
* doesn't choose one.
|
|
1248
|
+
*
|
|
1249
|
+
* @example
|
|
1250
|
+
* ```ts
|
|
1251
|
+
* const session = createAudioSession({ engine: createAudioEngine() });
|
|
1252
|
+
* await session.open(file);
|
|
1253
|
+
* const [clip] = session.getSnapshot().plan?.clips ?? [];
|
|
1254
|
+
* session.execute({ type: "audio.setGain", keys: [clip.key], gainDb: -3 });
|
|
1255
|
+
* session.undo();
|
|
1256
|
+
* ```
|
|
1257
|
+
*
|
|
1258
|
+
* @public
|
|
1259
|
+
*/
|
|
1260
|
+
export declare function createAudioSession(options: AudioSessionOptions): AudioSession;
|
|
1261
|
+
|
|
896
1262
|
/**
|
|
897
1263
|
* Converts decibels to a linear gain factor.
|
|
898
1264
|
*
|
|
@@ -1004,6 +1370,24 @@ export declare const NO_FADE: AudioFade;
|
|
|
1004
1370
|
*/
|
|
1005
1371
|
export declare function planLength(plan: AudioPlan): number;
|
|
1006
1372
|
|
|
1373
|
+
/**
|
|
1374
|
+
* Reads a plan document, such as one parsed from JSON, checking it as
|
|
1375
|
+
* {@link AudioPlanDocument}'s schema does and more: every clip must lie
|
|
1376
|
+
* within a source the document lists, and keys must be unique. Unknown
|
|
1377
|
+
* fields are refused, never dropped.
|
|
1378
|
+
*
|
|
1379
|
+
* @param value - The parsed JSON.
|
|
1380
|
+
* @returns The plan, and its sources by id.
|
|
1381
|
+
* @throws `AudioError` with `UNSUPPORTED_FORMAT` for another format or a
|
|
1382
|
+
* later version, and `INVALID_DOCUMENT` for anything else that's wrong,
|
|
1383
|
+
* with a {@link AudioDocumentRejection} as `details.reason`.
|
|
1384
|
+
* @public
|
|
1385
|
+
*/
|
|
1386
|
+
export declare function readAudioPlanDocument(value: unknown): {
|
|
1387
|
+
readonly plan: AudioPlan;
|
|
1388
|
+
readonly sources: Readonly<Record<string, AudioPlanDocumentSource>>;
|
|
1389
|
+
};
|
|
1390
|
+
|
|
1007
1391
|
/**
|
|
1008
1392
|
* Converts seconds to the nearest whole frame, for input from the UI, such
|
|
1009
1393
|
* as a typed trim point.
|
|
@@ -1014,4 +1398,15 @@ export declare function planLength(plan: AudioPlan): number;
|
|
|
1014
1398
|
*/
|
|
1015
1399
|
export declare function secondsToFrames(seconds: number, sampleRate: number): number;
|
|
1016
1400
|
|
|
1401
|
+
/**
|
|
1402
|
+
* Writes a plan as an {@link AudioPlanDocument}, plain JSON-ready data.
|
|
1403
|
+
*
|
|
1404
|
+
* @param plan - The plan.
|
|
1405
|
+
* @param sources - The sources by id, with at least every source the plan's
|
|
1406
|
+
* clips use. They're written as given.
|
|
1407
|
+
* @throws `TypeError` if a clip's source is missing from `sources`.
|
|
1408
|
+
* @public
|
|
1409
|
+
*/
|
|
1410
|
+
export declare function toAudioPlanDocument(plan: AudioPlan, sources: Readonly<Record<string, AudioPlanDocumentSource>>): AudioPlanDocument;
|
|
1411
|
+
|
|
1017
1412
|
export { }
|