Loading article…

Loading 4weird…

Docs · music · games

One script tag. Every game sings.

The in-game runtime is a single dependency-free script: include /games/html/fourweird-music.js, call window.FourWeirdMusic, and your game plays $music:1 songs and SFX through lazy WebAudio — fail-open when audio is missing, silent when a payload is invalid.

1: script tag
8KB: song budget
1KB: sfx budget
0: assets needed

The runtime

Embed fourweird-music.js

Reference the runtime by its absolute /games/html/ path — never a relative copy — and it guards itself idempotently on window.FourWeirdMusic. The AudioContext is created lazily on the first play call and resumed if suspended, so autoplay policies stay happy.

game.html — music wiring

/games/html/

var M = window.FourWeirdMusic;

M.playSong(songObj); // or a seed URL, or JSON text via playSongJson

M.playSfx("raygun"); M.setVolumes({ music: 0.5 });

Walkthrough

From silent game to soundtrack

Wire once, then drive everything through the M handle: songs for loops, baked SFX kind names for one-liners, volumes and mute for the options screen. Invalid payloads fail silently to false — your game never crashes on a bad note.

Include the script
Add <script src="/games/html/fourweird-music.js"> with the absolute path, then grab window.FourWeirdMusic. Including it twice is safe — the second load returns early.
Play a song loop
Call playSong with a song object, a $music:1 wrapper, or a seed URL (fetched fail-open). Stop it with stopSong (alias: stop).
Fire sound effects
Call playSfx with a baked kind name (raygun, death, coin, jump, win, lose, click, alarm…), an SFX object, or JSON text via playSfxJson.
Mix and mute
Balance with setVolumes({ master, music, sfx }) and honor the player's choice with setMuted(true) on the options screen.

Seed format

Ship tiny soundtrack files

Game soundtracks live on as small JSON seeds: *.song.json loops transcribed from each game's signature sound (menu, boss, death, coin) and *.sfx.json one-shot recipes. The embed runtime enforces its own tight budgets — songs ≤ 8KB, sfx ≤ 1KB, 8 tracks and 512 notes max — so every seed stays playable anywhere.

Worked example

Title loop plus coin SFX in one file

Wire a menu loop that starts on first input and a coin blip that fires on pickup. Both calls are fail open, so a missing file never breaks the game.

game.html — loop plus pickup

copy pattern

startButton.onclick = () => M.playSong(titleLoop);

onPickup = () => M.playSfx(coin);

optionsToggle.onchange = (e) => M.setMuted(e.target.checked);

bad payload returns false, game keeps running

Troubleshooting

Silent game, autoplay block, bad payload

Music bugs in games are almost always wiring, policy, or payload shape. Check in this order and most sessions recover in a minute.

Nothing plays at all
Confirm the script tag uses the absolute path /games/html/fourweird-music.js and that window.FourWeirdMusic exists before your first call. A relative copy or a doubled bundle path is the most common silence.
Music starts only after a click
That is autoplay policy working as intended. Bind the first playSong to a start button or any tap, and create the AudioContext lazily inside that handler. Resume it if the browser reports suspended.
SFX fires but the song will not loop
Check the song object shape and the 8KB song budget (8 tracks and 512 notes max). Fetch seed URLs fail open, so a 404 seed reads as silence. Inline the canonical JSON to isolate fetch versus shape.
A bad note crashes the scene
It should not. Invalid payloads fail silently to false by design. If your game throws, the throw is in your caller, so guard the call site and keep the frame loop independent of audio.
Volumes fight each other
Balance with setVolumes using separate music and sfx levels, then honor the options screen mute flag on every scene change. Persist the mute choice so returning players keep their setting.

Loading article…

DocsGames

Docs · music · games

One script tag. Every game sings.

1: script tag
8KB: song budget
1KB: sfx budget
0: assets needed

The runtime

Embed fourweird-music.js

game.html — music wiring

/games/html/

var M = window.FourWeirdMusic;

M.playSong(songObj); // or a seed URL, or JSON text via playSongJson

M.playSfx("raygun"); M.setVolumes({ music: 0.5 });

Walkthrough

From silent game to soundtrack

Include the script
Add <script src="/games/html/fourweird-music.js"> with the absolute path, then grab window.FourWeirdMusic. Including it twice is safe — the second load returns early.
Play a song loop
Call playSong with a song object, a $music:1 wrapper, or a seed URL (fetched fail-open). Stop it with stopSong (alias: stop).
Fire sound effects
Call playSfx with a baked kind name (raygun, death, coin, jump, win, lose, click, alarm…), an SFX object, or JSON text via playSfxJson.
Mix and mute
Balance with setVolumes({ master, music, sfx }) and honor the player's choice with setMuted(true) on the options screen.

Seed format

Ship tiny soundtrack files

Worked example

Title loop plus coin SFX in one file

Wire a menu loop that starts on first input and a coin blip that fires on pickup. Both calls are fail open, so a missing file never breaks the game.

game.html — loop plus pickup

copy pattern

startButton.onclick = () => M.playSong(titleLoop);

onPickup = () => M.playSfx(coin);

optionsToggle.onchange = (e) => M.setMuted(e.target.checked);

bad payload returns false, game keeps running

Troubleshooting

Silent game, autoplay block, bad payload

Music bugs in games are almost always wiring, policy, or payload shape. Check in this order and most sessions recover in a minute.

Nothing plays at all
Confirm the script tag uses the absolute path /games/html/fourweird-music.js and that window.FourWeirdMusic exists before your first call. A relative copy or a doubled bundle path is the most common silence.
Music starts only after a click
That is autoplay policy working as intended. Bind the first playSong to a start button or any tap, and create the AudioContext lazily inside that handler. Resume it if the browser reports suspended.
SFX fires but the song will not loop
Check the song object shape and the 8KB song budget (8 tracks and 512 notes max). Fetch seed URLs fail open, so a 404 seed reads as silence. Inline the canonical JSON to isolate fetch versus shape.
A bad note crashes the scene
It should not. Invalid payloads fail silently to false by design. If your game throws, the throw is in your caller, so guard the call site and keep the frame loop independent of audio.
Volumes fight each other
Balance with setVolumes using separate music and sfx levels, then honor the options screen mute flag on every scene change. Persist the mute choice so returning players keep their setting.

One script tag. Every game sings.

Embed fourweird-music.js

From silent game to soundtrack

Include the script

Play a song loop

Fire sound effects

Mix and mute

Ship tiny soundtrack files

Title loop plus coin SFX in one file

Silent game, autoplay block, bad payload

Nothing plays at all

Music starts only after a click

SFX fires but the song will not loop

A bad note crashes the scene

Volumes fight each other

One script tag. Every game sings.

Embed fourweird-music.js

From silent game to soundtrack

Include the script

Play a song loop

Fire sound effects

Mix and mute

Ship tiny soundtrack files

Title loop plus coin SFX in one file

Silent game, autoplay block, bad payload

Nothing plays at all

Music starts only after a click

SFX fires but the song will not loop

A bad note crashes the scene

Volumes fight each other