Syncromesh/Audio — SyncroMesh Documentation

Provides process-local audio playback for scripts running in the orchestrator context and in sibling board runtimes. WAV clips can be preloaded for sound effects, OGG/MP3/FLAC assets can be streamed as music, playback pitch can be changed per track, and output can be routed through custom string-named volume buses.

Import #

Functions #

preload

Loads a clip from mounted assets and returns a clip id.

Returns an existing clip id when path is already cached.
Intended for reusable sound effects. WAV is the primary supported clip format.

preload(path: string): Promise<number>

play

Starts playback and returns an instance id.

pathOrClipId can be an asset path string or a clip id from preload.
volume is clamped to [0, 1] and defaults to 1.0.
pitch is a playback frequency ratio: 1 is unchanged, 2 is one octave higher/twice as fast, and 0.5 is one octave lower/half speed. It defaults to 1 and is clamped to [0.01, 100].
bus defaults to "default" and may be any non-empty string.
loop defaults to false.
Set position to enable spatial playback for a one-shot clip.
listener defaults to {x:0,y:0}.
minDistance defaults to 1, maxDistance defaults to 40, and rolloff defaults to 1.

play(pathOrClipId: string | number, options?: { loop?: boolean; volume?: number; pitch?: number; bus?: string; position?: {x:number,y:number}; listener?: {x:number,y:number}; minDistance?: number; maxDistance?: number; rolloff?: number }): Promise<number>

playMusic

Streams a music asset and returns a music instance id.

Supports OGG/Vorbis, MP3, FLAC, and WAV through the SDL_mixer backend.
Only one music stream is active at a time; starting another replaces the current stream.
pitch has the same frequency-ratio semantics and [0.01, 100] range as play.
bus defaults to "default".

playMusic(path: string, options?: { loop?: boolean; volume?: number; pitch?: number; bus?: string }): Promise<number>

setPitch

Changes an active sound-effect instance's pitch and playback speed.

pitch must be finite and is clamped to [0.01, 100].
Rejects when instanceId is not an active sound-effect instance.

setPitch(instanceId: number, pitch: number): Promise<boolean>

setMusicPitch

Changes the active music stream's pitch and playback speed.

pitch must be finite and is clamped to [0.01, 100].
Rejects when no music stream is active.

setMusicPitch(pitch: number): Promise<boolean>

stopMusic

Stops the current music stream.

Rejects when no music stream is active.

stopMusic(): Promise<boolean>

stop

Stops a specific playback instance.

Resolves to true when the instance existed and was stopped.
Rejects when the instance id is unknown.

stop(instanceId: number): Promise<boolean>

stopAll

Stops all active playback instances.

Always resolves to true.

stopAll(): Promise<boolean>

setListener

Updates the global listener position used by spatial emitters.

Call this each frame (or on movement) from game code.
Applies to active emitters and future spatial playback.

setListener(position: {x:number,y:number}): Promise<boolean>

setEmitterPosition

Moves an active emitter instance in world space.

Use with a looped play(...) instance to create continuously moving emitters.
Rejects when instanceId does not exist.

setEmitterPosition(instanceId: number, position: {x:number,y:number}): Promise<boolean>

setBusVolume

Sets a custom bus volume and resolves the clamped value.

Missing or empty bus names resolve to "default".
Bus volume is multiplied by each instance volume and the master volume.

setBusVolume(busName: string, value: number): Promise<number>

getBusVolume

Returns the current bus volume.

Unknown buses default to 1.0.

getBusVolume(busName: string): Promise<number>

setMasterVolume

Sets global output volume and resolves the clamped value.

Master volume is applied to all active and future instances.
value must be finite; resulting volume is clamped to [0, 1].

setMasterVolume(value: number): Promise<number>

getMasterVolume

Returns the current master volume.

getMasterVolume(): Promise<number>

Example #

import * as Audio from 'Syncromesh/Audio';

const clipId = await Audio.preload('/rom/sfx/engine.wav');
const emitterId = await Audio.play(clipId, {
  loop: true,
  volume: 0.6,
  pitch: 0.9,
  position: { x: 0, y: 0 },
  minDistance: 1,
  maxDistance: 30,
  rolloff: 1.2
});

// update these from your game loop
await Audio.setListener({ x: camera.x, y: camera.y });
await Audio.setEmitterPosition(emitterId, { x: entity.x, y: entity.y });
await Audio.setPitch(emitterId, 1.15);

// ... later
await Audio.stop(emitterId);

← Syncromesh/Assets Syncromesh/Data →