2026-11-02 12:00:13 -08:00
// Plan2Code Web Console - the games' music: a small chiptune sequencer over tones.js's audio, silent unless Play sounds and the game's own switches allow it; defines only.
import { looks } from "./looks.js" ;
import { MUSIC_TABLES , audioOut } from "./tones.js" ;
/* -------------------------------------------------------------- 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 );
}
}
// 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
// off or audio cannot play.
export function music ( name , intensity = 0.5 , volume = 1 ) {
try {
const level = Math . min ( 1 , Math . max ( 0 , Number ( volume ) || 0 ));
if ( ! Object . hasOwn ( TRACKS , name ) || ! looks . sound || level <= 0 ) return ;
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 ());
}