picopilot 0.2.1 → 0.3.0

package/src/commands/audio.ts

@@ -9,6 +9,13 @@ import {tmpdir} from 'node:os';
 import {isAbsolute, join, resolve} from 'node:path';
 import {Cli, z} from 'incur';
 
+import {
+	analyzeAudio,
+	type AudioAnalysis,
+	AudioAnalyzeError,
+	decodeWav,
+	THRESHOLDS,
+} from '../engine/audio/index.js';
 import {
 	buildRecordHarness,
 	buildRenderHarness,
@@ -39,11 +46,48 @@ export type {Pico8AdapterFactory} from './pico8-env.js';
 const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /**
- * The default record backstop: kill a capture that never signals after this many
- * ms. Larger than `run`'s default because a record window is a real-time playback
- * (up to several seconds) plus PICO-8 startup, not a quick screenshot pass.
+ * The startup margin added to the record window for the default backstop. A
+ * recording is real time, so the backstop must cover PICO-8 startup (a virtual
+ * display, loading the cart) PLUS the whole record window. A fixed 30 s backstop
+ * used to kill any window of ~24 s or more before `audio_end`.
+ */
+export const RECORD_STARTUP_MARGIN_MS = 30_000;
+
+/** The least startup time an explicit backstop must leave beyond the window. */
+export const RECORD_MIN_STARTUP_MS = 5_000;
+
+/**
+ * The backstop for a record window: the explicit `--backstop-ms` when it leaves
+ * at least {@link RECORD_MIN_STARTUP_MS} for startup, else a refusal; or, when
+ * none is given, the window plus {@link RECORD_STARTUP_MARGIN_MS}.
  */
-const DEFAULT_BACKSTOP_MS = 30_000;
+export function resolveRecordBackstop(
+	seconds: number,
+	explicit: number | undefined,
+): {ok: true; ms: number} | {ok: false; message: string} {
+	const windowMs = Math.ceil(seconds * 1000);
+	if (explicit === undefined) {
+		return {ok: true, ms: windowMs + RECORD_STARTUP_MARGIN_MS};
+	}
+	const least = windowMs + RECORD_MIN_STARTUP_MS;
+	if (explicit < least) {
+		return {
+			ok: false,
+			message: `--backstop-ms ${explicit} is too small for a ${seconds} s record window: PICO-8 would be killed before the recording ends (it also needs a few seconds to start). Use at least ${least}, or omit --backstop-ms (the default is the window + ${RECORD_STARTUP_MARGIN_MS / 1000} s).`,
+		};
+	}
+	return {ok: true, ms: explicit};
+}
+
+/** The `--backstop-ms` option both audio subcommands share. */
+const BACKSTOP_OPTION = z
+	.number()
+	.int()
+	.positive()
+	.optional()
+	.describe(
+		`Safety backstop: kill PICO-8 after this many ms if it never signals. Default: the record window + ${RECORD_STARTUP_MARGIN_MS / 1000} s of startup margin. An explicit value smaller than the window + ${RECORD_MIN_STARTUP_MS / 1000} s is refused.`,
+	);
 
 /** The honest one-liner both `record` and `render` carry (ADR-0009): not offline. */
 const HONEST_CAVEAT =
@@ -75,6 +119,98 @@ function chooseWavDir(given: string | undefined): string {
 /** The env schema both audio subcommands share (locates the binary). */
 const AUDIO_ENV = PICO8_ENV;
 
+/** The structured analysis of a recording (`audio analyze`, `--analyze`). */
+const ANALYSIS_OUTPUT = z.object({
+	sampleRate: z.number(),
+	durationSeconds: z.number(),
+	skippedSeconds: z
+		.number()
+		.describe('Seconds skipped at the start (PICO-8 startup).'),
+	analyzedSeconds: z.number(),
+	loudness: z.object({
+		meanRms: z
+			.number()
+			.describe(
+				`Mean RMS of 2048-sample frames (0-1). Accepted game music: 0.07-0.10; over ${THRESHOLDS.loudMeanRms} warns.`,
+			),
+		medianRms: z.number(),
+		peakFrameRms: z.number().describe('The loudest frame.'),
+		peakFrameAtSeconds: z
+			.number()
+			.describe('When the loudest frame starts (s from file start).'),
+		peakSample: z.number().describe('99.9th-percentile absolute sample.'),
+		silentPercent: z.number().describe('Share of silent frames (%).'),
+	}),
+	brightness: z.object({
+		centroidHz: z
+			.number()
+			.describe(
+				`Median spectral centroid (Hz). Accepted: under 500; over ${THRESHOLDS.shrillCentroidHz} is shrill.`,
+			),
+		above2kHzPercent: z
+			.number()
+			.describe(
+				`Share of energy above 2 kHz (%). Accepted: about 0.2; over ${THRESHOLDS.shrillAbove2kHzPercent} is shrill.`,
+			),
+	}),
+	dynamicRangeDb: z
+		.number()
+		.describe(
+			`p90 - p10 of frame level, silence excluded (dB). Accepted: 7-8; under ${THRESHOLDS.flatRangeDb} is monotonous.`,
+		),
+	profile: z.object({
+		stepSeconds: z.number(),
+		rms: z.array(z.number()),
+		sparkline: z.string().describe('The loudness profile as a bar chart.'),
+	}),
+	loop: z
+		.object({
+			seconds: z.number().nullable(),
+			confidence: z.number().optional(),
+			reason: z.string().optional(),
+		})
+		.describe(
+			'The repetition length (needs the loop to appear twice in the recording).',
+		),
+	against: z
+		.object({referenceRms: z.number(), musicOverReferenceDb: z.number()})
+		.optional(),
+	warnings: z
+		.array(z.object({code: z.string(), message: z.string()}))
+		.describe('Plain-language findings; empty = nothing flagged.'),
+});
+
+/** The `--analyze` option of record/render. */
+const ANALYZE_OPTION = z
+	.boolean()
+	.default(false)
+	.describe(
+		'Also analyze the captured WAV (loudness, brightness, dynamic range, profile, loop length, warnings), as `audio analyze` does.',
+	);
+
+/**
+ * Analyzes a captured WAV for `--analyze`, or explains why it could not. Never
+ * fails the recording itself.
+ */
+function analyzeCapture(
+	wavPath: string | undefined,
+	kind: 'music' | 'sfx',
+): {analysis: AudioAnalysis} | {analysisError: string} | undefined {
+	if (wavPath === undefined) return undefined;
+	try {
+		// An SFX render starts recording on the frame the SFX starts: skip
+		// nothing, or a short SFX would be measured on its silent tail only.
+		return {
+			analysis: analyzeAudio(decodeWav(readFileSync(wavPath)), {
+				kind,
+				skipSeconds: kind === 'sfx' ? 0 : 1,
+			}),
+		};
+	} catch (e) {
+		return {analysisError: e instanceof Error ? e.message : String(e)};
+	}
+}
+
 /** The structured output shape shared by `record` and `render`. */
 const AUDIO_OUTPUT = z.object({
 	wav: z
@@ -118,6 +254,13 @@ const AUDIO_OUTPUT = z.object({
 		.describe(
 			"When no WAV was captured: the tail of PICO-8's own log.txt (load errors, SDL init failures).",
 		),
+	analysis: ANALYSIS_OUTPUT.optional().describe(
+		'With --analyze: the analysis of the captured WAV.',
+	),
+	analysisError: z
+		.string()
+		.optional()
+		.describe('With --analyze: why the WAV could not be analyzed.'),
 });
 
 /**
@@ -182,7 +325,7 @@ function recordOutput(
 function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 	const audio = Cli.create('audio', {
 		description:
-			'Get a WAV out of a cart by RECORDING a running session (ADR-0009). PICO-8 has no working offline WAV export, so both commands are REAL-TIME recordings of a -run session, NOT deterministic offline exports. They work headless: with no display, picopilot runs the session on a private virtual display (ADR-0017). Requires PICO-8.',
+			'Get a WAV out of a cart by RECORDING a running session (ADR-0009), and measure it. PICO-8 has no working offline WAV export, so `record` and `render` are REAL-TIME recordings of a -run session, NOT deterministic offline exports; they work headless (with no display, picopilot runs the session on a private virtual display, ADR-0017) and require PICO-8. `analyze` measures a WAV (loudness, brightness, dynamics, loop length) and needs nothing.',
 	});
 
 	// --- audio record <cart> ---------------------------------------------------
@@ -212,14 +355,8 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				.string()
 				.default(DONE_SENTINEL)
 				.describe('The stdout line that ends the recording.'),
-			backstopMs: z
-				.number()
-				.int()
-				.positive()
-				.default(DEFAULT_BACKSTOP_MS)
-				.describe(
-					'Safety backstop: kill PICO-8 after this many ms if it never signals.',
-				),
+			backstopMs: BACKSTOP_OPTION,
+			analyze: ANALYZE_OPTION,
 			display: DISPLAY_OPTION,
 		}),
 		env: AUDIO_ENV,
@@ -258,6 +395,18 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				throw e;
 			}
 
+			const backstop = resolveRecordBackstop(
+				harness.seconds,
+				options.backstopMs,
+			);
+			if (!backstop.ok) {
+				return error({
+					code: 'audio-backstop-too-small',
+					message: backstop.message,
+					exitCode: 1,
+				});
+			}
+
 			// The throwaway harness cart + the WAV both live in the isolated dir, so a
 			// record run never mutates the user's cart or writes outside the temp dir.
 			const wavDir = chooseWavDir(options.wavDir);
@@ -274,12 +423,17 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				wavDir,
 				wavBasename: harness.wavBasename,
 				sentinel: options.sentinel,
-				backstopMs: options.backstopMs,
+				backstopMs: backstop.ms,
 			});
 
 			if (!result.ok) return error(recordFailure('audio record', result));
 
-			const out = recordOutput(result.value, harness);
+			const out = {
+				...recordOutput(result.value, harness),
+				...(options.analyze
+					? analyzeCapture(result.value.wavPath, 'music')
+					: {}),
+			};
 			return ok(
 				out,
 				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
@@ -334,14 +488,8 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				.string()
 				.default(DONE_SENTINEL)
 				.describe('The stdout line that ends the recording.'),
-			backstopMs: z
-				.number()
-				.int()
-				.positive()
-				.default(DEFAULT_BACKSTOP_MS)
-				.describe(
-					'Safety backstop: kill PICO-8 after this many ms if it never signals.',
-				),
+			backstopMs: BACKSTOP_OPTION,
+			analyze: ANALYZE_OPTION,
 			display: DISPLAY_OPTION,
 		}),
 		env: AUDIO_ENV,
@@ -395,6 +543,18 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				throw e;
 			}
 
+			const backstop = resolveRecordBackstop(
+				harness.seconds,
+				options.backstopMs,
+			);
+			if (!backstop.ok) {
+				return error({
+					code: 'audio-backstop-too-small',
+					message: backstop.message,
+					exitCode: 1,
+				});
+			}
+
 			const wavDir = chooseWavDir(options.wavDir);
 			const harnessCart = join(wavDir, 'render-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
@@ -409,12 +569,20 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				wavDir,
 				wavBasename: harness.wavBasename,
 				sentinel: options.sentinel,
-				backstopMs: options.backstopMs,
+				backstopMs: backstop.ms,
 			});
 
 			if (!result.ok) return error(recordFailure('audio render', result));
 
-			const out = recordOutput(result.value, harness);
+			const out = {
+				...recordOutput(result.value, harness),
+				...(options.analyze
+					? analyzeCapture(
+							result.value.wavPath,
+							target.kind === 'sfx' ? 'sfx' : 'music',
+						)
+					: {}),
+			};
 			return ok(
 				out,
 				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
@@ -422,12 +590,101 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 		},
 	});
 
+	// --- audio analyze <wav> ----------------------------------------------------
+	audio.command('analyze', {
+		description: `Measure a WAV (from \`audio render\` / \`audio record\`) so a model that cannot hear can judge it: loudness (mean/peak RMS, loudest moment), brightness (spectral centroid, energy above 2 kHz), dynamic range, a loudness profile per half second, and the loop length, plus plain-language warnings (loud, shrill, monotonous, spikes, repetitive). Skips the first second by default (as the calibration did); thresholds are for music, \`--kind sfx\` keeps only the checks that apply to a one-shot sound. --against <sfx.wav> compares the music's loudness with a rendered SFX, so the music sits under the SFX. Pure TypeScript: needs neither PICO-8 nor Python.`,
+		args: z.object({
+			wav: z.string().describe('The WAV file to analyze.'),
+		}),
+		options: z.object({
+			skip: z.coerce
+				.number()
+				.min(0)
+				.default(1)
+				.describe(
+					'Seconds to skip at the start (default 1, as in the calibration; use 0 for an SFX render). Ignored when the WAV is too short for it.',
+				),
+			kind: z
+				.enum(['music', 'sfx'])
+				.default('music')
+				.describe(
+					'music: every warning; sfx: a one-shot sound, only near-silent / near-clipping (the music thresholds do not apply).',
+				),
+			against: z
+				.string()
+				.optional()
+				.describe(
+					'A reference SFX WAV (e.g. from `audio render --sfx 7`): report the music level relative to it and warn when the music is not quieter.',
+				),
+		}),
+		output: ANALYSIS_OUTPUT,
+		examples: [
+			{
+				description: 'Analyze a rendered song',
+				args: {wav: '/tmp/picopilot-audio-x/picopilot-audio.wav'},
+			},
+			{
+				description: 'Check the music sits under an SFX',
+				args: {wav: 'music.wav'},
+				options: {against: 'explosion.wav'},
+			},
+		],
+		run({args, options, error, ok}) {
+			const read = (p: string) => {
+				const abs = resolvePath(p);
+				if (!existsSync(abs)) {
+					throw new AudioAnalyzeError(
+						'audio-analyze-bad-wav',
+						`no WAV at ${abs}`,
+					);
+				}
+				return decodeWav(readFileSync(abs));
+			};
+			let analysis: AudioAnalysis;
+			try {
+				analysis = analyzeAudio(read(args.wav), {
+					skipSeconds: options.skip,
+					kind: options.kind,
+					...(options.against !== undefined
+						? {against: read(options.against)}
+						: {}),
+				});
+			} catch (e) {
+				if (e instanceof AudioAnalyzeError) {
+					return error({code: e.code, message: e.message, exitCode: 1});
+				}
+				throw e;
+			}
+			return ok(
+				analysis,
+				analysis.warnings.length > 0
+					? {
+							cta: {
+								description:
+									'Fix the flagged issues in the score, then measure again:',
+								commands: [
+									{
+										command: 'music from-score --file <score.json>',
+										description: 'Rewrite the music.',
+									},
+									{
+										command: 'audio render --pattern <n> --analyze',
+										description: 'Record and analyze it again.',
+									},
+								],
+							},
+						}
+					: undefined,
+			);
+		},
+	});
+
 	return audio;
 }
 
 /**
- * Registers the `audio` command group (`audio record`, `audio render`) on the
- * root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
+ * Registers the `audio` command group (`audio record`, `audio render`, `audio
+ * analyze`) on the root CLI. PICO-8-gated (ADR-0009): audio-to-WAV is a record of a running
  * session, never an offline export. `adapterFactory` is injected so tests drive
  * the orchestration against a fake runner (no paid binary in CI).
  */

package/src/commands/doctor.test.ts

@@ -144,6 +144,7 @@ describe('picopilot doctor', () => {
 			'gfx show / set / render',
 			'sfx',
 			'music',
+			'audio analyze',
 		]);
 	});
 });

package/src/commands/doctor.ts

@@ -73,6 +73,7 @@ const COMMAND_NEEDS: readonly {command: string; needs: readonly Need[]}[] = [
 	{command: 'run --record-audio', needs: ['pico8', 'display']},
 	{command: 'audio record', needs: ['pico8', 'display']},
 	{command: 'audio render', needs: ['pico8', 'display']},
+	{command: 'audio analyze', needs: []},
 ];
 
 /** The PICO-8 version from its install path (e.g. `.../pico-8-0.2.7/...`), if it names one. */

package/src/commands/music.test.ts

@@ -270,3 +270,122 @@ describe('picopilot music from-patterns: input surface (arg vs --file)', () => {
 		expect(JSON.parse(stdout).code).toBe('cart-not-found');
 	});
 });
+
+/** The __sfx__ body lines of a cart file. */
+function sfxLines(text: string): string[] {
+	const m = text.match(/__sfx__\n([\s\S]*?)(?:\n__|$)/);
+	return (m?.[1] ?? '').split('\n').filter((l) => l.length > 0);
+}
+
+describe('picopilot music from-score (ADR-0020)', () => {
+	const gameSfx = mmlToSfxRow('s4 @3 v6 c e g').row;
+
+	it('writes two songs, reports start patterns, and leaves other content alone', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const score = {
+			songs: [
+				{name: 'title', speed: 16, channels: ['l32 c d', 'o1 l64 c', null]},
+				{name: 'game', speed: 20, channels: [null, 'o1 l16 g d g d']},
+			],
+		};
+		const scoreFile = join(dir, 'score.json');
+		writeFileSync(scoreFile, JSON.stringify(score));
+		const before = readFileSync(cartPath, 'utf8');
+		const {stdout, exitCode} = await runMusic([
+			'music',
+			'from-score',
+			'--file',
+			scoreFile,
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(
+			out.songs.map((s: {name: string; startPattern: number}) => [
+				s.name,
+				s.startPattern,
+			]),
+		).toEqual([
+			['title', 0],
+			['game', 2],
+		]);
+		expect(out.patterns).toBe(4);
+		const after = readFileSync(cartPath, 'utf8');
+		// Slot 0 (the game SFX), __lua__ and __gfx__ are byte-identical.
+		expect(sfxLines(after)[0]).toBe(gameSfx);
+		expect(after.split('__sfx__')[0]).toBe(before.split('__sfx__')[0]);
+		// Free slots are used from 63 down; slot 0 is never touched.
+		expect(out.slots.every((s: {slot: number}) => s.slot > 0)).toBe(true);
+		expect(out.slots.every((s: {overwrote: boolean}) => !s.overwrote)).toBe(
+			true,
+		);
+		// The game song's first channel is off in every pattern.
+		const music = musicLines(after);
+		expect(music).toHaveLength(4);
+		for (const line of music.slice(2)) expect(line.slice(3, 5)).toBe('40');
+	});
+
+	it('--slots owns a range: re-running is idempotent (byte-identical cart)', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const score = JSON.stringify({channels: ['l32 c d', 'o1 l64 c']});
+		const argv = [
+			'music',
+			'from-score',
+			score,
+			'--cart',
+			cartPath,
+			'--slots',
+			'40-50',
+			'--json',
+		];
+		const first = await runMusic(argv);
+		expect(first.exitCode).toBe(0);
+		const once = readFileSync(cartPath, 'utf8');
+		await runMusic(argv);
+		expect(readFileSync(cartPath, 'utf8')).toBe(once);
+		const slots = JSON.parse(first.stdout).slots.map(
+			(s: {slot: number}) => s.slot,
+		);
+		expect(slots.every((s: number) => s >= 40 && s <= 50)).toBe(true);
+	});
+
+	it('a bad score never touches the cart', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const before = readFileSync(cartPath, 'utf8');
+		for (const score of [
+			'{',
+			'{"channels":["o5 g"]}',
+			'{"channels":["{c}"]}',
+		]) {
+			const {stdout, exitCode} = await runMusic([
+				'music',
+				'from-score',
+				score,
+				'--cart',
+				cartPath,
+				'--json',
+			]);
+			expect(exitCode, score).not.toBe(0);
+			expect(stdout).toMatch(/audio-(score|mml)-/);
+		}
+		expect(readFileSync(cartPath, 'utf8')).toBe(before);
+	});
+
+	it('refuses a non-contiguous --slots', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runMusic([
+			'music',
+			'from-score',
+			'{"channels":["c"]}',
+			'--cart',
+			cartPath,
+			'--slots',
+			'3,9',
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('audio-score-bad-slot-range');
+	});
+});