videopython 0.47.0__tar.gz → 0.49.0__tar.gz

{videopython-0.47.0 → videopython-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.47.0
+Version: 0.49.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -28,60 +28,16 @@ Requires-Dist: chatterbox-tts>=0.1.7; extra == 'ai'
 Requires-Dist: demucs>=4.0.0; extra == 'ai'
 Requires-Dist: diffusers>=0.30.0; extra == 'ai'
 Requires-Dist: imagehash>=4.3; extra == 'ai'
-Requires-Dist: llama-cpp-python>=0.3.0; extra == 'ai'
+Requires-Dist: ollama>=0.5.0; extra == 'ai'
 Requires-Dist: openai-whisper>=20240930; extra == 'ai'
 Requires-Dist: pyannote-audio>=4.0.0; extra == 'ai'
 Requires-Dist: pyloudnorm>=0.1.1; extra == 'ai'
-Requires-Dist: qwen-vl-utils>=0.0.10; extra == 'ai'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'ai'
 Requires-Dist: silero-vad>=5.1; extra == 'ai'
 Requires-Dist: torch>=2.8.0; extra == 'ai'
 Requires-Dist: torchaudio>=2.8.0; extra == 'ai'
 Requires-Dist: transformers>=5.2.0; extra == 'ai'
 Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'ai'
 Requires-Dist: ultralytics>=8.0.0; extra == 'ai'
-Provides-Extra: asr
-Requires-Dist: openai-whisper>=20240930; extra == 'asr'
-Requires-Dist: pyannote-audio>=4.0.0; extra == 'asr'
-Requires-Dist: silero-vad>=5.1; extra == 'asr'
-Requires-Dist: torch>=2.8.0; extra == 'asr'
-Requires-Dist: torchaudio>=2.8.0; extra == 'asr'
-Provides-Extra: dub
-Requires-Dist: demucs>=4.0.0; extra == 'dub'
-Requires-Dist: llama-cpp-python>=0.3.0; extra == 'dub'
-Requires-Dist: openai-whisper>=20240930; extra == 'dub'
-Requires-Dist: pyannote-audio>=4.0.0; extra == 'dub'
-Requires-Dist: pyloudnorm>=0.1.1; extra == 'dub'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'dub'
-Requires-Dist: silero-vad>=5.1; extra == 'dub'
-Requires-Dist: torch>=2.8.0; extra == 'dub'
-Requires-Dist: torchaudio>=2.8.0; extra == 'dub'
-Requires-Dist: transformers>=5.2.0; extra == 'dub'
-Provides-Extra: generation
-Requires-Dist: accelerate>=0.29.2; extra == 'generation'
-Requires-Dist: diffusers>=0.30.0; extra == 'generation'
-Requires-Dist: torch>=2.8.0; extra == 'generation'
-Requires-Dist: torchaudio>=2.8.0; extra == 'generation'
-Requires-Dist: transformers>=5.2.0; extra == 'generation'
-Provides-Extra: separation
-Requires-Dist: demucs>=4.0.0; extra == 'separation'
-Requires-Dist: torch>=2.8.0; extra == 'separation'
-Requires-Dist: torchaudio>=2.8.0; extra == 'separation'
-Provides-Extra: translation
-Requires-Dist: llama-cpp-python>=0.3.0; extra == 'translation'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'translation'
-Requires-Dist: torch>=2.8.0; extra == 'translation'
-Requires-Dist: transformers>=5.2.0; extra == 'translation'
-Provides-Extra: tts
-Requires-Dist: chatterbox-tts>=0.1.7; extra == 'tts'
-Provides-Extra: vision
-Requires-Dist: imagehash>=4.3; extra == 'vision'
-Requires-Dist: qwen-vl-utils>=0.0.10; extra == 'vision'
-Requires-Dist: torch>=2.8.0; extra == 'vision'
-Requires-Dist: torchaudio>=2.8.0; extra == 'vision'
-Requires-Dist: transformers>=5.2.0; extra == 'vision'
-Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'vision'
-Requires-Dist: ultralytics>=8.0.0; extra == 'vision'
 Description-Content-Type: text/markdown
 
 # videopython
@@ -104,8 +60,6 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
-AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
-
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.47.0 → videopython-0.49.0}/README.md

@@ -18,8 +18,6 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
-AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
-
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.47.0 → videopython-0.49.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.47.0"
+version = "0.49.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -53,90 +53,42 @@ dev = [
     "mkdocstrings>=1.0.0",
     "mkdocstrings-python>=2.0.1",
 ]
-# Thin dev-workflow group so `uv sync` / uv.lock keep working. Resolves the
-# SAME set as the aggregate `[ai]` extra below via a PEP 508 self-reference, so
-# there is a single source of truth (the granular extras) and no hand-sync.
-# `test_packaging_extras.py` asserts this stays consistent with the extra.
+# Thin dev-workflow group so `uv sync` / uv.lock keep working. References the
+# `[ai]` extra so dev installs every AI capability (single source of truth).
 ai = ["videopython[ai]"]
 
-# pip install videopython[<extra>] - pip uses optional-dependencies, not dependency-groups.
+# pip install "videopython[ai]" - pip uses optional-dependencies, not dependency-groups.
 #
-# Granular extras partition the heavy ML deps by the leaf module that imports
-# them, so consumers install only what a capability needs. `ai` is a convenience
-# aggregate that installs EVERYTHING via PEP 685 self-references (no hand-sync).
-# `test_packaging_extras.py` enforces union(granular) == ai as a drift guard.
+# A single [ai] extra installs every AI capability. The heavy ML deps still load
+# lazily at first use (no top-level imports under ai/), so importing videopython
+# stays light even with [ai] installed.
 [project.optional-dependencies]
-# Speech recognition / diarization (understanding/audio.py).
-asr = [
+ai = [
+    # Speech recognition / diarization (understanding/audio.py)
     "openai-whisper>=20240930",
     "pyannote-audio>=4.0.0",
-    # Voice activity detection (used by AudioToText to gate Whisper language detection)
     "silero-vad>=5.1",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Visual understanding: detection, scene/temporal, VLM (understanding/{faces,
-# objects,temporal,image}.py + video_analysis). transformers also backs the AST
-# AudioClassifier and the SceneVLM; qwen-vl-utils is the SceneVLM preprocessor;
-# imagehash is the SceneVLM frame-dedup; transnetv2 is scene detection.
-vision = [
+    # Visual understanding: detection, scene/temporal, VLM (understanding/*, video_analysis)
     "ultralytics>=8.0.0",
     "transnetv2-pytorch>=1.0.5",
     "transformers>=5.2.0",
-    "qwen-vl-utils>=0.0.10",
     "imagehash>=4.3",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Audio source separation (understanding/separation.py).
-separation = [
+    # Audio source separation (understanding/separation.py)
     "demucs>=4.0.0",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Text translation backends (generation/translation.py MarianMT +
-# generation/qwen3.py Qwen3 GGUF). MarianTokenizer requires sentencepiece.
-translation = [
-    "transformers>=5.2.0",
-    "sentencepiece>=0.1.99",
-    "llama-cpp-python>=0.3.0",
-    "torch>=2.8.0",
-]
-# Voice cloning TTS (generation/audio.py — Chatterbox Multilingual by Resemble
-# AI). ISOLATED: chatterbox-tts 0.1.7 carries the strict pins that force the
-# [tool.uv].override-dependencies block. This is the ONLY extra that drags them.
-# Left to chatterbox's own torch==2.6.0 / torchaudio==2.6.0 pins (no floors
-# here) so `pip install videopython[tts]` resolves STANDALONE in its own
-# image/Modal function -- the whole point of running TTS behind SpeechBackend.
-# The all-in [ai] resolve forces torch>=2.8.0 over this via override-dependencies.
-tts = [
+    # Voice cloning TTS (generation/audio.py — Chatterbox); its strict pins drive
+    # the [tool.uv].override-dependencies block below.
     "chatterbox-tts>=0.1.7",
-]
-# Local media generation: SDXL/CogVideoX (generation/{image,video}.py) +
-# MusicGen (generation/audio.py TextToMusic, via transformers).
-generation = [
+    # Local media generation: SDXL/CogVideoX + MusicGen (generation/*)
     "diffusers>=0.30.0",
-    "transformers>=5.2.0",
     "accelerate>=0.29.2",
+    # Dubbing loudness matching (dubbing/loudness.py)
+    "pyloudnorm>=0.1.1",
+    # LLM-authored editing planner (auto_edit/local.py OllamaVisionLLM)
+    "ollama>=0.5.0",
+    # Shared torch stack
     "torch>=2.8.0",
     "torchaudio>=2.8.0",
 ]
-# Dubbing pipeline's hard top-level deps: transcription (asr) + source
-# separation (separation) + translation, plus BS.1770 loudness matching
-# (dubbing/loudness.py). Deliberately EXCLUDES tts/chatterbox: local synthesis
-# runs through the SpeechBackend protocol against a separately-installed [tts]
-# extra or an injected remote backend, so a [dub] image co-resolves WITHOUT
-# chatterbox's override-forcing pin. A bare [dub] install that hits local
-# synthesis raises a clear [tts]-pointing ImportError.
-dub = [
-    "videopython[asr,separation,translation]",
-    # Loudness measurement (BS.1770) for dub-vs-source loudness matching (M3)
-    "pyloudnorm>=0.1.1",
-]
-# Convenience aggregate: installs every capability. PEP 685 self-references make
-# this the single "everything" install with no hand-duplicated dep list. This
-# combined resolve is what the [tool.uv].override-dependencies block exists for.
-ai = ["videopython[asr,vision,separation,translation,tts,generation,dub]"]
 
 [project.urls]
 Homepage = "https://videopython.com"
@@ -164,24 +116,16 @@ module = [
     "pyannote", "pyannote.*",
     "silero_vad", "silero_vad.*",
     "cv2", "cv2.*",
-    "llama_cpp", "llama_cpp.*",
     "pyloudnorm", "pyloudnorm.*",
-    "qwen_vl_utils", "qwen_vl_utils.*",
     "imagehash", "imagehash.*",
 ]
 ignore_missing_imports = true
 
 [tool.uv]
-# LOAD-BEARING ONLY for the all-in `[ai]` resolve (every extra installed
-# together, as in dev/CI and `uv sync`). chatterbox-tts 0.1.7 (the `[tts]`
-# extra) pins strict torch/torchaudio/numpy/diffusers that conflict with
-# pyannote-audio (torch>=2.8, `[asr]`) and CogVideoX (diffusers>=0.30,
-# `[generation]`). This override lets the combined resolver pick compatible
-# versions. A consumer installing a SUBSET that excludes chatterbox — notably
-# `[dub]` (asr+separation+translation+pyloudnorm, no tts) — co-resolves cleanly
-# WITHOUT this override; that clean `[dub]` resolve is the whole point of
-# isolating `[tts]`. The ai dependency floors are aligned with these overrides
-# to keep pip and uv resolving similar versions.
+# chatterbox-tts 0.1.7 (in [ai]) pins strict torch/torchaudio/numpy/diffusers
+# that conflict with pyannote-audio (torch>=2.8) and CogVideoX (diffusers>=0.30).
+# These overrides let the combined [ai] resolve pick compatible versions; the
+# floors in [ai] are aligned with them so pip and uv resolve similar versions.
 override-dependencies = [
     "torch>=2.8.0", "torchaudio>=2.8.0", "numpy>=2.0.0", "diffusers>=0.30.0",
     # ultralytics depends on opencv-python which conflicts with our

{videopython-0.47.0 → videopython-0.49.0}/src/videopython/ai/__init__.py

@@ -24,6 +24,16 @@ if TYPE_CHECKING:
     # Redundant aliases mark these as intentional re-exports (mypy/IDE see the
     # symbols; ruff doesn't flag them as unused). Runtime resolution is lazy via
     # __getattr__ below.
+    from .auto_edit import AutoEditError as AutoEditError
+    from .auto_edit import AutoEditor as AutoEditor
+    from .auto_edit import EditCatalog as EditCatalog
+    from .auto_edit import EditPlan as EditPlan
+    from .auto_edit import ImagePart as ImagePart
+    from .auto_edit import OllamaVisionLLM as OllamaVisionLLM
+    from .auto_edit import PlannerError as PlannerError
+    from .auto_edit import StructuredVisionLLM as StructuredVisionLLM
+    from .auto_edit import TextPart as TextPart
+    from .auto_edit import build_catalog as build_catalog
     from .effects import ObjectDetectionOverlay as ObjectDetectionOverlay
     from .generation import ImageToVideo as ImageToVideo
     from .generation import TextToImage as TextToImage
@@ -66,6 +76,17 @@ _exports: dict[str, str] = {
     "VideoAnalysis": ".video_analysis",
     "VideoAnalysisConfig": ".video_analysis",
     "VideoAnalyzer": ".video_analysis",
+    # Auto-editing (LLM-authored edits)
+    "AutoEditor": ".auto_edit",
+    "AutoEditError": ".auto_edit",
+    "OllamaVisionLLM": ".auto_edit",
+    "StructuredVisionLLM": ".auto_edit",
+    "PlannerError": ".auto_edit",
+    "TextPart": ".auto_edit",
+    "ImagePart": ".auto_edit",
+    "EditCatalog": ".auto_edit",
+    "EditPlan": ".auto_edit",
+    "build_catalog": ".auto_edit",
 }
 
 __all__ = list(_exports)

videopython-0.49.0/src/videopython/ai/_ollama.py

@@ -0,0 +1,71 @@
+"""Shared structured-generation client over a local Ollama server."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+from videopython.ai._optional import require
+
+
+class OllamaError(RuntimeError):
+    """Ollama returned unusable output (non-JSON or an unexpected shape)."""
+
+
+class OllamaStructuredClient:
+    """Generate schema-constrained JSON from text + optional images via Ollama.
+
+    Shared by the auto-edit planner, scene captioner, and translator. The model
+    must be served by a local Ollama daemon and support structured-output
+    ``format`` (and vision, when images are passed); ``options`` are extra Ollama
+    generation options merged over ``temperature=0``.
+    """
+
+    def __init__(self, model: str, *, host: str | None = None, options: dict[str, Any] | None = None) -> None:
+        self.model = model
+        self.host = host
+        self.options: dict[str, Any] = {"temperature": 0.0, **(options or {})}
+        self._client: Any = None
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            ollama = require("ollama", "ai", feature="Ollama")
+            self._client = ollama.Client(host=self.host)
+        return self._client
+
+    def generate_json(
+        self,
+        *,
+        system: str,
+        text: str,
+        schema: dict[str, Any],
+        images: list[np.ndarray] | None = None,
+    ) -> dict[str, Any]:
+        """Return the parsed JSON object Ollama generates under ``schema``."""
+        user: dict[str, Any] = {"role": "user", "content": text}
+        if images:
+            user["images"] = [_encode_png_b64(image) for image in images]
+        messages = [{"role": "system", "content": system}, user]
+        response = self._get_client().chat(model=self.model, messages=messages, format=schema, options=self.options)
+        content = response.message.content
+        try:
+            data = json.loads(content)
+        except (ValueError, TypeError) as exc:
+            raise OllamaError(f"Ollama returned non-JSON output: {content!r}") from exc
+        if not isinstance(data, dict):
+            raise OllamaError(f"Ollama returned a non-object JSON value: {type(data).__name__}")
+        return data
+
+    def unload(self) -> None:
+        self._client = None
+
+
+def _encode_png_b64(frame: np.ndarray) -> str:
+    buffer = io.BytesIO()
+    Image.fromarray(frame).save(buffer, format="PNG")
+    return base64.b64encode(buffer.getvalue()).decode("ascii")

{videopython-0.47.0 → videopython-0.49.0}/src/videopython/ai/_revisions.py

@@ -41,11 +41,6 @@ Usage:
 #     from the HF repo ``arnabdhar/YOLOv8-Face-Detection`` via
 #     hf_hub_download, and that one IS pinned below.)
 #
-#   * Dynamic Marian pairs -- ai/generation/translation.py builds the model
-#     name per language pair at runtime (e.g. "Helsinki-NLP/opus-mt-en-de").
-#     The set of repos is open-ended (one per direction), so pinning each pair
-#     to a SHA is impractical and out of scope; left unpinned by design.
-#
 #   * Chatterbox internal load -- ai/generation/audio.py calls
 #     ``ChatterboxMultilingualTTS.from_pretrained(device=...)`` with no repo
 #     argument. The repo id + revision are resolved internally by the
@@ -67,10 +62,6 @@ from __future__ import annotations
 # ``pinned(model_id)`` resolves with a plain dict lookup. SHAs captured from
 # the HuggingFace model API (see module docstring for refresh instructions).
 MODEL_REVISIONS: dict[str, str] = {
-    # SceneVLM (ai/understanding/image.py: SCENE_VLM_MODEL_IDS)
-    "Qwen/Qwen3.5-4B": "851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a",
-    "Qwen/Qwen3.5-9B": "c202236235762e1c871ad0ccb60c8ee5ba337b9a",
-    "Qwen/Qwen3.5-27B": "fc05daec18b0a78c049392ed2e771dde82bdf654",
     # Speaker diarization (ai/understanding/audio.py: PYANNOTE_DIARIZATION_MODEL).
     # Gated repo (auto-approved); from_pretrained needs an accepted HF token.
     "pyannote/speaker-diarization-community-1": "3533c8cf8e369892e6b79ff1bf80f7b0286a54ee",
@@ -78,8 +69,6 @@ MODEL_REVISIONS: dict[str, str] = {
     "MIT/ast-finetuned-audioset-10-10-0.4593": "f826b80d28226b62986cc218e5cec390b1096902",
     # Face detection checkpoint (ai/understanding/faces.py: hf_hub_download)
     "arnabdhar/YOLOv8-Face-Detection": "52fa54977207fa4f021de949b515fb19dcab4488",
-    # Qwen3 translation GGUF (ai/generation/qwen3.py: DEFAULT_REPO_ID)
-    "unsloth/Qwen3-4B-Instruct-2507-GGUF": "a06e946bb6b655725eafa393f4a9745d460374c9",
     # MusicGen (ai/generation/audio.py: TextToMusic)
     "facebook/musicgen-small": "4c8334b02c6ec4e8664a91979669a501ec497792",
     # SDXL (ai/generation/image.py: TextToImage)

videopython-0.49.0/src/videopython/ai/auto_edit/__init__.py

@@ -0,0 +1,29 @@
+"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it."""
+
+from __future__ import annotations
+
+from .backend import ImagePart, Part, PlannerError, StructuredVisionLLM, TextPart
+from .catalog import build_catalog
+from .editor import AutoEditError, AutoEditor
+from .local import OllamaVisionLLM
+from .models import CatalogBundle, CatalogScene, EditCatalog, EditPlan, PlanSegment
+from .resolve import UnknownSceneIdsError, resolve_plan
+
+__all__ = [
+    "AutoEditError",
+    "AutoEditor",
+    "CatalogBundle",
+    "CatalogScene",
+    "EditCatalog",
+    "EditPlan",
+    "ImagePart",
+    "OllamaVisionLLM",
+    "Part",
+    "PlanSegment",
+    "PlannerError",
+    "StructuredVisionLLM",
+    "TextPart",
+    "UnknownSceneIdsError",
+    "build_catalog",
+    "resolve_plan",
+]

videopython-0.49.0/src/videopython/ai/auto_edit/backend.py

@@ -0,0 +1,37 @@
+"""The SDK-free seam between the editor and a structured-vision model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+
+
+@dataclass
+class TextPart:
+    """A text chunk in a planner prompt."""
+
+    text: str
+
+
+@dataclass
+class ImagePart:
+    """A keyframe in a planner prompt: an RGB (H, W, 3) uint8 array."""
+
+    image: np.ndarray
+    label: str | None = None
+
+
+Part = TextPart | ImagePart
+
+
+class PlannerError(RuntimeError):
+    """A backend produced unusable output; the editor retries (infra errors should propagate instead)."""
+
+
+@runtime_checkable
+class StructuredVisionLLM(Protocol):
+    """Returns schema-shaped JSON from interleaved text + images; raises PlannerError on bad output."""
+
+    def generate_json(self, *, system: str, parts: list[Part], schema: dict[str, Any]) -> dict[str, Any]: ...

videopython-0.49.0/src/videopython/ai/auto_edit/catalog.py

@@ -0,0 +1,90 @@
+"""Build the LLM-facing edit catalog from VideoAnalysis results."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from videopython.base.video import extract_frames_at_times
+
+from .models import CatalogBundle, CatalogScene, EditCatalog
+
+if TYPE_CHECKING:
+    from videopython.ai.video_analysis import SceneAnalysisSample, VideoAnalysis
+    from videopython.base.transcription import Transcription
+
+DEFAULT_TRANSCRIPT_CHARS = 280
+
+
+def build_catalog(
+    analyses: Sequence[VideoAnalysis],
+    *,
+    keyframes: bool = True,
+    max_transcript_chars: int = DEFAULT_TRANSCRIPT_CHARS,
+) -> CatalogBundle:
+    """Project VideoAnalysis results into a flat scene catalog with one midpoint keyframe per scene."""
+    scenes: list[CatalogScene] = []
+    frames: dict[str, np.ndarray] = {}
+    used_ids: set[str] = set()
+
+    for analysis in analyses:
+        source_path = analysis.source.path
+        samples = analysis.scenes.samples if analysis.scenes else []
+        transcription = analysis.audio.transcription if analysis.audio else None
+        stem = Path(source_path).stem if source_path else "clip"
+
+        for sample in samples:
+            scene_id = _unique_id(stem, sample.scene_index, used_ids)
+            caption, shot_type = _description(sample)
+            transcript = _transcript_excerpt(
+                transcription, sample.start_second, sample.end_second, max_transcript_chars
+            )
+            scenes.append(
+                CatalogScene(
+                    id=scene_id,
+                    source=Path(source_path) if source_path else Path(stem),
+                    start=sample.start_second,
+                    end=sample.end_second,
+                    duration=max(0.0, sample.end_second - sample.start_second),
+                    shot_type=shot_type,
+                    caption=caption,
+                    transcript=transcript,
+                    has_speech=bool(transcript),
+                    has_faces=bool(sample.faces),
+                )
+            )
+            if keyframes:
+                if source_path is None:
+                    raise ValueError(f"Scene {scene_id!r} has no source path to extract a keyframe from.")
+                midpoint = (sample.start_second + sample.end_second) / 2.0
+                frames[scene_id] = extract_frames_at_times(source_path, [midpoint])[0]
+
+    return CatalogBundle(catalog=EditCatalog(scenes=scenes), keyframes=frames)
+
+
+def _unique_id(stem: str, scene_index: int, used: set[str]) -> str:
+    base = f"{stem}#{scene_index}"
+    candidate, suffix = base, 2
+    while candidate in used:
+        candidate = f"{base}-{suffix}"
+        suffix += 1
+    used.add(candidate)
+    return candidate
+
+
+def _description(sample: SceneAnalysisSample) -> tuple[str, str | None]:
+    desc = sample.scene_description
+    return (desc.caption or "", desc.shot_type) if desc else ("", None)
+
+
+def _transcript_excerpt(transcription: Transcription | None, start: float, end: float, max_chars: int) -> str:
+    sliced = transcription.slice(start, end) if transcription else None
+    if sliced is None:
+        return ""
+    text = " ".join(" ".join(segment.text.split()) for segment in sliced.segments).strip()
+    if len(text) > max_chars:
+        text = text[: max_chars - 3].rstrip() + "..."
+    return text