videopython 0.33.2__tar.gz → 0.33.4__tar.gz

videopython-0.33.4/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: videopython
+Version: 0.33.4
+Summary: Minimal video generation and processing library.
+Project-URL: Homepage, https://videopython.com
+Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
+Project-URL: Documentation, https://videopython.com
+Author-email: Bartosz Wójtowicz <bartoszwojtowicz@outlook.com>, Bartosz Rudnikowicz <bartoszrudnikowicz840@gmail.com>, Piotr Pukisz <piotr.pukisz@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,editing,generation,movie,opencv,python,shorts,video,videopython
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.10
+Requires-Dist: numpy>=1.25.2
+Requires-Dist: opencv-python-headless>=4.9.0.80
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: tqdm>=4.66.3
+Provides-Extra: ai
+Requires-Dist: accelerate>=0.29.2; extra == 'ai'
+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: hf-transfer>=0.1.9; extra == 'ai'
+Requires-Dist: imagehash>=4.3; extra == 'ai'
+Requires-Dist: llama-cpp-python>=0.3.0; extra == 'ai'
+Requires-Dist: numba>=0.61.0; extra == 'ai'
+Requires-Dist: ollama>=0.4.5; 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: scikit-learn>=1.3.0; extra == 'ai'
+Requires-Dist: scipy>=1.10.0; 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'
+Description-Content-Type: text/markdown
+
+# videopython
+
+[![PyPI](https://img.shields.io/pypi/v/videopython)](https://pypi.org/project/videopython/)
+[![Python](https://img.shields.io/pypi/pyversions/videopython)](https://pypi.org/project/videopython/)
+[![License](https://img.shields.io/github/license/BartWojtowicz/videopython)](LICENSE)
+
+Minimal, LLM-friendly Python library for programmatic video editing, processing, and AI video workflows.
+
+Full documentation: [videopython.com](https://videopython.com)
+
+> **Disclaimer:** This project started as a hand-written hobby project, but most of the code is now produced by LLM agents. Humans still drive direction, approve changes, and own design decisions.
+
+## Installation
+
+```bash
+# Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
+pip install videopython          # core video/audio editing
+pip install "videopython[ai]"    # + local AI features (GPU recommended)
+```
+
+Python `>=3.10, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
+
+## 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:
+
+```python
+from videopython.editing import VideoEdit
+
+edit = VideoEdit.from_dict({
+    "segments": [{
+        "source": "raw.mp4",
+        "start": 10.0,
+        "end": 20.0,
+        "operations": [
+            {"op": "resize", "width": 1080, "height": 1920},
+            {"op": "color_adjust", "saturation": 1.15, "contrast": 1.05},
+            {"op": "fade", "mode": "in", "duration": 0.5},
+        ],
+    }],
+})
+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. Use `edit.run()` to get a `Video` back in memory instead.
+
+### AI generation
+
+```python
+from videopython.ai import TextToImage, ImageToVideo, TextToSpeech
+
+image = TextToImage().generate_image("A cinematic mountain sunrise")
+video = ImageToVideo().generate_video(image=image)
+audio = TextToSpeech().generate_audio("Welcome to videopython.")
+video.add_audio(audio).save("ai_video.mp4")
+```
+
+## LLM & AI Agent Integration
+
+Every operation is a Pydantic model whose fields ARE the JSON wire format. `VideoEdit.json_schema()` returns a JSON Schema with a discriminated union over every registered `Operation` — pass it straight to Anthropic tool use, OpenAI function calling, or any structured-output API. Then `edit.validate()` dry-runs the plan via metadata before any frames are loaded, so a failed LLM output can be fed back as an error and retried cheaply.
+
+See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, validation error loops, and operation discovery patterns.
+
+## Features
+
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `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 (cut, resize, crop, fps, speed, reverse, freeze, silence removal) 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`, `SemanticSceneDetector`), `FaceTrackingCrop` transform, and the full-pipeline `VideoAnalyzer`.
+- **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
+
+## Examples
+
+- [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/)
+
+## Development
+
+See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, and contribution workflow.

videopython-0.33.4/README.md

@@ -0,0 +1,84 @@
+# videopython
+
+[![PyPI](https://img.shields.io/pypi/v/videopython)](https://pypi.org/project/videopython/)
+[![Python](https://img.shields.io/pypi/pyversions/videopython)](https://pypi.org/project/videopython/)
+[![License](https://img.shields.io/github/license/BartWojtowicz/videopython)](LICENSE)
+
+Minimal, LLM-friendly Python library for programmatic video editing, processing, and AI video workflows.
+
+Full documentation: [videopython.com](https://videopython.com)
+
+> **Disclaimer:** This project started as a hand-written hobby project, but most of the code is now produced by LLM agents. Humans still drive direction, approve changes, and own design decisions.
+
+## Installation
+
+```bash
+# Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
+pip install videopython          # core video/audio editing
+pip install "videopython[ai]"    # + local AI features (GPU recommended)
+```
+
+Python `>=3.10, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
+
+## 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:
+
+```python
+from videopython.editing import VideoEdit
+
+edit = VideoEdit.from_dict({
+    "segments": [{
+        "source": "raw.mp4",
+        "start": 10.0,
+        "end": 20.0,
+        "operations": [
+            {"op": "resize", "width": 1080, "height": 1920},
+            {"op": "color_adjust", "saturation": 1.15, "contrast": 1.05},
+            {"op": "fade", "mode": "in", "duration": 0.5},
+        ],
+    }],
+})
+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. Use `edit.run()` to get a `Video` back in memory instead.
+
+### AI generation
+
+```python
+from videopython.ai import TextToImage, ImageToVideo, TextToSpeech
+
+image = TextToImage().generate_image("A cinematic mountain sunrise")
+video = ImageToVideo().generate_video(image=image)
+audio = TextToSpeech().generate_audio("Welcome to videopython.")
+video.add_audio(audio).save("ai_video.mp4")
+```
+
+## LLM & AI Agent Integration
+
+Every operation is a Pydantic model whose fields ARE the JSON wire format. `VideoEdit.json_schema()` returns a JSON Schema with a discriminated union over every registered `Operation` — pass it straight to Anthropic tool use, OpenAI function calling, or any structured-output API. Then `edit.validate()` dry-runs the plan via metadata before any frames are loaded, so a failed LLM output can be fed back as an error and retried cheaply.
+
+See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, validation error loops, and operation discovery patterns.
+
+## Features
+
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `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 (cut, resize, crop, fps, speed, reverse, freeze, silence removal) 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`, `SemanticSceneDetector`), `FaceTrackingCrop` transform, and the full-pipeline `VideoAnalyzer`.
+- **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
+
+## Examples
+
+- [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/)
+
+## Development
+
+See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, and contribution workflow.

{videopython-0.33.2 → videopython-0.33.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.33.2"
+version = "0.33.4"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -186,9 +186,11 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/videopython"]
+artifacts = ["src/videopython/base/fonts/*.ttf", "src/videopython/base/fonts/LICENSE_DEJAVU"]
 
 [tool.hatch.build.targets.sdist]
 include = ["src/videopython", "src/videopython/py.typed"]
+artifacts = ["src/videopython/base/fonts/*.ttf", "src/videopython/base/fonts/LICENSE_DEJAVU"]
 
 [tool.pytest.ini_options]
 pythonpath = ["src/"]

videopython-0.33.4/src/videopython/base/fonts/LICENSE_DEJAVU

@@ -0,0 +1,99 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org. 
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+$Id: LICENSE 2133 2007-11-28 02:46:28Z lechimp $

videopython-0.33.4/src/videopython/base/fonts/__init__.py

@@ -0,0 +1,58 @@
+"""Bundled default font and graceful font loading.
+
+Text operations let callers omit a font path. This module provides a
+reliable resolution chain so rendering never hard-fails on a missing or
+unreadable font:
+
+1. The explicit ``font_filename`` if given and loadable.
+2. The bundled DejaVu Sans (broad Unicode coverage).
+3. PIL's built-in font (always available).
+"""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+
+from PIL import ImageFont
+
+__all__ = ["DEFAULT_FONT_FILENAME", "load_font"]
+
+DEFAULT_FONT_FILENAME = "DejaVuSans.ttf"
+
+
+def _try_truetype(path: str, font_size: int) -> ImageFont.FreeTypeFont | None:
+    try:
+        return ImageFont.truetype(path, font_size)
+    except (OSError, ValueError):
+        return None
+
+
+def load_font(font_filename: str | None, font_size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    """Load a font, falling back gracefully when one is unavailable.
+
+    Resolution order: the given ``font_filename`` -> the bundled DejaVu
+    Sans -> PIL's built-in bitmap font. Never raises for a missing or
+    unreadable font, so callers may pass ``None`` to mean "use the
+    default".
+
+    Args:
+        font_filename: Path to a ``.ttf``/``.otf`` file, or ``None``.
+        font_size: Font size in points.
+
+    Returns:
+        A loaded PIL font object.
+    """
+    if font_filename:
+        font = _try_truetype(font_filename, font_size)
+        if font is not None:
+            return font
+
+    try:
+        with as_file(files(__package__).joinpath(DEFAULT_FONT_FILENAME)) as bundled:
+            font = _try_truetype(str(bundled), font_size)
+            if font is not None:
+                return font
+    except (FileNotFoundError, ModuleNotFoundError):
+        pass
+
+    return ImageFont.load_default(font_size)

{videopython-0.33.2 → videopython-0.33.4}/src/videopython/base/image_text.py

@@ -16,6 +16,7 @@ import numpy as np
 from PIL import Image, ImageDraw, ImageFont
 
 from videopython.base.exceptions import OutOfBoundsError
+from videopython.base.fonts import load_font
 
 __all__ = ["ImageText", "TextAlign", "AnchorPoint"]
 
@@ -106,7 +107,7 @@ class ImageText:
         # PIL uses (width, height), so we reverse for Image.new
         self.image = Image.new(mode, (image_size[1], image_size[0]), color=background)
         self._draw = ImageDraw.Draw(self.image)
-        self._font_cache: dict[tuple[str, int], ImageFont.FreeTypeFont] = {}  # Cache for font objects
+        self._font_cache: dict[tuple[str | None, int], ImageFont.FreeTypeFont | ImageFont.ImageFont] = {}
 
     @property
     def img_array(self) -> np.ndarray:
@@ -119,7 +120,7 @@ class ImageText:
             raise ValueError("Filename cannot be empty")
         self.image.save(filename)
 
-    def _fit_font_width(self, text: str, font: str, max_width: int) -> int:
+    def _fit_font_width(self, text: str, font: str | None, max_width: int) -> int:
         """
         Find the maximum font size where the text width is less than or equal to max_width.
 
@@ -150,7 +151,7 @@ class ImageText:
             raise ValueError(f"Max width {max_width} is too small for any font size!")
         return max_font_size
 
-    def _fit_font_height(self, text: str, font: str, max_height: int) -> int:
+    def _fit_font_height(self, text: str, font: str | None, max_height: int) -> int:
         """
         Find the maximum font size where the text height is less than or equal to max_height.
 
@@ -184,7 +185,7 @@ class ImageText:
     def _get_font_size(
         self,
         text: str,
-        font: str,
+        font: str | None,
         max_width: int | None = None,
         max_height: int | None = None,
     ) -> int:
@@ -333,7 +334,7 @@ class ImageText:
     def write_text(
         self,
         text: str,
-        font_filename: str,
+        font_filename: str | None,
         xy: PositionType,
         font_size: int | None = 11,
         font_border_size: int = 0,
@@ -368,9 +369,6 @@ class ImageText:
         if not text:
             raise ValueError("Text cannot be empty")
 
-        if not font_filename:
-            raise ValueError("Font filename cannot be empty")
-
         if font_size is not None and font_size <= 0:
             raise ValueError("Font size must be positive")
 
@@ -405,12 +403,16 @@ class ImageText:
         self._draw.text((x, y), text, font=font, fill=color)
         return text_dimensions
 
-    def _get_font(self, font_filename: str, font_size: int) -> ImageFont.FreeTypeFont:
+    def _get_font(self, font_filename: str | None, font_size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
         """
         Get a font object, using cache if available.
 
+        Resolves via :func:`videopython.base.fonts.load_font`, so a missing,
+        unreadable, or ``None`` ``font_filename`` gracefully falls back to
+        the bundled default font instead of raising.
+
         Args:
-            font_filename: Path to the font file
+            font_filename: Path to the font file, or None for the default.
             font_size: Size of the font in points
 
         Returns:
@@ -418,13 +420,10 @@ class ImageText:
         """
         key = (font_filename, font_size)
         if key not in self._font_cache:
-            try:
-                self._font_cache[key] = ImageFont.truetype(font_filename, font_size)
-            except (OSError, IOError) as e:
-                raise ValueError(f"Error loading font '{font_filename}': {str(e)}")
+            self._font_cache[key] = load_font(font_filename, font_size)
         return self._font_cache[key]
 
-    def get_text_dimensions(self, font_filename: str, font_size: int, text: str) -> tuple[int, int]:
+    def get_text_dimensions(self, font_filename: str | None, font_size: int, text: str) -> tuple[int, int]:
         """
         Return dimensions (width, height) of the rendered text.
 
@@ -455,7 +454,11 @@ class ImageText:
             raise ValueError(f"Error measuring text: {str(e)}")
 
     def _get_font_baseline_offset(
-        self, base_font_filename: str, base_font_size: int, highlight_font_filename: str, highlight_font_size: int
+        self,
+        base_font_filename: str | None,
+        base_font_size: int,
+        highlight_font_filename: str | None,
+        highlight_font_size: int,
     ) -> int:
         """
         Calculate the vertical offset needed to align baselines of different fonts and sizes.
@@ -497,7 +500,7 @@ class ImageText:
     def _split_lines_by_width(
         self,
         text: str,
-        font_filename: str,
+        font_filename: str | None,
         font_size: int,
         box_width: int,
     ) -> list[str]:
@@ -566,7 +569,7 @@ class ImageText:
     def write_text_box(
         self,
         text: str,
-        font_filename: str,
+        font_filename: str | None,
         xy: PositionType,
         box_width: int | float | None = None,
         font_size: int = 11,
@@ -615,9 +618,6 @@ class ImageText:
         if not text:
             raise ValueError("Text cannot be empty")
 
-        if not font_filename:
-            raise ValueError("Font filename cannot be empty")
-
         if font_size <= 0:
             raise ValueError("Font size must be positive")
 
@@ -831,7 +831,7 @@ class ImageText:
     def _write_line_with_highlight(
         self,
         line: str,
-        font_filename: str,
+        font_filename: str | None,
         font_size: int,
         font_border_size: int,
         text_color: RGBColor,

{videopython-0.33.2 → videopython-0.33.4}/src/videopython/base/transcription.py

@@ -6,6 +6,13 @@ from typing import Any
 
 __all__ = ["Transcription", "TranscriptionSegment", "TranscriptionWord"]
 
+# Sentence-ending punctuation used by ``Transcription.capitalize_sentences``.
+_SENTENCE_TERMINATORS = (".", "!", "?", "…")
+
+# Trailing characters stripped before checking for a sentence terminator
+# (closing quotes/brackets and whitespace), so ``end."`` still ends a sentence.
+_TRAILING_WRAPPERS = "\"')]}»”’ "
+
 
 @dataclass
 class TranscriptionWord:
@@ -279,6 +286,92 @@ class Transcription:
 
         return Transcription(segments=standardized_segments, language=self.language)
 
+    def capitalize_sentences(self) -> Transcription:
+        """Return a new Transcription with sentence-start capitalization.
+
+        The first letter of the first spoken word and of every word that
+        follows sentence-ending punctuation (``.``, ``!``, ``?``, ``…``) is
+        upper-cased. Remaining characters are left untouched, so acronyms and
+        proper nouns from the source transcription are preserved. Timing,
+        speaker, and language are carried through unchanged.
+
+        Abbreviation detection is intentionally not attempted: a token like
+        ``"U.S."`` is treated as a sentence end. This heuristic is adequate
+        for burned-in subtitles and avoids a brittle abbreviation list.
+        """
+        capitalized_segments: list[TranscriptionSegment] = []
+        start_of_sentence = True
+
+        for segment in self.segments:
+            new_words: list[TranscriptionWord] = []
+            for word in segment.words:
+                token = word.word
+                if start_of_sentence:
+                    idx = next((i for i, ch in enumerate(token) if ch.isalpha()), None)
+                    if idx is not None:
+                        token = token[:idx] + token[idx].upper() + token[idx + 1 :]
+                        start_of_sentence = False
+                if token.rstrip(_TRAILING_WRAPPERS).endswith(_SENTENCE_TERMINATORS):
+                    start_of_sentence = True
+                new_words.append(TranscriptionWord(start=word.start, end=word.end, word=token, speaker=word.speaker))
+
+            capitalized_segments.append(
+                TranscriptionSegment(
+                    start=segment.start,
+                    end=segment.end,
+                    text=" ".join(w.word for w in new_words),
+                    words=new_words,
+                    speaker=segment.speaker,
+                    avg_logprob=segment.avg_logprob,
+                    no_speech_prob=segment.no_speech_prob,
+                    compression_ratio=segment.compression_ratio,
+                )
+            )
+
+        return Transcription(segments=capitalized_segments, language=self.language)
+
+    def chunk_segments(self, max_words: int) -> Transcription:
+        """Return a new Transcription splitting each segment into smaller cues.
+
+        Each segment is split into consecutive groups of at most ``max_words``
+        words, using that group's own first/last word timings. Unlike
+        :meth:`standardize_segments`, words are never merged across the
+        original segments, so silence gaps between segments are preserved and
+        subtitles do not linger over pauses. Speaker, confidence, and language
+        metadata are carried through unchanged.
+
+        Args:
+            max_words: Maximum number of words per output segment.
+
+        Raises:
+            ValueError: If ``max_words`` is not positive.
+        """
+        if max_words <= 0:
+            raise ValueError("max_words must be positive")
+
+        chunked_segments: list[TranscriptionSegment] = []
+        for segment in self.segments:
+            words = segment.words
+            if not words:
+                chunked_segments.append(segment)
+                continue
+            for i in range(0, len(words), max_words):
+                group = words[i : i + max_words]
+                chunked_segments.append(
+                    TranscriptionSegment(
+                        start=group[0].start,
+                        end=group[-1].end,
+                        text=" ".join(w.word for w in group),
+                        words=list(group),
+                        speaker=segment.speaker,
+                        avg_logprob=segment.avg_logprob,
+                        no_speech_prob=segment.no_speech_prob,
+                        compression_ratio=segment.compression_ratio,
+                    )
+                )
+
+        return Transcription(segments=chunked_segments, language=self.language)
+
     def slice(self, start: float, end: float) -> Transcription | None:
         """Return a new Transcription containing only words within the time range.
 

{videopython-0.33.2 → videopython-0.33.4}/src/videopython/editing/effects.py

@@ -24,6 +24,7 @@ from pydantic import Field, PrivateAttr, model_validator
 from tqdm import tqdm
 
 from videopython.base.description import BoundingBox
+from videopython.base.fonts import load_font
 from videopython.editing.operation import Effect
 
 if TYPE_CHECKING:
@@ -643,12 +644,7 @@ class TextOverlay(Effect):
         return self
 
     def _get_font(self) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
-        if self.font_filename:
-            return ImageFont.truetype(self.font_filename, self.font_size)
-        try:
-            return ImageFont.truetype("DejaVuSans.ttf", self.font_size)
-        except OSError:
-            return ImageFont.load_default()
+        return load_font(self.font_filename, self.font_size)
 
     def _wrap_text(self, text: str, font: ImageFont.FreeTypeFont | ImageFont.ImageFont, max_px: int) -> str:
         lines: list[str] = []