2026-11-04 13:12:56 -08:00
// Plan2Code Web Console - the games' music: a small chiptune sequencer over tones.js's audio, and recorded songs, silent unless Play sounds and the game's own switches allow it; defines only.
2026-11-02 12:00:13 -08:00
import { looks } from "./looks.js" ;
2026-11-04 13:12:56 -08:00
import { MUSIC_TABLES , SONG_TABLES , audioOut } from "./tones.js" ;
2026-11-02 12:00:13 -08:00
/* -------------------------------------------------------------- music
Each game's tracks live in its `activities/<id>-sfx.js` under `music`, as
note data, so there is no audio file to fetch. A game calls
music(name, intensity) every frame it wants its track (the window adds a
third argument, the game's music volume); stop calling and it
fades out within MUSIC_HOLD_MS, the way a hum does, so a paused, closed or
finished game falls quiet by itself, and hushMusic() quiets it at once. A
track picks up again where it left off, at the start of that bar.
A track is:
2026-11-04 10:24:06 -08:00
{ bpm, rush, bar, voices: { name: voice }, patterns: { id: { voice: "..." } }, order: [id, ...] }
2026-11-02 12:00:13 -08:00
`bpm` is the tempo at intensity 0 and `rush` the beats a minute added at
2026-11-04 10:24:06 -08:00
intensity 1. Each step is a sixteenth note. `bar` is the steps in a bar
(16 when left out); only a track in another meter sets it (12 for 6/8, 14
for 7/8, 20 for ten beats), so a track picks up again on the start of a
bar, and a track that sets it must give every pattern a whole number of bars. A voice is a chip channel:
2026-11-02 12:00:13 -08:00
{ wave, duty, gain, from, decay, sustain, vibrato, kit }. `wave` is
"pulse" (with `duty`, 0.125, 0.25 or 0.5, the classic chip squares),
"triangle", "sine", "square" or "sawtooth"; `kit` makes it the drums
instead. A voice joins once the intensity reaches its `from`, so a track
builds as play heats up. `decay` (seconds) and `sustain` (a share) shape
each note's fall from its peak; `vibrato` is { rate, depth, delay }.
A pattern line is space separated tokens, one a step, with "|" between
bars for the eye only: a note ("A4", "C#5", "Bb3"), "-" to hold the one
before, "." for a rest, or a note with an arpeggio, "A3^037", which
cycles the root up by those semitones (one digit each, or letters a-c for
10-12) every ARP_S seconds: the chip's way of playing a chord on one
channel. A drum step is any of k (kick), s (snare), h (closed hat) and o
(open hat) together, such as "kh", or ".". Every voice line in a pattern
runs the same number of steps. */
// A track not asked for again within this long fades out by itself.
const MUSIC_HOLD_MS = 250 ;
// How far ahead notes are booked, and how often the booking runs: booked
// against the audio clock, so the beat holds even when the page stutters.
const LOOKAHEAD_S = 0.12 ;
const TICK_MS = 25 ;
// The whole of the music sits under the game's own sounds, but clear of the
// engine and wind hums (0.045, then 0.16, were lost under Sunset Drive's engine).
const MUSIC_PEAK = 0.32 ;
// A change of the music volume glides over this long, so a slider drag never clicks.
const VOLUME_S = 0.08 ;
// A change of track (a new level) fades one into the other over this long.
const CROSSFADE_S = 2.5 ;
// One arpeggio step: fast enough to read as a chord.
const ARP_S = 1 / 40 ;
const FLOOR = 0.0001 ;
const NAMES = { C : 0 , D : 2 , E : 4 , F : 5 , G : 7 , A : 9 , B : 11 };
const TRACKS = Object . freeze ( Object . assign ({}, ... MUSIC_TABLES ));
export const musicNames = () => Object . keys ( TRACKS );
// A note's frequency, or NaN: "A4" is 440, "C#5", "Db5".
export function noteFreq ( note ) {
const m = /^([A-G])(#|b)?(-?\d)$/ . exec ( note );
if ( ! m ) return NaN ;
const semis = NAMES [ m [ 1 ]] + ( m [ 2 ] === "#" ? 1 : m [ 2 ] === "b" ? - 1 : 0 ) + ( Number ( m [ 3 ]) + 1 ) * 12 ;
return 440 * 2 ** (( semis - 69 ) / 12 );
}
const arpStep = ( ch ) => ( /\d/ . test ( ch ) ? Number ( ch ) : ch . charCodeAt ( 0 ) - 87 );
// One token of a pitched voice: { freqs } for a note (one, or an arpeggio's
// cycle), "hold", "rest", or null when it is not a token.
function readToken ( token ) {
if ( token === "-" ) return "hold" ;
if ( token === "." ) return "rest" ;
const [ note , arp ] = token . split ( "^" );
const root = noteFreq ( note );
if ( ! Number . isFinite ( root )) return null ;
if ( arp === undefined ) return { freqs : [ root ] };
if ( ! /^[0-9a-c]+$/ . test ( arp )) return null ;
return { freqs : [... arp ]. map (( ch ) => root * 2 ** ( arpStep ( ch ) / 12 )) };
}
const tokens = ( line ) => line . split ( /\s+/ ). filter (( t ) => t && t !== "|" );
// A track turned into steps ready to book, checked as it goes: a track that
// does not read throws, which the suite catches for every listed track.
export function compileTrack ( track ) {
if ( ! ( track . bpm >= 40 && track . bpm <= 240 )) throw new Error ( "bpm out of range" );
2026-11-04 10:24:06 -08:00
const bar = track . bar ?? 16 ;
if ( ! ( Number . isInteger ( bar ) && bar >= 4 && bar <= 64 )) throw new Error ( "bar out of range" );
2026-11-02 12:00:13 -08:00
const voices = Object . keys ( track . voices || {});
if ( ! voices . length ) throw new Error ( "no voices" );
const patterns = {};
for ( const [ id , pattern ] of Object . entries ( track . patterns || {})) {
let length = null ;
const lines = {};
for ( const [ voice , line ] of Object . entries ( pattern )) {
if ( ! voices . includes ( voice )) throw new Error ( ` ${ id } : no voice ${ voice } ` );
const steps = tokens ( line );
if ( length !== null && steps . length !== length ) throw new Error ( ` ${ id } : ${ voice } runs ${ steps . length } steps, not ${ length } ` );
length = steps . length ;
const kit = Boolean ( track . voices [ voice ]. kit );
const notes = [];
steps . forEach (( token , i ) => {
if ( kit ) {
if ( token !== "." && ! /^[ksho]+$/ . test ( token )) throw new Error ( ` ${ id } : ${ voice } step ${ i } " ${ token } " is not a drum` );
if ( token !== "." ) notes . push ({ at : i , len : 1 , drums : token });
return ;
}
const read = readToken ( token );
if ( read === null ) throw new Error ( ` ${ id } : ${ voice } step ${ i } " ${ token } " is not a note` );
if ( read === "hold" ) {
if ( notes . length && notes . at ( - 1 ). at + notes . at ( - 1 ). len === i ) notes . at ( - 1 ). len += 1 ;
return ;
}
if ( read !== "rest" ) notes . push ({ at : i , len : 1 , freqs : read . freqs });
});
lines [ voice ] = notes ;
}
if ( ! length ) throw new Error ( ` ${ id } : empty` );
2026-11-04 10:24:06 -08:00
if ( track . bar !== undefined && length % bar ) throw new Error ( ` ${ id } : ${ length } steps is not whole bars of ${ bar } ` );
2026-11-02 12:00:13 -08:00
patterns [ id ] = { length , lines };
}
const order = track . order || [];
if ( ! order . length || order . some (( id ) => ! patterns [ id ])) throw new Error ( "order names a missing pattern" );
// The song as one list of bars: each entry a pattern and the step it starts on.
let at = 0 ;
const song = order . map (( id ) => {
const part = { id , at };
at += patterns [ id ]. length ;
return part ;
});
return { track , patterns , song , length : at };
}
const compiled = new Map ();
function compiledTrack ( name ) {
if ( ! compiled . has ( name )) compiled . set ( name , compileTrack ( TRACKS [ name ]));
return compiled . get ( name );
}
/* --------------------------------------------------------- the voices */
const pulseWaves = new WeakMap ();
// A pulse wave of `duty`, the chip square: thin at 0.125, hollow at 0.25.
function pulse ( c , duty ) {
if ( typeof c . createPeriodicWave !== "function" ) return null ;
let byDuty = pulseWaves . get ( c );
if ( ! byDuty ) pulseWaves . set ( c , ( byDuty = new Map ()));
if ( ! byDuty . has ( duty )) {
const n = 32 ;
const real = new Float32Array ( n );
const imag = new Float32Array ( n );
for ( let k = 1 ; k < n ; k ++ ) real [ k ] = ( 2 / ( k * Math . PI )) * Math . sin ( k * Math . PI * duty );
byDuty . set ( duty , c . createPeriodicWave ( real , imag ));
}
return byDuty . get ( duty );
}
// One pitched note from t for `seconds`, into `dest`.
function playNote ( a , dest , voice , freqs , t , seconds ) {
const { c } = a ;
const end = t + seconds ;
const osc = c . createOscillator ();
const wave = voice . wave === "pulse" ? pulse ( c , voice . duty ?? 0.5 ) : null ;
if ( wave ) osc . setPeriodicWave ( wave );
else osc . type = voice . wave === "pulse" ? "square" : voice . wave || "square" ;
if ( freqs . length === 1 ) osc . frequency . setValueAtTime ( freqs [ 0 ], t );
else for ( let s = t , i = 0 ; s < end ; s += ARP_S , i ++ ) osc . frequency . setValueAtTime ( freqs [ i % freqs . length ], s );
if ( voice . vibrato && seconds > ( voice . vibrato . delay ?? 0 )) {
const lfo = c . createOscillator ();
const depth = c . createGain ();
lfo . frequency . value = voice . vibrato . rate ;
depth . gain . value = freqs [ 0 ] * voice . vibrato . depth ;
lfo . connect ( depth );
depth . connect ( osc . frequency );
lfo . start ( t + ( voice . vibrato . delay ?? 0 ));
lfo . stop ( end );
}
const gain = c . createGain ();
const peak = Math . max ( FLOOR * 10 , voice . gain ?? 1 );
const held = Math . max ( FLOOR * 10 , peak * ( voice . sustain ?? 0.7 ));
const release = Math . min ( 0.03 , seconds * 0.3 );
gain . gain . setValueAtTime ( FLOOR , t );
gain . gain . linearRampToValueAtTime ( peak , t + 0.004 );
gain . gain . linearRampToValueAtTime ( held , t + Math . max ( 0.005 , Math . min ( seconds * 0.6 , voice . decay ?? 0.06 )));
gain . gain . setValueAtTime ( held , end - release );
gain . gain . linearRampToValueAtTime ( 0 , end );
osc . connect ( gain );
gain . connect ( dest );
osc . start ( t );
osc . stop ( end + 0.01 );
}
// The drum kit: a kick that drops, a snare and hats of noise.
function playDrums ( a , dest , voice , hits , t ) {
const { c } = a ;
const level = voice . gain ?? 1 ;
for ( const hit of hits ) {
if ( hit === "k" ) {
const osc = c . createOscillator ();
const gain = c . createGain ();
osc . type = "sine" ;
osc . frequency . setValueAtTime ( 160 , t );
osc . frequency . exponentialRampToValueAtTime ( 42 , t + 0.11 );
gain . gain . setValueAtTime ( level , t );
gain . gain . exponentialRampToValueAtTime ( FLOOR , t + 0.13 );
osc . connect ( gain );
gain . connect ( dest );
osc . start ( t );
osc . stop ( t + 0.14 );
continue ;
}
const seconds = hit === "s" ? 0.12 : hit === "o" ? 0.16 : 0.035 ;
const src = c . createBufferSource ();
const filter = c . createBiquadFilter ();
const gain = c . createGain ();
src . buffer = a . noise ( "noise" );
filter . type = hit === "s" ? "bandpass" : "highpass" ;
filter . frequency . value = hit === "s" ? 1900 : 7000 ;
filter . Q . value = hit === "s" ? 0.8 : 0.7 ;
gain . gain . setValueAtTime ( level * ( hit === "s" ? 0.8 : 0.4 ), t );
gain . gain . exponentialRampToValueAtTime ( FLOOR , t + seconds );
src . connect ( filter );
filter . connect ( gain );
gain . connect ( dest );
src . start ( t , Math . random () * 1.5 );
src . stop ( t + seconds + 0.01 );
}
}
/* ------------------------------------------------------ the sequencer */
// The track playing now: its name, the bus it plays into, the step next to
// book and when, how hot play is, and when the game last asked for it.
let now = null ;
// Tracks on their way out after the game asked for another: each keeps
// playing under its fading bus until `until`, so a change of level is a
// crossfade, not a cut.
let leaving = [];
let ticker = null ;
// Where each track was, so one comes back in on the bar it left.
const positions = new Map ();
// The music's own gentle compressor, straight to the speakers, as on the
// prototype pages the tracks were picked on (prototypes/music/engine.js): not
// the sounds' harder one, so a blaster shot or a crash never pushes the
// music down. One per audio context.
const musicOuts = new WeakMap ();
function musicOut ( a ) {
const { c } = a ;
if ( typeof c . createDynamicsCompressor !== "function" ) return a . out ;
if ( ! musicOuts . has ( c )) {
const comp = c . createDynamicsCompressor ();
comp . threshold . value = - 14 ;
comp . ratio . value = 4 ;
comp . connect ( c . destination );
musicOuts . set ( c , comp );
}
return musicOuts . get ( c );
}
function startTrack ( a , name , rampS , volume ) {
const bus = a . c . createGain ();
bus . gain . setValueAtTime ( FLOOR , a . c . currentTime );
bus . gain . linearRampToValueAtTime ( MUSIC_PEAK * volume , a . c . currentTime + rampS );
bus . connect ( musicOut ( a ));
const song = compiledTrack ( name );
const was = positions . get ( name ) || 0 ;
2026-11-04 10:24:06 -08:00
return { name , song , bus , step : was - ( was % ( song . track . bar ?? 16 )), next : a . c . currentTime + 0.05 , intensity : 0 , seen : 0 , volume };
2026-11-02 12:00:13 -08:00
}
function letGo ( playing , ms ) {
setTimeout (() => {
try {
playing . bus . disconnect ();
} catch {}
}, ms );
}
// Quiets a track within a moment: the game paused, closed or stopped asking.
function fadeOut ( a , playing ) {
if ( ! playing ) return ;
positions . set ( playing . name , playing . step % playing . song . length );
try {
const t = a ? a . c . currentTime : 0 ;
playing . bus . gain . cancelScheduledValues ( t );
playing . bus . gain . setTargetAtTime ( 0 , t , 0.08 );
letGo ( playing , 800 );
} catch {}
}
// Fades a track out over CROSSFADE_S while it keeps playing.
function crossOut ( a , playing ) {
positions . set ( playing . name , playing . step % playing . song . length );
const t = a . c . currentTime ;
const gain = playing . bus . gain ;
gain . cancelScheduledValues ( t );
gain . setValueAtTime ( Math . max ( FLOOR , gain . value ), t );
gain . linearRampToValueAtTime ( FLOOR , t + CROSSFADE_S );
playing . until = t + CROSSFADE_S ;
leaving . push ( playing );
}
function hushAll ( a ) {
fadeOut ( a , now );
now = null ;
for ( const p of leaving ) fadeOut ( a , p );
leaving = [];
if ( ticker ) clearInterval ( ticker );
ticker = null ;
}
// Books every step of `p` that falls within the lookahead.
function book ( a , p ) {
const song = p . song ;
const track = song . track ;
const stepS = 60 / ( track . bpm + ( track . rush || 0 ) * p . intensity ) / 4 ;
// Behind by more than a beat (a stalled tab): skip ahead rather than rush
// to catch up.
if ( p . next < a . c . currentTime - 0.25 ) p . next = a . c . currentTime + 0.02 ;
for ( let n = 0 ; n < 32 && p . next < a . c . currentTime + LOOKAHEAD_S ; n ++ ) {
const at = p . step % song . length ;
const part = song . song . findLast (( s ) => s . at <= at );
const pattern = song . patterns [ part . id ];
const local = at - part . at ;
for ( const [ name , notes ] of Object . entries ( pattern . lines )) {
const voice = track . voices [ name ];
if ( p . intensity < ( voice . from ?? 0 )) continue ;
for ( const note of notes ) {
if ( note . at !== local ) continue ;
if ( note . drums ) playDrums ( a , p . bus , voice , note . drums , p . next );
else playNote ( a , p . bus , voice , note . freqs , p . next , note . len * stepS * 0.95 );
}
}
p . step += 1 ;
p . next += stepS ;
}
}
function tick () {
const a = audioOut ();
if ( ! now || ! a || ! looks . sound || performance . now () - now . seen > MUSIC_HOLD_MS ) {
hushAll ( a );
return ;
}
try {
book ( a , now );
leaving = leaving . filter (( p ) => {
if ( a . c . currentTime < p . until ) {
book ( a , p );
return true ;
}
letGo ( p , 100 );
return false ;
});
} catch {
hushAll ( a );
}
}
2026-11-04 13:12:56 -08:00
/* ---------------------------------------------------------- the songs
A game may play recorded songs instead: mp3 files named under `songs` in
its `activities/<id>-sfx.js`, a name to a path the server serves. It asks
for one the same way, music(name, intensity, volume, options), every frame
it wants it (the intensity does nothing here), and the song fades out
within MUSIC_HOLD_MS once it stops being asked for, paused where it was, so
a paused game picks it up again mid-song. A song plays once through, never
looped: music() returns "playing" while it does and "ended" once it is
over, which is the game's cue to ask for the next, and { restart: true }
plays it from the top. It returns nothing while it plays nothing. */
const SONGS = Object . freeze ( Object . assign ({}, ... SONG_TABLES ));
export const songNames = () => Object . keys ( SONGS );
// A recording is mastered far louder than the chip voices: this keeps one
// under the game's own sounds at full volume.
export const SONG_PEAK = 0.45 ;
// A song's fade in or out, from silence to SONG_PEAK.
const SONG_FADE_MS = 400 ;
// One element a song, made the first time it is asked for, so nothing is
// downloaded for a game nobody plays.
const songAudio = new Map ();
// The song playing now: its name, its element, the volume it is headed for
// and when the game last asked for it.
let song = null ;
let songTicker = null ;
function songElement ( name ) {
if ( ! songAudio . has ( name )) {
const el = new Audio ( `/ ${ SONGS [ name ] } ` );
el . preload = "auto" ;
el . volume = 0 ;
songAudio . set ( name , el );
}
return songAudio . get ( name );
}
function hushSong () {
if ( songTicker ) clearInterval ( songTicker );
songTicker = null ;
if ( ! song ) return ;
try {
song . el . pause ();
song . el . volume = 0 ;
} catch {}
song = null ;
}
// Glides the volume toward where it is headed; a song no longer asked for
// glides to silence and pauses there.
function songTick () {
const p = song ;
if ( ! p ) return hushSong ();
const held = looks . sound && performance . now () - p . seen <= MUSIC_HOLD_MS ;
const target = held ? p . target : 0 ;
const step = ( SONG_PEAK * TICK_MS ) / SONG_FADE_MS ;
const v = p . el . volume ;
p . el . volume = target > v ? Math . min ( target , v + step ) : Math . max ( target , v - step );
if ( ! held && p . el . volume <= 0 ) hushSong ();
}
function playSong ( name , level , options ) {
if ( typeof Audio !== "function" ) return undefined ;
if ( song && song . name !== name ) hushSong ();
const el = songElement ( name );
// load() is the way back to the top: it needs no seeking, which a file
// served without byte ranges cannot always do.
if ( options && options . restart && ( el . ended || el . currentTime > 0 )) el . load ();
if ( ! song ) song = { name , el , target : 0 , seen : 0 , starting : false };
const p = song ;
p . seen = performance . now ();
p . target = SONG_PEAK * level ;
if ( el . ended ) return "ended" ;
if ( el . paused && ! p . starting ) {
p . starting = true ;
Promise . resolve ( el . play ())
. catch (() => {})
. finally (() => ( p . starting = false ));
}
if ( ! songTicker ) songTicker = setInterval ( songTick , TICK_MS );
return "playing" ;
}
2026-11-02 12:00:13 -08:00
// Keeps the track `name` playing for another moment at `intensity` (0 to 1,
// how hot play is: it brings voices in and pushes the tempo). Asking for a
// different track crossfades from the last one to this one over
// CROSSFADE_S. `volume` (0 to 1) scales the whole track; at 0 it is not
// asked for, so it fades out. Silence, never an error, while Play sounds is
2026-11-04 13:12:56 -08:00
// off or audio cannot play. A song (above) plays instead when `name` is one,
// and what it returns is the song's "playing" or "ended".
export function music ( name , intensity = 0.5 , volume = 1 , options = undefined ) {
2026-11-02 12:00:13 -08:00
try {
const level = Math . min ( 1 , Math . max ( 0 , Number ( volume ) || 0 ));
2026-11-04 13:12:56 -08:00
if ( ! looks . sound || level <= 0 ) return undefined ;
if ( Object . hasOwn ( SONGS , name )) return playSong ( name , level , options );
if ( ! Object . hasOwn ( TRACKS , name )) return ;
2026-11-02 12:00:13 -08:00
const a = audioOut ();
if ( ! a ) return ;
let ramp = 0.25 ;
if ( now && now . name !== name ) {
crossOut ( a , now );
now = null ;
ramp = CROSSFADE_S ;
}
if ( ! now ) now = startTrack ( a , name , ramp , level );
else if ( now . volume !== level ) {
// A slider moved: glide there from wherever the bus is now, which
// also cuts short a fade-in still on its way.
const t = a . c . currentTime ;
now . bus . gain . cancelScheduledValues ( t );
now . bus . gain . setValueAtTime ( Math . max ( FLOOR , now . bus . gain . value ), t );
now . bus . gain . setTargetAtTime ( MUSIC_PEAK * level , t , VOLUME_S );
now . volume = level ;
}
now . seen = performance . now ();
now . intensity = Math . min ( 1 , Math . max ( 0 , Number ( intensity ) || 0 ));
if ( ! ticker ) {
ticker = setInterval ( tick , TICK_MS );
book ( a , now );
}
} catch {}
}
// Quiets the music at once: the window stopped ticking a game.
export function hushMusic () {
hushAll ( audioOut ());
2026-11-04 13:12:56 -08:00
hushSong ();
2026-11-02 12:00:13 -08:00
}