open-montage 0.3.0__tar.gz

open_montage-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        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: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest
+
+  render:
+    # Installs the optional renderer (MoviePy + bundled ffmpeg) and runs the
+    # full suite, including the integration test that encodes a real video.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install (with render extra)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,render]"
+      - name: Test (incl. video rendering)
+        run: pytest

open_montage-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+# Build distributions on every tag, and publish to PyPI for v* tags.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Publishes using a PYPI_API_TOKEN repository secret. Add it under
+    # Settings -> Secrets and variables -> Actions (see "Publishing" in README).
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

open_montage-0.3.0/.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

open_montage-0.3.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-06-06
+
+### Added
+
+- Aspect-ratio fitting for rendering: `fit="contain"` (letterbox, default),
+  `"cover"` (fill and crop), or `"stretch"`.
+- Crossfade `transition` between consecutive clips.
+- `ken_burns` slow centered zoom on still images.
+- Optional `title` card and per-clip `captions` (drawn from each clip's label),
+  rendered with Pillow so no system font is required.
+- New CLI flags: `--fit`, `--transition`, `--ken-burns`, `--title`,
+  `--title-duration`, `--captions`.
+- Release workflow (`.github/workflows/release.yml`) that builds and publishes
+  to PyPI on `v*` tags via Trusted Publishing, plus a README "Publishing"
+  section.
+
+## [0.2.0] - 2026-06-05
+
+### Added
+
+- Video rendering: `open_montage.render.render_montage()` turns a montage into a
+  real MP4 — still images held for their duration, video clips trimmed and
+  concatenated, with an optional audio track. Built on MoviePy (bundled ffmpeg
+  via imageio-ffmpeg), exposed behind the optional `[render]` extra so the core
+  model stays dependency-free.
+- `open-montage render` CLI subcommand (`--fps`, `--size`, `--audio`,
+  `--progress`).
+- Helpers `clip_kind()` and `parse_size()`, and a `RenderError` type.
+- Tests for the renderer, including an integration test that encodes a real
+  video (skipped when the render extra is unavailable), plus a CI job that
+  exercises rendering.
+
+## [0.1.0] - 2026-06-05
+
+### Added
+
+- Initial project scaffold.
+- Core domain model: `Clip`, `Segment`, `Montage`, and `MontageError`.
+- `Montage.timeline()` for computing absolute clip start/end times, plus
+  JSON serialization (`to_json` / `from_json`).
+- `open-montage` command-line interface with `build` and `info` subcommands.
+- Test suite, `ruff` linting, and a GitHub Actions CI workflow.

open_montage-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to Open Montage
+
+Thanks for helping build Open Montage.
+
+## Getting set up
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Before opening a PR
+
+Please make sure both of these pass:
+
+```bash
+ruff check .
+pytest
+```
+
+## Guidelines
+
+- Keep `open_montage.montage` free of I/O and third-party dependencies — it is
+  the pure core of the project. I/O and integrations belong in `cli.py` or in
+  new, clearly separated modules.
+- Add or update tests for any behavior change.
+- Keep public API changes documented in the `README` and `CHANGELOG`.

open_montage-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BAS-More
+
+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.

open_montage-0.3.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: open-montage
+Version: 0.3.0
+Summary: Describe media montages and render them into real movies.
+Project-URL: Homepage, https://github.com/BAS-More/Open-Montage
+Project-URL: Repository, https://github.com/BAS-More/Open-Montage
+Project-URL: Issues, https://github.com/BAS-More/Open-Montage/issues
+Author: BAS-More
+License: MIT
+License-File: LICENSE
+Keywords: edit-decision-list,media,montage,timeline,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: render
+Requires-Dist: moviepy<3,>=2.0; extra == 'render'
+Description-Content-Type: text/markdown
+
+# Open Montage
+
+A Python toolkit to **describe media montages and render them into real movies**.
+
+Open Montage has two layers:
+
+1. **A tiny, dependency-free model** — build a montage out of clips and read back
+   its timeline (the absolute start/end time of every clip), serialize it to JSON.
+2. **A video renderer** — turn that montage into an actual MP4: still images are
+   held for their duration, video clips are trimmed and stitched together, with an
+   optional audio track. Rendering uses [MoviePy](https://zulko.github.io/moviepy/),
+   which ships its own ffmpeg, so **no system ffmpeg install is needed**.
+
+`v0.3.0`, part of the BAS-More software library.
+
+## Install
+
+```bash
+pip install -e ".[render]"     # model + video renderer
+pip install -e ".[dev,render]" # everything, incl. test/lint tools
+pip install -e .               # model + CLI only (build/info), no rendering deps
+```
+
+The core model has **no third-party dependencies**; only the renderer pulls in
+MoviePy + ffmpeg.
+
+## Make a movie
+
+```bash
+# 1. Describe the montage (3 sources, 1.5s each)
+open-montage build scene1.png clip.mp4 scene2.jpg --duration 1.5 --title "Reel" -o reel.json
+
+# 2. Render it to a video file
+open-montage render reel.json -o reel.mp4 --fps 24 --size 1280x720 --audio music.mp3
+# Wrote 3 clip(s) → reel.mp4 (4.5s)
+
+# ...with effects: letterbox, crossfades, slow zoom, a title card and captions
+open-montage render reel.json -o reel.mp4 \
+    --size 1920x1080 --fit contain --transition 0.5 \
+    --ken-burns --title "Holiday" --captions
+```
+
+- **Images** (`.png .jpg .jpeg .bmp .gif .webp .tif`) are shown as stills for
+  their duration.
+- **Videos** (`.mp4 .mov .avi .mkv .webm .m4v .mpg`) are trimmed to their duration
+  (or used whole if shorter).
+- `--size` defaults to the first video clip's resolution, falling back to 1280×720.
+- `--audio` lays a track under the whole montage, trimmed to its length.
+
+### Effects
+
+| Flag | What it does |
+| --- | --- |
+| `--fit contain\|cover\|stretch` | Fit clips to the frame: letterbox (default), fill-and-crop, or stretch. |
+| `--transition SECONDS` | Crossfade between consecutive clips. Must be shorter than the shortest clip. |
+| `--ken-burns` | Slow centered zoom on still images. |
+| `--title TEXT` / `--title-duration S` | Show a title card before the montage. |
+| `--captions` | Overlay each clip's `label` as a caption along the bottom. |
+
+From Python:
+
+```python
+from open_montage import Clip, Montage, render_montage
+
+montage = (
+    Montage(title="Reel")
+    .add(Clip("scene1.png", duration=1.5, label="Sunrise"))
+    .add(Clip("clip.mp4", duration=3.0, label="Harbour"))
+)
+render_montage(
+    montage, "reel.mp4",
+    fps=24, size=(1920, 1080),
+    fit="contain", transition=0.5, ken_burns=True,
+    title="Holiday", captions=True, audio="music.mp3",
+)
+```
+
+## Model & inspection (no rendering deps)
+
+```python
+from open_montage import Clip, Montage
+
+montage = (
+    Montage(title="Holiday")
+    .add(Clip("beach.jpg", duration=2.0, label="Beach"))
+    .add(Clip("sunset.mp4", duration=4.0))
+)
+
+print(montage.total_duration)        # 6.0
+for segment in montage.timeline():
+    print(segment.clip.source, segment.start, "->", segment.end)
+
+montage.to_json()                    # serialize to a JSON document
+Montage.from_json(text)              # ...and back again
+```
+
+```bash
+open-montage info reel.json
+# Reel — 3 clip(s), 4.5s total
+#    1. scene1.png  [0s → 1.5s]
+#    ...
+```
+
+You can also run the CLI as a module: `python -m open_montage ...`.
+
+## Project layout
+
+```
+src/open_montage/
+  __init__.py     # public API (Clip, Montage, Segment, render_montage, ...)
+  montage.py      # pure domain model — no I/O, no dependencies
+  render.py       # video rendering via MoviePy/ffmpeg (optional [render] extra)
+  cli.py          # argparse command-line interface
+  __main__.py     # `python -m open_montage`
+tests/            # pytest suite
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,render]"
+ruff check .
+pytest
+```
+
+Render tests that encode video are skipped automatically if the `render` extra
+isn't installed.
+
+## Publishing
+
+Releases are built and published to [PyPI](https://pypi.org/) by
+[`.github/workflows/release.yml`](.github/workflows/release.yml) when a `v*` tag
+is pushed:
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+The workflow builds an sdist + wheel, runs `twine check`, and uploads to PyPI.
+Authentication uses a **PyPI API token**, configured once:
+
+1. Create the project / reserve the name `open-montage` on PyPI, and generate an
+   API token (PyPI → Account settings → API tokens).
+2. Add it to this repo as a secret named **`PYPI_API_TOKEN`**
+   (Settings → Secrets and variables → Actions → New repository secret).
+
+Then publishing happens automatically on the next `v*` tag. (Prefer keyless
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) instead? Drop the
+`with: password:` line from the publish step and configure a Trusted Publisher
+for this repo + `release.yml`.)
+
+Build locally to sanity-check before tagging:
+
+```bash
+python -m pip install build twine
+python -m build && python -m twine check dist/*
+```
+
+## License
+
+[MIT](LICENSE) © BAS-More

open_montage-0.3.0/README.md

@@ -0,0 +1,162 @@
+# Open Montage
+
+A Python toolkit to **describe media montages and render them into real movies**.
+
+Open Montage has two layers:
+
+1. **A tiny, dependency-free model** — build a montage out of clips and read back
+   its timeline (the absolute start/end time of every clip), serialize it to JSON.
+2. **A video renderer** — turn that montage into an actual MP4: still images are
+   held for their duration, video clips are trimmed and stitched together, with an
+   optional audio track. Rendering uses [MoviePy](https://zulko.github.io/moviepy/),
+   which ships its own ffmpeg, so **no system ffmpeg install is needed**.
+
+`v0.3.0`, part of the BAS-More software library.
+
+## Install
+
+```bash
+pip install -e ".[render]"     # model + video renderer
+pip install -e ".[dev,render]" # everything, incl. test/lint tools
+pip install -e .               # model + CLI only (build/info), no rendering deps
+```
+
+The core model has **no third-party dependencies**; only the renderer pulls in
+MoviePy + ffmpeg.
+
+## Make a movie
+
+```bash
+# 1. Describe the montage (3 sources, 1.5s each)
+open-montage build scene1.png clip.mp4 scene2.jpg --duration 1.5 --title "Reel" -o reel.json
+
+# 2. Render it to a video file
+open-montage render reel.json -o reel.mp4 --fps 24 --size 1280x720 --audio music.mp3
+# Wrote 3 clip(s) → reel.mp4 (4.5s)
+
+# ...with effects: letterbox, crossfades, slow zoom, a title card and captions
+open-montage render reel.json -o reel.mp4 \
+    --size 1920x1080 --fit contain --transition 0.5 \
+    --ken-burns --title "Holiday" --captions
+```
+
+- **Images** (`.png .jpg .jpeg .bmp .gif .webp .tif`) are shown as stills for
+  their duration.
+- **Videos** (`.mp4 .mov .avi .mkv .webm .m4v .mpg`) are trimmed to their duration
+  (or used whole if shorter).
+- `--size` defaults to the first video clip's resolution, falling back to 1280×720.
+- `--audio` lays a track under the whole montage, trimmed to its length.
+
+### Effects
+
+| Flag | What it does |
+| --- | --- |
+| `--fit contain\|cover\|stretch` | Fit clips to the frame: letterbox (default), fill-and-crop, or stretch. |
+| `--transition SECONDS` | Crossfade between consecutive clips. Must be shorter than the shortest clip. |
+| `--ken-burns` | Slow centered zoom on still images. |
+| `--title TEXT` / `--title-duration S` | Show a title card before the montage. |
+| `--captions` | Overlay each clip's `label` as a caption along the bottom. |
+
+From Python:
+
+```python
+from open_montage import Clip, Montage, render_montage
+
+montage = (
+    Montage(title="Reel")
+    .add(Clip("scene1.png", duration=1.5, label="Sunrise"))
+    .add(Clip("clip.mp4", duration=3.0, label="Harbour"))
+)
+render_montage(
+    montage, "reel.mp4",
+    fps=24, size=(1920, 1080),
+    fit="contain", transition=0.5, ken_burns=True,
+    title="Holiday", captions=True, audio="music.mp3",
+)
+```
+
+## Model & inspection (no rendering deps)
+
+```python
+from open_montage import Clip, Montage
+
+montage = (
+    Montage(title="Holiday")
+    .add(Clip("beach.jpg", duration=2.0, label="Beach"))
+    .add(Clip("sunset.mp4", duration=4.0))
+)
+
+print(montage.total_duration)        # 6.0
+for segment in montage.timeline():
+    print(segment.clip.source, segment.start, "->", segment.end)
+
+montage.to_json()                    # serialize to a JSON document
+Montage.from_json(text)              # ...and back again
+```
+
+```bash
+open-montage info reel.json
+# Reel — 3 clip(s), 4.5s total
+#    1. scene1.png  [0s → 1.5s]
+#    ...
+```
+
+You can also run the CLI as a module: `python -m open_montage ...`.
+
+## Project layout
+
+```
+src/open_montage/
+  __init__.py     # public API (Clip, Montage, Segment, render_montage, ...)
+  montage.py      # pure domain model — no I/O, no dependencies
+  render.py       # video rendering via MoviePy/ffmpeg (optional [render] extra)
+  cli.py          # argparse command-line interface
+  __main__.py     # `python -m open_montage`
+tests/            # pytest suite
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,render]"
+ruff check .
+pytest
+```
+
+Render tests that encode video are skipped automatically if the `render` extra
+isn't installed.
+
+## Publishing
+
+Releases are built and published to [PyPI](https://pypi.org/) by
+[`.github/workflows/release.yml`](.github/workflows/release.yml) when a `v*` tag
+is pushed:
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+The workflow builds an sdist + wheel, runs `twine check`, and uploads to PyPI.
+Authentication uses a **PyPI API token**, configured once:
+
+1. Create the project / reserve the name `open-montage` on PyPI, and generate an
+   API token (PyPI → Account settings → API tokens).
+2. Add it to this repo as a secret named **`PYPI_API_TOKEN`**
+   (Settings → Secrets and variables → Actions → New repository secret).
+
+Then publishing happens automatically on the next `v*` tag. (Prefer keyless
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) instead? Drop the
+`with: password:` line from the publish step and configure a Trusted Publisher
+for this repo + `release.yml`.)
+
+Build locally to sanity-check before tagging:
+
+```bash
+python -m pip install build twine
+python -m build && python -m twine check dist/*
+```
+
+## License
+
+[MIT](LICENSE) © BAS-More

open_montage-0.3.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "open-montage"
+description = "Describe media montages and render them into real movies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "BAS-More" }]
+keywords = ["montage", "media", "video", "edit-decision-list", "timeline"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Video",
+]
+dynamic = ["version"]
+dependencies = []
+
+[project.optional-dependencies]
+# Video rendering. MoviePy pulls in its own ffmpeg via imageio-ffmpeg, so no
+# system ffmpeg install is required.
+render = ["moviepy>=2.0,<3"]
+dev = ["pytest>=7", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/BAS-More/Open-Montage"
+Repository = "https://github.com/BAS-More/Open-Montage"
+Issues = "https://github.com/BAS-More/Open-Montage/issues"
+
+[project.scripts]
+open-montage = "open_montage.cli:main"
+
+[tool.hatch.version]
+path = "src/open_montage/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/open_montage"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

open_montage-0.3.0/src/open_montage/__init__.py

@@ -0,0 +1,23 @@
+"""Open Montage — describe media montages and render them into real movies.
+
+Two layers:
+
+* :mod:`open_montage.montage` — a tiny, dependency-free model. Build a
+  :class:`Montage` out of :class:`Clip` objects and read back its
+  :class:`Segment` timeline.
+* :mod:`open_montage.render` — turn a montage into an actual video file with
+  :func:`render_montage`. This needs the optional ``[render]`` extra (MoviePy).
+"""
+
+from .montage import Clip, Montage, MontageError, Segment
+from .render import RenderError, render_montage
+
+__all__ = [
+    "Clip",
+    "Montage",
+    "MontageError",
+    "RenderError",
+    "Segment",
+    "render_montage",
+]
+__version__ = "0.3.0"

open_montage-0.3.0/src/open_montage/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI with ``python -m open_montage``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())