docs: improve --help descriptions for music, image, video

- --lyrics: list all 14 supported structure tags, warn against
  descriptions inside brackets, note 3500 char limit
- --instrumental: explain music-2.5+ vs music-2.5 behavior
- --seed: note same seed + prompt = identical output
- --width/--height: note [512,2048], multiple of 8, overrides aspect-ratio
- --last-frame: note SEF mode, requires --first-frame, uses Hailuo-02
- --subject-image: note S2V-01 model, character consistency
- --prompt-optimizer: explain purpose
- --output-format: note 24h url expiry
- Add full arrangement example to music generate

Author: Raylan LIN

src/commands/image/generate.ts

@@ -24,14 +24,14 @@ export default defineCommand({
   usage: 'mmx image generate --prompt <text> [flags]',
   options: [
     { flag: '--prompt <text>', description: 'Image description', required: true },
-    { flag: '--aspect-ratio <ratio>', description: 'Aspect ratio (e.g. 16:9, 1:1)' },
+    { flag: '--aspect-ratio <ratio>', description: 'Aspect ratio (e.g. 16:9, 1:1). Ignored if --width and --height are both specified.' },
     { flag: '--n <count>', description: 'Number of images to generate (default: 1)', type: 'number' },
-    { flag: '--seed <n>', description: 'Random seed for reproducible results', type: 'number' },
-    { flag: '--width <px>', description: 'Custom width [512–2048, must be multiple of 8]', type: 'number' },
-    { flag: '--height <px>', description: 'Custom height [512–2048, must be multiple of 8]', type: 'number' },
-    { flag: '--prompt-optimizer', description: 'Automatically optimize the prompt before generation' },
-    { flag: '--aigc-watermark', description: 'Embed AI-generated content watermark' },
-    { flag: '--subject-ref <params>', description: 'Subject reference (type=character,image=path)' },
+    { flag: '--seed <n>', description: 'Random seed for reproducible generation (same seed + prompt = identical output)', type: 'number' },
+    { flag: '--width <px>', description: 'Custom width in pixels. Range [512, 2048], must be multiple of 8. Only effective for image-01 model. Overrides --aspect-ratio if set.', type: 'number' },
+    { flag: '--height <px>', description: 'Custom height in pixels. Range [512, 2048], must be multiple of 8. Only effective for image-01 model. Overrides --aspect-ratio if set.', type: 'number' },
+    { flag: '--prompt-optimizer', description: 'Automatically optimize the prompt before generation for better results.' },
+    { flag: '--aigc-watermark', description: 'Embed AI-generated content watermark in the output image.' },
+    { flag: '--subject-ref <params>', description: 'Subject reference for character consistency. Format: type=character,image=path-or-url' },
     { flag: '--out-dir <dir>', description: 'Download images to directory' },
     { flag: '--out-prefix <prefix>', description: 'Filename prefix (default: image)' },
   ],

src/commands/music/generate.ts

@@ -15,26 +15,26 @@ export default defineCommand({
   description: 'Generate a song (music-2.5 / music-2.5+)',
   usage: 'mmx music generate --prompt <text> (--lyrics <text> | --instrumental) [--out <path>] [flags]',
   options: [
-    { flag: '--prompt <text>', description: 'Music style description (can be detailed — see examples)' },
-    { flag: '--lyrics <text>', description: 'Song lyrics with structure tags. Use "无歌词" for instrumental music. Cannot be used with --instrumental.' },
-    { flag: '--lyrics-file <path>', description: 'Read lyrics from file. Use "无歌词" for instrumental. (use - for stdin)' },
+    { flag: '--prompt <text>', description: 'Music style description (e.g. "cinematic orchestral, building tension"). Max 2000 chars when combined with structured flags.' },
+    { flag: '--lyrics <text>', description: 'Song lyrics with structure tags (newline separated). Supported: [Intro], [Verse], [Pre Chorus], [Chorus], [Interlude], [Bridge], [Outro], [Post Chorus], [Transition], [Break], [Hook], [Build Up], [Inst], [Solo]. ⚠️ Tags must be clean — no descriptions inside brackets (they will be sung). Max 3500 chars. Use "\u65e0\u6b4c\u8bcd" for instrumental workaround. Cannot be used with --instrumental.' },
+    { flag: '--lyrics-file <path>', description: 'Read lyrics from file (use - for stdin). Same tag rules as --lyrics.' },
     { flag: '--vocals <text>', description: 'Vocal style, e.g. "warm male baritone", "bright female soprano", "duet with harmonies"' },
-    { flag: '--genre <text>', description: 'Music genre, e.g. folk, pop, jazz' },
+    { flag: '--genre <text>', description: 'Music genre, e.g. folk, pop, jazz, electronic' },
     { flag: '--mood <text>', description: 'Mood or emotion, e.g. warm, melancholic, uplifting' },
-    { flag: '--instruments <text>', description: 'Instruments to feature, e.g. "acoustic guitar, piano"' },
+    { flag: '--instruments <text>', description: 'Instruments to feature, e.g. "acoustic guitar, piano, strings"' },
     { flag: '--tempo <text>', description: 'Tempo description, e.g. fast, slow, moderate' },
     { flag: '--bpm <number>', description: 'Exact tempo in beats per minute', type: 'number' },
     { flag: '--key <text>', description: 'Musical key, e.g. C major, A minor, G sharp' },
     { flag: '--avoid <text>', description: 'Elements to avoid in the generated music' },
     { flag: '--use-case <text>', description: 'Use case context, e.g. "background music for video", "theme song"' },
     { flag: '--structure <text>', description: 'Song structure, e.g. "verse-chorus-verse-bridge-chorus"' },
-    { flag: '--references <text>', description: 'Reference tracks or artists, e.g. "similar to Ed Sheeran, Taylor Swift"' },
+    { flag: '--references <text>', description: 'Reference tracks or artists, e.g. "similar to Ed Sheeran"' },
     { flag: '--extra <text>', description: 'Additional fine-grained requirements not covered above' },
-    { flag: '--model <model>', description: 'Model to use: music-2.5 or music-2.5+ (recommended). music-2.5+ supports is_instrumental flag.' },
-    { flag: '--instrumental', description: 'Generate instrumental music (no vocals). music-2.5: lyrics workaround. music-2.5+: native is_instrumental flag.' },
-    { flag: '--lyrics-optimizer', description: 'Auto-generate lyrics from prompt. Only works when lyrics is empty. music-2.5 and music-2.5+ support.' },
-    { flag: '--output-format <fmt>', description: 'Return format: hex (default, saved to file) or url (24h expiry). When --stream, only hex.' },
-    { flag: '--aigc-watermark', description: 'Embed AI-generated content watermark in audio for content provenance' },
+    { flag: '--model <model>', description: 'Model: music-2.5 or music-2.5+ (recommended). music-2.5+ supports native is_instrumental.' },
+    { flag: '--instrumental', description: 'Generate instrumental music (no vocals). music-2.5+: native is_instrumental flag. music-2.5: [intro][outro] lyrics workaround.' },
+    { flag: '--lyrics-optimizer', description: 'Auto-generate lyrics from prompt. Only works when lyrics is empty. Supports music-2.5 and 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. Only effective when --stream is false.' },
     { flag: '--format <fmt>', description: 'Audio format (default: mp3)' },
     { flag: '--sample-rate <hz>', description: 'Sample rate (default: 44100)', type: 'number' },
     { flag: '--bitrate <bps>',    description: 'Bitrate (default: 256000)', type: 'number' },
@@ -54,6 +54,8 @@ export default defineCommand({
     'mmx music generate --prompt "indie folk, melancholic" --lyrics-optimizer --out auto.mp3',
     '# URL output (24h expiry — download promptly):',
     'mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --output-format url --quiet',
+    '# Album song with full arrangement:',
+    'mmx music generate --model "music-2.5+" --prompt "Atmospheric electronic, B minor, 85 BPM" --lyrics-file "song.txt" --vocals "Warm male baritone" --genre "atmospheric electronic" --instruments "piano, strings" --bpm 85 --key "B minor" --structure "Intro-Verse-Chorus-Bridge-Outro" --references "Bon Iver" --extra "Bridge drop-out." --out "demo.mp3"',
   ],
   async run(config: Config, flags: GlobalFlags) {
     let prompt = flags.prompt as string | undefined;

src/commands/video/generate.ts

@@ -24,16 +24,16 @@ export default defineCommand({
   description: 'Generate a video (Hailuo-2.3 / 2.3-Fast / Hailuo-02 / S2V-01)',
   usage: 'mmx video generate --prompt <text> [flags]',
   options: [
-    { flag: '--model <model>', description: 'Model ID (default: MiniMax-Hailuo-2.3). Auto-switches to Hailuo-02 with --last-frame, S2V-01 with --subject-image.' },
+    { flag: '--model <model>', description: 'Model ID (default: MiniMax-Hailuo-2.3). Auto-switched to Hailuo-02 with --last-frame, or S2V-01 with --subject-image.' },
     { flag: '--prompt <text>', description: 'Video description', required: true },
-    { flag: '--first-frame <path-or-url>', description: 'First frame image' },
-    { flag: '--last-frame <path-or-url>', description: 'Last frame image (SEF mode, auto-switches to Hailuo-02 model)' },
-    { flag: '--subject-image <path-or-url>', description: 'Subject reference image for character consistency (auto-switches to S2V-01 model)' },
+    { flag: '--first-frame <path-or-url>', description: 'First frame image (local path or URL). Auto base64-encoded for local files.' },
+    { flag: '--last-frame <path-or-url>', description: 'Last frame image (local path or URL). Enables SEF (start-end frame) interpolation mode with Hailuo-02 model. Requires --first-frame.' },
+    { flag: '--subject-image <path-or-url>', description: 'Subject reference image for character consistency (local path or URL). Switches to S2V-01 model.' },
     { flag: '--callback-url <url>', description: 'Webhook URL for completion notification' },
     { flag: '--download <path>', description: 'Save video to file on completion' },
-    { flag: '--no-wait', description: 'Return task ID immediately without waiting' },
+    { flag: '--no-wait', description: 'Return task ID immediately without waiting for completion' },
     { flag: '--async', description: 'Return task ID immediately (agent/CI mode, same as --no-wait but explicit)' },
-    { flag: '--poll-interval <seconds>', description: 'Polling interval when waiting (default: 5)', type: 'number' },
+    { flag: '--poll-interval <seconds>', description: 'Polling interval when waiting for completion (default: 5)', type: 'number' },
   ],
   examples: [
     'mmx video generate --prompt "A man reads a book. Static shot."',