videopython 0.55.0__tar.gz → 0.55.2__tar.gz

{videopython-0.55.0 → videopython-0.55.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: videopython
-Version: 0.55.0
+Version: 0.55.2
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -21,6 +21,7 @@ Requires-Dist: opencv-python-headless>=4.9.0.80
 Requires-Dist: pillow>=12.1.1
 Requires-Dist: pydantic>=2.8.0
 Requires-Dist: resvg-py>=0.3.2
+Requires-Dist: soxr>=0.5
 Requires-Dist: tqdm>=4.66.3
 Provides-Extra: ai
 Requires-Dist: accelerate>=0.29.2; extra == 'ai'
@@ -66,13 +67,11 @@ pip install "videopython[ai]"        # + ALL local AI features (GPU recommended)
 pip install "videopython[ai,mcp]"    # + MCP server for agent-driven editing
 ```
 
-Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use. LLM-driven editing and scene captioning use a local [Ollama](https://ollama.com) server (`ollama pull qwen3.6:27b`).
+Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use. LLM-driven editing and scene captioning use a local [Ollama](https://ollama.com) server (`ollama pull qwen3.6:27b`). See the [install guide](https://videopython.com/install/) for FFmpeg, Ollama, and hardware details.
 
-## Quick Start
+## Quick start
 
-### JSON editing plans
-
-A `VideoEdit` is a multi-segment plan, defined as a dict (or JSON), validated and executed against the source files:
+An edit is a plan — a dict (or JSON) validated and executed against the source files:
 
 ```python
 from videopython.editing import VideoEdit
@@ -93,7 +92,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
+`run_to_file()` streams, so memory stays bounded even for hour-long sources. Walk through it in [Tutorial 1](https://videopython.com/tutorials/first-edit/).
 
 ### Automatic editing (local LLM)
 
@@ -110,7 +109,7 @@ edit = editor.edit(
 edit.run_to_file("teaser.mp4")
 ```
 
-The model picks scenes **by id** from a catalog built from scene detection + captions, so its temporal imprecision never reaches the render. See the [Automatic Editing Guide](https://videopython.com/guides/auto-editing/).
+The model picks scenes **by id** from a catalog built from scene detection + captions, so its temporal imprecision never reaches the render. See [Let a local LLM edit for you](https://videopython.com/how-to/auto-editing/).
 
 ### AI generation
 
@@ -123,39 +122,43 @@ audio = TextToSpeech().generate_audio("Welcome to videopython.")
 video.add_audio(audio).save("ai_video.mp4")
 ```
 
-## LLM & AI Agent Integration
+## LLM & AI agent integration
 
-Putting an LLM in the loop works three ways:
+Putting an LLM in the loop works three ways, differing in who owns the model:
 
-1. **Bring your own LLM** — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans (details below).
-2. **`AutoEditor`** — a local Ollama vision model is the planner (see [Automatic editing](#automatic-editing-local-llm) above).
-3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. Install `[ai,mcp]`, run `videopython-mcp`, and point your MCP client at it. See the [MCP Server Guide](https://videopython.com/guides/mcp/).
+1. **Bring your own LLM** — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans. [Guide](https://videopython.com/how-to/llm-plans/)
+2. **`AutoEditor`** — a local Ollama vision model is the planner. [Guide](https://videopython.com/how-to/auto-editing/)
+3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. [Guide](https://videopython.com/how-to/mcp-server/)
 
-**Mode 1** in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
+Mode 1 in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
 
 - **`edit.check(meta)`** — collect *every* structured error in one pass, not just the first
 - **`edit.repair(meta)`** — auto-clamp mechanical violations (overruns, negatives) with a changelog
 - **`edit.normalize_dimensions(meta, target)`** — make heterogeneous segments concat-compatible
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples (Anthropic / OpenAI tool use), the refine loop, and operation discovery.
+Why it is built this way: [LLM-first design](https://videopython.com/explanation/llm-first-design/).
 
 ## Features
 
 - **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
 - **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (resize, crop, fps, speed, freeze, silence removal; cutting is the segment's own start/end) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
-- **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`. Scene captioning and dub translation run on a local [Ollama](https://ollama.com) model.
-- **`videopython.ai.auto_edit`** — `AutoEditor` + `OllamaVisionLLM`: plan and render an edit from sources + a one-line brief, with a local LLM selecting scenes by id from an auto-built catalog.
+- **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect, and the full-pipeline `VideoAnalyzer`. Scene captioning and dubbing translation run on a local [Ollama](https://ollama.com) model.
+- **`videopython.ai.auto_edit`** — `AutoEditor` + `OllamaVisionLLM`: plan and render an edit from sources + a one-line brief.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
-- **`videopython.mcp`** *(install with `[mcp]`)* — `videopython-mcp`, an MCP stdio server exposing the auto-edit pipeline (analyze → catalog → validate/repair/run) so an agent drives editing.
+- **`videopython.mcp`** *(install with `[ai,mcp]`)* — `videopython-mcp`, an MCP stdio server exposing the auto-edit pipeline so an agent drives editing.
+
+## Documentation
 
-## Examples
+The docs follow [Diátaxis](https://diataxis.fr): four sections, each answering a different kind of question.
 
-- [Social Media Clip](https://videopython.com/examples/social-clip/)
-- [AI-Generated Video](https://videopython.com/examples/ai-video/)
-- [Auto-Subtitles](https://videopython.com/examples/auto-subtitles/)
-- [Processing Large Videos](https://videopython.com/examples/large-videos/)
+| | |
+|---|---|
+| [Tutorials](https://videopython.com/tutorials/) | Learn by doing — start here if you are new |
+| [How-to guides](https://videopython.com/how-to/) | Recipes for a specific goal |
+| [Reference](https://videopython.com/reference/) | Classes, operations, parameters, wire format |
+| [Explanation](https://videopython.com/explanation/) | Why the library is shaped the way it is |
 
 ## Development
 
-See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, and contribution workflow.
+See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, docs, and the release workflow.

{videopython-0.55.0 → videopython-0.55.2}/README.md

@@ -19,13 +19,11 @@ pip install "videopython[ai]"        # + ALL local AI features (GPU recommended)
 pip install "videopython[ai,mcp]"    # + MCP server for agent-driven editing
 ```
 
-Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use. LLM-driven editing and scene captioning use a local [Ollama](https://ollama.com) server (`ollama pull qwen3.6:27b`).
+Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use. LLM-driven editing and scene captioning use a local [Ollama](https://ollama.com) server (`ollama pull qwen3.6:27b`). See the [install guide](https://videopython.com/install/) for FFmpeg, Ollama, and hardware details.
 
-## Quick Start
+## Quick start
 
-### JSON editing plans
-
-A `VideoEdit` is a multi-segment plan, defined as a dict (or JSON), validated and executed against the source files:
+An edit is a plan — a dict (or JSON) validated and executed against the source files:
 
 ```python
 from videopython.editing import VideoEdit
@@ -46,7 +44,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
+`run_to_file()` streams, so memory stays bounded even for hour-long sources. Walk through it in [Tutorial 1](https://videopython.com/tutorials/first-edit/).
 
 ### Automatic editing (local LLM)
 
@@ -63,7 +61,7 @@ edit = editor.edit(
 edit.run_to_file("teaser.mp4")
 ```
 
-The model picks scenes **by id** from a catalog built from scene detection + captions, so its temporal imprecision never reaches the render. See the [Automatic Editing Guide](https://videopython.com/guides/auto-editing/).
+The model picks scenes **by id** from a catalog built from scene detection + captions, so its temporal imprecision never reaches the render. See [Let a local LLM edit for you](https://videopython.com/how-to/auto-editing/).
 
 ### AI generation
 
@@ -76,39 +74,43 @@ audio = TextToSpeech().generate_audio("Welcome to videopython.")
 video.add_audio(audio).save("ai_video.mp4")
 ```
 
-## LLM & AI Agent Integration
+## LLM & AI agent integration
 
-Putting an LLM in the loop works three ways:
+Putting an LLM in the loop works three ways, differing in who owns the model:
 
-1. **Bring your own LLM** — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans (details below).
-2. **`AutoEditor`** — a local Ollama vision model is the planner (see [Automatic editing](#automatic-editing-local-llm) above).
-3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. Install `[ai,mcp]`, run `videopython-mcp`, and point your MCP client at it. See the [MCP Server Guide](https://videopython.com/guides/mcp/).
+1. **Bring your own LLM** — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans. [Guide](https://videopython.com/how-to/llm-plans/)
+2. **`AutoEditor`** — a local Ollama vision model is the planner. [Guide](https://videopython.com/how-to/auto-editing/)
+3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. [Guide](https://videopython.com/how-to/mcp-server/)
 
-**Mode 1** in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
+Mode 1 in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
 
 - **`edit.check(meta)`** — collect *every* structured error in one pass, not just the first
 - **`edit.repair(meta)`** — auto-clamp mechanical violations (overruns, negatives) with a changelog
 - **`edit.normalize_dimensions(meta, target)`** — make heterogeneous segments concat-compatible
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples (Anthropic / OpenAI tool use), the refine loop, and operation discovery.
+Why it is built this way: [LLM-first design](https://videopython.com/explanation/llm-first-design/).
 
 ## Features
 
 - **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
 - **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (resize, crop, fps, speed, freeze, silence removal; cutting is the segment's own start/end) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
-- **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`. Scene captioning and dub translation run on a local [Ollama](https://ollama.com) model.
-- **`videopython.ai.auto_edit`** — `AutoEditor` + `OllamaVisionLLM`: plan and render an edit from sources + a one-line brief, with a local LLM selecting scenes by id from an auto-built catalog.
+- **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect, and the full-pipeline `VideoAnalyzer`. Scene captioning and dubbing translation run on a local [Ollama](https://ollama.com) model.
+- **`videopython.ai.auto_edit`** — `AutoEditor` + `OllamaVisionLLM`: plan and render an edit from sources + a one-line brief.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
-- **`videopython.mcp`** *(install with `[mcp]`)* — `videopython-mcp`, an MCP stdio server exposing the auto-edit pipeline (analyze → catalog → validate/repair/run) so an agent drives editing.
+- **`videopython.mcp`** *(install with `[ai,mcp]`)* — `videopython-mcp`, an MCP stdio server exposing the auto-edit pipeline so an agent drives editing.
+
+## Documentation
 
-## Examples
+The docs follow [Diátaxis](https://diataxis.fr): four sections, each answering a different kind of question.
 
-- [Social Media Clip](https://videopython.com/examples/social-clip/)
-- [AI-Generated Video](https://videopython.com/examples/ai-video/)
-- [Auto-Subtitles](https://videopython.com/examples/auto-subtitles/)
-- [Processing Large Videos](https://videopython.com/examples/large-videos/)
+| | |
+|---|---|
+| [Tutorials](https://videopython.com/tutorials/) | Learn by doing — start here if you are new |
+| [How-to guides](https://videopython.com/how-to/) | Recipes for a specific goal |
+| [Reference](https://videopython.com/reference/) | Classes, operations, parameters, wire format |
+| [Explanation](https://videopython.com/explanation/) | Why the library is shaped the way it is |
 
 ## Development
 
-See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, and contribution workflow.
+See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, docs, and the release workflow.

{videopython-0.55.0 → videopython-0.55.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.55.0"
+version = "0.55.2"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -32,6 +32,7 @@ classifiers = [
 
 dependencies = [
     "numpy>=1.25.2",
+    "soxr>=0.5",  # polyphase resampling for Audio.resample; the engine librosa uses
     "opencv-python-headless>=4.9.0.80",
     "pillow>=12.1.1",
     "resvg-py>=0.3.2",
@@ -52,26 +53,24 @@ dev = [
     "mkdocs-material>=9.7.1",
     "mkdocstrings>=1.0.0",
     "mkdocstrings-python>=2.0.1",
+    # Keeps the pre-Diátaxis docs URLs alive (see mkdocs.yml redirect_maps).
+    # Capped <1.2.3: that release added a hard dependency on `properdocs` (an
+    # unrelated MkDocs fork) purely to print an ad during every docs build.
+    "mkdocs-redirects>=1.2,<1.2.3",
 ]
 # 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[ai]" - pip uses optional-dependencies, not dependency-groups.
-#
-# 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.
+# One [ai] extra for every AI capability. Heavy ML deps load lazily at first use
+# (no top-level imports under ai/), so importing videopython stays light.
 [project.optional-dependencies]
 ai = [
     # Speech recognition / diarization (understanding/audio.py)
     "openai-whisper>=20240930",
-    # whisper imports numba (timing.py), and numba is version-coupled to numpy:
-    # each release declares a `numpy<X` cap that moves forward (0.62 -> <2.4,
-    # 0.66 -> <2.5). Without a floor a resolver can satisfy a newer numpy by
-    # backtracking numba to an ancient release instead, which then fails at
-    # `import whisper`. Floor it so numba's own cap does the work; 0.62 is the
-    # oldest release covering our full Python range (3.11-3.13).
+    # Floored, not capped: numba declares the numpy cap, and without a floor a
+    # resolver satisfies a newer numpy by backtracking numba instead, breaking
+    # `import whisper`. 0.62 is the oldest release covering Python 3.11-3.13.
     "numba>=0.62",
     "pyannote-audio>=4.0.0",
     "silero-vad>=5.1",
@@ -82,20 +81,14 @@ ai = [
     "imagehash>=4.3",
     # Audio source separation (understanding/separation.py)
     "demucs>=4.0.0",
-    # Voice cloning TTS (generation/audio.py — Chatterbox). Upstream chatterbox-tts
-    # 0.1.7 pins diffusers==0.29.0 / torch==2.6.0 / transformers==5.2.0 with `==`,
-    # which is unsatisfiable against pyannote-audio (torch>=2.8) and our
-    # diffusers>=0.35 — it made `pip install "videopython[ai]"` impossible for
-    # consumers. videopython-chatterbox is upstream's source with corrected
-    # metadata (identical apart from its self-version lookup); the import name is
-    # still `chatterbox`. See https://github.com/BartWojtowicz/videopython-chatterbox
+    # Voice cloning TTS (generation/audio.py). Our fork of chatterbox-tts with
+    # corrected metadata; import name is still `chatterbox`. Not upstream — its
+    # `==` pins make [ai] unsatisfiable. See DEVELOPMENT.md "Dependencies".
     "videopython-chatterbox>=0.1.7.post1",
-    # Local media generation: Qwen-Image/Wan2.2 + MusicGen (generation/*).
-    # >=0.35 is the floor that ships QwenImagePipeline + Wan2.2 support (tested on 0.37.1).
+    # Local media generation (generation/*). >=0.35 ships QwenImagePipeline + Wan2.2.
     "diffusers>=0.35.0",
-    # Wan2.2 i2v pipeline cleans prompts with ftfy via a hard import (diffusers'
-    # pipeline_wan_i2v); the t2v pipeline guards it with is_ftfy_available(), i2v
-    # does not, so it is a required dep for ImageToVideo.
+    # Required, despite looking like diffusers' problem: the Wan2.2 i2v pipeline
+    # imports ftfy unguarded (the t2v one guards it with is_ftfy_available()).
     "ftfy>=6.1",
     "accelerate>=0.29.2",
     # Dubbing loudness matching (dubbing/loudness.py)
@@ -106,16 +99,13 @@ ai = [
     # processor used by the D-FINE object detector (understanding/objects.py).
     "torch>=2.8.0",
     "torchaudio>=2.8.0",
-    # No upper bound: each torchvision release declares an exact `torch==X.Y.Z`
-    # pin, so resolvers co-select a valid pair unaided. Capping torchvision alone
-    # is actively harmful — it transitively pinned torch to 2.8 (cu12) while
-    # torchaudio floated to 2.11 (cu13), resolving cleanly and then dying at
-    # import with `OSError: libcudart.so.13`. Cap every member or none.
+    # Do NOT add an upper bound. torchvision pins an exact torch, so capping it
+    # alone pinned torch to 2.8 (cu12) while torchaudio floated to 2.11 (cu13) —
+    # resolved cleanly, then died at import with `OSError: libcudart.so.13`.
+    # Cap every member of the torch stack or none.
     "torchvision>=0.23.0",
-    # torchaudio 2.11 routes save()/load() through torchcodec, and torchcodec is a
-    # native extension linked against libtorch that declares no torch requirement
-    # of its own. It arrives transitively via pyannote-audio; declare it so it is
-    # visible rather than incidental.
+    # Transitive via pyannote-audio, declared because torchaudio 2.11+ routes
+    # save()/load() through it and it is ABI-coupled to torch.
     "torchcodec>=0.7.0",
 ]
 # MCP server (videopython/mcp/). Pin <2 — v2 is pre-release/breaking.
@@ -150,36 +140,17 @@ module = [
     "silero_vad", "silero_vad.*",
     "cv2", "cv2.*",
     "pyloudnorm", "pyloudnorm.*",
+    "soxr", "soxr.*",
     "imagehash", "imagehash.*",
     "mcp", "mcp.*",
 ]
 ignore_missing_imports = true
 
 [tool.uv]
-# NOTE: overrides are a uv workspace feature — they do NOT ship in the built
-# wheel. Anything reconciled only here is invisible to `pip install videopython`,
-# so [ai] must be resolvable without this block. Keep it minimal.
-#
-# The torch/torchaudio/torchvision/diffusers overrides that used to live here
-# existed solely to paper over chatterbox-tts's `==` pins. They masked the
-# breakage from CI while every downstream consumer hit it, and an override
-# replaces a requirement *everywhere* — including torchvision's own exact
-# `torch==2.8.0` pin, which would have produced an ABI-invalid pair on the next
-# `uv lock --upgrade`. [ai] now depends on videopython-chatterbox, whose metadata
-# is correct, so none of them are needed.
-# The numpy>=2.0.0 override is gone for the same reason: it existed to counter
-# chatterbox-tts's `numpy<2.0.0` pin, and it also replaced numba's `numpy<2.5`
-# cap, resolving numpy 2.5 into an environment where `import whisper` dies with
-# "Numba needs NumPy 2.4 or less". numba IS version-coupled to numpy.
-override-dependencies = [
-    # Some transitive deps pull opencv-python, which conflicts with our
-    # opencv-python-headless (both provide cv2). Exclude opencv-python so
-    # only the headless variant is installed.
-    "opencv-python ; sys_platform == '_'",
-]
-# Pin minimum versions for transitive deps with known vulnerabilities.
-# Pygments 2.20.0 has a security fix but breaks mkdocs (passes None to html.escape).
-# Keep pygments<2.20.0 until a compatible release is available.
+# No overrides, deliberately: they are a uv workspace feature and do not ship in
+# the wheel, so anything patched here is invisible to `pip install`. Fix the
+# dependency's metadata instead — see DEVELOPMENT.md "Dependencies".
+# requests: CVE floor. pygments <2.20.0: 2.20.0 breaks mkdocs (passes None to html.escape).
 constraint-dependencies = ["requests>=2.33.0", "pygments>=2.19.2,<2.20.0"]
 
 [build-system]
@@ -207,9 +178,6 @@ pythonpath = ["src/"]
 testpaths = ["src/tests"]
 python_files = ["test_*.py"]
 addopts = ["-v", "--tb=short"]
-markers = [
-    "requires_model_download: marks tests that require downloading ML models (skipped in CI)",
-]
 
 [tool.ruff]
 line-length = 120

{videopython-0.55.0 → videopython-0.55.2}/src/videopython/audio/audio.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 import io
 import subprocess
+import tempfile
 import wave
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
+import soxr
 
 from videopython.base import _ffmpeg
 from videopython.base.exceptions import AudioLoadError, FFmpegProbeError
@@ -15,6 +17,17 @@ from videopython.base.exceptions import AudioLoadError, FFmpegProbeError
 if TYPE_CHECKING:
     from videopython.audio.analysis import AudioLevels, AudioSegment, AudioSegmentType, SilentSegment
 
+# What `Audio.from_path` asks ffmpeg for. Piped WAV comes back as pcm_s16le whatever
+# the source's bit depth, so requesting raw s16le loses no fidelity that the WAV path
+# was preserving, and there is no header to parse back.
+_PCM_FORMAT = "s16le"
+_PCM_DTYPE = np.int16
+_PCM_SAMPLE_WIDTH = 2
+
+# Read size when draining ffmpeg's stdout: big enough that a multi-GB decode is not
+# millions of round trips, small enough to be irrelevant for a short clip.
+_DECODE_CHUNK_BYTES = 8 << 20
+
 
 def atempo_chain(speed: float) -> list[str]:
     """Build the ``atempo`` filter chain that time-stretches audio by ``speed``.
@@ -162,100 +175,131 @@ class Audio:
         return cls(data, metadata)
 
     @classmethod
-    def from_path(cls, file_path: str | Path) -> Audio:
+    def from_path(
+        cls,
+        file_path: str | Path,
+        *,
+        sample_rate: int | None = None,
+        channels: int | None = None,
+    ) -> Audio:
         """
-        Load audio from a file using ffmpeg
+        Load audio from a file using ffmpeg.
+
+        ``sample_rate`` and ``channels`` ask ffmpeg to convert *while decoding*
+        rather than loading the source in full and converting afterwards. For a
+        caller that only wants 16kHz mono -- speech recognition, diarization,
+        speaker embeddings -- that is the difference between holding the whole
+        source in memory and holding a twelfth of it: a 12-hour 48kHz stereo
+        recording is 16.5GB of float32 at source rate and 1.4GB at 16kHz mono.
+        Resampling uses soxr, the engine :meth:`resample` uses, so the result
+        tracks ``Audio.from_path(p).to_mono().resample(r)`` sample for sample at
+        an error RMS around one 16-bit LSB -- the two quantize at different points
+        in the chain, and neither is the more faithful for it.
 
         Args:
             file_path: Path to the audio file
+            sample_rate: Decode at this rate instead of the source's.
+            channels: Decode to this many channels instead of the source's.
+                ``1`` downmixes to mono.
 
         Returns:
             Audio: New Audio instance
 
         Raises:
             FileNotFoundError: If the file doesn't exist
+            ValueError: If ``sample_rate`` or ``channels`` is not positive
             AudioLoadError: If there's an error loading the audio
         """
         file_path = Path(file_path)
         if not file_path.exists():
             raise FileNotFoundError(f"File not found: {file_path}")
+        if sample_rate is not None and sample_rate <= 0:
+            raise ValueError("Sample rate must be positive")
+        if channels is not None and channels <= 0:
+            raise ValueError("Channel count must be positive")
 
-        # Get audio info
         info = cls._get_ffmpeg_info(file_path)
-
-        # Convert to WAV using ffmpeg
+        target_rate = info["sample_rate"] if sample_rate is None else sample_rate
+        target_channels = info["channels"] if channels is None else channels
+
+        # Raw PCM rather than a WAV round-trip. Piped WAV comes back as pcm_s16le
+        # whatever the source's bit depth -- `-bits_per_raw_sample` is a hint the
+        # WAV muxer does not act on -- and its header carries a placeholder length
+        # because a pipe is not seekable. So parsing it back told us only what we
+        # had already asked for, and cost two more full copies of the audio on the
+        # way: one for `BytesIO`, one for `readframes`.
         cmd = [
             "ffmpeg",
+            "-v",
+            "error",
             "-i",
             str(file_path),
             "-f",
-            "wav",
+            _PCM_FORMAT,
             "-ar",
-            str(info["sample_rate"]),  # sample rate
+            str(target_rate),
             "-ac",
-            str(info["channels"]),  # channels
-            "-bits_per_raw_sample",
-            str(info["bit_depth"]),
+            str(target_channels),
+            # soxr rather than ffmpeg's default resampler, so that decoding at a
+            # rate and resampling to it afterwards agree.
+            "-af",
+            "aresample=resampler=soxr",
             "-",  # Output to stdout
         ]
 
         try:
-            process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-            wav_data, stderr = process.communicate()
+            # stderr to a file, not a pipe: stdout is drained to completion before
+            # stderr is read, and a full stderr pipe would deadlock ffmpeg partway
+            # through the audio.
+            with tempfile.TemporaryFile() as errors:
+                process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=errors)
+                assert process.stdout is not None
+                # A bytearray rather than `communicate()`, which accumulates chunks
+                # in a list and joins them at the end -- holding the whole of a long
+                # decode twice at the moment it completes.
+                raw = bytearray()
+                try:
+                    while chunk := process.stdout.read(_DECODE_CHUNK_BYTES):
+                        raw += chunk
+                finally:
+                    process.stdout.close()
+                if process.wait() != 0:
+                    errors.seek(0)
+                    raise AudioLoadError(f"FFmpeg error: {errors.read().decode(errors='replace')}")
+        except subprocess.CalledProcessError as e:
+            raise AudioLoadError(f"Error running ffmpeg: {e}")
 
-            if process.returncode != 0:
-                raise AudioLoadError(f"FFmpeg error: {stderr.decode()}")
-
-            # Read WAV data
-            with io.BytesIO(wav_data) as wav_io:
-                with wave.open(wav_io, "rb") as wav_file:
-                    # Get WAV metadata
-                    sample_width = wav_file.getsampwidth()
-                    channels = wav_file.getnchannels()
-                    sample_rate = wav_file.getframerate()
-                    n_frames = wav_file.getnframes()
-
-                    # Read raw audio data
-                    raw_data = wav_file.readframes(n_frames)
-
-                    # Convert bytes to numpy array based on sample width
-                    dtype_map = {1: np.int8, 2: np.int16, 4: np.int32}
-                    dtype = dtype_map.get(sample_width)
-                    if dtype is None:
-                        raise AudioLoadError(f"Unsupported sample width: {sample_width}")
-
-                    # Explicitly annotated: numpy>=2.5 shape-types ndarray, so the
-                    # 1-D frombuffer result cannot be rebound to a 2-D view below.
-                    data: np.ndarray[Any, np.dtype[np.float32]]
-                    data = np.frombuffer(raw_data, dtype=dtype).astype(np.float32)
-
-                    # Reshape to (frames, channels) if stereo
-                    if channels == 2:
-                        data = data.reshape(-1, 2)
-
-                    # Normalize to float between -1 and 1
-                    max_value = float(np.iinfo(dtype).max)  # type: ignore
-                    data = data / max_value
-
-                    # Ensure normalization is within bounds due to floating point precision
-                    data = np.clip(data, -1.0, 1.0)
-
-                    # Calculate frame count from actual data length
-                    # For stereo, len(data) is already correct after reshape
-                    frame_count = len(data)
-
-                    metadata = AudioMetadata(
-                        sample_rate=sample_rate,
-                        channels=channels,
-                        sample_width=sample_width,
-                        duration_seconds=info["duration"],
-                        frame_count=frame_count,
-                    )
+        # A truncated final frame would otherwise make `frombuffer` raise on a file
+        # that is entirely usable up to that point.
+        frame_bytes = _PCM_SAMPLE_WIDTH * target_channels
+        usable = len(raw) - (len(raw) % frame_bytes)
 
-                    return cls(data, metadata)
+        # Explicitly annotated: numpy>=2.5 shape-types ndarray, so the
+        # 1-D frombuffer result cannot be rebound to a 2-D view below.
+        data: np.ndarray[Any, np.dtype[np.float32]]
+        data = np.frombuffer(memoryview(raw)[:usable], dtype=_PCM_DTYPE).astype(np.float32)
 
-        except subprocess.CalledProcessError as e:
-            raise AudioLoadError(f"Error running ffmpeg: {e}")
+        # Reshape to (frames, channels) if stereo
+        if target_channels == 2:
+            data = data.reshape(-1, 2)
+
+        # Normalize to float between -1 and 1, and clamp for floating-point
+        # precision. Both in place: at these sizes a copy per step is most of what
+        # makes decoding a long file expensive.
+        data /= float(np.iinfo(_PCM_DTYPE).max)
+        np.clip(data, -1.0, 1.0, out=data)
+
+        # Calculate frame count from actual data length
+        # For stereo, len(data) is already correct after reshape
+        metadata = AudioMetadata(
+            sample_rate=target_rate,
+            channels=target_channels,
+            sample_width=_PCM_SAMPLE_WIDTH,
+            duration_seconds=info["duration"],
+            frame_count=len(data),
+        )
+
+        return cls(data, metadata)
 
     @classmethod
     def from_file(cls, file_path: str | Path) -> Audio:
@@ -384,6 +428,8 @@ class Audio:
         """
         Resample the audio to a new sample rate
 
+        Uses `soxr` (band-limited polyphase), the same engine librosa resamples with.
+
         Args:
             target_sample_rate: New sample rate in Hz
 
@@ -393,19 +439,16 @@ class Audio:
         if target_sample_rate == self.metadata.sample_rate:
             return self
 
-        # Calculate resampling ratio
-        ratio = target_sample_rate / self.metadata.sample_rate
-
-        target_length = round(self.data.shape[0] * ratio)
-
-        audio_array = self.data
-        if self.metadata.channels == 1:
-            audio_array = audio_array.reshape(-1, 1)
-
-        resampled_data = np.zeros((target_length, self.metadata.channels), dtype=np.float32)
+        # soxr takes mono (1-D) and interleaved stereo directly. "HQ" is librosa's default.
+        resampled_data = soxr.resample(
+            self.data,
+            self.metadata.sample_rate,
+            target_sample_rate,
+            quality="HQ",
+        ).astype(np.float32)
 
-        for channel in range(self.metadata.channels):
-            resampled_data[:, channel] = self._resample_channel(audio_array[:, channel], target_length)
+        # From the resampler, not a predicted round(n * ratio): metadata must match the array.
+        target_length = resampled_data.shape[0]
 
         new_metadata = AudioMetadata(
             sample_rate=target_sample_rate,
@@ -414,41 +457,9 @@ class Audio:
             duration_seconds=target_length / target_sample_rate,
             frame_count=target_length,
         )
-        if self.metadata.channels == 1:
-            resampled_data = resampled_data.flatten()
 
         return Audio(resampled_data, new_metadata)
 
-    @staticmethod
-    def _resample_channel(data: np.ndarray, new_length: int) -> np.ndarray:
-        """Resample a single channel of audio data to a new length"""
-
-        data_fourier = np.fft.rfft(data)
-        original_length = data.shape[0]
-
-        newshape = [new_length // 2 + 1]
-
-        data_fourier_placeholder = np.zeros(newshape, data_fourier.dtype)
-
-        min_length = min(new_length, original_length)
-        nyquist = min_length // 2 + 1
-        sl = [slice(0, nyquist)]
-        data_fourier_placeholder[tuple(sl)] = data_fourier[tuple(sl)]
-
-        if min_length % 2 == 0:
-            if new_length < original_length:
-                sl = [slice(min_length // 2, min_length // 2 + 1)]
-                data_fourier_placeholder[tuple(sl)] *= 2.0
-
-                sl = [slice(min_length // 2, min_length // 2 + 1)]
-                data_fourier_placeholder[tuple(sl)] *= 0.5
-
-        resampled_data = np.fft.irfft(data_fourier_placeholder, new_length)
-
-        resampled_data *= float(new_length) / float(original_length)
-
-        return resampled_data
-
     def concat(self, other: Audio, crossfade: float = 0.0) -> Audio:
         """
         Concatenate another audio segment to this one.
@@ -685,8 +696,6 @@ class Audio:
         filter_str = ",".join(filters) if filters else "anull"
 
         # Save current audio to temp WAV, process with ffmpeg, read back
-        import tempfile
-
         with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as input_file:
             input_path = input_file.name
 

{videopython-0.55.0 → videopython-0.55.2}/src/videopython/editing/effects.py

@@ -311,9 +311,8 @@ class ColorGrading(Effect):
         if self.brightness != 0 or self.contrast != 1.0:
             out = cv2.LUT(out, self._lut_tone)
         if self.saturation != 1.0:
-            # Saturation as a blend toward the luma-weighted greyscale of the
-            # frame. Replaces an RGB->HSV->RGB float32 round trip that cost more
-            # than every other stage of the grade combined (~42 of 56 ms/frame).
+            # Blend toward luma-weighted greyscale. Not an HSV round trip: that
+            # costs more than every other stage of the grade combined.
             grey = cv2.cvtColor(out, cv2.COLOR_RGB2GRAY)
             out = cv2.addWeighted(
                 out, self.saturation, cv2.cvtColor(grey, cv2.COLOR_GRAY2RGB), 1.0 - self.saturation, 0
@@ -364,17 +363,13 @@ class Vignette(Effect):
     def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         """Bake the gain mask into a 3-channel uint8 lookup, once per stream.
 
-        The mask is static, so the only per-frame work should be one multiply.
-        Storing it as uint8 replicated across channels lets ``cv2.multiply`` run
-        the whole frame in a single SIMD pass with no float conversion --
-        ~10x faster than promoting every frame to float32, and the mask itself
-        is *smaller* than the float32 original (6.2 MB vs 8.3 MB at 1080p).
-
-        The clip to [0, 1] also fixes a real defect: ``_create_mask`` goes
-        NEGATIVE once ``strength`` is high enough (down to -1.0 at
-        ``strength=1.0``), and ``(frame * -1.0).astype(np.uint8)`` wraps around,
-        so the darkest corners rendered as mid-grey (200 -> 56) and the vignette
-        got *brighter* past the zero crossing instead of saturating to black.
+        The mask is static, so per-frame work is one ``cv2.multiply`` SIMD pass
+        with no float conversion.
+
+        Clipping to [0, 1] is load-bearing, not tidying: ``_create_mask`` goes
+        negative once ``strength`` is high enough (-1.0 at ``strength=1.0``), and
+        ``(frame * -1.0).astype(np.uint8)`` wraps, which renders the darkest
+        corners mid-grey and makes the vignette brighten past the zero crossing.
         """
         if self._mask is None or self._mask.shape != (height, width):
             self._mask = self._create_mask(height, width)
@@ -1429,18 +1424,14 @@ class FilmGrain(Effect):
     _geometry: tuple[int, int] = PrivateAttr(default=(0, 0))
 
     def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
-        """Draw one oversized noise plane up front; each frame reads a random window of it.
-
-        Generating fresh Gaussian noise per frame meant ~2M ``standard_normal``
-        samples every frame, which dominated the effect (~31 ms/frame, more than
-        twice the encoder's whole per-frame budget). Sampling a
-        ``GRAIN_POOL_PAD``-padded plane once and taking a randomly offset window
-        per frame gives grain that still changes every frame -- offsets jump
-        rather than drift, so it scintillates like film rather than sliding --
-        for one saturating integer add.
-
-        Reproducibility is unchanged in contract (same ``seed`` -> same grain),
-        though the pattern itself differs from the per-frame-RNG version.
+        """Draw one oversized noise plane up front; each frame reads a random window.
+
+        Sampling Gaussian noise per frame costs ~2M draws a frame and dominates
+        the effect; one padded plane plus a per-frame offset reduces that to a
+        saturating integer add.
+
+        Offsets jump rather than advance, so the grain scintillates like film
+        instead of sliding. Same ``seed`` still gives the same grain.
         """
         amp = self.intensity * 255.0
         pad = GRAIN_POOL_PAD