Function analyze

app/pipeline/analyze.py:249–331

Best-effort BPM and key detection. On failure, returns (None, None) and leaves job fields untouched -- the chips stay as placeholders.

(job: Job, source: Path)

def analyze(job: Job, source: Path) -> tuple[int | None, str | None]:
    """Best-effort BPM and key detection. On failure, returns (None, None)
    and leaves job fields untouched -- the chips stay as placeholders."""
    logger.info("analyze: entering for job %s, source=%s", job.id, source)
    _set(job, status="analyzing", progress=0.0, stage="Analyzing audio...")
    try:
        import librosa
    except ImportError:
        logger.warning("librosa not installed -- skipping BPM/key analysis")
        return None, None

    try:
        # Analyse the first 180 s. Decode via ffmpeg directly into numpy
        # to avoid librosa's deprecated audioread fallback for
        # .webm/.m4a/.opus inputs.
        loaded = _load_audio_ffmpeg(source, sr=22050, duration=180.0)
        if loaded is None:
            return None, None
        y, sr = loaded

        # Harmonic / percussive separation. Beat tracking sees a cleaner
        # onset envelope on the percussive component; chroma sees a
        # cleaner pitch profile on the harmonic component (no cymbal
        # smear, no kick fundamentals leaking in).
        y_harmonic, y_percussive = librosa.effects.hpss(y)

        tempo_arr, beat_frames = librosa.beat.beat_track(y=y_percussive, sr=sr)
        try:
            tempo = float(tempo_arr[0])  # type: ignore[index]
        except (TypeError, IndexError):
            tempo = float(tempo_arr)
        bpm = int(round(tempo)) if tempo > 0 else None

        # chroma_cqt is constant-Q based — better pitch resolution than
        # chroma_stft, especially in the bass register where the open
        # strings of a guitar live.
        chroma = librosa.feature.chroma_cqt(y=y_harmonic, sr=sr)
        chroma_mean = chroma.mean(axis=1).tolist()
        if any(chroma_mean):
            key, scale, key_confidence = _detect_key(chroma_mean)
        else:
            key, scale, key_confidence = None, None, None

        # LUFS / peak. Computed on the same 22 kHz mono buffer; this
        # loses a few dB of accuracy vs full-sample-rate stereo, but
        # it's good enough for a UI display and adds ~50 ms to analyze.
        lufs, peak_db = _measure_loudness(y, sr)

        dynamic_range: float | None = None
        if lufs is not None and peak_db is not None:
            dynamic_range = round(peak_db - lufs, 1)

        # Beat interval coefficient of variation → stability 0-100.
        # CV = std/mean of inter-beat intervals; CV=0 is perfectly metronomic.
        tempo_stability: int | None = None
        import numpy as np

        beat_times = librosa.frames_to_time(beat_frames, sr=sr)