slidecast 0.1.0__tar.gz

slidecast-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token stored.
+# Configure the publisher once at https://pypi.org/manage/account/publishing/
+# (project: slidecast, workflow: publish.yml, environment: pypi), then push a
+# version tag:  git tag v0.1.0 && git push origin v0.1.0
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

slidecast-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q

slidecast-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.env
+*.xlsx
+
+# media artifacts
+*.mp4
+*.wav
+*.mp3
+*.png
+*.jpg

slidecast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinay Vobbilichetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slidecast-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: slidecast
+Version: 0.1.0
+Summary: Turn a list of HTML slides + narration into a narrated MP4. Headless-browser screenshots, pluggable text-to-speech, ffmpeg stitching. Bring your own slide design and voice.
+Project-URL: Homepage, https://github.com/vinayvobbili/slidecast
+Project-URL: Source, https://github.com/vinayvobbili/slidecast
+Author: Vinay Vobbilichetty
+License: MIT
+License-File: LICENSE
+Keywords: ffmpeg,kokoro,narration,playwright,screencast,slides,tts,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: requests>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Provides-Extra: ffmpeg
+Requires-Dist: imageio-ffmpeg>=0.4; extra == 'ffmpeg'
+Provides-Extra: gtts
+Requires-Dist: gtts>=2.3; extra == 'gtts'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == 'playwright'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# slidecast
+
+Turn a list of HTML slides + narration into a narrated MP4.
+
+You bring the slide design — any HTML you like — and the words. slidecast
+screenshots each slide with a headless browser, narrates it with a pluggable
+text-to-speech provider, and stitches the frames into one MP4 with ffmpeg. It
+has no opinion about how your slides look and no hard dependency on a specific
+voice or browser: every piece is swappable.
+
+## Install
+
+```
+pip install slidecast              # core (requests only)
+pip install slidecast[playwright]  # default renderer (headless Chromium)
+pip install slidecast[gtts]        # Google Translate TTS
+pip install slidecast[ffmpeg]      # bundled ffmpeg binary (no system install)
+```
+
+After installing the Playwright extra, fetch the browser once:
+
+```
+playwright install chromium
+```
+
+You also need ffmpeg — on `PATH`, via `$SLIDECAST_FFMPEG`, or the `[ffmpeg]`
+extra's bundled binary.
+
+## Library
+
+```python
+from slidecast import Reel, KokoroTTS
+
+reel = Reel(width=1280, height=720, tts=KokoroTTS(voice="af_heart"))
+reel.add("<!doctype html><h1>Hello</h1>", "Hello, and welcome.")
+reel.add("<!doctype html><h1>Goodbye</h1>", "Thanks for watching.", tail_pad=0.8)
+reel.render("out.mp4", make_poster=True)
+```
+
+A slide with empty narration becomes a silent hold (`min_duration` seconds). When
+the TTS provider reports a clip duration, the segment is padded to fit the speech
+exactly; when it can't (e.g. MP3), the audio drives the length.
+
+## CLI
+
+```
+slidecast render reel.yaml -o out.mp4 --poster
+```
+
+```yaml
+width: 1280
+height: 720
+fps: 25
+tts:
+  provider: kokoro        # kokoro | gtts | silent
+  url: http://127.0.0.1:8021/v1/audio/speech
+  voice: af_heart
+  response_format: wav
+slides:
+  - html_file: intro.html
+    narration: "Before any of this, here's why it matters."
+    tail_pad: 0.8
+  - html: "<!doctype html><h1>Step one</h1>"
+    narration: ""          # silent slide
+    min_duration: 3
+```
+
+## The swappable pieces
+
+**Text-to-speech** — anything with `synthesize(text, path) -> seconds | None`:
+
+- `KokoroTTS` — any OpenAI-compatible `/v1/audio/speech` endpoint (Kokoro,
+  OpenAI, LocalAI, …). Defaults to WAV so the clip length is measurable.
+- `GTTSTTS` — Google Translate TTS (`gtts`).
+- `SilentTTS` — a silent track of a fixed length. No dependencies; the default,
+  so a reel renders end to end with nothing configured.
+
+Pass `phonetic={r"\bSOC\b": "sock"}` to rewrite how tricky tokens are spoken
+without changing the on-screen text.
+
+**Renderer** — a context manager exposing `screenshot(html, path, *, width, height)`:
+
+- `PlaywrightRenderer` — headless Chromium, launched once per reel (default).
+- `ChromeBinaryRenderer` — drive an existing Chrome/Chromium binary by path.
+
+**ffmpeg steps** are exposed directly (`build_segment`, `concat`, `poster`) and
+take an injectable `runner`, so you can compose your own pipeline or test command
+construction without invoking ffmpeg.
+
+## License
+
+MIT

slidecast-0.1.0/README.md

@@ -0,0 +1,92 @@
+# slidecast
+
+Turn a list of HTML slides + narration into a narrated MP4.
+
+You bring the slide design — any HTML you like — and the words. slidecast
+screenshots each slide with a headless browser, narrates it with a pluggable
+text-to-speech provider, and stitches the frames into one MP4 with ffmpeg. It
+has no opinion about how your slides look and no hard dependency on a specific
+voice or browser: every piece is swappable.
+
+## Install
+
+```
+pip install slidecast              # core (requests only)
+pip install slidecast[playwright]  # default renderer (headless Chromium)
+pip install slidecast[gtts]        # Google Translate TTS
+pip install slidecast[ffmpeg]      # bundled ffmpeg binary (no system install)
+```
+
+After installing the Playwright extra, fetch the browser once:
+
+```
+playwright install chromium
+```
+
+You also need ffmpeg — on `PATH`, via `$SLIDECAST_FFMPEG`, or the `[ffmpeg]`
+extra's bundled binary.
+
+## Library
+
+```python
+from slidecast import Reel, KokoroTTS
+
+reel = Reel(width=1280, height=720, tts=KokoroTTS(voice="af_heart"))
+reel.add("<!doctype html><h1>Hello</h1>", "Hello, and welcome.")
+reel.add("<!doctype html><h1>Goodbye</h1>", "Thanks for watching.", tail_pad=0.8)
+reel.render("out.mp4", make_poster=True)
+```
+
+A slide with empty narration becomes a silent hold (`min_duration` seconds). When
+the TTS provider reports a clip duration, the segment is padded to fit the speech
+exactly; when it can't (e.g. MP3), the audio drives the length.
+
+## CLI
+
+```
+slidecast render reel.yaml -o out.mp4 --poster
+```
+
+```yaml
+width: 1280
+height: 720
+fps: 25
+tts:
+  provider: kokoro        # kokoro | gtts | silent
+  url: http://127.0.0.1:8021/v1/audio/speech
+  voice: af_heart
+  response_format: wav
+slides:
+  - html_file: intro.html
+    narration: "Before any of this, here's why it matters."
+    tail_pad: 0.8
+  - html: "<!doctype html><h1>Step one</h1>"
+    narration: ""          # silent slide
+    min_duration: 3
+```
+
+## The swappable pieces
+
+**Text-to-speech** — anything with `synthesize(text, path) -> seconds | None`:
+
+- `KokoroTTS` — any OpenAI-compatible `/v1/audio/speech` endpoint (Kokoro,
+  OpenAI, LocalAI, …). Defaults to WAV so the clip length is measurable.
+- `GTTSTTS` — Google Translate TTS (`gtts`).
+- `SilentTTS` — a silent track of a fixed length. No dependencies; the default,
+  so a reel renders end to end with nothing configured.
+
+Pass `phonetic={r"\bSOC\b": "sock"}` to rewrite how tricky tokens are spoken
+without changing the on-screen text.
+
+**Renderer** — a context manager exposing `screenshot(html, path, *, width, height)`:
+
+- `PlaywrightRenderer` — headless Chromium, launched once per reel (default).
+- `ChromeBinaryRenderer` — drive an existing Chrome/Chromium binary by path.
+
+**ffmpeg steps** are exposed directly (`build_segment`, `concat`, `poster`) and
+take an injectable `runner`, so you can compose your own pipeline or test command
+construction without invoking ffmpeg.
+
+## License
+
+MIT

slidecast-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "slidecast"
+version = "0.1.0"
+description = "Turn a list of HTML slides + narration into a narrated MP4. Headless-browser screenshots, pluggable text-to-speech, ffmpeg stitching. Bring your own slide design and voice."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Vinay Vobbilichetty" }]
+keywords = ["video", "tts", "slides", "screencast", "ffmpeg", "playwright", "narration", "kokoro"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "requests>=2",
+]
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.40"]
+gtts = ["gtts>=2.3"]
+ffmpeg = ["imageio-ffmpeg>=0.4"]
+yaml = ["pyyaml>=6"]
+dev = ["pytest>=7", "pyyaml>=6"]
+
+[project.scripts]
+slidecast = "slidecast.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/vinayvobbili/slidecast"
+Source = "https://github.com/vinayvobbili/slidecast"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/slidecast"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

slidecast-0.1.0/src/slidecast/__init__.py

@@ -0,0 +1,67 @@
+"""slidecast — turn a list of HTML slides + narration into a narrated MP4.
+
+You bring the slide design (any HTML you like) and the words; slidecast
+screenshots each slide with a headless browser, narrates it with a pluggable
+text-to-speech provider, and stitches the frames into one MP4 with ffmpeg.
+
+Quick start
+-----------
+    from slidecast import Reel, KokoroTTS
+
+    reel = Reel(width=1280, height=720, tts=KokoroTTS(voice="af_heart"))
+    reel.add("<!doctype html><h1>Hello</h1>", "Hello, and welcome.")
+    reel.add("<!doctype html><h1>Bye</h1>", "Thanks for watching.", tail_pad=0.8)
+    reel.render("out.mp4", make_poster=True)
+
+Pieces (all swappable)
+----------------------
+Model:
+    Slide(html, narration="", tail_pad=0.0, min_duration=0.0)
+    Reel(width, height, fps, tts=..., renderer=...).add(...).render(out)
+Text-to-speech (``synthesize(text, path) -> seconds | None``):
+    KokoroTTS  — any OpenAI-compatible /v1/audio/speech endpoint
+    GTTSTTS    — Google Translate TTS (mp3)
+    SilentTTS  — silent track, no deps (default)
+Renderers (HTML -> PNG, used as a context manager):
+    PlaywrightRenderer    — headless Chromium (default)
+    ChromeBinaryRenderer  — drive an existing Chrome binary by path
+ffmpeg steps (injectable runner, for direct use/testing):
+    build_segment(...) / concat(...) / poster(...)
+    find_ffmpeg() -> path   (PATH, $SLIDECAST_FFMPEG, or imageio-ffmpeg)
+"""
+
+from .ffmpeg import FFmpegNotFound, find_ffmpeg
+from .models import Slide
+from .reel import Reel
+from .render import ChromeBinaryRenderer, PlaywrightRenderer, Renderer
+from .tts import (
+    GTTSTTS,
+    KokoroTTS,
+    SilentTTS,
+    TTSProvider,
+    apply_phonetic,
+    wav_duration,
+)
+from .video import build_segment, concat, poster
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Slide",
+    "Reel",
+    "Renderer",
+    "PlaywrightRenderer",
+    "ChromeBinaryRenderer",
+    "TTSProvider",
+    "KokoroTTS",
+    "GTTSTTS",
+    "SilentTTS",
+    "apply_phonetic",
+    "wav_duration",
+    "build_segment",
+    "concat",
+    "poster",
+    "find_ffmpeg",
+    "FFmpegNotFound",
+    "__version__",
+]

slidecast-0.1.0/src/slidecast/cli.py

@@ -0,0 +1,112 @@
+"""Command line: render a reel from a spec file.
+
+    slidecast render reel.yaml -o out.mp4 --poster
+
+A spec is YAML or JSON::
+
+    width: 1280
+    height: 720
+    fps: 25
+    tts:
+      provider: kokoro        # kokoro | gtts | silent
+      url: http://127.0.0.1:8021/v1/audio/speech
+      voice: af_heart
+      response_format: wav
+    slides:
+      - html_file: intro.html       # path (relative to the spec) ...
+        narration: "Welcome."
+        tail_pad: 0.8
+      - html: "<!doctype html>..."  # ... or inline HTML
+        narration: ""               # empty => silent slide
+        min_duration: 3
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+from .reel import Reel
+from .render import ChromeBinaryRenderer
+from .tts import GTTSTTS, KokoroTTS, SilentTTS
+
+
+def _load_spec(path: Path) -> Dict[str, Any]:
+    text = path.read_text()
+    if path.suffix in (".yaml", ".yml"):
+        try:
+            import yaml
+        except ImportError:  # noqa: BLE001
+            raise SystemExit("YAML spec needs PyYAML — `pip install slidecast[yaml]`")
+        return yaml.safe_load(text)
+    return json.loads(text)
+
+
+def _build_tts(cfg: Dict[str, Any]):
+    cfg = dict(cfg or {})
+    provider = (cfg.pop("provider", "silent") or "silent").lower()
+    if provider == "kokoro":
+        return KokoroTTS(**cfg)
+    if provider == "gtts":
+        return GTTSTTS(**cfg)
+    if provider == "silent":
+        return SilentTTS(**cfg) if cfg else SilentTTS()
+    raise SystemExit(f"Unknown tts provider: {provider!r}")
+
+
+def _build_reel(spec: Dict[str, Any], base: Path) -> Reel:
+    reel = Reel(
+        width=int(spec.get("width", 1920)),
+        height=int(spec.get("height", 1080)),
+        fps=int(spec.get("fps", 25)),
+        tts=_build_tts(spec.get("tts", {})),
+        silent_slide_seconds=float(spec.get("silent_slide_seconds", 3.0)),
+    )
+    chrome = spec.get("chrome")
+    if chrome:
+        reel.renderer = ChromeBinaryRenderer(chrome=chrome)
+    for s in spec.get("slides", []):
+        html = s.get("html")
+        if not html and s.get("html_file"):
+            html = (base / s["html_file"]).read_text()
+        if not html:
+            raise SystemExit("each slide needs 'html' or 'html_file'")
+        reel.add(html, s.get("narration", ""),
+                 tail_pad=float(s.get("tail_pad", 0.0)),
+                 min_duration=float(s.get("min_duration", 0.0)))
+    return reel
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="slidecast", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("render", help="render a reel spec to an MP4")
+    r.add_argument("spec", type=Path, help="YAML or JSON reel spec")
+    r.add_argument("-o", "--out", type=Path, required=True, help="output .mp4 path")
+    r.add_argument("--poster", action="store_true", help="also write <stem>_poster.jpg")
+    r.add_argument("--keep-work", type=Path, default=None,
+                   help="keep intermediate frames/audio in this directory")
+    args = parser.parse_args(argv)
+
+    if args.cmd == "render":
+        spec = _load_spec(args.spec)
+        reel = _build_reel(spec, args.spec.resolve().parent)
+        n = len(reel.slides)
+
+        def progress(i, total, slide):
+            head = slide.narration[:48].replace("\n", " ") or "(silent)"
+            print(f"  [{i}/{total}] {head}", file=sys.stderr)
+
+        out = reel.render(args.out, make_poster=args.poster,
+                          workdir=args.keep_work, on_progress=progress)
+        size_mb = out.stat().st_size / 1e6
+        print(f"✓ wrote {out} ({size_mb:.1f} MB) from {n} slides")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

slidecast-0.1.0/src/slidecast/ffmpeg.py

@@ -0,0 +1,42 @@
+"""Locate an ffmpeg binary without forcing a system install.
+
+Resolution order:
+1. ``$SLIDECAST_FFMPEG`` — an explicit path, wins over everything.
+2. ``ffmpeg`` on ``$PATH`` — the normal case on a dev box or CI image.
+3. The binary bundled with ``imageio-ffmpeg`` (the ``[ffmpeg]`` extra), so a pure
+   ``pip install`` with no system package still works.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+
+class FFmpegNotFound(RuntimeError):
+    """Raised when no ffmpeg binary can be located by any strategy."""
+
+
+def find_ffmpeg() -> str:
+    """Return a path to an ffmpeg executable, or raise :class:`FFmpegNotFound`."""
+    explicit = os.environ.get("SLIDECAST_FFMPEG")
+    if explicit:
+        if shutil.which(explicit) or os.path.isfile(explicit):
+            return explicit
+        raise FFmpegNotFound(f"SLIDECAST_FFMPEG={explicit!r} is not an executable")
+
+    on_path = shutil.which("ffmpeg")
+    if on_path:
+        return on_path
+
+    try:
+        import imageio_ffmpeg  # type: ignore
+
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception:  # noqa: BLE001 — any failure here means "not available"
+        pass
+
+    raise FFmpegNotFound(
+        "ffmpeg not found. Install it on PATH, set $SLIDECAST_FFMPEG, or "
+        "`pip install slidecast[ffmpeg]` to use the bundled binary."
+    )

slidecast-0.1.0/src/slidecast/models.py

@@ -0,0 +1,34 @@
+"""Core data model: a slide is one screen of HTML plus what the voice says over it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Slide:
+    """One frame of a reel.
+
+    Attributes:
+        html: A complete, self-contained HTML document. slidecast does not style
+            your slides — it screenshots exactly what you hand it, so the design,
+            fonts, and layout are entirely yours.
+        narration: What the voice reads over this slide. Empty string => a silent
+            slide that holds for ``min_duration`` seconds.
+        tail_pad: Seconds of silence appended after the narration so the last word
+            is never clipped. Only applied when the narration duration is known.
+        min_duration: A floor on the segment length in seconds. For silent slides
+            this *is* the duration; for narrated slides the segment is at least
+            this long even if the narration is shorter.
+    """
+
+    html: str
+    narration: str = ""
+    tail_pad: float = 0.0
+    min_duration: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.html, str) or not self.html.strip():
+            raise ValueError("Slide.html must be a non-empty HTML string")
+        if self.tail_pad < 0 or self.min_duration < 0:
+            raise ValueError("tail_pad and min_duration must be non-negative")