diff --git a/20260313_Fixes (Copilot).md b/20260313_Fixes (Copilot).md index 06c1700..fa8a262 100644 --- a/20260313_Fixes (Copilot).md +++ b/20260313_Fixes (Copilot).md @@ -65,6 +65,441 @@ Secondary test stabilizations: --- +## 2026-04-04 Update — Sing settings UX and Subsonic browse wiring + +Completed follow-up corrections for the library/sing shell flow and Subsonic connectivity visibility. + +### Implemented + +- `frontend/src/App.tsx` + - Added a discrete right-side Settings overlay for library routes. + - Overlay close behaviors now include: + - close button, + - backdrop click, + - `Escape` key. + - Kept direct `/settings` route support for compatibility. + +- `frontend/src/components/AppLibraryShell.tsx` + - Added optional `onOpenSettings` callback prop. + - Settings button now opens overlay when callback is provided, otherwise falls back to route navigation. + +- `frontend/src/hooks/useSubsonicLibrary.ts` (new) + - Added shared hook to load library data via: + - `getSubsonicConfig()` + - `searchSubsonic()` + - Exposes `songs`, `loading`, `configured`, `error`, and `refresh` state. + +- `frontend/src/pages/Tracks.tsx` + - Replaced placeholder tracks with Subsonic-backed results. + - Added configuration and API error banners. + +- `frontend/src/pages/Albums.tsx` + - Replaced placeholder albums with derived album groupings from Subsonic songs. + - Added configuration and API error banners. + +- `frontend/src/pages/Artists.tsx` + - Replaced placeholder artists with derived artist/album counts from Subsonic songs. + - Added configuration and API error banners. + +- `frontend/src/pages/Playlists.tsx` + - Added explicit notice that playlist browse wiring is pending backend endpoint parity. + +### Validation + +- `cd frontend && npm run build` → pass + +### Documentation + +- Updated: `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - Added section: `2026-04-04 discrepancy review + action plan (Sing settings + Subsonic browsing)` + +--- + +## 2026-04-04 Update — Playlist API wiring + convert status end-to-end + +Completed Subsonic playlist backend/frontend wiring and connected library convert buttons to live status transitions. + +### Implemented + +- `backend/routers/subsonic.py` + - Added playlist routes: + - `GET /api/subsonic/playlists` + - `GET /api/subsonic/playlists/{playlist_id}` + - Removed the early-empty guard in `GET /api/subsonic/search` so browse flows can request results without forcing a manual query term. + +- `backend/services/subsonic_service.py` + - `search_songs()` now falls back to wildcard query (`*`) when no query/filter is supplied. + - Added `list_playlists()` to call `getPlaylists.view`. + - Added `get_playlist()` to call `getPlaylist.view` and return normalized track entries. + +- `frontend/src/types.ts` + - Added: + - `SubsonicPlaylist` + - `SubsonicPlaylistDetail` + +- `frontend/src/api/client.ts` + - Added: + - `listSubsonicPlaylists()` + - `getSubsonicPlaylist(playlistId)` + +- `frontend/src/pages/Playlists.tsx` + - Replaced placeholder-only behavior with API-backed playlist loading. + - Added config/loader/error states tied to Subsonic configuration. + +- `frontend/src/hooks/useConvertStatus.ts` (new) + - Added end-to-end convert orchestration: + - import from Subsonic, + - submit separation from imported path, + - poll job to terminal state, + - refresh project list, + - map per-song status to `queued` / `running` / `ready` / `failed`. + +- `frontend/src/pages/Tracks.tsx` + - Convert button now executes full conversion pipeline. + - Button label reflects live status (`Queued`, `Running`, `Ready`, `Retry`). + +- `frontend/src/pages/Albums.tsx` + - Album convert now runs batched song conversion. + - Album-level button status is derived from per-song state aggregate (`queued` / `running` / `ready` / `failed`). + +### Validation + +- `cd frontend && npm run build` → pass +- `python3 -m py_compile backend/routers/subsonic.py backend/services/subsonic_service.py` → pass + +--- + +## 2026-04-04 Update — Sing interface Subsonic browsing + convert status in-route + +Follow-up implementation aligned with the connectivity plan expectations for the Sing interface itself. + +### Implemented + +- `frontend/src/pages/Sing.tsx` + - Added dual-mode Sing view: + - `Karaoke Projects` + - `Subsonic Library` + - Added shared search input behavior per active mode. + - Added Subsonic config/error/loading states directly in Sing page. + - Added per-song convert action in Sing Subsonic mode with live status labels: + - `Queued`, `Running`, `Ready`, `Retry`. + +- `frontend/src/hooks/useSubsonicLibrary.ts` + - Switched browse query to wildcard (`q='*'`) to support list-style browsing even when no explicit search term is entered. + +### Validation + +- `cd frontend && npm run build` → pass + +### Documentation + +- Updated: `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - Added section: `2026-04-04 implementation update — Sing interface functional parity slice` + +--- + +## 2026-04-04 Update — Sing standard-player interface refactor + +Expanded Sing route UI from simple dual-toggle into a standard player-style interface with integrated karaoke workflows. + +### Implemented + +- `frontend/src/pages/Sing.tsx` + - Added in-page mode tabs: + - `Home`, `Tracks`, `Albums`, `Artists`, `Playlists`, `Karaoke`. + - Added mode-specific search behavior and content rendering. + - Added home dashboard cards (tracks/albums/artists/karaoke projects) and featured sections. + - Added Tracks list with per-song convert status/actions. + - Added Albums grid with batch convert + aggregate status labels. + - Added Artists and Playlists browse views in Sing route. + - Retained Karaoke project launcher behavior to `/karaoke` route. + +- `frontend/src/hooks/useSubsonicLibrary.ts` + - Ensured browse mode query uses wildcard (`q='*'`) so initial library load does not require manual search text. + +### Validation + +- `cd frontend && npm run build` → pass + +### Documentation + +- Updated: `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - Added section: `2026-04-04 implementation update — Sing as standard player + karaoke hub` + +--- + +## 2026-04-05 Update — Deployment port alignment + API-only backend mode + +Aligned runtime deployment behavior with split frontend/backend services. + +### Implemented + +- `stemengine.yml` + - Confirmed/kept canonical port mappings: + - WebUI: `5174:5173` + - Backend: `8000:8000` + - SingUI: `3001:5173` + - Added backend env guard: + - `BACKEND_SERVE_LEGACY_WEBUI=${BACKEND_SERVE_LEGACY_WEBUI:-false}` + - Clarified compose comments for WebUI/SingUI canonical mapping. + +- `backend/main.py` + - Changed backend static frontend serving to opt-in only. + - Default backend mode is now API-only unless: + - `BACKEND_SERVE_LEGACY_WEBUI=true` + +### Validation + +- `python3 -m py_compile backend/main.py` → pass +- `docker compose -f stemengine.yml config` → pass + +### Operational note + +- After deployment, WebUI/SingUI should be served only from their dedicated frontend containers. +- Backend port `8000` should serve API responses without legacy SPA fallback unless explicitly re-enabled. + +--- + +## 2026-04-06 Update — SEK packaging flow + project video sync + SEK-first SingUI direction + +Implemented StemEngine Karaoke package workflow improvements and documented the SEK-first runtime direction. + +### Implemented + +- `backend/services/project_assets_service.py` + - Added per-project karaoke config persistence (`stemengine_karaoke_config.json`): + - `video_source` + - `include_video` + - `sync_reference_track` + - `track_offsets_seconds` + - `last_sync` + - Added video source resolution: + - local file path + - YouTube/remote URL via `yt-dlp` + - Added track/video sync estimation using onset-envelope cross-correlation. + - Updated `.sek` manifest output to include synchronization block: + - `meta.synchronization.reference_track` + - `meta.synchronization.track_offsets_seconds` + - `meta.synchronization.video_source` + - `meta.synchronization.last_sync` + +- `backend/routers/projects.py` + - Added endpoints: + - `GET /api/projects/{project_id}/karaoke-config` + - `PATCH /api/projects/{project_id}/karaoke-config` + - `POST /api/projects/{project_id}/sync-video-offset` + - Kept/used `.sek` export endpoint: + - `POST /api/projects/{project_id}/export-sek` + +- `backend/services/project_service.py` + - Re-exported new karaoke config + sync service functions. + +- `frontend/src/api/client.ts` + - Added typed API helpers: + - `getProjectKaraokeConfig()` + - `patchProjectKaraokeConfig()` + - `syncProjectVideoOffset()` + - Retained `.sek` export helper: + - `exportProjectSek()` + +- `frontend/src/pages/ProjectDetail.tsx` + - Added **Karaoke Packaging (.sek)** section with: + - video source input + - sync reference track selector + - offset field + - include-video toggle + - `Save`, `Sync Offset`, and `Package` buttons + - Added run feedback (success/error) and last package path display. + +- Auto Pipeline integration + - `frontend/src/utils/autoPipeline.ts` + - Added `sekPackage` step type and display label. + - `frontend/src/components/AutoPipelineDialog.tsx` + - Added `sekPackage` execution path using `exportProjectSek()`. + - `frontend/src/pages/Settings.tsx` + - Added `sekPackage` add/config UI. + +### Documentation + +- Reworked top of `docs/KARAOKE_BOX_PLAN.md` to authoritative **SEK-first** direction: + - SingUI should read from user-set `.sek` folder + - runtime should avoid direct project-internal reads for karaoke playback + - packaging + sync offset requirements and acceptance criteria defined + +### Validation + +- Diagnostics check across edited backend/frontend files → no reported errors. + +--- + +## 2026-04-06 Update — Karaoke Phase 2 implemented (SEK folder library runtime) + +Implemented SingUI runtime support for loading karaoke songs from user-selected `.sek` folder. + +### Implemented + +- `backend/services/sek_library_service.py` (new) + - Added SEK folder scanning (`*.sek`) + - Added manifest parsing/validation + - Added package id hashing from package path + - Added packaged asset extraction (stems/lyrics/video) by inner path + +- `backend/routers/karaoke_sek.py` (new) + - Added endpoints: + - `GET /api/karaoke-sek/library` + - `GET /api/karaoke-sek/packages/{package_id}` + - `GET /api/karaoke-sek/packages/{package_id}/asset?path=...` + +- `backend/main.py` + - Registered `karaoke_sek` router + +- `backend/routers/settings.py` + - Added settings keys: + - `karaoke_source_mode` (`projects` | `sek-folder`) + - `karaoke_sek_folder` + - Added validation for source mode + +- `frontend/src/api/client.ts` + - Added SEK library APIs and asset URL helper: + - `listSekLibrary()` + - `getSekManifest()` + - `sekAssetUrl()` + - Extended `AppSettings` shape with karaoke source/folder keys + +- `frontend/src/pages/Sing.tsx` + - Added karaoke source switch UI (`Project-linked` / `SEK Folder`) + - Added user-set SEK folder input + refresh/save controls + - Added package list rendering from backend scan + - Added launch flow to karaoke route using selected `sekPackageId` + +- `frontend/src/pages/Karaoke.tsx` + - Added SEK playback mode based on route state: + - loads package manifest + - streams stems/lyrics/video via SEK asset endpoint + - keeps existing project-based mode as fallback + +### Documentation + +- Updated `docs/KARAOKE_BOX_PLAN.md`: + - Marked Phase 2 as implemented + - Added concrete delivered API/UI/runtime items + +### Validation + +- Backend/frontend diagnostics for touched files → no reported errors. + +--- + +## 2026-04-06 Update — Karaoke Phase 3 implemented (SEK-first default mode) + +Completed default-runtime switch so karaoke now prefers SEK folder mode by default. + +### Implemented + +- `backend/routers/settings.py` + - Updated default settings value: + - `karaoke_source_mode: "sek-folder"` (was `"projects"`) + +- `frontend/src/pages/Sing.tsx` + - Updated local fallback initialization to `sek-folder` + - Updated settings fallback read to `sek-folder` when key is absent + - Retained explicit source toggle so users can switch back to `projects` + +### Documentation + +- Updated `docs/KARAOKE_BOX_PLAN.md` + - Marked Phase 3 as implemented + - Captured SEK-first default + project fallback behavior + +- Updated `docs/plans/API_REFERENCE.md` + - Added Karaoke SEK endpoint group + - Added settings keys: + - `karaoke_source_mode` + - `karaoke_sek_folder` + - Documented default mode now set to `sek-folder` + +### Validation + +- Diagnostics check for touched files → no reported errors. + +--- + +## 2026-04-06 Update — Karaoke plan closure items completed (settings UX + API docs) + +Closed remaining plan-level gaps by adding dedicated settings UX and API documentation coverage. + +### Implemented + +- `frontend/src/pages/Settings.tsx` + - Added **Karaoke Runtime Source** block in Integrations tab: + - default mode selector (`sek-folder` / `projects`) + - SEK folder path input + - save action with status feedback + +### Documentation + +- `docs/KARAOKE_BOX_PLAN.md` + - Added explicit completion status and “Remaining Work” closure + - Added Settings UI deliverable note under Phase 2 + +- `docs/plans/API_REFERENCE.md` + - Added project karaoke endpoint docs: + - `GET /api/projects/{project_id}/karaoke-config` + - `PATCH /api/projects/{project_id}/karaoke-config` + - `POST /api/projects/{project_id}/sync-video-offset` + - `POST /api/projects/{project_id}/export-sek` + - Added settings keys/default docs and karaoke SEK library endpoint group + +### Validation + +- Diagnostics check for touched files → no reported errors. + +--- + +## 2026-04-06 Update — SEK packager sync behavior changed to automatic + +Adjusted packaging flow to remove manual offset entry and compute offset automatically during package export. + +### Implemented + +- `backend/services/project_assets_service.py` + - `export_project_stemengine_karaoke()` now supports: + - `video_source` override + - `sync_reference_track` override + - `auto_sync` (default `true`) + - During export, if video source is available and auto-sync is enabled: + - estimates offset automatically + - persists to karaoke config + - writes to `.sek` `manifest.json` synchronization block + +- `backend/routers/projects.py` + - Extended `POST /api/projects/{project_id}/export-sek` body with: + - `video_source` + - `sync_reference_track` + - `auto_sync` + +- `frontend/src/api/client.ts` + - `exportProjectSek()` updated to pass auto-sync inputs and read sync status in response. + +- `frontend/src/pages/ProjectDetail.tsx` + - Removed manual `Offset (seconds)` input and explicit `Sync Offset` button + - Packaging header/UX now states sync runs automatically + - `Package` action now sends video source + reference track and relies on backend auto-sync + +### Documentation + +- `docs/KARAOKE_BOX_PLAN.md` + - Updated flow language to automatic sync during packaging + +- `docs/plans/API_REFERENCE.md` + - Updated `export-sek` section with auto-sync request/behavior notes + +### Validation + +- Diagnostics check for touched files → no reported errors. + +--- + ## 2026-04-02 Update — Apollo LQ pipeline stabilization + targeted validation ### User-visible failures observed @@ -2336,6 +2771,29 @@ These route-level tests now verify that: ## Phase 2 closeout +## 2026-04-06 Draft + documentation — Nightingale-style SingUI karaoke flow + +Prepared a concrete architecture draft for adopting Nightingale’s separation-to-playback lifecycle in SingUI. + +### Added documentation + +- `docs/SINGUI_NIGHTINGALE_FLOW_DRAFT.md` + - defines a staged lifecycle: + 1. async prepare job (separate + lyric stage + asset materialization) + 2. playback readiness gate (`Ready` required) + 3. synchronized per-stem playback with `leading` muted by default + 4. single timeline bus for lyrics/HUD/overlays + - proposes a backend `karaoke_assets.json` contract to decouple UI from in-flight job internals + - includes API sketch, UX mapping, cache invalidation rules, rollout steps, and acceptance criteria + +- `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - appended section **36** summarizing the Nightingale-style adaptation and linking to the detailed draft + +### Outcome + +- The request to “draft and document” is fulfilled with implementation-ready design guidance for SingUI. +- No runtime code behavior changed in this step; this pass is documentation and architecture planning only. + Phase 2 goals are now considered complete for this codebase pass: - persistence is centralized in repository modules (`backend/repositories/*`) @@ -6689,3 +7147,277 @@ Plan + docs updates: Phase E status: ✅ **COMPLETE** Next planned slice: Phase F hardening + UX polish. + +### 2026-04-05 deployment fix — restore legacy StemEngine WebUI on 5174 + +Requested: +- Ensure `5174` serves the **legacy StemEngine WebUI** (management tools), + while SingUI remains isolated on `3001`. + +Root cause: +- Both `stemengine-webui` and `stemengine-sing` were pointing at the same + frontend source (`appdata/stemengine/frontend`), so `5174` was rendering the + new SingUI app instead of legacy management UI. + +Fixes implemented: + +1. `stemengine.yml` + - Rewired `stemengine-webui` to legacy source: + - build context: `x/StemEngine-0.9alpha/frontend` + - image: `stemengine-legacy-webui:latest` + - added dedicated dependency volume: + `stemengine-legacy-webui-node-modules` + - Kept `stemengine-sing` mapped to current frontend on `3001:5173`. + +2. `x/StemEngine-0.9alpha/frontend/Dockerfile.webui.dev` + - Added legacy dev Dockerfile for Vite service. + - Uses `npm install` (legacy project has no lockfile). + +3. `x/StemEngine-0.9alpha/frontend/vite.config.ts` + - Set Docker-friendly host binding: `0.0.0.0`. + - Set proxy target for `/api` to backend service via + `VITE_API_PROXY_TARGET` (default `http://stemengine:8000`). + +4. Documentation sync + - Updated connectivity plan with final routing split: + - `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + section: `## 27) 2026-04-05 final routing split — 5174 serves legacy StemEngine WebUI`. + +Runtime validation: +- `http://127.0.0.1:5174/` → `200` (legacy management UI) +- `http://127.0.0.1:3001/` → `200` (new SingUI) +- Compose config validates (`docker compose -f stemengine.yml config --quiet`). + +### 2026-04-05 correction — restore 5174 to current WebUI (undo legacy reroute) + +Requested: +- Restore frontend WebUI on `5174` to the **current app state** (as of + 2026-04-04), because the prior change rerouted `5174` to legacy UI and + effectively reverted visible WebUI behavior. + +Fixes implemented: + +1. `stemengine.yml` + - Restored `stemengine-webui` to current frontend source: + - context: `${SEFOLDER}/frontend` + - image: `stemengine-webui:latest` + - volume: `${SEFOLDER}/frontend:/app/frontend` + - dependency volume: `stemengine-webui-node-modules` + - Removed legacy-specific dependency volume wiring from compose. + - Left `stemengine-sing` on `3001:5173` using the same current frontend. + +2. Documentation updates + - `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - added correction section that supersedes the prior legacy split note. + +Validation: +- `docker compose -f stemengine.yml config --quiet` passes. +- Frontend services can be recreated on corrected mapping (`5174` WebUI, + `3001` SingUI endpoint). + +### 2026-04-05 correction — restore StemEngine sidebar shell on WebUI + +Issue reported: +- Even after port/source correction, WebUI (`5174`) was still presenting the + music-library navigation shell (Albums/Tracks/Artists/Playlists/Sing), not + the expected StemEngine workflow shell. + +Expected shell: +- Sidebar with: + - Subsonic search/import + - YT-DL import + - project list/search + +Fixes implemented: + +1. `frontend/src/App.tsx` + - Replaced library-shell composition with the route-based StemEngine shell + that mounts `Sidebar` + workflow pages. + - Restored route mapping: + - `/` → `Separator` + - `/projects/:projectId` → `ProjectDetail` + - `/settings` → `Settings` + - Wired sidebar state + `activeProjectId` with route parsing. + +2. Runtime refresh + - Recreated `stemengine-webui` and `stemengine-sing` containers to ensure + latest source is live. + +Validation: +- `frontend` build passes (`npm run build`). +- `http://127.0.0.1:5174/` responds `200`. +- Served sidebar source confirms `SubsonicPanel` and `YtDlPanel` are present. + +### 2026-04-06 investigation — WebUI (5174) vs SingUI (3001) conflation root cause + +Investigation outcome: + +- The repeated confusion came from architecture coupling: + - `stemengine-webui` and `stemengine-sing` were both built from the same + frontend context (`appdata/stemengine/frontend`), + - both used the same image digest, + - both mounted the same bind source and node_modules volume. + +Implication: + +- Any shell-level edit in `frontend/src/App.tsx` affects **both** ports unless a + strict service-mode gate exists. + +Operational findings: + +- Runtime containers confirm compose source: + - config file: `/home/translator/docker/stemengine.yml` + - working dir: `/home/translator/docker` +- Workspace contains another `stemengine.yml` under + `/home/translator/docker/appdata/stemengine/`, which increases edit-path + ambiguity during rapid changes. + +Documented mitigation path: + +- Added incident write-up and guardrail recommendations to + `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md`: + - explicit `VITE_UI_FLAVOR` split (`webui|sing`), + - canonical compose file policy, + - startup/CI smoke checks for `5174` and `3001` shell markers. + +### 2026-04-06 implementation — `VITE_UI_FLAVOR` split completed + +Implemented the recommended mode split to prevent future WebUI/SingUI conflation. + +Changes: + +1. `frontend/src/App.tsx` + - Added explicit runtime shell selection: + - `VITE_UI_FLAVOR=webui` → StemEngine workflow shell + - `VITE_UI_FLAVOR=sing` → Sing/Subsonic navigation shell + +2. `stemengine.yml` + - `stemengine-webui` now sets `VITE_UI_FLAVOR=webui` + - `stemengine-sing` now sets `VITE_UI_FLAVOR=sing` + +Validation: +- `frontend` build passes. +- Compose config passes. +- Container env inspection confirms flavor values are set correctly per service. + +### 2026-04-06 planning update — SingUI Subsonic parity + process-action roadmap + +Planned and documented the next execution slice for SingUI (`3001`): + +- Feishin/Navidrome-style browse parity over Subsonic (tracks/albums/artists/playlists) +- scalable paged browse endpoints on backend +- explicit track/album detail pages in Sing shell +- per-song `Process` and per-album `Process Album` actions with enforced button order + (`Process` before favorite) +- shared convert-status lifecycle (`Queued`, `Running`, `Ready`, `Retry`) +- readiness propagation into karaoke launch flows + +Primary documentation target: + +- `docs/KARAOKE_FRONTEND_STEMENGINE_CONNECTIVITY_PLAN.md` + - added section: `## 32) 2026-04-06 execution plan — SingUI Subsonic browse parity + StemEngine process actions` + +### 2026-04-06 implementation — SingUI detail browse + per-song/per-album process actions + +Implemented a concrete execution slice for SingUI (`3001`) aligned with Feishin/Navidrome browse patterns. + +Changes shipped: + +1. Detail routes and shell wiring + - `frontend/src/App.tsx` + - Added Sing-mode route handling for: + - `/albums/:albumId` + - `/tracks/:trackId` + +2. New detail pages + - `frontend/src/pages/AlbumDetail.tsx` (new) + - header actions ordered as `Process Album` then `Favorite` + - per-track rows include `Process` then `Favorite` + - `frontend/src/pages/TrackDetail.tsx` (new) + - actions ordered as `Process` then `Favorite` + +3. Browse pages linked to detail pages + - `frontend/src/pages/Albums.tsx` + - switched album browse source to `listSubsonicAlbums` for stable ids + - added links to album detail route + - process fallback: fetch album detail when local song map is not present + - `frontend/src/pages/Tracks.tsx` + - song title links to track detail route + - `frontend/src/pages/Sing.tsx` + - tracks/albums lists link to detail routes + +Validation: +- `npm run build` passes for frontend. +- Containers recreated for webui/sing. +- Runtime source checks confirm: + - Sing detail routes are present, + - album and track process controls are present in served pages. + +### 2026-04-06 UX fix — SingUI settings close affordance + +Issue: +- SingUI settings opened as fullscreen with no explicit close button. + +Fix: +- Updated `frontend/src/App.tsx` (`SingUiShell`) to include: + - `closeSettings()` handler: + - `navigate(-1)` when history exists, + - fallback to `/sing`. + - top settings toolbar with `Close` button and `X` icon. + +Validation: +- Runtime source check on `3001` confirms: + - `SingUI Settings` header present, + - `closeSettings` handler present. + +### 2026-04-06 SingUI compatibility fix — albums load, tracks/artists fail + +Symptom: +- In SingUI, Subsonic albums loaded but tracks/artists did not. + +Cause: +- Track/artist rendering relied on wildcard search (`/api/subsonic/search?q=*`). +- Target Subsonic-compatible server supports browse endpoints better than wildcard + search behavior. + +Fixes applied: + +1. `frontend/src/hooks/useSubsonicLibrary.ts` + - Added fallback for wildcard search failures: + - fetch album list, + - fetch album detail per album, + - flatten + dedupe songs for track consumption. + +2. `frontend/src/pages/Artists.tsx` + - Moved artists page to direct endpoint model (`listSubsonicArtists`) instead + of deriving artists from wildcard track search. + +Validation: +- Frontend build passes. +- Containers recreated. +- Served source verifies: + - library fallback path present, + - artists page wired to artist browse endpoint. + +### 2026-04-06 fix — SingUI Subsonic connect 500 (proxy target) + +Reported symptom: +- Subsonic connect from SingUI failed with `500`, while WebUI Subsonic search worked. + +Root cause: +- Vite dev proxy in current frontend pointed `/api` to `http://localhost:8000`. +- In Docker, that resolves to the frontend container itself, not backend service, + causing proxy errors for SingUI requests using relative `/api`. + +Implemented fix: + +1. `frontend/vite.config.ts` + - moved proxy target to env-driven Docker-safe value: + - `VITE_API_PROXY_TARGET` or fallback `http://stemengine:8000` + +2. `stemengine.yml` + - added for both `stemengine-webui` and `stemengine-sing`: + - `VITE_API_PROXY_TARGET=http://stemengine:8000` + +Validation: +- `GET http://127.0.0.1:3001/api/subsonic/config` returns `200` after recreate. diff --git a/README.md b/README.md index b56094f..4650e40 100755 --- a/README.md +++ b/README.md @@ -126,6 +126,8 @@ All configuration is via environment variables. The `docker-compose.yml` accepts | `GABOX_SMALL_MODEL_PREFERRED_FOR_LOW_VRAM` | `false` | Reserved policy flag for low-VRAM auto-preference workflows | | `STEMENGINE_LYRIC_SEGMENTER` | `auto` | Lyric line splitter strategy: `auto`, `karaoke_processor`, `legacy` | | `STEMENGINE_LYRIC_MAX_LINE_LENGTH` | `36` | Max line length target used by karaoke lyric segmentation | +| `STEMENGINE_KARAOKE_EXPORT_DIR` | empty | Optional global `.sek` export directory inside the container. If empty, exports go under each project (`Exports/StemEngineKaraoke`). | +| `SEK_EXPORTS` | `${SEFOLDER}/sek_exports` | Host path mounted to `/app/media/sek_exports` for centralized `.sek` package output. | | `TZ` | `UTC` | Timezone | | `NAVSERVER` | — | Subsonic server URL (can also be set in the UI) | | `NAVUSER` | — | Subsonic username | diff --git a/backend/config.py b/backend/config.py index bb4a37b..6afcc18 100755 --- a/backend/config.py +++ b/backend/config.py @@ -41,6 +41,10 @@ JOBS_DIR = Path(os.environ.get("JOBS_DIR", str(MEDIA_DIR / "jobs"))) PROJECTS_DIR = Path(os.environ.get("PROJECTS_DIR", str(MEDIA_DIR / "projects"))) DB_PATH = Path(os.environ.get("DB_PATH", str(MEDIA_DIR / "db" / "stemengine.db"))) LRC_SYNC_DIR = Path(os.environ.get("LRC_SYNC_DIR", str(MEDIA_DIR / "lrc_sync"))) +# Optional global output directory for .sek packages. +# - empty (default): write to per-project path /Exports/StemEngineKaraoke +# - set: write to this directory (absolute path recommended), grouped by project name +STEMENGINE_KARAOKE_EXPORT_DIR = os.environ.get("STEMENGINE_KARAOKE_EXPORT_DIR", "").strip() # BS-RoFormer model directory BS_ROFORMER_MODEL_DIR = Path(os.environ.get("BS_ROFORMER_MODEL_DIR", "/opt/bs_roformer_models")) diff --git a/backend/main.py b/backend/main.py index ce2342f..e448d3e 100755 --- a/backend/main.py +++ b/backend/main.py @@ -1,10 +1,11 @@ """ StemEngine — FastAPI application entry point. -Mounts all API routers and serves the built React frontend as static files. +Mounts API routers and optionally serves legacy static WebUI when explicitly enabled. """ import json import logging import logging.config +import os import warnings from contextlib import asynccontextmanager from pathlib import Path @@ -39,7 +40,7 @@ from fastapi.staticfiles import StaticFiles from fastapi.responses import FileResponse from . import job_manager as jm -from .routers import separate, transcribe, abc_convert, pipeline, jobs, lrc, subsonic, projects, models, lyric_transcribe, system, settings +from .routers import separate, transcribe, abc_convert, pipeline, jobs, lrc, subsonic, projects, models, lyric_transcribe, system, settings, karaoke_sek from .config import SUBSONIC_CONFIG_PATH from .app_settings import settings as app_settings from .db import init_db @@ -100,9 +101,15 @@ def _include_routers(app: FastAPI) -> None: app.include_router(lyric_transcribe.router) app.include_router(system.router) app.include_router(settings.router) + app.include_router(karaoke_sek.router) def _mount_static(app: FastAPI) -> None: + # Legacy behavior (backend-served frontend) is opt-in only. + # Default runtime is API-only with separate WebUI/SingUI services. + if os.environ.get("BACKEND_SERVE_LEGACY_WEBUI", "false").lower() != "true": + return + # Serve built React frontend from /app/backend/static # Mount order matters: API routes always win over static assets. _static_dir = Path(__file__).parent / "static" diff --git a/backend/repositories/jobs.py b/backend/repositories/jobs.py index 088e0a1..523ca1b 100644 --- a/backend/repositories/jobs.py +++ b/backend/repositories/jobs.py @@ -100,7 +100,7 @@ def append_files(job_id: str, new_files: list) -> bool: def list_completed_separation_candidates() -> list[JobRecord]: with _session() as session: - return ( + rows = ( session.query(JobRecord) .filter( JobRecord.job_type.in_(["separate", "pipeline"]), @@ -108,6 +108,13 @@ def list_completed_separation_candidates() -> list[JobRecord]: ) .all() ) + candidates: list[JobRecord] = [] + for row in rows: + result = row.result if isinstance(row.result, dict) else {} + if result.get("reprocess"): + continue + candidates.append(row) + return candidates def list_terminal_unlinked_older_than(older_than: datetime, limit: int = 200) -> list[str]: diff --git a/backend/routers/karaoke_sek.py b/backend/routers/karaoke_sek.py new file mode 100644 index 0000000..b287063 --- /dev/null +++ b/backend/routers/karaoke_sek.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +from fastapi import APIRouter, HTTPException, Query +from fastapi.responses import Response + +from ..services.project_service_common import ProjectOperationError +from ..services.sek_library_service import ( + get_sek_asset, + get_sek_manifest, + list_sek_packages, +) + +router = APIRouter(prefix="/api/karaoke-sek", tags=["karaoke-sek"]) + + +@router.get("/library") +def list_library(folder: str | None = Query(default=None, description="Optional SEK folder override")): + try: + return list_sek_packages(folder) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.get("/packages/{package_id}") +def get_manifest(package_id: str, folder: str | None = Query(default=None, description="Optional SEK folder override")): + try: + return get_sek_manifest(package_id, folder) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.get("/packages/{package_id}/asset") +def get_asset( + package_id: str, + path: str = Query(..., description="Inner package path, e.g. stems/vocals.mp3"), + folder: str | None = Query(default=None, description="Optional SEK folder override"), +): + try: + data, mime, filename = get_sek_asset(package_id, path, folder) + return Response( + content=data, + media_type=mime, + headers={ + "Content-Disposition": f'inline; filename="{filename}"', + "Cache-Control": "public, max-age=3600", + }, + ) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc diff --git a/backend/routers/projects.py b/backend/routers/projects.py index 18c03ba..31b25da 100755 --- a/backend/routers/projects.py +++ b/backend/routers/projects.py @@ -22,6 +22,9 @@ from ..services.project_service import ( enqueue_project_mix, enqueue_project_transcription, enqueue_stem_reprocess, + export_project_karaoke_mugen, + export_project_stemengine_karaoke, + get_project_karaoke_config, get_project_cover_art, get_project_or_raise, list_projects as list_projects_service, @@ -31,6 +34,8 @@ from ..services.project_service import ( purge_orphaned_separation_jobs_from_store, rename_project_stem, rescan_project_stems, + sync_project_video_offset, + update_project_karaoke_config, verify_all_project_stems, write_all_project_metadata_snapshots, ) @@ -314,6 +319,31 @@ class DeleteStemRequest(BaseModel): stem_name: str +class KaraokeMugenExportRequest(BaseModel): + default_title_lang: str = "eng" + repository: str = "stemengine.local" + + +class StemEngineKaraokeExportRequest(BaseModel): + package_name: Optional[str] = None + include_video: bool = True + video_source: Optional[str] = None + sync_reference_track: Optional[str] = None + auto_sync: bool = True + + +class ProjectKaraokeConfigPatchRequest(BaseModel): + video_source: Optional[str] = None + include_video: Optional[bool] = None + sync_reference_track: Optional[str] = None + offset_seconds: Optional[float] = None + + +class ProjectVideoSyncRequest(BaseModel): + video_source: str + reference_track: str = "source" + + @router.delete("/{project_id}/stem") def delete_stem_endpoint(project_id: str, body: DeleteStemRequest): """Delete a stem file from disk and remove it from the job record.""" @@ -324,6 +354,77 @@ def delete_stem_endpoint(project_id: str, body: DeleteStemRequest): raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc +@router.post("/{project_id}/export-karaoke-mugen") +def export_karaoke_mugen_endpoint(project_id: str, body: KaraokeMugenExportRequest): + """Export project artifacts as a Karaoke Mugen-compatible package scaffold.""" + project = _get_project_or_404(project_id) + try: + return export_project_karaoke_mugen( + project, + default_title_lang=body.default_title_lang, + repository=body.repository, + ) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.post("/{project_id}/export-sek") +def export_stemengine_karaoke_endpoint(project_id: str, body: StemEngineKaraokeExportRequest): + """Export a StemEngine Karaoke (.sek) package with stems + .elrc (+ optional video).""" + project = _get_project_or_404(project_id) + try: + return export_project_stemengine_karaoke( + project, + package_name=body.package_name, + include_video=body.include_video, + video_source=body.video_source, + sync_reference_track=body.sync_reference_track, + auto_sync=body.auto_sync, + ) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.get("/{project_id}/karaoke-config") +def get_project_karaoke_config_endpoint(project_id: str): + """Return persisted karaoke packaging config for this project.""" + project = _get_project_or_404(project_id) + try: + return get_project_karaoke_config(project) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.patch("/{project_id}/karaoke-config") +def patch_project_karaoke_config_endpoint(project_id: str, body: ProjectKaraokeConfigPatchRequest): + """Update persisted karaoke packaging config for this project.""" + project = _get_project_or_404(project_id) + try: + return update_project_karaoke_config( + project, + video_source=body.video_source, + include_video=body.include_video, + sync_reference_track=body.sync_reference_track, + offset_seconds=body.offset_seconds, + ) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + +@router.post("/{project_id}/sync-video-offset") +def sync_video_offset_endpoint(project_id: str, body: ProjectVideoSyncRequest): + """Estimate and persist sync offset between a linked video and a project track.""" + project = _get_project_or_404(project_id) + try: + return sync_project_video_offset( + project, + video_source=body.video_source, + reference_track=body.reference_track, + ) + except ProjectOperationError as exc: + raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc + + # --------------------------------------------------------------------------- # Stem Rescan # --------------------------------------------------------------------------- diff --git a/backend/routers/settings.py b/backend/routers/settings.py index d62d7ed..8fbaf19 100644 --- a/backend/routers/settings.py +++ b/backend/routers/settings.py @@ -33,6 +33,7 @@ _VALID_WHISPER_MODELS = { "large", "large-v1", "large-v2", "large-v3", "large-v3-turbo", "turbo", } +_VALID_KARAOKE_SOURCE_MODE = {"projects", "sek-folder"} # Default values for all known preference keys _DEFAULTS: dict[str, Any] = { @@ -45,6 +46,8 @@ _DEFAULTS: dict[str, Any] = { "auto_model": "htdemucs", "auto_format": "mp3", "auto_presets": [], + "karaoke_source_mode": "sek-folder", + "karaoke_sek_folder": "", } @@ -101,6 +104,8 @@ class SettingsPatch(BaseModel): auto_model: Optional[str] = None auto_format: Optional[str] = None auto_presets: Optional[list] = None + karaoke_source_mode: Optional[str] = None + karaoke_sek_folder: Optional[str] = None @field_validator("sep_power") @classmethod @@ -120,6 +125,15 @@ class SettingsPatch(BaseModel): ) return v + @field_validator("karaoke_source_mode") + @classmethod + def _validate_karaoke_source_mode(cls, v: Optional[str]) -> Optional[str]: + if v is not None and v not in _VALID_KARAOKE_SOURCE_MODE: + raise ValueError( + f"Unknown karaoke_source_mode '{v}'. Valid values: {sorted(_VALID_KARAOKE_SOURCE_MODE)}" + ) + return v + @router.patch("") def patch_settings(body: SettingsPatch): diff --git a/backend/routers/subsonic.py b/backend/routers/subsonic.py index 5ed03cb..da73f82 100755 --- a/backend/routers/subsonic.py +++ b/backend/routers/subsonic.py @@ -72,8 +72,6 @@ def search( album_artist: str = "", ): """Search songs on the configured Subsonic server.""" - if not any([q.strip(), title.strip(), artist.strip(), album.strip(), album_artist.strip()]): - return [] try: return subsonic_service.search_songs( query=q.strip(), @@ -90,6 +88,72 @@ def search( raise HTTPException(status_code=502, detail=f"Subsonic search failed: {exc}") +@router.get("/playlists") +def list_playlists(): + """List playlists from the configured Subsonic server.""" + try: + return subsonic_service.list_playlists() + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic playlist list failed: {exc}") + + +@router.get("/playlists/{playlist_id}") +def get_playlist(playlist_id: str): + """Return playlist metadata and songs for a playlist id.""" + try: + return subsonic_service.get_playlist(playlist_id) + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic playlist fetch failed: {exc}") + + +@router.get("/albums") +def list_albums(offset: int = 0, size: int = 50, query: str = "", artist_id: str = ""): + """List albums from the configured Subsonic server (paged browse).""" + try: + return subsonic_service.list_albums(offset=offset, size=size, query=query.strip(), artist_id=artist_id.strip()) + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic album list failed: {exc}") + + +@router.get("/albums/{album_id}") +def get_album(album_id: str): + """Return album metadata and songs by id.""" + try: + return subsonic_service.get_album(album_id) + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic album fetch failed: {exc}") + + +@router.get("/artists") +def list_artists(offset: int = 0, size: int = 200, query: str = ""): + """List artists from the configured Subsonic server.""" + try: + return subsonic_service.list_artists(offset=offset, size=size, query=query.strip()) + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic artist list failed: {exc}") + + +@router.get("/artists/{artist_id}") +def get_artist(artist_id: str): + """Return artist metadata and albums by id.""" + try: + return subsonic_service.get_artist(artist_id) + except RuntimeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Subsonic artist fetch failed: {exc}") + + class ImportRequest(BaseModel): id: str title: str diff --git a/backend/services/project_assets_service.py b/backend/services/project_assets_service.py index 05bb3b7..137676e 100644 --- a/backend/services/project_assets_service.py +++ b/backend/services/project_assets_service.py @@ -2,13 +2,21 @@ from __future__ import annotations import json import os +import subprocess import shutil +import tempfile +import zipfile from pathlib import Path +from datetime import datetime, timezone from urllib import error as urlerror from urllib import request as urlrequest +from uuid import uuid4 + +import librosa +import numpy as np from .. import job_manager as jm -from ..config import UPLOAD_DIR +from ..config import STEMENGINE_KARAOKE_EXPORT_DIR, UPLOAD_DIR from ..repositories import jobs as jobs_repo from ..repositories import projects as projects_repo from .metadata_util import _read_cover_art, read_metadata @@ -290,3 +298,667 @@ def get_project_cover_art(project: dict) -> tuple[bytes, str]: pass raise ProjectOperationError(404, "No cover art") + + +def _pick_source_media_file(sep_job: dict | None) -> Path | None: + for file_entry in (sep_job or {}).get("files", []): + if file_entry.get("type") != "source": + continue + raw = file_entry.get("path") + if not raw: + continue + candidate = Path(str(raw)) + if candidate.exists() and candidate.is_file(): + return candidate + return None + + +def _cover_extension_from_mime(mime: str | None) -> str: + normalized = str(mime or "").strip().lower() + mapping = { + "image/jpeg": ".jpg", + "image/jpg": ".jpg", + "image/png": ".png", + "image/webp": ".webp", + "image/gif": ".gif", + "image/bmp": ".bmp", + "image/tiff": ".tiff", + } + return mapping.get(normalized, ".jpg") + + +def _build_source_metadata_component(source_media: Path | None) -> tuple[dict, bytes | None, str | None, str | None]: + metadata = { + "source_file": source_media.name if source_media else "", + "title": "", + "artist": "", + "albumartist": "", + "album": "", + "cover_art": None, + } + if source_media is None: + return metadata, None, None, None + + try: + tags = read_metadata(str(source_media)) + metadata["title"] = str(tags.get("title") or "").strip() + metadata["artist"] = str(tags.get("artist") or "").strip() + metadata["albumartist"] = str(tags.get("albumartist") or "").strip() + metadata["album"] = str(tags.get("album") or "").strip() + except Exception: + pass + + cover_bytes: bytes | None = None + cover_mime: str | None = None + + try: + data, mime = _read_cover_art(str(source_media)) + if data: + cover_bytes = data + cover_mime = mime or "image/jpeg" + except Exception: + pass + + if not cover_bytes: + thumbnail_url = _read_source_thumbnail_url(source_media) + if thumbnail_url: + try: + remote_data, remote_mime = _fetch_remote_image(thumbnail_url) + if remote_data: + cover_bytes = remote_data + cover_mime = remote_mime or "image/jpeg" + except Exception: + pass + + if cover_bytes: + ext = _cover_extension_from_mime(cover_mime) + cover_name = f"cover{ext}" + metadata["cover_art"] = { + "file": f"metadata/{cover_name}", + "mime": cover_mime or "image/jpeg", + "bytes": len(cover_bytes), + } + return metadata, cover_bytes, cover_mime, cover_name + + return metadata, None, None, None + + +def _pick_best_lyrics_file(project_root: Path) -> Path | None: + candidates = [ + p for p in project_root.rglob("*") + if p.is_file() and p.suffix.lower() in {".ass", ".lrc", ".elrc"} + ] + if not candidates: + return None + + def priority(path: Path) -> tuple[int, float]: + ext = path.suffix.lower() + weight = 0 if ext == ".ass" else (1 if ext == ".lrc" else 2) + return (weight, -path.stat().st_mtime) + + return sorted(candidates, key=priority)[0] + + +def _pick_best_elrc_file(project_root: Path) -> Path | None: + candidates = [p for p in project_root.rglob("*.elrc") if p.is_file()] + if not candidates: + return None + return sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True)[0] + + +def _karaoke_config_path(project_root: Path) -> Path: + return project_root / "stemengine_karaoke_config.json" + + +def _default_karaoke_config() -> dict: + return { + "video_source": "", + "include_video": True, + "sync_reference_track": "source", + "track_offsets_seconds": {}, + "last_sync": None, + } + + +def _read_karaoke_config(project_root: Path) -> dict: + cfg = _default_karaoke_config() + path = _karaoke_config_path(project_root) + if not path.exists(): + return cfg + try: + raw = json.loads(path.read_text(encoding="utf-8")) + if isinstance(raw, dict): + cfg.update(raw) + except Exception: + pass + cfg["video_source"] = str(cfg.get("video_source") or "").strip() + cfg["sync_reference_track"] = str(cfg.get("sync_reference_track") or "source").strip() or "source" + cfg["include_video"] = bool(cfg.get("include_video", True)) + offsets = cfg.get("track_offsets_seconds") + cfg["track_offsets_seconds"] = offsets if isinstance(offsets, dict) else {} + return cfg + + +def _write_karaoke_config(project_root: Path, cfg: dict) -> dict: + normalized = _default_karaoke_config() + normalized.update(cfg or {}) + normalized["video_source"] = str(normalized.get("video_source") or "").strip() + normalized["sync_reference_track"] = str(normalized.get("sync_reference_track") or "source").strip() or "source" + normalized["include_video"] = bool(normalized.get("include_video", True)) + offsets = normalized.get("track_offsets_seconds") + normalized["track_offsets_seconds"] = offsets if isinstance(offsets, dict) else {} + _karaoke_config_path(project_root).write_text( + json.dumps(normalized, ensure_ascii=False, indent=2), + encoding="utf-8", + ) + return normalized + + +def get_project_karaoke_config(project: dict) -> dict: + project_root = project_output_dir(project) + if not project_root.exists(): + raise ProjectOperationError(404, "Project directory not found") + cfg = _read_karaoke_config(project_root) + return { + "project_id": project.get("id"), + "project_name": project.get("name"), + "config": cfg, + } + + +def update_project_karaoke_config( + project: dict, + *, + video_source: str | None = None, + include_video: bool | None = None, + sync_reference_track: str | None = None, + offset_seconds: float | None = None, +) -> dict: + project_root = project_output_dir(project) + if not project_root.exists(): + raise ProjectOperationError(404, "Project directory not found") + + cfg = _read_karaoke_config(project_root) + if video_source is not None: + cfg["video_source"] = str(video_source).strip() + if include_video is not None: + cfg["include_video"] = bool(include_video) + if sync_reference_track is not None and str(sync_reference_track).strip(): + cfg["sync_reference_track"] = str(sync_reference_track).strip() + if offset_seconds is not None: + track = str(cfg.get("sync_reference_track") or "source") + offsets = dict(cfg.get("track_offsets_seconds") or {}) + offsets[track] = float(offset_seconds) + cfg["track_offsets_seconds"] = offsets + cfg["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + + written = _write_karaoke_config(project_root, cfg) + return { + "success": True, + "project_id": project.get("id"), + "config": written, + } + + +def _resolve_reference_track_file(project: dict, track_name: str) -> Path: + sep_job = jobs_repo.get(project["sep_job_id"]) or {} + if track_name == "source": + source = _pick_source_media_file(sep_job) + if source is None: + raise ProjectOperationError(404, "No source media file found for project") + return source + + stems = _collect_project_stems(sep_job) + for stem in stems: + if str(stem["name"]).lower() == track_name.lower(): + return Path(stem["path"]) + raise ProjectOperationError(404, f"Reference track not found: {track_name}") + + +def _looks_like_url(value: str) -> bool: + return value.startswith("http://") or value.startswith("https://") + + +def _download_video_from_url(video_url: str, target_dir: Path) -> Path: + target_dir.mkdir(parents=True, exist_ok=True) + out_tpl = str(target_dir / "video.%(ext)s") + cmd = [ + "yt-dlp", + "--no-playlist", + "-f", + "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best", + "-o", + out_tpl, + video_url, + ] + completed = subprocess.run(cmd, capture_output=True, text=True) + if completed.returncode != 0: + msg = (completed.stderr or completed.stdout or "yt-dlp failed").strip() + raise ProjectOperationError(400, f"Failed to fetch video URL: {msg}") + + candidates = sorted(target_dir.glob("video.*"), key=lambda p: p.stat().st_mtime, reverse=True) + if not candidates: + raise ProjectOperationError(400, "Failed to download video from URL") + return candidates[0] + + +def _resolve_video_source_to_file(project_root: Path, source: str) -> Path: + cleaned = str(source or "").strip() + if not cleaned: + raise ProjectOperationError(400, "Video source is empty") + + if _looks_like_url(cleaned): + assets_dir = project_root / "Assets" / "Video" + return _download_video_from_url(cleaned, assets_dir) + + candidate = Path(cleaned) + if not candidate.is_absolute(): + candidate = (project_root / candidate).resolve() + if not candidate.exists() or not candidate.is_file(): + raise ProjectOperationError(404, f"Video file not found: {cleaned}") + return candidate + + +def _estimate_track_offset_seconds(reference_file: Path, video_file: Path) -> float: + sr = 22050 + duration = 120.0 + y_ref, _ = librosa.load(str(reference_file), sr=sr, mono=True, offset=0.0, duration=duration) + y_vid, _ = librosa.load(str(video_file), sr=sr, mono=True, offset=0.0, duration=duration) + if y_ref.size == 0 or y_vid.size == 0: + raise ProjectOperationError(400, "Could not decode audio for sync") + + ref_env = librosa.onset.onset_strength(y=y_ref, sr=sr) + vid_env = librosa.onset.onset_strength(y=y_vid, sr=sr) + if ref_env.size < 16 or vid_env.size < 16: + raise ProjectOperationError(400, "Not enough audio detail to estimate sync offset") + + ref_env = ref_env - np.mean(ref_env) + vid_env = vid_env - np.mean(vid_env) + corr = np.correlate(vid_env, ref_env, mode="full") + lag = int(np.argmax(corr) - (ref_env.size - 1)) + + hop_length = 512 + offset_seconds = float((lag * hop_length) / sr) + return round(offset_seconds, 3) + + +def sync_project_video_offset( + project: dict, + *, + video_source: str, + reference_track: str = "source", +) -> dict: + project_root = project_output_dir(project) + if not project_root.exists(): + raise ProjectOperationError(404, "Project directory not found") + + ref_file = _resolve_reference_track_file(project, reference_track) + video_file = _resolve_video_source_to_file(project_root, video_source) + offset_seconds = _estimate_track_offset_seconds(ref_file, video_file) + + cfg = _read_karaoke_config(project_root) + cfg["video_source"] = str(video_source).strip() + cfg["sync_reference_track"] = reference_track + offsets = dict(cfg.get("track_offsets_seconds") or {}) + offsets[reference_track] = offset_seconds + cfg["track_offsets_seconds"] = offsets + cfg["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + written = _write_karaoke_config(project_root, cfg) + + return { + "success": True, + "project_id": project.get("id"), + "reference_track": reference_track, + "offset_seconds": offset_seconds, + "resolved_video": str(video_file), + "config": written, + } + + +def _collect_project_stems(sep_job: dict | None) -> list[dict]: + stems: list[dict] = [] + for file_entry in (sep_job or {}).get("files", []): + if file_entry.get("type") != "stem": + continue + raw_path = file_entry.get("path") + if not raw_path: + continue + path = Path(str(raw_path)) + if not path.exists() or not path.is_file(): + continue + stems.append( + { + "name": str(file_entry.get("stem") or path.stem), + "path": path, + "filename": path.name, + } + ) + return stems + + +def _pick_optional_video_file(project_root: Path, sep_job: dict | None) -> Path | None: + video_exts = {".mp4", ".mkv", ".webm", ".mov", ".m4v"} + + source_media = _pick_source_media_file(sep_job) + if source_media and source_media.suffix.lower() in video_exts: + return source_media + + candidates = [ + p + for p in project_root.rglob("*") + if p.is_file() and p.suffix.lower() in video_exts + ] + if not candidates: + return None + return sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True)[0] + + +def _sanitize_filename_component(value: str) -> str: + bad = '<>:"/\\|?*' + cleaned = "".join("_" if ch in bad or ord(ch) < 32 else ch for ch in (value or "").strip()) + cleaned = " ".join(cleaned.split()) + return cleaned.strip(". ") + + +def export_project_stemengine_karaoke( + project: dict, + package_name: str | None = None, + include_video: bool = True, + video_source: str | None = None, + sync_reference_track: str | None = None, + auto_sync: bool = True, +) -> dict: + """ + Build a StemEngine Karaoke (.sek) package for a project. + + A .sek file is a ZIP archive with this layout: + - manifest.json + - stems/* + - lyrics/*.elrc + - video/* (optional) + """ + sep_job = jobs_repo.get(project["sep_job_id"]) or {} + project_root = project_output_dir(project) + if not project_root.exists(): + raise ProjectOperationError(404, "Project directory not found") + + stems = _collect_project_stems(sep_job) + if not stems: + raise ProjectOperationError(404, "No stem files found for project") + + elrc_path = _pick_best_elrc_file(project_root) + if elrc_path is None: + raise ProjectOperationError(404, "No .elrc lyrics file found for project") + + cfg = _read_karaoke_config(project_root) + if video_source is not None: + cfg["video_source"] = str(video_source).strip() + if sync_reference_track is not None and str(sync_reference_track).strip(): + cfg["sync_reference_track"] = str(sync_reference_track).strip() + + # Persist any explicit overrides so project config remains the source of truth. + cfg = _write_karaoke_config(project_root, cfg) + + cfg_include_video = bool(cfg.get("include_video", True)) + effective_include_video = bool(include_video and cfg_include_video) + + video_path: Path | None = None + configured_source = str(cfg.get("video_source") or "").strip() + if effective_include_video and configured_source: + try: + video_path = _resolve_video_source_to_file(project_root, configured_source) + except ProjectOperationError: + video_path = None + if effective_include_video and video_path is None: + video_path = _pick_optional_video_file(project_root, sep_job) + + warnings: list[str] = [] + + # Automatic synchronization: when video is requested and a configured source exists, + # estimate and persist offset for the selected reference track before packaging. + auto_sync_applied = False + auto_sync_offset: float | None = None + reference_track = str(cfg.get("sync_reference_track") or "source") + if auto_sync and effective_include_video and configured_source: + try: + ref_file = _resolve_reference_track_file(project, reference_track) + resolved_video_for_sync = _resolve_video_source_to_file(project_root, configured_source) + estimated = _estimate_track_offset_seconds(ref_file, resolved_video_for_sync) + + offsets = dict(cfg.get("track_offsets_seconds") or {}) + offsets[reference_track] = estimated + cfg["track_offsets_seconds"] = offsets + cfg["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + cfg = _write_karaoke_config(project_root, cfg) + + auto_sync_applied = True + auto_sync_offset = estimated + except ProjectOperationError as exc: + warnings.append(f"Auto-sync failed: {exc.detail}") + except Exception: + warnings.append("Auto-sync failed due to an unexpected error") + + stem_count = len(stems) + now_iso = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + + source_media = _pick_source_media_file(sep_job) + source_metadata, cover_bytes, _cover_mime, cover_name = _build_source_metadata_component(source_media) + default_base = project.get("name") or (source_media.stem if source_media else project.get("id") or "StemEngine Karaoke") + chosen_base = _sanitize_filename_component(package_name or default_base) or "StemEngine Karaoke" + sek_filename = chosen_base if chosen_base.lower().endswith(".sek") else f"{chosen_base}.sek" + + configured_export_dir = str(STEMENGINE_KARAOKE_EXPORT_DIR or "").strip() + if configured_export_dir: + base_export_dir = Path(configured_export_dir) + if not base_export_dir.is_absolute(): + base_export_dir = project_root / base_export_dir + project_bucket = _sanitize_filename_component(project.get("name") or project.get("id") or "project") or "project" + export_dir = base_export_dir / project_bucket + else: + export_dir = project_root / "Exports" / "StemEngineKaraoke" + export_dir.mkdir(parents=True, exist_ok=True) + sek_path = export_dir / sek_filename + + video_note: str | None = None + if not effective_include_video: + video_note = "No video included: video packaging is disabled." + elif video_path is None: + video_note = "No video included: no video source/file could be resolved for this package." + + manifest = { + "format": "stemengine-karaoke", + "version": 1, + "created_at": now_iso, + "project": { + "id": project.get("id"), + "name": project.get("name"), + }, + "metadata": source_metadata, + "contents": { + "lyrics": f"lyrics/{elrc_path.name}", + "video": f"video/{video_path.name}" if video_path else None, + "stems": [ + { + "name": stem["name"], + "file": f"stems/{stem['filename']}", + "bytes": stem["path"].stat().st_size, + } + for stem in stems + ], + }, + "meta": { + "stem_count": stem_count, + "has_video": bool(video_path), + "video_note": video_note, + "lyrics_type": "elrc", + "synchronization": { + "reference_track": reference_track, + "track_offsets_seconds": cfg.get("track_offsets_seconds") or {}, + "video_source": configured_source, + "last_sync": cfg.get("last_sync"), + }, + }, + } + + with zipfile.ZipFile(sek_path, mode="w", compression=zipfile.ZIP_DEFLATED) as zf: + zf.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2)) + zf.write(elrc_path, arcname=f"lyrics/{elrc_path.name}") + for stem in stems: + zf.write(stem["path"], arcname=f"stems/{stem['filename']}") + if cover_bytes and cover_name: + zf.writestr(f"metadata/{cover_name}", cover_bytes) + if video_path: + zf.write(video_path, arcname=f"video/{video_path.name}") + + if effective_include_video and video_path is None: + warnings.append("No video file found; packaged audio stems + .elrc only.") + + return { + "success": True, + "project_id": project.get("id"), + "project_name": project.get("name"), + "sek_path": str(sek_path), + "package_name": sek_filename, + "export_dir": str(export_dir), + "stem_count": stem_count, + "lyrics": str(elrc_path), + "video": str(video_path) if video_path else "", + "auto_sync_applied": auto_sync_applied, + "auto_sync_reference_track": reference_track, + "auto_sync_offset_seconds": auto_sync_offset, + "warnings": warnings, + } + + +def export_project_karaoke_mugen( + project: dict, + default_title_lang: str = "eng", + repository: str = "stemengine.local", +) -> dict: + """ + Build a Karaoke Mugen-compatible export folder for a StemEngine project. + + Output layout: + /Exports/KaraokeMugen// + - .kara.json + - + - (preferred .ass, fallback .lrc/.elrc) + """ + sep_job = jobs_repo.get(project["sep_job_id"]) or {} + media_path = _pick_source_media_file(sep_job) + if media_path is None: + raise ProjectOperationError(404, "No source media file found for project") + + project_root = project_output_dir(project) + if not project_root.exists(): + raise ProjectOperationError(404, "Project directory not found") + + lyrics_path = _pick_best_lyrics_file(project_root) + + kid = str(uuid4()) + now_iso = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") + export_dir = project_root / "Exports" / "KaraokeMugen" / kid + export_dir.mkdir(parents=True, exist_ok=True) + + media_dest = export_dir / media_path.name + shutil.copy2(media_path, media_dest) + + lyrics_entries = [] + warnings: list[str] = [] + if lyrics_path is not None: + lyrics_dest = export_dir / lyrics_path.name + shutil.copy2(lyrics_path, lyrics_dest) + lyrics_entries.append( + { + "default": True, + "filename": lyrics_dest.name, + "version": "Default", + } + ) + if lyrics_dest.suffix.lower() != ".ass": + warnings.append( + "Lyrics file is not ASS; convert to .ass in Aegisub for best Karaoke Mugen compatibility." + ) + else: + warnings.append( + "No lyrics file (.ass/.lrc/.elrc) was found in the project; add one before importing into Karaoke Mugen." + ) + + title_lang = (default_title_lang or "eng").strip().lower() or "eng" + title_value = project.get("name") or media_path.stem + year_value = datetime.now(timezone.utc).year + + kara_payload = { + "header": { + "version": 4, + "description": "Karaoke Mugen Karaoke Data File", + }, + "medias": [ + { + "default": True, + "duration": 0, + "filename": media_dest.name, + "filesize": media_dest.stat().st_size, + "lyrics": lyrics_entries, + "version": "Default", + } + ], + "data": { + "created_at": now_iso, + "ignoreHooks": False, + "kid": kid, + "modified_at": now_iso, + "repository": (repository or "stemengine.local").strip() or "stemengine.local", + "songname": title_value, + "tags": { + "authors": [], + "collections": [], + "creators": [], + "families": [], + "genres": [], + "groups": [], + "langs": [], + "misc": [], + "origins": [], + "platforms": [], + "series": [], + "singers": [], + "singergroups": [], + "songtypes": [], + "songwriters": [], + "versions": [], + "warnings": [], + "franchises": [], + }, + "titles": { + title_lang: title_value, + }, + "titles_default_language": title_lang, + "titles_aliases": [], + "year": year_value, + }, + "meta": { + "stemengine": { + "project_id": project.get("id"), + "project_name": project.get("name"), + "source_media": str(media_path), + "source_lyrics": str(lyrics_path) if lyrics_path else None, + "warnings": warnings, + } + }, + } + + kara_path = export_dir / f"{kid}.kara.json" + kara_path.write_text(json.dumps(kara_payload, ensure_ascii=False, indent=2), encoding="utf-8") + + return { + "success": True, + "project_id": project.get("id"), + "project_name": project.get("name"), + "kid": kid, + "export_dir": str(export_dir), + "kara_json": str(kara_path), + "media": str(media_dest), + "lyrics": str((export_dir / lyrics_path.name) if lyrics_path else ""), + "warnings": warnings, + } diff --git a/backend/services/project_reprocess_service.py b/backend/services/project_reprocess_service.py index 5f1e938..27aa09d 100644 --- a/backend/services/project_reprocess_service.py +++ b/backend/services/project_reprocess_service.py @@ -47,6 +47,15 @@ def enqueue_stem_reprocess( project_dir = project_output_dir(project) reprocess_dir = project_dir / "Stems" / "Reprocessed" / _safe_reprocess_folder_name(stem_name) job_id = jm.create_job("separate") + jobs_repo.update( + job_id, + result={ + "reprocess": True, + "parent_job_id": project["sep_job_id"], + "parent_project_id": project["id"], + "source_stem": stem_name, + }, + ) jm.submit_gpu( run_separation, job_id, diff --git a/backend/services/project_service.py b/backend/services/project_service.py index 025e928..2871186 100644 --- a/backend/services/project_service.py +++ b/backend/services/project_service.py @@ -8,12 +8,17 @@ from .project_assets_service import ( build_project_detail, collect_related_job_ids, delete_project_stem, + export_project_stemengine_karaoke, delete_project_with_related_jobs, + export_project_karaoke_mugen, + get_project_karaoke_config, get_project_cover_art, get_project_or_raise, list_projects, rename_project_stem, rescan_project_stems, + sync_project_video_offset, + update_project_karaoke_config, ) from .project_cleanup_service import ( cleanup_all_lrc_output_files, diff --git a/backend/services/sek_library_service.py b/backend/services/sek_library_service.py new file mode 100644 index 0000000..794b8a9 --- /dev/null +++ b/backend/services/sek_library_service.py @@ -0,0 +1,152 @@ +from __future__ import annotations + +import hashlib +import json +import mimetypes +from pathlib import Path +from typing import Any +from zipfile import BadZipFile, ZipFile + +from ..config import SETTINGS_PATH +from .project_service_common import ProjectOperationError + + +def _load_settings() -> dict[str, Any]: + if not SETTINGS_PATH.exists(): + return {} + try: + raw = json.loads(SETTINGS_PATH.read_text(encoding="utf-8")) + return raw if isinstance(raw, dict) else {} + except Exception: + return {} + + +def _resolve_folder_path(folder: str | None = None) -> Path: + if folder and str(folder).strip(): + return Path(str(folder).strip()) + settings = _load_settings() + configured = str(settings.get("karaoke_sek_folder") or "").strip() + if not configured: + raise ProjectOperationError(400, "No SEK folder configured") + return Path(configured) + + +def _package_id(path: Path) -> str: + return hashlib.sha1(str(path.resolve()).encode("utf-8")).hexdigest()[:16] + + +def _safe_zip_member(member: str) -> bool: + if not member: + return False + p = Path(member) + if p.is_absolute(): + return False + return ".." not in p.parts + + +def _read_manifest(package_path: Path) -> dict[str, Any]: + with ZipFile(package_path, "r") as zf: + try: + raw = zf.read("manifest.json") + except KeyError as exc: + raise ProjectOperationError(400, f"Package missing manifest.json: {package_path.name}") from exc + try: + parsed = json.loads(raw.decode("utf-8")) + if not isinstance(parsed, dict): + raise ValueError("manifest root must be object") + return parsed + except Exception as exc: + raise ProjectOperationError(400, f"Invalid manifest.json in {package_path.name}") from exc + + +def list_sek_packages(folder: str | None = None) -> dict[str, Any]: + base = _resolve_folder_path(folder) + if not base.exists() or not base.is_dir(): + raise ProjectOperationError(404, f"SEK folder does not exist: {base}") + + packages: list[dict[str, Any]] = [] + for package_path in sorted(base.glob("*.sek"), key=lambda p: p.stat().st_mtime, reverse=True): + warnings: list[str] = [] + manifest: dict[str, Any] | None = None + valid = True + + try: + manifest = _read_manifest(package_path) + except (ProjectOperationError, BadZipFile): + valid = False + warnings.append("Unreadable package or missing manifest.json") + + contents = (manifest or {}).get("contents") if isinstance(manifest, dict) else {} + stems = contents.get("stems") if isinstance(contents, dict) else [] + lyrics = contents.get("lyrics") if isinstance(contents, dict) else "" + video = contents.get("video") if isinstance(contents, dict) else "" + + title = ( + ((manifest or {}).get("project") or {}).get("name") + if isinstance((manifest or {}).get("project"), dict) + else None + ) or package_path.stem + + if valid and not lyrics: + warnings.append("manifest contents.lyrics is missing") + if valid and not isinstance(stems, list): + warnings.append("manifest contents.stems is not a list") + + packages.append( + { + "id": _package_id(package_path), + "filename": package_path.name, + "path": str(package_path.resolve()), + "title": title, + "valid": valid, + "stem_count": len(stems) if isinstance(stems, list) else 0, + "has_video": bool(video), + "lyrics": lyrics if isinstance(lyrics, str) else "", + "mtime": package_path.stat().st_mtime, + "warnings": warnings, + } + ) + + return { + "folder": str(base.resolve()), + "count": len(packages), + "packages": packages, + } + + +def _resolve_package_by_id(package_id: str, folder: str | None = None) -> Path: + base = _resolve_folder_path(folder) + if not base.exists() or not base.is_dir(): + raise ProjectOperationError(404, f"SEK folder does not exist: {base}") + + for package_path in base.glob("*.sek"): + if _package_id(package_path) == package_id: + return package_path + raise ProjectOperationError(404, f"Package not found: {package_id}") + + +def get_sek_manifest(package_id: str, folder: str | None = None) -> dict[str, Any]: + package_path = _resolve_package_by_id(package_id, folder) + manifest = _read_manifest(package_path) + return { + "id": package_id, + "filename": package_path.name, + "path": str(package_path.resolve()), + "manifest": manifest, + } + + +def get_sek_asset(package_id: str, inner_path: str, folder: str | None = None) -> tuple[bytes, str, str]: + package_path = _resolve_package_by_id(package_id, folder) + normalized = str(inner_path or "").strip().replace("\\", "/") + if not _safe_zip_member(normalized): + raise ProjectOperationError(400, "Invalid package asset path") + + with ZipFile(package_path, "r") as zf: + names = set(zf.namelist()) + if normalized not in names: + raise ProjectOperationError(404, f"Asset not found in package: {normalized}") + data = zf.read(normalized) + + mime, _ = mimetypes.guess_type(normalized) + return data, (mime or "application/octet-stream"), normalized.split("/")[-1] diff --git a/backend/services/separator_service.py b/backend/services/separator_service.py index a4fad36..b919846 100755 --- a/backend/services/separator_service.py +++ b/backend/services/separator_service.py @@ -1342,6 +1342,8 @@ def _run_separation_impl( progress="Separation complete.", files=all_files, result={ + "reprocess": output_dir_override is not None, + "parent_job_id": parent_job_id if output_dir_override is not None else None, "project_name": proj_name, "project_path": str(dirs['project']), "stems_dir": str(stems_dir), diff --git a/backend/services/subsonic_service.py b/backend/services/subsonic_service.py index c1ef533..a69c6c9 100755 --- a/backend/services/subsonic_service.py +++ b/backend/services/subsonic_service.py @@ -264,7 +264,9 @@ def search_songs( x for x in [title.strip(), artist.strip(), album.strip(), album_artist.strip()] if x ) if not effective_query: - return [] + # Browsing mode fallback when no explicit query is provided. + # Most Subsonic-compatible servers accept '*' as wildcard for search3. + effective_query = '*' p = _params(config) # Over-fetch and post-filter so advanced fields (title/album/albumArtist) @@ -319,6 +321,252 @@ def search_songs( return songs[: max(1, int(count or 20))] +def list_playlists() -> list[dict]: + """Return playlists from Subsonic server.""" + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + r = _requests.get(_url(config, 'getPlaylists.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + playlists = resp.get('playlists', {}).get('playlist', []) or [] + results = [] + for item in playlists: + results.append({ + 'id': item.get('id', ''), + 'name': item.get('name', 'Untitled Playlist'), + 'songCount': int(item.get('songCount') or 0), + 'duration': int(item.get('duration') or 0), + 'public': bool(item.get('public', False)), + 'owner': item.get('owner', ''), + 'created': item.get('created', ''), + 'changed': item.get('changed', ''), + }) + return results + + +def get_playlist(playlist_id: str) -> dict: + """Return playlist details with songs.""" + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + p['id'] = playlist_id + r = _requests.get(_url(config, 'getPlaylist.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + playlist = resp.get('playlist') or {} + entries = playlist.get('entry') or [] + + songs = [] + for s in entries: + song_artist = s.get('artist', '') + song_album_artist = s.get('albumArtist', '') + songs.append({ + 'id': s.get('id', ''), + 'title': s.get('title', 'Unknown'), + 'artist': song_album_artist or song_artist, + 'songArtist': song_artist, + 'albumArtist': song_album_artist, + 'album': s.get('album', ''), + 'duration': int(s.get('duration') or 0), + 'suffix': s.get('suffix', 'mp3'), + 'size': int(s.get('size') or 0), + 'bitRate': int(s.get('bitRate') or 0), + }) + + return { + 'id': playlist.get('id', ''), + 'name': playlist.get('name', 'Untitled Playlist'), + 'songCount': int(playlist.get('songCount') or len(songs)), + 'duration': int(playlist.get('duration') or 0), + 'public': bool(playlist.get('public', False)), + 'owner': playlist.get('owner', ''), + 'created': playlist.get('created', ''), + 'changed': playlist.get('changed', ''), + 'songs': songs, + } + + +def _normalize_song(s: dict) -> dict: + song_artist = s.get('artist', '') + song_album_artist = s.get('albumArtist', '') + return { + 'id': s.get('id', ''), + 'title': s.get('title', 'Unknown'), + 'artist': song_album_artist or song_artist, + 'songArtist': song_artist, + 'albumArtist': song_album_artist, + 'album': s.get('album', ''), + 'duration': int(s.get('duration') or 0), + 'suffix': s.get('suffix', 'mp3'), + 'size': int(s.get('size') or 0), + 'bitRate': int(s.get('bitRate') or 0), + } + + +def list_albums(offset: int = 0, size: int = 50, query: str = '', artist_id: str = '') -> list[dict]: + """Return paged album browse results from Subsonic server.""" + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + p.update({ + 'type': 'alphabeticalByName', + 'size': max(1, min(int(size or 50), 500)), + 'offset': max(0, int(offset or 0)), + }) + if artist_id: + p['artistId'] = artist_id + + r = _requests.get(_url(config, 'getAlbumList2.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + albums = resp.get('albumList2', {}).get('album', []) or [] + q = (query or '').strip().lower() + + results = [] + for album in albums: + title = album.get('name', 'Unknown Album') + artist = album.get('artist', 'Unknown Artist') + if q and q not in title.lower() and q not in artist.lower(): + continue + results.append({ + 'id': album.get('id', ''), + 'name': title, + 'artist': artist, + 'songCount': int(album.get('songCount') or 0), + 'duration': int(album.get('duration') or 0), + 'year': int(album.get('year') or 0) if album.get('year') else None, + 'coverArt': album.get('coverArt', ''), + }) + return results + + +def get_album(album_id: str) -> dict: + """Return album details with tracks.""" + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + p['id'] = album_id + r = _requests.get(_url(config, 'getAlbum.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + album = resp.get('album') or {} + songs = [_normalize_song(s) for s in (album.get('song') or [])] + + return { + 'id': album.get('id', ''), + 'name': album.get('name', 'Unknown Album'), + 'artist': album.get('artist', 'Unknown Artist'), + 'songCount': int(album.get('songCount') or len(songs)), + 'duration': int(album.get('duration') or 0), + 'year': int(album.get('year') or 0) if album.get('year') else None, + 'coverArt': album.get('coverArt', ''), + 'songs': songs, + } + + +def list_artists(offset: int = 0, size: int = 200, query: str = '') -> list[dict]: + """Return artist browse results from Subsonic server. + + Subsonic `getArtists` is index-based (non-paged), so pagination is applied + in-process after flattening. + """ + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + r = _requests.get(_url(config, 'getArtists.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + flat = [] + for bucket in (resp.get('artists', {}).get('index', []) or []): + for artist in (bucket.get('artist', []) or []): + flat.append({ + 'id': artist.get('id', ''), + 'name': artist.get('name', 'Unknown Artist'), + 'albumCount': int(artist.get('albumCount') or 0), + }) + + q = (query or '').strip().lower() + if q: + flat = [a for a in flat if q in a['name'].lower()] + + start = max(0, int(offset or 0)) + end = start + max(1, min(int(size or 200), 1000)) + return flat[start:end] + + +def get_artist(artist_id: str) -> dict: + """Return artist details including albums.""" + config = load_config() + if not config: + raise RuntimeError("Subsonic server not configured") + + p = _params(config) + p['id'] = artist_id + r = _requests.get(_url(config, 'getArtist.view'), params=p, timeout=20) + r.raise_for_status() + resp = r.json().get('subsonic-response', {}) + + if resp.get('status') != 'ok': + msg = resp.get('error', {}).get('message', 'Subsonic API error') + raise RuntimeError(msg) + + artist = resp.get('artist') or {} + albums = [] + for album in (artist.get('album') or []): + albums.append({ + 'id': album.get('id', ''), + 'name': album.get('name', 'Unknown Album'), + 'artist': album.get('artist', artist.get('name', 'Unknown Artist')), + 'songCount': int(album.get('songCount') or 0), + 'duration': int(album.get('duration') or 0), + 'year': int(album.get('year') or 0) if album.get('year') else None, + 'coverArt': album.get('coverArt', ''), + }) + + return { + 'id': artist.get('id', ''), + 'name': artist.get('name', 'Unknown Artist'), + 'albumCount': int(artist.get('albumCount') or len(albums)), + 'albums': albums, + } + + def import_song( song_id: str, title: str, diff --git a/backend/static/index.html b/backend/static/index.html index 5fceff9..6713537 100644 --- a/backend/static/index.html +++ b/backend/static/index.html @@ -19,8 +19,8 @@ - - + +
diff --git a/backend/tests/test_project_reprocess.py b/backend/tests/test_project_reprocess.py index 52ac82f..f8a3815 100644 --- a/backend/tests/test_project_reprocess.py +++ b/backend/tests/test_project_reprocess.py @@ -5,6 +5,54 @@ from backend.tests.support import BackendTestCase class ProjectReprocessTests(BackendTestCase): + def test_reprocess_done_job_is_not_auto_promoted_to_project(self): + from backend import job_manager as jm + + sep_job_id = jm.create_job("separate") + project_dir = Path(self._temp_dir.name) / "media" / "projects" / "Reprocess" + stems_dir = project_dir / "Stems" + stems_dir.mkdir(parents=True, exist_ok=True) + source_path = project_dir / "Reprocess.mp3" + source_path.write_bytes(b"audio") + stem_path = stems_dir / "Reprocess (vocals).mp3" + stem_path.write_bytes(b"audio") + + jm.update_job( + sep_job_id, + status=jm.JobStatus.DONE, + files=[ + {"name": source_path.name, "path": str(source_path), "type": "source"}, + {"name": stem_path.name, "path": str(stem_path), "type": "stem", "stem": "vocals"}, + ], + result={"project_name": "Reprocess", "project_path": str(project_dir), "project_id": "seed"}, + ) + project = jm.find_or_create_project("Reprocess", sep_job_id) + + reprocess_job_id = jm.create_job("separate") + jm.update_job( + reprocess_job_id, + status=jm.JobStatus.DONE, + files=[{"name": "Reprocess (Instrumental).mp3", "path": str(stem_path), "type": "stem", "stem": "instrumental"}], + result={ + "reprocess": True, + "parent_job_id": sep_job_id, + "project_name": "Reprocess (Instrumental)", + "project_path": str(project_dir / "Stems" / "Reprocessed" / "vocals"), + "project_id": None, + }, + ) + + response = self.client.get("/api/projects") + self.assertEqual(response.status_code, 200) + projects = response.json() + + self.assertEqual(len(projects), 1) + self.assertEqual(projects[0]["id"], project["id"]) + self.assertNotIn( + reprocess_job_id, + [p.get("sep_job_id") for p in projects], + ) + def test_reprocess_rejects_unknown_model(self): from backend import job_manager as jm diff --git a/docs/KARAOKE_BOX_PLAN.md b/docs/KARAOKE_BOX_PLAN.md new file mode 100644 index 0000000..2221601 --- /dev/null +++ b/docs/KARAOKE_BOX_PLAN.md @@ -0,0 +1,432 @@ +# StemEngine Karaoke Box — SEK-First Rework (Authoritative) + +> This top section supersedes the older project-direct playback notes below. +> StemEngine karaoke should now target **SEK package playback** as the primary flow. + +## Current Status + +All SEK-first phases in this plan are implemented (Phase 1, Phase 2, Phase 3). + +## Remaining Work + +- No open items remain in the SEK-first phase list. +- Legacy notes below are historical reference only. + +## Core Shift + +SingUI should load songs from a **user-selected SEK folder** and play `.sek` bundles directly, +instead of reading StemEngine project internals at runtime. + +## Execution Phases (SEK-first) + +### Phase 1 — Packaging + Sync Foundation (**implemented 2026-04-06**) + +Delivered: + +- Project-level karaoke packaging config persistence +- Video source linking (URL/path) +- Sync offset estimation against selected reference track +- `.sek` packaging with synchronization metadata in `manifest.json` +- Project page **Package** workflow (`Save`, `Sync Offset`, `Package`) +- Auto Pipeline step for `.sek` export + +Implemented endpoints: + +- `GET /api/projects/{id}/karaoke-config` +- `PATCH /api/projects/{id}/karaoke-config` +- `POST /api/projects/{id}/sync-video-offset` +- `POST /api/projects/{id}/export-sek` + +Implemented UI areas: + +- `ProjectDetail` → `Karaoke Packaging (.sek)` section +- `Settings` / Auto Pipeline → `Export StemEngine .sek Package` + +### Phase 2 — SingUI SEK Folder Library (**implemented 2026-04-06**) + +Delivered: + +- User-set karaoke source mode + SEK folder persisted in app settings + - `karaoke_source_mode`: `projects` | `sek-folder` + - `karaoke_sek_folder`: folder path +- Backend SEK library API: + - `GET /api/karaoke-sek/library` + - `GET /api/karaoke-sek/packages/{package_id}` + - `GET /api/karaoke-sek/packages/{package_id}/asset?path=...` +- Folder scan + `manifest.json` parsing for `.sek` packages +- SingUI karaoke tab source switch: + - Project-linked mode (existing) + - SEK Folder mode (new) +- Settings → Integrations controls for: + - default karaoke source mode + - SEK folder path persistence +- Karaoke player launch from package payload: + - stems from package assets + - `.elrc` from package assets + - optional video from package assets + +### Phase 3 — SEK-first default runtime (**implemented 2026-04-06**) + +Delivered: + +- Default karaoke source mode switched to `sek-folder` + - backend settings defaults now initialize `karaoke_source_mode = sek-folder` + - SingUI fallback default also starts in `sek-folder` mode +- `projects` mode retained as explicit user-select fallback/debug path + +## Packaging Requirements (Project Pages + Auto Pipeline) + +Each project can be prepared for packaging via a **Karaoke Packaging** panel: + +1. Link a video source (YouTube URL or local video path) +2. Choose sync reference track (`source` or any stem) +3. Click **Package** — sync offset is computed automatically +4. Package writes computed per-track offset into `manifest.json` + +The same `.sek` export is available as an **Auto Pipeline** step. + +### Required manifest data in `.sek` + +`manifest.json` must include synchronization metadata: + +- `meta.synchronization.reference_track` +- `meta.synchronization.track_offsets_seconds` +- `meta.synchronization.video_source` +- `meta.synchronization.last_sync` + +This allows playback clients to apply track-aware timing offsets consistently. + +`manifest.json` must also include a source-inherited `metadata` component: + +- `metadata.title` +- `metadata.artist` +- `metadata.albumartist` +- `metadata.album` +- `metadata.source_file` +- `metadata.cover_art` (if available), with the cover image packaged as `metadata/cover.*` + +## SingUI Runtime (SEK Folder Mode) + +Add settings for: + +- `source mode`: `projects` | `sek-folder` +- `sek folder path`: user-defined filesystem path + +When in `sek-folder` mode: + +1. Scan folder for `.sek` +2. Read each `manifest.json` +3. Build song list from package metadata +4. Launch karaoke player from package assets (`stems`, `.elrc`, optional video) + +No direct dependence on project DB/job layout is required for playback. + +## Acceptance Criteria + +- Project pages show a visible **Package** button for `.sek` +- User can link video and reference track; offset is auto-computed during packaging +- Packaged `.sek` writes that offset into `manifest.json` +- Auto Pipeline can export `.sek` +- SingUI can read/play `.sek` from user folder without loading projects directly + +--- + +# Legacy notes (kept for reference) + +**Source analysis:** `johnpc/karaoke-for-jellyfin` (Next.js 15 + Socket.IO) +**Target:** StemEngine SingUI (React + Vite + TanStack Query, port 3001) +**Date:** 2025-06 + +--- + +## What Was Learned From karaoke-for-jellyfin + +### Architecture (3 interfaces) +| Route | Role | +|---|---| +| `/` | Mobile — search Jellyfin library, add songs to queue, reorder | +| `/tv` | TV Display — fullscreen lyrics, state machine, transitions | +| `/admin` | Admin — host controls panel | + +### TV State Machine +``` +waiting ──► playing ──[song ends]──► applause (15s) + ▲ │ + └── [queue empty] ◄──── next-up (15s) ◄─┘ + │ + [has next song]──► playing +``` + +### Key Source Components +- **`KaraokeSessionManager`** (singleton) — in-memory session: queue CRUD, playback state, user management, `skipInProgress` / `songTransitionInProgress` mutex locks, auto-advance timer +- **`server.js`** — custom Next.js server with Socket.IO; events: `join-session`, `add-song`, `remove-song`, `playback-control`, `skip-song`, `song-ended`, `start-next-song`, `user-heartbeat`; TV auto-joins as host on connect +- **`src/types/index.ts`** — `QueueItem`, `KaraokeSession`, `PlaybackState`, `TVDisplayState`, `SongRating`, `TransitionState`, `HostControls`, `SessionSettings`, `ConnectedUser`, full WS event types + +### Type Inventory (relevant subset) + +```ts +// Queue +interface QueueItem { id, mediaItem, addedBy, addedAt, position, status: 'pending'|'playing'|'completed'|'skipped' } + +// Session +interface PlaybackState { isPlaying, currentTime, volume, isMuted, playbackRate, lyricsOffset } +interface HostControls { autoAdvance, allowUserSkip, allowUserRemove, maxSongsPerUser, requireApproval } +interface SessionSettings { maxUsers, lyricsEnabled, crossfadeEnabled, crossfadeDuration } + +// TV display +type TVDisplayState = 'waiting' | 'playing' | 'applause' | 'next-up' | 'transitioning' +interface SongRating { grade: string, score: number, message: string } // random, not mic-computed +interface TransitionState { displayState, completedSong?, nextSong?, rating?, transitionStartTime? } +``` + +### Rating System +Weighted random grade (B+ most common): +``` +A+ 5% A 15% A- 20% B+ 25% B 20% B- 10% C+ 3% C 1% ... F 0.1% +Score range per grade (e.g. A+ → 95–100, B → 75–79) +``` +**Note:** Rating is not computed from mic input — it is purely random. + +### Key Patterns +1. **Mutex locks** on queue/skip/transition ops prevent race conditions +2. **Immediate removal** of completed/skipped items from queue (not left as `completed`) +3. **Deduplication** on reconnect (same user name → old socket removed) +4. **TV auto-join** via `socket.handshake.query.client === 'tv'` — no explicit join needed +5. **`time-update`** sent periodically from TV (every ~2s) to server — server tracks position but does NOT broadcast back (avoids spam) +6. **`lyricsOffset`** in `PlaybackState` — adjustable ±N seconds via playback-control event, broadcast to all clients +7. **Heartbeat** + 5-min stale threshold, cleanup every 2 min + +--- + +## StemEngine Mapping + +| karaoke-for-jellyfin | StemEngine equivalent | +|---|---| +| `MediaItem` (Jellyfin song) | `Project` (StemEngine project with stems + LRC) | +| `streamUrl` | stem audio URLs via `downloadUrl(jobId, name)` | +| `lyricsPath` | LRC/ELRC file from `detail.lrc_jobs` | +| `WaitingScreen` | New `KaraokeWaitingScreen` | +| `LyricsDisplay` | Existing `KaraokePerformanceMode` | +| `RatingAnimation` | New `KaraokeRatingOverlay` | +| `NextSongSplash` | New `KaraokeNextUpSplash` | +| `ApplausePlayer` | New `KaraokeApplausePlayer` | +| `HostControls` overlay | Already in `KaraokePerformanceMode` HUD | +| `QueuePreview` overlay | New `KaraokeQueuePreview` | +| `QRCode` | New `KaraokeQRCode` | +| `KaraokeSessionManager` | Phase 2: `KaraokeSessionManager` or backend WS | +| `server.js` Socket.IO | Phase 2: new backend `/ws/karaoke` endpoint | +| Mobile `/` search + add | Phase 2: new `/karaoke/join` route | + +--- + +## Implementation Phases + +### Phase 1 — Local Queue + Auto-advance *(single-device, no backend changes)* + +**Complexity:** Low +**Value:** High — makes it feel like a karaoke box immediately + +#### 1a. `KaraokeQueueContext` +New file: `src/context/KaraokeQueueContext.tsx` + +```ts +interface KaraokeQueueItem { + projectId: string + title: string + artist?: string + albumArt?: string +} + +interface KaraokeQueueState { + queue: KaraokeQueueItem[] + currentIndex: number // -1 = nothing playing +} + +// Actions +addToQueue(item) +removeFromQueue(projectId) +moveItem(from, to) +advanceQueue() // currentIndex++, or wraps/stops +clearQueue() +setCurrentIndex(n) +``` + +- Persisted to `localStorage` (`karaoke-queue-v1`) with debounce +- Provided at App root level + +#### 1b. Sing.tsx — Queue sidebar +- Add "Add to Queue" button on each karaoke row that is `ready` + has linked project +- New right panel in karaoke tab: drag-reorderable queue list with remove buttons +- "Sing" button now **either** starts a standalone song (no queue) **or** plays from queue position + +#### 1c. Karaoke.tsx — Queue-aware player +- On mount: if entering from queue context (`location.state.fromQueue === true`), read `currentQueueItem` instead of explicit `projectId` +- When song ends (user hits exit / `onExit`): if more songs in queue → call `advanceQueue()` then navigate to next song automatically +- Pass "up next" info to `KaraokePerformanceMode` for HUD display + +#### 1d. `KaraokePerformanceMode` — "Up next" HUD element +- Small persistent chip in bottom-left corner: `⏭ Song Title – Artist` +- Disappears when queue exhausted + +--- + +### Phase 2 — Post-song Transitions (TV State Machine) *(pure client-side)* + +**Complexity:** Medium +**Value:** High — the biggest visual upgrade + +#### New components + +**`src/components/karaoke/KaraokeRatingOverlay.tsx`** +- Props: `song: { title, artist }`, `rating: SongRating`, `onComplete: () => void`, `duration?: number` +- Full-screen overlay on top of player +- Animated grade reveal: big letter grade (A+..F) + score bar + message +- Uses same weighted random generator as karaoke-for-jellyfin +- Auto-dismisses after `duration` ms (default 15 000) + +**`src/components/karaoke/KaraokeNextUpSplash.tsx`** +- Props: `nextSong: KaraokeQueueItem`, `onComplete: () => void`, `duration?: number` +- Full-screen "Next Up" card: album art placeholder + title + artist + countdown ring +- Auto-dismisses after `duration` ms (default 15 000) + +**`src/components/karaoke/KaraokeApplausePlayer.tsx`** +- Renders `