From 4d749c3d9db192bc411663ca52638d41fee32474 Mon Sep 17 00:00:00 2001
From: iret77 <63622643+iret77@users.noreply.github.com>
Date: Thu, 30 Jul 2026 19:35:08 +0200
Subject: [PATCH] feat(form): add audio field for native playback in dialogs

Adds an `audio` field kind to the `form` MCP tool, rendering a native
`<audio controls>` player for reviewing TTS samples, voice memos, or
generated sound clips (#25). Mirrors the existing video handling: a
local audio path (mp3/m4a/wav/aac/ogg/flac) is routed through the
same size-unbounded /media cache the gallery tool uses for video,
never the 10 MB data:-URL inliner, so it works identically whether
the agent runs locally or on a remote SSH host.

Both bridges implement the same routing to avoid behavioral drift:
- companion/src-tauri: imageresolve (path/ext detection + collection),
  mcp.rs (media upload wiring, tool description), http.rs (known field
  kind), dialog.rs (window size estimate)
- python/src/aiui_mcp/server.py: mirrored upload/collect helpers and
  tool docstring

Documents the new field in docs/skill.md and the Python package's
bundled skill.md, and records the change in CHANGELOG.md.
---
 CHANGELOG.md                             |  13 +++
 companion/src-tauri/src/dialog.rs        |  14 +++
 companion/src-tauri/src/http.rs          |  12 ++-
 companion/src-tauri/src/imageresolve.rs  | 131 +++++++++++++++++++++++
 companion/src-tauri/src/mcp.rs           |  44 ++++++--
 companion/src/lib/widgets/Form.svelte    |  26 +++++
 docs/skill.md                            |  39 +++++++
 python/src/aiui_mcp/server.py            |  90 ++++++++++++++++
 python/src/aiui_mcp/skill.md             |  22 ++++
 python/tests/test_resolve_local_paths.py |  61 +++++++++++
 10 files changed, 440 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a5a80a9..9196b39 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,6 +57,19 @@ All notable changes to this project are documented here.
   can recover pixel coordinates losslessly. `required` gates the submit
   action on an annotation being present. Documented in the skill field
   catalog and mirrored in the Rust and Python `form` tool descriptions.
+- **`audio` field in `form` dialogs (#25).** Native `<audio controls>`
+  player for TTS-sample review, voice-memo confirmation, or triaging a
+  generated sound clip — read-only like `image`/`mermaid`/`wireframe`,
+  no value in the form result. Spec: `{kind: "audio", src, label?}`.
+  `src` accepts the same three formats as `image` (`data:`, `http(s)://`,
+  absolute/`~/` local path), but a local audio file
+  (mp3/m4a/wav/aac/ogg/flac) is never inlined as `data:` — it's always
+  routed through the same size-unbounded `/media` cache the `gallery`
+  tool already uses for local video, so clips of any size work
+  identically whether the agent runs on the user's Mac or a remote SSH
+  host. Both bridges (Rust companion and the `aiui-mcp` PyPI package for
+  remote/headless use) implement the same routing so behavior doesn't
+  drift between the two.
 
 ## [0.8.3] — 2026-07-29
 
diff --git a/companion/src-tauri/src/dialog.rs b/companion/src-tauri/src/dialog.rs
index 4ec54ea..79bb528 100644
--- a/companion/src-tauri/src/dialog.rs
+++ b/companion/src-tauri/src/dialog.rs
@@ -252,6 +252,9 @@ pub fn estimate_dialog_size(spec: &serde_json::Value) -> (f64, f64) {
                     .unwrap_or(320.0);
                 (BASE_W, (img_h + 90.0).min(560.0))
             }
+            // Audio (#25): just a native `<audio controls>` bar (~40px) plus
+            // an optional caption — far shallower than an image preview.
+            "audio" => (BASE_W, 90.0),
             "tree" => (BASE_W, 240.0),
             "list" => {
                 let items = field
@@ -614,6 +617,17 @@ mod tests {
         assert!(h > 480.0, "mermaid should push height past base, got {h}");
     }
 
+    #[test]
+    fn estimate_size_audio_stays_narrow_and_short() {
+        let spec = serde_json::json!({
+            "kind": "form",
+            "fields": [{ "kind": "audio", "src": "data:audio/mpeg;base64,AAAA", "label": "Sample" }]
+        });
+        let (w, h) = estimate_dialog_size(&spec);
+        assert_eq!(w, 520.0, "audio field should not widen the window");
+        assert_eq!(h, 480.0, "a single short audio field should stay at base height");
+    }
+
     #[test]
     fn estimate_size_clamps_to_max() {
         let mut fields = Vec::new();
diff --git a/companion/src-tauri/src/http.rs b/companion/src-tauri/src/http.rs
index e87827e..2ab4a74 100644
--- a/companion/src-tauri/src/http.rs
+++ b/companion/src-tauri/src/http.rs
@@ -771,8 +771,8 @@ async fn update(
 const KNOWN_FIELD_KINDS: &[&str] = &[
     "text", "password", "secret", "number", "select", "checkbox", "slider",
     "date", "datetime", "date_range", "color", "static_text", "markdown",
-    "image", "annotated_image", "mermaid", "wireframe", "image_grid", "list",
-    "table", "tree",
+    "image", "annotated_image", "audio", "mermaid", "wireframe", "image_grid",
+    "list", "table", "tree",
 ];
 
 /// Validate a dialog spec *before* any window is created (v0.4.46,
@@ -1278,6 +1278,14 @@ mod validate_tests {
         assert!(validate_spec(&spec).is_ok());
     }
 
+    #[test]
+    fn accepts_form_with_audio_field() {
+        let spec = json!({"kind":"form","fields":[
+            {"kind":"audio","src":"data:audio/mpeg;base64,AAAA","label":"Sample"}
+        ]});
+        assert!(validate_spec(&spec).is_ok());
+    }
+
     #[test]
     fn accepts_form_with_tabs() {
         let spec = json!({"kind":"form","tabs":[
diff --git a/companion/src-tauri/src/imageresolve.rs b/companion/src-tauri/src/imageresolve.rs
index 40ab9e6..29668ee 100644
--- a/companion/src-tauri/src/imageresolve.rs
+++ b/companion/src-tauri/src/imageresolve.rs
@@ -248,6 +248,17 @@ fn guess_mime_from_extension(path: &Path) -> &'static str {
         Some("mp4" | "m4v") => "video/mp4",
         Some("mov") => "video/quicktime",
         Some("webm") => "video/webm",
+        // Audio — for the form `audio` field's `<audio controls>` (#25). Like
+        // video, local audio is routed through the /media cache before this
+        // function ever sees it (see `is_local_audio_path`), so these
+        // branches mainly document the contract / cover the data:-URL and
+        // http(s) resolver paths, which reuse this mime table too.
+        Some("mp3") => "audio/mpeg",
+        Some("m4a") => "audio/mp4",
+        Some("wav") => "audio/wav",
+        Some("aac") => "audio/aac",
+        Some("ogg") => "audio/ogg",
+        Some("flac") => "audio/flac",
         // Unknown extension: hand it to the WebView as octet-stream.
         // It will likely fail to render, but that's a clear "your file
         // isn't an image" signal rather than a misleading mime guess.
@@ -300,6 +311,62 @@ pub fn collect_local_video_paths(spec: &Value) -> Vec<String> {
     found
 }
 
+/// True for a local-filesystem path that points at an audio file by
+/// extension. Used to route audio through the push-to-cache `/media` path
+/// instead of the (10 MB-capped, base64-bloating) `data:` inliner — mirrors
+/// [`is_local_video_path`] above, the Python bridge's `_is_local_audio`, and
+/// the analogous check that will land in the `form` widget's `audio` field.
+/// Covers the common lossy/lossless formats a TTS sample, voice memo, or
+/// generated sound clip is likely to arrive in (#25).
+pub fn is_local_audio_path(s: &str) -> bool {
+    if !looks_like_local_path(s) {
+        return false;
+    }
+    let lower = s.to_ascii_lowercase();
+    // Strip any query/fragment a path-ish string might carry before matching.
+    let stem = lower.split(['?', '#']).next().unwrap_or(&lower);
+    stem.ends_with(".mp3")
+        || stem.ends_with(".m4a")
+        || stem.ends_with(".wav")
+        || stem.ends_with(".aac")
+        || stem.ends_with(".ogg")
+        || stem.ends_with(".flac")
+}
+
+/// File extension (lowercase, no dot) of a local audio path — for naming the
+/// uploaded cache file. Defaults to `mp3` if somehow absent. Mirrors
+/// [`video_ext`].
+pub fn audio_ext(s: &str) -> String {
+    let lower = s.to_ascii_lowercase();
+    let stem = lower.split(['?', '#']).next().unwrap_or(&lower);
+    stem.rsplit('.')
+        .next()
+        .filter(|e| !e.is_empty())
+        .unwrap_or("mp3")
+        .to_string()
+}
+
+/// Collect every distinct local audio path referenced in a `src`/`thumbnail`
+/// slot anywhere in the spec. Mirrors [`collect_local_video_paths`] — the
+/// bridge uploads each to the Mac's `/media` endpoint, then calls
+/// [`replace_srcs`] to swap the paths for the returned playback URLs — all
+/// *before* [`resolve_local_paths`] runs, so the image inliner never tries to
+/// base64 a large audio file.
+pub fn collect_local_audio_paths(spec: &Value) -> Vec<String> {
+    let mut found: Vec<String> = Vec::new();
+    walk(spec, &mut |key, value| {
+        if !SRC_KEYS.contains(&key) {
+            return;
+        }
+        if let Some(s) = value.as_str() {
+            if is_local_audio_path(s) && !found.iter().any(|f| f == s) {
+                found.push(s.to_string());
+            }
+        }
+    });
+    found
+}
+
 /// Replace every `src`/`thumbnail` string that appears as a key in `map`
 /// with its mapped value. Used to swap uploaded local video paths for their
 /// `/media/blob/...` playback URLs.
@@ -456,6 +523,67 @@ mod tests {
         assert_eq!(video_ext("/a/take.mov"), "mov");
     }
 
+    #[test]
+    fn is_local_audio_path_classifies_correctly() {
+        assert!(is_local_audio_path("/Users/me/sample.mp3"));
+        assert!(is_local_audio_path("~/Music/voice.M4A"));
+        assert!(is_local_audio_path("/tmp/a.wav"));
+        assert!(is_local_audio_path("/tmp/a.aac"));
+        assert!(is_local_audio_path("/tmp/a.ogg"));
+        assert!(is_local_audio_path("/tmp/a.flac"));
+        // Not local, or not audio.
+        assert!(!is_local_audio_path("https://x.test/clip.mp3"));
+        assert!(!is_local_audio_path("data:audio/mpeg;base64,AAAA"));
+        assert!(!is_local_audio_path("/Users/me/photo.png"));
+        assert!(!is_local_audio_path("/Users/me/clip.mp4")); // video, not audio
+        assert!(!is_local_audio_path("relative/clip.mp3"));
+    }
+
+    #[test]
+    fn audio_ext_extracts_lowercase_extension() {
+        assert_eq!(audio_ext("/a/b.MP3"), "mp3");
+        assert_eq!(audio_ext("~/x.flac"), "flac");
+        assert_eq!(audio_ext("/a/take.WAV"), "wav");
+    }
+
+    #[test]
+    fn collect_and_replace_local_audio() {
+        let spec = json!({
+            "kind": "form",
+            "fields": [
+                {"kind": "audio", "src": "/Users/me/sample.mp3"},
+                {"kind": "audio", "src": "https://x.test/two.mp3"},
+                {"kind": "image", "src": "/Users/me/pic.png"},
+                {"kind": "list", "items": [
+                    {"label": "L", "value": "l", "thumbnail": "/Users/me/sample.mp3"}
+                ]}
+            ]
+        });
+        let mut found = collect_local_audio_paths(&spec);
+        found.sort();
+        // De-duplicated: the same path in two slots appears once.
+        assert_eq!(found, vec!["/Users/me/sample.mp3".to_string()]);
+
+        let mut spec = spec;
+        let mut map = std::collections::HashMap::new();
+        map.insert(
+            "/Users/me/sample.mp3".to_string(),
+            "http://127.0.0.1:7777/media/blob/x.mp3".to_string(),
+        );
+        replace_srcs(&mut spec, &map);
+        assert_eq!(
+            spec["fields"][0]["src"].as_str().unwrap(),
+            "http://127.0.0.1:7777/media/blob/x.mp3"
+        );
+        assert_eq!(
+            spec["fields"][3]["items"][0]["thumbnail"].as_str().unwrap(),
+            "http://127.0.0.1:7777/media/blob/x.mp3"
+        );
+        // Untouched: https audio and the image.
+        assert_eq!(spec["fields"][1]["src"].as_str().unwrap(), "https://x.test/two.mp3");
+        assert_eq!(spec["fields"][2]["src"].as_str().unwrap(), "/Users/me/pic.png");
+    }
+
     #[test]
     fn collects_src_at_any_depth() {
         let spec = json!({
@@ -629,6 +757,9 @@ mod tests {
         assert_eq!(guess_mime_from_extension(Path::new("a.png")), "image/png");
         assert_eq!(guess_mime_from_extension(Path::new("a.JPG")), "image/jpeg");
         assert_eq!(guess_mime_from_extension(Path::new("a.svg")), "image/svg+xml");
+        assert_eq!(guess_mime_from_extension(Path::new("a.mp3")), "audio/mpeg");
+        assert_eq!(guess_mime_from_extension(Path::new("a.M4A")), "audio/mp4");
+        assert_eq!(guess_mime_from_extension(Path::new("a.wav")), "audio/wav");
         assert_eq!(
             guess_mime_from_extension(Path::new("a.unknown")),
             "application/octet-stream"
diff --git a/companion/src-tauri/src/mcp.rs b/companion/src-tauri/src/mcp.rs
index f550559..13879ff 100644
--- a/companion/src-tauri/src/mcp.rs
+++ b/companion/src-tauri/src/mcp.rs
@@ -333,7 +333,7 @@ fn tools_list() -> Value {
         },
         {
             "name": "form",
-            "description": "Whenever the user needs to provide ≥ 2 related inputs, or any single input that doesn't belong in chat (secret, date/datetime/range, bounded number, sortable ranking, multi-select, color pick, table-row triage with column context, image confirm/grid), call this tool instead of typing the questions one by one. Fields: text, password, secret, number, select, checkbox, slider, date, datetime, date_range, color, static_text, markdown, image, annotated_image, mermaid, wireframe, image_grid, list, table, tree. **File-write / secret capture (#135):** any input field may carry an optional `target` to write the entered value to a file ON THE HOST THE AGENT RUNS ON when the user submits (the affirmative button IS the per-write approval; the user sees the path first): `{\"kind\":\"secret\",\"name\":\"pat\",\"label\":\"GitHub PAT\",\"target\":{\"mode\":\"create\",\"path\":\"~/.github_tokens/byte5ai\",\"perm\":\"0600\",\"overwrite\":true}}`. `mode`: `create` (write raw value; needs `overwrite:true` to clobber) or `substitute` (replace a `placeholder` that occurs exactly once in an existing file — for YAML/TOML/INI/etc; choose a DISTINCTIVE sentinel that can't collide with real file content, e.g. `__AIUI_SECRET_GITHUB_PAT__`, not a common word — if it occurs 0 or >1 times the write is refused with an error, never misapplied to the wrong spot). A `secret`-kind field is **write-only**: its value is NEVER returned to you (result carries only `{written, target, bytes}`); use it precisely so a credential the user types never enters this conversation. Non-secret fields with a `target` are written AND returned. The destination is always the agent's own host: the aiui module already running there (the native app locally, the bridge on a remote SSH session) performs the write as a LOCAL file operation, so `create` and `substitute` both work identically local and remote — and you cannot target a foreign host. Errors come back as `{written:false, error}`. Group long forms with `tabs: [{label, fields: [...]}]` (one submit, all tabs validated). Footer actions are top-level on the form (`actions: [...]`), NOT inside a tab — they always render at the window's bottom. Action variants: primary (blue), success (green), destructive (red). Returns {cancelled, action?, values}. For yes/no, use `confirm`. For one-of-N pick, use `ask`. Sortable list field shape (most common stumble — always include `value` per item): {\"kind\":\"list\",\"name\":\"rank\",\"label\":\"Sortieren\",\"sortable\":true,\"items\":[{\"label\":\"A\",\"value\":\"a\"},{\"label\":\"B\",\"value\":\"b\"}]}. Image fields (`image`, `image_grid`, list-item `thumbnail`): `src` accepts (1) an absolute or `~/`-rooted local path — aiui's bridge on YOUR host reads it and inlines as `data:`; (2) an `http(s)://` URL — Mac-companion fetches and inlines; (3) a `data:` URL — pass through. Pick the path form when the file is on disk on your host. Relative paths and cross-host paths don't resolve. Never base64-roundtrip through a shell pipeline — build the `data:` URL in your runtime. To have the user MARK a spot on an image (logo placement, crop hint, bug location) use `annotated_image`: `{\"kind\":\"annotated_image\",\"name\":\"spot\",\"src\":\"~/shot.png\",\"mode\":\"point\"}` — `mode` is `point` (click one marker, default), `region` (drag a rectangle), or `both` (user flips a Point/Region tool). `src` follows the same resolution rules as `image`. Returns normalized 0..1 coords under the field name: `{\"point\":{\"x\",\"y\"}|null,\"region\":{\"x\",\"y\",\"w\",\"h\"}|null,\"natural\":{\"width\",\"height\"}|null}` — multiply by `natural` for pixels. For schematic visualisations (flowcharts, sequence/state diagrams, gantt, mind-maps) use the `mermaid` field instead of ASCII art: `{\"kind\":\"mermaid\",\"source\":\"graph TD; A --> B; B --> C\"}`. For UI-layout mockups (dashboard tiles, hardware-UI panels, login screens, anything with fixed-position boxes-and-labels) use the `wireframe` field — declarative panel grid, NOT ASCII boxes-and-pipes: `{\"kind\":\"wireframe\",\"columns\":3,\"panels\":[{\"title\":\"STATUS\",\"content\":\"Tiefe: 18 m\\nKurs: 270°\",\"col_span\":1},{\"title\":\"EMPFANG\",\"content\":\"14:32 [STARK]…\",\"col_span\":2}]}`. Each panel has optional `title` (uppercase header), `content` (multi-line monospace text, escape `\\n`), `col_span`/`row_span` (default 1), and `tone` (\"default\"/\"muted\"/\"highlight\"). See the aiui skill for the full field catalog. **This tool blocks until the user submits or cancels. Response can take minutes (longer for complex forms) — do not assume aiui is broken on slow response, the user is filling the form. The companion sends MCP progress notifications every ~10 s while waiting.**",
+            "description": "Whenever the user needs to provide ≥ 2 related inputs, or any single input that doesn't belong in chat (secret, date/datetime/range, bounded number, sortable ranking, multi-select, color pick, table-row triage with column context, image confirm/grid, audio playback), call this tool instead of typing the questions one by one. Fields: text, password, secret, number, select, checkbox, slider, date, datetime, date_range, color, static_text, markdown, image, annotated_image, audio, mermaid, wireframe, image_grid, list, table, tree. **Audio field (#25):** `{\"kind\":\"audio\",\"src\":\"...\",\"label\":\"...\"}` — read-only native `<audio controls>` player, for \"listen to this TTS sample / voice memo / generated sound clip before deciding\". `src` accepts a `data:audio/...` URL, an `http(s)://` URL, or an absolute/`~/`-rooted local path (mp3/m4a/wav/aac/ogg/flac) — local audio is pushed through the same size-unbounded `/media` cache as gallery video, never the 10 MB `data:` inliner, so large clips work too. **File-write / secret capture (#135):** any input field may carry an optional `target` to write the entered value to a file ON THE HOST THE AGENT RUNS ON when the user submits (the affirmative button IS the per-write approval; the user sees the path first): `{\"kind\":\"secret\",\"name\":\"pat\",\"label\":\"GitHub PAT\",\"target\":{\"mode\":\"create\",\"path\":\"~/.github_tokens/byte5ai\",\"perm\":\"0600\",\"overwrite\":true}}`. `mode`: `create` (write raw value; needs `overwrite:true` to clobber) or `substitute` (replace a `placeholder` that occurs exactly once in an existing file — for YAML/TOML/INI/etc; choose a DISTINCTIVE sentinel that can't collide with real file content, e.g. `__AIUI_SECRET_GITHUB_PAT__`, not a common word — if it occurs 0 or >1 times the write is refused with an error, never misapplied to the wrong spot). A `secret`-kind field is **write-only**: its value is NEVER returned to you (result carries only `{written, target, bytes}`); use it precisely so a credential the user types never enters this conversation. Non-secret fields with a `target` are written AND returned. The destination is always the agent's own host: the aiui module already running there (the native app locally, the bridge on a remote SSH session) performs the write as a LOCAL file operation, so `create` and `substitute` both work identically local and remote — and you cannot target a foreign host. Errors come back as `{written:false, error}`. Group long forms with `tabs: [{label, fields: [...]}]` (one submit, all tabs validated). Footer actions are top-level on the form (`actions: [...]`), NOT inside a tab — they always render at the window's bottom. Action variants: primary (blue), success (green), destructive (red). Returns {cancelled, action?, values}. For yes/no, use `confirm`. For one-of-N pick, use `ask`. Sortable list field shape (most common stumble — always include `value` per item): {\"kind\":\"list\",\"name\":\"rank\",\"label\":\"Sortieren\",\"sortable\":true,\"items\":[{\"label\":\"A\",\"value\":\"a\"},{\"label\":\"B\",\"value\":\"b\"}]}. Image fields (`image`, `image_grid`, list-item `thumbnail`): `src` accepts (1) an absolute or `~/`-rooted local path — aiui's bridge on YOUR host reads it and inlines as `data:`; (2) an `http(s)://` URL — Mac-companion fetches and inlines; (3) a `data:` URL — pass through. Pick the path form when the file is on disk on your host. Relative paths and cross-host paths don't resolve. Never base64-roundtrip through a shell pipeline — build the `data:` URL in your runtime. To have the user MARK a spot on an image (logo placement, crop hint, bug location) use `annotated_image`: `{\"kind\":\"annotated_image\",\"name\":\"spot\",\"src\":\"~/shot.png\",\"mode\":\"point\"}` — `mode` is `point` (click one marker, default), `region` (drag a rectangle), or `both` (user flips a Point/Region tool). `src` follows the same resolution rules as `image`. Returns normalized 0..1 coords under the field name: `{\"point\":{\"x\",\"y\"}|null,\"region\":{\"x\",\"y\",\"w\",\"h\"}|null,\"natural\":{\"width\",\"height\"}|null}` — multiply by `natural` for pixels. For schematic visualisations (flowcharts, sequence/state diagrams, gantt, mind-maps) use the `mermaid` field instead of ASCII art: `{\"kind\":\"mermaid\",\"source\":\"graph TD; A --> B; B --> C\"}`. For UI-layout mockups (dashboard tiles, hardware-UI panels, login screens, anything with fixed-position boxes-and-labels) use the `wireframe` field — declarative panel grid, NOT ASCII boxes-and-pipes: `{\"kind\":\"wireframe\",\"columns\":3,\"panels\":[{\"title\":\"STATUS\",\"content\":\"Tiefe: 18 m\nKurs: 270°\",\"col_span\":1},{\"title\":\"EMPFANG\",\"content\":\"14:32 [STARK]…\",\"col_span\":2}]}`. Each panel has optional `title` (uppercase header), `content` (multi-line monospace text, escape `\n`), `col_span`/`row_span` (default 1), and `tone` (\"default\"/\"muted\"/\"highlight\"). See the aiui skill for the full field catalog. **This tool blocks until the user submits or cancels. Response can take minutes (longer for complex forms) — do not assume aiui is broken on slow response, the user is filling the form. The companion sends MCP progress notifications every ~10 s while waiting.**",
             "inputSchema": {
                 "type": "object",
                 "required": ["title"],
@@ -801,18 +801,24 @@ fn base_url(cfg: &AppConfig) -> String {
     format!("http://127.0.0.1:{}", cfg.http_port)
 }
 
-/// Push a local video file to the companion's `POST /media` cache and return
-/// the playback URL it hands back. Reads the file on *this* host (local Mac,
-/// or the remote for an SSH-tunneled session) and uploads the bytes over the
-/// same :7777 channel the render goes through — so it works identically
-/// local and remote without any Mac→remote access. Errors (file unreadable,
-/// 413, old companion without `/media` → 404) bubble up; the caller treats
-/// them as non-fatal and leaves the original path in place.
+/// Push a local video or audio file to the companion's `POST /media` cache
+/// and return the playback URL it hands back. Reads the file on *this* host
+/// (local Mac, or the remote for an SSH-tunneled session) and uploads the
+/// bytes over the same :7777 channel the render goes through — so it works
+/// identically local and remote without any Mac→remote access. Errors (file
+/// unreadable, 413, old companion without `/media` → 404) bubble up; the
+/// caller treats them as non-fatal and leaves the original path in place.
+///
+/// `ext` names the cached file's extension (and thus the served
+/// Content-Type) — pass [`crate::imageresolve::video_ext`] or
+/// [`crate::imageresolve::audio_ext`] depending on which collector matched
+/// `path`.
 async fn upload_media(
     http: &reqwest::Client,
     cfg: &AppConfig,
     token: &str,
     path: &str,
+    ext: &str,
 ) -> Result<String, String> {
     let expanded = if let Some(rest) = path.strip_prefix("~/") {
         match dirs::home_dir() {
@@ -825,7 +831,6 @@ async fn upload_media(
     let bytes = tokio::fs::read(&expanded)
         .await
         .map_err(|e| format!("read {}: {e}", expanded.display()))?;
-    let ext = crate::imageresolve::video_ext(path);
     let url = format!("{}/media?ext={}", base_url(cfg), ext);
     let resp = http
         .post(&url)
@@ -1057,7 +1062,26 @@ async fn render_dialog(
     if !videos.is_empty() {
         let mut map = std::collections::HashMap::new();
         for path in videos {
-            match upload_media(http, cfg, &token, &path).await {
+            let ext = crate::imageresolve::video_ext(&path);
+            match upload_media(http, cfg, &token, &path, &ext).await {
+                Ok(media_url) => {
+                    map.insert(path, media_url);
+                }
+                Err(e) => trace(&format!("render_dialog: media upload failed for {path}: {e}")),
+            }
+        }
+        crate::imageresolve::replace_srcs(&mut spec, &map);
+    }
+    // Audio (#25): same reasoning as video — route local audio through the
+    // /media cache rather than the 10 MB-capped `data:` inliner, so a form's
+    // `audio` field works uniformly regardless of clip size or whether the
+    // agent runs locally or on a remote SSH host.
+    let audios = crate::imageresolve::collect_local_audio_paths(&spec);
+    if !audios.is_empty() {
+        let mut map = std::collections::HashMap::new();
+        for path in audios {
+            let ext = crate::imageresolve::audio_ext(&path);
+            match upload_media(http, cfg, &token, &path, &ext).await {
                 Ok(media_url) => {
                     map.insert(path, media_url);
                 }
diff --git a/companion/src/lib/widgets/Form.svelte b/companion/src/lib/widgets/Form.svelte
index 341efcf..4dfe76f 100644
--- a/companion/src/lib/widgets/Form.svelte
+++ b/companion/src/lib/widgets/Form.svelte
@@ -80,6 +80,7 @@
           region?: { x: number; y: number; w: number; h: number };
         };
       }
+    | { kind: "audio"; src: string; label?: string }
     | { kind: "mermaid"; source: string; label?: string; max_height?: number }
     | {
         kind: "wireframe";
@@ -208,6 +209,7 @@
       case "static_text":
       case "markdown":
       case "image":
+      case "audio":
       case "mermaid":
       case "wireframe":
         return undefined;
@@ -256,6 +258,7 @@
         f.kind !== "static_text" &&
         f.kind !== "markdown" &&
         f.kind !== "image" &&
+        f.kind !== "audio" &&
         f.kind !== "mermaid" &&
         f.kind !== "wireframe"
     );
@@ -490,6 +493,7 @@
       f.kind === "static_text" ||
       f.kind === "markdown" ||
       f.kind === "image" ||
+      f.kind === "audio" ||
       f.kind === "mermaid" ||
       f.kind === "wireframe"
     )
@@ -693,6 +697,12 @@
             {/if}
           </div>
         </div>
+      {:else if f.kind === "audio"}
+        <figure class="audio-field">
+          {#if f.label}<figcaption>{f.label}</figcaption>{/if}
+          <!-- svelte-ignore a11y_media_has_caption -->
+          <audio src={f.src} controls preload="metadata"></audio>
+        </figure>
       {:else if f.kind === "mermaid"}
         <MermaidView source={f.source} label={f.label} max_height={f.max_height} />
       {:else if f.kind === "wireframe"}
@@ -1125,6 +1135,22 @@
   .annimg-readout code { font-size: 11.5px; }
   .annimg-empty { font-size: 11.5px; color: var(--muted); }
 
+  /* --- audio --- */
+  .audio-field {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+  .audio-field figcaption {
+    font-size: 12px;
+    color: var(--muted);
+  }
+  .audio-field audio {
+    display: block;
+    width: 100%;
+  }
+
   /* --- image grid --- */
   .image-grid {
     display: grid;
diff --git a/docs/skill.md b/docs/skill.md
index e347d92..74a0103 100644
--- a/docs/skill.md
+++ b/docs/skill.md
@@ -43,6 +43,10 @@ instead:
 - Any step that asks **"is this generated image OK?"** → `confirm`
   with `image: {src}`. Don't fall back to a `form`-with-image-and-two-
   buttons when the question is a plain yes/no.
+- Any step that wants the user to **listen to a TTS sample, voice memo,
+  or generated sound clip** before confirming, choosing, or triaging it
+  → `form` with an `audio` field (native `<audio controls>`). Don't
+  paste a file path in chat and ask the user to open it themselves.
 - Any step that asks **"which of these images?"** with 2–6 candidates
   → `ask` with `thumbnail` per option. Use `form` + `image_grid` only
   when there are many candidates (≥ 7) or the picker needs multi-select.
@@ -70,6 +74,7 @@ Skip the dialog for content the user reads, doesn't answer:
 | 2–6 options, possibly with per-option context | `ask` |
 | Pick one of N images ("A or B or C") | `ask` with `thumbnail` per option |
 | Multi-field input, multi-action footer | `form` |
+| Listen to a TTS sample / voice memo / sound clip before deciding | `form` with an `audio` field |
 | Pick one of *many* images (e.g. 12 logo variants) | `form` with `image_grid` |
 | Per-item verdict on a *batch* of images/videos ("approve/revise/skip each") | `gallery` |
 | Pick one of 2–3 full variants shown side by side (drafts, headlines, before/after) | `compare` |
@@ -295,6 +300,35 @@ These don't ask anything — they sit between input fields to give context
 - `static_text` — plain styled note with `tone: "info"|"warn"|"muted"`.
   Lighter weight than `markdown` when no formatting is needed.
 
+## Audio playback: `audio`
+
+Read-only, like `image` — sits between input fields for the user to
+listen to before deciding. Spec: `{kind: "audio", src, label?}`. Renders
+a native `<audio controls>` player; no value is returned in the form
+result.
+
+```json
+{ "kind": "audio", "src": "~/Downloads/tts-sample.mp3", "label": "Voice: warm" }
+```
+
+`src` follows the **same resolution rules as `image`** (see
+[Image sources](#image-sources-src--thumbnail) below), plus one twist:
+a **local** audio path (`mp3`/`m4a`/`wav`/`aac`/`ogg`/`flac`) is never
+inlined as a `data:` URL, no matter how small. It's pushed through the
+same size-unbounded `/media` cache the `gallery` tool uses for local
+video — the bridge uploads the bytes to the Mac and the dialog streams
+them back over a loopback URL, working identically whether you run
+locally or on a remote SSH host. `http(s)://` and `data:` audio URLs
+work exactly like they do for `image` — no special handling needed.
+
+Use `audio` for "does this TTS voice sound right?", "confirm this
+generated jingle", "here's the voice memo the user attached — does it
+transcribe correctly?". For a plain yes/no on the clip, still reach for
+`confirm` if there's nothing else to fill in; use `audio` inside a
+`form` when the listen-then-decide step needs other inputs alongside it
+(a text field for feedback, a `select` for which voice to use next,
+etc.).
+
 ## Visual pickers: `image_grid`
 
 For "pick one (or more) of these N generated images" — logo variants,
@@ -449,6 +483,11 @@ aiui takes an image source in these places:
 - `gallery` → `items[].src` — batch review, images or videos
 - `compare` → `variants[].src` — side-by-side pick, images or videos
 
+(`form` → `audio` field → `src` accepts the same three formats too —
+see [Audio playback](#audio-playback-audio) above — with one difference:
+a local path never inlines as `data:`, it always routes through the
+`/media` cache, size-unbounded.)
+
 In all of them the same three input formats render correctly:
 
 - **Local filesystem path** (`/Users/me/foo.png`, `~/Pictures/x.jpg`)
diff --git a/python/src/aiui_mcp/server.py b/python/src/aiui_mcp/server.py
index eda2203..49a057f 100644
--- a/python/src/aiui_mcp/server.py
+++ b/python/src/aiui_mcp/server.py
@@ -299,6 +299,18 @@ async def _check_wire_compat(client: httpx.AsyncClient) -> None:
     # Pythons, and `image/svg` (without `+xml`) on others. Lock it down
     # so the WebView always sees the canonical `image/svg+xml`.
     ".svg": "image/svg+xml",
+    # Audio (#25): `mimetypes.guess_type` returns None or an inconsistent
+    # value for several of these across Python/OS combinations (notably
+    # `.m4a` and `.flac`). Local audio is normally routed through
+    # `_upload_local_audios` before this function ever runs, but pin these
+    # down anyway so the `data:` fallback path stays correct too — mirrors
+    # `guess_mime_from_extension` in the Rust bridge.
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".wav": "audio/wav",
+    ".aac": "audio/aac",
+    ".ogg": "audio/ogg",
+    ".flac": "audio/flac",
 }
 
 
@@ -447,6 +459,79 @@ async def _upload_local_videos(spec: dict[str, Any], client: httpx.AsyncClient)
     _replace_srcs(spec, mapping)
 
 
+_AUDIO_EXTS = (".mp3", ".m4a", ".wav", ".aac", ".ogg", ".flac")
+
+
+def _is_local_audio(s: str) -> bool:
+    """A local-filesystem path pointing at an audio file by extension.
+    Mirrors `is_local_audio_path` in the Rust bridge (#25). Covers the
+    common lossy/lossless formats a TTS sample, voice memo, or generated
+    sound clip is likely to arrive in.
+    """
+    if not _looks_like_local_path(s):
+        return False
+    stem = s.lower().split("?", 1)[0].split("#", 1)[0]
+    return stem.endswith(_AUDIO_EXTS)
+
+
+def _collect_local_audios(node: Any, out: list[str]) -> None:
+    """Gather distinct local audio paths from every `src`/`thumbnail` slot."""
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if key in _SRC_KEYS and isinstance(value, str) and _is_local_audio(value):
+                if value not in out:
+                    out.append(value)
+            else:
+                _collect_local_audios(value, out)
+    elif isinstance(node, list):
+        for item in node:
+            _collect_local_audios(item, out)
+
+
+async def _upload_local_audios(spec: dict[str, Any], client: httpx.AsyncClient) -> None:
+    """Push local audio files to the companion's `/media` cache and rewrite
+    their `src`/`thumbnail` to the returned loopback playback URL (#25).
+
+    Same reasoning as `_upload_local_videos`: local files are too big (or
+    simply unnecessary) to inline as `data:` given the 10 MB cap + base64
+    bloat, and a remote agent's file isn't readable from the Mac — so the
+    bridge streams the bytes over the same :7777 channel the render uses.
+    Best-effort: a read error, a 413, or an old companion without `/media`
+    (404) leaves the path untouched, and `_resolve_local_paths` then does
+    whatever it can with it.
+    """
+    paths: list[str] = []
+    _collect_local_audios(spec, paths)
+    if not paths:
+        return
+    mapping: dict[str, str] = {}
+    for p in paths:
+        try:
+            data = Path(p).expanduser().read_bytes()
+        except OSError as e:
+            log.warning("audio skipped (read failed) %s: %s", p, e)
+            continue
+        ext = p.lower().split("?", 1)[0].split("#", 1)[0].rsplit(".", 1)[-1] or "mp3"
+        try:
+            r = await client.post(
+                f"{ENDPOINT}/media",
+                params={"ext": ext},
+                headers={
+                    "Authorization": f"Bearer {_token()}",
+                    "Content-Type": "application/octet-stream",
+                },
+                content=data,
+            )
+            r.raise_for_status()
+            url = r.json().get("url")
+        except (httpx.HTTPError, ValueError) as e:
+            log.warning("audio upload failed %s: %s", p, e)
+            continue
+        if url:
+            mapping[p] = url
+    _replace_srcs(spec, mapping)
+
+
 def _collect_target_fields(spec: dict[str, Any]) -> list[dict[str, Any]]:
     """Form fields carrying a non-null `target` (#135), from flat `fields` and
     any `tabs[].fields`."""
@@ -704,6 +789,10 @@ async def _post_render(
         # swap their `src` for the returned playback URL — BEFORE the image
         # inliner runs, so it never tries to base64 a huge clip.
         await _upload_local_videos(spec, client)
+        # Audio (#25): same reasoning — local audio for the form `audio`
+        # field is routed through the /media cache instead of the 10 MB
+        # `data:` inliner, uniformly regardless of clip size.
+        await _upload_local_audios(spec, client)
         # Resolve any absolute / `~/`-rooted file paths *before* shipping
         # the spec down the HTTP wire. This bridge runs on the same host
         # as the agent — local for Mac use, remote for SSH-tunneled
@@ -868,6 +957,7 @@ async def form(
     - markdown:    {kind, text}  — read-only Markdown block; only as inline context for following inputs in the same form, NOT as a standalone display tool.
     - image:       {kind, src, label?, alt?, max_height?}  — read-only image. `src` accepts an absolute / `~/` local path (read on YOUR host), an `http(s)://` URL (fetched on the Mac), or a `data:` URL. Use for visual confirmation of agent-generated previews.
     - annotated_image: {kind, name, src, label?, alt?, mode?, max_height?, required?, default?}  — let the user MARK a spot on an image (logo placement, crop hint, bug location). `src` follows the same rules as `image`. `mode` ∈ {"point" (click one marker, default), "region" (drag a rectangle), "both" (user flips a Point/Region tool)}. `default` may seed `{point?: {x, y}, region?: {x, y, w, h}}` in normalized units. Result under `name`: {point: {x, y} | null, region: {x, y, w, h} | null, natural: {width, height} | null} — all coordinates normalized 0..1; multiply by `natural` for pixels.
+    - audio:       {kind, src, label?}  — read-only native `<audio controls>` player. Use for "listen to this TTS sample / voice memo / generated sound clip before deciding". `src` accepts a `data:audio/...` URL, an `http(s)://` URL, or an absolute/`~/` local path (mp3/m4a/wav/aac/ogg/flac) — local audio is pushed through the same size-unbounded `/media` cache as gallery video, never the 10 MB `data:` inliner.
     - mermaid:     {kind, source, label?, max_height?}  — read-only Mermaid diagram (flowchart, sequence, state, gantt, mindmap, …). `source` is a Mermaid-DSL string. Use this instead of ASCII / box-drawing art when you'd otherwise sketch a diagram in chat — aiui renders to SVG and DOMPurify-sanitises before display.
     - wireframe:   {kind, panels: [{title?, content?, col_span?, row_span?, tone?}], columns?, gap?, label?, max_height?}  — read-only UI-layout mockup. Real CSS-Grid panels with optional header (`title`) and multi-line monospace body (`content`, escape `\n`). `tone` ∈ {"default","muted","highlight"}. Use this for *UI-layouts* (dashboard tiles, hardware-UI panels, login screens, anything with fixed-position boxes-and-labels) instead of ASCII boxes-and-pipes — `mermaid` is for *diagrams* (graphs, sequence/state, gantt). Wireframe complements it for the layout class.
     - image_grid:  {kind, name, label?, images: [{value, src, label?}], multi_select?, columns?, default_selected?, required?}
diff --git a/python/src/aiui_mcp/skill.md b/python/src/aiui_mcp/skill.md
index cc422d9..3383620 100644
--- a/python/src/aiui_mcp/skill.md
+++ b/python/src/aiui_mcp/skill.md
@@ -33,6 +33,10 @@ instead:
   sortable `list` field.
 - Any step that wants a **date, datetime, range, color, or numeric value
   in a bounded interval** → `form` with the matching field.
+- Any step that wants the user to **listen to a TTS sample, voice memo,
+  or generated sound clip** before confirming, choosing, or triaging it
+  → `form` with an `audio` field (native `<audio controls>`). Don't
+  paste a file path in chat and ask the user to open it themselves.
 
 ## When chat actually wins
 
@@ -51,6 +55,7 @@ Skip the dialog for content the user reads, doesn't answer:
 | Yes/no, especially destructive | `confirm` |
 | 2–6 options, possibly with per-option context | `ask` |
 | Multi-field input, multi-action footer | `form` |
+| Listen to a TTS sample / voice memo / sound clip before deciding | `form` with an `audio` field |
 | Per-item verdict on a *batch* of images/videos ("approve/revise/skip each") | `gallery` |
 | Single free-text answer | just ask in chat |
 | More than 8 fields | split into multiple `form` calls; do not cram one dialog |
@@ -127,6 +132,23 @@ These don't ask anything — they sit between input fields to give context
 - `static_text` — plain styled note with `tone: "info"|"warn"|"muted"`.
   Lighter weight than `markdown` when no formatting is needed.
 
+## Audio playback: `audio`
+
+Read-only, like `image` — sits between input fields for the user to
+listen to before deciding. Spec: `{kind: "audio", src, label?}`. Renders
+a native `<audio controls>` player; no value is returned in the form
+result. `src` accepts a `data:audio/...` URL, an `http(s)://` URL, or an
+absolute/`~/` local path (mp3/m4a/wav/aac/ogg/flac). A local audio path
+is never inlined as `data:` — even a small clip — it's always pushed
+through the same size-unbounded `/media` cache the `gallery` tool uses
+for local video, so it works identically whether this bridge runs on
+the user's Mac or a remote SSH host it's reaching over the reverse
+tunnel.
+
+Use `audio` for "does this TTS voice sound right?", "confirm this
+generated jingle", "here's the voice memo — does it transcribe
+correctly?".
+
 ## Schematic diagrams: `mermaid`
 
 For graph-shaped visualisations — flowcharts, sequence diagrams, state
diff --git a/python/tests/test_resolve_local_paths.py b/python/tests/test_resolve_local_paths.py
index 0761f50..d9bb41a 100644
--- a/python/tests/test_resolve_local_paths.py
+++ b/python/tests/test_resolve_local_paths.py
@@ -14,7 +14,9 @@
 import pytest
 
 from aiui_mcp.server import (
+    _collect_local_audios,
     _collect_local_videos,
+    _is_local_audio,
     _is_local_video,
     _looks_like_local_path,
     _read_path_as_data_url,
@@ -227,3 +229,62 @@ def test_collect_and_replace_local_videos_mirrors_rust() -> None:
     # Untouched: https video and the image.
     assert spec["items"][1]["src"] == "https://x.test/two.mp4"
     assert spec["items"][2]["src"] == "/Users/me/pic.png"
+
+
+def test_read_path_as_data_url_uses_audio_mime_overrides(tmp_path: Path) -> None:
+    for ext, mime in (
+        ("mp3", "audio/mpeg"),
+        ("m4a", "audio/mp4"),
+        ("wav", "audio/wav"),
+        ("aac", "audio/aac"),
+        ("ogg", "audio/ogg"),
+        ("flac", "audio/flac"),
+    ):
+        f = tmp_path / f"sample.{ext}"
+        f.write_bytes(b"fake audio bytes")
+        url = _read_path_as_data_url(str(f))
+        assert url.startswith(f"data:{mime};base64,"), f"{ext}: {url}"
+
+
+def test_is_local_audio_classifies_correctly() -> None:
+    assert _is_local_audio("/Users/me/sample.mp3")
+    assert _is_local_audio("~/Music/voice.M4A")
+    assert _is_local_audio("/tmp/a.wav")
+    assert _is_local_audio("/tmp/a.aac")
+    assert _is_local_audio("/tmp/a.ogg")
+    assert _is_local_audio("/tmp/a.flac")
+    assert not _is_local_audio("https://x.test/clip.mp3")
+    assert not _is_local_audio("data:audio/mpeg;base64,AAAA")
+    assert not _is_local_audio("/Users/me/photo.png")
+    assert not _is_local_audio("/Users/me/clip.mp4")  # video, not audio
+    assert not _is_local_audio("relative/clip.mp3")
+
+
+def test_collect_and_replace_local_audio_mirrors_rust() -> None:
+    spec = {
+        "kind": "form",
+        "fields": [
+            {"kind": "audio", "src": "/Users/me/sample.mp3"},
+            {"kind": "audio", "src": "https://x.test/two.mp3"},
+            {"kind": "image", "src": "/Users/me/pic.png"},
+            {
+                "kind": "list",
+                "items": [{"label": "L", "value": "l", "thumbnail": "/Users/me/sample.mp3"}],
+            },
+        ],
+    }
+    found: list[str] = []
+    _collect_local_audios(spec, found)
+    # De-duplicated: the same path in two slots appears once.
+    assert found == ["/Users/me/sample.mp3"]
+
+    mapping = {"/Users/me/sample.mp3": "http://127.0.0.1:7777/media/blob/x.mp3"}
+    _replace_srcs(spec, mapping)
+    assert spec["fields"][0]["src"] == "http://127.0.0.1:7777/media/blob/x.mp3"
+    assert (
+        spec["fields"][3]["items"][0]["thumbnail"]
+        == "http://127.0.0.1:7777/media/blob/x.mp3"
+    )
+    # Untouched: https audio and the image.
+    assert spec["fields"][1]["src"] == "https://x.test/two.mp3"
+    assert spec["fields"][2]["src"] == "/Users/me/pic.png"