Initial Project Setup

.github/agents/code-munch.agent.md

@@ -0,0 +1,59 @@
+---
+name: code_munch
+description: "Minimal agent to invoke the MCP `code_munch` indexer for repository indexing."
+model: qwen3.6:35b-a3b (ollama)
+---
+
+# Minimal Code Munch Agent
+
+This file contains a minimal usage note for invoking the MCP `code_munch` indexer to create a JSON index of this repository.
+
+## Prerequisite — ensure code_munch is installed and running
+
+- Verify the `jcodemunch-mcp` executable is available and runnable:
+
+```
+# Unix / WSL / Git Bash:
+command -v jcodemunch-mcp && jcodemunch-mcp --version
+
+# Windows (PowerShell):
+Get-Command jcodemunch-mcp
+
+# Simple run test:
+jcodemunch-mcp --help
+```
+
+- If the executable is missing, install per upstream instructions (example):
+
+```
+pip install jcodemunch-mcp
+```
+
+- Start the server locally before calling the MCP client, or ensure the MCP host listed in `.continue/mcpServers/code-munch.yaml` can reach it.
+
+- Check the local MCP client config for JSON errors that can prevent startup:
+
+```
+# Windows (PowerShell) — validate the MCP client config JSON
+python -c "import json,sys;json.load(open(r'C:\Users\CharlesFettinger\AppData\Roaming\Code\User\.mcp.json'));print('OK')"
+
+# Or use a JSON linter/editor to open `C:\Users\CharlesFettinger\AppData\Roaming\Code\User\.mcp.json`
+```
+
+If this check raises an exception, fix the JSON (missing commas, trailing commas, or invalid values) before starting the MCP server.
+
+## Usage
+
+Use the `mcp_code_munch_index_folder` tool directly to index a repository. No `mcp call` CLI is required.
+
+```
+mcp_code_munch_index_folder(path: "g:\\Projects\\Wrdler")
+```
+
+- MCP server configuration: `.continue/mcpServers/code-munch.yaml`.
+- Output index fields: `relative_path`, `language`, `size_bytes`, `line_count`, `sha256`, `imports`, `top_level_defs`, `summary`.
+
+## Important Agent Instruction
+
+- Do NOT create a plan that instructs other agents or tools to call the MCP `code_munch` server. When invoking `code_munch`, use the `mcp_code_munch_index_folder` tool directly instead of generating a separate "plan" step or using the `mcp call` CLI. This avoids accidental plan-driven remote executions or duplicated orchestration steps.
+

.github/agents/dev.agent.md

@@ -0,0 +1,72 @@
+---
+name: dev
+description: "Use when: implementing features, fixing bugs, refactoring code, or executing development tasks for the ai-video-orchestrator Python project."
+---
+
+# Dev — Implementation Agent
+
+## Persona
+
+- **Role:** Expert Senior Software Engineer & Implementation Specialist
+- **Style:** Extremely concise, pragmatic, detail-oriented, solution-focused
+- **Focus:** Implementing tasks with precision, comprehensive testing, minimal context overhead
+
+## Core Principles
+
+- Read requirements fully before writing any code.
+- Follow existing project conventions (Python 3.12, Black, ruff, mypy).
+- Only update sections you own (task checkboxes, dev notes, change log).
+- Present choices as numbered lists.
+- HALT on: unapproved deps needed, ambiguity after checking story, 3 consecutive failures, missing config, failing regression.
+
+## Commands
+
+All commands require `*` prefix when invoked (e.g., `*help`).
+
+| Command | Description |
+|---------|-------------|
+| `*help` | Show this command list |
+| `*develop {scope}` | Read task → implement → add tests → run checks → mark done |
+| `*run-tests` | Run `pytest -q`, `ruff check .`, `black --check .` |
+| `*explain` | Explain changes and rationale at a junior engineer level |
+| `*review-qa` | Apply fixes from QA review findings |
+| `*dod-checklist` | Run the Definition of Done checklist |
+| `*exit` | Leave Dev persona |
+
+## Develop Workflow
+
+```
+Read task → Implement → Write tests → Run validations
+  → ALL pass? → Mark task [x] → Update file list → Next task
+  → ANY fail? → Fix → Re-validate (max 3 attempts, then HALT)
+```
+
+### Completion Criteria
+
+- All tasks marked `[x]` with tests
+- `pytest` passes (unit/integration)
+- `ruff check .` passes
+- `black --check .` passes
+- Optional: `mypy --strict` passes for new/changed modules
+- File list is complete
+- Run DoD checklist (`*dod-checklist`)
+
+## Project-Specific Notes
+
+- **Language:** Python 3.12
+- **Framework:** Gradio app with custom `mediagallery` component
+- **Runtime tools:** FFmpeg, moviepy (used for metadata & rendering)
+- **Test:** `pytest` (unit/integration), Playwright (optional E2E)
+- **Style:** `black`, `ruff`, `isort`
+- **Lint:** `ruff`
+- **Run:** `python app.py` (local dev)
+- **Env:** HF spaces tokens via `HF_TOKEN` may be required for some features
+
+## Blocking Conditions
+
+Stop and ask the user when:
+1. A new dependency is needed that isn't pre-approved
+2. Requirements are ambiguous after checking the task description
+3. You've failed 3 times on the same implementation/fix
+4. Configuration is missing (env vars, API keys like `HF_TOKEN`)
+5. Regression tests fail after your change

.github/agents/file-discovery.agent.md

@@ -0,0 +1,49 @@
+---
+name: file-discovery
+description: "Use when: discover media files and extract metadata from a folder for the MediaGallery pipeline."
+---
+
+# File Discovery Agent
+
+Name: File Discovery Agent
+Purpose: Walk a user-specified folder, discover supported media files, extract metadata, and return a `files_info` list compatible with the existing MediaGallery pipeline.
+
+Skills required:
+- python-pro
+- mcp-developer
+- gradio-expert (for UI wiring guidance)
+
+Triggers:
+- User provides a folder path in the UI
+- CLI / automated import job
+
+Entrypoint function:
+- `discover_folder_files(folder_path: str) -> list[dict]`
+
+Expected outputs:
+- A list of file info dicts, each containing: `filename`, `filepath`, `type` ("image"/"video"/"audio"), `width`, `height`, `duration_sec` (video/audio), `mime`, `created_at`
+- Compatible with `normalize_files()` and `get_files_infos()` in repo
+
+Implementation notes:
+- Use `pathlib.Path.rglob()` to walk the directory and filter by `allowed_medias` from `app.py`.
+- Use `Pillow` (`PIL.Image`) for image dimensions, `moviepy` for video/audio duration and dimensions, and `python-magic` or `mimetypes` fallback for mime type detection.
+- Respect file size and duration limits described in README (file size limit, max duration).
+- Support stable ordering (by filename or file created time) to make deterministic plans.
+
+Testing:
+- Provide pytest unit tests under `tests/test_file_discovery.py` mocking a temporary directory with sample files.
+
+Deployment:
+- Place implementation stub in `utils.py` (function name: `discover_folder_files`).
+
+Security:
+- Do not follow symlinks outside folder root unless explicitly allowed.
+- Validate path input to avoid path-traversal.
+- When running as part of an MCP server, prefer using the MCP file-system service (FSS) to access files in approved locations rather than direct disk access.
+  - Configure and honor an `allowed_paths` / whitelist (examples: `C:\Users\CharlesFettinger\.github\agents`, project media folders) so the agent only reads from approved roots.
+  - Reject or sanitize user-supplied paths that reference locations outside the configured allowed paths.
+  - Do not enable recursive traversal of system roots (e.g., `C:\` or `/`) from untrusted inputs.
+  - Log and audit all FSS file accesses for traceability.
+
+Example prompt for the agent (if exposed to an LLM-backed subagent):
+"Given a folder path `C:/Users/Me/Pictures/trip`, find all supported media files, extract dimensions and duration, and return a JSON array of file-info objects compatible with the project's `files_info` schema."

.github/agents/local_dev.agent.md

@@ -0,0 +1,73 @@
+---
+name: local dev
+description: "Use when: implementing features, fixing bugs, refactoring code, or executing development tasks for the ai-video-orchestrator Python project."
+model: qwen3.5:35b-a3b-q8_0 (ollama)
+---
+
+# Dev — Implementation Agent
+
+## Persona
+
+- **Role:** Expert Senior Software Engineer & Implementation Specialist
+- **Style:** Extremely concise, pragmatic, detail-oriented, solution-focused
+- **Focus:** Implementing tasks with precision, comprehensive testing, minimal context overhead
+
+## Core Principles
+
+- Read requirements fully before writing any code.
+- Follow existing project conventions (Python 3.12, Black, ruff, mypy).
+- Only update sections you own (task checkboxes, dev notes, change log).
+- Present choices as numbered lists.
+- HALT on: unapproved deps needed, ambiguity after checking story, 3 consecutive failures, missing config, failing regression.
+
+## Commands
+
+All commands require `*` prefix when invoked (e.g., `*help`).
+
+| Command | Description |
+|---------|-------------|
+| `*help` | Show this command list |
+| `*develop {scope}` | Read task → implement → add tests → run checks → mark done |
+| `*run-tests` | Run `pytest -q`, `ruff check .`, `black --check .` |
+| `*explain` | Explain changes and rationale at a junior engineer level |
+| `*review-qa` | Apply fixes from QA review findings |
+| `*dod-checklist` | Run the Definition of Done checklist |
+| `*exit` | Leave Dev persona |
+
+## Develop Workflow
+
+```
+Read task → Implement → Write tests → Run validations
+  → ALL pass? → Mark task [x] → Update file list → Next task
+  → ANY fail? → Fix → Re-validate (max 3 attempts, then HALT)
+```
+
+### Completion Criteria
+
+- All tasks marked `[x]` with tests
+- `pytest` passes (unit/integration)
+- `ruff check .` passes
+- `black --check .` passes
+- Optional: `mypy --strict` passes for new/changed modules
+- File list is complete
+- Run DoD checklist (`*dod-checklist`)
+
+## Project-Specific Notes
+
+- **Language:** Python 3.12
+- **Framework:** Gradio app with custom `mediagallery` component
+- **Runtime tools:** FFmpeg, moviepy (used for metadata & rendering)
+- **Test:** `pytest` (unit/integration), Playwright (optional E2E)
+- **Style:** `black`, `ruff`, `isort`
+- **Lint:** `ruff`
+- **Run:** `python app.py` (local dev)
+- **Env:** HF spaces tokens via `HF_TOKEN` may be required for some features
+
+## Blocking Conditions
+
+Stop and ask the user when:
+1. A new dependency is needed that isn't pre-approved
+2. Requirements are ambiguous after checking the task description
+3. You've failed 3 times on the same implementation/fix
+4. Configuration is missing (env vars, API keys like `HF_TOKEN`)
+5. Regression tests fail after your change

.github/agents/orchestrator.agent.md

@@ -0,0 +1,69 @@
+---
+name: orchestrator
+description: "Use when: a task should be decomposed into subtasks handled by specialized subagents (dev, qa). Coordinates build, test, and review workflows across agents for this repository."
+---
+
+# Orchestrator — Multi-Agent Coordinator
+
+## Persona
+
+- **Role:** Task decomposition and workflow coordination
+- **Style:** Concise, systematic, results-oriented
+- **Focus:** Breaking work into subagent tasks, collecting outputs, and ensuring quality gates pass
+
+## Available Subagents
+
+| Agent | File | Use For |
+| ----- | ---- | ------- |
+| **dev** | `.github/agents/dev.agent.md` | Implementing features, fixing bugs, refactoring, running tests |
+| **local_dev** | `.github/agents/local_dev.agent.md` | Python project implementation (Gradio, mediagallery, FFmpeg, moviepy) |
+| **code_munch** | `.github/agents/code-munch.agent.md` | Repository indexing via MCP code_munch server |
+| **qa** | `.github/agents/qa.agent.md` | Code review, test design, QA gate decisions, risk assessment |
+| **orchestrator** | `.github/agents/orchestrator.agent.md` | High-level task decomposition and workflow coordination |
+
+## Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `*help` | Show this command list |
+| `*plan {goal}` | Decompose goal into numbered subtasks with assigned agents |
+| `*build` | Run full pipeline: `ruff check .` → `pytest` (local checks) |
+| `*test` | Run `pytest` and report results |
+| `*gate {scope}` | Invoke QA agent to produce a gate decision for the scope |
+| `*status` | Show progress on current plan |
+
+## Workflow
+
+1. **Decompose** — Break the user's goal into 2–6 discrete subtasks.
+2. **Assign** — Pick the best subagent for each subtask (dev, local_dev, code_munch, qa, or orchestrator).
+3. **Execute** — Launch each subagent via `runSubagent` with a focused prompt and minimal context.
+4. **Validate** — After dev work, invoke QA for review/gate. If gate is FAIL, re-invoke dev with findings.
+5. **Report** — Merge outputs, present consolidated result with a changelog.
+
+### Build-Test-Review Cycle
+
+```
+Orchestrator
+  ├─► code_munch    → index repository (MCP call)
+  ├─► local_dev     → implement task (Python/Gradio project)
+  ├─► local_dev     → run tests (pytest, ruff, black)
+  ├─► qa agent      → review + gate decision
+  │     ├─ PASS       → done
+  │     ├─ CONCERNS   → log, proceed
+  │     └─ FAIL       → local_dev fixes → re-gate (max 2 retries)
+  └─► report results
+```
+
+## Safety & Constraints
+
+- Do not use `applyTo: "**"` — invoke explicitly.
+- Keep subagent prompts small; do not leak secrets.
+- HALT after 2 failed gate retries and escalate to user.
+- Prefer reversible actions; confirm destructive operations with user.
+
+## Supporting Resources
+
+| Resource | Path |
+| -------- | ---- |
+| Gate Output Dir | `.ai/qa/gates/` |
+| Assessment Output Dir | `.ai/qa/assessments/` |

.github/agents/qa.agent.md

@@ -0,0 +1,88 @@
+---
+name: qa
+description: "Use when: reviewing code quality, designing tests, performing QA gate decisions, tracing requirements to tests, or assessing risk for the ai-video-orchestrator Python project."
+---
+
+# Quinn — Test Architect & Quality Advisor
+
+## Persona
+
+- **Role:** Test Architect with Quality Advisory Authority
+- **Style:** Comprehensive, systematic, advisory, educational, pragmatic
+- **Focus:** Quality analysis through test architecture, risk assessment, and advisory gates
+
+## Core Principles
+
+- **Depth As Needed** — Go deep based on risk signals, stay concise when low risk.
+- **Requirements Traceability** — Map acceptance criteria to tests using Given-When-Then.
+- **Risk-Based Testing** — Prioritize by probability × impact.
+- **Testability Assessment** — Evaluate controllability, observability, debuggability.
+- **Gate Governance** — Provide clear PASS / CONCERNS / FAIL decisions with rationale.
+- **Advisory Excellence** — Educate through documentation, never block arbitrarily.
+- **Pragmatic Balance** — Distinguish must-fix from nice-to-have improvements.
+
+## Commands
+
+All commands require `*` prefix when invoked (e.g., `*help`).
+
+| Command | Description |
+|---------|-------------|
+| `*help` | Show this command list |
+| `*gate {scope}` | Write/update a QA gate decision for the given scope |
+| `*review {scope}` | Adaptive risk-aware review producing gate decision |
+| `*test-design {scope}` | Create comprehensive test scenarios (unit/integration/e2e) |
+| `*trace {scope}` | Map requirements → tests using Given-When-Then |
+| `*risk-profile {scope}` | Generate risk assessment matrix |
+| `*run-tests` | Execute `pytest -q` and `ruff check .` |
+| `*exit` | Leave QA persona |
+
+## Gate Decision Criteria
+
+| Gate | When |
+|------|------|
+| **PASS** | All acceptance criteria met, no high-severity issues, tests pass |
+| **CONCERNS** | Non-blocking issues present; can proceed with awareness |
+| **FAIL** | Acceptance criteria not met or high-severity issues found |
+
+## Severity Scale
+
+- `low` — Minor / cosmetic
+- `medium` — Should fix soon, not blocking
+- `high` — Critical, should block release
+
+## Issue ID Prefixes
+
+`SEC-` Security · `PERF-` Performance · `TEST-` Testing gaps · `MNT-` Maintainability · `ARCH-` Architecture · `DOC-` Documentation · `REQ-` Requirements
+
+## Gate File Location
+
+Gate files are saved to `.ai/qa/gates/{scope-slug}.yml`.
+
+### Minimal Gate Schema
+
+```yaml
+schema: 1
+scope: "{scope}"
+gate: PASS|CONCERNS|FAIL
+status_reason: "1-2 sentence explanation"
+reviewer: "Quinn"
+updated: "{ISO-8601}"
+top_issues: []
+model: "GPT-5 mini"
+```
+
+## Project-Specific Notes
+
+- This is a **Python / Gradio** project (ai-video-orchestrator).
+- Run unit/integration tests with `pytest -q`, lint with `ruff check .`, format checks with `black --check .`.
+- Type checking (optional) with `mypy` for new modules.
+- E2E tests (where present) use Playwright; keep tests independent and reproducible.
+- When reviewing, update only the QA Results section of any story/task file — do not modify other sections without consent.
+
+## Workflow
+
+1. Read the scope (file, component, story, or PR diff).
+2. Analyze against acceptance criteria, coding standards, and security best practices.
+3. Design test scenarios at appropriate levels (unit → integration → e2e).
+4. Produce gate decision with actionable findings.
+5. Run `pytest -q` and `ruff check .` to validate.

.github/copilot-instructions.md

@@ -0,0 +1,61 @@
+# Copilot Instructions
+
+## General Guidelines
+- Minimal changes to existing code
+- Preserve functionality when possible
+- Clear and concise comments
+- No plan unless specified
+- No compile unless specified
+- No test unless specified
+- If testing is specified:
+    - prefer MCP playwright-based tests headless browser testing with chrome, webkit , edge and firefox
+    - MSTest framework
+    - UV is used
+- Avoid new dependencies
+- use existing functions in the modules folder before writing new code. avoid modifying the existing functions if possible, prefer overload functions.
+
+
+## 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
+        )
+```
+

.github/instructions/py.instructions.md

@@ -0,0 +1,14 @@
+## Python and Streamlit Instructions
+---
+applyTo: `**/*.py`
+---
+
+- Write clear and concise docstrings for each function and class.
+- Use snake_case for function names, variable names, and module names.
+- Use CamelCase for class names.
+- Follow PEP 8: Use 4 spaces for indentation, limit lines to 79 characters.
+- Add a blank line before and after function definitions.
+- For Streamlit: Prefix components with `st.`, organize UI elements logically, use `st.sidebar` for controls.
+- Ensure imports are at the top, grouped by standard, third-party (e.g., streamlit), then local.
+- never loop the same command to burn user tokens, ask if you run into an error for permission
+- in html string variables use double curly braces for interpolation, e.g., `{{ variable_name }}`, especially in f-strings with "<script>" tags.

.github/prompts/document.md

@@ -0,0 +1,15 @@
+update readme.md, claude.md, specs/specs.mdx, specs/requirements.mdx , specs/leaderboard_spec.mdx, battlewords/__init__.py, pyproject.toml, #gameplay_guide.md  for these latest changes, as needed. Make changes minimal.
+include any new features, bug fixes, or important updates in the documentation.
+ensure **Current Version:** is up to date in all relevant files.
+ensure **Last Updated:** is current
+
+- Update documentation to reflect UI changes in battlewords/ui.py, including:
+  - Leaderboard navigation is now in the footer menu, not the sidebar.
+  - Game over dialog integrates leaderboard submission and displays qualification results.
+  - Leaderboard page routing uses query parameters and custom navigation links.
+  - Footer navigation links to Leaderboard, Play, and Settings pages.
+- Make all documentation changes minimal and focused on these UI updates.
+
+Additionally in #readme.md:
+- Update Recent Changes to reflect the new UI changes
+- Update Known Issues sections to reflect any related bug fixes or improvements.

.gitignore

@@ -0,0 +1,17 @@
+################################################################################
+# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
+################################################################################
+
+/.vs
+.env
+# Commonly ignored items (adjust as needed)
+node_modules/
+.pip/
+venv/
+__pycache/
+**.bat, **.ps1
+.bak
+/__pycache__
+separated/htdemucs/
+separated/htdemucs_6s/
+*.webm

CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md — SeparateTracks Project Context
+
+## Project Overview
+**SeparateTracks** (`Surn/SeparateTracks`) — A HuggingFace Docker Space that:
+- Downloads audio from YouTube via `yt-dlp` + Deno
+- Separates audio into 6 instrument stems using Demucs (`htdemucs_6s`)
+- 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()` |
+| `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) |
+| `specs/build.md` | Step-by-step build plan |
+
+## Architecture
+```
+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
+```
+
+## 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
+- **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)
+- **Testing** — Playwright MCP headless (Chrome/WebKit/Edge/Firefox), MSTest, UV
+
+## Python Style (from `.github/instructions/py.instructions.md`)
+- Snake_case functions/variables, CamelCase classes
+- PEP 8: 4-space indent, 79-char lines
+- Imports: stdlib → third-party → local
+- **In f-strings with `<script>` tags: use `{{ }}` for JS template literals**
+- Tools: `black`, `ruff`, `isort`, `mypy` (optional)
+
+## Environment Variables (`.env`)
+| Variable | Purpose |
+|----------|---------|
+| `HF_TOKEN` | HuggingFace API token |
+| `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
+```
+
+## Docker Commands
+```bash
+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 |
+| `file-discovery` | Locates files across repo |
+
+## Security Notes
+- `.env` contains sensitive credentials — never commit
+- `constants.py` validates `HF_TOKEN` at import time; ensure `.env` is loaded first
+- Rotate `HF_TOKEN` and `CRYPTO_PK` if they were ever exposed

README.md

@@ -1,11 +1,22 @@
 ---
 title: SeparateTracks
-emoji: 🦀
-colorFrom: purple
-colorTo: indigo
+emoji: 🎼
+colorFrom: red
+colorTo: yellow
 sdk: docker
+sdk_version: 6.13.0
+app_file: app.py
+tags:
+ - audio
+ - music
+ - tools
+ - MCP
 pinned: false
-short_description: Take
+short_description: Separate tracks from a mixed audio
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# Track Separate
+
+

app.py

@@ -0,0 +1,274 @@
+# app.py — SeparateTracks Gradio application
+# Entry point: python app.py  (runs on http://localhost:7860)
+# MCP endpoint: http://localhost:7860/gradio_api/mcp/sse
+import os
+import sys
+
+import gradio as gr
+
+from yt_audio_get_tracks import download_audio, separate_tracks
+
+
+# ---------------------------------------------------------------------------
+# 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 {
+    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;
+}
+"""
+
+# ---------------------------------------------------------------------------
+# 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)
+# ---------------------------------------------------------------------------
+def _footer_html():
+    try:
+        from modules.version_info import versions_html
+        return versions_html()
+    except Exception:
+        python_ver = ".".join(str(x) for x in sys.version_info[:3])
+        return f"python: {python_ver} &bull; gradio: {gr.__version__}"
+
+
+# ---------------------------------------------------------------------------
+# Core processing function (also exposed as MCP tool)
+# ---------------------------------------------------------------------------
+def process_video(video_id: str) -> str:
+    """Download audio from a YouTube video and separate it into instrument stems.
+
+    Uses Demucs htdemucs_6s to produce drums, vocals, guitar, bass, piano,
+    other, and a combined music track. Results are displayed as an audio gallery.
+
+    Args:
+        video_id: YouTube video ID (e.g. dQw4w9WgXcQ).
+
+    Returns:
+        HTML string containing the AudioGallery with all separated stems.
+    """
+    video_id = video_id.strip()
+    if not video_id:
+        return "<p style='color:red;'>Please enter a YouTube video ID.</p>"
+
+    try:
+        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)
+    except Exception as exc:
+        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
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+with gr.Blocks(title="SeparateTracks") as demo:
+    gr.Markdown(
+        "## \U0001f3bc SeparateTracks\n"
+        "Enter a YouTube video ID to separate the audio into instrument stems "
+        "using [Demucs htdemucs\\_6s](https://github.com/adefossez/demucs)."
+    )
+
+    with gr.Row():
+        video_id_input = gr.Textbox(
+            label="YouTube Video ID",
+            placeholder="dQw4w9WgXcQ",
+            scale=4,
+        )
+        run_btn = gr.Button("Separate Tracks", variant="primary", scale=1)
+
+    audio_output = gr.HTML(label="Separated Tracks")
+    gr.HTML(value=_footer_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,
+    )

dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+# System deps: ffmpeg for audio processing, git for version_info, Deno for yt-dlp JS extractor
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg curl unzip git \
+    && curl -fsSL https://deno.land/install.sh | sh \
+    && cp /root/.deno/bin/deno /usr/local/bin/ \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy requirements first for better layer caching
+COPY requirements.txt .
+
+# Install torch first (demucs dependency), then gradio, then everything else
+RUN pip install --no-cache-dir torch torchaudio torchvision
+RUN pip install --no-cache-dir gradio[mcp] transformers
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+CMD ["python", "app.py"]

modules/constants.py

@@ -0,0 +1,84 @@
+# modules/constants.py
+# constants.py contains all the constants used in the project such as the default LUT example image, prompts, negative prompts, pre-rendered maps, models, LoRA weights, and more.
+# execptions made for some environmental variables
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+import numpy as np
+
+
+
+IS_SHARED_SPACE = "Surn/SeparateTracks" in os.environ.get('SPACE_ID', '')
+
+# Load environment variables from .env file
+dotenv_path = Path(__file__).parent.parent / '.env'
+load_dotenv(dotenv_path)
+
+# Function to load env vars from .env and create Python variables
+def load_env_vars(env_path):
+    try:
+        with open(env_path, 'r') as file:
+            for line in file:
+                # Skip empty lines or comments
+                line = line.strip()
+                if line and not line.startswith('#'):
+                    # Split on the first '=' only
+                    if '=' in line:
+                        key, value = line.split('=', 1)
+                        key = key.strip()
+                        value = value.strip()
+                        # Dynamically create a Python variable with the key name
+                        globals()[key] = value
+                        # Also update os.environ (optional, for consistency)
+                        os.environ[key] = value
+    except FileNotFoundError:
+        print(f"Warning: .env file not found at {env_path}")
+
+
+
+USE_FLASH_ATTENTION = os.getenv("USE_FLASH_ATTENTION", "0") == "1"
+HF_API_TOKEN = os.getenv("HF_TOKEN", None)
+CRYPTO_PK = os.getenv("CRYPTO_PK", None)
+if not HF_API_TOKEN:
+    raise ValueError("HF_TOKEN is not set. Please check your .env file.")
+
+default_lut_example_img = "./LUT/daisy.jpg"
+MAX_SEED = np.iinfo(np.int32).max
+TARGET_SIZE = (2688,1536)
+BASE_HEIGHT = 640
+SCALE_FACTOR = (12/5)
+try:
+    if os.environ['TMPDIR']:
+        TMPDIR = os.environ['TMPDIR']
+    else:
+        TMPDIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tmp')
+except:
+    TMPDIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tmp')
+
+os.makedirs(TMPDIR, exist_ok=True)
+
+SPACE_NAME = os.getenv('SPACE_NAME', 'Surn/SeparateTracks')
+
+# Constants for URL shortener and storage
+HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage") # Replace with your Hugging Face repository ID
+
+SHORTENER_JSON_FILE = "shortener.json"
+
+model_extensions = {".glb", ".gltf", ".obj", ".ply"}
+model_extensions_list = list(model_extensions)
+image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+image_extensions_list = list(image_extensions)
+audio_extensions = {".mp3", ".wav", ".ogg", ".flac"}
+audio_extensions_list = list(audio_extensions)
+video_extensions = {".mp4"}
+video_extensions_list = list(video_extensions)
+doc_extensions = {".json"}
+doc_extensions_list = list(doc_extensions)
+upload_file_types = model_extensions_list + image_extensions_list + audio_extensions_list + video_extensions_list + doc_extensions_list
+
+umg_mcp_server = "https://surn-unlimitedmusicgen.hf.space/gradio_api/mcp/sse"
+#umg_mcp_server = "http://127.0.0.1:7860/gradio_api/mcp/sse"
+badge_negative_prompt = "low quality, blurry, copyright, cropped, worst quality, bad text, missing text, normal quality, jpeg artifacts, signature, watermark, username, missing_transparent_background"
+default_badge = "assets/openbadge.png"
+default_badge_512_url = os.getenv("DEFAULT_BADGE_512_URL",None)
+

modules/file_utils.py

@@ -0,0 +1,204 @@
+# file_utils
+import os
+import shutil
+from pathlib import Path
+import requests
+from PIL import Image
+from io import BytesIO
+from urllib.parse import urlparse
+
+def get_file_parts(file_path: str):
+    # Split the path into directory and filename
+    directory, filename = os.path.split(file_path)
+    
+    # Split the filename into name and extension
+    name, ext = os.path.splitext(filename)
+    
+    # Convert the extension to lowercase
+    new_ext = ext.lower()
+    return directory, filename, name, ext, new_ext
+
+def rename_file_to_lowercase_extension(file_path: str) -> str:
+    """
+    Renames a file's extension to lowercase in place.
+
+    Parameters:
+        file_path (str): The original file path.
+
+    Returns:
+        str: The new file path with the lowercase extension.
+
+    Raises:
+        OSError: If there is an error renaming the file (e.g., file not found, permissions issue).
+    """
+    directory, filename, name, ext, new_ext = get_file_parts(file_path)
+    # If the extension changes, rename the file
+    if ext != new_ext:
+        new_filename = name + new_ext
+        new_file_path = os.path.join(directory, new_filename)
+        try:
+            os.rename(file_path, new_file_path)
+            print(f"Rename {file_path} to {new_file_path}\n")
+        except Exception as e:
+            print(f"os.rename failed: {e}. Falling back to binary copy operation.")
+            try:
+                # Read the file in binary mode and write it to new_file_path
+                with open(file_path, 'rb') as f:
+                    data = f.read()
+                with open(new_file_path, 'wb') as f:
+                    f.write(data)
+                    print(f"Copied {file_path} to {new_file_path}\n")
+                # Optionally, remove the original file after copying
+                #os.remove(file_path)
+            except Exception as inner_e:
+                print(f"Failed to copy file from {file_path} to {new_file_path}: {inner_e}")
+                raise inner_e
+        return new_file_path
+    else:
+        return file_path
+
+def get_filename(file):
+    # extract filename from file object
+    filename = None
+    if file is not None:
+        filename = file.name
+    return filename
+
+def convert_title_to_filename(title):
+    # convert title to filename
+    filename = title.lower().replace(" ", "_").replace("/", "_")
+    return filename
+
+def get_filename_from_filepath(filepath):
+    file_name = os.path.basename(filepath)
+    file_base, file_extension = os.path.splitext(file_name)
+    return file_base, file_extension
+
+def delete_file(file_path: str) -> None:
+    """
+    Deletes the specified file.
+
+    Parameters:
+        file_path (str): The path to thefile to delete.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        Exception: If there is an error deleting the file.
+    """
+    try:
+        path = Path(file_path)
+        path.unlink()
+        print(f"Deleted original file: {file_path}")
+    except FileNotFoundError:
+        print(f"File not found: {file_path}")
+    except Exception as e:
+        print(f"Error deleting file: {e}")
+
+def get_unique_file_path(directory, filename, file_ext, counter=0):
+    """
+    Recursively increments the filename until a unique path is found.
+    
+    Parameters:
+        directory (str): The directory for the file.
+        filename (str): The base filename.
+        file_ext (str): The file extension including the leading dot.
+        counter (int): The current counter value to append.
+        
+    Returns:
+        str: A unique file path that does not exist.
+    """
+    if counter == 0:
+        filepath = os.path.join(directory, f"{filename}{file_ext}")
+    else:
+        filepath = os.path.join(directory, f"{filename}{counter}{file_ext}")
+
+    if not os.path.exists(filepath):
+        return filepath
+    else:
+        return get_unique_file_path(directory, filename, file_ext, counter + 1)
+
+# Example usage:
+# new_file_path = get_unique_file_path(video_dir, title_file_name, video_new_ext)
+
+def download_and_save_image(url: str, dst_folder: Path, token: str = None) -> Path:
+    """
+    Downloads an image from a URL with authentication if a token is provided,
+    verifies it with PIL, and saves it in dst_folder with a unique filename.
+
+    Args:
+        url (str): The image URL.
+        dst_folder (Path): The destination folder for the image.
+        token (str, optional): A valid Bearer token. If not provided, the HF_API_TOKEN
+                              environment variable is used if available.
+
+    Returns:
+        Path: The saved image's file path.
+    """
+    headers = {}
+    # Use provided token; otherwise, fall back to environment variable.
+    api_token = token
+    if api_token:
+        headers["Authorization"] = f"Bearer {api_token}"
+    
+    response = requests.get(url, headers=headers)
+    response.raise_for_status()
+    pil_image = Image.open(BytesIO(response.content))
+    
+    parsed_url = urlparse(url)
+    original_filename = os.path.basename(parsed_url.path)  # e.g., "background.png"
+    base, ext = os.path.splitext(original_filename)
+    
+    # Use get_unique_file_path from file_utils.py to generate a unique file path.
+    unique_filepath_str = get_unique_file_path(str(dst_folder), base, ext)
+    dst = Path(unique_filepath_str)
+    dst_folder.mkdir(parents=True, exist_ok=True)
+    pil_image.save(dst)
+    return dst
+
+def download_and_save_file(url: str, dst_folder: Path, token: str = None) -> Path:
+    """
+    Downloads a binary file (e.g., audio or video) from a URL with authentication if a token is provided,
+    and saves it in dst_folder with a unique filename.
+
+    Args:
+        url (str): The file URL.
+        dst_folder (Path): The destination folder for the file.
+        token (str, optional): A valid Bearer token.
+
+    Returns:
+        Path: The saved file's path.
+    """
+    headers = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    
+    response = requests.get(url, headers=headers)
+    response.raise_for_status()
+    
+    parsed_url = urlparse(url)
+    original_filename = os.path.basename(parsed_url.path)
+    base, ext = os.path.splitext(original_filename)
+    
+    unique_filepath_str = get_unique_file_path(str(dst_folder), base, ext)
+    dst = Path(unique_filepath_str)
+    dst_folder.mkdir(parents=True, exist_ok=True)
+    
+    with open(dst, "wb") as f:
+        f.write(response.content)
+    
+    return dst
+
+
+if __name__ == "__main__":
+    # Example usage
+    url = "https://example.com/image.png"
+    dst_folder = Path("downloads")
+    download_and_save_image(url, dst_folder)
+    # Example usage for file download
+    file_url = "https://example.com/file.mp3"
+    downloaded_file = download_and_save_file(file_url, dst_folder)
+    print(f"File downloaded to: {downloaded_file}")
+    # Example usage for renaming file extension
+    file_path = "example.TXT"
+    new_file_path = rename_file_to_lowercase_extension(file_path)
+    print(f"Renamed file to: {new_file_path}")

modules/version_info.py

@@ -0,0 +1,120 @@
+# version_info.py
+
+import subprocess
+import os
+import sys
+import gc
+import gradio as gr
+
+git = os.environ.get('GIT', "git")
+
+def commit_hash():
+    try:
+        return subprocess.check_output([git, "rev-parse", "HEAD"], shell=False, encoding='utf8').strip()
+    except Exception:
+        return "<none>"
+
+def get_xformers_version():
+    try:
+        import xformers
+        return xformers.__version__
+    except Exception:
+        return "<none>"
+def get_transformers_version():
+    try:
+        import transformers
+        return transformers.__version__
+    except Exception:
+        return "<none>"
+
+def get_accelerate_version():
+    try:
+        import accelerate
+        return accelerate.__version__
+    except Exception:
+        return "<none>"
+def get_safetensors_version():
+    try:
+        import safetensors
+        return safetensors.__version__
+    except Exception:
+        return "<none>"
+def get_diffusers_version():
+    try:
+        import diffusers
+        return diffusers.__version__
+    except Exception:
+        return "<none>"
+
+def get_torch_info():
+    from torch import __version__ as torch_version_, version, cuda, backends
+    device_type = initialize_cuda()
+    if device_type == "cuda":
+        try:
+            info = [torch_version_, f"CUDA Version:{version.cuda}", f"Available:{cuda.is_available()}", f"flash attention enabled: {backends.cuda.flash_sdp_enabled()}", f"Capabilities: {cuda.get_device_capability(0)}", f"Device Name: {cuda.get_device_name(0)}", f"Device Count: {cuda.device_count()}"]
+            del torch_version_, version, cuda, backends
+            return info
+        except Exception:
+            del torch_version_, version, cuda, backends
+            return "<none>"
+    else:
+        return "Not Recognized"
+
+def release_torch_resources():
+    from torch import cuda
+    # Clear the CUDA cache
+    cuda.empty_cache()
+    cuda.ipc_collect()
+    # Delete any objects that are using GPU memory
+    #for obj in gc.get_objects():
+    #    if is_tensor(obj) or (hasattr(obj, 'data') and is_tensor(obj.data)):
+    #        del obj
+    # Run garbage collection
+    del cuda
+    gc.collect()
+    
+
+def initialize_cuda():
+    from torch import cuda, version
+    if cuda.is_available():
+        device = cuda.device("cuda")
+        print(f"CUDA is available. Using device: {cuda.get_device_name(0)} with CUDA version: {version.cuda}")
+        result = "cuda"
+    else:
+        print("CUDA is not available. Using CPU.")
+        result = "cpu"
+    return result
+
+def versions_html():
+    from torch import __version__ as torch_version_
+    python_version = ".".join([str(x) for x in sys.version_info[0:3]])
+    commit = commit_hash()
+
+    # Define the Toggle Dark Mode link with JavaScript
+    toggle_dark_link = '''
+        <a href="#" onclick="document.body.classList.toggle('dark'); return false;" style="cursor: pointer; text-decoration: underline;">
+            Toggle Dark Mode
+        </a>
+    '''
+
+    v_html = f"""
+        version: <a href="https://huggingface.co/spaces/Surn/DPTDepth3D/commit/{"huggingface" if commit == "<none>" else commit}" target="_blank">{"huggingface" if commit == "<none>" else commit}</a>
+        &#x2000;•&#x2000;
+        python: <span title="{sys.version}">{python_version}</span>
+        &#x2000;•&#x2000;
+        torch: {torch_version_}
+        &#x2000;•&#x2000;
+        xformers: {get_xformers_version()}
+        &#x2000;•&#x2000;
+        transformers: {get_transformers_version()}
+        &#x2000;•&#x2000;
+        safetensors: {get_safetensors_version()}
+        &#x2000;•&#x2000;
+        gradio: {gr.__version__}
+        &#x2000;•&#x2000;
+        {toggle_dark_link}
+        <br>
+        Full GPU Info:{get_torch_info()}
+        """
+    del torch_version_
+    return v_html

requirements.txt

@@ -0,0 +1,15 @@
+# core audio pipeline
+yt-dlp
+demucs
+pydub
+youtube-transcript-api
+youtube-channel-transcript-api
+
+# gradio UI + MCP server
+gradio[mcp]>=5.0
+
+# utility deps used by modules/
+python-dotenv
+numpy
+Pillow
+requests

specs/build.md

@@ -0,0 +1,296 @@
+# SeparateTracks — Build Plan
+
+## Goal
+Produce a running Gradio application (`app.py`) that downloads audio from YouTube,
+separates it into instrument stems via Demucs, displays results in an `AudioGallery`
+UI, and exposes an MCP server endpoint — deployable locally and as a HuggingFace
+Docker Space (`Surn/SeparateTracks`).
+
+---
+
+## Project Map
+
+| File | Status | Purpose |
+|------|--------|---------|
+| `yt_audio_get_tracks.py` | exists | Core logic: download + separate |
+| `app.py` | **MISSING** | Gradio UI entry point |
+| `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 |
+
+---
+
+## Step 1 — Fix `.gitignore`
+
+**Problem:** `.env` contains real credentials (`HF_TOKEN`, `CRYPTO_PK`) and is not
+excluded from git tracking.
+
+**Action:** Add `.env` to `.gitignore`.
+
+```
+# add to .gitignore
+.env
+separated/
+*.webm
+```
+
+> **WARNING:** Rotate/regenerate the `HF_TOKEN` and `CRYPTO_PK` values in `.env`
+> if they have ever been committed to git or shared publicly.
+
+---
+
+## Step 2 — Fix `requirements.txt`
+
+Current file is missing packages that `modules/` and the planned `app.py` need.
+
+```txt
+# core audio pipeline
+yt-dlp
+demucs
+pydub
+youtube-transcript-api
+youtube-channel-transcript-api
+
+# gradio UI + MCP
+gradio[mcp]>=5.0
+
+# utility deps used by modules/
+python-dotenv
+numpy
+Pillow
+requests
+```
+
+> `ffmpeg` must be installed at the OS level (not via pip); handle in dockerfile.
+> `torch`, `torchaudio` are installed separately in dockerfile (CUDA variants).
+
+---
+
+## Step 3 — Fix `dockerfile`
+
+Current dockerfile:
+- Missing `apt-get install ffmpeg`
+- Missing `pip install -r requirements.txt`
+- Missing demucs, yt-dlp, pydub installs
+
+Updated dockerfile structure:
+
+```dockerfile
+FROM python:3.12-slim
+
+# System deps: ffmpeg for audio processing + Deno for yt-dlp JS extractor
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg curl unzip git \
+    && curl -fsSL https://deno.land/install.sh | sh \
+    && cp /root/.deno/bin/deno /usr/local/bin/ \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+
+# Install torch CPU build first (HF Spaces GPU spaces override separately)
+RUN pip install --no-cache-dir torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+RUN pip install --no-cache-dir gradio[mcp] transformers
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+CMD ["python", "app.py"]
+```
+
+> For HF Spaces GPU, the base image and torch install are handled by the Space
+> runtime — the dockerfile may be simplified or replaced by `sdk: gradio` in README.
+
+---
+
+## 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
+
+
+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)
+```
+
+---
+
+## Step 5 — Implement `AudioGallery` Component
+
+Per copilot-instructions.md, the `AudioGallery` extends `gr.HTML` and renders
+an audio grid with waveform canvases.
+
+**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
+
+**Reference:** https://huggingface.co/spaces/fffiloni/audio-gallery
+
+---
+
+## 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)
+
+No additional code is needed beyond `mcp_server=True` in `launch()`.
+
+---
+
+## Step 7 — Fix `modules/constants.py` for Local Dev
+
+`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
+loaded before `constants.py` is imported.
+
+**Note:** `constants.py` also imports `numpy` and `python-dotenv` — both must be
+in `requirements.txt` (covered in Step 2).
+
+---
+
+## Step 8 — Local Run Verification
+
+```bash
+# Prerequisites
+# - Python 3.12
+# - ffmpeg in PATH
+# - .env file with HF_TOKEN set
+
+pip install -r requirements.txt
+python app.py
+# → Open http://localhost:7860
+# → Enter a YouTube video ID, click "Separate Tracks"
+# → Verify 7 stems appear in AudioGallery
+# → Verify MCP endpoint at http://localhost:7860/gradio_api/mcp/sse
+```
+
+---
+
+## Step 9 — Docker Verification
+
+```bash
+docker build -t separatetracks .
+docker run -p 7860:7860 --env-file .env separatetracks
+# → Open http://localhost:7860 and verify same as Step 8
+```
+
+---
+
+## Step 10 — HuggingFace Space Deployment
+
+1. `README.md` already has correct HF Space header (`sdk: docker`, `app_file: app.py`)
+2. Push to `Surn/SeparateTracks` HF Space repo
+3. Set Space secrets: `HF_TOKEN`, `CRYPTO_PK`, `HF_REPO_ID`, `SPACE_NAME`
+4. Space auto-builds from dockerfile on push
+
+---
+
+## Dependency Map
+
+```
+app.py
+ ├── yt_audio_get_tracks.py
+ │    ├── yt-dlp          (pip)
+ │    ├── pydub           (pip)  → ffmpeg (apt)
+ │    └── demucs          (pip)  → torch (pip)
+ ├── modules/constants.py
+ │    ├── python-dotenv   (pip)
+ │    └── numpy           (pip)
+ ├── modules/version_info.py
+ │    └── gradio          (pip)
+ └── modules/file_utils.py
+      ├── Pillow          (pip)
+      └── requests        (pip)
+```
+
+---
+
+## File Checklist
+
+| # | File | Action | Done |
+|---|------|--------|------|
+| 1 | `.gitignore` | Add `.env` entry | [x] |
+| 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 |
+
+---
+
+## Notes
+
+- **Deno**: Required by yt-dlp for some YouTube JS extraction. Dockerfile installs it
+  from `deno.land/install.sh`. Locally, download from
+  https://github.com/denoland/deno/releases/latest/download/deno-x86_64-pc-windows-msvc.zip
+  and add `deno.exe` to PATH or project root.
+- **Demucs model**: `htdemucs_6s` downloads ~1.5 GB on first run. In Docker, this
+  happens at runtime unless pre-cached in image.
+- **Python style**: Black + ruff + isort per agent conventions. PEP 8, 4-space indent,
+  79-char lines.
+- **AudioGallery JS**: Use `{{ }}` for JS template literals inside Python f-strings
+  (py.instructions.md rule).

yt_audio_get_tracks.py

@@ -0,0 +1,68 @@
+# yt_separator.py
+# pip install yt-dlp demucs pydub (ffmpeg required)
+import os, sys, subprocess
+import shutil
+import yt_dlp
+from pydub import AudioSegment
+
+def download_audio(url, video_id):
+    temp_dir = 'separated'
+    os.makedirs(temp_dir, exist_ok=True)
+    ydl_opts = {
+        'format': 'bestaudio/best',
+        'outtmpl': os.path.join(temp_dir, f'{video_id}.%(ext)s'),
+        'postprocessors': [{'key': 'FFmpegExtractAudio', 'preferredcodec': 'wav'}],
+        'keepvideo': True,
+        'quiet': False,
+        'no_warnings': False,
+        'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+        'http_headers': {'Referer': 'https://www.youtube.com/'},
+        # 'cookiesfrombrowser': ('chrome', None, None),
+    }
+
+    if shutil.which('deno') is None:
+        print("⚠️ Deno not found.")
+        ydl_opts['compat_opts'] = ['no-youtube-js']
+
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        ydl.download([url])
+    return os.path.join(temp_dir, f'{video_id}.wav')
+
+def separate_tracks(input_wav, video_id):
+    if not os.path.exists(input_wav):
+        raise FileNotFoundError(f"{input_wav} does not exist")
+    
+    output_dir = 'separated'
+    subprocess.run(['demucs', '-n', 'htdemucs_6s', '--mp3', '--out', output_dir, input_wav], check=True)
+    
+    base = os.path.join(output_dir, 'htdemucs_6s', video_id)
+    
+    drums = f'{base}/drums.mp3'
+    vocals = f'{base}/vocals.mp3'
+    bass = f'{base}/bass.mp3'
+    guitar = f'{base}/guitar.mp3'
+    piano = f'{base}/piano.mp3'
+    other = f'{base}/other.mp3'
+    
+    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)
+    
+    return drums, vocals, guitar, bass, other, piano, music_path
+
+
+def main():
+    video_id = input("enter youtube video id: ")
+    url = f"https://www.youtube.com/watch?v={video_id}"
+    try:
+        wav = download_audio(url, video_id)
+        d, v, g, b, o, p, m = separate_tracks(wav, video_id)
+        print(d, v, g, b, o, p, m)
+    except Exception as exc:
+        print(exc)
+
+
+if __name__ == "__main__":
+    main()