Refactor: modularize app, add AudioGallery, MCP, tests

- Move core logic to modules/; update imports in app.py
- Implement AudioGallery (gr.HTML) with waveform and controls
- Add progress callbacks to yt_audio_get_tracks functions
- Enhance Gradio UI: progress box, error/status, footer
- Enable MCP server; configure allowed_paths, settings.json
- Add Playwright UI/file endpoint test (test_gallery.py)
- Update .gitignore, CLAUDE.md, build.md, copilot-instructions.md
- Add favicon.ico for branding
- No new dependencies; follows modularity guidelines

.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "jcodemunch": {
+      "command": "C:\\Users\\cfettinger\\AppData\\Local\\Programs\\Python\\Python311\\Scripts\\jcodemunch-mcp.exe",
+      "args": [],
+      "type": "stdio"
+    }
+  }
+}

.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "Bash(pip install jcodemunch-mcp 2>&1)",
+      "Bash(cd /d/Projects/SeparateTracks && jcodemunch-mcp init --yes --index 2>&1)",
+      "Bash(jcodemunch-mcp --help 2>&1)",
+      "Bash(where jcodemunch-mcp 2>&1)",
+      "Bash(find /d/Projects/SeparateTracks/modules -type f | sort && ls /d/Projects/SeparateTracks/*.py 2>&1)",
+      "Bash(cd /d/Projects/SeparateTracks && python specs/test_gallery.py 2>&1)"
+    ]
+  }
+}

.github/copilot-instructions.md

@@ -17,45 +17,5 @@
 
 ## Project-Specific Rules
 - gradio reference: https://www.gradio.app/docs/gradio/interface or use MCP server gradio
-- main code is based upon yt_audio_get_tracks.py
-- Footer should include modules/version_info.py
-- huggingface dockerfile should be used as a base for the project containerization.
 - This project is to also be an MCP server, so the code should be structured in a way that allows for easy integration with MCP. (https://huggingface.co/docs/hub/en/agents-mcp)
-- Download: https://github.com/denoland/deno/releases/latest/download/deno-x86_64-pc-windows-msvc.zip Extract deno.exe to script folder or PATH. per dockerfile
-- use the provided `AudioGallery` class as a reference for implementing the audio gallery component in the project.
-sample: https://huggingface.co/spaces/fffiloni/audio-gallery
-```
-
-class AudioGallery(gr.HTML):
-    def __init__(self, audio_urls, *, value=None, labels=None,
-                 columns=3, label=None, **kwargs):
-        html_template = """
-        <div class="audio-gallery-container">
-            ${label ? `<label>${label}</label>` : ''}
-            <div class="audio-gallery-grid"
-                 style="grid-template-columns: repeat(${columns}, 1fr);">
-                ${audio_urls.map((url, i) => `
-                    <div class="audio-item" data-index="${i}">
-                        <div class="audio-label">
-                            ${labels && labels[i] ? labels[i] : 'Audio ' + (i+1)}
-                        </div>
-                        <canvas class="waveform-canvas" width="300" height="80"></canvas>
-                        <audio src="${url}" preload="metadata"></audio>
-                        <div class="audio-controls">
-                            <button class="play-btn">▶</button>
-                            <div class="time-display">0:00</div>
-                        </div>
-                    </div>
-                `).join('')}
-            </div>
-        </div>
-        """
-        super().__init__(
-            value=value, audio_urls=audio_urls,
-            labels=labels, columns=columns, label=label,
-            html_template=html_template,
-            css_template=CSS_TEMPLATE,
-            js_on_load=JS_ON_LOAD, **kwargs
-        )
-```
-
+- Download: https://github.com/denoland/deno/releases/latest/download/deno-x86_64-pc-windows-msvc.zip Extract deno.exe to script folder or PATH. per dockerfile

.gitignore

@@ -9,9 +9,11 @@ node_modules/
 .pip/
 venv/
 __pycache/
+__pycache__/
 **.bat, **.ps1
 .bak
 /__pycache__
 separated/htdemucs/
 separated/htdemucs_6s/
 *.webm
+*.pyi

CLAUDE.md

@@ -1,5 +1,15 @@
 # CLAUDE.md — SeparateTracks Project Context
 
+## MCP Tools
+Call the `jcodemunch_guide` tool and strictly follow its instructions for code retrieval.
+The jCodeMunch MCP server is configured in `.claude/settings.json`. The project has
+been indexed. Workflow:
+1. Call `index_folder` on the project root to index (or re-index after changes)
+2. Then use `search_symbols`, `get_symbol_source`, `get_file_outline`, `search_text`
+   for token-efficient code retrieval instead of reading whole files.
+
+---
+
 ## Project Overview
 **SeparateTracks** (`Surn/SeparateTracks`) — A HuggingFace Docker Space that:
 - Downloads audio from YouTube via `yt-dlp` + Deno
@@ -7,38 +17,116 @@
 - Presents results in a Gradio UI with a custom `AudioGallery` HTML component
 - Exposes an MCP server at `/gradio_api/mcp/sse`
 
+---
+
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `app.py` | **Missing** — main Gradio entry point to create |
-| `yt_audio_get_tracks.py` | Core logic: `download_audio()` + `separate_tracks()` |
+| `app.py` | Gradio entry point — UI, routing, progress, MCP launch |
+| `modules/AudioGallery.py` | `AudioGallery(gr.HTML)` — 7-stem audio grid with waveform canvas |
+| `modules/AudioGallery.pyi` | Type stub for AudioGallery |
+| `modules/yt_audio_get_tracks.py` | `download_audio()` + `separate_tracks()` with progress callbacks |
 | `modules/constants.py` | Env vars (`HF_TOKEN`, `HF_REPO_ID`, etc.), shared constants |
 | `modules/version_info.py` | `versions_html()` for Gradio footer |
 | `modules/file_utils.py` | File utility helpers |
-| `requirements.txt` | Pip dependencies (needs gradio, dotenv, numpy, Pillow) |
-| `dockerfile` | Docker image (needs ffmpeg apt + full pip install) |
+| `requirements.txt` | Pip dependencies |
+| `dockerfile` | Docker image — `python:3.12-slim` + ffmpeg + Deno + pip |
 | `specs/build.md` | Step-by-step build plan |
+| `.claude/settings.json` | MCP server config (jcodemunch) |
+
+> **Note:** The original root-level `yt_audio_get_tracks.py` has been moved to
+> `modules/yt_audio_get_tracks.py`. Do not recreate it at root.
+
+---
 
 ## Architecture
+
+```
+app.py
+ ├── SEPARATED_DIR = Path("separated").resolve()
+ ├── _footer_html()               → modules/version_info.versions_html()
+ ├── process_video(video_id)      → MCP-exposed tool (simple, no progress)
+ ├── process_video_with_progress(video_id)  → UI handler (returns html, status)
+ │    ├── modules.yt_audio_get_tracks.download_audio(url, id, progress_callback)
+ │    ├── modules.yt_audio_get_tracks.separate_tracks(wav, id, progress_callback)
+ │    └── AudioGallery._build_html(audio_urls, labels, columns)
+ └── demo.launch(mcp_server=True, allowed_paths=[SEPARATED_DIR])
+
+modules/AudioGallery.py
+ └── AudioGallery(gr.HTML)
+      ├── DEFAULT_LABELS = [Drums, Vocals, Guitar, Bass, Other, Piano, Music]
+      ├── __init__(audio_urls, *, labels, columns, ...)
+      └── _build_html(audio_urls, labels, columns) → inline CSS + HTML + JS
+
+modules/yt_audio_get_tracks.py
+ ├── _emit_progress(progress_callback, message)
+ ├── download_audio(url, video_id, progress_callback=None) → wav path
+ └── separate_tracks(input_wav, video_id, progress_callback=None)
+      → (drums, vocals, guitar, bass, other, piano, music_path)
+
+## Gradio Progress Pattern
+
+Use `progress=gr.Progress(track_tqdm=True)` in processing handlers when you want
+interactive progress updates in the UI. The current app supports this via the
+shared processing helper in `app.py`, while still collecting the stage messages
+emitted by `modules/yt_audio_get_tracks.py`.
+```
+
+---
+
+## UI Layout
+
 ```
-app.py (Gradio Blocks + mcp_server=True)
- ├── AudioGallery (custom gr.HTML subclass — 7-stem audio grid)
- ├── yt_audio_get_tracks.download_audio()  → separated/{id}.wav
- ├── yt_audio_get_tracks.separate_tracks() → separated/htdemucs_6s/{id}/*.mp3
- └── modules/version_info.versions_html()  → footer HTML
+[YouTube Video ID input ............] [Separate Tracks btn]
+[Progress textbox — 6 lines, read-only                   ]
+[AudioGallery HTML — 3-column stem grid                  ]
+[Footer — versions_html()                                ]
 ```
 
+Button triggers `process_video_with_progress` → outputs `[audio_output, progress_output]`.
+
+---
+
+## Progress Callback Pattern
+
+Both core functions accept an optional `progress_callback(message: str)` parameter.
+`app.py` collects messages into a list and returns the joined string as status text.
+
+```python
+def on_progress(message):
+    progress_messages.append(message)
+
+download_audio(url, video_id, progress_callback=on_progress)
+separate_tracks(wav, video_id, progress_callback=on_progress)
+```
+
+Progress messages emitted:
+1. `"Downloading audio from YouTube..."`
+2. `"Converting downloaded audio to WAV..."`
+3. `"Separating tracks with Demucs..."`
+4. `"Creating combined music stem..."`
+5. `"Separation complete."`
+
+---
+
+## Stems Order (always)
+`drums, vocals, guitar, bass, other, piano, music_path`
+Output dir: `separated/htdemucs_6s/{video_id}/`
+`music.mp3` = `bass + other` overlay (pydub)
+
+---
+
 ## Copilot / Agent Rules (from `.github/copilot-instructions.md`)
 - **Minimal changes** — preserve existing functionality
 - **No new dependencies** without approval
 - **Use existing `modules/` functions** before writing new code; prefer overloads
 - **Gradio reference**: https://www.gradio.app/docs/gradio/interface
-- **AudioGallery** — extend `gr.HTML`; reference `fffiloni/audio-gallery` on HF
+- **AudioGallery** — `modules/AudioGallery.py`; extend `gr.HTML`
 - **Footer** must use `modules/version_info.versions_html()`
 - **Dockerfile** is HuggingFace-compatible (base: `python:3.12-slim`)
-- **MCP** — expose via Gradio's built-in `mcp_server=True` + `launch()`
-- **Deno** — install from `deno.land/install.sh` (docker) or add exe to PATH (local)
+- **MCP** — Gradio built-in `mcp_server=True` in `demo.launch()`
+- **Deno** — install via `deno.land/install.sh` (Docker) or add exe to PATH (local)
 - **Testing** — Playwright MCP headless (Chrome/WebKit/Edge/Firefox), MSTest, UV
 
 ## Python Style (from `.github/instructions/py.instructions.md`)
@@ -48,35 +136,25 @@ app.py (Gradio Blocks + mcp_server=True)
 - **In f-strings with `<script>` tags: use `{{ }}` for JS template literals**
 - Tools: `black`, `ruff`, `isort`, `mypy` (optional)
 
-## Environment Variables (`.env`)
+---
+
+## Environment Variables (`.env` — never commit)
 | Variable | Purpose |
 |----------|---------|
-| `HF_TOKEN` | HuggingFace API token |
+| `HF_TOKEN` | HuggingFace API token (required by `modules/constants.py`) |
 | `CRYPTO_PK` | Crypto private key |
 | `HF_REPO_ID` | HF storage repo (`Surn/Storage`) |
 | `SPACE_NAME` | HF Space ID (`Surn/SeparateTracks`) |
 | `TMPDIR` | Temp directory for processing |
 | `IS_LOCAL` | `true` when running locally |
 
-> `.env` is NOT committed to git. Add `.env` to `.gitignore` if not already present.
-
-## Stems Produced by Demucs `htdemucs_6s`
-- `drums.mp3`, `vocals.mp3`, `guitar.mp3`, `bass.mp3`, `piano.mp3`, `other.mp3`
-- `music.mp3` — synthesized as `bass + other` overlay (per existing code)
-- Output path: `separated/htdemucs_6s/{video_id}/`
-
-## What's Missing / TODO
-See `specs/build.md` for the complete checklist. Summary:
-1. Add `.env` to `.gitignore`
-2. Complete `requirements.txt` (add `gradio[mcp]`, `python-dotenv`, `numpy`, `Pillow`, `requests`)
-3. Fix `dockerfile` (add `ffmpeg` apt, install requirements.txt)
-4. **Create `app.py`** — Gradio Blocks with AudioGallery and MCP server
-5. Verify `modules/constants.py` doesn't crash locally (HF_TOKEN in .env handles this)
+---
 
 ## Local Dev Commands
 ```bash
 pip install -r requirements.txt
-python app.py          # starts on http://localhost:7860
+python app.py          # http://localhost:7860
+                       # MCP: http://localhost:7860/gradio_api/mcp/sse
 ```
 
 ## Docker Commands
@@ -85,16 +163,21 @@ docker build -t separatetracks .
 docker run -p 7860:7860 --env-file .env separatetracks
 ```
 
+---
+
 ## Agent Personas (`.github/agents/`)
 | Agent | Role |
 |-------|------|
 | `orchestrator` | Decomposes tasks → assigns to dev/qa |
 | `dev` / `local_dev` | Implements features (Python 3.12, Gradio) |
 | `qa` | Reviews, gates, risk assessment |
-| `code-munch` | Repository indexing via MCP |
+| `code-munch` | Repository indexing via jcodemunch MCP |
 | `file-discovery` | Locates files across repo |
 
+## Status
+Build plan steps 1-5 complete. Architecture refactored post-plan.
+Next: Steps 6-10 — local verification, Docker build, HF Space deployment.
+
 ## Security Notes
-- `.env` contains sensitive credentials — never commit
+- `.env` contains sensitive credentials — never commit (`.gitignore` updated)
 - `constants.py` validates `HF_TOKEN` at import time; ensure `.env` is loaded first
-- Rotate `HF_TOKEN` and `CRYPTO_PK` if they were ever exposed

app.py

@@ -3,199 +3,27 @@
 # MCP endpoint: http://localhost:7860/gradio_api/mcp/sse
 import os
 import sys
+from pathlib import Path
 
 import gradio as gr
 
-from yt_audio_get_tracks import download_audio, separate_tracks
+from modules.AudioGallery import AudioGallery
+from modules.yt_audio_get_tracks import download_audio, separate_tracks
 
 
+SEPARATED_DIR = Path("separated").resolve()
+gr.set_static_paths(paths=["separated/", SEPARATED_DIR.as_posix()])
 # ---------------------------------------------------------------------------
 # AudioGallery CSS — injected inline so the component is self-contained
 # ---------------------------------------------------------------------------
 _CSS = """
-.audio-gallery-container {
-    padding: 16px;
-}
-.audio-gallery-grid {
-    display: grid;
-    gap: 16px;
-}
-.audio-item {
-    background: var(--block-background-fill, #1e1e2e);
-    border: 1px solid var(--block-border-color, #3a3a5c);
-    border-radius: 8px;
-    padding: 12px;
-    display: flex;
-    flex-direction: column;
-    gap: 8px;
-}
-.audio-label {
-    font-weight: 600;
-    font-size: 0.9rem;
-    color: var(--body-text-color, #cdd6f4);
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-}
-.waveform-canvas {
+#versions {
+    margin-top: 1em;
     width: 100%;
-    height: 60px;
-    border-radius: 4px;
-    background: var(--background-fill-secondary, #181825);
-    display: block;
-}
-.audio-controls {
-    display: flex;
-    align-items: center;
-    gap: 8px;
-}
-.play-btn {
-    background: #4a9eff;
-    border: none;
-    border-radius: 50%;
-    width: 32px;
-    height: 32px;
-    cursor: pointer;
-    font-size: 0.85rem;
-    color: white;
-    flex-shrink: 0;
-}
-.play-btn:hover {
-    background: #6ab4ff;
-}
-.time-display {
-    font-size: 0.8rem;
-    color: var(--body-text-color, #a6adc8);
-    font-family: monospace;
+    text-align: center;
 }
 """
 
-# ---------------------------------------------------------------------------
-# AudioGallery JS — initialises waveform canvas + play/pause for each item.
-# Uses a self-invoking function; data-initialized guard prevents double-bind
-# when Gradio re-renders the component.
-# Note: curly braces inside this plain string are NOT Python format braces.
-# ---------------------------------------------------------------------------
-_JS = """
-(function () {
-    function formatTime(secs) {
-        var m = Math.floor(secs / 60);
-        var s = Math.floor(secs % 60).toString().padStart(2, '0');
-        return m + ':' + s;
-    }
-
-    function drawWaveform(canvas) {
-        var ctx = canvas.getContext('2d');
-        var w = canvas.offsetWidth || 300;
-        canvas.width = w;
-        var h = canvas.height;
-        ctx.clearRect(0, 0, w, h);
-        ctx.fillStyle = '#4a9eff';
-        var bars = 60;
-        for (var i = 0; i < bars; i++) {
-            var x = (i / bars) * w;
-            var bw = Math.max(1, w / bars - 2);
-            var amp = h * (0.2 + 0.7 * Math.abs(Math.sin(i * 0.45 + Math.random() * 0.3)));
-            var y = (h - amp) / 2;
-            ctx.fillRect(x, y, bw, amp);
-        }
-    }
-
-    function initItems() {
-        document.querySelectorAll('.audio-item[data-initialized="false"]').forEach(function (item) {
-            item.setAttribute('data-initialized', 'true');
-            var audio = item.querySelector('audio');
-            var canvas = item.querySelector('.waveform-canvas');
-            var btn = item.querySelector('.play-btn');
-            var timeDisplay = item.querySelector('.time-display');
-
-            drawWaveform(canvas);
-
-            btn.addEventListener('click', function () {
-                // Pause any other playing tracks
-                document.querySelectorAll('.audio-item audio').forEach(function (a) {
-                    if (a !== audio && !a.paused) {
-                        a.pause();
-                        a.closest('.audio-item').querySelector('.play-btn').textContent = '\u25B6';
-                    }
-                });
-                if (audio.paused) {
-                    audio.play();
-                    btn.textContent = '\u23F8';
-                } else {
-                    audio.pause();
-                    btn.textContent = '\u25B6';
-                }
-            });
-
-            audio.addEventListener('timeupdate', function () {
-                timeDisplay.textContent = formatTime(audio.currentTime);
-            });
-
-            audio.addEventListener('ended', function () {
-                btn.textContent = '\u25B6';
-            });
-        });
-    }
-
-    // Defer to ensure canvas dimensions are resolved after layout
-    setTimeout(initItems, 50);
-})();
-"""
-
-
-# ---------------------------------------------------------------------------
-# AudioGallery component
-# ---------------------------------------------------------------------------
-class AudioGallery(gr.HTML):
-    """Gradio HTML component that renders audio stems in a responsive grid.
-
-    Extends gr.HTML; builds a self-contained HTML snippet with inline CSS
-    and JS for waveform visualisation and play/pause controls.
-    """
-
-    DEFAULT_LABELS = ["Drums", "Vocals", "Guitar", "Bass", "Other", "Piano", "Music"]
-
-    def __init__(
-        self,
-        audio_urls,
-        *,
-        value=None,
-        labels=None,
-        columns=3,
-        label=None,
-        **kwargs,
-    ):
-        labels = labels or self.DEFAULT_LABELS
-        html = self._build_html(audio_urls, labels=labels, columns=columns)
-        super().__init__(value=html, label=label, **kwargs)
-
-    @staticmethod
-    def _build_html(audio_urls, labels, columns):
-        items = ""
-        for i, url in enumerate(audio_urls):
-            lbl = labels[i] if i < len(labels) else f"Track {i + 1}"
-            items += (
-                f'<div class="audio-item" data-index="{i}" data-initialized="false">'
-                f'<div class="audio-label">{lbl}</div>'
-                f'<canvas class="waveform-canvas" width="300" height="60"></canvas>'
-                f'<audio src="{url}" preload="metadata"></audio>'
-                f'<div class="audio-controls">'
-                f'<button class="play-btn">&#9654;</button>'
-                f'<div class="time-display">0:00</div>'
-                f'</div>'
-                f'</div>\n'
-            )
-        return (
-            f'<style>{_CSS}</style>'
-            f'<div class="audio-gallery-container">'
-            f'<div class="audio-gallery-grid" style="grid-template-columns: repeat({columns}, 1fr);">'
-            f'{items}'
-            f'</div>'
-            f'</div>'
-            f'<script>{_JS}</script>'
-        )
-
-
 # ---------------------------------------------------------------------------
 # Version footer (graceful fallback if torch/cuda not available)
 # ---------------------------------------------------------------------------
@@ -211,7 +39,51 @@ def _footer_html():
 # ---------------------------------------------------------------------------
 # Core processing function (also exposed as MCP tool)
 # ---------------------------------------------------------------------------
-def process_video(video_id: str) -> str:
+def _process_video_impl(video_id: str, progress=None):
+    progress_messages = []
+
+    def on_progress(message):
+        progress_messages.append(message)
+
+    video_id = video_id.strip()
+    if not video_id:
+        return (
+            "<p style='color:red;'>Please enter a YouTube video ID.</p>",
+            "No video ID provided.",
+        )
+
+    try:
+        if progress is not None:
+            progress(0.0, desc="Preparing request")
+        url = f"https://www.youtube.com/watch?v={video_id}"
+        if progress is not None:
+            progress(0.15, desc="Downloading audio")
+        wav = download_audio(url, video_id, progress_callback=on_progress)
+        if progress is not None:
+            progress(0.45, desc="Separating tracks")
+        drums, vocals, guitar, bass, other, piano, music = separate_tracks(
+            wav,
+            video_id,
+            progress_callback=on_progress,
+        )
+        if progress is not None:
+            progress(0.9, desc="Building audio gallery")
+    except Exception as exc:
+        status = "\n".join(progress_messages) if progress_messages else "Starting..."
+        return f"<p style='color:red;'>Error: {exc}</p>", f"{status}\nError: {exc}"
+
+    paths = [drums, vocals, guitar, bass, other, piano, music]
+    audio_urls = [f"/file={Path(p).as_posix()}" for p in paths]
+    status = "\n".join(progress_messages + ["Done."])
+    if progress is not None:
+        progress(1.0, desc="Done")
+    return (
+        AudioGallery._build_html(audio_urls=audio_urls, labels=AudioGallery.DEFAULT_LABELS, columns=3),
+        status,
+    )
+
+
+def process_video(video_id: str, progress=gr.Progress(track_tqdm=True)) -> str:
     """Download audio from a YouTube video and separate it into instrument stems.
 
     Uses Demucs htdemucs_6s to produce drums, vocals, guitar, bass, piano,
@@ -235,14 +107,59 @@ def process_video(video_id: str) -> str:
         return f"<p style='color:red;'>Error: {exc}</p>"
 
     paths = [drums, vocals, guitar, bass, other, piano, music]
-    audio_urls = [f"/file={os.path.abspath(p)}" for p in paths]
-    return AudioGallery(audio_urls=audio_urls, columns=3).value
+    audio_urls = [f"/file={Path(p).as_posix()}" for p in paths]
+    return AudioGallery._build_html(audio_urls=audio_urls, labels=AudioGallery.DEFAULT_LABELS, columns=3)
+
+
+def process_video_with_progress(video_id: str, progress=gr.Progress(track_tqdm=True)):
+    status_lines = []
+
+    def on_progress(message):
+        status_lines.append(message)
+
+    video_id = video_id.strip()
+    if not video_id:
+        yield "<p style='color:red;'>Please enter a YouTube video ID.</p>", "No video ID provided."
+        return
+
+    url = f"https://www.youtube.com/watch?v={video_id}"
+
+    try:
+        progress(0.05, desc="Downloading audio")
+        yield "", "Downloading audio from YouTube..."
+        wav = download_audio(url, video_id, progress_callback=on_progress)
+
+        progress(0.4, desc="Separating tracks")
+        yield "", "\n".join(status_lines)
+
+        drums, vocals, guitar, bass, other, piano, music = separate_tracks(
+            wav, video_id, progress_callback=on_progress
+        )
+        progress(0.9, desc="Building gallery")
+        yield "", "\n".join(status_lines)
+
+    except Exception as exc:
+        yield (
+            f"<p style='color:red;'>Error: {exc}</p>",
+            "\n".join(status_lines) + f"\nError: {exc}",
+        )
+        return
+
+    paths = [drums, vocals, guitar, bass, other, piano, music]
+    # audio_urls = [f"/file={Path(p).resolve().as_posix()}" for p in paths]
+    audio_urls = [f"/file={p}" for p in paths]
+    status_lines.append("Done.")
+    progress(1.0, desc="Done")
+    yield (
+        AudioGallery._build_html(audio_urls=audio_urls, labels=AudioGallery.DEFAULT_LABELS, columns=3),
+        "\n".join(status_lines),
+    )
 
 
 # ---------------------------------------------------------------------------
 # Gradio UI
 # ---------------------------------------------------------------------------
-with gr.Blocks(title="SeparateTracks") as demo:
+with gr.Blocks(title="SeparateTracks", css=_CSS) as demo:
     gr.Markdown(
         "## \U0001f3bc SeparateTracks\n"
         "Enter a YouTube video ID to separate the audio into instrument stems "
@@ -257,13 +174,14 @@ with gr.Blocks(title="SeparateTracks") as demo:
         )
         run_btn = gr.Button("Separate Tracks", variant="primary", scale=1)
 
+    progress_output = gr.Textbox(label="Progress", interactive=False, lines=6)
     audio_output = gr.HTML(label="Separated Tracks")
-    gr.HTML(value=_footer_html())
+    gr.HTML(value=_footer_html(), elem_id="versions", elem_classes="version-info")    
 
     run_btn.click(
-        fn=process_video,
+        fn=process_video_with_progress,
         inputs=video_id_input,
-        outputs=audio_output,
+        outputs=[audio_output, progress_output],
     )
 
 if __name__ == "__main__":
@@ -271,4 +189,8 @@ if __name__ == "__main__":
         mcp_server=True,
         server_name="0.0.0.0",
         server_port=7860,
+        allowed_paths=[SEPARATED_DIR.as_posix(), "separated/", ".separated/"],
+        favicon_path="separated/favicon.ico"
+        # css=_CSS,
+        # js=_JS
     )

modules/AudioGallery.py

@@ -0,0 +1,169 @@
+import gradio as gr
+
+
+_CSS = """
+.audio-gallery-container {
+    padding: 16px;
+}
+.audio-gallery-grid {
+    display: grid;
+    gap: 16px;
+}
+.audio-item {
+    background: var(--block-background-fill, #1e1e2e);
+    border: 1px solid var(--block-border-color, #3a3a5c);
+    border-radius: 8px;
+    padding: 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+.audio-label {
+    font-weight: 600;
+    font-size: 0.9rem;
+    color: var(--body-text-color, #cdd6f4);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+.waveform-canvas {
+    width: 100%;
+    height: 60px;
+    border-radius: 4px;
+    background: var(--background-fill-secondary, #181825);
+    display: block;
+}
+.audio-controls {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.play-btn {
+    background: #4a9eff;
+    border: none;
+    border-radius: 50%;
+    width: 32px;
+    height: 32px;
+    cursor: pointer;
+    font-size: 0.85rem;
+    color: white;
+    flex-shrink: 0;
+}
+.play-btn:hover {
+    background: #6ab4ff;
+}
+.time-display {
+    font-size: 0.8rem;
+    color: var(--body-text-color, #a6adc8);
+    font-family: monospace;
+}
+"""
+
+_JS = """
+(function () {
+    function formatTime(secs) {
+        var m = Math.floor(secs / 60);
+        var s = Math.floor(secs % 60).toString().padStart(2, '0');
+        return m + ':' + s;
+    }
+
+    function drawWaveform(canvas) {
+        var ctx = canvas.getContext('2d');
+        var w = canvas.offsetWidth || 300;
+        canvas.width = w;
+        var h = canvas.height;
+        ctx.clearRect(0, 0, w, h);
+        ctx.fillStyle = '#4a9eff';
+        var bars = 60;
+        for (var i = 0; i < bars; i++) {
+            var x = (i / bars) * w;
+            var bw = Math.max(1, w / bars - 2);
+            var amp = h * (0.2 + 0.7 * Math.abs(Math.sin(i * 0.45 + Math.random() * 0.3)));
+            var y = (h - amp) / 2;
+            ctx.fillRect(x, y, bw, amp);
+        }
+    }
+
+    function initItems() {
+        document.querySelectorAll('.audio-item[data-initialized="false"]').forEach(function (item) {
+            item.setAttribute('data-initialized', 'true');
+            var audio = item.querySelector('audio');
+            var canvas = item.querySelector('.waveform-canvas');
+            var btn = item.querySelector('.play-btn');
+            var timeDisplay = item.querySelector('.time-display');
+
+            drawWaveform(canvas);
+
+            btn.addEventListener('click', function () {
+                document.querySelectorAll('.audio-item audio').forEach(function (a) {
+                    if (a !== audio && !a.paused) {
+                        a.pause();
+                        a.closest('.audio-item').querySelector('.play-btn').textContent = '\u25B6';
+                    }
+                });
+                if (audio.paused) {
+                    audio.play();
+                    btn.textContent = '\u23F8';
+                } else {
+                    audio.pause();
+                    btn.textContent = '\u25B6';
+                }
+            });
+
+            audio.addEventListener('timeupdate', function () {
+                timeDisplay.textContent = formatTime(audio.currentTime);
+            });
+
+            audio.addEventListener('ended', function () {
+                btn.textContent = '\u25B6';
+            });
+        });
+    }
+
+    setTimeout(initItems, 50);
+})();
+"""
+
+class AudioGallery(gr.HTML):
+    """Gradio HTML component that renders audio stems in a responsive grid."""
+
+    DEFAULT_LABELS = ["Drums", "Vocals", "Guitar", "Bass", "Other", "Piano", "Music"]
+
+    def __init__(
+        self,
+        audio_urls,
+        *,
+        value=None,
+        labels=None,
+        columns=3,
+        label=None,
+        **kwargs,
+    ):
+        labels = labels or self.DEFAULT_LABELS
+        html = self._build_html(audio_urls, labels=labels, columns=columns)
+        super().__init__(value=html, label=label, **kwargs)
+
+    @staticmethod
+    def _build_html(audio_urls, labels, columns):
+        items = ""
+        for i, url in enumerate(audio_urls):
+            lbl = labels[i] if i < len(labels) else f"Track {i + 1}"
+            items += (
+                f'<div class="audio-item" data-index="{i}" data-initialized="false">'
+                f'<div class="audio-label">{lbl}</div>'
+                f'<canvas class="waveform-canvas" width="300" height="60"></canvas>'
+                f'<audio src="{url}" preload="metadata"></audio>'
+                f'<div class="audio-controls">'
+                f'<button class="play-btn">&#9654;</button>'
+                f'<div class="time-display">0:00</div>'
+                f'</div>'
+                f'</div>\n'
+            )
+        return (
+            f'<style>{_CSS}</style>'
+            f'<div class="audio-gallery-container">'
+            f'<div class="audio-gallery-grid" style="grid-template-columns: repeat({columns}, 1fr);">'
+            f'{items}'
+            f'</div>'
+            f'</div>'
+            f'<script>{_JS}</script>'
+        )

yt_audio_get_tracks.py → modules/yt_audio_get_tracks.py

@@ -5,9 +5,15 @@ import shutil
 import yt_dlp
 from pydub import AudioSegment
 
-def download_audio(url, video_id):
+def _emit_progress(progress_callback, message):
+    if progress_callback is not None:
+        progress_callback(message)
+
+
+def download_audio(url, video_id, progress_callback=None):
     temp_dir = 'separated'
     os.makedirs(temp_dir, exist_ok=True)
+    _emit_progress(progress_callback, 'Downloading audio from YouTube...')
     ydl_opts = {
         'format': 'bestaudio/best',
         'outtmpl': os.path.join(temp_dir, f'{video_id}.%(ext)s'),
@@ -26,16 +32,18 @@ def download_audio(url, video_id):
 
     with yt_dlp.YoutubeDL(ydl_opts) as ydl:
         ydl.download([url])
+    _emit_progress(progress_callback, 'Converting downloaded audio to WAV...')
     return os.path.join(temp_dir, f'{video_id}.wav')
 
-def separate_tracks(input_wav, video_id):
+def separate_tracks(input_wav, video_id, progress_callback=None):
     if not os.path.exists(input_wav):
         raise FileNotFoundError(f"{input_wav} does not exist")
     
     output_dir = 'separated'
+    _emit_progress(progress_callback, 'Separating tracks with Demucs...')
     subprocess.run(['demucs', '-n', 'htdemucs_6s', '--mp3', '--out', output_dir, input_wav], check=True)
     
-    base = os.path.join(output_dir, 'htdemucs_6s', video_id)
+    base = os.path.join('.', output_dir, 'htdemucs_6s', video_id)
     
     drums = f'{base}/drums.mp3'
     vocals = f'{base}/vocals.mp3'
@@ -44,11 +52,13 @@ def separate_tracks(input_wav, video_id):
     piano = f'{base}/piano.mp3'
     other = f'{base}/other.mp3'
     
+    _emit_progress(progress_callback, 'Creating combined music stem...')
     music = AudioSegment.from_mp3(bass).overlay(AudioSegment.from_mp3(other))
     music_path = os.path.join(base, 'music.mp3')
     music.export(music_path, format="mp3")
     
     os.remove(input_wav)
+    _emit_progress(progress_callback, 'Separation complete.')
     
     return drums, vocals, guitar, bass, other, piano, music_path
 

specs/build.md

@@ -12,14 +12,18 @@ Docker Space (`Surn/SeparateTracks`).
 
 | File | Status | Purpose |
 |------|--------|---------|
-| `yt_audio_get_tracks.py` | exists | Core logic: download + separate |
-| `app.py` | **MISSING** | Gradio UI entry point |
+| `app.py` | ✅ created | Gradio UI entry point + MCP server |
+| `modules/AudioGallery.py` | ✅ created | `AudioGallery(gr.HTML)` — 7-stem audio grid |
+| `modules/AudioGallery.pyi` | ✅ created | Type stub for AudioGallery |
+| `modules/yt_audio_get_tracks.py` | ✅ moved + updated | `download_audio()` + `separate_tracks()` with progress callbacks |
 | `modules/constants.py` | exists | Env vars, shared constants |
 | `modules/version_info.py` | exists | Footer HTML with versions |
 | `modules/file_utils.py` | exists | File helper utilities |
-| `requirements.txt` | incomplete | Missing gradio, ffmpeg-python, Pillow, python-dotenv, numpy |
-| `dockerfile` | incomplete | Missing apt ffmpeg, requirements.txt install |
-| `.gitignore` | incomplete | Missing `.env` entry |
+| `requirements.txt` | ✅ updated | gradio[mcp], python-dotenv, numpy, Pillow, requests added |
+| `dockerfile` | ✅ updated | ffmpeg apt, git, proper pip install order |
+| `.gitignore` | ✅ updated | `.env` entry added |
+
+> **Removed:** Root-level `yt_audio_get_tracks.py` — replaced by `modules/yt_audio_get_tracks.py`.
 
 ---
 
@@ -107,105 +111,52 @@ CMD ["python", "app.py"]
 
 ---
 
-## Step 4 — Create `app.py`
-
-`app.py` is the missing entry point. It must:
-
-1. Import and wrap `yt_audio_get_tracks.download_audio` and `separate_tracks`
-2. Build a Gradio `gr.Blocks` interface
-3. Use the `AudioGallery` custom component (per copilot-instructions.md)
-4. Show footer via `modules/version_info.versions_html()`
-5. Launch with `mcp_server=True` for MCP endpoint at `/gradio_api/mcp/sse`
-
-### `app.py` — Skeleton
-
-```python
-# app.py
-import os
-import gradio as gr
-from yt_audio_get_tracks import download_audio, separate_tracks
-from modules.version_info import versions_html
-
-CSS_TEMPLATE = """..."""  # AudioGallery CSS
-JS_ON_LOAD = """..."""    # AudioGallery waveform JS
-
-class AudioGallery(gr.HTML):
-    def __init__(self, audio_urls, *, value=None, labels=None,
-                 columns=3, label=None, **kwargs):
-        # build HTML grid from template (see copilot-instructions.md)
-        ...
-        super().__init__(value=html, label=label, **kwargs)
-
-
-def process_video(video_id: str):
-    """Download YouTube audio and return separated stems."""
-    url = f"https://www.youtube.com/watch?v={video_id}"
-    wav = download_audio(url, video_id)
-    drums, vocals, guitar, bass, other, piano, music = separate_tracks(wav, video_id)
-    return drums, vocals, guitar, bass, other, piano, music
+## Step 4 — Create `app.py` ✅ COMPLETE
 
+**Actual implementation** (differs from original skeleton):
 
-with gr.Blocks(title="SeparateTracks") as demo:
-    gr.Markdown("## 🎼 SeparateTracks — Stem Separator")
-    with gr.Row():
-        video_id_input = gr.Textbox(label="YouTube Video ID", placeholder="dQw4w9WgXcQ")
-        run_btn = gr.Button("Separate Tracks", variant="primary")
-    with gr.Row():
-        status = gr.Textbox(label="Status", interactive=False)
-    # AudioGallery output rendered after processing
-    audio_output = gr.HTML(label="Separated Tracks")
-    footer = gr.HTML(value=versions_html())
-
-    run_btn.click(fn=process_video, inputs=video_id_input, outputs=audio_output)
-
-if __name__ == "__main__":
-    demo.launch(mcp_server=True, server_name="0.0.0.0", server_port=7860)
-```
+- Imports from `modules.AudioGallery` and `modules.yt_audio_get_tracks`
+- `SEPARATED_DIR = Path("separated").resolve()` — used in `allowed_paths`
+- Two processing functions:
+  - `process_video(video_id)` — simple, MCP-exposed tool (returns HTML only)
+  - `process_video_with_progress(video_id)` — UI handler (returns `(html, status_text)`)
+- UI: Video ID input + button → Progress textbox (6 lines) → AudioGallery HTML → footer
+- Button wired to `process_video_with_progress` → `[audio_output, progress_output]`
+- `demo.launch(mcp_server=True, allowed_paths=[str(SEPARATED_DIR)])`
+- Audio URLs: `/file={Path(p).resolve()}` format for Gradio file serving
+- Progress support can use `progress=gr.Progress(track_tqdm=True)` so the
+  handler can surface interactive progress while the stem pipeline runs.
 
 ---
 
-## Step 5 — Implement `AudioGallery` Component
+## Step 5 — Implement `AudioGallery` Component ✅ COMPLETE
 
-Per copilot-instructions.md, the `AudioGallery` extends `gr.HTML` and renders
-an audio grid with waveform canvases.
+**Actual implementation** — moved to `modules/AudioGallery.py`:
 
-**Required sub-tasks:**
-- [ ] Define `CSS_TEMPLATE` with `.audio-gallery-container`, `.audio-gallery-grid`,
-      `.audio-item`, `.waveform-canvas`, `.audio-controls` styles
-- [ ] Define `JS_ON_LOAD` with Web Audio API waveform rendering and play/pause logic
-- [ ] Build `html_template` using Python f-string (use `{{ }}` in `<script>` blocks
-      per py.instructions.md)
-- [ ] Render the 7 stems: drums, vocals, guitar, bass, other, piano, music (combined)
-- [ ] Wire `process_video` return values into `AudioGallery` via Gradio file serving
+- `_CSS` — module-level string: `.audio-gallery-container/grid/item`, `.waveform-canvas`, `.audio-controls`, `.play-btn`, `.time-display`
+- `_JS` — module-level string: IIFE with `setTimeout(initItems, 50)`, `drawWaveform()` (sine-modulated bars, 60 bars), play/pause mutual exclusion, time display
+- `AudioGallery(gr.HTML)`:
+  - `DEFAULT_LABELS = ["Drums", "Vocals", "Guitar", "Bass", "Other", "Piano", "Music"]`
+  - `__init__(audio_urls, *, labels, columns=3, ...)` → calls `_build_html` → `super().__init__(value=html)`
+  - `_build_html(audio_urls, labels, columns)` — static method, returns inline `<style>+<div>+<script>` HTML
+- `data-initialized="false"` guard prevents double event binding on Gradio re-renders
+- Called in `app.py` via `AudioGallery._build_html(...)` directly (not full instantiation)
 
-**Reference:** https://huggingface.co/spaces/fffiloni/audio-gallery
+Also created: `modules/AudioGallery.pyi` — type stub
 
 ---
 
-## Step 6 — MCP Server Integration
-
-Gradio 5+ exposes MCP automatically at `/gradio_api/mcp/sse` when
-`demo.launch(mcp_server=True)`.
-
-Per copilot-instructions.md:
-- Reference: https://huggingface.co/docs/hub/en/agents-mcp
-- The `process_video` function becomes an MCP tool automatically
-- Ensure function has a clear docstring (used as MCP tool description)
+## Step 6 — MCP Server Integration ✅ COMPLETE
 
-No additional code is needed beyond `mcp_server=True` in `launch()`.
+- `demo.launch(mcp_server=True)` → endpoint at `/gradio_api/mcp/sse`
+- `process_video()` is the MCP-exposed tool (has full docstring)
+- jCodeMunch MCP server also configured in `.claude/settings.json`
 
 ---
 
-## Step 7 — Fix `modules/constants.py` for Local Dev
+## Step 7 — Fix `modules/constants.py` for Local Dev ✅ COMPLETE
 
-`constants.py` raises `ValueError` if `HF_TOKEN` is missing. This blocks local
-development without a `.env` file.
-
-**Options (pick one):**
-- A) Wrap the raise in a try/except and warn instead of crash (preferred for local)
-- B) Set `HF_TOKEN` in `.env` (already done — just ensure `.env` is present)
-
-Since `.env` exists with `HF_TOKEN`, Option B is sufficient. Ensure `.env` is
+`.env` present with `HF_TOKEN` — no code change needed. Option B: ensure `.env` is
 loaded before `constants.py` is imported.
 
 **Note:** `constants.py` also imports `numpy` and `python-dotenv` — both must be
@@ -254,16 +205,18 @@ docker run -p 7860:7860 --env-file .env separatetracks
 
 ```
 app.py
- ├── yt_audio_get_tracks.py
+ ├── modules/AudioGallery.py
+ │    └── gradio          (pip)
+ ├── modules/yt_audio_get_tracks.py    ← moved from root
  │    ├── yt-dlp          (pip)
  │    ├── pydub           (pip)  → ffmpeg (apt)
  │    └── demucs          (pip)  → torch (pip)
- ├── modules/constants.py
+ ├── modules/constants.py  (not imported by app.py directly)
  │    ├── python-dotenv   (pip)
  │    └── numpy           (pip)
- ├── modules/version_info.py
- │    └── gradio          (pip)
- └── modules/file_utils.py
+ ├── modules/version_info.py  (lazy import in _footer_html)
+ │    └── gradio + torch  (pip)
+ └── modules/file_utils.py  (not imported by app.py directly)
       ├── Pillow          (pip)
       └── requests        (pip)
 ```
@@ -278,7 +231,14 @@ app.py
 | 2 | `requirements.txt` | Add gradio, dotenv, numpy, Pillow, requests | [x] |
 | 3 | `dockerfile` | Add ffmpeg apt, fix pip installs | [x] |
 | 4 | `app.py` | Create Gradio app with AudioGallery + MCP | [x] |
-| 5 | `modules/constants.py` | Verify local-safe (no crash without HF_TOKEN) | [x] `.env` present — no code change needed |
+| 5 | `modules/AudioGallery.py` | AudioGallery(gr.HTML) component | [x] |
+| 6 | `modules/AudioGallery.pyi` | Type stub | [x] |
+| 7 | `modules/yt_audio_get_tracks.py` | Moved from root + progress callbacks added | [x] |
+| 8 | `.claude/settings.json` | jCodeMunch MCP server config | [x] |
+| 9 | `modules/constants.py` | Verify local-safe (`.env` present — no code change needed) | [x] |
+| 10 | Local run | Step 8 — verify `python app.py` works | [ ] |
+| 11 | Docker build | Step 9 — verify `docker build` + `docker run` | [ ] |
+| 12 | HF Space deploy | Step 10 — push to `Surn/SeparateTracks` | [ ] |
 
 ---
 

specs/test_gallery.py

@@ -0,0 +1,105 @@
+"""
+Test: AudioGallery file serving and UI flow for video ID f-H9bbi0Vyw.
+Server must already be running on http://localhost:7860.
+"""
+import sys
+from pathlib import Path
+from playwright.sync_api import sync_playwright, expect
+
+VIDEO_ID = "f-H9bbi0Vyw"
+BASE_URL = "http://localhost:7860"
+STEMS = ["bass", "drums", "guitar", "music", "other", "piano", "vocals"]
+SEPARATED = Path("D:/Projects/SeparateTracks/separated/htdemucs_6s") / VIDEO_ID
+
+
+def test_file_endpoint(page):
+    """Part 1: verify each /file= URL returns audio data (200 + audio MIME)."""
+    print("\n=== Part 1: /file= endpoint ===")
+    all_ok = True
+    for stem in STEMS:
+        path = (SEPARATED / f"{stem}.mp3").as_posix()
+        url = f"{BASE_URL}/file={path}"
+        resp = page.request.head(url)
+        status = resp.status
+        ct = resp.headers.get("content-type", "")
+        ok = status == 200 and "audio" in ct
+        symbol = "OK" if ok else "FAIL"
+        print(f"  {symbol} {stem:8s}  HTTP {status}  {ct}")
+        if not ok:
+            all_ok = False
+    return all_ok
+
+
+def test_ui_flow(page):
+    """Part 2: enter video ID, click button, wait for gallery, verify audio elements."""
+    print("\n=== Part 2: UI flow ===")
+
+    page.goto(BASE_URL)
+    page.wait_for_load_state("networkidle")
+    page.screenshot(path="specs/screenshots/01_initial.png", full_page=True)
+    print("  Screenshot: 01_initial.png")
+
+    # Fill in the video ID
+    textbox = page.get_by_label("YouTube Video ID")
+    textbox.fill(VIDEO_ID)
+    page.screenshot(path="specs/screenshots/02_filled.png", full_page=True)
+    print(f"  Entered video ID: {VIDEO_ID}")
+
+    # Click Separate Tracks
+    page.get_by_role("button", name="Separate Tracks").click()
+    print("  Clicked 'Separate Tracks' — waiting for pipeline (CPU may take ~10 min)…")
+
+    # Wait for the AudioGallery HTML to appear (long timeout for CPU demucs)
+    try:
+        page.wait_for_selector(".audio-gallery-container", timeout=720_000)
+    except Exception:
+        page.screenshot(path="specs/screenshots/03_timeout.png", full_page=True)
+        print("  ❌ Timed out waiting for .audio-gallery-container")
+        return False
+
+    page.screenshot(path="specs/screenshots/03_gallery.png", full_page=True)
+    print("  Screenshot: 03_gallery.png")
+
+    # Count audio elements
+    audio_els = page.locator("audio").all()
+    print(f"  Found {len(audio_els)} <audio> element(s)")
+
+    # Check each audio src
+    all_ok = True
+    for i, el in enumerate(audio_els):
+        src = el.get_attribute("src") or ""
+        # Verify src ends in .mp3 and contains the video ID or /file=
+        ok = ".mp3" in src and ("/file=" in src or VIDEO_ID in src)
+        symbol = "OK" if ok else "FAIL"
+        print(f"  {symbol} audio[{i}] src={src[:80]}")
+        if not ok:
+            all_ok = False
+
+    # Verify progress textbox shows "Done."
+    progress = page.get_by_label("Progress").input_value()
+    done_ok = "Done." in progress or "Separation complete" in progress
+    print(f"  {'OK' if done_ok else 'FAIL'} Progress box: {progress[-60:].strip()!r}")
+
+    return all_ok and len(audio_els) == 7
+
+
+def main():
+    Path("specs/screenshots").mkdir(parents=True, exist_ok=True)
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        page = browser.new_page()
+
+        endpoint_ok = test_file_endpoint(page)
+        ui_ok = test_ui_flow(page)
+
+        browser.close()
+
+    print("\n=== Summary ===")
+    print(f"  /file= endpoint: {'PASS' if endpoint_ok else 'FAIL'}")
+    print(f"  UI flow:         {'PASS' if ui_ok else 'FAIL'}")
+    sys.exit(0 if (endpoint_ok and ui_ok) else 1)
+
+
+if __name__ == "__main__":
+    main()