@crievo/omni 0.0.0-stage → 0.1.1

package/tools/omnivideo.py

@@ -0,0 +1,1122 @@
+#!/usr/bin/env python3
+"""Deterministic stages of omnivideo. Reads and writes videos/<slug>/scenes.json.
+
+    omnivideo.py status   <video>   which stage the video is at and which is next
+    omnivideo.py voice    <video>   generates new or changed lines (Fish Audio, Cartesia
+                                    or VoiceStudio, with fallback: tools/voice.py)
+    omnivideo.py timing   <video>   duration of each scene and where each line starts
+    omnivideo.py captions <video>   time of each word (measured on the audio, no transcription)
+                                    and captions.srt
+
+`voice` and `captions` accept `--scene cNN` to handle a single scene (what the
+preview uses). `voice --regenerate-fallback` generates again, with the video's
+provider, the lines that came out of a fallback. With `--scene`, `captions`
+writes the word timings but not captions.srt, which only exists for the whole video.
+
+Another reading of a line that came out bad, and the choice between readings:
+
+    omnivideo.py voice <video> --regenerate c03f1[,c05f1]   generates again, even with the same text,
+                                                            only those lines (with the video's provider)
+    omnivideo.py voice <video> --regenerate c03f1 --provider fish
+                                                            generates that line with this provider (the others
+                                                            stay as fallback); the choice holds for that line only
+                                                            (`provider_pinned`) and survives a general `voice`
+    omnivideo.py voice <video> --use c03f1 <version>        restores history/voice/c03f1/<version>/
+
+The reading that is replaced always goes to history/voice/<line>/ (the most
+recent `history.versions`): none is lost when swapping.
+
+`status --json` gives the same diagnosis as data, for the studio and other
+integrations. `voice` and `captions` wait for their turn in the machine queue
+(tools/job_queue.py).
+
+Run with the project's Python (.venv, created by node tools/setup.mjs), which has requests, soundfile and numpy:
+
+    .venv/bin/python tools/omnivideo.py voice videos/<slug>
+"""
+
+import itertools
+import json
+import math
+import re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from pathlib import Path
+
+import usage
+import voice
+from history import keep_previous
+from job_queue import turn
+from omni_paths import DATA_ROOT as ROOT
+
+CFG = json.loads((ROOT / "omnivideo.config.json").read_text())
+
+WEAK = {
+    "de",
+    "da",
+    "do",
+    "das",
+    "dos",
+    "a",
+    "o",
+    "as",
+    "os",
+    "e",
+    "em",
+    "um",
+    "uma",
+    "que",
+    "com",
+    "pra",
+    "no",
+    "na",
+    "nos",
+    "nas",
+    "por",
+    "se",
+    "seu",
+    "sua",
+    "ao",
+    "à",
+    "às",
+    "é",
+    "ou",
+    "mas",
+}
+
+# stale line fields once the audio changes (`asr_similaridade`: legacy, from when captions transcribed)
+STALE_LINE_KEYS = ("start", "end", "words", "asr_similarity", "asr_similaridade")
+
+
+def fail(msg):
+    print(f"erro: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def load(video):
+    path = video / "scenes.json"
+    if not path.exists():
+        fail(f"{path} não existe — a etapa de roteiro de motion ainda não rodou")
+    return json.loads(path.read_text())
+
+
+def narrated(video):
+    """False: "Sem narração e voz" (content.json `narration: false`). The video skips the spoken script, the
+    narration, the voice and the captions: from the request to the motion script, the composition, the
+    render, the assembly and the editor, with each scene as long as its composition says."""
+    try:
+        return json.loads((Path(video) / "content.json").read_text()).get("narration") is not False
+    except (OSError, ValueError):
+        return True
+
+
+def save(video, data):
+    tmp = video / "scenes.json.tmp"
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+    tmp.replace(video / "scenes.json")
+
+
+def all_lines(data):
+    for scene in data["scenes"]:
+        for line in scene.get("lines", []):
+            yield scene, line
+
+
+def norm(word):
+    return re.sub(r"[^\w]", "", word.lower())
+
+
+def frame_ceil(seconds, fps):
+    return math.ceil(round(seconds * fps, 6)) / fps
+
+
+def probe_duration(path):
+    out = subprocess.run(
+        ["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(path)],
+        capture_output=True,
+        text=True,
+    )
+    try:
+        return float(out.stdout.strip())
+    except ValueError:
+        return None
+
+
+# --- voice -------------------------------------------------------------------
+# The providers (Fish Audio, Cartesia, VoiceStudio) live in tools/voice.py.
+
+
+def with_first(chain, provider):
+    """The chain with `provider` in front (the others follow as fallback, in the same order).
+    Only a provider this video's voice configured is valid: it is the list of the screen's picker."""
+    if not provider:
+        return chain
+    found = next((p for p in chain if p.id == provider), None)
+    if found is None:
+        fail(
+            f"{voice.NAMES.get(provider, provider)} não está entre os providers desta voz: "
+            f"{', '.join(voice.NAMES[p.id] for p in chain)}"
+        )
+    return [found] + [p for p in chain if p is not found]
+
+
+def pending_lines(video, data, chain, only, regenerate_fallback=False, regenerate=()):
+    """Lines without audio, with a different text or instruction, or whose requested
+    provider changed. A line generated by a fallback is not redone on its own (the
+    default being down would make every run generate everything again): only with
+    --regenerate-fallback. Those in `regenerate` (--regenerate) come out again even
+    when unchanged: another reading of the same text. With --regenerate, only them:
+    changing the video's provider does not drag the other lines along (a line's
+    button on the screen generates that line, not the whole video)."""
+    pref = chain[0].id
+    by_id = {p.id: p for p in chain}
+    pending = []
+    for scene, line in all_lines(data):
+        if only and scene["id"] != only:
+            continue
+        if regenerate and line["id"] not in regenerate:
+            continue
+        wav = video / "voice" / f"{line['id']}.wav"
+        if line["id"] in regenerate or not wav.exists() or not line.get("hash"):
+            pending.append(line)
+            continue
+        # line from before the providers: VoiceStudio, no provider change
+        used = line.get("provider", "voicestudio")
+        requested = line.get("provider_requested", used) if "provider" in line else pref
+        # `provider_pinned`: the line has its own provider (chosen on the screen), which the video's does not change;
+        # what the user chose (provider_pinned) is never redone on its own, not even by --regenerate-fallback
+        if not line.get("provider_pinned") and (requested != pref or (regenerate_fallback and used != requested)):
+            pending.append(line)
+            continue
+        d = voice.digest(by_id[used], line) if used in by_id else None
+        # VoiceStudio closed: the profile cannot be checked; the audio stays
+        if d is not None and d != line["hash"]:
+            pending.append(line)
+    return pending
+
+
+def normalize_wav(src, dest):
+    """Fish and Cartesia stream WAV, sometimes with the wrong header size:
+    ffmpeg rewrites it whole, as 16-bit PCM."""
+    r = subprocess.run(
+        ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(src), "-c:a", "pcm_s16le", str(dest)],
+        capture_output=True,
+        text=True,
+    )
+    if r.returncode != 0:
+        raise voice.Failed(f"áudio inválido: {r.stderr.strip()[:200]}", disable=False)
+
+
+RATE_LIMIT_TRIES = 4
+
+
+def generate_line(chain, disabled, line, tmp, run=None):
+    """Tries the video's provider and then the fallbacks. A provider that fails on
+    key, credit or service is dropped for the rest of the run: the following lines
+    all come from the same voice. A 429 (too many lines at once, with the voice in
+    parallel) is not a failure of the provider: wait and try it again. `run`
+    (usage.Run) records what was generated and what failed."""
+    for prov in chain:
+        if prov.id in disabled:
+            continue
+        reason = prov.ready()
+        if reason:
+            print(f"⚠ {voice.NAMES[prov.id]} fora: {reason}")
+            if run:
+                run.failure(prov.id, line["id"], reason)
+            disabled.add(prov.id)
+            continue
+        for attempt in range(1, RATE_LIMIT_TRIES + 1):
+            try:
+                audio = prov.generate(line)
+                raw = tmp.with_suffix(".raw")
+                raw.write_bytes(audio)
+                if prov.id == "voicestudio":
+                    raw.replace(tmp)
+                else:
+                    normalize_wav(raw, tmp)
+                    raw.unlink(missing_ok=True)
+                return prov
+            except voice.Failed as exc:
+                if exc.rate_limited and attempt < RATE_LIMIT_TRIES:
+                    wait = 2 * attempt
+                    print(f"⚠ {line['id']}: {voice.NAMES[prov.id]} pediu calma (429); de novo em {wait}s")
+                    time.sleep(wait)
+                    continue
+                print(f"⚠ {line['id']}: {exc}" + ("" if prov is chain[-1] else " → tentando o próximo provider"))
+                if run:
+                    run.failure(prov.id, line["id"], exc)
+                if exc.disable:
+                    disabled.add(prov.id)
+                break
+    fail(f"{line['id']}: nenhum provider gerou a fala ({', '.join(voice.NAMES[p.id] for p in chain)})")
+
+
+def voice_groups(lines, provider):
+    """The lines split into equal groups, one per worker, generated at the same
+    time: `voice.parallel.lines_per_worker` lines each (12 lines at 4 each = 3
+    workers of 4), up to `max_workers`; when the cap is hit, the groups grow and
+    stay even (sizes differ by at most one). VoiceStudio runs on this machine and
+    generates one line at a time: one group."""
+    cfg = CFG["voice"].get("parallel") or {}
+    per = max(1, int(cfg.get("lines_per_worker", 4)))
+    cap = max(1, int(cfg.get("max_workers", 4)))
+    workers = 1 if provider == "voicestudio" else min(cap, math.ceil(len(lines) / per))
+    workers = max(1, min(workers, len(lines)))
+    size, extra = divmod(len(lines), workers)
+    groups, i = [], 0
+    for w in range(workers):
+        n = size + (1 if w < extra else 0)
+        groups.append(lines[i : i + n])
+        i += n
+    return groups
+
+
+def cmd_voice(video, only=None, regenerate_fallback=False, regenerate=(), provider=None):
+    if not narrated(video):
+        fail("este vídeo é sem narração e voz (content.json): não há voz a gerar")
+    import requests
+    import soundfile as sf
+
+    data = load(video)
+    ids = {l["id"] for _, l in all_lines(data)}
+    if set(regenerate) - ids:
+        fail(f"fala que não existe: {', '.join(sorted(set(regenerate) - ids))}")
+    chain = with_first(voice.chain(requests, data), provider)
+    print(
+        f"voz: {voice.NAMES[chain[0].id]}"
+        + (f" (fallback: {', '.join(voice.NAMES[p.id] for p in chain[1:])})" if chain[1:] else "")
+    )
+    (video / "voice").mkdir(exist_ok=True)
+    if not pending_lines(video, data, chain, only, regenerate_fallback, regenerate):
+        print("todas as falas já estão geradas")
+        warn_fallback(data)
+        return
+
+    # generating voice takes the machine (VoiceStudio is local): wait for the turn in
+    # the queue. The wait may be long, and scenes.json is re-read on the turn so as
+    # not to overwrite what changed meanwhile
+    # usage.Run records each line and, on exit (with or without error), reads the platforms' balance
+    with turn("voice", video), usage.Run(video.name) as run:
+        data = load(video)
+        chain = with_first(voice.chain(requests, data), provider)
+        pending = pending_lines(video, data, chain, only, regenerate_fallback, regenerate)
+        if not pending:
+            print("todas as falas já estão geradas")
+        else:
+            run.before(chain[0].id)
+        disabled = set()
+        profile_id = (voice.voice_profile(data)[0] or {}).get("id")
+        groups = voice_groups(pending, chain[0].id) if pending else []
+        if len(groups) > 1:
+            print(f"{len(pending)} fala(s) em {len(groups)} grupos ao mesmo tempo: {', '.join(str(len(g)) for g in groups)}")
+        # generating runs in parallel; writing (voice/, history/, scenes.json, the usage log) one at a time
+        lock = threading.Lock()
+        count = itertools.count(1)
+
+        def one(line):
+            wav = video / "voice" / f"{line['id']}.wav"
+            tmp = wav.with_name(f".{wav.stem}.new.wav")
+            started = time.time()
+            prov = generate_line(chain, disabled, line, tmp, run)
+            model = getattr(prov, "model", None)
+            with lock:
+                digest = voice.digest(prov, line)
+                # this line's previous voice goes to history/voice/, with the text it
+                # said (scenes.json already has the new text)
+                sidecar = wav.with_suffix(".json")
+                with keep_previous(
+                    video, "voice", line["id"], [str(wav.relative_to(video)), str(sidecar.relative_to(video))]
+                ):
+                    tmp.replace(wav)
+                    dur = sf.info(str(wav)).duration
+                    sidecar.write_text(
+                        json.dumps(
+                            {
+                                "text": line["text"],
+                                "instruct": line.get("instruct"),
+                                "hash": digest,
+                                "provider": prov.id,
+                                "profile": profile_id,
+                                "dur": round(dur, 3),
+                            },
+                            ensure_ascii=False,
+                        )
+                        + "\n"
+                    )
+                line.update(
+                    wav=str(wav.relative_to(video)),
+                    dur=round(dur, 3),
+                    hash=digest,
+                    provider=prov.id,
+                    provider_requested=chain[0].id,
+                )
+                # the voice (profile) that said the line, for the player to show; with no profile registered, none
+                if profile_id:
+                    line["voice_profile"] = profile_id
+                else:
+                    line.pop("voice_profile", None)
+                for stale in STALE_LINE_KEYS:
+                    line.pop(stale, None)
+                if line["id"] in regenerate:
+                    # another reading with a chosen provider: it stays for this line; without a choice, back to the video's
+                    if provider:
+                        line["provider_pinned"] = True
+                    else:
+                        line.pop("provider_pinned", None)
+                save(video, data)
+                run.line(prov.id, line, dur, fallback=prov is not chain[0], model=model)
+                rate = len(line["text"].split()) / dur if dur else 0
+                flag = "  ← ritmo estranho, ouvir" if not 2.2 <= rate <= 4.5 else ""
+                via = "" if prov is chain[0] else f" · via {voice.NAMES[prov.id]} (fallback)"
+                if prov.id == "fish" and not voice.is_free(model):
+                    via += f" · {model} (pago)"
+                print(
+                    f"[{next(count)}/{len(pending)}] {line['id']}: {dur:.2f}s de áudio em {time.time() - started:.0f}s "
+                    f"({rate:.1f} palavras/s){via}{flag}",
+                    flush=True,
+                )
+
+        def group(lines):
+            for line in lines:
+                one(line)
+
+        # a line no provider generated ends the run (fail → SystemExit): the other
+        # groups finish the line they are on, and the error comes out here
+        with ThreadPoolExecutor(max_workers=max(1, len(groups))) as pool:
+            for _ in pool.map(group, groups):
+                pass
+        warn_fallback(data)
+
+
+def cmd_use(video, line_id, version):
+    """Restores a version kept in history/voice/<line>/<version>/ as the line's. The
+    one that was active goes to history in its place: swapping back is the same
+    command. Only a version that says the current text is valid."""
+    data = load(video)
+    line = next((l for _, l in all_lines(data) if l["id"] == line_id), None)
+    if not line:
+        fail(f"a fala {line_id} não existe no scenes.json")
+    src = video / "history" / "voice" / line_id / version
+    old_wav, old_sidecar = src / f"{line_id}.wav", src / f"{line_id}.json"
+    if not old_wav.exists():
+        fail(f"não há versão {version} da fala {line_id} em history/voice/")
+    if not old_sidecar.exists():
+        fail(f"a versão {version} não guardou o texto que dizia ({line_id}.json): não dá para conferir")
+    meta = json.loads(old_sidecar.read_text())
+    if meta.get("text") != line["text"] or meta.get("instruct") != line.get("instruct"):
+        fail(f"a versão {version} diz outro texto: “{meta.get('text')}”. A fala agora é “{line['text']}”")
+
+    wav = video / "voice" / f"{line_id}.wav"
+    sidecar = wav.with_suffix(".json")
+    # copy without the old mtime: status sees the export and captions as outdated
+    with keep_previous(video, "voice", line_id, [str(wav.relative_to(video)), str(sidecar.relative_to(video))]):
+        shutil.copyfile(old_wav, wav)
+        shutil.copyfile(old_sidecar, sidecar)
+    shutil.rmtree(src, ignore_errors=True)
+    dur = meta.get("dur") or probe_duration(wav)
+    line.update(
+        wav=str(wav.relative_to(video)),
+        dur=round(dur, 3),
+        hash=meta["hash"],
+        provider=meta.get("provider", "voicestudio"),
+        provider_requested=voice.preferred(data),
+    )
+    if meta.get("profile"):
+        line["voice_profile"] = meta["profile"]
+    else:
+        line.pop("voice_profile", None)
+    # a chosen version from another provider is a choice, not a fallback: no general `voice` undoes it
+    if line["provider"] != line["provider_requested"]:
+        line["provider_pinned"] = True
+    else:
+        line.pop("provider_pinned", None)
+    for stale in STALE_LINE_KEYS:
+        line.pop(stale, None)
+    save(video, data)
+    print(
+        f"{line_id}: agora usa a versão de {version} ({dur:.2f}s, {voice.NAMES.get(line['provider'], line['provider'])}); "
+        "a anterior ficou no historico. Refaça tempo, render, legenda e montagem."
+    )
+
+
+def mixed_voices(data):
+    """Different providers nobody chose (fallback). A line with provider_pinned was
+    chosen by the user on the screen and is left out: it is not something to unify."""
+    used = {}
+    for _, line in all_lines(data):
+        if line.get("wav") and not line.get("provider_pinned"):
+            used.setdefault(line.get("provider", "voicestudio"), []).append(line["id"])
+    return used if len(used) > 1 else None
+
+
+def warn_fallback(data):
+    mixed = mixed_voices(data)
+    if mixed:
+        print(
+            "⚠ vozes de providers diferentes neste vídeo: "
+            + "; ".join(f"{voice.NAMES.get(p, p)}: {', '.join(ids)}" for p, ids in mixed.items())
+        )
+    pref = voice.preferred(data)
+    fallback = [
+        l["id"]
+        for _, l in all_lines(data)
+        if l.get("wav") and l.get("provider", pref) != pref and not l.get("provider_pinned")
+    ]
+    if fallback:
+        print(
+            f"⚠ {len(fallback)} fala(s) saíram de fallback, não do {voice.NAMES[pref]}: {', '.join(fallback)}. "
+            f"Com ele de volta: `omnivideo.py voice <video> --regenerate-fallback`"
+        )
+
+
+# --- timing ------------------------------------------------------------------
+
+
+def cmd_timing_silent(video, data):
+    """No voice: a scene lasts as long as its composition says, the larger of `min_duration` and the last
+    beat's `t` plus the hold (a beat's `t` is in seconds, there are no words to tie it to)."""
+    t = CFG["timing"]
+    fps = data["format"]["fps"]
+    clock = 0.0
+    print(f"{'cena':<6}{'início':>8}{'duração':>9}  (sem narração e voz)")
+    for scene in data["scenes"]:
+        beats = [b["t"] for b in scene.get("beats", []) if isinstance(b.get("t"), (int, float))]
+        if not beats and not scene.get("min_duration"):
+            fail(f"cena {scene['id']} sem `min_duration` nem beats com `t`: sem voz, é a composição que dá a duração")
+        length = max(scene.get("min_duration", 0.0), (max(beats) + scene.get("hold", t["final_hold"])) if beats else 0.0)
+        scene["duration"] = round(frame_ceil(length, fps), 4)
+        scene["start"] = round(clock, 4)
+        clock += scene["duration"]
+        print(f"{scene['id']:<6}{scene['start']:>8.2f}{scene['duration']:>9.2f}")
+    data["total_duration"] = round(clock, 4)
+    save(video, data)
+    print(f"total: {clock:.2f}s")
+
+
+def cmd_timing(video, only=None):
+    data = load(video)
+    if not narrated(video):
+        return cmd_timing_silent(video, data)
+    t = CFG["timing"]
+    fps = data["format"]["fps"]
+    missing = [l["id"] for _, l in all_lines(data) if "dur" not in l]
+    if missing:
+        fail(f"falas sem áudio: {', '.join(missing)} — rode `omnivideo.py voice` antes")
+
+    clock = 0.0
+    print(f"{'cena':<6}{'início':>8}{'duração':>9}{'voz até':>9}  falas")
+    for scene in data["scenes"]:
+        # a scene may have its own lead_in and hold: a sentence that continues into the
+        # next scene must not get the full silence of a cut
+        cursor = scene.get("lead_in", t["lead_in"])
+        for line in scene.get("lines", []):
+            line["start"] = round(frame_ceil(cursor, fps), 4)
+            line["end"] = round(line["start"] + line["dur"], 4)
+            cursor = line["end"] + t["pause_between_lines"]
+        voice_end = scene["lines"][-1]["end"] if scene.get("lines") else 0.0
+        length = max(voice_end + scene.get("hold", t["final_hold"]), scene.get("min_duration", 0.0))
+        scene["duration"] = round(frame_ceil(length, fps), 4)
+        scene["start"] = round(clock, 4)
+        clock += scene["duration"]
+        print(
+            f"{scene['id']:<6}{scene['start']:>8.2f}{scene['duration']:>9.2f}{voice_end:>9.2f}  "
+            f"{len(scene.get('lines', []))}"
+        )
+    data["total_duration"] = round(clock, 4)
+    save(video, data)
+    print(f"total: {clock:.2f}s")
+
+
+# --- captions ----------------------------------------------------------------
+
+
+def word_weight(word):
+    """How long the word takes, relative to the others: its letters (measured against
+    Whisper, letters beat syllables). Numbers and acronyms weigh by what is said."""
+    w = norm(word)
+    if w.isdigit():
+        return 3 * len(w)
+    if word.strip(".,;:!?…").isupper() and len(w) > 1:
+        return 2.5 * len(w)
+    return max(1, len(w))
+
+
+def voice_spans(wav):
+    """Where the voice starts and ends in the file, and the silences inside (≥ 0.12 s)."""
+    import numpy as np
+    import soundfile as sf
+
+    audio, sr = sf.read(str(wav), dtype="float32", always_2d=True)
+    audio = audio.mean(axis=1)
+    step = int(sr * 0.01)
+    n = max(1, len(audio) // step)
+    rms = np.sqrt(np.mean(audio[: n * step].reshape(n, step) ** 2, axis=1) + 1e-12)
+    # start and end with a low threshold (the opening consonant is weak); silence with a higher one
+    edge = rms > max(rms.max() * 0.015, np.percentile(rms, 10) * 2)
+    voiced = rms > max(rms.max() * 0.04, np.percentile(rms, 10) * 3)
+    if not edge.any():
+        return 0.0, len(audio) / sr, []
+    start, end = int(np.argmax(edge)), int(n - np.argmax(edge[::-1]))
+    silences, k = [], start
+    while k < end:
+        if not voiced[k]:
+            j = k
+            while j < end and not voiced[j]:
+                j += 1
+            if j - k >= 12:
+                silences.append((k * 0.01, j * 0.01))
+            k = j
+        else:
+            k += 1
+    return start * 0.01, end * 0.01, silences
+
+
+PAUSE = {",": 1.5, ";": 1.5, ":": 1.5, ".": 2.5, "?": 2.5, "!": 2.5, "…": 2.5}
+
+
+def estimate_words(wav, text):
+    """Time of each word without transcribing: the text is known, so all that is
+    left is splitting the spoken span of the audio. Each word weighs by its letters,
+    and commas and periods weigh a pause. A real silence near punctuation becomes an
+    anchor: the word ends where it starts and the next one enters where it ends."""
+    words = text.split()
+    if not words:
+        return []
+    start, end, silences = voice_spans(wav)
+    weight = [word_weight(w) for w in words]
+    pause = [PAUSE.get(w[-1], 0.0) if k < len(words) - 1 else 0.0 for k, w in enumerate(words)]
+    total = sum(weight) + sum(pause)
+
+    # where each pause would fall by the math; the nearest silence (up to 0.4 s), in order, anchors
+    anchors, cursor, used = {}, start, 0
+    for k in range(len(words)):
+        cursor += (end - start) * weight[k] / total
+        if pause[k]:
+            mid = cursor + (end - start) * pause[k] / total / 2
+            near = [(abs((s + e) / 2 - mid), i) for i, (s, e) in enumerate(silences) if i >= used]
+            if near and min(near)[0] <= 0.4:
+                i = min(near)[1]
+                anchors[k] = silences[i]
+                used = i + 1
+            cursor += (end - start) * pause[k] / total
+
+    # between anchors, split by weight
+    times, a, seg_start = [], 0, start
+    for b in sorted(anchors) + [len(words) - 1]:
+        seg_end = anchors[b][0] if b in anchors else end
+        p = weight[a : b + 1]
+        q = pause[a:b] + [0.0]
+        total_seg = sum(p) + sum(q)
+        t = seg_start
+        for k in range(a, b + 1):
+            dur = (seg_end - seg_start) * weight[k] / total_seg
+            times.append((t, t + dur))
+            t += dur + (seg_end - seg_start) * q[k - a] / total_seg
+        if b in anchors:
+            seg_start = anchors[b][1]
+        a = b + 1
+        if a >= len(words):
+            break
+    return [{"w": w, "s": round(s, 3), "e": round(e, 3)} for w, (s, e) in zip(words, times)]
+
+
+def phrases(words, max_chars):
+    """Cuts at sentence ends and commas; joins short comma pieces."""
+    length = lambda ws: len(" ".join(w["w"] for w in ws))
+    parts, cur = [], []
+    for w in words:
+        cur.append(w)
+        if w["w"].endswith((".", "?", "!", "…", ",", ";", ":")):
+            parts.append(cur)
+            cur = []
+    if cur:
+        parts.append(cur)
+    merged = []
+    for part in parts:
+        prev = merged[-1] if merged else None
+        if (
+            prev
+            and prev[-1]["w"].endswith(",")
+            and (length(prev) < 12 or length(part) < 8)
+            and length(prev + part) <= max_chars
+        ):
+            merged[-1] = prev + part
+        else:
+            merged.append(part)
+    return merged
+
+
+def balanced_split(words, max_chars):
+    length = lambda ws: len(" ".join(w["w"] for w in ws))
+    if length(words) <= max_chars:
+        return [words]
+    n = math.ceil(length(words) / max_chars)
+    best = None
+    while best is None or best[0] >= 10_000:
+        for cuts in itertools.combinations(range(1, len(words)), n - 1):
+            parts = [words[a:b] for a, b in zip((0,) + cuts, cuts + (len(words),))]
+            target = length(words) / n
+            cost = sum((length(p) - target) ** 2 for p in parts)
+            cost += sum(10_000 for p in parts if length(p) > max_chars)
+            cost += sum(2_000 for p in parts[:-1] if norm(p[-1]["w"]) in WEAK)
+            cost += sum(2_000 for p in parts[:-1] if norm(p[-1]["w"]).isdigit())
+            cost += sum(3_000 for p in parts if len(p) == 1)
+            if best is None or cost < best[0]:
+                best = (cost, parts)
+        if best[0] >= 10_000 and n < len(words):
+            n += 1
+            best = None
+        else:
+            break
+    return best[1]
+
+
+def srt_time(seconds):
+    ms = int(round(seconds * 1000))
+    h, ms = divmod(ms, 3_600_000)
+    m, ms = divmod(ms, 60_000)
+    s, ms = divmod(ms, 1000)
+    return f"{h:02}:{m:02}:{s:02},{ms:03}"
+
+
+def caption_text(words):
+    text = " ".join(w["w"] for w in words)
+    return text[:-1] if text.endswith((",", ".", ";", ":")) else text
+
+
+def cmd_captions(video, only=None):
+    if not narrated(video):
+        fail("este vídeo é sem narração e voz (content.json): não há falas para legendar")
+    # what is missing shows up now, not after waiting for the turn
+    targets_of(load(video), only)
+    # it takes seconds, but goes through the queue: the studio takes the stage's history and log from it
+    with turn("captions", video):
+        write_captions(video, only)
+
+
+def targets_of(data, only):
+    targets = [(s, l) for s, l in all_lines(data) if not only or s["id"] == only]
+    if not targets:
+        fail(f"nenhuma fala{' na cena ' + only if only else ''}")
+    if any("wav" not in l for _, l in targets):
+        fail("há falas sem áudio — rode `omnivideo.py voice` antes")
+    if not only and any("start" not in l or "start" not in s for s, l in targets):
+        fail("as falas ainda não têm posição — rode `omnivideo.py timing` antes")
+    return targets
+
+
+def apply_texts(data, cues):
+    """Text edited on the screen (`captions.texts`, see tools/captions.mjs) goes back to
+    the caption the line still generates with the same `original` text: same id,
+    else the same line, else any one (the screen's id may have fallen on the
+    neighbouring line). An edit with no match is dropped, with a warning: the line changed."""
+    cap = data.get("captions") or {}
+    left = dict(cap.get("texts") or {})
+    if not left:
+        return
+    line_of = lambda i: i.rsplit(".", 1)[0]
+    rules = (lambda c, k: c[3] == k, lambda c, k: line_of(c[3]) == line_of(k), lambda c, k: True)
+    matched = {}
+    for matches in rules:
+        for key, ed in list(left.items()):
+            cue = next(
+                (c for c in cues if c[3] not in matched and c[2] == ed.get("original") and matches(c, key)), None
+            )
+            if cue:
+                cue[2] = ed["text"]
+                matched[cue[3]] = ed
+                del left[key]
+    for key, ed in left.items():
+        print(f"aviso: o texto editado de {key} (“{ed.get('text')}”) saiu: a fala não gera mais “{ed.get('original')}”")
+    if matched:
+        cap["texts"] = matched
+        print(f"{len(matched)} legenda(s) com o texto editado na tela")
+    else:
+        cap.pop("texts", None)
+        if not cap:
+            data.pop("captions", None)
+
+
+def write_captions(video, only):
+    data = load(video)
+    cc = CFG["captions"]
+    targets = targets_of(data, only)
+    max_chars = cc["max_chars"][data["format"]["aspect"]]
+
+    cues = []
+    for scene, line in targets:
+        words = estimate_words(video / line["wav"], line["text"])
+        line["words"] = words
+        line.pop("asr_similarity", None)  # from when captions transcribed
+        line.pop("asr_similaridade", None)  # legacy name
+        if only:
+            continue
+        base = scene["start"] + line["start"]
+        chunks = [c for part in phrases(words, max_chars) for c in balanced_split(part, max_chars)]
+        for n, chunk in enumerate(chunks, 1):
+            # id `<line>.<n>`, the same as tools/captions.mjs
+            cues.append([base + chunk[0]["s"], base + chunk[-1]["e"], caption_text(chunk), f"{line['id']}.{n}"])
+
+    for k, cue in enumerate(cues):
+        nxt = cues[k + 1][0] if k + 1 < len(cues) else None
+        if nxt is not None and nxt - cue[1] < 0.35:
+            cue[1] = nxt
+        cue[1] = max(cue[1], cue[0] + cc["min_duration"])
+        if nxt is not None:
+            cue[1] = min(cue[1], nxt)
+
+    if only:
+        save(video, data)
+        print(f"{only}: tempo de cada palavra gravado em {len(targets)} fala(s); captions.srt não muda")
+    else:
+        apply_texts(data, cues)
+        srt = "\n".join(f"{i}\n{srt_time(a)} --> {srt_time(b)}\n{t}\n" for i, (a, b, t, _) in enumerate(cues, 1))
+        with keep_previous(video, "captions", None, ["captions.srt"]):
+            (video / "captions.srt").write_text(srt, encoding="utf-8")
+        save(video, data)
+        longest = max((len(c[2]) for c in cues), default=0)
+        print(f"captions.srt: {len(cues)} legendas, maior com {longest} caracteres (limite {max_chars})")
+
+
+# --- status ------------------------------------------------------------------
+
+
+def deadline_passed(a):
+    return (
+        a.get("mode") == "auto"
+        and time.time() >= datetime.fromisoformat(a["deadline"].replace("Z", "+00:00")).timestamp()
+    )
+
+
+def scenes_approval(video, ids):
+    """Approval of the motion script's scenes (tools/approval.mjs). None: the video
+    has no round (made before it existed). A passed deadline in auto mode counts
+    as approved, as in approval.mjs, which is the writer."""
+    path = video / "motion" / "approval.json"
+    if not path.exists():
+        return None
+    a = json.loads(path.read_text())
+    scenes = a.get("scenes", {})
+    # round closed: a scene created afterwards (the composition split one) does not reopen the stage
+    if a.get("completed_at"):
+        ids = [i for i in ids if i in scenes]
+    passed = deadline_passed(a)
+    states = [(scenes.get(i) or {}).get("state", "pending") for i in ids]
+    states = ["approved" if s == "pending" and passed else s for s in states]
+    change = [i for i, s in zip(ids, states) if s == "change_requested"]
+    pending = [i for i, s in zip(ids, states) if s == "pending"]
+    if change and not pending:
+        return {"ok": False, "status": "change_requested", "detail": f"cenas pedem alteração: {', '.join(change)}"}
+    if pending:
+        who = "contagem pausada: o usuário está editando" if a.get("mode") != "auto" else "aprovam sozinhas no prazo"
+        return {"ok": False, "status": "pending", "detail": f"cenas esperando aprovação: {', '.join(pending)} ({who})"}
+    return {"ok": True, "status": "approved", "detail": None}
+
+
+def script_approval(video):
+    """Approval of the script (tools/approval.mjs --script, script-approval.json).
+    None: the video has no round (made before it existed, or in the chat without one).
+    A passed deadline in auto mode counts as approved, as for the scenes."""
+    path = video / "script-approval.json"
+    if not path.exists():
+        return None
+    a = json.loads(path.read_text())
+    item = a.get("items", {}).get("script") or {}
+    state = item.get("state", "pending")
+    if state == "pending" and deadline_passed(a):
+        state = "approved"
+    if state == "change_requested":
+        return {"ok": False, "status": "change_requested", "detail": f"pede alteração: «{item.get('comment', '')}»"}
+    if state == "pending":
+        who = "contagem pausada: o usuário está editando" if a.get("mode") != "auto" else "aprova sozinho no prazo"
+        return {"ok": False, "status": "pending", "detail": f"esperando aprovação ({who})"}
+    return {"ok": True, "status": "approved", "detail": None}
+
+
+# PT labels of `changed` values, for the human detail text
+CHANGED_LABEL = {"captions": "legenda", "scenes": "cenas", "motion": "motion", "voice": "voz"}
+
+
+def diagnose(video):
+    """What `status` says, as data: the studio and other integrations read this
+    instead of redoing the math."""
+    stages = []
+
+    def stage(id_, number, name, ok, detail=None, **extra):
+        stages.append({"id": id_, "number": number, "name": name, "ok": bool(ok), "detail": detail, **extra})
+
+    silent = not narrated(video)
+
+    def skipped(id_, number, name):
+        """"Sem narração e voz": the stage does not exist for this video; it counts as done and says why."""
+        stage(id_, number, name, True, "sem narração e voz", skipped=True)
+
+    has_script = (video / "script.md").exists()
+    script_appr = script_approval(video) if has_script else None
+    if silent:
+        skipped("script", "1", "roteiro")
+    else:
+        stage(
+            "script",
+            "1",
+            "roteiro",
+            has_script and (script_appr is None or script_appr["ok"]),
+            script_appr and script_appr["detail"],
+            approval=script_appr and script_appr["status"],
+        )
+    data = json.loads((video / "scenes.json").read_text()) if (video / "scenes.json").exists() else None
+    scenes = data["scenes"] if data else []
+    written = (video / "motion.md").exists() and data is not None
+    approval = scenes_approval(video, [s["id"] for s in scenes]) if written else None
+    stage(
+        "motion_script",
+        "2",
+        "roteiro de motion",
+        written and (approval is None or approval["ok"]),
+        approval and approval["detail"],
+        approval=approval and approval["status"],
+    )
+    lines = [l for s in scenes for l in s.get("lines", [])]
+    # narration and voice apply to the whole video: one scene with lines is not the stage done
+    is_narrated = bool(scenes) and all(s.get("lines") for s in scenes) and all(l.get("text") for l in lines)
+    voiced = is_narrated and all((video / l.get("wav", "-")).exists() for l in lines)
+    stage(
+        "motion",
+        "3",
+        "motion (stills e folha de contatos)",
+        bool(scenes) and all((video / s.get("html", f"motion/{s['id']}.html")).exists() for s in scenes),
+    )
+    if silent:
+        skipped("narration", "4", "narração")
+    else:
+        stage("narration", "4", "narração", is_narrated)
+    # the user is swapping voices on the screen: the voice is not decided, and nothing after it runs
+    pause_file = video / "voice-pause.json"
+    voice_pause = json.loads(pause_file.read_text()) if pause_file.exists() else None
+    if silent:
+        skipped("voice", "5", "voz")
+    else:
+        stage(
+            "voice",
+            "5",
+            "voz",
+            voiced and not voice_pause,
+            "em escolha na tela: o usuário está trocando vozes. Pare aqui; ele segue pelo botão "
+            '"Seguir com estas vozes" na etapa Voz'
+            if voice_pause
+            else None,
+            pause=voice_pause,
+        )
+    stage("timing", "5", "tempo", bool(scenes) and all("duration" in s and "start" in s for s in scenes))
+
+    shifted = []
+
+    def rendered(s):
+        mp4 = video / s.get("mp4", f"motion/{s['id']}.mp4")
+        d = probe_duration(mp4) if mp4.exists() else None
+        if d is None or abs(d - s.get("duration", -1)) > 1.5 / data["format"]["fps"]:
+            return False
+        # background on video time: the MP4 is valid only for the start it was rendered with
+        info = video / "motion" / f"{s['id']}.render.json"
+        if info.exists():
+            r = json.loads(info.read_text())
+            if r.get("video_time") and abs(r.get("start", -1) - s.get("start", -2)) > 1e-3:
+                shifted.append(s["id"])
+                return False
+        return True
+
+    ok_render = bool(scenes) and all(["duration" in s and rendered(s) for s in scenes])
+    stage(
+        "render",
+        "6",
+        "render final dos motions",
+        ok_render,
+        f"início mudou em {', '.join(shifted)}: o fundo pularia no corte" if shifted else None,
+        stale=shifted,
+    )
+    if silent:
+        skipped("captions", "7", "legenda")
+    else:
+        stage("captions", "7", "legenda", (video / "captions.srt").exists() and all("words" in l for l in lines))
+    # 8: assemble.mjs (ffmpeg) writes export/assembly.json; a video assembled earlier in
+    # Premiere (premiere.json with export) also counts
+    assembly = video / "export" / "assembly.json"
+    aj = json.loads(assembly.read_text()) if assembly.exists() else {}
+    pj = json.loads((video / "premiere.json").read_text()) if (video / "premiere.json").exists() else {}
+    # what changed after the export, for the screen to say (and the export-again button to know) what
+    inputs = {
+        "captions": [video / "captions.srt"],
+        "scenes": [video / "scenes.json"],
+        "motion": [video / s.get("mp4", f"motion/{s['id']}.mp4") for s in scenes],
+        "voice": [video / l["wav"] for l in lines if l.get("wav")],
+    }
+    if aj:
+        ready = (video / aj.get("mp4", "")).exists()
+        changed = [
+            k
+            for k, ps in inputs.items()
+            if ready and any(p.exists() and p.stat().st_mtime > assembly.stat().st_mtime for p in ps)
+        ]
+        outdated = bool(changed)
+        stage(
+            "export",
+            "8",
+            "montagem e exportação",
+            ready and not outdated,
+            f"desatualizada: {', '.join(CHANGED_LABEL[k] for k in changed)} mudou depois; rode assemble.mjs de novo"
+            if outdated
+            else None,
+            outdated=outdated,
+            changed=changed,
+        )
+    else:
+        legacy_export = bool(pj.get("export")) and Path(pj["export"]).exists()
+        stage(
+            "export", "8", "montagem e exportação", legacy_export, "exportado pelo Premiere" if legacy_export else None
+        )
+
+    warnings = []
+    if data and scenes:
+        library = Path(CFG["references"]["dir"])
+        refs = data.get("references") or []
+        if not refs:
+            warnings.append("scenes.json sem `references`: o estilo não saiu de um estilo visual")
+        for ref in refs:
+            if not (library / ref).is_dir():
+                warnings.append(f"estilo visual “{ref}” não existe em {library}")
+        warnings.extend(hard_lines(lines))
+        mixed = mixed_voices(data)
+        if mixed:
+            warnings.append(
+                "vozes de providers diferentes: "
+                + "; ".join(f"{voice.NAMES.get(p, p)} em {len(ids)} fala(s)" for p, ids in mixed.items())
+            )
+    nxt = next((s for s in stages if not s["ok"]), None)
+    return {
+        "video": video.name,
+        "dir": str(video),
+        "stages": stages,
+        "next": {"id": nxt["id"], "name": label(nxt)} if nxt else None,
+        "ready": nxt is None,
+        "total_duration": data["total_duration"] if data and "total_duration" in data else None,
+        "scenes": len(scenes),
+        "lines": len(lines),
+        "warnings": warnings,
+    }
+
+
+def label(stage):
+    return f"{stage['name']} ({stage['detail']})" if stage["detail"] else stage["name"]
+
+
+def hard_lines(lines):
+    """Punctuation the voice reads as an intonation break (reference/writing-for-voice.md)."""
+    warnings = []
+    for l in lines:
+        t = l.get("text") or ""
+        reasons = []
+        if ":" in t:
+            reasons.append("dois-pontos")
+        if ";" in t:
+            reasons.append("ponto e vírgula")
+        if any(c in t for c in "—–()/"):
+            reasons.append("travessão, parênteses ou barra")
+        if "..." in t or "…" in t:
+            reasons.append("reticências")
+        if t.count(",") > 1:
+            reasons.append(f"{t.count(',')} vírgulas")
+        if re.search(r"\d+\.\d", t):
+            reasons.append("número com ponto (versão?)")
+        if reasons:
+            warnings.append(
+                f"fala {l.get('id')} difícil para a voz ({', '.join(reasons)}): reescreva (reference/writing-for-voice.md)"
+            )
+    return warnings
+
+
+def cmd_status(video, as_json=False):
+    d = diagnose(video)
+    if as_json:
+        print(json.dumps(d, ensure_ascii=False, indent=2))
+        return
+    for s in d["stages"]:
+        print(f"{'✓' if s['ok'] else '·'} {label(s)}")
+    if d["total_duration"] is not None:
+        print(f"duração total: {d['total_duration']:.2f}s em {d['scenes']} cenas, {d['lines']} falas")
+    for w in d["warnings"]:
+        print(f"⚠ {w}")
+    print(f"próxima etapa: {d['next']['name']}" if d["next"] else "pronto")
+
+
+COMMANDS = {"status": cmd_status, "voice": cmd_voice, "timing": cmd_timing, "captions": cmd_captions}
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    as_json = "--json" in args
+    if as_json:
+        args.remove("--json")
+    regenerate_fallback = "--regenerate-fallback" in args
+    if regenerate_fallback:
+        args.remove("--regenerate-fallback")
+    regenerate = ()
+    if "--regenerate" in args:
+        i = args.index("--regenerate")
+        regenerate = tuple(x for x in (args[i + 1] if i + 1 < len(args) else "").split(",") if x)
+        args = args[:i] + args[i + 2 :]
+        if not regenerate:
+            fail("--regenerate precisa dos ids das falas (ex.: --regenerate c03f1,c05f1)")
+    provider = None
+    if "--provider" in args:
+        i = args.index("--provider")
+        provider = args[i + 1] if i + 1 < len(args) else None
+        args = args[:i] + args[i + 2 :]
+        if not provider:
+            fail("--provider precisa do id do provider (ex.: --provider fish)")
+        if not regenerate:
+            fail("--provider só vale com --regenerate: é o provider daquela fala, não do vídeo")
+    use = None
+    if "--use" in args:
+        i = args.index("--use")
+        use = args[i + 1 : i + 3]
+        args = args[:i] + args[i + 3 :]
+        if len(use) != 2:
+            fail("--use precisa da fala e da versão (ex.: --use c03f1 2026-10-12T14-03-11-482Z)")
+    only = None
+    if "--scene" in args:
+        i = args.index("--scene")
+        only = args[i + 1] if i + 1 < len(args) else None
+        args = args[:i] + args[i + 2 :]
+        if not only:
+            fail("--scene precisa do id da cena (ex.: --scene c01)")
+    if len(args) != 2 or args[0] not in COMMANDS:
+        print(__doc__)
+        sys.exit(2)
+    if only and args[0] not in ("voice", "captions"):
+        fail("--scene só vale para voice e captions")
+    if as_json and args[0] != "status":
+        fail("--json só vale para status")
+    if regenerate_fallback and args[0] != "voice":
+        fail("--regenerate-fallback só vale para voice")
+    if (regenerate or use) and args[0] != "voice":
+        fail("--regenerate e --use só valem para voice")
+    if regenerate and use:
+        fail("--regenerate gera outra leitura; --use escolhe uma guardada: um de cada vez")
+    target = Path(args[1]).resolve()
+    if not target.is_dir():
+        fail(f"{target} não é uma pasta de vídeo")
+    if only and not any(s["id"] == only for s in load(target)["scenes"]):
+        fail(f"a cena {only} não existe no scenes.json")
+    if as_json:
+        cmd_status(target, as_json=True)
+    elif args[0] == "voice" and use:
+        cmd_use(target, *use)
+    elif args[0] == "voice":
+        cmd_voice(target, only, regenerate_fallback, regenerate, provider)
+    else:
+        COMMANDS[args[0]](target, only) if only else COMMANDS[args[0]](target)