docs: audio tab Phase 1 implementation plan (extract/edit/classify)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-02 13:36:37 +02:00
parent e14cebd081
commit 8f18c7a817
1 changed files with 648 additions and 0 deletions
@@ -0,0 +1,648 @@
+# Audio Workspace Tab — Phase 1 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the **Scan** control-deck tab with a first-class **Audio** tab (a `QToolBox` with *Extract & Edit* and *Scan / Classify* panes), relocate the extract controls off the transport row, add a persistent output-format picker, and add non-destructive parametric editing (fade / normalize / gain via an ffmpeg `-af` chain, plus trim by adjusting the extract window) with a read-only waveform strip and play/stop audition.
+
+**Architecture:** Pure `core/ffmpeg.py` helper for the filter chain (fully unit-tested). `main.py` renames `_tab_scan`→`_tab_audio`, rebuilds its body as a `QToolBox`, moves the existing extract widgets into it, and adds the new edit widgets. No DB/schema change; Phase 2 (audio dataset) is deferred. The Foley/LTX-2 export path and `ScanResultsPanel` are untouched.
+
+**Tech Stack:** Python 3, PyQt6, ffmpeg/ffprobe (via `core/ffmpeg.py`), pytest. UI tests use the existing `win` fixture in `tests/test_ui_structure.py` (offscreen Qt).
+
+**Design doc:** `docs/plans/2026-07-02-audio-tab-design.md`
+
+---
+
+## Conventions
+
+- Run one test: `pytest tests/test_utils.py::test_name -v`
+- Run UI tests: `pytest tests/test_ui_structure.py -v` (needs the offscreen/LD_PRELOAD env the repo already uses — see `conftest.py`).
+- Commit after every green step. Prefix messages `feat:` / `test:` / `refactor:`.
+- Work on branch `audio-tab` (already created; design doc already committed there).
+
+---
+
+## Task 1: ffmpeg filter-chain helper + `filters` param
+
+Non-destructive editing is applied at render time as an ffmpeg `-af` chain. The
+chain builder is a pure function → fully unit-testable without invoking ffmpeg.
+Trim is **not** a filter: trim-in/out just adjust the `start`/`duration` passed
+to `build_audio_clip_command` (done in Task 5), so this task only covers
+fade / normalize / gain.
+
+**Files:**
+- Modify: `core/ffmpeg.py` (add `audio_edit_filters`, extend `build_audio_clip_command` at lines 204-218)
+- Test: `tests/test_utils.py` (after the existing audio-clip tests, ~line 77)
+
+**Step 1: Write the failing tests**
+
+```python
+def test_audio_edit_filters_empty_when_defaults():
+    from core.ffmpeg import audio_edit_filters
+    assert audio_edit_filters(duration=3.0) == []
+
+def test_audio_edit_filters_fade_normalize_gain():
+    from core.ffmpeg import audio_edit_filters
+    f = audio_edit_filters(duration=10.0, fade_in=0.5, fade_out=2.0,
+                           normalize=True, gain_db=-3.0)
+    assert "afade=t=in:st=0:d=0.5" in f
+    # fade-out starts at duration - fade_out
+    assert "afade=t=out:st=8.0:d=2.0" in f
+    assert "loudnorm" in f
+    assert "volume=-3.0dB" in f
+
+def test_audio_clip_command_no_filters_unchanged():
+    # No filters -> byte-identical to today's command (no -af).
+    cmd = build_audio_clip_command("/in.mp4", 1.0, 2.0, "/o/a.wav")
+    assert "-af" not in cmd
+
+def test_audio_clip_command_appends_filter_chain():
+    cmd = build_audio_clip_command("/in.mp4", 1.0, 2.0, "/o/a.wav",
+                                   filters=["afade=t=in:st=0:d=0.5", "loudnorm"])
+    i = cmd.index("-af")
+    assert cmd[i + 1] == "afade=t=in:st=0:d=0.5,loudnorm"
+    # filter chain sits before the output path, after -vn/codec
+    assert i < len(cmd) - 1 and cmd[-1] == "/o/a.wav"
+```
+
+**Step 2: Run to verify they fail**
+
+Run: `pytest tests/test_utils.py -k "audio_edit_filters or filter_chain or no_filters" -v`
+Expected: FAIL (`audio_edit_filters` not defined; `filters` is an unexpected kwarg).
+
+**Step 3: Implement**
+
+Add above `build_audio_clip_command` in `core/ffmpeg.py`:
+
+```python
+def audio_edit_filters(duration: float, fade_in: float = 0.0,
+                       fade_out: float = 0.0, normalize: bool = False,
+                       gain_db: float = 0.0) -> list[str]:
+    """Compose an ffmpeg -af chain for the non-destructive audio edits.
+
+    Trim is handled by the caller (it adjusts start/duration), so only
+    fade / normalize / gain appear here. Returns [] when nothing is set, so
+    the extract command stays byte-identical to the un-edited case."""
+    chain: list[str] = []
+    if fade_in > 0:
+        chain.append(f"afade=t=in:st=0:d={fade_in}")
+    if fade_out > 0:
+        st = max(0.0, duration - fade_out)
+        chain.append(f"afade=t=out:st={st}:d={fade_out}")
+    if normalize:
+        chain.append("loudnorm")
+    if gain_db != 0.0:
+        chain.append(f"volume={gain_db}dB")
+    return chain
+```
+
+Extend `build_audio_clip_command`:
+
+```python
+def build_audio_clip_command(input_path: str, start: float, duration: float,
+                             out_path: str,
+                             filters: "list[str] | None" = None) -> list[str]:
+    """ffmpeg command to extract exactly *duration* seconds of audio starting
+    at *start*, re-encoded per *out_path*'s extension (wav/mp3/flac/…).
+    *filters* (if any) are joined into a single -af chain."""
+    ext = os.path.splitext(out_path)[1].lower()
+    codec = _AUDIO_CODEC_BY_EXT.get(ext, [])
+    af = ["-af", ",".join(filters)] if filters else []
+    return [
+        _bin("ffmpeg"), "-y",
+        "-ss", str(start),
+        "-i", input_path,
+        "-t", str(duration),
+        "-vn",
+        *codec,
+        *af,
+        out_path,
+    ]
+```
+
+**Step 4: Run to verify pass**
+
+Run: `pytest tests/test_utils.py -k audio -v`
+Expected: PASS (new tests + the existing `test_audio_clip_command_*` still green).
+
+**Step 5: Commit**
+
+```bash
+git add core/ffmpeg.py tests/test_utils.py
+git commit -m "feat: audio_edit_filters helper + optional -af chain on build_audio_clip_command"
+```
+
+---
+
+## Task 2: Rename the Scan deck tab → Audio (structure only)
+
+Pure rename/re-key of the deck panel. The body still holds the scan grid for now
+(Task 4 replaces it with the `QToolBox`). This isolates the deck-wiring change
+from the layout change.
+
+**Files:**
+- Modify: `main.py` imports (line ~22), `_build_control_deck` (4666-4685), the builder call at 4498, and `_build_scan_tab` def (4745)
+- Test: `tests/test_ui_structure.py` (new test near the audio tests, ~line 274)
+
+**Step 1: Write the failing test**
+
+```python
+def test_audio_deck_tab_exists(win):
+    # The old "Scan" deck tab is now "Audio".
+    assert hasattr(win, "_tab_audio")
+    assert win._tab_audio._deck_key == "audio"
+    assert win._tab_audio in win._deck_panels
+    assert not hasattr(win, "_tab_scan")
+    labels = [win._control_deck.tabText(i)
+              for i in range(win._control_deck.count())]
+    assert "Audio" in labels and "Scan" not in labels
+```
+
+**Step 2: Run to verify it fails**
+
+Run: `pytest tests/test_ui_structure.py::test_audio_deck_tab_exists -v`
+Expected: FAIL (`_tab_scan` still present; no `_tab_audio`).
+
+**Step 3: Implement**
+
+1. Add `QToolBox, QGroupBox` to the `PyQt6.QtWidgets` import block (line ~22, next to `QTabWidget, QTabBar`):
+
+```python
+    QTableWidget, QTableWidgetItem, QTabWidget, QTabBar, QHeaderView,
+    QToolBox, QGroupBox,
+    QGridLayout,
+```
+
+2. In `_build_control_deck`, replace the three `_tab_scan` lines (4668, 4678-4680) and the `_deck_panels`/`addTab` lines (4682, 4685):
+
+```python
+        self._tab_audio = QWidget();  self._tab_audio.setObjectName("audio_tab")
+        ...
+        self._tab_audio._pinned = False
+        self._tab_audio._label = "Audio"
+        self._tab_audio._deck_key = "audio"
+        # Ordered list for deterministic column / tab order.
+        self._deck_panels = [self._tab_export, self._tab_crop, self._tab_audio]
+        deck.addTab(self._tab_export, self._tab_export._label)
+        deck.addTab(self._tab_crop, self._tab_crop._label)
+        deck.addTab(self._tab_audio, self._tab_audio._label)
+```
+
+3. Rename the method `def _build_scan_tab(self)` → `def _build_audio_tab(self)` and change `QGridLayout(self._tab_scan)` → `QGridLayout(self._tab_audio)` (temporary; Task 4 rewrites the body).
+
+4. Change the call at line 4498 `self._build_scan_tab()` → `self._build_audio_tab()`.
+
+**Step 4: Run to verify pass**
+
+Run: `pytest tests/test_ui_structure.py -v`
+Expected: PASS (new test green; existing deck/pin tests still green).
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_ui_structure.py
+git commit -m "refactor: rename Scan deck tab -> Audio (deck wiring only)"
+```
+
+---
+
+## Task 3: Construct the new Audio widgets; drop extract controls from the transport row
+
+Build the new edit widgets in `__init__` next to the existing extract controls
+(~line 4438-4464), and stop adding `_spn_audio_len` / `_btn_extract_audio` to the
+transport row (they move into the tab in Task 4). Keep the widgets as instance
+attributes so `_build_audio_tab` can place them.
+
+**Files:**
+- Modify: `main.py` transport-row block (4441-4464)
+- Test: `tests/test_ui_structure.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_audio_edit_widgets_exist(win):
+    from PyQt6.QtWidgets import QComboBox, QCheckBox, QDoubleSpinBox
+    assert isinstance(win._cmb_audio_fmt, QComboBox)
+    assert win._cmb_audio_fmt.count() >= 3            # wav/mp3/flac at least
+    assert isinstance(win._spn_fade_in, QDoubleSpinBox)
+    assert isinstance(win._spn_fade_out, QDoubleSpinBox)
+    assert isinstance(win._chk_normalize, QCheckBox)
+    assert isinstance(win._spn_gain, QDoubleSpinBox)
+```
+
+**Step 2: Run to verify it fails**
+
+Run: `pytest tests/test_ui_structure.py::test_audio_edit_widgets_exist -v`
+Expected: FAIL (attributes don't exist).
+
+**Step 3: Implement**
+
+After the `_btn_extract_audio` construction (~line 4461), add:
+
+```python
+        # Output format (persisted) — drives the extract extension + save filter.
+        self._cmb_audio_fmt = QComboBox()
+        for label, ext in (("WAV", ".wav"), ("MP3", ".mp3"), ("FLAC", ".flac"),
+                           ("M4A", ".m4a"), ("OGG", ".ogg"), ("OPUS", ".opus")):
+            self._cmb_audio_fmt.addItem(label, ext)
+        _saved_fmt = self._settings.value("audio_extract_fmt", ".wav")
+        _idx = self._cmb_audio_fmt.findData(_saved_fmt)
+        if _idx >= 0:
+            self._cmb_audio_fmt.setCurrentIndex(_idx)
+        self._cmb_audio_fmt.currentIndexChanged.connect(
+            lambda _i: self._settings.setValue(
+                "audio_extract_fmt", self._cmb_audio_fmt.currentData()))
+
+        # Non-destructive edit controls (applied via ffmpeg -af at extract time).
+        self._spn_fade_in = QDoubleSpinBox()
+        self._spn_fade_in.setRange(0.0, 30.0); self._spn_fade_in.setDecimals(2)
+        self._spn_fade_in.setSingleStep(0.1); self._spn_fade_in.setSuffix(" s")
+        self._spn_fade_in.setToolTip("Fade-in duration (0 = none)")
+        self._spn_fade_out = QDoubleSpinBox()
+        self._spn_fade_out.setRange(0.0, 30.0); self._spn_fade_out.setDecimals(2)
+        self._spn_fade_out.setSingleStep(0.1); self._spn_fade_out.setSuffix(" s")
+        self._spn_fade_out.setToolTip("Fade-out duration (0 = none)")
+        self._chk_normalize = QCheckBox("Normalize")
+        self._chk_normalize.setToolTip("Apply EBU R128 loudness normalization (loudnorm)")
+        self._spn_gain = QDoubleSpinBox()
+        self._spn_gain.setRange(-30.0, 30.0); self._spn_gain.setDecimals(1)
+        self._spn_gain.setSingleStep(0.5); self._spn_gain.setSuffix(" dB")
+        self._spn_gain.setToolTip("Gain applied to the extracted audio (0 = unchanged)")
+```
+
+Then **remove** these two lines (currently 4462-4463) so the controls no longer
+sit in the transport row:
+
+```python
+        transport_row.addWidget(self._spn_audio_len)
+        transport_row.addWidget(self._btn_extract_audio)
+```
+
+(Leave the `transport_row.addSpacing(12)` at 4440 if it now orphans a trailing
+spacer — check the row visually in Task 8; drop the spacer if it looks odd.)
+
+**Step 4: Run to verify pass**
+
+Run: `pytest tests/test_ui_structure.py::test_audio_edit_widgets_exist -v`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_ui_structure.py
+git commit -m "feat: audio format + fade/normalize/gain widgets; free them from the transport row"
+```
+
+---
+
+## Task 4: Rebuild `_build_audio_tab` as a `QToolBox` (Extract & Edit / Scan · Classify)
+
+Replace the temporary scan grid with a two-page `QToolBox`. Page 1 places the
+extract + edit widgets; Page 2 holds the (moved) scan grid.
+
+**Files:**
+- Modify: `main.py` `_build_audio_tab` (formerly `_build_scan_tab`, ~4745)
+- Test: `tests/test_ui_structure.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_audio_toolbox_has_two_panes(win):
+    from PyQt6.QtWidgets import QToolBox
+    tb = win._tab_audio.findChild(QToolBox)
+    assert tb is not None
+    titles = [tb.itemText(i) for i in range(tb.count())]
+    assert titles[0].startswith("Extract")
+    assert any("Scan" in t or "Classify" in t for t in titles)
+    # Extract controls now live under the Audio tab, not the transport row.
+    assert win._btn_extract_audio.parent() is not None
+    # Scan controls remain reachable.
+    assert win._btn_scan.isEnabled() in (True, False)
+```
+
+**Step 2: Run to verify it fails**
+
+Run: `pytest tests/test_ui_structure.py::test_audio_toolbox_has_two_panes -v`
+Expected: FAIL (no `QToolBox` under `_tab_audio`).
+
+**Step 3: Implement**
+
+Rewrite `_build_audio_tab` (keep the existing scan grid content — the `model_row`
+… `threshold` widgets — verbatim, just parented to the new `scan_page`):
+
+```python
+    def _build_audio_tab(self) -> None:
+        outer = QVBoxLayout(self._tab_audio)
+        outer.setContentsMargins(0, 0, 0, 0)
+        tb = QToolBox()
+
+        # ── Page 1: Extract & Edit ───────────────────────────────
+        extract_page = QWidget()
+        g = QGridLayout(extract_page)
+        g.setContentsMargins(8, 6, 8, 6); g.setHorizontalSpacing(8); g.setVerticalSpacing(6)
+        g.addWidget(QLabel("Length:"), 0, 0)
+        g.addWidget(self._spn_audio_len, 0, 1)
+        g.addWidget(QLabel("Format:"), 0, 2)
+        g.addWidget(self._cmb_audio_fmt, 0, 3)
+        g.addWidget(self._group_sep(), 1, 0, 1, 4)
+        g.addWidget(QLabel("Fade in:"), 2, 0);  g.addWidget(self._spn_fade_in, 2, 1)
+        g.addWidget(QLabel("Fade out:"), 2, 2); g.addWidget(self._spn_fade_out, 2, 3)
+        g.addWidget(self._chk_normalize, 3, 0, 1, 2)
+        g.addWidget(QLabel("Gain:"), 3, 2);     g.addWidget(self._spn_gain, 3, 3)
+        # Waveform strip + audition land here in Tasks 6-7 (placeholder row 4).
+        g.addWidget(self._btn_extract_audio, 5, 0, 1, 4)
+        tb.addItem(extract_page, "Extract & Edit")
+
+        # ── Page 2: Scan / Classify (moved verbatim) ─────────────
+        scan_page = QWidget()
+        sg = QGridLayout(scan_page)
+        sg.setContentsMargins(8, 6, 8, 6); sg.setHorizontalSpacing(8); sg.setVerticalSpacing(6)
+        model_row = QHBoxLayout()
+        model_row.addWidget(self._cmb_scan_model, 1); model_row.addWidget(self._btn_model_history)
+        sg.addWidget(QLabel("Model:"), 0, 0); sg.addLayout(model_row, 0, 1, 1, 3)
+        sg.addWidget(self._group_sep(), 1, 0, 1, 4)
+        sg.addWidget(self._btn_scan, 2, 0); sg.addWidget(self._btn_auto_export, 2, 1)
+        sg.addWidget(self._btn_speech, 2, 2); sg.addWidget(self._btn_scan_mode, 2, 3)
+        sg.addWidget(self._group_sep(), 3, 0, 1, 4)
+        sg.addWidget(self._spn_auto_fuse, 4, 0); sg.addWidget(self._sld_threshold, 4, 1)
+        sg.setColumnStretch(3, 1)
+        tb.addItem(scan_page, "Scan / Classify")
+
+        outer.addWidget(tb)
+```
+
+> Confirm `QVBoxLayout` and `QLabel` are imported (they are — used throughout).
+> If `QVBoxLayout` is missing from the import block, add it.
+
+**Step 4: Run to verify pass**
+
+Run: `pytest tests/test_ui_structure.py -v`
+Expected: PASS. Update the existing `test_extract_audio_controls_exist` if it
+assumed the transport row — it only checks widget types/attrs, so it stays green.
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_ui_structure.py
+git commit -m "feat: Audio tab QToolBox — Extract & Edit + Scan/Classify panes"
+```
+
+---
+
+## Task 5: Wire format + edit params into `_on_extract_audio`
+
+Extraction now honors the format picker (extension + save filter) and the edit
+controls (fade/normalize/gain via `audio_edit_filters`; trim is deferred to the
+optional trim spinboxes — see note). Keep the existing no-clamp behavior and
+truncation reporting.
+
+**Files:**
+- Modify: `main.py` `_on_extract_audio` (6403-6457) + import (`audio_edit_filters` at line 38)
+- Test: covered by `tests/test_utils.py` (command-level, Task 1) + manual (Task 8). Add one behavior test below.
+
+**Step 1: Write the failing test** (in `tests/test_ui_structure.py`)
+
+```python
+def test_extract_uses_selected_format_and_edits(win, monkeypatch, tmp_path):
+    import core.ffmpeg as fx
+    win._file_path = "/x/video.mp4"
+    win._cursor = 5.0
+    win._spn_audio_len.setValue(4.0)
+    # pick MP3
+    win._cmb_audio_fmt.setCurrentIndex(win._cmb_audio_fmt.findData(".mp3"))
+    win._spn_fade_in.setValue(0.5)
+    captured = {}
+    def fake_cmd(inp, start, dur, out, filters=None):
+        captured.update(out=out, filters=filters or [])
+        return ["true"]
+    monkeypatch.setattr(win_module, "build_audio_clip_command", fake_cmd)  # module alias
+    # short-circuit the save dialog to a temp mp3 and subprocess to success
+    monkeypatch.setattr(win_module.QFileDialog, "getSaveFileName",
+                        staticmethod(lambda *a, **k: (str(tmp_path / "c.mp3"), "")))
+    monkeypatch.setattr(win_module.subprocess, "run",
+                        lambda *a, **k: type("P", (), {"returncode": 0, "stderr": ""})())
+    monkeypatch.setattr(win_module.os.path, "exists", lambda p: True)
+    win._on_extract_audio()
+    assert captured["out"].endswith(".mp3")
+    assert any("afade=t=in" in f for f in captured["filters"])
+```
+
+> `win_module` = the imported `main` module in the test file; adjust to the
+> fixture's existing import alias. If patching `os.path.exists` globally is too
+> broad, patch `main.os.path.exists` only within the call or assert on
+> `captured` before the exists check by making `fake_cmd` raise a sentinel.
+
+**Step 2: Run to verify it fails**
+
+Run: `pytest tests/test_ui_structure.py::test_extract_uses_selected_format_and_edits -v`
+Expected: FAIL (format/edits not yet honored).
+
+**Step 3: Implement**
+
+In `_on_extract_audio`, replace the default-name/extension + command build:
+
+```python
+        start = self._cursor
+        dur = self._spn_audio_len.value()
+        ext = self._cmb_audio_fmt.currentData() or ".wav"
+        fmt_label = self._cmb_audio_fmt.currentText()
+        stem = os.path.splitext(os.path.basename(self._file_path))[0]
+        default_name = f"{stem}_{start:.2f}-{start + dur:.2f}s{ext}"
+        default_dir = (self._settings.value("audio_extract_dir", "")
+                       or self._tab_export_folder()
+                       or os.path.dirname(self._file_path))
+        # Put the chosen format first in the filter list.
+        filters = (f"{fmt_label} (*{ext});;WAV (*.wav);;MP3 (*.mp3);;"
+                   "FLAC (*.flac);;All files (*)")
+        path, _sel = QFileDialog.getSaveFileName(
+            self, "Save audio clip", os.path.join(default_dir, default_name), filters)
+        if not path:
+            return
+        if not os.path.splitext(path)[1]:
+            path += ext
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        edit = audio_edit_filters(
+            duration=dur,
+            fade_in=self._spn_fade_in.value(),
+            fade_out=self._spn_fade_out.value(),
+            normalize=self._chk_normalize.isChecked(),
+            gain_db=self._spn_gain.value())
+        cmd = build_audio_clip_command(self._file_path, start, dur, path,
+                                       filters=edit or None)
+```
+
+Add `audio_edit_filters` to the ffmpeg import at line 38:
+
+```python
+from core.ffmpeg import (build_audio_clip_command, audio_edit_filters,
+                         probe_duration, ...)   # keep existing names
+```
+
+**Step 4: Run to verify pass**
+
+Run: `pytest tests/test_ui_structure.py -v && pytest tests/test_utils.py -k audio -v`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_ui_structure.py
+git commit -m "feat: extract honors format picker + fade/normalize/gain edits"
+```
+
+---
+
+## Task 6: Read-only waveform strip
+
+A compact widget that paints peak envelopes of the current region, refreshed on
+cursor/length change. Decoding reuses `core/audio_scan._load_audio_ffmpeg`
+(already returns mono float samples). Keep it dependency-free (QPainter).
+
+**Files:**
+- Create: `AudioWaveform(QWidget)` class in `main.py` (near `TimelineWidget`, ~line 1857) OR a small `core/waveform.py` for the peak-reduction (testable) + a thin painter in `main.py`.
+- Modify: `_build_audio_tab` (add to row 4 of the extract grid), `_update_audio_region` (6394) to refresh peaks.
+- Test: `tests/test_utils.py` for the pure peak-reduction; UI smoke test for the widget.
+
+**Step 1: Write the failing test** (pure reduction in `core/waveform.py`)
+
+```python
+def test_peaks_downsamples_to_bucket_count():
+    from core.waveform import peaks
+    import numpy as np
+    samples = np.sin(np.linspace(0, 100, 10000)).astype("float32")
+    p = peaks(samples, buckets=64)
+    assert len(p) == 64
+    assert all(0.0 <= v <= 1.0 for v in p)
+```
+
+**Step 2: Run to verify it fails** — `pytest tests/test_utils.py::test_peaks_downsamples_to_bucket_count -v` → FAIL (no module).
+
+**Step 3: Implement** `core/waveform.py`:
+
+```python
+import numpy as np
+
+def peaks(samples, buckets: int = 128) -> list[float]:
+    """Reduce a 1-D sample array to *buckets* normalized peak magnitudes."""
+    if samples is None or len(samples) == 0:
+        return [0.0] * buckets
+    a = np.abs(np.asarray(samples, dtype="float32"))
+    idx = np.linspace(0, len(a), buckets + 1).astype(int)
+    out = [float(a[idx[i]:idx[i + 1]].max()) if idx[i + 1] > idx[i] else 0.0
+           for i in range(buckets)]
+    m = max(out) or 1.0
+    return [v / m for v in out]
+```
+
+Then add `AudioWaveform(QWidget)` in `main.py`: stores `self._peaks: list[float]`,
+`set_peaks(p)` calls `update()`, `paintEvent` draws vertical bars centered on the
+mid-line (teal, matching the timeline band `QColor(0,220,190)`). Fixed height ~48.
+Place it at extract-grid row 4 spanning 4 columns. In `_update_audio_region`,
+after computing `start`, decode the `[start, start+len]` slice off-thread (reuse
+the scan prefetch pattern) or lazily on a "↻" button to avoid blocking the UI —
+**decode must not run on the UI thread for long clips**; gate it behind a manual
+refresh button in v1 (simplest, no threading).
+
+**Step 4: Run to verify pass** — `pytest tests/test_utils.py -k peaks -v` → PASS.
+
+**Step 5: Commit**
+
+```bash
+git add core/waveform.py main.py tests/test_utils.py
+git commit -m "feat: read-only waveform strip for the Audio tab"
+```
+
+---
+
+## Task 7: Play / Stop audition
+
+Audition the current region without disturbing the mpv video player. Simplest
+robust approach: extract the region to a temp file via the existing command and
+play it with `QMediaPlayer` + `QAudioOutput` (PyQt6.QtMultimedia), or shell out
+to `ffplay`. Keep it a toggle button `_btn_audio_play`.
+
+**Files:**
+- Modify: `main.py` (`_btn_audio_play` construction in Task 3 block; handler `_on_audio_audition`; place button in `_build_audio_tab`).
+- Test: UI smoke test that the button exists and toggling with no file is a no-op.
+
+**Step 1: Write the failing test**
+
+```python
+def test_audition_button_exists_and_safe_without_file(win):
+    from PyQt6.QtWidgets import QPushButton
+    assert isinstance(win._btn_audio_play, QPushButton)
+    win._file_path = ""
+    win._on_audio_audition()   # must not raise
+```
+
+**Step 2: Run** → FAIL (no `_btn_audio_play`).
+
+**Step 3: Implement** — construct `_btn_audio_play` (checkable, "▶ Play") in the
+Task 3 widget block; add to the extract grid next to the waveform; handler
+renders the current region (respecting edits) to a temp file under the scratch
+dir and plays via `QMediaPlayer`; toggling off stops. Guard on `self._file_path`.
+Decide `QMediaPlayer` vs `ffplay` during implementation; prefer `QMediaPlayer`
+(no extra process, stops cleanly). If QtMultimedia is unavailable in the frozen
+build, fall back to `ffplay -autoexit -nodisp`.
+
+**Step 4: Run** → PASS.
+
+**Step 5: Commit**
+
+```bash
+git add main.py tests/test_ui_structure.py
+git commit -m "feat: play/stop audition of the current audio region"
+```
+
+---
+
+## Task 8: Full test pass, visual check, docs
+
+**Step 1:** Run the whole suite:
+
+```bash
+pytest tests/ -v
+```
+
+Expected: all green. Fix any test that assumed the old transport-row placement.
+
+**Step 2:** Launch the app (use the `/run` skill or `./8cut.sh`), load a video,
+and verify by observation:
+- Audio tab present as 3rd deck tab; `QToolBox` opens on *Extract & Edit*.
+- Length + Format + edit controls present; transport row no longer shows them.
+- Teal timeline band still tracks cursor + length.
+- Extract with MP3 + fade-in produces an mp3 that fades in (spot-check with a
+  player); status line reports the saved length.
+- Waveform refresh draws bars; Play auditions; Scan/Classify pane still scans.
+
+**Step 3:** Update `README.md` + changelog: note the Audio tab replaces the Scan
+tab and adds format + fade/normalize/gain + audition. Mention Phase 2 (audio
+dataset) is planned.
+
+**Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: Audio workspace tab (Phase 1) — changelog + README"
+```
+
+---
+
+## Deferred to Phase 2 (separate plan)
+
+- Audio dataset pane (browser + label, add-from-extraction, in-tab Stats /
+  Hard-negatives / Train). **Blocked on the merged-vs-separate decision** in the
+  design doc (recommended: merged — write labeled `(source_video, start, end)`
+  time-ranges into the existing per-profile training DB).
+
+## Risks / watch-outs
+
+- **`loudnorm` is single-pass here** — fine for audition/dataset clips; if you
+  need broadcast-accurate normalization, that's a two-pass follow-up.
+- **Waveform/audition decode off the UI thread** — v1 gates waveform behind a
+  manual refresh and audition behind a temp render; do not decode long clips
+  synchronously on the UI thread.
+- **Deck pin persistence** — old `"scan"` pin key is silently dropped; verify the
+  side-by-side (pin two panels) still works with the Audio panel.
+- **`test_extract_uses_selected_format_and_edits`** monkeypatch details depend on
+  how `main` imports `build_audio_clip_command`/`QFileDialog`/`subprocess`;
+  adapt the patch targets to the actual module namespace.