Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Chiptune score contract (#2911) — the versioned JSON shape an LLM emits for
* a looping 8-bit background-music score, plus the pure math that turns it
* into absolute-time note events.
*
* One score = NES-style channels (two pulse waves, a triangle bass, a noise
* drum lane), a bank of named patterns, and an `order` list that sequences
* patterns into one seamless loop. Loop length is whole-pattern by
* construction: total steps = sum of the ordered patterns' steps, so the
* render/preview can loop sample-exactly with no tail math.
*
* Consumed by:
* - server/lib/chiptuneRender.js — offline PCM/WAV render (deterministic)
* - server/services/chiptune.js — LLM generation (responseSchema) + publish
* - server/services/tracks/logic.js — track sanitizer (sanitizeChiptuneScore)
* - client/src/lib/chiptunePlayback.js — WebAudio preview (MIRRORS
* buildScoreEvents' timing semantics; keep the two in lockstep)
*/
import { z } from 'zod';
import { pitchToMidi, midiToFreq } from './pitchMath.js';
export const CHIPTUNE_SCORE_VERSION = 1;
// Bounds — shared by the Zod schema, the LLM prompt contract, and the tests.
export const CHIPTUNE_LIMITS = Object.freeze({
BPM_MIN: 40,
BPM_MAX: 240,
STEPS_PER_BEAT_MAX: 8,
BEATS_PER_BAR_MAX: 12,
BARS_PER_PATTERN_MAX: 16,
PATTERNS_MAX: 8,
ORDER_MAX: 32,
NOTES_PER_CHANNEL_MAX: 512,
TOTAL_STEPS_MAX: 8192,
// Wall-clock cap on the loop. Steps alone don't bound duration (40 BPM at
// 1 step/beat = 1.5s per step), and the offline renderer allocates
// ~176 KB/sec of PCM — an unbounded schema-valid score could demand
// gigabytes from one errant LLM response. 3 minutes is far beyond any
// sane background loop.
MAX_LOOP_SEC: 180,
// Aggregate cap on VOICED time (sum of every note's clamped length across
// the order walk). The loop-duration cap bounds the output buffer but not
// the render work: hundreds of full-loop overlapping notes would each spin
// the per-sample synth loop for the whole piece (billions of iterations
// from one errant response). 4 channels × MAX_LOOP_SEC fully voiced = 720s
// is the physical ceiling of distinct-channel audio; anything past it is
// pure overdraw.
NOTE_SECONDS_MAX: 720,
// Event-density ceiling (notes per second across the whole loop). The
// browser preview creates 1-2 AudioNodes per note per loop pass — a
// schema-valid quarter-second loop stuffed with 2 000 notes would mint
// thousands of nodes per second and freeze the Music studio. Real chiptune
// rarely exceeds ~20 notes/sec across four channels.
EVENTS_PER_SEC_MAX: 64,
TITLE_MAX: 120,
});
// The fixed channel palette. `wave` is constrained per id so the LLM can't
// put a noise lane on a pulse channel (the renderer keys drum presets off it).
export const CHIPTUNE_CHANNEL_IDS = Object.freeze(['pulse1', 'pulse2', 'triangle', 'noise']);
export const CHIPTUNE_NOISE_PRESETS = Object.freeze(['kick', 'snare', 'hat', 'open-hat']);
const patternNameField = z.string().regex(/^[A-Za-z0-9_-]{1,16}$/);
const noteSchema = z.object({
step: z.number().int().min(0).max(CHIPTUNE_LIMITS.TOTAL_STEPS_MAX),
// Tonal channels: scientific pitch ("C4", "F#3", "Bb2"). Noise channel: a
// drum preset name (kick/snare/hat/open-hat). Validated leniently here (the
// event builder drops what it can't resolve) so one odd note can't reject a
// whole otherwise-good generation.
pitch: z.string().trim().min(1).max(12),
len: z.number().int().min(1).max(CHIPTUNE_LIMITS.TOTAL_STEPS_MAX),
vel: z.number().min(0).max(1).optional(),
});
const channelSchema = z.object({
id: z.enum(CHIPTUNE_CHANNEL_IDS),
wave: z.enum(['square', 'triangle', 'noise']),
duty: z.number().min(0.05).max(0.95).optional(),
gain: z.number().min(0).max(1).optional(),
});
const patternSchema = z.object({
bars: z.number().int().min(1).max(CHIPTUNE_LIMITS.BARS_PER_PATTERN_MAX),
// Keys are plain strings here (zod 4 treats enum-keyed records as
// exhaustive); the superRefine below rejects keys that aren't declared
// channel ids, which also gives a better error message.
notes: z.record(
z.string().max(16),
z.array(noteSchema).max(CHIPTUNE_LIMITS.NOTES_PER_CHANNEL_MAX),
),
});
export const chiptuneScoreSchema = z.object({
version: z.literal(CHIPTUNE_SCORE_VERSION),
title: z.string().trim().max(CHIPTUNE_LIMITS.TITLE_MAX).optional(),
bpm: z.number().min(CHIPTUNE_LIMITS.BPM_MIN).max(CHIPTUNE_LIMITS.BPM_MAX),
stepsPerBeat: z.number().int().min(1).max(CHIPTUNE_LIMITS.STEPS_PER_BEAT_MAX),
beatsPerBar: z.number().int().min(1).max(CHIPTUNE_LIMITS.BEATS_PER_BAR_MAX),
channels: z.array(channelSchema).min(1).max(CHIPTUNE_CHANNEL_IDS.length),
patterns: z.record(patternNameField, patternSchema)
.refine((p) => {
const n = Object.keys(p).length;
return n >= 1 && n <= CHIPTUNE_LIMITS.PATTERNS_MAX;
}, { message: `patterns must contain 1–${CHIPTUNE_LIMITS.PATTERNS_MAX} entries` }),
order: z.array(patternNameField).min(1).max(CHIPTUNE_LIMITS.ORDER_MAX),
}).superRefine((score, ctx) => {
const channelIds = new Set(score.channels.map((c) => c.id));
if (channelIds.size !== score.channels.length) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['channels'], message: 'channel ids must be unique' });
}
// The channel palette is fixed NES-style: the id determines the waveform.
// Left unbound, `{ id: 'pulse1', wave: 'noise' }` validates and then every
// melody note on that channel silently drops (pitches aren't drum presets) —
// persisting a broken score instead of triggering the runner's schema retry.
for (const [i, c] of score.channels.entries()) {
const expected = c.id === 'noise' ? 'noise' : c.id === 'triangle' ? 'triangle' : 'square';
if (c.wave !== expected) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['channels', i, 'wave'], message: `channel "${c.id}" must use wave "${expected}"` });
}
}
for (const name of score.order) {
// Object.hasOwn, not truthiness: an order entry like "toString" or
// "constructor" resolves through the prototype chain to a function
// (truthy), then every downstream `.bars` read is undefined → NaN math.
if (!Object.hasOwn(score.patterns, name)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['order'], message: `order references unknown pattern "${name}"` });
return;
}
}
for (const [name, pattern] of Object.entries(score.patterns)) {
for (const channelId of Object.keys(pattern.notes || {})) {
if (!channelIds.has(channelId)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ['patterns', name, 'notes'],
message: `pattern "${name}" writes to undeclared channel "${channelId}"`,
});
}
}
}
// The order loop above already returned on any unknown pattern, so the
// shared step math is safe to reuse here (one formula, not two).
const totalSteps = scoreTotalSteps(score);
if (totalSteps > CHIPTUNE_LIMITS.TOTAL_STEPS_MAX) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['order'], message: `loop is too long (${totalSteps} steps > ${CHIPTUNE_LIMITS.TOTAL_STEPS_MAX})` });
}
const stepSec = 60 / (score.bpm * score.stepsPerBeat);
const totalSec = totalSteps * stepSec;
if (totalSec > CHIPTUNE_LIMITS.MAX_LOOP_SEC) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['order'], message: `loop is too long (${Math.round(totalSec)}s > ${CHIPTUNE_LIMITS.MAX_LOOP_SEC}s)` });
}
// Bound the aggregate VOICED time the renderer will synthesize (see
// NOTE_SECONDS_MAX) — the duration cap alone doesn't bound overlapping-note
// render work — plus event density (see EVENTS_PER_SEC_MAX, the browser
// preview's AudioNode budget) and require at least one AUDIBLE event, so an
// all-rests / all-unparseable / all-muted response triggers the runner's
// schema retry instead of persisting a silent "successful" composition.
// Mirrors buildScoreEvents' semantics (len clamped to the pattern end;
// out-of-pattern notes contribute nothing; a tonal pitch must parse, a
// noise pitch must be a known preset).
const channelById = new Map(score.channels.map((c) => [c.id, c]));
let voicedSteps = 0;
let eventCount = 0;
let audible = 0;
for (const name of score.order) {
const pattern = score.patterns[name];
const steps = pattern.bars * score.beatsPerBar * score.stepsPerBeat;
for (const [channelId, notes] of Object.entries(pattern.notes || {})) {
const channel = channelById.get(channelId);
for (const note of notes) {
if (note.step >= steps) continue;
voicedSteps += Math.min(note.len, steps - note.step);
eventCount += 1;
if (!channel || (channel.gain ?? 0.5) === 0 || (note.vel ?? 0.8) === 0) continue;
const sounds = channel.wave === 'noise'
? CHIPTUNE_NOISE_PRESETS.includes(note.pitch)
: pitchToMidi(note.pitch) != null;
if (sounds) audible += 1;
}
}
}
if (voicedSteps * stepSec > CHIPTUNE_LIMITS.NOTE_SECONDS_MAX) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['patterns'], message: `too much voiced audio (${Math.round(voicedSteps * stepSec)}s of notes > ${CHIPTUNE_LIMITS.NOTE_SECONDS_MAX}s)` });
}
if (totalSec > 0 && eventCount / totalSec > CHIPTUNE_LIMITS.EVENTS_PER_SEC_MAX) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['patterns'], message: `too many notes for the loop length (${Math.round(eventCount / totalSec)}/s > ${CHIPTUNE_LIMITS.EVENTS_PER_SEC_MAX}/s)` });
}
if (audible === 0) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['patterns'], message: 'score has no audible notes (every note is out of range, unparseable, or muted)' });
}
});
/**
* Validate an untrusted value into a canonical score, or null. Used by the
* track sanitizer (absent/invalid → null = "no score", per the sentinel rule).
*/
export function sanitizeChiptuneScore(raw) {
if (!raw || typeof raw !== 'object') return null;
const parsed = chiptuneScoreSchema.safeParse(raw);
return parsed.success ? parsed.data : null;
}
/** Seconds per sequencer step. */
export const scoreStepSec = (score) => 60 / (score.bpm * score.stepsPerBeat);
/** Steps in one pattern. */
export const patternSteps = (score, pattern) => pattern.bars * score.beatsPerBar * score.stepsPerBeat;
/** Total loop length in steps (the order walk). */
export function scoreTotalSteps(score) {
return score.order.reduce((sum, name) => sum + patternSteps(score, score.patterns[name]), 0);
}
/** Total loop length in seconds — whole-step exact, so loops are seamless. */
export const scoreDurationSec = (score) => scoreTotalSteps(score) * scoreStepSec(score);
/**
* Flatten a validated score into absolute-time events, one per sounding note:
* { channelId, wave, duty, gain, freq|null, noise|null, startSec, durSec, vel }
*
* Timing semantics (MIRRORED by client/src/lib/chiptunePlayback.js — keep in
* lockstep): the order walk lays patterns back to back; a note sounds at
* (patternBase + step) · stepSec for len · stepSec seconds. Notes that start
* past their pattern's end are dropped; notes that overhang it are clamped so
* nothing bleeds past the loop boundary (loop-safe by construction). A tonal
* pitch that doesn't parse (or an unknown noise preset) drops just that note.
*/
export function buildScoreEvents(score) {
const stepSec = scoreStepSec(score);
const channelsById = new Map(score.channels.map((c) => [c.id, c]));
const events = [];
let baseStep = 0;
for (const name of score.order) {
const pattern = score.patterns[name];
const steps = patternSteps(score, pattern);
for (const [channelId, notes] of Object.entries(pattern.notes || {})) {
const channel = channelsById.get(channelId);
if (!channel) continue;
for (const note of notes) {
if (note.step >= steps) continue;
const lenSteps = Math.min(note.len, steps - note.step);
const isNoise = channel.wave === 'noise';
const noise = isNoise
? (CHIPTUNE_NOISE_PRESETS.includes(note.pitch) ? note.pitch : null)
: null;
const freq = isNoise ? null : midiToFreq(pitchToMidi(note.pitch));
if (isNoise ? !noise : !freq) continue;
events.push({
channelId,
wave: channel.wave,
duty: channel.duty ?? 0.5,
gain: channel.gain ?? 0.5,
freq,
noise,
startSec: (baseStep + note.step) * stepSec,
durSec: lenSteps * stepSec,
vel: note.vel ?? 0.8,
});
}
}
baseStep += steps;
}
events.sort((a, b) => a.startSec - b.startSec);
return { events, stepSec, totalSteps: baseStep, totalSec: baseStep * stepSec };
}