feat: add audio format validation aligned with latest T2A API

Separate format sets per API domain (T2A supports 7 formats including
pcmu_raw, pcmu_wav, opus; Music supports mp3, wav, pcm, flac) with
streaming constraint enforcement for T2A wav.

Author: RyanLee-Dev

src/commands/music/cover.ts

@@ -6,6 +6,7 @@ import { request, requestJson } from '../../client/http';
 import { musicEndpoint } from '../../client/endpoints';
 import { formatOutput, detectOutputFormat } from '../../output/formatter';
 import { saveAudioOutput } from '../../output/audio';
+import { MUSIC_FORMATS, formatList, validateAudioFormat } from '../../utils/audio-formats';
 import type { Config } from '../../config/schema';
 import type { GlobalFlags } from '../../types/flags';
 import type { MusicRequest, MusicResponse } from '../../types/api';
@@ -24,7 +25,7 @@ export default defineCommand({
     { flag: '--lyrics <text>', description: 'Cover lyrics. If omitted, extracted from reference audio via ASR.' },
     { flag: '--lyrics-file <path>', description: 'Read lyrics from file (use - for stdin)' },
     { flag: '--seed <number>', description: 'Random seed 0–1000000 for reproducible results', type: 'number' },
-    { flag: '--format <fmt>', description: 'Audio format: mp3, wav, pcm (default: mp3)' },
+    { flag: '--format <fmt>', description: `Audio format: ${formatList(MUSIC_FORMATS)} (default: mp3)` },
     { flag: '--sample-rate <hz>', description: 'Sample rate: 16000, 24000, 32000, 44100 (default: 44100)', type: 'number' },
     { flag: '--bitrate <bps>', description: 'Bitrate: 32000, 64000, 128000, 256000 (default: 256000)', type: 'number' },
     { flag: '--channel <n>', description: 'Channels: 1 (mono) or 2 (stereo, default)', type: 'number' },
@@ -65,6 +66,7 @@ export default defineCommand({
 
     const ts = new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-');
     const ext = (flags.format as string) || 'mp3';
+    validateAudioFormat(ext, MUSIC_FORMATS);
     const outPath = (flags.out as string | undefined) ?? `cover_${ts}.${ext}`;
     const format = detectOutputFormat(config.output);
 

src/commands/music/generate.ts

@@ -6,6 +6,7 @@ import { musicEndpoint } from '../../client/endpoints';
 import { formatOutput, detectOutputFormat } from '../../output/formatter';
 import { saveAudioOutput } from '../../output/audio';
 import { readTextFromPathOrStdin } from '../../utils/fs';
+import { MUSIC_FORMATS, formatList, validateAudioFormat } from '../../utils/audio-formats';
 import type { Config } from '../../config/schema';
 import type { GlobalFlags } from '../../types/flags';
 import type { MusicRequest, MusicResponse } from '../../types/api';
@@ -37,7 +38,7 @@ export default defineCommand({
     { flag: '--model <model>', description: 'Model: music-2.6 (recommended), music-2.6-free (default, unlimited), music-2.5+, or music-2.5.' },
     { flag: '--output-format <fmt>', description: 'Return format: hex (default, saved to file) or url (24h expiry, download promptly). When --stream, only hex.' },
     { flag: '--aigc-watermark', description: 'Embed AI-generated content watermark in audio for content provenance' },
-    { flag: '--format <fmt>', description: 'Audio format (default: mp3)' },
+    { flag: '--format <fmt>', description: `Audio format: ${formatList(MUSIC_FORMATS)} (default: mp3)` },
     { flag: '--sample-rate <hz>', description: 'Sample rate (default: 44100)', type: 'number' },
     { flag: '--bitrate <bps>',    description: 'Bitrate (default: 256000)', type: 'number' },
     { flag: '--stream', description: 'Stream raw audio to stdout' },
@@ -121,6 +122,7 @@ export default defineCommand({
 
     const ts = new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-');
     const ext = (flags.format as string) || 'mp3';
+    validateAudioFormat(ext, MUSIC_FORMATS);
     const outPath = (flags.out as string | undefined) ?? `music_${ts}.${ext}`;
     const format = detectOutputFormat(config.output);
 

src/commands/speech/synthesize.ts

@@ -8,6 +8,7 @@ import { detectOutputFormat, formatOutput } from '../../output/formatter';
 import { saveAudioOutput } from '../../output/audio';
 import { writeFileSync } from 'fs';
 import { readTextFromPathOrStdin } from '../../utils/fs';
+import { T2A_FORMATS, formatList, validateAudioFormat, validateT2AStreaming } from '../../utils/audio-formats';
 import type { Config } from '../../config/schema';
 import type { GlobalFlags } from '../../types/flags';
 import type { SpeechRequest, SpeechResponse } from '../../types/api';
@@ -25,7 +26,7 @@ export default defineCommand({
     { flag: '--speed <n>',               description: 'Speech speed multiplier', type: 'number' },
     { flag: '--volume <n>',              description: 'Volume level', type: 'number' },
     { flag: '--pitch <n>',               description: 'Pitch adjustment', type: 'number' },
-    { flag: '--format <fmt>',            description: 'Audio format (default: mp3)' },
+    { flag: '--format <fmt>',            description: `Audio format: ${formatList(T2A_FORMATS)} (default: mp3)` },
     { flag: '--sample-rate <hz>',        description: 'Sample rate (default: 32000)', type: 'number' },
     { flag: '--bitrate <bps>',           description: 'Bitrate (default: 128000)', type: 'number' },
     { flag: '--channels <n>',            description: 'Audio channels (default: 1)', type: 'number' },
@@ -63,6 +64,8 @@ export default defineCommand({
     const voice = (flags.voice as string) || 'English_expressive_narrator';
     const ts = new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-');
     const ext = (flags.format as string) || 'mp3';
+    validateAudioFormat(ext, T2A_FORMATS);
+    validateT2AStreaming(ext, flags.stream === true);
     const outPath = (flags.out as string | undefined) ?? `speech_${ts}.${ext}`;
     const outFormat = 'hex';
     const format = detectOutputFormat(config.output);

src/utils/audio-formats.ts

@@ -0,0 +1,31 @@
+import { CLIError } from '../errors/base';
+import { ExitCode } from '../errors/codes';
+
+export const T2A_FORMATS = ['mp3', 'pcm', 'flac', 'wav', 'pcmu_raw', 'pcmu_wav', 'opus'] as const;
+export const MUSIC_FORMATS = ['mp3', 'wav', 'pcm', 'flac'] as const;
+
+export type T2AFormat = (typeof T2A_FORMATS)[number];
+export type MusicFormat = (typeof MUSIC_FORMATS)[number];
+
+export function formatList(formats: readonly string[]): string {
+  return formats.join(', ');
+}
+
+export function validateAudioFormat(format: string, formats: readonly string[]): void {
+  if (!(formats as readonly string[]).includes(format)) {
+    throw new CLIError(
+      `Invalid audio format "${format}". Supported: ${formatList(formats)}`,
+      ExitCode.USAGE,
+    );
+  }
+}
+
+export function validateT2AStreaming(format: string, stream: boolean): void {
+  if (stream && format === 'wav') {
+    throw new CLIError(
+      'wav format is not supported in streaming mode.',
+      ExitCode.USAGE,
+      'Use mp3, pcm, flac, pcmu_raw, pcmu_wav, or opus for streaming.',
+    );
+  }
+}

test/commands/music/generate.test.ts

@@ -180,4 +180,32 @@ describe('music generate command', () => {
     const parsed = JSON.parse(captured);
     expect(parsed.request.model).toBe('music-2.5');
   });
+
+  it('rejects invalid audio format', async () => {
+    await expect(
+      generateCommand.execute(
+        { ...baseConfig, dryRun: true },
+        { ...baseFlags, dryRun: true, prompt: 'Folk', lyrics: 'la la', format: 'opus' },
+      ),
+    ).rejects.toThrow('Invalid audio format "opus"');
+  });
+
+  it.each(['mp3', 'wav', 'pcm', 'flac'])(
+    'accepts %s format in dry-run',
+    async (fmt) => {
+      const origLog = console.log;
+      let captured = '';
+      console.log = (msg: string) => { captured += msg; };
+      try {
+        await generateCommand.execute(
+          { ...baseConfig, dryRun: true, output: 'json' as const },
+          { ...baseFlags, dryRun: true, prompt: 'Folk', lyrics: 'la la', format: fmt },
+        );
+        const parsed = JSON.parse(captured);
+        expect(parsed.request.audio_setting.format).toBe(fmt);
+      } finally {
+        console.log = origLog;
+      }
+    },
+  );
 });

test/commands/speech/synthesize.test.ts

@@ -203,3 +203,60 @@ describe('speech synthesize command', () => {
     }
   });
 });
+
+describe('speech synthesize format validation', () => {
+  const config = {
+    apiKey: 'test-key',
+    region: 'global' as const,
+    baseUrl: 'https://api.mmx.io',
+    output: 'json' as const,
+    timeout: 10,
+    verbose: false,
+    quiet: false,
+    noColor: true,
+    yes: false,
+    dryRun: true,
+    nonInteractive: true,
+    async: false,
+  };
+
+  const flags = {
+    text: 'Hello',
+    quiet: false,
+    verbose: false,
+    noColor: true,
+    yes: false,
+    dryRun: true,
+    help: false,
+    nonInteractive: true,
+    async: false,
+  };
+
+  it('rejects invalid audio format', async () => {
+    await expect(
+      synthesizeCommand.execute(config, { ...flags, format: 'aac' }),
+    ).rejects.toThrow('Invalid audio format "aac"');
+  });
+
+  it.each(['mp3', 'pcm', 'flac', 'wav', 'pcmu_raw', 'pcmu_wav', 'opus'])(
+    'accepts %s format in dry-run',
+    async (fmt) => {
+      const originalLog = console.log;
+      let output = '';
+      console.log = (msg: string) => { output += msg; };
+      try {
+        await synthesizeCommand.execute(config, { ...flags, format: fmt });
+        const parsed = JSON.parse(output);
+        expect(parsed.request.audio_setting.format).toBe(fmt);
+      } finally {
+        console.log = originalLog;
+      }
+    },
+  );
+
+  it('rejects wav in streaming mode', async () => {
+    await expect(
+      synthesizeCommand.execute(config, { ...flags, format: 'wav', stream: true }),
+    ).rejects.toThrow('wav format is not supported in streaming');
+  });
+});

test/utils/audio-formats.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  T2A_FORMATS,
+  MUSIC_FORMATS,
+  formatList,
+  validateAudioFormat,
+  validateT2AStreaming,
+} from '../../src/utils/audio-formats';
+
+describe('audio-formats', () => {
+  describe('T2A_FORMATS', () => {
+    it.each(['mp3', 'pcm', 'flac', 'wav', 'pcmu_raw', 'pcmu_wav', 'opus'] as const)(
+      'accepts %s',
+      (fmt) => expect(() => validateAudioFormat(fmt, T2A_FORMATS)).not.toThrow(),
+    );
+
+    it.each(['aac', 'ogg', 'wma', 'mp4', ''])(
+      'rejects %s',
+      (fmt) => expect(() => validateAudioFormat(fmt, T2A_FORMATS)).toThrow(/Invalid audio format/),
+    );
+  });
+
+  describe('MUSIC_FORMATS', () => {
+    it.each(['mp3', 'wav', 'pcm', 'flac'] as const)(
+      'accepts %s',
+      (fmt) => expect(() => validateAudioFormat(fmt, MUSIC_FORMATS)).not.toThrow(),
+    );
+
+    it.each(['opus', 'pcmu_raw', 'pcmu_wav', 'aac'])(
+      'rejects %s',
+      (fmt) => expect(() => validateAudioFormat(fmt, MUSIC_FORMATS)).toThrow(/Invalid audio format/),
+    );
+  });
+
+  describe('validateT2AStreaming', () => {
+    it('rejects wav in streaming mode', () => {
+      expect(() => validateT2AStreaming('wav', true)).toThrow(/wav format is not supported in streaming/);
+    });
+
+    it('allows wav in non-streaming mode', () => {
+      expect(() => validateT2AStreaming('wav', false)).not.toThrow();
+    });
+
+    it.each(['mp3', 'pcm', 'flac', 'pcmu_raw', 'pcmu_wav', 'opus'])(
+      'allows %s in streaming mode',
+      (fmt) => expect(() => validateT2AStreaming(fmt, true)).not.toThrow(),
+    );
+  });
+
+  describe('formatList', () => {
+    it('joins formats with comma-space', () => {
+      expect(formatList(['a', 'b', 'c'])).toBe('a, b, c');
+    });
+  });
+});