picopilot 0.2.0 → 0.3.0

package/src/commands/audio.test.ts

@@ -10,6 +10,7 @@ import {homedir, tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {Cli} from 'incur';
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {encodeWav16} from '../engine/audio/analyze.js';
 import {mmlToSfxRow} from '../engine/audio/sfx.js';
 import {mergeSfxRow} from '../engine/audio/section.js';
 import {Cart} from '../engine/cart/index.js';
@@ -20,7 +21,12 @@ import type {
 	RunOptions,
 } from '../engine/pico8/index.js';
 import {displayUnavailable, pico8NotFound} from '../engine/pico8/index.js';
-import {type Pico8AdapterFactory, registerAudio} from './audio.js';
+import {
+	type Pico8AdapterFactory,
+	RECORD_STARTUP_MARGIN_MS,
+	registerAudio,
+	resolveRecordBackstop,
+} from './audio.js';
 
 const HEADER = 'pico-8 cartridge // http://www.pico-8.com\nversion 42\n';
 
@@ -353,3 +359,166 @@ describe('audio record/render: headless (ADR-0017)', () => {
 		expect(out.pico8LogTail).toContain('main.lua');
 	});
 });
+
+describe('audio record/render: the backstop follows the record window', () => {
+	it('defaults to the window plus a startup margin (a 24 s window is not killed at 30 s)', async () => {
+		for (const argv of [
+			[
+				'audio',
+				'render',
+				cartPath,
+				'--pattern',
+				'0',
+				'--seconds',
+				'24',
+				'--json',
+			],
+			['audio', 'record', cartPath, '--seconds', '24', '--json'],
+		]) {
+			const seen: {record?: RecordOptions} = {};
+			const {exitCode} = await runAudio(
+				() => stubAdapter(recorded(undefined), seen),
+				argv,
+			);
+			expect(exitCode).toBe(0);
+			expect(seen.record?.backstopMs).toBe(24_000 + RECORD_STARTUP_MARGIN_MS);
+		}
+	});
+
+	it('an explicit backstop that cannot fit the window is refused up front', async () => {
+		const seen: {record?: RecordOptions} = {};
+		const {stdout, exitCode} = await runAudio(
+			() => stubAdapter(recorded(undefined), seen),
+			[
+				'audio',
+				'render',
+				cartPath,
+				'--pattern',
+				'0',
+				'--seconds',
+				'28',
+				'--backstop-ms',
+				'30000',
+				'--json',
+			],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('audio-backstop-too-small');
+		expect(stdout).toContain('33000');
+		expect(seen.record).toBeUndefined(); // PICO-8 was never launched
+	});
+
+	it('an explicit backstop with room for startup is honoured', async () => {
+		const seen: {record?: RecordOptions} = {};
+		await runAudio(
+			() => stubAdapter(recorded(undefined), seen),
+			[
+				'audio',
+				'record',
+				cartPath,
+				'--seconds',
+				'4',
+				'--backstop-ms',
+				'12000',
+				'--json',
+			],
+		);
+		expect(seen.record?.backstopMs).toBe(12_000);
+	});
+
+	it('resolveRecordBackstop', () => {
+		expect(resolveRecordBackstop(8, undefined)).toEqual({ok: true, ms: 38_000});
+		expect(resolveRecordBackstop(8, 13_000)).toEqual({ok: true, ms: 13_000});
+		expect(resolveRecordBackstop(8, 12_999).ok).toBe(false);
+	});
+});
+
+/** Writes a WAV of `seconds` of a sine at `amp` to `path`. */
+function writeSineWav(path: string, seconds: number, hz: number, amp: number) {
+	const samples = new Float32Array(Math.round(seconds * 22050));
+	for (let i = 0; i < samples.length; i++) {
+		samples[i] = amp * Math.sin((2 * Math.PI * hz * i) / 22050);
+	}
+	writeFileSync(path, encodeWav16(samples, 22050));
+}
+
+describe('audio analyze (no PICO-8 needed)', () => {
+	it('reports loudness/brightness/dynamics and plain-language warnings', async () => {
+		const wav = join(dir, 'm.wav');
+		writeSineWav(wav, 4, 440, 0.3);
+		const {stdout, exitCode} = await runAudio(
+			() => stubAdapter(pico8NotFound()),
+			['audio', 'analyze', wav, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.skippedSeconds).toBe(1);
+		expect(out.loudness.meanRms).toBeCloseTo(0.212, 2);
+		expect(Math.abs(out.brightness.centroidHz - 440)).toBeLessThan(30);
+		const codes = out.warnings.map((w: {code: string}) => w.code);
+		expect(codes).toContain('loud');
+		expect(codes).toContain('monotonous');
+	});
+
+	it('--against compares the music with a reference SFX', async () => {
+		const music = join(dir, 'm.wav');
+		const sfx = join(dir, 's.wav');
+		writeSineWav(music, 4, 330, 0.05);
+		writeSineWav(sfx, 1, 660, 0.3);
+		const {stdout} = await runAudio(
+			() => stubAdapter(pico8NotFound()),
+			['audio', 'analyze', music, '--against', sfx, '--json'],
+		);
+		expect(JSON.parse(stdout).against.musicOverReferenceDb).toBeLessThan(-10);
+	});
+
+	it('a missing or bad WAV is a structured error', async () => {
+		const bad = join(dir, 'bad.wav');
+		writeFileSync(bad, 'not a wav');
+		for (const p of [bad, join(dir, 'missing.wav')]) {
+			const {stdout, exitCode} = await runAudio(
+				() => stubAdapter(pico8NotFound()),
+				['audio', 'analyze', p, '--json'],
+			);
+			expect(exitCode).not.toBe(0);
+			expect(stdout).toContain('audio-analyze-bad-wav');
+		}
+	});
+
+	it('render --analyze attaches the analysis of the captured WAV', async () => {
+		const wav = join(dir, 'cap.wav');
+		writeSineWav(wav, 3, 440, 0.05);
+		const {stdout, exitCode} = await runAudio(
+			() => stubAdapter(recorded(wav)),
+			['audio', 'render', cartPath, '--sfx', '0', '--analyze', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.captured).toBe(true);
+		expect(out.analysis.loudness.meanRms).toBeCloseTo(0.035, 2);
+	});
+
+	it('without --analyze there is no analysis', async () => {
+		const wav = join(dir, 'cap.wav');
+		writeSineWav(wav, 3, 440, 0.05);
+		const {stdout} = await runAudio(
+			() => stubAdapter(recorded(wav)),
+			['audio', 'record', cartPath, '--json'],
+		);
+		expect(JSON.parse(stdout).analysis).toBeUndefined();
+	});
+});
+
+describe('render --analyze on an SFX target', () => {
+	it('analyzes the whole capture (no 1 s skip) with sfx rules', async () => {
+		const wav = join(dir, 'blip.wav');
+		writeSineWav(wav, 1.5, 440, 0.3);
+		const {stdout} = await runAudio(
+			() => stubAdapter(recorded(wav)),
+			['audio', 'render', cartPath, '--sfx', '0', '--analyze', '--json'],
+		);
+		const out = JSON.parse(stdout);
+		expect(out.analysis.skippedSeconds).toBe(0);
+		expect(out.analysis.warnings).toEqual([]);
+	});
+});

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,
@@ -20,11 +27,12 @@ import {
 import {makeReadInclude} from './cart-includes.js';
 import {
 	createShellAdapterFactory,
-	displayModeOf,
+	DISPLAY_OPTION,
 	displayUnavailableError,
 	PICO8_ENV,
 	type Pico8AdapterFactory,
 	pico8NotFoundError,
+	resolveCommandDisplay,
 } from './pico8-env.js';
 
 /**
@@ -38,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 =
@@ -74,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
@@ -117,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.'),
 });
 
 /**
@@ -181,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> ---------------------------------------------------
@@ -211,14 +355,9 @@ 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,
 		output: AUDIO_OUTPUT,
@@ -256,26 +395,45 @@ 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);
 			const harnessCart = join(wavDir, 'record-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
 
+			const display = resolveCommandDisplay(options.display, vars);
+			if (!display.ok) return error(display.error);
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
-				display: displayModeOf(vars),
+				display: display.mode,
 			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				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)},
@@ -330,14 +488,9 @@ 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,
 		output: AUDIO_OUTPUT,
@@ -390,24 +543,46 @@ 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);
 
+			const display = resolveCommandDisplay(options.display, vars);
+			if (!display.ok) return error(display.error);
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
-				display: displayModeOf(vars),
+				display: display.mode,
 			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				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)},
@@ -415,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

@@ -15,8 +15,9 @@ import {
 } from '../engine/pico8/index.js';
 import {
 	createShellAdapterFactory,
-	displayModeOf,
+	DISPLAY_OPTION,
 	PICO8_ENV,
+	resolveCommandDisplay,
 	type Pico8AdapterFactory,
 } from './pico8-env.js';
 import {
@@ -72,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. */
@@ -112,6 +114,7 @@ export function registerDoctor(cli: Cli.Cli, deps: DoctorDeps = {}): void {
 		description:
 			'Report what this machine can do: PICO-8 (found, runs headless, version), shrinko8, the display a PICO-8 -run session would use (native / virtual Xvfb / none), and which picopilot commands are therefore available. Call this first on a new machine.',
 		env: PICO8_ENV,
+		options: z.object({display: DISPLAY_OPTION}),
 		output: z.object({
 			pico8: z.object({
 				found: z.boolean().describe('Whether the PICO-8 binary was found.'),
@@ -162,8 +165,10 @@ export function registerDoctor(cli: Cli.Cli, deps: DoctorDeps = {}): void {
 				)
 				.describe('Commands that do not, and what they are missing.'),
 		}),
-		async run({env, ok, var: vars}) {
-			const display: DisplayMode = displayModeOf(vars);
+		async run({env, ok, error, options, var: vars}) {
+			const resolved = resolveCommandDisplay(options.display, vars);
+			if (!resolved.ok) return error(resolved.error);
+			const display: DisplayMode = resolved.mode;
 			const childEnv = pico8ChildEnv(
 				env as Record<string, string | undefined>,
 				deps.parentEnv ?? process.env,