proofcut 0.29.0__py3-none-any.whl

proofcut/__init__.py

@@ -0,0 +1,14 @@
+"""proofcut — a source-available, local-first AI video editor.
+
+The public surface is the MCP server (``proofcut mcp``) and the equivalent CLI
+(``proofcut <subcommand>``). Everything operates on a *project directory*; see
+:mod:`proofcut.project` for its layout.
+"""
+
+#: Duplicated in ``pyproject.toml`` deliberately. The metadata lookup that
+#: would remove the copy reads the *installed* dist-info, which goes stale
+#: against an editable checkout without saying so; tests/test_version.py
+#: has the reasoning and holds the two numbers together.
+__version__ = "0.29.0"
+
+__all__ = ["__version__"]

proofcut/_face_worker.py

@@ -0,0 +1,109 @@
+"""The detector side of `faces`, run under a *different* interpreter.
+
+**This module is never imported by proofcut.** It is executed by the Python that
+`faces.face_python()` resolves — a venv with insightface and onnxruntime in it —
+which is the whole reason it is a separate file. proofcut's own venv stays free of
+both, exactly as `asr.py` keeps whisper behind a binary and `_vlm_worker.py`
+keeps torch behind an interpreter. It lives inside the package only so it ships
+with it.
+
+It reads one JSON job from `argv[1]` and writes one JSON result to `argv[2]`. A
+file rather than stdout for `_vlm_worker.py`'s reason: insightface prints its
+model directory and its provider list to whichever stream it feels like, and
+that landing in the middle of a JSON document is a parse error that reads like a
+detector failure.
+
+The detector is built **once** for the whole job — every window of every clip
+goes through one session.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _frame(media: str, ts: float):
+    """Pull one BGR frame from `media` at `ts`, through the ffmpeg binary.
+
+    PNG down the pipe and `cv2.imdecode` back, rather than rawvideo reshaped to
+    a size passed in the job: the size would be proofcut's manifest talking about
+    the file, and a reshape against a stale width is not an error — it is a
+    sheared frame that detects plausible faces in the wrong places. Here the
+    decoder tells us the geometry and there is nothing to disagree with.
+
+    Deliberately not `ffmpeg-python`: this file's dependencies are whatever the
+    resolved interpreter happens to have, and every extra import is another way
+    for it to fail on a box that could otherwise detect. numpy and cv2 come with
+    insightface; a convenience wrapper around a subprocess does not.
+    """
+    import cv2
+    import numpy as np
+
+    completed = subprocess.run(
+        [
+            "ffmpeg", "-nostdin", "-v", "error",
+            "-ss", f"{ts:.4f}", "-i", media,
+            "-frames:v", "1", "-f", "image2pipe", "-c:v", "png", "pipe:",
+        ],
+        capture_output=True,
+        check=True,
+    )  # fmt: skip
+    if not completed.stdout:
+        raise RuntimeError(
+            f"ffmpeg returned no frame at {ts:.3f}s — seeking past the end of {media}?"
+        )
+    image = cv2.imdecode(np.frombuffer(completed.stdout, np.uint8), cv2.IMREAD_COLOR)
+    if image is None:
+        raise RuntimeError(f"could not decode the frame ffmpeg returned at {ts:.3f}s")
+    return image
+
+
+def main() -> int:
+    job = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    destination = Path(sys.argv[2])
+
+    from insightface.app import FaceAnalysis
+
+    # `allowed_modules=["detection"]` is the whole reason this is cheap: the
+    # buffalo_l pack also carries recognition, landmark and gender/age models
+    # worth ~300 MB that a framing pass has no use for. ctx_id=-1 is CPU.
+    app = FaceAnalysis(
+        name=job["model"], allowed_modules=["detection"], providers=job["providers"]
+    )
+    app.prepare(ctx_id=-1, det_size=(job["det_size"], job["det_size"]))
+
+    results = []
+    for done, window in enumerate(job["windows"], 1):
+        try:
+            frames = []
+            for ts in window["timestamps"]:
+                faces = app.get(_frame(window["media"], ts))
+                frames.append(
+                    {
+                        "ts": ts,
+                        "faces": [
+                            {
+                                "box": [float(v) for v in face.bbox],
+                                "score": float(face.det_score),
+                            }
+                            for face in faces
+                        ],
+                    }
+                )
+            results.append({"index": window["index"], "frames": frames})
+        except Exception as exc:  # noqa: BLE001 — reported per window, not fatal
+            results.append({"index": window["index"], "error": f"{type(exc).__name__}: {exc}"})
+        # `proofcut.progress.MARKER`'s line, restated: this interpreter imports
+        # nothing from proofcut.
+        sys.stderr.write(f"proofcut-progress {done} {len(job['windows'])}\n")
+        sys.stderr.flush()
+
+    destination.write_text(json.dumps({"results": results}), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

proofcut/_tts_worker.py

@@ -0,0 +1,108 @@
+"""The synthesiser side of `tts`, run under a *different* interpreter.
+
+**This module is never imported by proofcut.** It is executed by the Python that
+`tts.tts_python()` resolves — a venv with `qwen_tts` and a CUDA torch — which is
+the whole reason it is a separate file, exactly as `_vlm_worker.py` and
+`_face_worker.py` keep torch and onnxruntime out of proofcut's own venv.
+
+It reads one JSON job from `argv[1]` and writes one JSON result to `argv[2]`;
+a file rather than stdout because transformers and qwen_tts both print to
+whichever stream they feel like ("flash-attn is not installed…"), and that
+landing in a JSON document is a parse error that reads like a synth failure.
+
+The model is loaded **once** for the job and every seed renders through it.
+The likeness number is the model's own speaker encoder — the same one it
+conditions on — so `sim` is cosine(embedding(render), embedding(reference)).
+
+`spread` is the second number, and it exists because the first one cannot see
+flatness: likeness-only ranking systematically keeps the *flattest* read
+(goodsometimes, 2026-08-24 — every one of the six flattest winners in a
+38-chunk essay had a livelier take among its losing seeds, one lost on a dead
+sim tie). It is the std of voiced pitch in semitones around the median (pyin,
+60–400 Hz), the local-llm round-2 proxy for how much the read moves; it cannot
+rank *where* emphasis lands, only whether there is any.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    job = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    destination = Path(sys.argv[2])
+
+    import librosa
+    import numpy as np
+    import soundfile as sf
+    import torch
+    from qwen_tts import Qwen3TTSModel
+
+    # `tts.device()`; absent is what every job before the key meant. Plain
+    # `cuda` keeps the `cuda:0` this always loaded onto.
+    device = job.get("device") or "cuda"
+    model = Qwen3TTSModel.from_pretrained(
+        job["model"],
+        device_map="cuda:0" if device == "cuda" else device,
+        dtype=torch.bfloat16,
+        attn_implementation="sdpa",
+    )
+
+    def pitch_spread(audio: np.ndarray, rate: int = 24000) -> float | None:
+        """Std of voiced f0 in semitones around its median — None under 20 voiced frames."""
+        f0 = librosa.pyin(audio, fmin=60, fmax=400, sr=rate)[0]
+        voiced = f0[~np.isnan(f0)]
+        if voiced.size < 20:
+            return None
+        return round(float(np.std(12 * np.log2(voiced / np.median(voiced)))), 2)
+
+    @torch.inference_mode()
+    def embed(audio: np.ndarray) -> np.ndarray:
+        e = model.model.extract_speaker_embedding(audio.astype(np.float32), 24000)
+        e = e.float().cpu().numpy().reshape(-1)
+        return e / (np.linalg.norm(e) or 1.0)
+
+    ref_audio, _ = librosa.load(job["ref_audio"], sr=24000, mono=True)
+    ref = embed(ref_audio)
+
+    out_dir = Path(job["out_dir"])
+    candidates = []
+    for done, seed in enumerate(job["seeds"], 1):
+        try:
+            torch.manual_seed(int(seed))
+            torch.cuda.manual_seed_all(int(seed))
+            wavs, sr = model.generate_voice_clone(
+                text=job["text"],
+                language=job["language"],
+                ref_audio=job["ref_audio"],
+                ref_text=job["ref_text"],
+                max_new_tokens=int(job["max_new_tokens"]),
+            )
+            wav = np.asarray(wavs[0], dtype=np.float32)
+            path = out_dir / f"s{int(seed)}.wav"
+            sf.write(str(path), wav, sr)
+            audio = wav if sr == 24000 else librosa.resample(wav, orig_sr=sr, target_sr=24000)
+            candidates.append(
+                {
+                    "seed": int(seed),
+                    "path": str(path),
+                    "duration": round(len(wav) / sr, 3),
+                    "sim": round(float(embed(audio) @ ref), 4),
+                    "spread": pitch_spread(audio),
+                }
+            )
+        except Exception as exc:  # noqa: BLE001 — reported per seed, not fatal
+            candidates.append({"seed": int(seed), "error": f"{type(exc).__name__}: {exc}"})
+        # `proofcut.progress.MARKER`'s line, restated: this interpreter imports
+        # nothing from proofcut.
+        sys.stderr.write(f"proofcut-progress {done} {len(job['seeds'])}\n")
+        sys.stderr.flush()
+
+    destination.write_text(json.dumps({"model": job["model"], "candidates": candidates}), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

proofcut/_vlm_worker.py

@@ -0,0 +1,170 @@
+"""The vision-model side of `describe`, run under a *different* interpreter.
+
+**This module is never imported by proofcut.** It is executed by the Python that
+`describe.vlm_python()` resolves — a venv with torch, transformers and
+bitsandbytes in it — which is the whole reason it is a separate file. proofcut's
+own venv stays free of torch, exactly as `asr.py` keeps whisper behind a
+binary. It lives inside the package only so it ships with it.
+
+It reads one JSON job from `argv[1]` and writes one JSON result to `argv[2]`.
+A file rather than stdout because transformers, bitsandbytes and torch all
+write to whichever stream they feel like, and a progress bar landing in the
+middle of a JSON document is a parse error that reads like a model failure.
+
+The model is loaded **once** for the whole job — every window of every clip
+goes through one process. Loading is ~15s and the description of a single
+window is ~3s, so a process per window would spend more time loading than
+describing.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _frames(media: str, timestamps: list[float], size: str) -> list:
+    """Pull one RGB frame per timestamp, through the ffmpeg binary.
+
+    Deliberately not `ffmpeg-python`: this file's dependencies are whatever
+    the resolved interpreter happens to have, and every extra import is
+    another way for it to fail on a box that could otherwise describe.
+    torch, transformers, numpy and PIL are unavoidable; a convenience wrapper
+    around a subprocess is not.
+    """
+    import numpy as np
+    from PIL import Image
+
+    width, height = (int(x) for x in size.split("x"))
+    out = []
+    for ts in timestamps:
+        completed = subprocess.run(
+            [
+                "ffmpeg", "-nostdin", "-v", "error",
+                "-ss", f"{ts:.3f}", "-i", media,
+                "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24",
+                "-s", size, "pipe:",
+            ],
+            capture_output=True,
+            check=True,
+        )
+        want = width * height * 3
+        if len(completed.stdout) < want:
+            raise RuntimeError(
+                f"ffmpeg returned {len(completed.stdout)} bytes for the frame at "
+                f"{ts:.2f}s, wanted {want} — seeking past the end of {media}?"
+            )
+        buf = np.frombuffer(completed.stdout[:want], np.uint8).reshape(height, width, 3)
+        out.append(Image.fromarray(buf))
+    return out
+
+
+def _load(model_path: str, device: str) -> tuple:
+    """Qwen2.5-VL, 4-bit NF4 with bf16 compute, and its processor.
+
+    The config every VRAM figure in PLAN.md § B-roll by description was
+    measured under — until 2026-09-10 it was imported from a sibling repo's
+    tagger at run time, and it is carried here unchanged so that proofcut can
+    describe on a box that has never seen that repo.
+    """
+    import torch
+    from transformers import (
+        AutoProcessor,
+        BitsAndBytesConfig,
+        Qwen2_5_VLForConditionalGeneration,
+    )
+
+    quant = BitsAndBytesConfig(
+        load_in_4bit=True,
+        bnb_4bit_compute_dtype=torch.bfloat16,
+        bnb_4bit_use_double_quant=True,
+        bnb_4bit_quant_type="nf4",
+    )
+    model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+        model_path,
+        quantization_config=quant,
+        device_map=device,
+        torch_dtype=torch.bfloat16,
+    ).eval()
+    processor = AutoProcessor.from_pretrained(model_path)
+    return model, processor
+
+
+def _generate(
+    model, processor, images: list, prompt: str, *, max_new_tokens: int, device: str
+) -> str:
+    """One greedy pass over the frames and the prompt; the decoded reply."""
+    import torch
+
+    content = [{"type": "image", "image": im} for im in images]
+    content.append({"type": "text", "text": prompt})
+    messages = [{"role": "user", "content": content}]
+    text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    inputs = processor(text=[text], images=list(images), return_tensors="pt").to(device)
+    with torch.no_grad():
+        out = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False)
+    generated = out[:, inputs["input_ids"].shape[1] :]
+    return processor.batch_decode(generated, skip_special_tokens=True)[0].strip()
+
+
+def main() -> int:
+    job = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    destination = Path(sys.argv[2])
+
+    # `describe.device()`; absent is what every job before the key meant.
+    # Refused before torch is imported: the 4-bit load below is bitsandbytes,
+    # which has no backend but CUDA, and an unquantised load on another device
+    # is a different memory budget and a different model output — a decision
+    # for whoever measures one (docs/plans/PORTABILITY.md step 3).
+    device = job.get("device") or "cuda"
+    if not device.startswith("cuda"):
+        sys.stderr.write(
+            f"the vision model loads 4-bit through bitsandbytes, which is CUDA-only; "
+            f"device {device!r} has no path in this worker yet\n"
+        )
+        return 2
+
+    model, processor = _load(job["model"], device)
+
+    results = []
+    for done, window in enumerate(job["windows"], 1):
+        try:
+            frames = _frames(window["media"], window["timestamps"], job["frame_size"])
+            text = _generate(
+                model,
+                processor,
+                frames,
+                job["prompt"],
+                max_new_tokens=job["max_new_tokens"],
+                device=device,
+            )
+            results.append({"index": window["index"], "text": text})
+        except Exception as exc:  # noqa: BLE001 — reported per window, not fatal
+            results.append({"index": window["index"], "error": f"{type(exc).__name__}: {exc}"})
+        # Freeing between windows is what keeps peak VRAM at one window's
+        # worth rather than the run's. This box has 11.5 GiB usable and an
+        # always-on llama-server holding 3.5 of it.
+        _empty_cache()
+        _progress(done, len(job["windows"]))
+
+    destination.write_text(json.dumps({"results": results}), encoding="utf-8")
+    return 0
+
+
+def _progress(done: int, total: int) -> None:
+    """`proofcut.progress.MARKER`'s line, restated: this runs under another
+    interpreter and imports nothing from proofcut."""
+    sys.stderr.write(f"proofcut-progress {done} {total}\n")
+    sys.stderr.flush()
+
+
+def _empty_cache() -> None:
+    import torch
+
+    torch.cuda.empty_cache()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())