From 5709bf56225894016281fbc6646bae0942468299 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sun, 15 Feb 2026 11:55:53 +0100
Subject: docs: add CLI options reference and WAV dump examples

Expanded HOWTO.md with complete CLI options list and WAV rendering
examples. Updated HEADLESS_MODE.md with new dump-wav options.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/HEADLESS_MODE.md | 10 +++++++++-
 doc/HOWTO.md         | 26 +++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/doc/HEADLESS_MODE.md b/doc/HEADLESS_MODE.md
index f139317..85abbaf 100644
--- a/doc/HEADLESS_MODE.md
+++ b/doc/HEADLESS_MODE.md
@@ -17,10 +17,18 @@ cmake --build build_headless -j4
 # Custom duration
 ./build_headless/demo64k --headless --duration 60
 
-# Audio validation
+# Audio validation (full demo or 60s)
 ./build_headless/demo64k --dump-wav test.wav
+
+# Render specific time range
+./build_headless/demo64k --dump-wav test.wav --dump-wav-start 10 --dump-wav-duration 5
 ```
 
+**WAV Dump Options:**
+- `--dump-wav [FILE]` - Output filename (default: audio_dump.wav)
+- `--dump-wav-start TIME` - Start at time (seeks first, default: 0)
+- `--dump-wav-duration TIME` - Duration limit (default: demo length or 60s)
+
 Test script: `./scripts/test_headless.sh`
 
 ## vs STRIP_EXTERNAL_LIBS
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 506bf0a..0dc9ec7 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -25,7 +25,15 @@ cmake -S . -B build
 cmake --build build -j4
 ./build/demo64k
 ```
-Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload`
+
+**CLI Options:**
+- `--fullscreen` - Fullscreen mode
+- `--resolution WxH` - Window resolution (e.g., 1920x1080)
+- `--seek TIME` - Start at time (seconds)
+- `--hot-reload` - Watch config files for changes
+- `--dump-wav [FILE]` - Render audio to WAV file
+- `--dump-wav-start TIME` - Start WAV dump at time (seeks first)
+- `--dump-wav-duration TIME` - Limit WAV dump duration
 
 ### Production Builds
 ```bash
@@ -252,6 +260,21 @@ Features: Drag/drop, beat-based editing, audio playback, waveform visualization,
 
 ## Audio
 
+### Rendering Audio to WAV
+
+```bash
+# Render full demo
+./build/demo64k --dump-wav output.wav
+
+# Render specific time range
+./build/demo64k --dump-wav output.wav --dump-wav-start 10 --dump-wav-duration 5
+
+# Render first 30 seconds
+./build/demo64k --dump-wav output.wav --dump-wav-duration 30
+```
+
+### API Usage
+
 ```cpp
 #include "audio/audio_engine.h"
 
@@ -262,6 +285,7 @@ g_audio_engine.update(music_time);
 g_audio_engine.shutdown();
 audio_shutdown();
 ```
+
 See `doc/TRACKER.md` for music system.
 
 ---
-- 
cgit v1.2.3