# Audio Merge (Crossfade) — Phase 2 Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** A "Merge" pane in the Audio tab that assembles an ordered list of audio clips into one output with a crossfade at every join, rendered via ffmpeg `acrossfade`. Clips come from the current extract selection (with its edits) or from files on disk.

**Architecture:** A pure `core/ffmpeg.build_crossfade_merge_command` (TDD) + a third `QToolBox` page in `_build_audio_tab`. Reuses Phase-1 pieces: `build_audio_clip_command`, `_current_edit_filters`, `probe_duration`, and the ffplay audition machinery (`_audition_proc`/`_stop_audition`/`_teardown_audition`).

**Tech Stack:** Python 3, PyQt6, ffmpeg (`acrossfade`/`concat` filters), pytest.

**Design doc:** `docs/plans/2026-07-02-audio-merge-design.md`

---

## Conventions
- Branch `audio-tab` (continues Phase 1). New commit per task; don't amend across tasks.
- UI tests: `LD_PRELOAD=/usr/lib/libstdc++.so.6 QT_QPA_PLATFORM=offscreen python -m pytest tests/test_ui_structure.py -v`. Run `test_ui_structure.py` and `test_utils.py` in SEPARATE processes (known segfault when combined). Pre-existing red in `test_utils.py`: `test_audio_extract_timing`, `test_ffmpeg_command_no_resize`, `test_db_get_markers_returns_sorted` — untouched by this work.

---

## Task M1: `build_crossfade_merge_command` (pure, TDD)

**Files:** Modify `core/ffmpeg.py`; test `tests/test_utils.py`.

**Step 1 — failing tests:**
```python
def test_merge_single_clip_reencodes():
    cmd = build_crossfade_merge_command(["/a.wav"], 0.5, "/o/out.mp3")
    assert cmd[0] == "ffmpeg"
    assert cmd.count("-i") == 1
    assert "libmp3lame" in cmd            # codec by out ext
    assert "acrossfade" not in " ".join(cmd)
    assert cmd[-1] == "/o/out.mp3"

def test_merge_two_clips_acrossfade():
    cmd = build_crossfade_merge_command(["/a.wav", "/b.wav"], 0.5, "/o/out.wav")
    assert cmd.count("-i") == 2
    fc = cmd[cmd.index("-filter_complex") + 1]
    assert "[0][1]acrossfade=d=0.5" in fc
    assert "[out]" in fc
    assert cmd[cmd.index("-map") + 1] == "[out]"

def test_merge_three_clips_chains():
    cmd = build_crossfade_merge_command(["/a.wav", "/b.wav", "/c.wav"], 1.0, "/o/o.wav")
    fc = cmd[cmd.index("-filter_complex") + 1]
    assert fc.count("acrossfade=d=1.0") == 2      # two joins
    assert cmd[cmd.index("-map") + 1] == "[out]"

def test_merge_zero_crossfade_uses_concat():
    cmd = build_crossfade_merge_command(["/a.wav", "/b.wav"], 0.0, "/o/o.wav")
    fc = cmd[cmd.index("-filter_complex") + 1]
    assert "concat=n=2:v=0:a=1" in fc
    assert "acrossfade" not in fc

def test_merge_empty_raises():
    import pytest
    with pytest.raises(ValueError):
        build_crossfade_merge_command([], 0.5, "/o/o.wav")
```

**Step 2** — run `...pytest tests/test_utils.py -k merge -v` → FAIL.

**Step 3 — implement** in `core/ffmpeg.py` (near `build_audio_clip_command`):
```python
def build_crossfade_merge_command(clips: list[str], crossfade: float,
                                  out_path: str) -> list[str]:
    """ffmpeg command that concatenates *clips* in order into *out_path*,
    crossfading each join by *crossfade* seconds (0 = butt-join). Re-encoded
    per the output extension."""
    if not clips:
        raise ValueError("no clips to merge")
    ext = os.path.splitext(out_path)[1].lower()
    codec = _AUDIO_CODEC_BY_EXT.get(ext, [])
    cmd = [_bin("ffmpeg"), "-y"]
    for c in clips:
        cmd += ["-i", c]
    if len(clips) == 1:
        return cmd + ["-vn", *codec, out_path]
    if crossfade > 0:
        # Chain acrossfade: [0][1]->[a1]; [a1][2]->[a2]; … last label = [out].
        parts, prev = [], "0"
        for i in range(1, len(clips)):
            label = "out" if i == len(clips) - 1 else f"a{i}"
            parts.append(f"[{prev}][{i}]acrossfade=d={crossfade}[{label}]")
            prev = label
        fc = ";".join(parts)
    else:
        inputs = "".join(f"[{i}]" for i in range(len(clips)))
        fc = f"{inputs}concat=n={len(clips)}:v=0:a=1[out]"
    return cmd + ["-filter_complex", fc, "-map", "[out]", *codec, out_path]
```
Confirm `_bin` import in ffmpeg.py (it uses `_bin` already).

**Step 4** — `...pytest tests/test_utils.py -k "merge or audio_clip" -v` → PASS (5 new + existing audio-clip tests).

**Step 5 — commit:** `git add core/ffmpeg.py tests/test_utils.py && git commit -m "feat: build_crossfade_merge_command — chained acrossfade / concat"`

---

## Task M2: Merge pane widgets + 3rd QToolBox page

**Files:** Modify `main.py`; test `tests/test_ui_structure.py`.

**Step 1 — failing test:**
```python
def test_merge_pane_present(win):
    from PyQt6.QtWidgets import QToolBox, QListWidget, QDoubleSpinBox
    tb = win._tab_audio.findChild(QToolBox)
    titles = [tb.itemText(i) for i in range(tb.count())]
    assert "Merge" in titles
    assert isinstance(win._merge_list, QListWidget)
    assert isinstance(win._spn_crossfade, QDoubleSpinBox)
    assert win._spn_crossfade.value() == 0.5
```

**Step 2** — run → FAIL.

**Step 3 — implement:**
- In `__init__` (after the audio-edit widget block), construct: `self._merge_list = QListWidget()` (set `setSelectionMode(SingleSelection)`); `self._spn_crossfade = QDoubleSpinBox()` (range 0.0–10.0, decimals 2, step 0.1, suffix " s", value from QSettings `audio_crossfade` default 0.5, persist on change); the buttons `self._btn_merge_add_sel` ("＋ Selection"), `self._btn_merge_add_file` ("＋ File…"), `self._btn_merge_up` ("▲"), `self._btn_merge_down` ("▼"), `self._btn_merge_remove` ("✕"), `self._btn_merge_preview` ("▶ Preview"), `self._btn_merge_save` ("Merge & Save…"). Wire each `clicked` to its handler (defined in M3/M4; add stub methods now that `pass` — or define fully in later tasks and reference them). To keep TDD green, define minimal stub handlers now.
- In `_build_audio_tab`, add a third page: a `QWidget` with a `QVBoxLayout` holding the list, a crossfade row (`QLabel("Crossfade:")` + `_spn_crossfade`), a button grid (add/remove/reorder), and a bottom row (Preview, Merge & Save). `tb.addItem(merge_page, "Merge")`.

**Step 4** — run full `tests/test_ui_structure.py` → new test passes, prior 27 still pass.

**Step 5 — commit:** `feat: Merge pane (3rd Audio QToolBox page) — list + crossfade + buttons`

---

## Task M3: Add-to-sequence + reorder/remove

**Files:** `main.py`; test `tests/test_ui_structure.py`.

**Step 1 — failing test** (drives the list ops without file dialogs):
```python
def test_merge_list_add_remove_reorder(win, tmp_path):
    from PyQt6.QtCore import Qt
    a = tmp_path / "a.wav"; b = tmp_path / "b.wav"
    a.write_bytes(b""); b.write_bytes(b"")
    win._merge_add_paths([str(a), str(b)])
    assert win._merge_list.count() == 2
    assert win._merge_list.item(0).data(Qt.ItemDataRole.UserRole) == str(a)
    win._merge_list.setCurrentRow(1)
    win._merge_move(-1)                       # move b up
    assert win._merge_list.item(0).data(Qt.ItemDataRole.UserRole) == str(b)
    win._merge_list.setCurrentRow(0)
    win._merge_remove_selected()
    assert win._merge_list.count() == 1
```

**Step 2** — run → FAIL.

**Step 3 — implement** on MainWindow:
- `_merge_add_paths(paths)` — for each path append a `QListWidgetItem` with text `basename  (Ds)` (duration via `probe_duration`, blank if None) and `setData(UserRole, abspath)`.
- `_on_merge_add_file` — `QFileDialog.getOpenFileNames` (audio filter, remembered dir) → `_merge_add_paths`.
- `_on_merge_add_selection` — guard `_file_path`; render `[_cursor, _cursor+len]` with `_current_edit_filters()` to a unique temp wav (track it for cleanup) via `build_audio_clip_command` + `subprocess.run` under wait cursor; on success `_merge_add_paths([tmp])`; else status.
- `_merge_move(delta)` and `_merge_remove_selected()` — standard list row moves/removal.
- Replace the M2 stubs for add/file/selection/up/down/remove with these (up=`_merge_move(-1)`, down=`_merge_move(1)`).

**Step 4** — run full UI file → new test + prior pass.

**Step 5 — commit:** `feat: Merge sequence — add (file/selection), reorder, remove`

---

## Task M4: Merge & Save + Preview

**Files:** `main.py`; test `tests/test_ui_structure.py`.

**Step 1 — failing test** (patches the builder to capture args; sentinel-raises to avoid running ffmpeg):
```python
def test_merge_save_builds_command(win, tmp_path, monkeypatch):
    import main as m, pytest
    from PyQt6.QtCore import Qt
    a = tmp_path / "a.wav"; b = tmp_path / "b.wav"; a.write_bytes(b""); b.write_bytes(b"")
    win._merge_add_paths([str(a), str(b)])
    win._spn_crossfade.setValue(0.75)
    seen = {}
    class _Stop(Exception): pass
    def fake(clips, xf, out):
        seen["clips"] = clips; seen["xf"] = xf; seen["out"] = out
        raise _Stop
    monkeypatch.setattr(m, "build_crossfade_merge_command", fake)
    monkeypatch.setattr(m.QFileDialog, "getSaveFileName",
                        staticmethod(lambda *a, **k: (str(tmp_path / "m.wav"), "")))
    with pytest.raises(_Stop):
        win._on_merge_save()
    assert seen["clips"] == [str(a), str(b)]
    assert seen["xf"] == 0.75
    assert seen["out"].endswith(".wav")

def test_merge_save_empty_is_noop(win):
    win._merge_list.clear()
    win._on_merge_save()          # must not raise / not open a dialog
```

**Step 2** — run → FAIL.

**Step 3 — implement:**
- `_merge_paths()` helper → list of UserRole paths in order.
- `import build_crossfade_merge_command` at the top with the other ffmpeg imports.
- `_on_merge_save` — if `_merge_paths()` empty → status + return; save dialog (reuse the extract save-filter builder / remembered dir); `cmd = build_crossfade_merge_command(paths, self._spn_crossfade.value(), out)`; run under wait cursor + status; on success report `probe_duration`, mirror extract's success/error handling.
- `_play_file(path)` — extract the ffplay-start logic from `_on_audio_audition` into this shared helper (render→play stays in audition; `_play_file` just starts `QProcess(ffplay)` on an existing file and reuses `_stop_audition`/teardown). Have `_on_audio_audition` call `_play_file(tmp)` after its render.
- `_on_merge_preview` — build to a unique temp wav, run, then `_play_file(tmp)`; guard empty list.

**Step 4** — run full UI file → new tests + prior pass; also re-run the audition test to confirm the `_play_file` refactor didn't break it.

**Step 5 — commit:** `feat: merge save + preview (crossfade render, ffplay preview)`

---

## Task M5: Temp cleanup, verify, docs

**Files:** `main.py`, `README.md`; verify.

- **Temp cleanup:** track rendered temp clips/preview outputs in a `self._merge_temps: set[str]`; best-effort `os.remove` them in `closeEvent` (add next to the audition teardown). Add `_stop_audition()` to `closeEvent` too (Phase-1 code-review follow-up).
- **Docs:** bump `APP_VERSION` "1.3"→"1.4"; add a `("1.4", [...])` changelog entry describing the Merge pane (assemble clips, crossfade at joins, add from selection/file, preview, save). README: add a bullet group under "Audio extraction & editing" for **Merge / crossfade**.
- **Verify:** run `tests/test_utils.py`, `tests/test_ui_structure.py`, `tests/test_audio_scan.py`, `tests/test_db.py` each in its own process; report counts; confirm the only failures are the 3 known pre-existing ones. `python -c "import main; print('OK')"` smoke.
- **Commit:** `docs: Merge pane (Phase 2) — v1.4 changelog + README + temp cleanup`

---

## Deferred (Phase 2-later / "fancier stuff")
- Interactive waveform drag-select (in/out handles, zoom, moving playhead) to define each added clip precisely.
- Per-join crossfade durations + curve selection (`c1=/c2=`), per-clip gain, drag-to-reorder.
- Saved/reloadable merge projects.