Files
stemengine_old/backend/services/project_assets_service.py
2026-04-23 14:59:57 +09:00

1372 lines
49 KiB
Python

from __future__ import annotations
import colorsys
import io
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 MEDIA_DIR, 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, is_lrc_synced, lyrics_to_plaintext, read_metadata
from .audio_analysis_service import analyze_audio_features
from .project_metadata import patch_project_metadata_audio_features, read_project_metadata
from .project_service_common import ProjectOperationError, _infer_stem_name, project_output_dir
from .separation.output_layout import stem_filename
def _sidecar_path(media_path: Path) -> Path:
return media_path.with_suffix(media_path.suffix + ".json")
def _read_import_sidecar(media_path: Path) -> dict:
sidecar = _sidecar_path(media_path)
if not sidecar.exists():
return {}
try:
raw = json.loads(sidecar.read_text(encoding="utf-8"))
return raw if isinstance(raw, dict) else {}
except Exception:
return {}
def _read_source_thumbnail_url(source_path: Path) -> str:
sidecar = _read_import_sidecar(source_path)
value = str(sidecar.get("thumbnail") or "").strip()
if value.startswith(("http://", "https://")):
return value
return ""
def _read_source_origin_fields(source_path: Path) -> tuple[str, str]:
sidecar = _read_import_sidecar(source_path)
raw_source_url = str(
sidecar.get("source_url")
or sidecar.get("webpage_url")
or sidecar.get("url")
or ""
).strip()
source_url = raw_source_url if raw_source_url.startswith(("http://", "https://")) else ""
navidrome_id = str(
sidecar.get("navidrome_id")
or sidecar.get("subsonic_song_id")
or sidecar.get("song_id")
or sidecar.get("id")
or ""
).strip()
return source_url, navidrome_id
def _fetch_remote_image(url: str) -> tuple[bytes, str | None]:
req = urlrequest.Request(url, headers={"User-Agent": "StemEngine/cover-art-fallback"})
with urlrequest.urlopen(req, timeout=8) as resp:
data = resp.read()
mime = resp.headers.get_content_type() if resp.headers else None
return data, mime
def list_projects() -> list[dict]:
return projects_repo.list_all()
def get_project_or_raise(project_id: str) -> dict:
project = projects_repo.get(project_id)
if project is None:
raise ProjectOperationError(404, f"Project not found: {project_id}")
return project
def collect_related_job_ids(project: dict) -> set[str]:
job_ids = {project["sep_job_id"]}
for job_id in (project.get("trans_jobs") or {}).values():
job_ids.add(job_id)
for job_id in (project.get("abc_jobs") or {}).values():
job_ids.add(job_id)
for job_id in (project.get("lrc_jobs") or {}).values():
job_ids.add(job_id)
if project.get("mix_job_id"):
job_ids.add(project["mix_job_id"])
return job_ids
def delete_project_with_related_jobs(project: dict) -> bool:
"""Delete project files plus the project record and all linked job records."""
project_dir = project_output_dir(project)
if project_dir.exists():
shutil.rmtree(project_dir, ignore_errors=True)
upload_dir = UPLOAD_DIR / project["sep_job_id"]
if upload_dir.exists():
shutil.rmtree(upload_dir, ignore_errors=True)
job_ids_to_delete = collect_related_job_ids(project)
deleted = projects_repo.delete(project["id"])
for job_id in job_ids_to_delete:
jm.delete_job(job_id)
return deleted
def build_project_detail(project: dict) -> dict:
"""Expand linked jobs and source metadata for a project detail response."""
trans_jobs_expanded = {
stem: jobs_repo.get(job_id)
for stem, job_id in (project.get("trans_jobs") or {}).items()
}
abc_jobs_expanded = {
stem: jobs_repo.get(job_id)
for stem, job_id in (project.get("abc_jobs") or {}).items()
}
lrc_jobs_expanded = {
stem: jobs_repo.get(job_id)
for stem, job_id in (project.get("lrc_jobs") or {}).items()
}
sep_job = jobs_repo.get(project["sep_job_id"])
mix_job = jobs_repo.get(project.get("mix_job_id")) if project.get("mix_job_id") else None
source_artist = ""
source_title = ""
source_thumbnail_url = ""
source_file = next(
(file_entry for file_entry in (sep_job or {}).get("files", []) if file_entry.get("type") == "source"),
None,
)
if source_file:
src_path = source_file.get("path", "")
if src_path and Path(src_path).exists():
source_thumbnail_url = _read_source_thumbnail_url(Path(src_path))
try:
meta = read_metadata(src_path)
source_artist = meta.get("artist") or meta.get("albumartist") or ""
source_title = meta.get("title") or ""
except Exception:
pass
preset_name = project.get("preset_name") or ""
return {
**project,
"sep_job": sep_job,
"trans_jobs": trans_jobs_expanded,
"abc_jobs": abc_jobs_expanded,
"lrc_jobs": lrc_jobs_expanded,
"mix_job": mix_job,
"source_artist": source_artist,
"source_title": source_title,
"source_thumbnail_url": source_thumbnail_url,
"preset_name": preset_name,
}
def rename_project_stem(project: dict, stem_name: str, new_name: str) -> dict:
"""Rename a tracked stem on disk and update the separation job record."""
sep_job = jobs_repo.get(project["sep_job_id"])
if sep_job is None:
raise ProjectOperationError(404, "Separation job not found")
cleaned_name = new_name.strip()
if not cleaned_name:
raise ProjectOperationError(400, "New name cannot be empty")
stem_files = list(sep_job.get("files", []))
stem_file = None
stem_idx = None
existing_target = None
for index, file_entry in enumerate(stem_files):
if file_entry.get("stem") == stem_name or file_entry.get("name") == stem_name:
stem_file = file_entry
stem_idx = index
if file_entry.get("stem") == cleaned_name or file_entry.get("name") == cleaned_name:
existing_target = file_entry
if stem_file is None or stem_idx is None:
# Idempotent success: source stem is already at target name.
if existing_target is not None:
return {
"success": True,
"old_name": stem_name,
"new_name": str(existing_target.get("stem") or cleaned_name),
"new_path": str(existing_target.get("path") or ""),
"no_op": True,
}
raise ProjectOperationError(404, f"Stem not found: {stem_name}")
old_path = Path(stem_file["path"])
if not old_path.exists():
raise ProjectOperationError(404, f"Stem file not found on disk: {old_path}")
new_filename = f"{project['name']} ({cleaned_name}){old_path.suffix}"
new_path = old_path.parent / new_filename
if new_path.exists() and new_path != old_path:
raise ProjectOperationError(409, f"A file with name '{new_filename}' already exists")
try:
os.rename(str(old_path), str(new_path))
except Exception as exc:
raise ProjectOperationError(500, f"Failed to rename stem: {exc}") from exc
stem_files[stem_idx] = {
**stem_file,
"name": new_filename,
"stem": cleaned_name,
"path": str(new_path),
}
jobs_repo.update(project["sep_job_id"], files=stem_files)
return {
"success": True,
"old_name": stem_name,
"new_name": cleaned_name,
"new_path": str(new_path),
}
def delete_project_stem(project: dict, stem_name: str) -> dict:
"""Delete a tracked stem file from disk and remove it from the separation job record."""
sep_job = jobs_repo.get(project["sep_job_id"])
if sep_job is None:
raise ProjectOperationError(404, "Separation job not found")
stem_files = list(sep_job.get("files", []))
stem_file = None
stem_idx = None
for index, file_entry in enumerate(stem_files):
if file_entry.get("stem") == stem_name or file_entry.get("name") == stem_name:
stem_file = file_entry
stem_idx = index
break
if stem_file is None or stem_idx is None:
# Idempotent success: already deleted/missing.
return {"success": True, "deleted": stem_name, "no_op": True}
stem_path = Path(stem_file["path"])
if stem_path.exists():
try:
stem_path.unlink()
except Exception as exc:
raise ProjectOperationError(500, f"Failed to delete stem file: {exc}") from exc
stem_files.pop(stem_idx)
jobs_repo.update(project["sep_job_id"], files=stem_files)
return {"success": True, "deleted": stem_name}
def rescan_project_stems(project: dict, audio_exts: set[str]) -> dict:
"""Register untracked audio files under the project's Stems directory."""
sep_job = jobs_repo.get(project["sep_job_id"])
if sep_job is None:
raise ProjectOperationError(404, "Separation job not found")
stems_dir = project_output_dir(project) / "Stems"
if not stems_dir.exists():
raise ProjectOperationError(404, "Stems directory not found")
files = list(sep_job.get("files", []))
tracked_paths = {file_entry["path"] for file_entry in files}
added = []
for audio_file in sorted(stems_dir.rglob("*")):
if not audio_file.is_file():
continue
if audio_file.suffix.lower() not in audio_exts:
continue
if str(audio_file) in tracked_paths:
continue
entry = {
"name": audio_file.name,
"path": str(audio_file),
"type": "stem",
"stem": _infer_stem_name(audio_file.stem, project["name"]),
}
files.append(entry)
tracked_paths.add(str(audio_file))
added.append(entry)
if added:
jobs_repo.update(project["sep_job_id"], files=files)
return {"added": len(added), "stems": [entry["stem"] for entry in added]}
def get_project_cover_art(project: dict) -> tuple[bytes, str]:
"""Return embedded cover-art bytes and mime type from a project's source file."""
sep_job_data = jobs_repo.get(project["sep_job_id"]) or {}
source_file = next(
(file_entry for file_entry in sep_job_data.get("files", []) if file_entry.get("type") == "source"),
None,
)
if not source_file:
raise ProjectOperationError(404, "No source file")
source_path = source_file.get("path", "")
if not source_path or not Path(source_path).exists():
raise ProjectOperationError(404, "Source file not found")
data, mime = _read_cover_art(source_path)
if data:
return data, mime or "image/jpeg"
thumbnail_url = _read_source_thumbnail_url(Path(source_path))
if thumbnail_url:
try:
remote_data, remote_mime = _fetch_remote_image(thumbnail_url)
if remote_data:
return remote_data, remote_mime or "image/jpeg"
except (urlerror.URLError, TimeoutError, ValueError, OSError):
pass
except Exception:
pass
raise ProjectOperationError(404, "No cover art")
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 _rgb_to_hex(r: int, g: int, b: int) -> str:
return f"#{max(0, min(255, int(r))):02x}{max(0, min(255, int(g))):02x}{max(0, min(255, int(b))):02x}"
def _build_dynamic_palette_from_image_bytes(image_bytes: bytes, source: str) -> dict | None:
if not image_bytes:
return None
try:
from PIL import Image
except Exception:
return None
try:
with Image.open(io.BytesIO(image_bytes)) as img:
rgb = img.convert("RGB")
rgb.thumbnail((64, 64))
arr = np.asarray(rgb)
except Exception:
return None
if arr.size == 0:
return None
pixels = arr.reshape(-1, 3)
mean_rgb = pixels.mean(axis=0)
r, g, b = [float(v) / 255.0 for v in mean_rgb]
h, s, v = colorsys.rgb_to_hsv(r, g, b)
# Dark background from art seed so lyrics remain readable.
bg_r, bg_g, bg_b = colorsys.hsv_to_rgb(
h,
max(0.45, min(0.92, s * 0.95 + 0.05)),
max(0.10, min(0.28, v * 0.42)),
)
# High-visibility accents.
hi_r, hi_g, hi_b = colorsys.hsv_to_rgb(
(h + 0.10) % 1.0,
max(0.58, min(0.95, s * 1.08 + 0.08)),
0.94,
)
wh_r, wh_g, wh_b = colorsys.hsv_to_rgb(
(h + 0.18) % 1.0,
max(0.54, min(0.92, s * 1.02 + 0.10)),
0.98,
)
speaker_palette: list[str] = []
for offset in (0.00, 0.10, 0.20, 0.32, 0.44, 0.56, 0.68, 0.82):
pr, pg, pb = colorsys.hsv_to_rgb(
(h + offset) % 1.0,
max(0.58, min(0.94, s * 1.03 + 0.08)),
0.92,
)
speaker_palette.append(_rgb_to_hex(round(pr * 255), round(pg * 255), round(pb * 255)))
return {
"source": source,
"seed_color": _rgb_to_hex(round(r * 255), round(g * 255), round(b * 255)),
"background_color": _rgb_to_hex(round(bg_r * 255), round(bg_g * 255), round(bg_b * 255)),
"text_color": "#ffffff",
"highlight_color": _rgb_to_hex(round(hi_r * 255), round(hi_g * 255), round(hi_b * 255)),
"word_highlight_color": _rgb_to_hex(round(wh_r * 255), round(wh_g * 255), round(wh_b * 255)),
"speaker_palette": speaker_palette,
}
def _build_source_metadata_component(source_media: Path | None) -> tuple[dict, bytes | None, str | None, str | None]:
source_url, navidrome_id = _read_source_origin_fields(source_media) if source_media else ("", "")
metadata = {
"source_file": source_media.name if source_media else "",
"source_url": source_url,
"navidrome_id": navidrome_id,
"title": "",
"artist": "",
"albumartist": "",
"album": "",
"cover_art": None,
"dynamic_palette": 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
palette_source: str | None = None
try:
data, mime = _read_cover_art(str(source_media))
if data:
cover_bytes = data
cover_mime = mime or "image/jpeg"
palette_source = "embedded_cover_art"
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"
palette_source = "thumbnail_url"
except Exception:
pass
if cover_bytes:
metadata["dynamic_palette"] = _build_dynamic_palette_from_image_bytes(
cover_bytes,
palette_source or "cover_art",
)
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 _canonical_lyrics_track_name(value: str | None) -> str:
raw = str(value or "").strip().lower().replace("_", " ").replace("-", " ")
raw = " ".join(raw.split())
if not raw:
return "default"
if "backing" in raw:
return "backing"
if "leading" in raw or raw.startswith("lead") or " lead" in raw:
return "leading"
if raw in {"vocals", "vocal", "lyrics", "lyric", "default"}:
return "default"
return raw
def _collect_project_elrc_tracks(project: dict, project_root: Path) -> list[dict]:
collected: dict[str, Path] = {}
def register(track_name: str | None, candidate: Path | None) -> None:
if candidate is None or not candidate.exists() or not candidate.is_file():
return
key = _canonical_lyrics_track_name(track_name or candidate.stem)
existing = collected.get(key)
if existing is None or candidate.stat().st_mtime > existing.stat().st_mtime:
collected[key] = candidate
for stem_name, job_id in (project.get("lrc_jobs") or {}).items():
job = jobs_repo.get(job_id) or {}
for file_entry in (job.get("files") or []):
raw_path = file_entry.get("path")
if not raw_path:
continue
path = Path(str(raw_path))
file_type = str(file_entry.get("type") or "").lower()
if file_type == "elrc" or path.suffix.lower() == ".elrc":
register(stem_name, path)
for candidate in project_root.rglob("*.elrc"):
register(candidate.stem, candidate)
order = {"leading": 0, "default": 1, "backing": 2}
return [
{"name": key, "path": path}
for key, path in sorted(
collected.items(),
key=lambda item: (order.get(item[0], 10), item[0], -item[1].stat().st_mtime),
)
]
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,
"visualizer": {
"mode": "moire",
"settings": {
"quality": "balanced",
"fps_cap": 60,
"muon": {
"radius_multiplier": 1.0,
"aperture": 1.0,
"spacing": 1.0,
},
"fluid": {
"spawn_density": 1.0,
"splat_force": 1.0,
"decay": 1.0,
},
},
},
}
_LEGACY_MODES = {"muon", "fluid", "tendrils", "spirit", "auto", "muon_iframe"}
_NEW_MODES = {"moire", "dissolve", "glitch", "spiral"}
_ALL_MODES = _LEGACY_MODES | _NEW_MODES
def _normalize_visualizer_config(raw: object) -> dict:
defaults = {
"mode": "moire",
"settings": {
"quality": "balanced",
"fps_cap": 60,
"muon_iframe": {
"style": "default",
"preset": "default",
"quality": "balanced",
},
"muon": {
"radius_multiplier": 1.0,
"aperture": 1.0,
"spacing": 1.0,
},
"fluid": {
"spawn_density": 1.0,
"splat_force": 1.0,
"decay": 1.0,
},
"moire": {
"freq_multiplier": 1.0,
"rotation_speed": 1.0,
"fold_count": 6,
},
"dissolve": {
"scroll_speed": 1.0,
"noise_scale": 1.0,
"persistence": 0.92,
},
"glitch": {
"cell_scale": 1.0,
"threshold": 0.5,
"jitter": 1.0,
},
"spiral": {
"arm_count": 6,
"rotation_speed": 1.0,
"radial_freq": 1.0,
},
},
}
cfg = dict(raw) if isinstance(raw, dict) else {}
mode = str(cfg.get("mode") or defaults["mode"]).strip().lower()
if mode not in _ALL_MODES:
mode = defaults["mode"]
settings_raw = cfg.get("settings")
settings = dict(settings_raw) if isinstance(settings_raw, dict) else {}
muon_iframe_raw = settings.get("muon_iframe")
muon_raw = settings.get("muon")
fluid_raw = settings.get("fluid")
moire_raw = settings.get("moire")
dissolve_raw = settings.get("dissolve")
glitch_raw = settings.get("glitch")
spiral_raw = settings.get("spiral")
muon_iframe = dict(muon_iframe_raw) if isinstance(muon_iframe_raw, dict) else {}
muon = dict(muon_raw) if isinstance(muon_raw, dict) else {}
fluid = dict(fluid_raw) if isinstance(fluid_raw, dict) else {}
moire = dict(moire_raw) if isinstance(moire_raw, dict) else {}
dissolve = dict(dissolve_raw) if isinstance(dissolve_raw, dict) else {}
glitch = dict(glitch_raw) if isinstance(glitch_raw, dict) else {}
spiral = dict(spiral_raw) if isinstance(spiral_raw, dict) else {}
dm = defaults["settings"]
return {
"mode": mode,
"settings": {
"quality": str(settings.get("quality") or dm["quality"]).strip() or "balanced",
"fps_cap": int(settings.get("fps_cap") or dm["fps_cap"]),
"muon_iframe": {
"style": str(muon_iframe.get("style") or dm["muon_iframe"]["style"]).strip().lower() or "default",
"preset": str(muon_iframe.get("preset") or dm["muon_iframe"]["preset"]).strip() or "default",
"quality": str(muon_iframe.get("quality") or dm["muon_iframe"]["quality"]).strip().lower() or "balanced",
},
"muon": {
"radius_multiplier": float(muon.get("radius_multiplier") or dm["muon"]["radius_multiplier"]),
"aperture": float(muon.get("aperture") or dm["muon"]["aperture"]),
"spacing": float(muon.get("spacing") or dm["muon"]["spacing"]),
},
"fluid": {
"spawn_density": float(fluid.get("spawn_density") or dm["fluid"]["spawn_density"]),
"splat_force": float(fluid.get("splat_force") or dm["fluid"]["splat_force"]),
"decay": float(fluid.get("decay") or dm["fluid"]["decay"]),
},
"moire": {
"freq_multiplier": float(moire.get("freq_multiplier") or dm["moire"]["freq_multiplier"]),
"rotation_speed": float(moire.get("rotation_speed") or dm["moire"]["rotation_speed"]),
"fold_count": int(moire.get("fold_count") or dm["moire"]["fold_count"]),
},
"dissolve": {
"scroll_speed": float(dissolve.get("scroll_speed") or dm["dissolve"]["scroll_speed"]),
"noise_scale": float(dissolve.get("noise_scale") or dm["dissolve"]["noise_scale"]),
"persistence": float(dissolve.get("persistence") or dm["dissolve"]["persistence"]),
},
"glitch": {
"cell_scale": float(glitch.get("cell_scale") or dm["glitch"]["cell_scale"]),
"threshold": float(glitch.get("threshold") or dm["glitch"]["threshold"]),
"jitter": float(glitch.get("jitter") or dm["glitch"]["jitter"]),
},
"spiral": {
"arm_count": int(spiral.get("arm_count") or dm["spiral"]["arm_count"]),
"rotation_speed": float(spiral.get("rotation_speed") or dm["spiral"]["rotation_speed"]),
"radial_freq": float(spiral.get("radial_freq") or dm["spiral"]["radial_freq"]),
},
},
}
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 {}
cfg["visualizer"] = _normalize_visualizer_config(cfg.get("visualizer"))
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 {}
normalized["visualizer"] = _normalize_visualizer_config(normalized.get("visualizer"))
_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")
project_name = str(project.get("name") or "").strip() or str(project.get("id") or "StemEngine Karaoke")
for stem in stems:
stem["package_filename"] = stem_filename(project_name, str(stem["name"]), Path(stem["path"]).suffix)
elrc_tracks = _collect_project_elrc_tracks(project, project_root)
if not elrc_tracks:
raise ProjectOperationError(404, "No .elrc lyrics file found for project")
primary_elrc = next((track for track in elrc_tracks if track["name"] in {"leading", "default"}), elrc_tracks[0])
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)
# ── Audio features (BPM / key) ─────────────────────────────────────────
# Prefer the value cached in project.json by the separator worker.
# If not present (old project, re-package), run analysis now and cache.
audio_features: dict = {}
cached_meta = read_project_metadata(project_root)
if cached_meta and isinstance(cached_meta.get("audio_features"), dict):
audio_features = cached_meta["audio_features"]
elif source_media and source_media.exists():
try:
audio_features = analyze_audio_features(source_media)
if audio_features:
patch_project_metadata_audio_features(project_root, audio_features)
except Exception:
pass
if audio_features:
source_metadata["audio_features"] = audio_features
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()
base_export_dir = Path(configured_export_dir) if configured_export_dir else (MEDIA_DIR / "sek_exports")
if not base_export_dir.is_absolute():
base_export_dir = MEDIA_DIR / 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
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/{primary_elrc['path'].name}",
"lyrics_tracks": {
track["name"]: f"lyrics/{track['path'].name}"
for track in elrc_tracks
},
"video": f"video/{video_path.name}" if video_path else None,
"stems": [
{
"name": stem["name"],
"file": f"stems/{stem['package_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",
"lyrics_track_count": len(elrc_tracks),
"synchronization": {
"reference_track": reference_track,
"track_offsets_seconds": cfg.get("track_offsets_seconds") or {},
"video_source": configured_source,
"last_sync": cfg.get("last_sync"),
},
},
"visualizer": _normalize_visualizer_config(cfg.get("visualizer")),
}
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))
written_lyrics: set[str] = set()
for track in elrc_tracks:
lyrics_path = track["path"]
arcname = f"lyrics/{lyrics_path.name}"
if arcname in written_lyrics:
continue
zf.write(lyrics_path, arcname=arcname)
written_lyrics.add(arcname)
for stem in stems:
zf.write(stem["path"], arcname=f"stems/{stem['package_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(primary_elrc["path"]),
"lyrics_tracks": {track["name"]: str(track["path"]) for track in elrc_tracks},
"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 _ass_to_plaintext(lyrics: str) -> str:
lines: list[str] = []
for raw_line in lyrics.splitlines():
if raw_line.startswith("Dialogue:"):
payload = raw_line.split(",", 9)
text = payload[-1] if payload else raw_line
else:
text = raw_line
text = text.replace("\\N", "\n")
text = text.replace("\\n", "\n")
for segment in text.splitlines():
cleaned = segment.strip()
if not cleaned:
continue
while "{" in cleaned and "}" in cleaned:
start = cleaned.find("{")
end = cleaned.find("}", start)
if end < 0:
break
cleaned = f"{cleaned[:start]}{cleaned[end + 1:]}".strip()
if cleaned:
lines.append(cleaned)
return "\n".join(lines)
def get_project_lyrics_preview(project: dict) -> dict:
project_root = project_output_dir(project)
if not project_root.exists():
raise ProjectOperationError(404, "Project directory not found")
elrc_tracks = _collect_project_elrc_tracks(project, project_root)
selected_path: Path | None = None
selected_source = ""
if elrc_tracks:
primary_elrc = next((track for track in elrc_tracks if track["name"] in {"leading", "default"}), elrc_tracks[0])
selected_path = Path(primary_elrc["path"])
selected_source = f"elrc:{primary_elrc['name']}"
else:
selected_path = _pick_best_lyrics_file(project_root)
selected_source = "project_lyrics_file"
if selected_path is None or not selected_path.exists() or not selected_path.is_file():
raise ProjectOperationError(404, "No lyrics file found for project")
try:
raw = selected_path.read_text(encoding="utf-8", errors="ignore")
except Exception as exc:
raise ProjectOperationError(500, f"Failed to read project lyrics: {exc}") from exc
suffix = selected_path.suffix.lower()
if suffix == ".ass":
plain = _ass_to_plaintext(raw)
synced = False
elif suffix in {".lrc", ".elrc"}:
plain = lyrics_to_plaintext(raw)
synced = is_lrc_synced(raw)
else:
plain = raw
synced = False
plain_lines = [line.strip() for line in plain.splitlines() if line.strip()]
return {
"path": str(selected_path),
"source": selected_source,
"format": suffix.lstrip("."),
"synced": synced,
"raw": raw,
"plain": plain,
"line_count": len(plain_lines),
}
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:
<project>/Exports/KaraokeMugen/<kid>/
- <kid>.kara.json
- <copied media file>
- <copied lyrics file> (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,
}