kasaframe 0.0.0-stage → 0.1.3

package/tools/beats/beats.py

@@ -0,0 +1,372 @@
+#!/usr/bin/env python3
+"""곡을 재서 beats.json(SPEC 4번)을 쓴다.
+
+드롭·구간은 저역 에너지와 onset 으로 잰 시각이다. BPM 을 곱해 만든 시각은
+뒤로 갈수록 밀려서 쓰지 않는다 — 마디·프레이즈도 잰 박을 세어서 얻는다.
+"""
+import argparse
+import json
+import os
+import sys
+
+import numpy as np
+import librosa
+from scipy.ndimage import median_filter, uniform_filter1d
+
+SR = 22050
+# 5.8ms — 60fps 한 프레임(16.7ms) 안에 드롭 시각이 떨어지게
+HOP = 128
+NFFT = 2048
+BANDS = {"low": (20, 150), "mid": (150, 2000), "high": (2000, SR / 2)}
+EPS = 1e-10
+
+
+def nfr(sec):
+    return max(1, int(round(sec * SR / HOP)))
+
+
+def db(p):
+    return 10 * np.log10(p + EPS)
+
+
+class Song:
+    def __init__(self, path):
+        y, _ = librosa.load(path, sr=SR, mono=True)
+        self.length = len(y) / SR
+        S = np.abs(librosa.stft(y, n_fft=NFFT, hop_length=HOP)) ** 2
+        f = librosa.fft_frequencies(sr=SR, n_fft=NFFT)
+        self.t = librosa.frames_to_time(np.arange(S.shape[1]), sr=SR, hop_length=HOP)
+        self.power = {k: S[(f >= lo) & (f < hi)].sum(0) for k, (lo, hi) in BANDS.items()}
+        # 한 프레임짜리 값은 너무 튀어서 30ms 로 고른다(킥 어택은 그대로 남는 길이)
+        self.fast = {k: db(uniform_filter1d(p, nfr(0.03))) for k, p in self.power.items()}
+        mel = librosa.feature.melspectrogram(S=S, sr=SR, n_mels=128)
+        logmel = librosa.power_to_db(mel)
+        self.onset = librosa.onset.onset_strength(S=logmel, sr=SR, hop_length=HOP)
+        mf = librosa.mel_frequencies(n_mels=128, fmax=SR / 2)
+        self.low_onset = librosa.onset.onset_strength(S=logmel[mf < 150], sr=SR, hop_length=HOP)
+        self.mfcc = librosa.feature.mfcc(S=logmel, n_mfcc=13)
+        self.chroma = librosa.feature.chroma_stft(S=S, sr=SR, hop_length=HOP)
+
+    def frame(self, sec):
+        return int(np.clip(np.searchsorted(self.t, sec), 0, len(self.t) - 1))
+
+
+def track_beats(song, bpm_hint):
+    if bpm_hint:
+        start = bpm_hint
+    else:
+        start = float(librosa.feature.tempo(onset_envelope=song.onset, sr=SR, hop_length=HOP)[0])
+        # 반박으로 잡히면 박 사이가 0.7초가 넘어 화면이 박을 놓친다 — 90 아래는 두 배로 센다
+        if start < 90:
+            start *= 2
+    _, bf = librosa.beat.beat_track(
+        onset_envelope=song.onset, sr=SR, hop_length=HOP, start_bpm=start, tightness=200
+    )
+    return librosa.frames_to_time(bf, sr=SR, hop_length=HOP)
+
+
+def runs(mask):
+    out, i, n = [], 0, len(mask)
+    while i < n:
+        j = i
+        while j < n and mask[j] == mask[i]:
+            j += 1
+        out.append([bool(mask[i]), i, j])
+        i = j
+    return out
+
+
+def bass_runs(song):
+    """저역이 깔린 구간(on)과 빠진 구간(off). 킥 사이 틈은 0.5초 평균으로 메운다."""
+    bass = db(uniform_filter1d(song.power["low"], nfr(0.5)))
+    ref = np.percentile(bass, 90)
+    on, state = np.zeros(len(bass), bool), False
+    for i, v in enumerate(bass):
+        if state and v < ref - 20:
+            state = False
+        elif not state and v > ref - 12:
+            state = True
+        on[i] = state
+    rs = runs(on)
+    # 1초보다 짧은 on/off 는 앞 구간에 붙인다 — 잠깐 끊긴 것을 구간으로 세지 않는다
+    merged = []
+    for r in rs:
+        if merged and (r[2] - r[1]) < nfr(1.0):
+            merged[-1][2] = r[2]
+        elif merged and merged[-1][0] == r[0]:
+            merged[-1][2] = r[2]
+        else:
+            merged.append(list(r))
+    return merged, ref
+
+
+def refine_hit(song, i_from, i_to, level):
+    """[i_from, i_to) 안에서 저역이 level 에 처음 닿는 프레임."""
+    idx = np.nonzero(song.fast["low"][i_from:i_to] >= level)[0]
+    return None if len(idx) == 0 else i_from + int(idx[0])
+
+
+def attack_time(song, hit):
+    """킥 어택 시각. 가운데 맞춘 STFT 창은 계단을 창 길이만큼 번지게 하는데,
+    파워가 꼭대기의 절반(-3dB)을 지나는 창 중심이 바로 계단 자리다."""
+    raw = db(song.power["low"])
+    a, b = max(1, hit - nfr(0.08)), min(len(raw), hit + nfr(0.06))
+    half = raw[hit:b].max() - 3
+    for j in range(a, b):
+        if raw[j] >= half:
+            f = (half - raw[j - 1]) / max(raw[j] - raw[j - 1], EPS)
+            return float(song.t[j - 1] + np.clip(f, 0, 1) * (song.t[j] - song.t[j - 1]))
+    return float(song.t[hit])
+
+
+def find_drops(song, rs):
+    low = song.fast["low"]
+    drops = []
+    # 저역이 1초 넘게 빠졌다가 들어오는 곳 — 진짜 드롭
+    for k in range(1, len(rs)):
+        prev, cur = rs[k - 1], rs[k]
+        # 곡 첫머리의 짧은 무음 뒤에 저역이 시작하는 것은 드롭이 아니라 그냥 시작이다
+        if not cur[0] or prev[0] or (prev[2] - prev[1]) < nfr(1.0):
+            continue
+        i0 = cur[1]
+        peak = np.percentile(low[i0 : i0 + nfr(4)], 95)
+        hit = refine_hit(song, max(prev[1], i0 - nfr(1.5)), i0 + nfr(1.5), peak - 3)
+        if hit is None:
+            continue
+        before = np.median(low[max(prev[1], i0 - nfr(4)) : i0 - nfr(1.0)] if i0 - nfr(1.0) > prev[1] else low[prev[1] : i0])
+        drops.append({"i": hit, "contrast": float(peak - before), "how": "bass-in"})
+
+    # 저역은 깔린 채 위쪽이 잠깐 통째로 끊겼다가(스톱) 크게 다시 치는 곳 — 다시 드롭
+    high = song.fast["high"]
+    ref = median_filter(high, size=nfr(2.0), mode="nearest")
+    # 고역이 원래 성긴 곳(인트로 피아노 같은)의 틈은 스톱이 아니다 — 꽉 찬 구간에서 통째로 빈 것만
+    dense = np.percentile(high, 50) - 6
+    gap = (high < ref - 18) & (ref >= dense)
+    for on, a, b in runs(gap):
+        if not on or (b - a) < nfr(0.04):
+            continue
+        if not any(r[0] and r[1] <= a < r[2] for r in rs):
+            continue
+        if any(abs(d["i"] - b) < nfr(2.0) for d in drops):
+            continue
+        depth = float(np.median(ref[a:b]) - high[a:b].min())
+        # 킥 사이 짧은 숨(20~25dB)은 리듬일 뿐이고, 다시 드롭 앞 스톱은 30dB 넘게 비었다
+        if depth < 30:
+            continue
+        local = np.percentile(low[max(0, b - nfr(3)) : b + nfr(3)], 95)
+        hit = refine_hit(song, b, b + nfr(0.25), local - 3)
+        # 스톱 뒤에 저역이 새로 쳐야 한다 — 이어지던 저역에 걸린 것은 드롭이 아니다
+        if hit is None or low[hit] - low[a:hit].min() < 6:
+            continue
+        drops.append({"i": hit, "contrast": depth, "how": "stop"})
+
+    drops.sort(key=lambda d: d["i"])
+    for d in drops:
+        d["t"] = attack_time(song, d["i"])
+        # 저역이 통째로 빠졌다 들어오는 드롭이 스톱 뒤 다시 치는 것보다 크게 들린다
+        scale = 1.0 if d["how"] == "bass-in" else 0.8
+        d["strength"] = round(float(np.clip(d["contrast"] / 45, 0, 1) * scale), 2)
+    return drops
+
+
+def downbeat_flags(song, beats, drops):
+    """박마다 마디 첫 박인지. 잰 드롭을 닻으로 삼아 닻마다 4박을 다시 센다."""
+    n = len(beats)
+    anchors = sorted({int(np.argmin(np.abs(beats - d["t"]))) for d in drops})
+    if not anchors:
+        kick = song.low_onset[[song.frame(b) for b in beats]]
+        scores = [kick[p::4].mean() if len(kick[p::4]) else 0 for p in range(4)]
+        anchors = [int(np.argmax(scores))]
+    flags = np.zeros(n, bool)
+    for i in range(n):
+        prior = [a for a in anchors if a <= i]
+        a = prior[-1] if prior else anchors[0]
+        flags[i] = (i - a) % 4 == 0
+    return flags
+
+
+def novelty_cuts(song, downbeats, rs, taken):
+    """음색·화성이 바뀌는 마디 경계(자기유사 체커보드)."""
+    if len(downbeats) < 12:
+        return []
+    frames = [song.frame(d) for d in downbeats]
+    feat = np.vstack([song.mfcc, song.chroma, *[song.fast[k][None, :] for k in BANDS]])
+    sync = librosa.util.sync(feat, frames, aggregate=np.mean)[:, 1:]
+    sync = (sync - sync.mean(1, keepdims=True)) / (sync.std(1, keepdims=True) + EPS)
+    sync /= np.linalg.norm(sync, axis=0, keepdims=True) + EPS
+    ssm = sync.T @ sync
+    K, m = 4, ssm.shape[0]
+    sign = np.r_[-np.ones(K), np.ones(K)]
+    kernel = np.outer(sign, sign)
+    nov = np.zeros(m)
+    for i in range(K, m - K):
+        nov[i] = (ssm[i - K : i + K, i - K : i + K] * kernel).sum()
+    nov = np.maximum(nov, 0)
+    if nov.max() <= 0:
+        return []
+    thr = nov[nov > 0].mean() + nov[nov > 0].std()
+    bar = np.median(np.diff(downbeats))
+    cuts = []
+    for i in range(1, m - 1):
+        if not (nov[i] > thr and nov[i] >= nov[i - 1] and nov[i] >= nov[i + 1]):
+            continue
+        # sync 는 첫 경계 앞을 한 칸으로 잡아서 i 번째 칸은 i 번째 다운비트에서 시작한다
+        t = downbeats[i]
+        fi = song.frame(t)
+        if not any(r[0] and r[1] <= fi < r[2] for r in rs):
+            continue
+        if any(abs(t - x) < 2 * bar for x in taken + [c["t"] for c in cuts]):
+            continue
+        cuts.append({"t": float(t), "strength": round(float(nov[i] / nov.max()), 2)})
+    return cuts
+
+
+def snap_back(t, downbeats, beats):
+    """t 에서 끝난 구간의 마디 첫 박 — 마지막 한 방이 마디 첫 박에 떨어지고 바로 비는 곡이 많다."""
+    bar = np.median(np.diff(downbeats)) if len(downbeats) > 1 else 2.0
+    prior = downbeats[(downbeats <= t + 0.1) & (downbeats > t - bar / 2)]
+    if len(prior):
+        return float(prior[-1])
+    return float(beats[np.argmin(np.abs(beats - t))]) if len(beats) else t
+
+
+def build_sections(song, rs, ref, drops, beats, downbeats):
+    secs = []
+    first_on = next((r for r in rs if r[0]), None)
+    if first_on is None or song.t[first_on[1]] > 1.0:
+        secs.append({"t": 0.0, "kind": "intro"})
+    else:
+        secs.append({"t": 0.0, "kind": "main"})
+    for d in drops:
+        secs.append({"t": d["t"], "kind": "drop", "strength": d["strength"]})
+    for k in range(1, len(rs)):
+        if rs[k][0] or not rs[k - 1][0]:
+            continue
+        if (rs[k][2] - rs[k][1]) < nfr(2.0):
+            continue
+        later_on = any(r[0] for r in rs[k + 1 :])
+        prev = rs[k - 1]
+        loud = np.nonzero(song.fast["low"][prev[1] : rs[k][1] + nfr(0.5)] >= ref - 15)[0]
+        end = song.t[prev[1] + int(loud[-1])] if len(loud) else song.t[rs[k][1]]
+        secs.append({"t": snap_back(end, downbeats, beats), "kind": "break" if later_on else "outro"})
+    for c in novelty_cuts(song, downbeats, rs, [s["t"] for s in secs]):
+        secs.append({"t": c["t"], "kind": "main", "strength": c["strength"]})
+    secs.sort(key=lambda s: s["t"])
+    return secs
+
+
+def phrase_starts(sections, downbeats, end):
+    """구간 시작마다 다시 센 4마디 묶음. 드롭 앞 구간은 드롭에서 거꾸로 센다."""
+    if len(downbeats) < 2:
+        return [s["t"] for s in sections]
+    bar = float(np.median(np.diff(downbeats)))
+    per = 4 if bar <= 2.0 else 2
+    out = []
+    for k, s in enumerate(sections):
+        a = s["t"]
+        b = sections[k + 1]["t"] if k + 1 < len(sections) else end
+        inside = [d for d in downbeats if a - bar / 4 <= d < b - bar / 4]
+        if k + 1 < len(sections) and sections[k + 1]["kind"] == "drop":
+            picks = inside[::-1][per - 1 :: per][::-1]
+        else:
+            picks = inside[::per]
+        out.append(a)
+        out += [p for p in picks if p - a > bar / 2]
+    return sorted(set(round(x, 4) for x in out))
+
+
+def energy_curves(song, a, b, hz):
+    step = 1.0 / hz
+    edges = np.arange(a, b + EPS, step)
+    out = {"hz": hz}
+    for k, p in song.power.items():
+        # 정규화는 곡 전체 기준 — 잘라 쓴 구간이 조용해도 1 까지 부풀지 않게
+        whole = db(uniform_filter1d(p, nfr(step)))
+        hi = np.percentile(whole, 99)
+        lo = hi - 45
+        vals = []
+        for e in edges[:-1]:
+            i, j = song.frame(e), song.frame(e + step)
+            v = db(p[i : max(j, i + 1)].mean())
+            vals.append(round(float(np.clip((v - lo) / (hi - lo), 0, 1)), 3))
+        out[k] = vals
+    return out
+
+
+def analyze(path, start, duration, hz, bpm_hint):
+    song = Song(path)
+    a = max(0.0, start)
+    b = song.length if duration is None else min(song.length, a + duration)
+
+    beats = track_beats(song, bpm_hint)
+    rs, ref = bass_runs(song)
+    drops = find_drops(song, rs)
+    # 드롭 바로 옆 박은 잰 드롭 시각으로 맞춘다 — 마커가 한 점에 겹치게
+    for d in drops:
+        j = int(np.argmin(np.abs(beats - d["t"])))
+        if abs(beats[j] - d["t"]) < 0.06:
+            beats[j] = d["t"]
+    flags = downbeat_flags(song, beats, drops)
+    downbeats = beats[flags]
+    sections = build_sections(song, rs, ref, drops, beats, downbeats)
+    phrases = phrase_starts(sections, downbeats, song.length)
+
+    def clip(ts):
+        return [round(float(t) - a, 4) for t in ts if a <= t < b]
+
+    secs = []
+    for s in sections:
+        if s["t"] < b:
+            secs.append({**s, "t": round(max(0.0, s["t"] - a), 4)})
+    while len(secs) > 1 and secs[1]["t"] == 0.0:
+        secs.pop(0)
+    # 박 간격은 프레임 단위로 떨어져 중앙값이 한쪽으로 쏠린다 — 박 번호에 대한 기울기로 잰다
+    bpm = 60.0 / float(np.polyfit(np.arange(len(beats)), beats, 1)[0]) if len(beats) > 1 else 0.0
+    out = {
+        "source": os.path.basename(path),
+        "from": round(a, 4),
+        "duration": round(b - a, 4),
+        "bpm": round(bpm, 2),
+        "beats": clip(beats),
+        "downbeats": clip(downbeats),
+        "bars": clip(downbeats),
+        "phrases": sorted(set([0.0] + clip(phrases))),
+        "sections": secs,
+        "drops": [round(d["t"] - a, 4) for d in drops if a <= d["t"] < b],
+        "energy": energy_curves(song, a, b, hz),
+    }
+    return out
+
+
+def report(o):
+    lines = [
+        f"bpm {o['bpm']} · 박 {len(o['beats'])} · 마디 {len(o['downbeats'])} · 프레이즈 {len(o['phrases'])} · 길이 {o['duration']}초 (곡 {o['from']}초부터)",
+        "드롭 " + (" · ".join(f"{t:.3f}" for t in o["drops"]) or "없음"),
+        "구간 " + " · ".join(f"{s['t']:.2f} {s['kind']}" for s in o["sections"]),
+    ]
+    return "\n".join(lines)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="곡 → beats.json")
+    ap.add_argument("audio")
+    ap.add_argument("--out", default="beats.json")
+    ap.add_argument("--from", dest="start", type=float, default=0.0)
+    ap.add_argument("--duration", type=float, default=None)
+    ap.add_argument("--hz", type=int, default=20)
+    ap.add_argument("--bpm", type=float, default=None, help="박 추적 시작값(반박·두배박으로 잘못 잡힐 때만)")
+    args = ap.parse_args()
+    if not os.path.isfile(args.audio):
+        print(f"곡이 없다: {args.audio}", file=sys.stderr)
+        return 2
+    o = analyze(args.audio, args.start, args.duration, args.hz, args.bpm)
+    out_dir = os.path.dirname(os.path.abspath(args.out))
+    o["source"] = os.path.relpath(os.path.abspath(args.audio), out_dir)
+    with open(args.out, "w") as f:
+        json.dump(o, f, ensure_ascii=False, separators=(",", ":"))
+    print(report(o), file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/beats/requirements.txt

@@ -0,0 +1,3 @@
+librosa>=0.10
+numpy
+scipy

package/tools/lyrics/align.py

@@ -0,0 +1,164 @@
+"""공식 가사에 시각을 붙인다 — 보컬을 떼고(demucs htdemucs) whisper 강제 정렬(stable-ts align)로 줄·어절 시각.
+
+  python align.py --audio 곡 --text 공식가사.txt --lang ko --out lyrics.json [--from 초 --duration 초] [--model large-v3-turbo]
+
+글자는 공식 가사가 정본이다. 정렬이 돌려준 글자는 시각을 얻는 데만 쓰고, 어긋난 글자는 앞뒤 시각 사이로 메운다.
+흐름은 natsu_mv/align_lyrics.py(demucs + stable-whisper align) 를 옮겼다. 결과 시각은 --from 을 0 으로 센다(beats.json 과 같다).
+"""
+import argparse
+import difflib
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+CACHE = Path(os.environ.get("KF_LYRICS_CACHE", Path.home() / ".cache" / "kasaframe" / "lyrics"))
+
+
+def log(msg):
+    print(f"[lyrics] {msg}", file=sys.stderr, flush=True)
+
+
+def cut(audio, start, duration, out):
+    args = ["ffmpeg", "-v", "error", "-y"]
+    if start:
+        args += ["-ss", f"{start}"]
+    args += ["-i", audio]
+    if duration:
+        args += ["-t", f"{duration}"]
+    subprocess.run(args + ["-ac", "2", "-ar", "44100", out], check=True)
+
+
+def separate(wav, device):
+    """보컬만 — 같은 소리는 한 번만 뗀다(~/.cache/kasaframe/lyrics/<해시>).
+    demucs 명령은 torchaudio(→ torchcodec)로 저장해 ffmpeg 9 에서 죽어서, 모델만 빌려 soundfile 로 읽고 쓴다(demucs.separate 와 같은 정규화)"""
+    digest = hashlib.sha256(Path(wav).read_bytes()).hexdigest()[:16]
+    vocals = CACHE / digest / "vocals.wav"
+    if vocals.exists():
+        log(f"보컬 캐시 {vocals}")
+        return str(vocals)
+    log("보컬 떼는 중(demucs htdemucs)")
+    import soundfile as sf
+    import torch
+    from demucs.apply import apply_model
+    from demucs.pretrained import get_model
+
+    model = get_model("htdemucs")
+    model.eval()
+    data, sr = sf.read(wav, dtype="float32", always_2d=True)
+    if sr != model.samplerate:
+        raise SystemExit(f"{sr}Hz — demucs 는 {model.samplerate}Hz 를 받는다")
+    x = torch.from_numpy(data.T.copy())
+    if x.shape[0] == 1:
+        x = x.repeat(2, 1)
+    ref = x.mean(0)
+    mean, std = ref.mean(), ref.std() + 1e-8
+    with torch.no_grad():
+        out = apply_model(model, ((x - mean) / std)[None], device=device, split=True, overlap=0.25, progress=False)[0]
+    out = out * std + mean
+    vocals.parent.mkdir(parents=True, exist_ok=True)
+    sf.write(str(vocals), out[model.sources.index("vocals")].T.numpy(), model.samplerate)
+    return str(vocals)
+
+
+def char_times(words):
+    """정렬된 낱말을 글자마다 (글자, 시작, 끝)으로 — 낱말 안에서는 고르게 나눈다"""
+    out = []
+    for text, start, end in words:
+        chars = [c for c in text if not c.isspace()]
+        n = len(chars) or 1
+        for i, c in enumerate(chars):
+            out.append((c, start + (end - start) * i / n, start + (end - start) * (i + 1) / n))
+    return out
+
+
+def fill(times):
+    """못 맞춘 글자(None)를 앞뒤 시각 사이로 메운다"""
+    known = [i for i, t in enumerate(times) if t is not None]
+    if not known:
+        raise SystemExit("정렬된 글자가 하나도 공식 가사와 안 맞는다 — 언어(--lang)·곡 구간(--from)을 본다")
+    for i, t in enumerate(times):
+        if t is not None:
+            continue
+        prev = max((k for k in known if k < i), default=None)
+        nxt = min((k for k in known if k > i), default=None)
+        if prev is None:
+            times[i] = (times[nxt][0], times[nxt][0])
+        elif nxt is None:
+            times[i] = (times[prev][1], times[prev][1])
+        else:
+            a, b = times[prev][1], times[nxt][0]
+            span = nxt - prev
+            times[i] = (a + (b - a) * (i - prev - 1) / span, a + (b - a) * (i - prev) / span)
+    return times
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--audio", required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--lang", default="ko")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--from", dest="start", type=float, default=0.0)
+    ap.add_argument("--duration", type=float, default=0.0)
+    ap.add_argument("--model", default=os.environ.get("WHISPER_MODEL", "large-v3-turbo"))
+    ap.add_argument("--device", default=os.environ.get("WHISPER_DEVICE", "cpu"))
+    ap.add_argument("--no-separate", action="store_true", help="이미 보컬만 있는 소리")
+    a = ap.parse_args()
+
+    lines = [ln.strip() for ln in Path(a.text).read_text(encoding="utf-8").splitlines() if ln.strip()]
+    if not lines:
+        raise SystemExit(f"{a.text} 에 가사 줄이 없다")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        wav = os.path.join(tmp, Path(a.audio).stem + ".wav")
+        cut(a.audio, a.start, a.duration, wav)
+        vocals = wav if a.no_separate else separate(wav, a.device)
+
+        import stable_whisper
+
+        log(f"정렬 — {a.model} · {a.device} · {a.lang} · 줄 {len(lines)}")
+        model = stable_whisper.load_model(a.model, device=a.device)
+        result = model.align(vocals, "\n".join(lines), language=a.lang, original_split=True)
+        words = [(w.word, float(w.start), float(w.end)) for seg in result.segments for w in seg.words]
+
+    aligned = char_times(words)
+    official = [(li, ci) for li, ln in enumerate(lines) for ci, c in enumerate(ln) if not c.isspace()]
+    off_chars = [lines[li][ci] for li, ci in official]
+    sm = difflib.SequenceMatcher(None, off_chars, [c for c, _, _ in aligned], autojunk=False)
+    times = [None] * len(off_chars)
+    matched = 0
+    for blk in sm.get_matching_blocks():
+        for k in range(blk.size):
+            _, s, e = aligned[blk.b + k]
+            times[blk.a + k] = (s, e)
+            matched += 1
+    times = fill(times)
+    log(f"글자 {len(off_chars)} 중 {matched} 이 정렬 글자와 맞았다" + ("" if matched == len(off_chars) else " — 나머지는 앞뒤 시각 사이로 메웠다"))
+
+    at = {}
+    for (li, ci), t in zip(official, times):
+        at[(li, ci)] = t
+    out_lines = []
+    for li, ln in enumerate(lines):
+        idx = [ci for ci, c in enumerate(ln) if not c.isspace()]
+        words_out = []
+        ci = 0
+        for w in ln.split():
+            first = ln.index(w, ci)
+            last = first + len(w) - 1
+            ci = last + 1
+            words_out.append({"w": w, "start": round(at[(li, first)][0], 3), "end": round(at[(li, last)][1], 3)})
+        out_lines.append({"text": ln, "start": round(at[(li, idx[0])][0], 3), "end": round(at[(li, idx[-1])][1], 3), "words": words_out})
+
+    data = {"source": os.path.abspath(a.audio), "from": a.start, "lang": a.lang, "aligner": f"demucs htdemucs + stable-ts align ({a.model})", "lines": out_lines}
+    Path(a.out).write_text(json.dumps(data, ensure_ascii=False, indent=1), encoding="utf-8")
+    for ln in out_lines:
+        log(f"{ln['start']:7.2f} - {ln['end']:7.2f}  {ln['text']}")
+
+
+if __name__ == "__main__":
+    main()

package/tools/lyrics/requirements.txt

@@ -0,0 +1,9 @@
+# kf lyrics align — 보컬 분리(demucs) + 공식 가사 강제 정렬(stable-ts 의 whisper align).
+# MMS 강제 정렬 가중치는 CC-BY-NC(비상업)라 넣지 않는다. torch 가 3.13 이하에서 서서 kf setup lyrics 가 3.12 venv 를 만든다.
+demucs==4.0.1
+stable-ts==2.19.1
+openai-whisper==20250625
+torch==2.12.1
+torchaudio==2.11.0
+# torchaudio 의 저장은 torchcodec 이 맡는데 ffmpeg 4–8 판만 싣는다(ffmpeg 9 에서 죽는다) — 소리 읽고 쓰기는 soundfile 로 한다
+soundfile==0.14.0