feat: media player API, web player panel, and Hope music MCP

- web/media_server.py: FastAPI service owning the permanent library
  (library.json + ./media volume), yt-dlp YouTube Music search, queued
  download jobs with mp3 transcode (ffmpeg), per-room player desired
  state, and an HTTPS proxy for external live-stream URLs.
- agent/media_mcp.py: Hope tools — search_music, play_song,
  offer_song_choices, pause/resume/stop/skip/seek, now_playing,
  list_library, add_stream.
- agent/agent.py: media toolset wiring + conversation rule (music
  playing disables the agent mic; re-engaging pauses music).
- web UI: slide-out Music panel (search, suggestions, library, live
  stream add, play/pause, ±10s, seek, volume) with a reconciling poller
  and media_state data-channel reports.
- token server returns the minted room name; nginx serves /media/files
  as static (native Range) and proxies /media/api to the media server.
- supervisord runs media-server; compose mounts ./media and adds
  ffmpeg to the image.

web/app.js

@@ -693,6 +693,7 @@ document.addEventListener("keydown", (event) => {
     if (event.key !== "Escape") return;
     if (settingsSheet.classList.contains("open")) closeSheet();
     if (tasksPanel.classList.contains("open")) setTasksOpen(false);
+    if (mediaPanel.classList.contains("open")) setMediaOpen(false);
 });
 // ── Wake lock ───────────────────────────────────────────────────────────────
 async function acquireWakeLock() {
@@ -816,6 +817,8 @@ function createRoom(token) {
         stopBtn.disabled = true;
         agentParticipant = null;
         agentReady = false;
+        // Leaving the conversation hands the room back to the music player.
+        resumePlaybackAfterTalk();
     });
 
     return newRoom.connect(LIVEKIT_URL, token, {
@@ -873,8 +876,9 @@ async function connectConversation() {
             await acquireWakeLock();
 
             // Get a signed access token from the token endpoint.
-            const token = await fetchToken(ROOM_NAME);
-            room = await createRoom(token);
+            const tokenData = await fetchToken(ROOM_NAME);
+            await enterMediaScope(tokenData.room);
+            room = await createRoom(tokenData.token);
 
             // The agent is dispatched when we join. If it misses the dispatch
             // (for example during a server restart), reconnect once.
@@ -886,8 +890,9 @@ async function connectConversation() {
                 agentParticipant = null;
                 agentReady = false;
                 await stale.disconnect();
-                const freshToken = await fetchToken(ROOM_NAME);
-                room = await createRoom(freshToken);
+                const freshTokenData = await fetchToken(ROOM_NAME);
+                await enterMediaScope(freshTokenData.room);
+                room = await createRoom(freshTokenData.token);
                 if (!(await waitForAgent(15000))) {
                     throw new Error("Assistant did not join — reload the page and try again");
                 }
@@ -999,6 +1004,8 @@ stopBtn.addEventListener("click", () => {
     muteBtn.disabled = true;
     micMuted = false;
     updateMuteIcon();
+    // Ending the conversation resumes music that was paused for the talk.
+    resumePlaybackAfterTalk();
 });
 
 // ── Mic mute toggle ─────────────────────────────────────────────────────────
@@ -1030,7 +1037,7 @@ async function fetchToken(roomName) {
     });
     if (!resp.ok) throw new Error(`Token endpoint returned ${resp.status}`);
     const data = await resp.json();
-    return data.token;
+    return { token: data.token, room: data.room || null };
 }
 
 // ── Helper: send voice selection to the agent via data channel ─────────────
@@ -1064,3 +1071,502 @@ function sendModelMessage(model, targetRoom) {
         reliable: true,
     });
 }
+
+// ── Media player ────────────────────────────────────────────────────────────
+// The browser <audio> element is the player. The media server owns library +
+// per-room desired state; this UI reconciles against GET /media/api/state
+// (polling) and reports real playback back. Hope drives the same state via
+// her media tools, so voice commands and panel clicks stay in sync.
+//
+// Conversation rule (mirrored in agent.py): while a track plays the agent's
+// mic is off. Connecting to Hope pauses music; ending the conversation
+// resumes what was playing.
+
+const mediaBtn = document.getElementById("mediaBtn");
+const mediaPanel = document.getElementById("mediaPanel");
+const closeMediaBtn = document.getElementById("closeMediaBtn");
+const mediaBadge = document.getElementById("mediaBadge");
+const mediaArt = document.getElementById("mediaArt");
+const mediaArtPlaceholder = document.getElementById("mediaArtPlaceholder");
+const mediaTitleEl = document.getElementById("mediaTitle");
+const mediaChannelEl = document.getElementById("mediaChannel");
+const mediaProgressWrap = document.getElementById("mediaProgressWrap");
+const mediaProgressFill = document.getElementById("mediaProgressFill");
+const mediaProgressLabel = document.getElementById("mediaProgressLabel");
+const rewBtn = document.getElementById("rewBtn");
+const fwdBtn = document.getElementById("fwdBtn");
+const playPauseBtn = document.getElementById("playPauseBtn");
+const playIcon = document.getElementById("playIcon");
+const pauseIcon = document.getElementById("pauseIcon");
+const stopMediaBtn = document.getElementById("stopMediaBtn");
+const seekBar = document.getElementById("seekBar");
+const mediaCurEl = document.getElementById("mediaCur");
+const mediaDurEl = document.getElementById("mediaDur");
+const volumeBar = document.getElementById("volumeBar");
+const mediaSearchForm = document.getElementById("mediaSearchForm");
+const mediaSearchInput = document.getElementById("mediaSearchInput");
+const mediaResultsEl = document.getElementById("mediaResults");
+const mediaChoicesWrap = document.getElementById("mediaChoicesWrap");
+const mediaChoicesEl = document.getElementById("mediaChoices");
+const mediaLibraryEl = document.getElementById("mediaLibrary");
+const streamForm = document.getElementById("streamForm");
+const streamNameInput = document.getElementById("streamName");
+const streamUrlInput = document.getElementById("streamUrl");
+const mediaAudio = document.getElementById("mediaAudio");
+
+let mediaRoom = null;              // LiveKit room name (player state scope)
+let mediaCurrentTrackId = null;    // track id loaded into the audio element
+let mediaAppliedSeekTs = 0;        // last applied seek_hint timestamp
+let mediaWasPlayingBeforeTalk = false;
+let mediaPollTimer = null;
+let mediaLastReport = 0;
+
+function mediaScope() {
+    return mediaRoom || "default";
+}
+
+async function mediaPost(path, body) {
+    const resp = await fetch(`/media/api${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ room: mediaScope(), ...body }),
+    });
+    if (!resp.ok) {
+        const detail = await resp.json().catch(() => ({}));
+        throw new Error(detail.error || `media API ${path} -> ${resp.status}`);
+    }
+    return resp.json();
+}
+
+// Called just before joining the LiveKit room: carry whatever the audio
+// element holds into the room-scoped player state, paused (talking pauses
+// music). resumePlaybackAfterTalk() reverses this when the talk ends.
+async function enterMediaScope(newRoom) {
+    if (!newRoom || newRoom === mediaRoom) return;
+    const wasPlaying = !!mediaCurrentTrackId && !mediaAudio.paused;
+    mediaWasPlayingBeforeTalk = wasPlaying;
+    const carriedTrack = mediaCurrentTrackId;
+    mediaRoom = newRoom;
+    if (carriedTrack) {
+        try {
+            await mediaPost("/play", { room: mediaRoom, track_id: carriedTrack, start_paused: true });
+        } catch (e) { console.warn("media scope transfer failed:", e); }
+        mediaAudio.pause();
+    }
+}
+
+async function resumePlaybackAfterTalk() {
+    if (!mediaWasPlayingBeforeTalk) return;
+    mediaWasPlayingBeforeTalk = false;
+    try { await mediaPost("/control", { action: "resume" }); } catch (e) { /* poll retries */ }
+}
+
+function publishMediaState(state) {
+    if (!room || !room.localParticipant) return;
+    const payload = new TextEncoder().encode(
+        JSON.stringify({ type: "media_state", state, track_id: mediaCurrentTrackId })
+    );
+    room.localParticipant.publishData(payload, { topic: "media-control", reliable: true });
+}
+
+function reportMediaPlayback(state) {
+    const body = {
+        state,
+        track_id: mediaCurrentTrackId,
+        position: isFinite(mediaAudio.currentTime) ? mediaAudio.currentTime : 0,
+    };
+    if (isFinite(mediaAudio.duration)) body.duration = mediaAudio.duration;
+    mediaPost("/report", body).catch(() => {});
+}
+
+// ── Polling + reconciliation ────────────────────────────────────────────────
+function startMediaPolling() {
+    if (mediaPollTimer) return;
+    mediaPollTimer = setInterval(() => {
+        pollMediaState();
+    }, 1500);
+}
+
+async function pollMediaState() {
+    let s;
+    try {
+        const resp = await fetch(`/media/api/state?room=${encodeURIComponent(mediaScope())}`);
+        if (!resp.ok) return;
+        s = await resp.json();
+    } catch (e) {
+        return; // media server briefly unavailable; try again next tick
+    }
+    reconcileMedia(s);
+}
+
+function reconcileMedia(s) {
+    renderMediaChoices(s.choices || []);
+    updateMediaBadge(s);
+
+    const track = s.track;
+    const pendingJob = (s.pending || []).find(j => !track || j.track_id === track.id);
+    updateMediaProgress(track, pendingJob);
+
+    if (track && track.id !== mediaCurrentTrackId) loadMediaTrack(track);
+    if (!track && mediaCurrentTrackId && s.desired === "stopped") clearMediaAudio();
+
+    applyDesiredMediaState(s, track);
+
+    if (s.seek_hint && s.seek_hint.ts !== mediaAppliedSeekTs && isFinite(mediaAudio.duration)) {
+        mediaAppliedSeekTs = s.seek_hint.ts;
+        const target = Math.min(s.seek_hint.position, mediaAudio.duration);
+        if (Number.isFinite(target)) {
+            mediaAudio.currentTime = Math.max(0, target);
+            updateSeekUI();
+        }
+    }
+}
+
+function applyDesiredMediaState(s, track) {
+    if (s.desired === "playing") {
+        if (track && track.status === "ready" && mediaAudio.src && mediaAudio.paused) {
+            mediaAudio.play().catch((e) => console.warn("playback blocked:", e));
+        }
+    } else if (!mediaAudio.paused) {
+        mediaAudio.pause();
+    }
+}
+
+function loadMediaTrack(track) {
+    mediaCurrentTrackId = track.id;
+    updateMediaNowCard(track);
+    if (track.audio_url && (track.kind === "stream" || track.status === "ready")) {
+        if (mediaAudio.getAttribute("src") !== track.audio_url) {
+            mediaAudio.src = track.audio_url;
+            mediaAudio.load();
+        }
+    } else {
+        // Downloading or failed: no stream yet. The poll flips this to the
+        // real URL once status turns "ready".
+        mediaAudio.removeAttribute("src");
+        mediaAudio.load();
+        updateMediaControls();
+    }
+}
+
+function clearMediaAudio() {
+    mediaCurrentTrackId = null;
+    mediaAudio.pause();
+    mediaAudio.removeAttribute("src");
+    mediaAudio.load();
+    mediaTitleEl.textContent = "Nothing loaded";
+    mediaChannelEl.textContent = "";
+    mediaArt.hidden = true;
+    mediaArtPlaceholder.hidden = false;
+    updateMediaControls();
+}
+
+function updateMediaNowCard(track) {
+    mediaTitleEl.textContent = track.title || track.id;
+    mediaChannelEl.textContent = track.channel || (track.kind === "stream" ? "Live stream" : "");
+    if (track.art_url) {
+        mediaArt.src = track.art_url;
+        mediaArt.hidden = false;
+        mediaArtPlaceholder.hidden = true;
+    } else {
+        mediaArt.hidden = true;
+        mediaArtPlaceholder.hidden = false;
+    }
+}
+
+function updateMediaProgress(track, job) {
+    if (!job) {
+        mediaProgressWrap.hidden = true;
+        return;
+    }
+    mediaProgressWrap.hidden = false;
+    const pct = Math.round(job.progress || 0);
+    mediaProgressFill.style.width = `${pct}%`;
+    const stage = job.stage === "transcoding"
+        ? "Re-encoding…"
+        : job.stage === "queued" ? "Queued…" : "Downloading…";
+    mediaProgressLabel.textContent = `${stage} ${pct}%`;
+    if (track) updateMediaNowCard(track);
+}
+
+function updateMediaBadge(s) {
+    const pending = (s.pending || []).length;
+    const playing = !mediaAudio.paused && !!mediaCurrentTrackId;
+    if (pending > 0) {
+        mediaBadge.hidden = false;
+        mediaBadge.textContent = String(pending);
+    } else if (playing) {
+        mediaBadge.hidden = false;
+        mediaBadge.innerHTML = "&#9835;";
+    } else {
+        mediaBadge.hidden = true;
+    }
+}
+
+// ── Playback controls ───────────────────────────────────────────────────────
+function updateMediaControls() {
+    const playing = !mediaAudio.paused && !!mediaCurrentTrackId;
+    playIcon.hidden = playing;
+    pauseIcon.hidden = !playing;
+    playPauseBtn.setAttribute("aria-label", playing ? "Pause" : "Play");
+    updateMediaBadge({ pending: [] });
+}
+
+function fmtTime(sec) {
+    if (!isFinite(sec) || sec < 0) return "0:00";
+    const s = Math.floor(sec % 60);
+    const m = Math.floor((sec / 60) % 60);
+    const h = Math.floor(sec / 3600);
+    return h ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
+}
+
+function updateSeekUI() {
+    if (!isFinite(mediaAudio.duration) || mediaAudio.duration <= 0) {
+        seekBar.value = 0;
+        mediaDurEl.textContent = "0:00";
+        mediaCurEl.textContent = fmtTime(mediaAudio.currentTime);
+        return;
+    }
+    seekBar.max = Math.floor(mediaAudio.duration);
+    seekBar.value = Math.floor(mediaAudio.currentTime);
+    mediaCurEl.textContent = fmtTime(mediaAudio.currentTime);
+    mediaDurEl.textContent = fmtTime(mediaAudio.duration);
+}
+
+playPauseBtn.addEventListener("click", () => {
+    if (!mediaCurrentTrackId || !mediaAudio.src) return;
+    if (mediaAudio.paused) {
+        mediaAudio.play().catch((e) => console.warn("play failed:", e));
+        mediaPost("/control", { action: "resume" }).catch(() => {});
+    } else {
+        mediaAudio.pause();
+        mediaPost("/control", { action: "pause" }).catch(() => {});
+    }
+});
+
+rewBtn.addEventListener("click", () => {
+    if (!mediaAudio.src) return;
+    mediaAudio.currentTime = Math.max(0, mediaAudio.currentTime - 10);
+    reportMediaPlayback(!mediaAudio.paused ? "playing" : "paused");
+});
+
+fwdBtn.addEventListener("click", () => {
+    if (!mediaAudio.src || !isFinite(mediaAudio.duration)) return;
+    mediaAudio.currentTime = Math.min(mediaAudio.duration - 0.5, mediaAudio.currentTime + 10);
+    reportMediaPlayback(!mediaAudio.paused ? "playing" : "paused");
+});
+
+stopMediaBtn.addEventListener("click", () => {
+    clearMediaAudio();
+    mediaPost("/control", { action: "stop" }).catch(() => {});
+    publishMediaState("stopped");
+});
+
+seekBar.addEventListener("change", () => {
+    if (!mediaAudio.src || !isFinite(mediaAudio.duration)) return;
+    mediaAudio.currentTime = Number(seekBar.value);
+    reportMediaPlayback(!mediaAudio.paused ? "playing" : "paused");
+});
+
+volumeBar.addEventListener("input", () => {
+    mediaAudio.volume = Number(volumeBar.value) / 100;
+    try { localStorage.setItem("media_volume", volumeBar.value); } catch (e) { /* ok */ }
+});
+mediaAudio.volume = Number(localStorage.getItem("media_volume") ?? 90) / 100;
+volumeBar.value = Math.round(mediaAudio.volume * 100);
+
+mediaAudio.addEventListener("play", () => {
+    updateMediaControls();
+    reportMediaPlayback("playing");
+    publishMediaState("playing");
+});
+mediaAudio.addEventListener("pause", () => {
+    updateMediaControls();
+    if (mediaCurrentTrackId) {
+        reportMediaPlayback("paused");
+        publishMediaState("paused");
+    }
+});
+mediaAudio.addEventListener("ended", () => {
+    updateMediaControls();
+    reportMediaPlayback("stopped");
+    publishMediaState("stopped");
+    mediaPost("/control", { action: "stop" }).catch(() => {});
+});
+mediaAudio.addEventListener("timeupdate", () => {
+    updateSeekUI();
+    const now = Date.now();
+    if (!mediaAudio.paused && now - mediaLastReport > 5000) {
+        mediaLastReport = now;
+        reportMediaPlayback("playing");
+    }
+});
+mediaAudio.addEventListener("durationchange", updateSeekUI);
+mediaAudio.addEventListener("error", () => {
+    if (mediaCurrentTrackId) {
+        mediaChannelEl.textContent = "Playback error — the track may still be preparing.";
+    }
+});
+
+// ── Search / choices / library ──────────────────────────────────────────────
+function fmtListDuration(sec) {
+    const s = Number(sec);
+    return isFinite(s) && s > 0 ? fmtTime(s) : "";
+}
+
+function mediaRowActions() {
+    const play = document.createElement("button");
+    play.className = "btn btn-secondary media-row-play";
+    play.type = "button";
+    play.textContent = "Play";
+    return play;
+}
+
+function renderMediaResults(results) {
+    mediaResultsEl.innerHTML = "";
+    if (!results || results.length === 0) {
+        mediaResultsEl.innerHTML = '<div class="media-empty">No results.</div>';
+        return;
+    }
+    for (const r of results) {
+        const row = document.createElement("div");
+        row.className = "media-row";
+        const info = document.createElement("div");
+        info.className = "media-row-info";
+        const dur = fmtListDuration(r.duration);
+        info.innerHTML = `<strong>${escapeHtml(r.title)}</strong>` +
+            `<span>${escapeHtml(r.channel || "")}${dur ? " · " + dur : ""}` +
+            `${r.in_library ? " · in library" : ""}</span>`;
+        const play = mediaRowActions();
+        play.addEventListener("click", () => playVideoId(r));
+        row.appendChild(info);
+        row.appendChild(play);
+        mediaResultsEl.appendChild(row);
+    }
+}
+
+async function playVideoId(r) {
+    try {
+        await mediaPost("/play", {
+            video_id: r.video_id,
+            title: r.title,
+            channel: r.channel || "",
+        });
+    } catch (e) {
+        mediaChannelEl.textContent = `Could not start: ${e.message}`;
+    }
+}
+
+mediaSearchForm.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const query = mediaSearchInput.value.trim();
+    if (!query) return;
+    mediaResultsEl.innerHTML = '<div class="media-empty">Searching YouTube Music…</div>';
+    try {
+        const data = await mediaPost("/search", { query, limit: 6 });
+        renderMediaResults(data.results);
+    } catch (e) {
+        mediaResultsEl.innerHTML = `<div class="media-empty">Search failed: ${escapeHtml(e.message)}</div>`;
+    }
+});
+
+function renderMediaChoices(choices) {
+    mediaChoicesWrap.hidden = choices.length === 0;
+    mediaChoicesEl.innerHTML = "";
+    for (const c of choices) {
+        const row = document.createElement("div");
+        row.className = "media-row media-choice";
+        const info = document.createElement("div");
+        info.className = "media-row-info";
+        const dur = fmtListDuration(c.duration);
+        info.innerHTML = `<strong>${escapeHtml(c.title)}</strong>` +
+            `<span>${escapeHtml(c.channel || "")}${dur ? " · " + dur : ""}</span>`;
+        const play = mediaRowActions();
+        play.addEventListener("click", () => playVideoId(c));
+        row.appendChild(info);
+        row.appendChild(play);
+        mediaChoicesEl.appendChild(row);
+    }
+}
+
+async function refreshLibrary() {
+    let data;
+    try {
+        data = await fetch("/media/api/library").then((r) => r.json());
+    } catch (e) {
+        return;
+    }
+    mediaLibraryEl.innerHTML = "";
+    const tracks = data.tracks || [];
+    if (tracks.length === 0) {
+        mediaLibraryEl.innerHTML = '<div class="media-empty">Downloaded songs and streams live here.</div>';
+        return;
+    }
+    for (const t of tracks) {
+        const row = document.createElement("div");
+        row.className = "media-row";
+        const info = document.createElement("div");
+        info.className = "media-row-info";
+        const dur = fmtListDuration(t.duration);
+        const statusTag = t.status === "ready" ? "" : ` · ${t.status}`;
+        info.innerHTML = `<strong>${escapeHtml(t.title)}</strong>` +
+            `<span>${escapeHtml(t.channel || (t.kind === "stream" ? "Live stream" : ""))}` +
+            `${dur ? " · " + dur : ""}${statusTag}</span>`;
+        const play = mediaRowActions();
+        play.disabled = t.status !== "ready";
+        play.addEventListener("click", () => {
+            mediaPost("/play", { track_id: t.id }).catch((e) => {
+                mediaChannelEl.textContent = `Could not play: ${e.message}`;
+            });
+        });
+        const del = document.createElement("button");
+        del.className = "btn btn-icon media-row-delete";
+        del.type = "button";
+        del.setAttribute("aria-label", `Remove ${t.title}`);
+        del.title = "Remove from library";
+        del.innerHTML = '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"></path></svg>';
+        del.addEventListener("click", async () => {
+            try {
+                await fetch(`/media/api/tracks/${encodeURIComponent(t.id)}`, { method: "DELETE" });
+                if (t.id === mediaCurrentTrackId) clearMediaAudio();
+                refreshLibrary();
+            } catch (e) { /* leave the row; next refresh decides */ }
+        });
+        row.appendChild(info);
+        row.appendChild(play);
+        row.appendChild(del);
+        mediaLibraryEl.appendChild(row);
+    }
+}
+
+streamForm.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const name = streamNameInput.value.trim() || streamUrlInput.value.trim();
+    const url = streamUrlInput.value.trim();
+    if (!url) return;
+    try {
+        await mediaPost("/streams", { name, url });
+        streamNameInput.value = "";
+        streamUrlInput.value = "";
+        refreshLibrary();
+    } catch (e) {
+        mediaChannelEl.textContent = `Could not add stream: ${e.message}`;
+    }
+});
+
+// ── Panel open/close ────────────────────────────────────────────────────────
+function setMediaOpen(open) {
+    mediaPanel.classList.toggle("open", open);
+    mediaBtn.setAttribute("aria-expanded", String(open));
+    if (open) {
+        refreshLibrary();
+        pollMediaState();
+    }
+}
+
+mediaBtn.setAttribute("aria-expanded", "false");
+mediaBtn.addEventListener("click", () => setMediaOpen(!mediaPanel.classList.contains("open")));
+closeMediaBtn.addEventListener("click", () => setMediaOpen(false));
+
+startMediaPolling();
+updateMediaControls();

web/index.html

@@ -42,6 +42,11 @@
                     <span>Tasks</span>
                     <span class="tasks-badge" id="tasksBadge" hidden>0</span>
                 </button>
+                <button id="mediaBtn" class="btn btn-secondary tasks-trigger" aria-label="Music player" title="Music player">
+                    <svg viewBox="0 0 24 24" width="17" height="17" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 18V5l12-2v13"></path><circle cx="6" cy="18" r="3"></circle><circle cx="18" cy="16" r="3"></circle></svg>
+                    <span>Music</span>
+                    <span class="tasks-badge" id="mediaBadge" hidden>&#9835;</span>
+                </button>
             </div>
         </header>
 
@@ -149,6 +154,85 @@
         </div>
     </div>
 
+    <div class="tasks-panel media-panel" id="mediaPanel" aria-label="Music player">
+        <div class="tasks-header">
+            <div>
+                <h2>Music</h2>
+                <p>YouTube Music downloads and live streams, streamed to you.</p>
+            </div>
+            <button id="closeMediaBtn" class="btn btn-icon" aria-label="Close music player">
+                <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"></path></svg>
+            </button>
+        </div>
+
+        <div class="media-now">
+            <img id="mediaArt" class="media-art" alt="" hidden>
+            <div class="media-art-placeholder" id="mediaArtPlaceholder" aria-hidden="true">
+                <svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M9 18V5l12-2v13"></path><circle cx="6" cy="18" r="3"></circle><circle cx="18" cy="16" r="3"></circle></svg>
+            </div>
+            <div class="media-now-info">
+                <strong id="mediaTitle">Nothing loaded</strong>
+                <span id="mediaChannel"></span>
+                <div class="media-progress" id="mediaProgressWrap" hidden>
+                    <div class="media-progress-fill" id="mediaProgressFill"></div>
+                    <span class="media-progress-label" id="mediaProgressLabel">Fetching&hellip;</span>
+                </div>
+            </div>
+        </div>
+
+        <div class="media-controls" role="group" aria-label="Playback controls">
+            <button id="rewBtn" class="btn btn-icon" aria-label="Back 10 seconds" title="Back 10s">
+                <svg viewBox="0 0 24 24" width="19" height="19" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11 17a5 5 0 1 0-5-5"></path><path d="M11 17H6v-5"></path><path d="m19 5-4 4h-3"></path><path d="m15 9 4-4"></path></svg>
+            </button>
+            <button id="playPauseBtn" class="btn btn-icon media-play" aria-label="Play or pause" title="Play / pause">
+                <svg id="playIcon" viewBox="0 0 24 24" width="22" height="22" fill="currentColor" aria-hidden="true"><path d="M8 5v14l11-7Z"></path></svg>
+                <svg id="pauseIcon" viewBox="0 0 24 24" width="22" height="22" fill="currentColor" aria-hidden="true" hidden><path d="M7 5h4v14H7zM13 5h4v14h-4z"></path></svg>
+            </button>
+            <button id="fwdBtn" class="btn btn-icon" aria-label="Forward 10 seconds" title="Forward 10s">
+                <svg viewBox="0 0 24 24" width="19" height="19" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M13 17a5 5 0 1 1 5-5"></path><path d="M13 17h5v-5"></path><path d="m5 5 4 4h3"></path><path d="m9 9 4-4"></path></svg>
+            </button>
+            <button id="stopMediaBtn" class="btn btn-icon" aria-label="Stop" title="Stop">
+                <svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor" aria-hidden="true"><rect x="6" y="6" width="12" height="12" rx="2"></rect></svg>
+            </button>
+        </div>
+
+        <div class="media-seek">
+            <span class="media-time" id="mediaCur">0:00</span>
+            <input type="range" id="seekBar" min="0" max="1000" value="0" step="1" aria-label="Seek position">
+            <span class="media-time" id="mediaDur">0:00</span>
+        </div>
+        <div class="media-volume">
+            <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11 5 6 9H2v6h4l5 4V5Z"></path><path d="M15.5 8.5a5 5 0 0 1 0 7"></path></svg>
+            <input type="range" id="volumeBar" min="0" max="100" value="90" aria-label="Volume">
+        </div>
+
+        <h3 class="sheet-section-title">Search YouTube Music</h3>
+        <form class="media-search" id="mediaSearchForm">
+            <input id="mediaSearchInput" type="search" placeholder="Song, artist, lyrics&hellip;" autocomplete="off">
+            <button class="btn btn-secondary" type="submit">Find</button>
+        </form>
+        <div class="media-list" id="mediaResults"></div>
+
+        <div id="mediaChoicesWrap" hidden>
+            <h3 class="sheet-section-title">Hope&rsquo;s suggestions</h3>
+            <div class="media-list" id="mediaChoices"></div>
+        </div>
+
+        <h3 class="sheet-section-title">Library</h3>
+        <div class="media-list" id="mediaLibrary">
+            <div class="media-empty">Downloaded songs and streams live here.</div>
+        </div>
+
+        <h3 class="sheet-section-title">Add live stream</h3>
+        <form class="media-search media-stream-form" id="streamForm">
+            <input id="streamName" type="text" placeholder="Station name" autocomplete="off">
+            <input id="streamUrl" type="url" placeholder="https://&hellip; audio stream URL" required>
+            <button class="btn btn-secondary" type="submit">Add</button>
+        </form>
+    </div>
+
+    <audio id="mediaAudio" preload="metadata"></audio>
+
     <script src="livekit-client.umd.js"></script>
     <script src="app.js"></script>
 </body>

web/media_server.py

@@ -0,0 +1,619 @@
+#!/usr/bin/env python3
+"""Media server for the Hope voice assistant.
+
+A small FastAPI service that owns the permanent music library and player
+coordination:
+
+- Library: downloaded YouTube Music tracks (mp3, transcoded via yt-dlp +
+  ffmpeg) and user-added live audio stream URLs, persisted in library.json.
+- Search: yt-dlp ``ytsearch`` (YouTube Music pages share video ids), used by
+  Hope's media MCP toolset and by the web UI search box.
+- Download jobs: one-at-a-time worker thread; progress is parsed from
+  yt-dlp stdout and surfaced through GET /media/api/state.
+- Player state: per-room desired state (loaded track, playing/paused/stopped,
+  seek hints). The browser is the actual player and reconciles against this;
+  it reports real playback state back so Hope's voice tools can answer
+  "what's playing".
+
+Security posture matches the token server: bind 127.0.0.1 only, reachability
+exclusively through the nginx HTTPS proxy (/media/api/). File bytes for
+downloaded tracks are served as nginx static files (/media/files/, native
+HTTP Range support for seeking); this service only proxies external stream
+URLs (mixed-content: an http:// radio URL would be blocked by the browser,
+so it is fetched server-side and re-served over HTTPS).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+
+import httpx
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, RedirectResponse, StreamingResponse
+
+MEDIA_DIR = Path(os.environ.get("MEDIA_DIR", "/data/media"))
+FILES_DIR = MEDIA_DIR / "files"
+THUMBS_DIR = MEDIA_DIR / "thumbs"
+JOBS_DIR = MEDIA_DIR / "jobs"
+LIBRARY_FILE = MEDIA_DIR / "library.json"
+COOKIES_FILE = os.environ.get("YTDLP_COOKIES", "")
+MEDIA_HOST = os.environ.get("MEDIA_SERVER_HOST", "127.0.0.1")
+MEDIA_PORT = int(os.environ.get("MEDIA_SERVER_PORT", "8092"))
+
+DOWNLOAD_TIMEOUT = int(os.environ.get("MEDIA_DOWNLOAD_TIMEOUT", "600"))
+SEARCH_TIMEOUT = int(os.environ.get("MEDIA_SEARCH_TIMEOUT", "45"))
+
+app = FastAPI(title="hope-media", docs_url=None, redoc_url=None, openapi_url=None)
+
+_lock = threading.Lock()          # guards library + rooms below
+_library: dict[str, Any] = {"tracks": {}, "version": 1}
+_rooms: dict[str, dict[str, Any]] = {}
+_jobs: dict[str, dict[str, Any]] = {}
+_executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="media-dl")
+
+for _d in (FILES_DIR, THUMBS_DIR, JOBS_DIR):
+    _d.mkdir(parents=True, exist_ok=True)
+
+
+# ── Library store ───────────────────────────────────────────────────────────
+
+def _load_library() -> None:
+    if LIBRARY_FILE.exists():
+        try:
+            data = json.loads(LIBRARY_FILE.read_text(encoding="utf-8"))
+            tracks = data.get("tracks", {})
+            if isinstance(tracks, dict):
+                _library["tracks"] = tracks
+                _library["version"] = int(data.get("version", 1))
+        except (json.JSONDecodeError, OSError):
+            # Corrupt library: keep the broken file aside, start fresh.
+            try:
+                LIBRARY_FILE.replace(LIBRARY_FILE.with_suffix(".json.broken"))
+            except OSError:
+                pass
+
+
+def _save_library() -> None:
+    tmp = LIBRARY_FILE.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(_library), encoding="utf-8")
+    tmp.replace(LIBRARY_FILE)
+
+
+def _bump_version() -> int:
+    _library["version"] = int(_library.get("version", 1)) + 1
+    return _library["version"]
+
+
+def _track_dict(track: dict) -> dict:
+    out = dict(track)
+    if track["kind"] == "youtube":
+        if track.get("status") == "ready":
+            out["audio_url"] = f"/media/files/{track['id']}.mp3"
+        out["art_url"] = (
+            f"/media/thumbs/{track['id']}.jpg"
+            if (THUMBS_DIR / f"{track['id']}.jpg").exists()
+            else None
+        )
+    else:
+        out["audio_url"] = f"/media/api/stream/{track['id']}"
+    return out
+
+
+def _get_track(track_id: str) -> dict | None:
+    return _library["tracks"].get(track_id)
+
+
+def _upsert_track(track: dict) -> None:
+    _library["tracks"][track["id"]] = track
+    _bump_version()
+    _save_library()
+
+
+_load_library()
+
+
+# ── Player state (per room) ─────────────────────────────────────────────────
+
+def _room_state(room: str) -> dict:
+    return _rooms.setdefault(
+        room,
+        {"track_id": None, "desired": "stopped", "reported": None,
+         "seek_hint": None, "choices": []},
+    )
+
+
+def _room_snapshot(room: str) -> dict:
+    st = _room_state(room)
+    track = _get_track(st["track_id"]) if st["track_id"] else None
+    pending = [
+        {
+            "job_id": j["id"],
+            "track_id": j["track_id"],
+            "stage": j["stage"],
+            "progress": j["progress"],
+            "error": j.get("error"),
+        }
+        for j in _jobs.values()
+        if j["stage"] in ("queued", "downloading", "transcoding")
+    ]
+    return {
+        "room": room,
+        "track": _track_dict(track) if track else None,
+        "desired": st["desired"],
+        "reported": st["reported"],
+        "seek_hint": st["seek_hint"],
+        "choices": st["choices"],
+        "pending": pending,
+        "version": _library["version"],
+    }
+
+
+# ── yt-dlp helpers ──────────────────────────────────────────────────────────
+
+def _ytdlp_base_args() -> list[str]:
+    args = [sys.executable, "-m", "yt_dlp", "--no-playlist", "--no-warnings"]
+    if COOKIES_FILE and Path(COOKIES_FILE).exists():
+        args += ["--cookies", COOKIES_FILE]
+    return args
+
+
+_PROGRESS_RE = re.compile(r"\[download\]\s+([\d.]+)%")
+
+
+def _run_search(query: str, limit: int) -> list[dict]:
+    """Flat ytsearch lookup — cheap, no download, works anonymously."""
+    cmd = _ytdlp_base_args() + [
+        "--flat-playlist", "--dump-json",
+        f"ytsearch{limit}:{query}",
+    ]
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=SEARCH_TIMEOUT, check=False
+        )
+    except subprocess.TimeoutExpired:
+        raise HTTPException(504, "YouTube Music search timed out")
+    if proc.returncode != 0 and not proc.stdout.strip():
+        detail = (proc.stderr or "").strip().splitlines()[-1:] or ["unknown error"]
+        raise HTTPException(502, f"Search failed: {detail[0][:300]}")
+    results = []
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        video_id = entry.get("id")
+        if not video_id:
+            continue
+        existing = _get_track(video_id)
+        results.append({
+            "video_id": video_id,
+            "title": entry.get("title") or video_id,
+            "channel": entry.get("uploader") or entry.get("channel") or "",
+            "duration": entry.get("duration"),
+            "view_count": entry.get("view_count"),
+            "in_library": bool(existing),
+            "track_id": existing["id"] if existing else None,
+            "library_status": existing["status"] if existing else None,
+        })
+    return results
+
+
+def _job_dict(job: dict) -> dict:
+    return {k: job.get(k) for k in
+            ("id", "track_id", "stage", "progress", "error", "started_at")}
+
+
+def _persist_job(job: dict) -> None:
+    try:
+        (JOBS_DIR / f"{job['id']}.json").write_text(
+            json.dumps(_job_dict(job)), encoding="utf-8"
+        )
+    except OSError:
+        pass
+
+
+def _fail_job(job: dict, track: dict, message: str) -> None:
+    job["stage"] = "error"
+    job["error"] = message[:500]
+    _persist_job(job)
+    with _lock:
+        track["status"] = "failed"
+        track["error"] = message[:500]
+        _bump_version()
+        _save_library()
+
+
+def _download_worker(job: dict, track: dict, video_id: str) -> None:
+    """Runs in the single-worker executor: yt-dlp download + mp3 transcode."""
+    target = FILES_DIR / f"{track['id']}.mp3"
+    cmd = _ytdlp_base_args() + [
+        "-f", "bestaudio/best",
+        "-x", "--audio-format", "mp3", "--audio-quality", "192K",
+        "--embed-thumbnail", "--add-metadata",
+        "--write-thumbnail", "--convert-thumbnails", "jpg",
+        "--newline", "--progress",
+        "--print-json",
+        "--retries", "3", "--fragment-retries", "3",
+        "-P", str(FILES_DIR),
+        "-o", f"{track['id']}.%(ext)s",
+        f"https://www.youtube.com/watch?v={video_id}",
+    ]
+    job["stage"] = "downloading"
+    info: dict = {}
+    try:
+        proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, errors="replace",
+        )
+        deadline = time.monotonic() + DOWNLOAD_TIMEOUT
+        assert proc.stdout is not None and proc.stderr is not None
+        for line in proc.stdout:
+            if time.monotonic() > deadline:
+                proc.kill()
+                raise RuntimeError(f"Download exceeded {DOWNLOAD_TIMEOUT}s")
+            line = line.strip()
+            m = _PROGRESS_RE.search(line)
+            if m:
+                job["progress"] = min(85.0, float(m.group(1)) * 0.85)
+                _persist_job(job)
+            elif line.startswith(("[ExtractAudio]", "[Metadata]", "[EmbedThumbnail]")):
+                job["stage"] = "transcoding"
+                job["progress"] = max(job["progress"], 86.0)
+                _persist_job(job)
+            elif line.startswith("{"):
+                try:
+                    info = json.loads(line)
+                except json.JSONDecodeError:
+                    pass
+        proc.wait(timeout=30)
+        if proc.returncode != 0:
+            stderr_tail = (proc.stderr.read() or "").strip().splitlines()
+            detail = stderr_tail[-1] if stderr_tail else f"exit code {proc.returncode}"
+            raise RuntimeError(detail)
+        if not target.exists():
+            raise RuntimeError("yt-dlp finished but no mp3 was produced")
+    except Exception as exc:  # noqa: BLE001 — any failure marks the track failed
+        _fail_job(job, track, str(exc))
+        return
+
+    thumb_src = FILES_DIR / f"{track['id']}.jpg"
+    try:
+        if thumb_src.exists():
+            thumb_src.replace(THUMBS_DIR / f"{track['id']}.jpg")
+    except OSError:
+        pass
+
+    job["stage"] = "ready"
+    job["progress"] = 100.0
+    _persist_job(job)
+    with _lock:
+        track["status"] = "ready"
+        track["error"] = None
+        if info:
+            if info.get("title"):
+                track["title"] = info["title"]
+            if info.get("uploader") or info.get("channel"):
+                track["channel"] = info.get("uploader") or info.get("channel")
+            if info.get("duration"):
+                track["duration"] = round(float(info["duration"]))
+        _bump_version()
+        _save_library()
+
+
+def _start_download(track: dict, video_id: str) -> dict:
+    job = {
+        "id": uuid.uuid4().hex[:12],
+        "track_id": track["id"],
+        "stage": "queued",
+        "progress": 0.0,
+        "error": None,
+        "started_at": time.time(),
+    }
+    _jobs[job["id"]] = job
+    _persist_job(job)
+    _executor.submit(_download_worker, job, track, video_id)
+    return job
+
+
+# ── API: health, library ────────────────────────────────────────────────────
+
+@app.get("/media/api/healthz")
+def healthz() -> dict:
+    return {"ok": True, "version": _library["version"]}
+
+
+@app.get("/media/api/library")
+def get_library() -> dict:
+    with _lock:
+        tracks = sorted(
+            (_track_dict(t) for t in _library["tracks"].values()),
+            key=lambda t: t.get("added_at", 0),
+            reverse=True,
+        )
+        return {"tracks": tracks, "version": _library["version"]}
+
+
+def _delete_track_files(track: dict) -> None:
+    if track["kind"] != "youtube":
+        return
+    for path in (
+        FILES_DIR / f"{track['id']}.mp3",
+        FILES_DIR / f"{track['id']}.jpg",
+        THUMBS_DIR / f"{track['id']}.jpg",
+    ):
+        try:
+            path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+@app.delete("/media/api/tracks/{track_id}")
+def delete_track(track_id: str) -> dict:
+    with _lock:
+        track = _get_track(track_id)
+        if not track:
+            raise HTTPException(404, "unknown track")
+        del _library["tracks"][track_id]
+        _bump_version()
+        _save_library()
+        for room, st in _rooms.items():
+            if st["track_id"] == track_id:
+                st["track_id"] = None
+                st["desired"] = "stopped"
+    _delete_track_files(track)
+    return {"ok": True}
+
+
+# ── API: search + play + control ────────────────────────────────────────────
+
+@app.post("/media/api/search")
+async def search(request: Request) -> dict:
+    body = await request.json()
+    query = str(body.get("query", "")).strip()
+    if not query:
+        raise HTTPException(400, "query is required")
+    limit = max(1, min(int(body.get("limit", 6)), 15))
+    return {"query": query, "results": _run_search(query, limit)}
+
+
+def _resolve_play_target(body: dict) -> dict:
+    """Find or create the track a play request refers to.
+
+    Accepts video_id (YouTube), track_id (existing library entry) or a raw
+    url+name (live stream). Returns the library track dict.
+    """
+    video_id = str(body.get("video_id") or "").strip()
+    track_id = str(body.get("track_id") or "").strip()
+    url = str(body.get("url") or "").strip()
+
+    if video_id:
+        existing = _get_track(video_id)
+        if existing:
+            return existing
+        track = {
+            "id": video_id,
+            "kind": "youtube",
+            "video_id": video_id,
+            "title": str(body.get("title") or video_id),
+            "channel": str(body.get("channel") or ""),
+            "duration": body.get("duration"),
+            "status": "downloading",
+            "error": None,
+            "added_at": time.time(),
+        }
+        _upsert_track(track)
+        _start_download(track, video_id)
+        return track
+
+    if track_id:
+        track = _get_track(track_id)
+        if not track:
+            raise HTTPException(404, "unknown track")
+        return track
+
+    if url:
+        if not re.match(r"^https?://", url):
+            raise HTTPException(400, "url must be http(s)")
+        track_id = "s" + uuid.uuid4().hex[:10]
+        track = {
+            "id": track_id,
+            "kind": "stream",
+            "video_id": None,
+            "title": str(body.get("name") or url),
+            "channel": str(body.get("channel") or ""),
+            "duration": None,
+            "status": "ready",
+            "error": None,
+            "url": url,
+            "added_at": time.time(),
+        }
+        _upsert_track(track)
+        return track
+
+    raise HTTPException(400, "one of video_id, track_id or url is required")
+
+
+@app.post("/media/api/play")
+async def play(request: Request) -> dict:
+    body = await request.json()
+    room = str(body.get("room") or "default")
+    track = _resolve_play_target(body)
+    with _lock:
+        st = _room_state(room)
+        st["track_id"] = track["id"]
+        # start_paused carries a track into a new scope without starting it —
+        # the UI uses this when a conversation begins (talking pauses music).
+        st["desired"] = "paused" if body.get("start_paused") else "playing"
+        st["choices"] = []  # a pick resolves any open suggestion list
+        st["seek_hint"] = None
+        snapshot = _room_snapshot(room)
+    return {"ok": True, **snapshot}
+
+
+@app.post("/media/api/control")
+async def control(request: Request) -> dict:
+    body = await request.json()
+    room = str(body.get("room") or "default")
+    action = str(body.get("action") or "")
+    with _lock:
+        st = _room_state(room)
+        if action == "pause":
+            st["desired"] = "paused"
+        elif action == "resume":
+            if not st["track_id"]:
+                raise HTTPException(409, "nothing loaded")
+            st["desired"] = "playing"
+        elif action == "stop":
+            st["desired"] = "stopped"
+        elif action == "seek":
+            st["seek_hint"] = {
+                "position": max(0.0, float(body.get("position", 0))),
+                "ts": time.time(),
+            }
+        elif action == "skip":
+            current = st["track_id"]
+            candidates = sorted(
+                (
+                    t for t in _library["tracks"].values()
+                    if t.get("status") == "ready" and t["id"] != current
+                ),
+                key=lambda t: t.get("added_at", 0),
+                reverse=True,
+            )
+            if candidates:
+                st["track_id"] = candidates[0]["id"]
+                st["desired"] = "playing"
+                st["seek_hint"] = None
+            else:
+                st["desired"] = "stopped"
+        else:
+            raise HTTPException(400, f"unknown action: {action}")
+        snapshot = _room_snapshot(room)
+    return {"ok": True, **snapshot}
+
+
+@app.post("/media/api/choices")
+async def choices(request: Request) -> dict:
+    """Publish Hope's song suggestions so the UI can render clickable picks."""
+    body = await request.json()
+    room = str(body.get("room") or "default")
+    raw = body.get("choices") or []
+    cleaned = []
+    for c in raw[:5]:
+        if not isinstance(c, dict) or not c.get("video_id"):
+            continue
+        cleaned.append({
+            "video_id": str(c["video_id"]),
+            "title": str(c.get("title") or c["video_id"]),
+            "channel": str(c.get("channel") or ""),
+            "duration": c.get("duration"),
+        })
+    with _lock:
+        _room_state(room)["choices"] = cleaned
+    return {"ok": True, "choices": cleaned}
+
+
+@app.get("/media/api/state")
+def state(room: str = "default") -> dict:
+    with _lock:
+        return _room_snapshot(room)
+
+
+@app.post("/media/api/report")
+async def report(request: Request) -> dict:
+    """The browser reports real playback state (source of truth for the player)."""
+    body = await request.json()
+    room = str(body.get("room") or "default")
+    with _lock:
+        st = _room_state(room)
+        st["reported"] = {
+            "track_id": body.get("track_id"),
+            "state": str(body.get("state") or "stopped"),
+            "position": float(body.get("position") or 0.0),
+            "duration": body.get("duration"),
+            "ts": time.time(),
+        }
+    return {"ok": True}
+
+
+@app.post("/media/api/streams")
+async def add_stream(request: Request) -> dict:
+    body = await request.json()
+    track = _resolve_play_target({"url": body.get("url"), "name": body.get("name")})
+    return {"ok": True, "track": _track_dict(track)}
+
+
+# ── API: stream proxy (external http(s) audio over same-origin HTTPS) ───────
+
+_HOP_HEADERS = ("content-type", "content-range", "accept-ranges", "content-length")
+
+
+@app.get("/media/api/stream/{track_id}")
+async def stream_proxy(track_id: str, request: Request):
+    with _lock:
+        track = _get_track(track_id)
+    if not track:
+        raise HTTPException(404, "unknown track")
+    if track["kind"] == "youtube":
+        # Downloaded tracks are nginx static files (native Range support).
+        if track.get("status") == "ready":
+            return RedirectResponse(f"/media/files/{track_id}.mp3")
+        raise HTTPException(409, f"track is {track.get('status')}, not ready")
+
+    range_header = request.headers.get("range")
+    headers = {"Range": range_header} if range_header else {"Range": "bytes=0-"}
+    client = httpx.AsyncClient(timeout=httpx.Timeout(30, read=600), follow_redirects=True)
+    try:
+        upstream = await client.send(client.build_request("GET", track["url"], headers=headers), stream=True)
+    except httpx.HTTPError as exc:
+        await client.aclose()
+        raise HTTPException(502, f"upstream stream failed: {exc}")
+
+    if upstream.status_code >= 400:
+        await upstream.aclose()
+        await client.aclose()
+        raise HTTPException(502, f"upstream returned {upstream.status_code}")
+
+    out_headers = {
+        name: value
+        for name, value in upstream.headers.items()
+        if name.lower() in _HOP_HEADERS
+    }
+    media_type = upstream.headers.get("content-type", "audio/mpeg")
+
+    async def relay():
+        try:
+            async for chunk in upstream.aiter_bytes(64 * 1024):
+                yield chunk
+        finally:
+            await upstream.aclose()
+            await client.aclose()
+
+    return StreamingResponse(
+        relay(),
+        status_code=upstream.status_code,
+        media_type=media_type,
+        headers=out_headers,
+    )
+
+
+@app.exception_handler(HTTPException)
+async def http_error(_request: Request, exc: HTTPException):
+    return JSONResponse({"error": exc.detail}, status_code=exc.status_code)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host=MEDIA_HOST, port=MEDIA_PORT, log_level="info")

web/style.css

@@ -1245,6 +1245,263 @@ body[data-mode="text"] .mic-meter {
 .task-result { margin-top: 0.5rem; color: #bcebd8; background: rgba(118, 217, 178, 0.1); }
 .task-error { margin-top: 0.5rem; color: #ffc2ba; background: rgba(255, 128, 111, 0.1); }
 
+/* ── Media player ───────────────────────────────────────────────────────── */
+/* Reuses .tasks-panel positioning (fixed right, slides in via .open); the
+   content scrolls under a sticky header. */
+.media-panel {
+    overflow-y: auto;
+    padding-bottom: 1.2rem;
+}
+
+.media-panel .tasks-header {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: #0d1929;
+}
+
+.media-now {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin: 1rem 1.1rem 0;
+    padding: 0.75rem;
+    border-radius: 12px;
+    background: var(--surface-raised);
+}
+
+.media-art,
+.media-art-placeholder {
+    width: 56px;
+    height: 56px;
+    flex: 0 0 56px;
+    border-radius: 8px;
+    object-fit: cover;
+    background: rgba(23, 41, 65, 0.7);
+}
+
+.media-art-placeholder {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--ink-muted);
+}
+
+.media-now-info {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+}
+
+.media-now-info strong {
+    color: var(--ink);
+    font-size: 0.88rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.media-now-info span {
+    color: var(--ink-muted);
+    font-size: 0.72rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.media-progress {
+    position: relative;
+    margin-top: 0.35rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+
+/* Track bar behind the fill (fill width is driven inline by progress). */
+.media-progress::before {
+    content: "";
+    position: absolute;
+    left: 0;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 90px;
+    height: 4px;
+    border-radius: 2px;
+    background: rgba(139, 167, 255, 0.18);
+}
+
+.media-progress-fill {
+    height: 4px;
+    flex: 0 0 auto;
+    width: 0;
+    border-radius: 2px;
+    background: var(--iris);
+    transition: width 400ms ease;
+}
+
+.media-progress-label {
+    color: var(--ink-muted);
+    font-size: 0.66rem;
+    white-space: nowrap;
+}
+
+.media-controls {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.9rem;
+    margin: 0.9rem 1.1rem 0;
+}
+
+.media-controls .btn-icon {
+    color: var(--ink-soft);
+}
+
+.media-play {
+    width: 52px;
+    height: 52px;
+    border-radius: 50%;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: #0b1523 !important;
+    background: var(--iris) !important;
+    border: none;
+}
+
+.media-play:hover:not(:disabled) {
+    filter: brightness(1.1);
+}
+
+.media-seek {
+    display: flex;
+    align-items: center;
+    gap: 0.55rem;
+    margin: 0.75rem 1.1rem 0;
+}
+
+.media-time {
+    color: var(--ink-muted);
+    font-size: 0.68rem;
+    font-variant-numeric: tabular-nums;
+    min-width: 2.6rem;
+    text-align: center;
+}
+
+.media-seek input[type="range"],
+.media-volume input[type="range"] {
+    flex: 1;
+    accent-color: var(--iris);
+    cursor: pointer;
+}
+
+.media-volume {
+    display: flex;
+    align-items: center;
+    gap: 0.55rem;
+    margin: 0.55rem 1.1rem 0;
+    color: var(--ink-muted);
+}
+
+.media-search {
+    display: flex;
+    gap: 0.45rem;
+    margin: 0 1.1rem;
+}
+
+.media-search input {
+    flex: 1;
+    min-width: 0;
+    padding: 0.5rem 0.7rem;
+    border: 1px solid var(--line-strong);
+    border-radius: 9px;
+    color: var(--ink);
+    background: rgba(5, 11, 20, 0.45);
+    font-size: 0.8rem;
+}
+
+.media-search input::placeholder {
+    color: var(--ink-muted);
+}
+
+.media-stream-form input:first-child {
+    flex: 0 0 38%;
+}
+
+.media-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+    margin: 0.65rem 1.1rem 1rem;
+    max-height: 240px;
+    overflow-y: auto;
+}
+
+.media-row {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.55rem 0.65rem;
+    border-radius: 9px;
+    background: var(--surface-raised);
+}
+
+.media-row-info {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.1rem;
+}
+
+.media-row-info strong {
+    color: var(--ink);
+    font-size: 0.78rem;
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.media-row-info span {
+    color: var(--ink-muted);
+    font-size: 0.68rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.media-row-play {
+    flex: 0 0 auto;
+    padding: 0.3rem 0.7rem;
+    font-size: 0.7rem;
+}
+
+.media-row-delete {
+    flex: 0 0 auto;
+    color: var(--ink-muted);
+}
+
+.media-row-delete:hover {
+    color: #ffc2ba;
+}
+
+.media-empty {
+    padding: 0.8rem;
+    border-radius: 9px;
+    color: var(--ink-muted);
+    background: var(--surface-raised);
+    font-size: 0.74rem;
+    text-align: center;
+}
+
+.media-choice {
+    border: 1px solid rgba(139, 167, 255, 0.35);
+    background: rgba(60, 95, 201, 0.12);
+}
+
 /* ── Responsive ─────────────────────────────────────────────────────────── */
 @media (max-height: 760px) and (min-width: 881px) {
     .workspace {
@@ -1386,7 +1643,8 @@ body[data-mode="text"] .mic-meter {
         padding: 1.25rem 1rem;
     }
 
-    .tasks-panel {
+    .tasks-panel,
+    .media-panel {
         width: 100vw;
     }
 

web/token_server.py

@@ -97,6 +97,9 @@ class Handler(BaseHTTPRequestHandler):
         resp = json.dumps(
             {
                 "token": token,
+                # The room name scopes media-server player state; the UI sends
+                # it with every /media/api/ call.
+                "room": room_name,
                 "user": {
                     "id": user_id,
                     "display_name": profile.get("display_name") or user_id,