Files
stemengine_old/backend/routers/projects.py
T
2026-07-09 10:58:09 +09:00

509 lines
19 KiB
Python
Executable File

"""
Project management endpoints.
A Project is created automatically when a separation job completes.
It links the separation job to downstream jobs (transcription, ABC, mix).
"""
from pathlib import Path
import re
from typing import Optional
from fastapi import APIRouter, Depends, HTTPException, Response
from pydantic import BaseModel
from ..config import DEFAULT_TRANSCRIBE_MODE
from ..services.project_service import (
cleanup_all_lrc_output_files,
cleanup_rename_all_project_stems,
delete_project_stem,
enqueue_project_abc_conversion,
enqueue_project_lyric_transcription,
enqueue_project_lrc_alignment,
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_lyrics_preview,
get_project_or_raise,
list_projects as list_projects_service,
ProjectOperationError,
build_project_detail,
delete_project_with_related_jobs,
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,
)
from ..services.lyric_transcriber_service import DEFAULT_WHISPER_MODEL
from ..security import require_admin_token
router = APIRouter(prefix="/api/projects", tags=["projects"])
_AUDIO_EXTS = {".mp3", ".wav", ".flac"}
_MP3_BITRATE_RE = re.compile(r"^(?:96|112|128|160|192|224|256|320)k$")
def _validate_mp3_bitrate(value: Optional[str]) -> Optional[str]:
if value is None:
return None
cleaned = value.strip().lower()
if not cleaned:
return None
if not _MP3_BITRATE_RE.match(cleaned):
raise HTTPException(
status_code=400,
detail=(
f"Invalid mp3_bitrate: {value}. "
"Expected one of: 96k, 112k, 128k, 160k, 192k, 224k, 256k, 320k"
),
)
return cleaned
# ---------------------------------------------------------------------------
# Request bodies
# ---------------------------------------------------------------------------
class TranscribeRequest(BaseModel):
stem_name: str # which stem to transcribe (key from sep job)
mode: str = DEFAULT_TRANSCRIBE_MODE
bend_policy: str = "auto" # auto | force_on | force_off
class AbcRequest(BaseModel):
stem_name: str # which stem's MIDI to convert
song_title: Optional[str] = None
class LrcRequest(BaseModel):
stem_name: str # which stem to align (usually vocals)
lyrics_source: str = "text" # text | auto | tag
lyrics_text: Optional[str] = None # required when lyrics_source='text'
output_filename: Optional[str] = None
style_options: Optional[dict] = None
timing_precision: str = "word" # 'word' | 'syllable'
lrc_power_preset: str = "standard" # 'eco' | 'standard' | 'performance'
class MixRequest(BaseModel):
preset_type: str # 'static' | 'dynamic'
static_option: Optional[str] = None
dynamic_levels: Optional[dict] = None # stem_name → float volume
output_format: Optional[str] = None # inferred from stems if absent
class LyricTranscribeRequest(BaseModel):
"""Request body for AI-based lyric transcription (WhisperX or Parakeet)."""
stem_name: str # which stem to transcribe (usually vocals)
model: str = "medium" # model id for selected engine
language: Optional[str] = None # ISO-639-1 code (auto-detect if None)
task: str = "transcribe" # 'transcribe' or 'translate' (translate currently WhisperX-oriented)
output_formats: list = ["elrc", "json", "txt"] # lrc, elrc, json, txt, srt, vtt
initial_prompt: Optional[str] = None # optional prompt to guide the model
temperature: float = 0.0 # sampling temperature
condition_on_previous_text: bool = False # if True, pass previous output as prompt; can cause hallucination loops
engine: str = "whisperx" # 'whisperx' | 'parakeet'
diarize: bool = False # run speaker diarization (WhisperX only)
lrc_power_preset: str = "eco" # 'eco' | 'standard' | 'performance'
phoneme_align: bool = False # use phonemizer + phoneme model for syllable-level timestamps
lsync_align: bool = False # use lsync wav2vec2 CTC + pyphen for syllable-level timestamps
two_pass: bool = False # run a second VAD pass to fill gaps > 2 s
vocal_style: str = "general" # 'general' | 'hiphop' — genre-specific VAD/ASR tuning
explicit: bool = False # disable Whisper's profanity filter via initial_prompt primer
lyrics_source: str = "transcribe" # 'transcribe' | 'auto' | 'tag' | 'file' — when not 'transcribe',
# skip Whisper and force-align existing lyrics instead
existing_lyrics: Optional[str] = None # lyrics text (plain or LRC) to align; overrides lyrics_source
vocal_source: str = "as_is" # 'as_is' | 'prefer_existing' | 'auto'
# 'as_is' — use the selected stem directly (default)
# 'prefer_existing' — look for vocal/backing stem in project, no Demucs
# 'auto' — full heuristics + Demucs fallback
def _get_project_or_404(project_id: str) -> dict:
try:
return get_project_or_raise(project_id)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
# ---------------------------------------------------------------------------
# Endpoints
# ---------------------------------------------------------------------------
@router.get("")
def list_projects():
"""Return all projects, newest first. Migrates orphaned separation jobs."""
return list_projects_service()
@router.get("/{project_id}")
def get_project_detail(project_id: str):
"""Return project with all linked jobs expanded."""
project = _get_project_or_404(project_id)
return build_project_detail(project)
@router.get("/{project_id}/cover-art")
def get_cover_art(project_id: str):
"""Return cover art image bytes from the source audio file, or 404 if none."""
project = _get_project_or_404(project_id)
try:
data, mime = get_project_cover_art(project)
return Response(content=data, media_type=mime)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.get("/{project_id}/lyrics")
def get_project_lyrics(project_id: str):
"""Return the best available project lyrics payload for Track Details previews."""
project = _get_project_or_404(project_id)
try:
return get_project_lyrics_preview(project)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.delete("/{project_id}")
def delete_project(project_id: str):
"""Remove the project record and all associated files from disk."""
project = _get_project_or_404(project_id)
delete_project_with_related_jobs(project)
return {"detail": "Project deleted"}
@router.post("/{project_id}/transcribe")
def transcribe_project(project_id: str, body: TranscribeRequest):
"""Transcribe a specific stem from this project to MIDI."""
project = _get_project_or_404(project_id)
try:
return enqueue_project_transcription(project, body.stem_name, body.mode, body.bend_policy)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.post("/{project_id}/abc")
def abc_project(project_id: str, body: AbcRequest):
"""Convert MIDI from a specific stem's transcription job to ABC notation."""
project = _get_project_or_404(project_id)
try:
return enqueue_project_abc_conversion(project, body.stem_name, body.song_title)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.post("/{project_id}/mix")
def mix_project(project_id: str, body: MixRequest):
"""Create a static or dynamic mix from this project's stems."""
project = _get_project_or_404(project_id)
try:
return enqueue_project_mix(
project,
body.preset_type,
body.static_option,
body.dynamic_levels,
body.output_format,
)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.post("/{project_id}/lrc")
def lrc_project(project_id: str, body: LrcRequest):
"""Align lyrics with a specific stem from this project to produce an ELRC file."""
project = _get_project_or_404(project_id)
try:
return enqueue_project_lrc_alignment(
project,
body.stem_name,
body.lyrics_source,
body.lyrics_text,
body.output_filename,
body.style_options,
body.timing_precision,
body.lrc_power_preset,
)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
@router.post("/{project_id}/lyric-transcribe")
def lyric_transcribe_project(project_id: str, body: LyricTranscribeRequest):
"""
Transcribe lyrics from a vocal stem using AI (Whisper).
Unlike /lrc which aligns existing lyrics, this endpoint generates
lyrics from audio using speech recognition. It produces:
- ELRC with word-level timestamps
- LRC with line-level timestamps
- JSON with full transcription data
- Plain text lyrics
"""
project = _get_project_or_404(project_id)
try:
return enqueue_project_lyric_transcription(
project,
body.stem_name,
body.model,
body.language,
body.task,
body.output_formats,
body.initial_prompt,
body.temperature,
body.condition_on_previous_text,
body.engine,
body.diarize,
body.lrc_power_preset,
body.phoneme_align,
body.lsync_align,
body.two_pass,
body.vocal_style,
body.explicit,
body.lyrics_source,
body.existing_lyrics,
body.vocal_source,
)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
# ---------------------------------------------------------------------------
# Stem Reprocessing
# ---------------------------------------------------------------------------
class ReprocessRequest(BaseModel):
stem_name: str
model: str
output_format: str = "mp3"
mp3_bitrate: Optional[str] = None
@router.post("/{project_id}/reprocess")
def reprocess_stem_endpoint(project_id: str, body: ReprocessRequest):
"""
Reprocess an individual stem using a specialized model.
Useful for applying per-instrument models like MDX-Net or MelBand.
"""
project = _get_project_or_404(project_id)
try:
mp3_bitrate = _validate_mp3_bitrate(body.mp3_bitrate)
return enqueue_stem_reprocess(
project,
body.stem_name,
body.model,
body.output_format,
mp3_bitrate,
)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
# ---------------------------------------------------------------------------
# Stem Renaming
# ---------------------------------------------------------------------------
class RenameStemRequest(BaseModel):
stem_name: str
new_name: str
@router.post("/{project_id}/rename-stem")
def rename_stem_endpoint(project_id: str, body: RenameStemRequest):
"""Rename a stem file and update the job record."""
project = _get_project_or_404(project_id)
try:
return rename_project_stem(project, body.stem_name, body.new_name)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
# ---------------------------------------------------------------------------
# Stem Delete
# ---------------------------------------------------------------------------
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."""
project = _get_project_or_404(project_id)
try:
return delete_project_stem(project, body.stem_name)
except ProjectOperationError as exc:
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
# ---------------------------------------------------------------------------
@router.post("/{project_id}/rescan-stems")
def rescan_stems(project_id: str):
"""
Recursively scan the project's Stems directory and register any audio
files not already tracked in the separation job's file list.
Useful after external renames or manual file additions. Stem names are
inferred from filenames: "Artist - Title (vocals).mp3" → "vocals",
"vocals.mp3" → "vocals". Returns the list of newly added stem entries.
"""
project = _get_project_or_404(project_id)
try:
return rescan_project_stems(project, _AUDIO_EXTS)
except ProjectOperationError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc
# ---------------------------------------------------------------------------
# Cleanup / maintenance endpoints
# ---------------------------------------------------------------------------
@router.get("/cleanup/verify")
def cleanup_verify(_: None = Depends(require_admin_token)):
"""
Check every project's stem files are actually on disk.
Returns a list of projects with missing files — no mutations performed.
"""
return verify_all_project_stems()
@router.post("/cleanup/write-metadata")
def cleanup_write_metadata(_: None = Depends(require_admin_token)):
"""
Write/refresh project.json for every project in the database.
Uses current DB state so trans_jobs, lrc_jobs etc. are included.
"""
return write_all_project_metadata_snapshots()
@router.post("/cleanup/rename-stems")
def cleanup_rename_stems(_: None = Depends(require_admin_token)):
"""
Rename all stem files that still use the old 'filename - Vocals.ext' format
to the new 'Artist - Title (vocals).ext' format.
Updates the DB job file records after each rename.
"""
return cleanup_rename_all_project_stems()
@router.post("/cleanup/purge-orphaned")
def cleanup_purge_orphaned(_: None = Depends(require_admin_token)):
"""
Delete separation job rows (job_type='separate') that have no matching
ProjectRecord. Also deletes jobs of any type whose parent project is gone.
"""
return purge_orphaned_separation_jobs_from_store()
@router.post("/cleanup/clean-lrc-files")
def cleanup_clean_lrc_files(_: None = Depends(require_admin_token)):
"""
Scan every LRC/ELRC output file in all lrc jobs and strip section-marker
lines (e.g. [01:30.00][Chorus]). Returns counts of files and lines affected.
"""
return cleanup_all_lrc_output_files()