diff --git a/20260313_Fixes (Copilot).md b/20260313_Fixes (Copilot).md
index 5b8c0fa..fe974f8 100644
--- a/20260313_Fixes (Copilot).md
+++ b/20260313_Fixes (Copilot).md
@@ -2885,6 +2885,496 @@ Validation:
- frontend diagnostics: clean
- frontend typecheck: `EXIT:0`
+---
+
+### 2026-03-18 implementation (contrast-safe dynamic lyric palettes)
+
+Requested:
+- Ensure generated dynamic palettes maintain high contrast against the dynamic background, with background anchored as the darkest layer.
+
+Scope:
+- `frontend/src/components/LyricsLivePreview.tsx`
+
+#### Implemented
+
+1) WCAG-style contrast helpers added
+- Added luminance + contrast-ratio utilities and `ensureReadableColor()`.
+- Dynamic text/accent colors are now auto-adjusted to satisfy contrast targets against the active dynamic background:
+ - text target: `>= 7.0`
+ - highlight/word/speaker targets: `>= 4.5`
+
+2) Darkest-background anchoring
+- Added `normalizeDynamicBackground()` so extracted artwork color is forced into a dark luminance envelope.
+- This guarantees background stays the darkest visual layer while preserving hue identity.
+
+3) Contrast-safe dynamic gradient
+- Added `buildDynamicBackgroundGradient()` to build top/bottom gradient stops from the dark anchored background while keeping both stops in a low-luminance range.
+
+4) Contrast-safe dynamic accents and speaker palette
+- `buildHighContrastSpeakerPalette()` now accepts background context and post-adjusts each generated color via `ensureReadableColor()`.
+- Added dynamic theme derivation (`dynamicTheme`) for:
+ - `textColor`
+ - `highlightColor`
+ - `wordHighlight`
+ - `speakerPalette`
+- Preview/canvas now consumes these effective dynamic colors when dynamic background mode is enabled.
+
+5) UX hint in style panel
+- Added a small note under dynamic background controls to clarify that dynamic mode auto-adjusts lyric colors for readability.
+
+Validation:
+- frontend typecheck: `EXIT:0`
+
+---
+
+### 2026-03-18 plan (speaker color ≠ base text + Pop mode rendering correctness)
+
+Requested:
+- Dynamic speaker colors must never match base text color (fill becomes invisible when they match).
+- `Pop` mode text rendering is currently incorrect.
+
+Scope:
+- `frontend/src/components/LyricsLivePreview.tsx`
+
+#### Root cause analysis
+
+1) Speaker/fill invisibility risk
+- Current active color selection is `speakerColorValue ?? style.wordHighlight` while base color is `style.textColor`.
+- There is no explicit “distinctness guard” between speaker color and base text color.
+- In fill mode, if active and base resolve to the same (or near-same) color, the gradient transition is visually lost.
+
+2) Pop mode rendering mismatch
+- `Pop` path currently reuses per-word color progression driven by fill fraction (`frac > 0`) rather than strict active-word state.
+- This can make past words look permanently highlighted and can produce incorrect visual state compared to intended “active word pops; inactive words stay dim/base”.
+
+#### Plan
+
+1) Add color distinctness utility for speaker/active colors
+- Introduce `ensureDistinctColor(active, base, minRatio, minDeltaE-ish)` helper in preview color utilities.
+- Enforce both:
+ - minimum contrast against background (existing/contrast helpers)
+ - minimum separation from base text color (new guard)
+- Use this in:
+ - dynamic speaker palette generation
+ - runtime speaker fallback path (`getSpeakerColor()` effective output)
+
+2) Define explicit Pop-mode color semantics
+- Pop mode should use state-driven coloring, not fill-progress coloring:
+ - active word: speaker/active color
+ - completed words: configurable but deterministic (either base or muted active tint)
+ - future words: base/dim color
+- Update `updateCanvasWordFills()` pop branch to drive color from active unit state (`isCurrentWord`, `isPast`, `isFuture`) instead of `frac > 0`.
+
+3) Keep fill and pop code paths independent
+- Keep fill-mode gradient stop logic unchanged for `fill`.
+- In `pop`, disable gradient assumptions and apply direct fill color + scale tween only.
+- Ensure pop behavior is consistent across display granularities (`scroll`, `word`, `syllable`).
+
+4) Add safety for user-overridden speaker colors
+- If user picks a speaker color too close to base text color, auto-adjust or warn with “Auto-fix contrast/separation”.
+- Persist adjusted color only when user confirms; otherwise apply ephemeral runtime correction.
+
+5) Validation matrix
+- Dynamic BG on/off × speaker diarization on/off.
+- Fill mode: active sweep remains visible on all lines.
+- Pop mode: only intended active token pops; non-active tokens remain readable and correctly colored.
+- Cases where user speaker color equals base text color.
+
+#### Acceptance criteria
+
+- Speaker color never renders indistinguishable from base text in active karaoke states.
+- Fill sweep remains visually detectable for diarized lines.
+- Pop mode renders correct active/inactive coloring and scale behavior without stale highlight carryover.
+- Frontend typecheck passes and diagnostics remain clean.
+
+---
+
+### 2026-03-18 investigation (dynamic background checkbox appears missing)
+
+Requested:
+- Investigate why the dynamic background checkbox seems to have disappeared.
+
+Scope:
+- `frontend/src/components/LyricsLivePreview.tsx`
+
+#### Findings
+
+1) Checkbox visibility is hard-gated by `hasCoverArt`
+- In `StylePicker`, the entire dynamic block is conditionally rendered only when `hasCoverArt` is truthy.
+- See dynamic toggle guard in the style panel render path.
+
+2) `hasCoverArt` currently requires both URL and successful image load
+- Parent passes:
+ - `hasCoverArt={!!artworkUrl && artLoaded}`
+- This means a URL alone is not enough; image load must succeed first.
+
+3) `artLoaded` is initialized/reset to false and only flips true on hidden ``
+- `artLoaded` starts false, and is reset false whenever `artworkUrl` changes.
+- The checkbox remains hidden until the hidden preload image emits `onLoad`.
+
+4) Practical failure mode
+- If source image fails to load (remote thumbnail hotlink block, auth/CORS/proxy restrictions, bad URL, network failure), `artLoaded` remains false.
+- Result: dynamic checkbox never renders, even when `artworkUrl` exists.
+
+5) Why this regressed in perception
+- Dynamic background used to be thought of as “available when artwork URL exists”.
+- Current logic ties availability to “image loaded successfully”, making the control disappear in partial-failure scenarios.
+
+#### Impact
+
+- Users can lose access to the dynamic toggle entirely, with no explicit UI explanation.
+- This appears as a missing feature rather than an asset-load issue.
+
+#### Recommended follow-up (implementation step)
+
+1. Decouple control visibility from load success:
+ - show dynamic toggle when `artworkUrl` exists.
+2. Keep runtime extraction guarded:
+ - if image load fails, disable `dynBg` application and show inline warning.
+3. Add small status text in panel:
+ - “Artwork unavailable; dynamic extraction disabled for this source.”
+
+Acceptance criteria for fix:
+- Dynamic toggle is visible whenever an artwork URL is present.
+- Toggle state remains understandable when extraction cannot run.
+- No silent disappearance of the control.
+
+---
+
+### 2026-03-18 implementation (lyrics preview completeness: thumbnail fallback, video parity, vertical anchor)
+
+Requested:
+- Implement and document the missing preview pieces:
+ 1) thumbnail-driven background/cover fallback,
+ 2) source-video playback parity in karaoke preview,
+ 3) vertical active-line alignment control.
+
+Scope:
+- `backend/services/project_assets_service.py`
+- `backend/tests/test_projects_detail.py`
+- `frontend/src/types.ts`
+- `frontend/src/pages/ProjectDetail.tsx`
+- `frontend/src/components/LyricsLivePreview.tsx`
+
+#### Implemented
+
+1) Backend thumbnail-aware project metadata + cover endpoint fallback
+- `build_project_detail()` now exposes:
+ - `source_thumbnail_url` (derived from source-file sidecar metadata when present).
+- `get_project_cover_art()` behavior updated:
+ - first tries embedded artwork from media tags (existing behavior),
+ - if absent, falls back to downloading the source thumbnail URL from sidecar metadata,
+ - still returns `404` only when neither source is available.
+- Added local helper utilities in `project_assets_service.py` for sidecar parsing and remote image fetch.
+
+2) Frontend project detail wiring
+- Added `ProjectDetail.source_thumbnail_url` in `frontend/src/types.ts`.
+- Wired thumbnail URL through `ProjectDetail` → `StemLyricsRow` → `LrcPreview` → `LyricsLivePreview`.
+
+3) Lyrics preview artwork fallback + dynamic background source
+- Added `thumbnailUrl` prop to `LyricsLivePreview`.
+- Introduced unified artwork source precedence:
+ - `artworkUrl = coverArtUrl ?? thumbnailUrl`.
+- Updated art probe/loading and dynamic background extraction to use `artworkUrl`.
+- Updated windowed/fullscreen cover card rendering and StylePicker art-availability gating to use the same fallback source.
+
+4) Source-video playback parity in karaoke preview
+- Added `hasVideoBackdrop` behavior so source video backdrop is shown whenever `videoUrl` is available (not only `visualStyle === 'video'`).
+- Kept transport sync behavior (seek/play/pause) active for source video via `currentTime` / `isPlaying` synchronization effects.
+- Canvas background is transparently composited when video backdrop is present.
+
+5) Vertical active-line alignment control
+- Added style field:
+ - `activeLineVerticalAlign: 'top' | 'center' | 'bottom'`
+- Added StylePicker UI control (`Anchor`: Top/Center/Bottom).
+- Added propagation to canvas style payload and rebuild key.
+- Updated canvas scroll target math in both:
+ - `snapCanvasSceneState()` and
+ - animated update path,
+ so active-line anchor uses configurable vertical position instead of hard-coded center.
+
+Validation:
+- Frontend typecheck (`frontend`): OK
+- Python syntax compile for changed backend files: OK
+- Backend unittest execution in this environment is blocked by missing runtime dependency (`fastapi` not installed in the current shell env)
+
+---
+
+### 2026-03-18 plan (lyrics preview UI polish: slider track visibility + full-video fit)
+
+Issue reported:
+- In lyric preview, slider bars appear invisible.
+- Video preview looks vertically narrow / cropped (user cannot see full frame).
+
+Current behavior (confirmed by code inspection):
+- Range inputs in `LyricsLivePreview` use compact controls (`h-1`/`h-1.5`) and rely on global range styling.
+- Global CSS currently sets `input[type="range"]` background to `--ui-surface-2` only, with no explicit high-contrast track styling for WebKit/Firefox pseudo-elements.
+- In many skins/themes this becomes low-contrast against panel backgrounds, so the track appears missing even when the thumb exists.
+- Video element in preview uses `object-fit: cover`, which intentionally crops to fill the container; this can cut top/bottom content and feel “too narrow vertically.”
+
+Planned fix:
+
+1) Make slider tracks explicitly visible across browsers
+- Add dedicated range-track styles in `frontend/src/index.css`:
+ - `::-webkit-slider-runnable-track`
+ - `::-moz-range-track`
+ - (optionally) `::-moz-range-progress`
+- Use a contrast-safe track color based on semantic tokens (with dark/light parity).
+- Keep brand-colored thumb and improve focus ring visibility.
+
+2) Preserve slider readability in lyric preview panel
+- In `LyricsLivePreview`, keep compact slider size but add per-control class for consistent contrast (e.g., shared `lyric-slider` class).
+- Ensure disabled states remain visible (reduced opacity but still legible track).
+
+3) Show full video frame by default in preview
+- Change preview video fit behavior from strict `cover` to full-frame rendering (`contain`) for lyric preview mode.
+- Add a fallback/letterbox fill strategy so unused space remains visually pleasant:
+ - keep readability scrim,
+ - optional blurred background layer from the same video frame/artwork behind contained video.
+
+4) Keep future flexibility for users
+- Add an optional style toggle for video fit:
+ - `Fill (cover)`
+ - `Fit (contain)`
+- Default to `Fit (contain)` to satisfy “show whole video” expectation.
+
+5) Validation checklist
+- Slider tracks are clearly visible in default, dark, and alternative skin modes.
+- Slider thumb + track visible in Chromium and Firefox.
+- Preview video shows full frame without top/bottom crop in default mode.
+- Lyrics readability remains acceptable with scrim/overlay.
+
+Scope:
+- `frontend/src/index.css`
+- `frontend/src/components/LyricsLivePreview.tsx`
+
+#### 2026-03-18 implementation update
+
+Implemented now:
+
+1) Slider track visibility fix (cross-browser)
+- Updated global range styling in `frontend/src/index.css` with explicit track/thumb rendering for:
+ - `::-webkit-slider-runnable-track`
+ - `::-webkit-slider-thumb`
+ - `::-moz-range-track`
+ - `::-moz-range-thumb`
+- Added contrast-safe semantic colors and a visible focus outline for keyboard accessibility.
+- Result: slider bars are no longer effectively invisible in lyric preview controls.
+
+2) Full-frame video preview fit
+- Updated lyric preview video layer in `frontend/src/components/LyricsLivePreview.tsx`:
+ - `objectFit: 'cover'` → `objectFit: 'contain'`
+ - Added dark background fill to support letterboxing cleanly.
+- Result: source video frame is shown fully in preview instead of vertical crop.
+
+Validation:
+- frontend diagnostics on changed files: clean
+- frontend typecheck: OK
+
+---
+
+### 2026-03-18 plan (contrast-safe dynamic palettes for lyric preview)
+
+Issue reported:
+- Dynamic palette generation can produce low-contrast combinations (example: red-ish background with red lyric/accent text on Octopus Project).
+- Current visual output is “vivid” but not guaranteed readable.
+
+Current behavior (confirmed):
+- Dynamic background color is extracted from artwork and hue/saturation boosted.
+- Dynamic speaker palette is generated from seed hue offsets with fixed saturation/lightness.
+- `textColor`, `highlightColor`, and `wordHighlight` are not contrast-validated against the effective dynamic background.
+- There is no explicit WCAG-style contrast gate before applying generated colors.
+
+Root cause:
+- Palette logic is hue-driven, not contrast-driven.
+- “High contrast” naming currently refers to color distinctness across speakers, not guaranteed contrast against the active background.
+
+Plan:
+
+1) Add deterministic contrast utilities (frontend)
+- In `LyricsLivePreview.tsx`, add color helpers:
+ - relative luminance,
+ - contrast ratio ($CR = \frac{L_1 + 0.05}{L_2 + 0.05}$),
+ - candidate adjustment loop for lightness/saturation.
+- Define targets:
+ - primary lyric text vs background: `CR >= 4.5` (WCAG AA normal text),
+ - highlight/accent colors vs background: `CR >= 3.0` minimum, prefer `>= 4.5` when possible.
+
+2) Treat extracted background as the darkest anchor
+- Keep extracted color identity but force it into a bounded dark range for readability (background remains “darkest layer”).
+- Derive gradient top/bottom from this anchor while preserving that both stops stay below a luminance ceiling.
+
+3) Generate contrast-safe accents from the background
+- Replace fixed-lightness hue offsets with adaptive generation:
+ - start from desired hue rotations,
+ - adjust lightness until contrast target is met against effective background,
+ - reject/fallback candidates that cannot meet threshold.
+- Apply this for:
+ - speaker palette (`dynamicSpeakerPalette`),
+ - default dynamic `wordHighlight` / `highlightColor` candidates when `dynBg` is on.
+
+4) Protect user overrides without breaking readability
+- If user manually picks colors that fail contrast:
+ - do not overwrite stored preference silently,
+ - surface a small warning badge in StylePicker (“Low contrast”),
+ - offer one-click “Auto-fix contrast” action.
+
+5) Add guardrails for edge-case artwork
+- If extracted seed is too close to red/magenta and accents collide, auto-shift accents toward complementary warm-light or cool-light candidates (amber/cyan family) while still enforcing ratio thresholds.
+- Keep deterministic fallback palette list for impossible cases.
+
+6) Validation matrix
+- Test on dark red, dark blue, and near-gray album thumbnails.
+- Verify text/highlight/speaker colors all meet target contrast against effective background.
+- Confirm no regression in fullscreen, non-fullscreen, and video-backed preview modes.
+
+Acceptance criteria:
+- Dynamic background may remain artistically tinted, but lyric text and active highlights are always readable.
+- Generated palettes are contrast-validated before render.
+- Background remains the darkest visual layer; accents/text are consistently lighter and ratio-compliant.
+
+Scope:
+- `frontend/src/components/LyricsLivePreview.tsx`
+- (optional) `frontend/src/types.ts` for a future `contrastPolicy` style option
+
+---
+
+### 2026-03-18 plan (YouTube imports → project discoverability)
+
+Issue reported:
+- Users import media via yt-dlp but expect it to appear under Projects immediately.
+
+Current behavior (confirmed):
+- yt-dlp imports are stored in `IMPORTS_DIR` and listed in UI import lists.
+- They are accessible from:
+ - Sidebar → Subsonic panel → **Imported Files** list
+ - Separator page → **Input Source = Imported Files**
+- A Project is only created after running separation/pipeline on that imported file.
+
+Root cause:
+- Product behavior is technically correct, but the UX does not clearly communicate that imports are *library inputs*, not Projects.
+- The primary next action (start separation/auto-pipeline) is not prominent enough after a yt-dlp import completes.
+
+Planned fix:
+
+1) Clarify status copy in YT-DL panel
+- On successful job completion, show explicit helper text:
+ - “Imported successfully. Open Separator → Imported Files, or run Auto Pipeline.”
+
+2) Add explicit post-import action buttons
+- In `YtDlPanel` completion state, add visible actions:
+ - `Open Separator (Imported)`
+ - `Run Auto Pipeline`
+- Preselect the newly imported file for the action target.
+
+3) Improve imported list affordance in Sidebar
+- Keep `Auto Pipeline` control visible for the newest imported item (not hover-only).
+- Optional: badge imported video/audio source (`yt-dlp` / `subsonic`) for context.
+
+4) Keep project model unchanged
+- Do not auto-create Projects at import time.
+- Preserve invariant: Projects represent processed workspaces with pipeline/separation outputs.
+
+Acceptance criteria:
+- After yt-dlp import completes, user can reach a “create project” path in one click.
+- No ambiguity that imports are available immediately under imported-source selectors.
+- No backend behavior changes required for project persistence semantics.
+
+#### 2026-03-18 implementation update
+
+Implemented now:
+
+1) Source-based split in Sidebar import lists
+- `SubsonicPanel` now filters out `source=yt-dlp` items from its local **Imported Files** block.
+- Label updated to **Subsonic Imports** to reduce source ambiguity.
+
+2) yt-dlp imports now visible in the YT-DL panel itself
+- `YtDlPanel` now queries the same imports feed and displays a **YT-DL Imports** list.
+- List contains only `source=yt-dlp` items and refreshes while the panel is open.
+
+3) Direct processing action retained where users expect it
+- Each YT-DL imported item has `Auto pipeline` action in `YtDlPanel`.
+- Keeps the “import → process → project” flow in the same panel.
+
+Validation:
+- `npm run -s typecheck` — `EXIT:0`
+
+
+### 2026-03-17 implementation (yt-dlp import + video preview playback + advanced Subsonic search)
+
+### 2026-03-18 plan (YT-DL thumbnail-driven karaoke visuals + vertical line anchor)
+
+Requested:
+- Fix missing/weak visual elements in lyrics preview.
+- Generate a dynamic background for YT-DL imports using video thumbnail.
+- Use thumbnail as project/preview cover when embedded art is missing.
+- Ensure source video playback works in karaoke preview window.
+- Add vertical active-line alignment control: top / center / bottom.
+
+Current state (confirmed):
+- `LyricsLivePreview` already supports `videoUrl` playback in `video` visual mode.
+- Project cover art endpoint only reads embedded media artwork (`_read_cover_art`) from source file.
+- YT-DL metadata sidecar already stores `thumbnail` URL, but preview/project cover flow does not consume it.
+- Style options currently expose horizontal alignment (`textAlign`) only.
+
+Scope (planned files):
+- `backend/services/subsonic_service.py`
+- `backend/services/project_assets_service.py`
+- `frontend/src/types.ts`
+- `frontend/src/components/LyricsLivePreview.tsx`
+- `frontend/src/pages/ProjectDetail.tsx`
+- `frontend/src/components/Sidebar.tsx` (optional source badges only)
+
+Implementation plan:
+
+1) Persist thumbnail metadata in import/project paths
+- Extend imported-file typing to include thumbnail/webpage metadata fields in `ImportedFile`.
+- Ensure project detail payload can expose a `source_thumbnail_url` when source comes from yt-dlp metadata sidecar.
+- Add cover-art fallback in project assets service:
+ - If embedded cover art missing, return thumbnail-derived image (download/cache) when available.
+
+2) Thumbnail-as-cover fallback (backend)
+- In `get_project_cover_art(...)`:
+ - Keep existing embedded-art path first.
+ - Add fallback branch to resolve yt-dlp sidecar thumbnail URL for the source file.
+ - Fetch once and cache under project cache/art path; serve cached bytes with mime.
+- Add safety/timeouts and fail soft (keep 404 if no image).
+
+3) Dynamic thumbnail background pipeline (frontend)
+- Add optional `thumbnailUrl` prop to `LyricsLivePreview`.
+- For YT-DL/video sources when no cover art exists:
+ - render blurred thumbnail background layer (cover-fit),
+ - apply readability scrim/gradient,
+ - derive accent colors (simple average/hsl extraction) for glow/highlight defaults.
+- Keep existing `videoUrl` layer precedence in `video` style; thumbnail becomes paused/fallback background.
+
+4) Video playback parity in karaoke preview
+- Ensure video layer is mounted/visible for karaoke preview layouts where controls/editor panels are open.
+- Keep transport sync contract unchanged (seek/play/pause/reset tied to video clock when audio absent).
+- Add explicit fallback when video fails to load: thumbnail background + warning badge.
+
+5) Vertical active-line alignment control
+- Extend style model with `verticalAlign: 'top' | 'center' | 'bottom'`.
+- Add control in style picker (3-button toggle like horizontal alignment).
+- Implement in `LyricsCanvas` layout math:
+ - `top`: active line anchored in upper band,
+ - `center`: current behavior,
+ - `bottom`: active line anchored in lower band.
+- Apply uniformly across `scroll`, `fade`, `karaoke`, `glow`, `blur`, and `video` styles.
+
+6) Missing-elements hardening pass
+- Audit z-index/layering for video, scrim, lyric canvas, overlays.
+- Add minimum contrast guardrails (auto darken scrim when background luminance is high).
+- Verify fullscreen and non-fullscreen parity.
+
+Validation checklist:
+- YT-DL import with no embedded cover: preview shows thumbnail-based cover/background.
+- Karaoke preview plays source video in sync with transport controls.
+- Vertical alignment toggle visibly repositions active line top/center/bottom.
+- No regressions for non-YT-DL audio-only projects.
+- `npm run -s typecheck` and backend compile checks clean.
+
+---
### 2026-03-17 implementation (yt-dlp import + video preview playback + advanced Subsonic search)
diff --git a/backend/services/project_assets_service.py b/backend/services/project_assets_service.py
index ba35eef..3e94d45 100644
--- a/backend/services/project_assets_service.py
+++ b/backend/services/project_assets_service.py
@@ -1,8 +1,11 @@
from __future__ import annotations
+import json
import os
import shutil
from pathlib import Path
+from urllib import error as urlerror
+from urllib import request as urlrequest
from ..config import UPLOAD_DIR
from ..repositories import jobs as jobs_repo
@@ -11,6 +14,37 @@ from .metadata_util import _read_cover_art, read_metadata
from .project_service_common import ProjectOperationError, _infer_stem_name, project_output_dir
+def _sidecar_path(media_path: Path) -> Path:
+ return media_path.with_suffix(media_path.suffix + ".json")
+
+
+def _read_import_sidecar(media_path: Path) -> dict:
+ sidecar = _sidecar_path(media_path)
+ if not sidecar.exists():
+ return {}
+ try:
+ raw = json.loads(sidecar.read_text(encoding="utf-8"))
+ return raw if isinstance(raw, dict) else {}
+ except Exception:
+ return {}
+
+
+def _read_source_thumbnail_url(source_path: Path) -> str:
+ sidecar = _read_import_sidecar(source_path)
+ value = str(sidecar.get("thumbnail") or "").strip()
+ if value.startswith(("http://", "https://")):
+ return value
+ return ""
+
+
+def _fetch_remote_image(url: str) -> tuple[bytes, str | None]:
+ req = urlrequest.Request(url, headers={"User-Agent": "StemEngine/cover-art-fallback"})
+ with urlrequest.urlopen(req, timeout=8) as resp:
+ data = resp.read()
+ mime = resp.headers.get_content_type() if resp.headers else None
+ return data, mime
+
+
def list_projects() -> list[dict]:
return projects_repo.list_all()
@@ -73,6 +107,7 @@ def build_project_detail(project: dict) -> dict:
source_artist = ""
source_title = ""
+ source_thumbnail_url = ""
source_file = next(
(file_entry for file_entry in (sep_job or {}).get("files", []) if file_entry.get("type") == "source"),
None,
@@ -80,6 +115,7 @@ def build_project_detail(project: dict) -> dict:
if source_file:
src_path = source_file.get("path", "")
if src_path and Path(src_path).exists():
+ source_thumbnail_url = _read_source_thumbnail_url(Path(src_path))
try:
meta = read_metadata(src_path)
source_artist = meta.get("artist") or meta.get("albumartist") or ""
@@ -96,6 +132,7 @@ def build_project_detail(project: dict) -> dict:
"mix_job": mix_job,
"source_artist": source_artist,
"source_title": source_title,
+ "source_thumbnail_url": source_thumbnail_url,
}
@@ -206,6 +243,18 @@ def get_project_cover_art(project: dict) -> tuple[bytes, str]:
raise ProjectOperationError(404, "Source file not found")
data, mime = _read_cover_art(source_path)
- if not data:
- raise ProjectOperationError(404, "No cover art")
- return data, mime or "image/jpeg"
+ if data:
+ return data, mime or "image/jpeg"
+
+ thumbnail_url = _read_source_thumbnail_url(Path(source_path))
+ if thumbnail_url:
+ try:
+ remote_data, remote_mime = _fetch_remote_image(thumbnail_url)
+ if remote_data:
+ return remote_data, remote_mime or "image/jpeg"
+ except (urlerror.URLError, TimeoutError, ValueError, OSError):
+ pass
+ except Exception:
+ pass
+
+ raise ProjectOperationError(404, "No cover art")
diff --git a/backend/tests/test_projects_detail.py b/backend/tests/test_projects_detail.py
index 7afaeb4..d8cd914 100644
--- a/backend/tests/test_projects_detail.py
+++ b/backend/tests/test_projects_detail.py
@@ -29,4 +29,5 @@ class ProjectDetailTests(BackendTestCase):
self.assertEqual(payload["lrc_jobs"]["vocals"]["id"], lrc_job_id)
self.assertEqual(payload["mix_job"]["id"], mix_job_id)
self.assertEqual(payload["source_artist"], "")
- self.assertEqual(payload["source_title"], "")
\ No newline at end of file
+ self.assertEqual(payload["source_title"], "")
+ self.assertEqual(payload["source_thumbnail_url"], "")
\ No newline at end of file
diff --git a/frontend/src/components/LyricsLivePreview.tsx b/frontend/src/components/LyricsLivePreview.tsx
index efc416e..32bc0b9 100755
--- a/frontend/src/components/LyricsLivePreview.tsx
+++ b/frontend/src/components/LyricsLivePreview.tsx
@@ -45,6 +45,8 @@ interface Props {
storageKey?: string
/** URL of the source audio cover art (served by /api/projects/{id}/cover-art). */
coverArtUrl?: string
+ /** Thumbnail URL fallback from yt-dlp sidecar metadata. */
+ thumbnailUrl?: string
/** Artist name from source audio metadata. */
artist?: string
/** Track title from source audio metadata — used in the visual overlay only. */
@@ -127,19 +129,105 @@ function hslToHex(h: number, s: number, l: number): string {
return `#${[r, g, b].map(v => v.toString(16).padStart(2, '0')).join('')}`
}
-function buildHighContrastSpeakerPalette(seedColor?: string): string[] {
+function clamp01(value: number): number {
+ return Math.min(1, Math.max(0, value))
+}
+
+function relativeLuminance(rgb: { r: number; g: number; b: number }): number {
+ const toLinear = (v: number) => {
+ const x = v / 255
+ return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4)
+ }
+ const r = toLinear(rgb.r)
+ const g = toLinear(rgb.g)
+ const b = toLinear(rgb.b)
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+function contrastRatio(a: { r: number; g: number; b: number }, b: { r: number; g: number; b: number }): number {
+ const la = relativeLuminance(a)
+ const lb = relativeLuminance(b)
+ const lighter = Math.max(la, lb)
+ const darker = Math.min(la, lb)
+ return (lighter + 0.05) / (darker + 0.05)
+}
+
+function ensureReadableColor(
+ seedColor: string,
+ bgColor: string,
+ minRatio = 4.5,
+ preferLighter = true,
+): string {
+ const seedRgb = parseCssColorToRgb(seedColor)
+ const bgRgb = parseCssColorToRgb(bgColor)
+ if (!seedRgb || !bgRgb) return seedColor
+
+ const bgLum = relativeLuminance(bgRgb)
+ const seedLum = relativeLuminance(seedRgb)
+ const seedRatio = contrastRatio(seedRgb, bgRgb)
+ if (seedRatio >= minRatio && (!preferLighter || seedLum > bgLum + 0.015)) return seedColor
+
+ const { h, s } = rgbToHsl(seedRgb.r, seedRgb.g, seedRgb.b)
+ const sat = Math.min(0.98, Math.max(0.62, s))
+
+ let best = seedColor
+ let bestRatio = seedRatio
+ for (let i = 0; i <= 40; i++) {
+ const l = clamp01(0.99 - i * 0.02)
+ const candidate = hslToHex(h, sat, l)
+ const rgb = parseCssColorToRgb(candidate)
+ if (!rgb) continue
+ const lum = relativeLuminance(rgb)
+ if (preferLighter && lum <= bgLum + 0.015) continue
+ const ratio = contrastRatio(rgb, bgRgb)
+ if (ratio >= minRatio) return candidate
+ if (ratio > bestRatio) {
+ best = candidate
+ bestRatio = ratio
+ }
+ }
+
+ const whiteRatio = contrastRatio({ r: 255, g: 255, b: 255 }, bgRgb)
+ if (whiteRatio >= bestRatio) return '#ffffff'
+ return best
+}
+
+function normalizeDynamicBackground(seedColor?: string): string | null {
+ if (!seedColor) return null
+ const rgb = parseCssColorToRgb(seedColor)
+ if (!rgb) return null
+ const { h, s, l } = rgbToHsl(rgb.r, rgb.g, rgb.b)
+ // Keep dynamic backgrounds as the darkest visual layer.
+ const darkS = Math.min(0.90, Math.max(0.52, s * 1.08))
+ const darkL = Math.min(0.22, Math.max(0.08, l * 0.58 + 0.02))
+ return hslToHex(h, darkS, darkL)
+}
+
+function buildDynamicBackgroundGradient(bgColor?: string): string | null {
+ if (!bgColor) return null
+ const rgb = parseCssColorToRgb(bgColor)
+ if (!rgb) return null
+ const { h, s, l } = rgbToHsl(rgb.r, rgb.g, rgb.b)
+ const top = hslToHex(h, Math.min(0.94, Math.max(0.56, s * 1.08)), Math.min(0.30, l + 0.05))
+ const bottom = hslToHex((h + 8) % 360, Math.min(0.90, Math.max(0.50, s)), Math.max(0.05, l - 0.05))
+ return `linear-gradient(180deg, ${top} 0%, ${bottom} 100%)`
+}
+
+function buildHighContrastSpeakerPalette(seedColor?: string, bgColor?: string): string[] {
const fallback = SPEAKER_PALETTE
if (!seedColor) return fallback
const rgb = parseCssColorToRgb(seedColor)
if (!rgb) return fallback
const { h } = rgbToHsl(rgb.r, rgb.g, rgb.b)
const hues = [0, 38, 78, 120, 168, 210, 255, 300]
- return hues.map((delta, idx) => {
+ const palette = hues.map((delta, idx) => {
const hh = (h + delta) % 360
const sat = 0.86
- const light = idx % 2 === 0 ? 0.58 : 0.68
+ const light = idx % 2 === 0 ? 0.66 : 0.74
return hslToHex(hh, sat, light)
})
+ if (!bgColor) return palette
+ return palette.map(color => ensureReadableColor(color, bgColor, 4.5, true))
}
// ─── Speaker colours ──────────────────────────────────────────────────────────
@@ -508,6 +596,7 @@ interface StyleState {
highlightColor: string
wordHighlight: string
textAlign: 'left' | 'center' | 'right'
+ activeLineVerticalAlign: 'top' | 'center' | 'bottom'
lineSpacing: number
dynBg: boolean
dynBgMode: 'flat' | 'gradient'
@@ -545,6 +634,7 @@ function buildInitialStyle(styleOptions?: Partial): StyleSta
highlightColor: styleOptions?.highlightColor ?? DEFAULT_STYLE.highlightColor,
wordHighlight: styleOptions?.wordHighlightColor ?? DEFAULT_STYLE.wordHighlight,
textAlign: (styleOptions?.textAlign ?? DEFAULT_STYLE.textAlign) as 'left' | 'center' | 'right',
+ activeLineVerticalAlign: (styleOptions?.activeLineVerticalAlign ?? DEFAULT_STYLE.activeLineVerticalAlign) as 'top' | 'center' | 'bottom',
lineSpacing: styleOptions?.lineSpacing ?? DEFAULT_STYLE.lineSpacing,
}
}
@@ -557,6 +647,7 @@ const DEFAULT_STYLE: StyleState = {
highlightColor: '#3b82f6',
wordHighlight: '#60a5fa',
textAlign: 'center',
+ activeLineVerticalAlign: 'center',
lineSpacing: 1.6,
dynBg: false,
dynBgMode: 'gradient',
@@ -675,6 +766,26 @@ function StylePicker({
className="w-20 h-1.5 accent-brand-400"
/>
+