Audio
Back to the reference

Audio

Sound, music in layers, zones and the listener.

19 symbols

useAudiofunctionhooknacatamalon

useAudio() => TAudioHandle

The game's volumes: the general one and one per channel, plus a way to silence everything.

A channel is a group of sounds that share a volume. 'sfx' and 'music' are there from the start, and any other name works the moment a sound uses it. This is what the sliders of an options screen move, and the numbers a game saves in its store so they are still there next time.

Volumes go from 0 (silent) to 1 (as recorded); above 1 is allowed and can distort.

Example

declare const settings: TGameStore<{ music: number }>;
declare const quieter: TText;

export const Options: TSceneFn = () => {
    const audio = useAudio();
    audio.setVolume(settings.state.music, 'music');

    listen(quieter, { onClick: () => audio.setVolume(audio.getVolume('music') - 0.1, 'music') });
    return createScene();
};
View source · hooks/audio/use_audio.ts:34

useAudioListenerfunctionhooknacatamalon

useAudioListener(options: { enabled }) => TAudioListener

Puts the game's ears on this object: every sound placed in the world is heard from where it is, and in a 3D scene, facing the way it faces.

Without it the game is heard from the camera, which is right until the camera is not where the player is. A game seen from behind its character wants the ears on the character: a bird to the character's left is then heard on the left, wherever the camera has swung round to.

One per object. With several switched on the first one is used, and that is said once; switch one off with enabled to hand over to the next, and in the end back to the camera.

Parameters

options{ enabled }

Whether it starts on. Default on.

Example

const Player = () => {
    useTransform({ x: 0, y: 0.5, z: 0 });
    createMesh({ geometry: useCubeGeometry() });
    useAudioListener();
};
View source · hooks/audio/use_audio_listener.ts:33

useMusicfunctionhooknacatamalon

useMusic(options: TMusicOptions) => TMusicHandle

Plays a piece of music made of layers, and hands back the controls for it.

The layers are the same tune played by different instruments, one file each and all the same length. They always play together and in time; what the game changes is how loud each one is. That is how music follows the place without ever starting over: walk into the water and the tune goes muffled, start a fight and the drums come in, and the melody never loses its place.

It belongs to the channel 'music' unless it says otherwise, so an options screen moves it with the rest. Like every sound, it stops with the scene or the object that asked for it.

Parameters

optionsTMusicOptions

The layers by name, each with the volume it starts at, and the piece's volume, channel and whether it starts on its own.

Example

declare const player: TSprite;

const Level = () => {
    const music = useMusic({
        layers: {
            land: { src: '/audio/theme_land.ogg' },
            water: { src: '/audio/theme_water.ogg', volume: 0 },
        },
        autoplay: true,
    });

    useUpdate(() => {
        const under = player.transform.y < 0;
        music.setLayer('land', under ? 0 : 1, 0.5);
        music.setLayer('water', under ? 1 : 0, 0.5);
    });
    return createScene();
};
View source · hooks/audio/use_music.ts:72

useSoundfunctionhooknacatamalon

useSound(source: TSoundSource, options: TSoundOptions) => TSoundHandle

Plays a sound, and hands back the controls for it.

Called in the body of a scene, like every hook; the controls are used whenever, from an update, a click, a signal. When the scene stops or the object that asked for it is destroyed, its sound stops: a level's music does not survive the level.

A one-off (the default) can sound on top of itself, which is what effects need: two coins picked up at once are heard twice. A looping sound is a single thing that pause, resume and stop act on: music, rain, an engine.

With spatial it is heard from where the object that asked for it is, and follows it; with zone it fills an area around the object instead, the way birds fill a meadow. Starting and stopping can fade, and so can the volume.

Pausing the game or the scene does not stop a sound, because a menu over a frozen level often wants the music to carry on. To silence something on pause, listen to scenePaused/gamePaused and decide for each sound.

Parameters

sourceTSoundSource

A clip from useLoadAudio, or { src } to load it here.

optionsTSoundOptions

Volume, looping, speed, channel, and placing it in the world: at a point, facing a way, or filling an area.

Example

export const Level: TSceneFn = () => {
    const music = useSound({ src: '/audio/theme.mp3' }, { channel: 'music', loop: true, autoplay: true });
    const jump = useSound({ src: '/audio/jump.mp3' }, { volume: 0.6 });
    const keys = useKeyboard();

    useUpdate(() => {
        if (keys.justPressed('Space')) jump.play();
    });

    useSignal(scenePaused, () => music.setVolume(0.2));
    return createScene();
};
View source · hooks/audio/use_sound.ts:77

TAudioHandletypenacatamalon

The volumes of a game, and the way to silence it. Returned by useAudio.

A channel is a group of sounds that share a volume: 'sfx' and 'music' are there from the start, and any other name works the moment a sound uses it. This is what an options screen with a slider per kind of sound is made of, and what a game saves in its store.

Properties

setVolume
getVolume
stopAll
View source · audio/types/t_audio.ts:94

TAudioListenertypenacatamalon

Where the game is heard from, put on an object: its ears.

Without one the ears are in the camera, which is right for most games. A game seen from behind its character wants them on the character instead, or a bird on the left of the character is heard on whichever side of the camera it happens to be.

Properties

type'audio-listener'
idstring
enabledboolean

Off, the ears go back to the next in line, and in the end to the camera.

View source · audio/types/t_audio_listener.ts:12

TMusicAttachmenttypenacatamalon

A piece of music in layers attached to one object: which files, and how loud each is meant to be. What it keeps is the intention, never how far into the tune it had got.

Properties

type'music'
idstring
layersTMusicLayer[]
volumenumber
channelstring
autoplayboolean
View source · audio/types/t_music.ts:71

TMusicLayerOptionstypenacatamalon

TMusicLayerOptions: { src, key } | { clip } & { volume }

One layer of a piece of music: a file, or a clip already loaded, and how loud it starts.

View source · audio/types/t_music.ts:11

TMusicOptionstypenacatamalon

How a piece of music in layers plays.

Properties

idoptionalstring

The same name the saved scene keeps. Made up when nobody says.

layersRecord<string, TMusicLayerOptions>

The layers, by name: the same tune played by different instruments, each in its own file and all the same length. They always play together and in time, and what changes is how loud each one is.

volumeoptionalnumber

The volume of the whole piece. Default 1.

channeloptionalstring

Default 'music'.

autoplayoptionalboolean

Starts as soon as every layer is ready, with no play(). Default false.

View source · audio/types/t_music.ts:25

TSoundAttachmenttypenacatamalon

One sound attached to one object: which clip, and how it was asked to play.

What it holds is the intention, never what is sounding. A scene saved while the music was halfway through comes back ready to start, not halfway through: where a voice had got to is a fact about this run, and a level is not.

It carries the clip itself rather than its name, the way a sprite carries its texture, so that whoever writes the scene down can name the file and ask for it to be fetched again in one step.

Properties

type'sound'
idstring
clipTAudioClip
volumenumber
loopboolean
ratenumber
channelstring
autoplayboolean
spatialboolean
refDistancenumber | null

null until somebody chooses one: then it is what the scene measures in.

maxDistancenumber | null
coneTSoundCone | null
zoneTSoundZone | null
View source · audio/types/t_sound.ts:169

TSoundConetypenacatamalon

Where a sound is heard loudest: a speaker, a siren, a radio on a shelf. Straight ahead of its object it plays at full volume, and further round it drops towards outerVolume.

Ahead is the way the object faces: its -Z in a 3D scene, the same way a camera and a lamp face, and along its turn in a flat one (to the right when it is not turned).

Properties

innernumber

How wide the loud part is, in degrees, from edge to edge.

outernumber

Past this width, in degrees, it is at its quietest. Between the two it fades.

outerVolumenumber

How loud it is behind, from 0 (silent) to 1 (the same as ahead).

View source · audio/types/t_sound.ts:25

TSoundHandletypenacatamalon

Controls a sound made with useSound.

Properties

play
stop
pause
resume
setVolume
setLoop
setRate
playingboolean

Whether something of this sound is sounding right now.

View source · audio/types/t_sound.ts:195

TSoundOptionstypenacatamalon

How a sound plays.

Properties

idoptionalstring

The name this sound keeps in a saved scene, so that opening one and saving it again gives the same file back. Made up when nobody says, which is right for a sound written in code and wrong for one that came out of a document.

volumeoptionalnumber

0 silent, 1 as recorded. Default 1. This sound only: the channel and the general volume still apply.

loopoptionalboolean

Repeats until it is stopped. Default false.

It also decides what the sound is: a one-off can be played on top of itself (two coins at once are heard twice), while a looping one is a single sound that pause, resume and stop act on: music, rain, an engine.

rateoptionalnumber

How fast it plays, which also changes the pitch: 2 is twice as fast, an octave up. Default 1.

channeloptionalstring

Which volume group it belongs to: 'sfx' (the default) or 'music' are there from the start, and any other name works straight away. An options screen moves these with useAudio.

autoplayoptionalboolean

Starts as soon as the file is ready, with no play(). Default false.

spatialoptionalboolean

Places the sound in the world, where the object that asked for it is: it comes from a side and gets quieter with distance. It follows the object wherever it goes, including when what carries it is what moves.

Heard from the camera, or from whatever useAudioListener put the ears on. In a 3D scene it can also be told apart in front and behind, best with headphones. Default false, which is the same volume wherever the listener is.

refDistanceoptionalnumber

How far it can be heard at full volume. Placed sounds only. Measured the way the scene measures: 100 pixels in a flat scene and under an orthographic camera, 1 unit under a perspective one.

maxDistanceoptionalnumber

Past this distance it is not heard at all: between refDistance and this it fades in a straight line. Placed sounds only. 2000 pixels, or 20 units under a perspective camera.

coneoptionalTSoundCone

Louder ahead of the object than behind it. Placed sounds only.

zoneoptionalTSoundZone

Fills an area instead of coming from a point: full volume inside, fading outside, and never from one side, because an ambience is all around. Wins over spatial.

View source · audio/types/t_sound.ts:77

TSoundZonetypenacatamalon

An area a sound fills, the way a meadow is full of birds or a cave of dripping: inside, it plays at full volume wherever you stand, and outside it fades as you walk away.

Properties

shapeTSoundZoneShape

Measured on the object, so it moves, turns and grows with it.

fadenumber

How far outside the shape it takes to fade to silence. 0 stops dead at the edge.

View source · audio/types/t_sound.ts:59