videopython 0.55.0__tar.gz → 0.55.1__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: videopython
-Version: 0.55.0
+Version: 0.55.1
 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.1}/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.55.0"
+version = "0.55.1"
 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.1}/src/videopython/audio/audio.py

@@ -8,6 +8,7 @@ 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
@@ -384,6 +385,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 +396,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 +414,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.

{videopython-0.55.0 → videopython-0.55.1}/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