Sound API

Manage the key sound library: the pool of audio files that key elements can play on press. Sounds live in the app data sounds directory and include both user-imported files (local) and bundled ones (builtin).

Types


type SoundListItem = {
  soundPath: string; // absolute path, also the stable identifier
  fileName: string;
  sizeBytes: number;
  modifiedAtMs?: number;
  hidden: boolean; // hidden from picker lists, playback is unaffected
  enabled: boolean; // deprecated, inverse alias of hidden kept for 1.6.1 compat
  source: 'local' | 'builtin';
  originalPath?: string; // pre-trim original (present for edited sounds)
  trimStartRatio?: number;
  trimEndRatio?: number;
  displayName?: string;
};

Library

`dmn.sound.list(): Promise<SoundListItem[]>`

Returns every sound in the library, including hidden ones. Filtering by hidden is up to the caller (the built-in picker hides them from its default views and shows them under a “Hidden Sounds” filter).


const sounds = await dmn.sound.list();
const visible = sounds.filter((s) => !s.hidden);

`dmn.sound.load(): Promise<SoundLoadResult>`

Opens a file dialog, copies the chosen audio file into the library, and returns its soundPath.

`dmn.sound.rename(soundPath, displayName): Promise<SoundRenameResult>`

Sets the display name shown in pickers. The file itself is not renamed.

`dmn.sound.remove(soundPath): Promise<SoundDeleteResult>`

Deletes the file and unassigns the sound from every element using it.

Visibility

`dmn.sound.setHidden(soundPath, hidden): Promise<SoundSetHiddenResult>`

Hides a sound from (or restores it to) picker lists. Hiding is list-only housekeeping: keys that already use the sound keep playing it. Builtin sounds can be hidden too.


await dmn.sound.setHidden(sound.soundPath, true); // hide
await dmn.sound.setHidden(sound.soundPath, false); // unhide


type SoundSetHiddenResult = {
  success: boolean;
  soundPath: string;
  hidden: boolean;
};

`dmn.sound.setEnabled(soundPath, enabled): Promise<SoundSetEnabledResult>`

Deprecated. Inverse alias kept for backward compatibility. enabled is simply !hidden; use setHidden instead.

Editing

`dmn.sound.saveProcessedWav(wavBase64, fileName?, originalBase64?, originalExtension?, trimStartRatio?, trimEndRatio?): Promise<SoundSaveProcessedWavResult>`

Saves a processed (trimmed) WAV into the library, optionally alongside the original for later re-editing.

`dmn.sound.loadOriginal(soundPath): Promise<SoundLoadOriginalResult>`

Returns the stored original audio (base64) of an edited sound.

`dmn.sound.updateProcessedWav(soundPath, wavBase64, trimStartRatio?, trimEndRatio?, displayName?): Promise<SoundUpdateProcessedWavResult>`

Overwrites an edited sound’s processed WAV in place.

Diagnostics

`dmn.sound.setLatencyLogging(enabled): Promise<void>`

Toggles key-sound latency logging in the audio engine. Enabling is only available in dev/debug builds. Release builds reject enabled: true with an error.