tituli 0.0.2__tar.gz

tituli-0.0.2/.claude/CLAUDE.md

@@ -0,0 +1,32 @@
+# tituli — agent & contributor guide
+
+Text in video: title cards, credits, captions + attribution, lower thirds, notes, calligrams. One `Layout` of placed `Run`s over `Plate`s on a `Frame`; Pillow rasterises, ffmpeg composites. See README for the API and the seam table.
+
+## Seams (current default → replacement)
+
+1. `Frame.from_image(avoid=)` — none → `burns.salient_box` / any `FacesDetector` (`[saliency]`)
+2. `render(engine=)` — `PillowEngine` → `tituli.shaping.HarfBuzzEngine` (`[shaping]`)
+3. `on_path(shape=)` — named presets → SVG `d` / `Path`
+4. `Frame(delivery=)` — none → `DELIVERY_RESERVED["youtube"]` (add a target, never a caller-side rule)
+5. `tituli.bodies` — plain dict → `annot://schema/text-overlay/v1` in lacing (`[lacing]`)
+
+Surfaces built: CLI (`python -m tituli` over `tituli.tools._dispatch_funcs`), shipped skill. MCP/HTTP would project the same list — never author a second one.
+
+## Invariants (tests pin these — change deliberately)
+
+- `import tituli` pulls no surface library and no optional dependency (`tests/test_surfaces.py`).
+- **Nothing is silently left off the film.** `label_for` returning `None` raises (`UNLABELLED` is the explicit choice); credits paginate and raise rather than truncate; `video.overlay` renders every overlay or raises *naming* the ones it cannot; equal-weight collisions raise.
+- One suppression rule for both scheduling paths: `_yield_to` — a heavier overlay takes the time it needs; the lighter keeps what is left if still readable. `schedule_labels` and `resolve` must agree (invariant test).
+- Pipeline order: wrap → measure → ink → scrim cut to the block → compose. A scrim sized before measuring is the bug this order exists to prevent.
+- Sizes are fractions of frame height; time is seconds; boxes crossing a boundary are normalised `(x, y, w, h)`.
+- Never burn text into stills a camera move will pan; composite onto the finished motion video.
+- A **tracked** style (`tracking != 0`) lays out one run per glyph (Pillow cannot track) — tests that count runs must use an untracked style.
+- No fonts ship in the package. Discovery + Pillow's embedded Aileron fallback.
+
+## Reviewing
+
+A description of a design and the code that implements it are different artifacts; reviewing the first says nothing about the second. This package's first review found three real defects that its (accurate) API report could not show — one of them the silent-drop the scheduler was built to prevent, reintroduced one layer down in `video.overlay`. Read the code path a consumer will actually take, end to end, before calling it done. (Same lesson as braidio's `nw#27` note: check the artifact, not the log.)
+
+## Neighbours
+
+`burns` (saliency, Ken Burns), `mixing` (SRT burn-in — not tituli), `braidio.video.credits_card` (plain-list credits: `Credits.from_lines`), `muvid` (lyric vocabulary; its `calligram` solver is `tituli.rain`), `an` (motion as structure; an#155 is the boundary), `illustration` (sourcing the stills captions describe).

tituli-0.0.2/.claude/skills/tituli/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: tituli
+description: Put tasteful text on video or stills with the `tituli` Python package — title cards, end credits from structured data, captions with a tiny source attribution that stay off the subject, lower thirds, editorial context notes, and calligrams / concrete poems (text along a circle, wave, SVG path, or falling like Apollinaire's "Il pleut"). Use when asked to "add credits", "add a title card", "caption this image", "label these stills", "put a name and role on screen", "add context cards", "overlay text on this video", "make a calligram", "text on a path", or when a film needs on-screen text that looks designed rather than debug-dumped. Owns placement (title-safe, subject-avoiding, YouTube subtitle band reserved), ink/scrim by contrast, wrapping and truncation, scheduling of captions against heavier cards, and ffmpeg compositing. Not for SRT subtitles (use `mixing`).
+license: MIT
+metadata:
+  audience: users
+---
+
+# tituli — text in video
+
+`pip install tituli` (Pillow only). Video output needs `ffmpeg` on PATH (only `overlay`/`fade`/`crop`; never `drawtext`). Extras: `[saliency]` (burns, subject avoidance), `[shaping]` (HarfBuzz), `[lacing]`, `[cli]`.
+
+## The one model
+
+Every call returns a `Layout`; `render(layout, frame)` gives an image; `tituli.video.*` puts images on footage. A `Frame` says how much is known about the picture:
+
+```python
+from tituli import Frame
+
+Frame.blank((1920, 1080))  # knows only its size -> white on a dark scrim
+Frame.blank((1920, 1080), color="#101014")  # solid colour -> ink by contrast, no scrim
+Frame.from_image(
+    "still.jpg", delivery="youtube"
+)  # samples pixels; keeps the subtitle band clear
+Frame.from_image("still.jpg", avoid=burns.salient_box)  # ...and keeps off the subject
+Frame.over(
+    ["f01.jpg", "f02.jpg", "f03.jpg"], avoid=burns.salient_box
+)  # the frames under a camera move; worst instant wins
+```
+
+## Recipes
+
+**Title card** (PNG, or MP4 with a duration):
+```python
+from tituli import Frame, title_card, render
+
+f = Frame.blank((1920, 1080), color="#101014")
+render(title_card("The Apple", "a concrete poem", kicker="Episode 3", frame=f), f).save(
+    "title.png"
+)
+# video: tituli.video.still(image, "title.mp4", duration=4)
+```
+
+**Caption + tiny attribution on a still** — text is wrapped and truncated for you; attribution is small on purpose:
+```python
+from tituli import Frame, caption, render
+
+f = Frame.from_image(
+    "still.jpg", delivery="youtube"
+)  # add avoid=burns.salient_box if burns is installed
+lay = caption(
+    "Angelica Schuyler Church", "John Trumbull, 1785 · public domain", frame=f
+)
+render(lay, f).save(
+    "captioned.png"
+)  # or render_overlay(lay, f.size) for a transparent PNG
+```
+
+**Lower third / context note**: `lower_third("Eliza Hamilton", "née Schuyler", frame=f)`; `note(["What Hamilton is", "Who Chernow is"], headline="Before we go on", frame=f)`.
+
+**Credits** — structured, never a wall of filenames, never truncated:
+```python
+from tituli import Credits, credits_cards, credits_crawl, credits_frame, render, Frame
+
+cr = Credits.from_dict(
+    {
+        "title": "The Apple",
+        "sections": [
+            {"heading": "Voices", "entries": [["Narrator", "T. Whalen"]]},
+            {"heading": "Images", "entries": ["Still Life — Cézanne — public domain"]},
+        ],
+        "closing": ["Made with tituli"],
+    }
+)
+f = credits_frame((1920, 1080))
+for i, card in enumerate(credits_cards(cr, frame=f)):
+    render(card, f).save(f"credits_{i}.png")
+lay, total = credits_crawl(
+    cr, frame=f
+)  # then tituli.video.crawl(render(lay, Frame.blank((1920, total), color=f.color)), "credits.mp4", size=(1920,1080), speed_px_s=97)
+```
+`Credits.from_lines(lines)` takes a plain list (braidio's `credits_card` shape).
+
+**Captions on a finished film** (composite onto the motion video, never into the stills):
+```python
+from tituli import Span, Label, UNLABELLED, schedule_labels, TimedOverlay, resolve, note
+from tituli.video import overlay
+f = Frame.blank((1920, 1080)).with_delivery("youtube")
+cards = [TimedOverlay(note([...], headline="...", frame=f), 12.0, 18.0, slot="top-left", weight=2)]
+spans = [Span(start, end, key=still_id) for ...]                  # your cut
+labels = schedule_labels(spans, lambda s: Label(text, attribution) if known else UNLABELLED, suppressed_by=cards)
+overlay("film.mp4", resolve([*cards, *labels]), "film_captioned.mp4")   # renders Label payloads itself; raises naming anything it can't
+```
+Rules built in: label on first appearance, again only after 150 s, truncated (not dropped) against a heavier card, and a suppressed label is not counted as shown. Returning `None` from `label_for` raises — say `UNLABELLED` when a still is deliberately unlabelled.
+
+**Calligram**: `on_path(text, shape="circle"|"wave"|"arc"|"M 0 0 C ..."|Path, frame=f, upright=False)`; `rain(lines, frame=Frame.blank((1080, 1920), color="#f4f1e8"))` (portrait); `in_shape(text, mask_image, frame=f)`. A glyph-by-glyph reveal: `lay.staggered(step=0.05, ramp=0.2)` → `tituli.video.frames_to_video(frames(lay, f, duration=6), "out.mp4", size=f.size)`.
+
+## CLI
+
+`python -m tituli title_card "Title" "sub" --background "#101014" --out t.png` · `python -m tituli caption still.jpg "text" "source" --out c.png` · `python -m tituli credits spec.json --mode crawl --out credits.mp4` · `python -m tituli calligram "text" --shape circle --out c.png` · `python -m tituli overlay_video film.mp4 overlays.json --out out.mp4` · `python -m tituli fonts Helvetica`.
+
+## Taste rules the defaults already follow
+
+Title-safe 90 %; WCAG 4.5:1 target; sans working set (Helvetica Neue → Inter → … → DejaVu Sans) with Pillow's Aileron as the last fallback; ≥ 36 px-equivalent at 1080p for anything meant to be read; attribution ~22 px and 85 % opacity; credits hold ≥ 3 s / crawl ≈ 97 px/s; reveals 0.4 s; corner-falloff scrim cut to the text block, only when contrast or busyness demands it. Sizes are fractions of frame height, so the same call is right at 720p and 4K. Don't override these unless asked.

tituli-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

tituli-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Transport (NAMED, legacy): explicitly passes only the secrets
+    # listed below (PYPI_PASSWORD + those declared in
+    # [tool.wads.ci.env]). Every name must be in the frozen wads
+    # superset (wads/ci_secrets.py) or GitHub rejects the workflow
+    # at parse time. The default JSON transport has no such limit;
+    # regenerate with `wads-migrate ci-to-stub` to switch.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

tituli-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

tituli-0.0.2/LICENSE

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

tituli-0.0.2/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: tituli
+Version: 0.0.2
+Summary: Text in video: title cards, credits, captions and calligrams with tasteful defaults
+Project-URL: Homepage, https://github.com/thorwhalen/tituli
+Project-URL: Repository, https://github.com/thorwhalen/tituli
+Project-URL: Documentation, https://thorwhalen.github.io/tituli
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calligram,captions,credits,ffmpeg,kinetic-typography,pillow,title-card,typography,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Text Processing :: Fonts
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.1
+Provides-Extra: cli
+Requires-Dist: cw<0.2,>=0.1.1; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: lacing
+Requires-Dist: lacing; extra == 'lacing'
+Provides-Extra: saliency
+Requires-Dist: burns>=0.0.11; extra == 'saliency'
+Provides-Extra: shaping
+Requires-Dist: freetype-py; extra == 'shaping'
+Requires-Dist: uharfbuzz; extra == 'shaping'
+Description-Content-Type: text/markdown
+
+# tituli
+
+Text in video, with tasteful defaults: **title cards**, **credits**, **captions with a tiny attribution**, **lower thirds**, **context notes**, and **calligrams** — from one layout model, rendered with Pillow, composited with ffmpeg.
+
+```bash
+pip install tituli            # Pillow only; ffmpeg on PATH for video output
+```
+
+```python
+from tituli import Frame, title_card, caption, render
+
+frame = Frame.blank((1920, 1080), color="#101014")
+render(
+    title_card("Il pleut", "Apollinaire, 1918", kicker="Episode 3", frame=frame), frame
+).save("title.png")
+
+frame = Frame.from_image(
+    "still.jpg", delivery="youtube"
+)  # add avoid=burns.salient_box to keep off the subject
+render(
+    caption("Eliza Hamilton", "Ralph Earl, 1787 · public domain", frame=frame), frame
+).save("captioned.png")
+```
+
+Or from the shell (`pip install tituli[cli]`):
+
+```bash
+python -m tituli title_card "The Apple" "a concrete poem" --background "#101014" --out title.png
+python -m tituli credits credits.json --mode crawl --out credits.mp4
+python -m tituli caption still.jpg "Angelica Schuyler Church" "John Trumbull, 1785" --out cap.png
+python -m tituli calligram "round and round the apple goes" --shape circle --out calligram.png
+```
+
+## One model
+
+Every use case fills a `Layout` — placed `Run`s (a string, a baseline origin, an angle, a resolved face, a colour) over `Plate`s (scrims, rules) — on a `Frame`. A block of prose is one run per line; a calligram is one run per glyph. The humble cases are the degenerate calligram. `render(layout, frame)` gives an RGBA overlay (frame without a background) or an RGB composite; `tituli.video` puts either onto footage.
+
+### The frame-knowledge ladder
+
+"A video that *is* text" and "text over a video" are the same problem; what differs is **how much the layout engine knows about the picture**. `Frame` carries all four rungs, every one optional, and the engine *asks* rather than branching:
+
+| rung | the Frame knows | so the engine can |
+|---|---|---|
+| a | its size | place by anchor in the title-safe area; assume the worst → white on a dark scrim |
+| b | a solid colour (`Frame.blank(size, color=…)`) | pick ink by WCAG contrast; no scrim |
+| c | the pixels (`Frame.from_image(still)` or `Frame.over(stills)`) | sample luminance under the candidate box; ink by contrast; scrim only if the patch is mid-toned or busy |
+| d | c + regions to keep clear (`avoid=`) | rank the nine anchor positions by how little they cover the subject |
+
+`Frame.over(stills)` samples every frame a camera move will pass through and reports the *worst instant*, so a scrim over a Ken Burns pan is as light as the whole window allows. `delivery="youtube"` hard-excludes the bottom 22 % (subtitle track + control bar) from placement — modelled as named reserved zones, not a rule to remember.
+
+### Pipeline order (it matters)
+
+**shape/wrap → measure → decide ink → cut the scrim to the measured block → compose.** Text whose length you don't control (a licence template pasted into an artist field) is wrapped to a width fraction and hard-truncated with an ellipsis *inside the package*. And never burn text into stills that a camera move will pan and zoom — composite onto the finished motion video (`tituli.video.overlay`).
+
+## What you get
+
+| call | what it makes |
+|---|---|
+| `title_card(title, subtitle, kicker=…, frame=…)` | opening card; title fitted (shrunk, never clipped) to 80 % of the safe width |
+| `caption(text, attribution, frame=…)` | museum label: what's on screen + a small credit line; subject-avoiding; corner-falloff scrim |
+| `lower_third(name, role, frame=…)` | who is speaking |
+| `note(lines, headline=…, frame=…)` | editorial context: a headline over equal-weight lines ("what *Hamilton* is") |
+| `intertitle(text, frame=…)` | silent-film card, serif italic |
+| `Credits.from_dict(…)` → `credits_cards` / `credits_crawl` | structured roll: sections, role/name pairs on a gutter, tracked small-cap headings; **never truncates** (paginates, or raises if you cap the cards) |
+| `on_path(text, shape="circle"\|"wave"\|SVG d\|Path)` | glyphs riding any path, rotated to the tangent or kept upright |
+| `rain(lines)` | Apollinaire's *Il pleut*: upright letters stepping down fanning streaks (the 1918 measurements as defaults) |
+| `in_shape(text, mask)` | prose poured into a silhouette |
+| `schedule_labels(spans, label_for, suppressed_by=cards)` | one label per shot with first-appearance, repeat-gap and suppression rules **inside** the loop |
+| `tituli.video.still / overlay / crawl / frames_to_video` | ffmpeg output; only `overlay`/`fade`/`crop` needed — never `drawtext`/`libass` |
+
+All sizes are fractions of frame height, so a style reads the same at 720p and 4K. The presets (`tituli.style`) are one type ramp shared by overlays and the end card, so a film is one design.
+
+### Scheduling: tituli owns it, or you do — no middle
+
+`schedule_labels` derives labels from a cut with the three rules built in. A label suppressed by a heavier overlay is *truncated* to the time before it, kept if what remains is readable, and otherwise skipped **without being recorded as shown** — so the portrait a cold viewer most needs named still gets labelled the next time it appears. `resolve()` applies the identical rule to hand-built overlays (one overlay per slot at a time; equal weights colliding raise). `label_for` returns a `Label` or the explicit `UNLABELLED`; `None` raises — "no caption" is a stated choice, never the cheap default, because an unlabelled still beside a labelled one is an implicit claim.
+
+## Seams
+
+| # | seam | v1 default (no new dependency) | replacement you can point at |
+|---|---|---|---|
+| 1 | subject avoidance — `Frame.from_image(avoid=)` | none (boxes you pass) | `burns.salient_box`, any `burns.FacesDetector` (`pip install tituli[saliency]`) |
+| 2 | the rasteriser — `render(engine=)` | `PillowEngine` (FreeType via Pillow, bitmap rotation) | `HarfBuzzEngine` — shaping + outline transforms (`pip install tituli[shaping]`) |
+| 3 | the shape — `on_path(shape=)` | named presets | an SVG `d` string or any `Path` (a traced outline) |
+| 4 | delivery zones — `Frame(delivery=)` | none | `DELIVERY_RESERVED["youtube"]`; add a target, not a rule |
+| 5 | the graph — `tituli.bodies` | plain dict from `body_for()` | `annot://schema/text-overlay/v1` registered with lacing (`pip install tituli[lacing]`) |
+
+Surface for v1: **CLI** (`python -m tituli`, `cw.dispatch` over `tituli.tools._dispatch_funcs`). MCP/HTTP would project the same list. Agent skill shipped (`tituli/data/skills/tituli`).
+NOT seams: the scrim design, the anchor grid, the type ramp, the ffmpeg encode args — written directly, on purpose.
+
+## Where this sits in the fleet
+
+- **`an` — [thorwhalen/an#155](https://github.com/thorwhalen/an/issues/155)** asked whether per-glyph text belongs in `an` or a sibling package. tituli is the sibling: it owns *typesetting for video* (shaping, metrics, wrap, contrast, safe area, reserved zones, path placement, the title/credits/caption conventions) and emits placed glyphs (`Run` with `unit=glyph|word|line` and an `index`). `an` keeps *motion as structure* and can consume those placements as its option-2 "svg_sprite per glyph, converted at compile time". tituli's own time envelope is deliberately small (fades, stagger, crawl).
+- **`muvid`** keeps its lyric-video vocabulary and ASS burn-in; its `calligram` archetype's streak solver is `tituli.rain`, generalised over real glyph metrics and any frame, and `text_on_path` / `concrete_page` ceilings (a hardcoded sine; centred rows only; a 0.62-em character estimate) are what `on_path` / `in_shape` / real `Face.length` remove.
+- **`braidio.video.credits_card`** is the plain-list case: `Credits.from_lines(lines)` → `credits_cards`, same never-truncate rule, designed type.
+- **`burns`** owns saliency and the Ken Burns move; tituli only consumes `salient_box`.
+- **`mixing`** owns subtitle (SRT) burn-in; tituli does not do subtitles.
+- The Hamilton film's `overlays.py` (captions + context cards → transparent PNG → one ffmpeg `overlay` chain) was the seed for `caption`, `note`, `schedule_labels` and `video.overlay`, with its lessons kept: per-input `-loop 1 -t`, fade on the still's own clock, `-c:a copy`, the corner scrim cut to the block, and the suppression check inside the scheduler.
+
+### Linked artifacts (lacing)
+
+A caption is an annotation **on the image**: `reference = MediaRef(asset_id=<image hash>)`, body `annot://schema/text-overlay/v1` (`tituli.bodies.body_for(layout, frame, text=…)` builds it; `register()` registers it, lazily, only with `tituli[lacing]`). For the (image, audio-segment) **pair** no N-ary reference is invented: as `artful.PanelBody` does, the pair annotation's `reference` is the interval on the segment and `provenance.was_derived_from` lists both the image `asset_id` and the caption annotation id. The body records `unlabelled=True` when a still was deliberately left without a label.
+
+## Style defaults (why they look right)
+
+Title-safe 90 % (SMPTE ST 2046-1); WCAG 4.5:1 aimed for, 3:1 floor; sans working set Helvetica Neue → Inter → Helvetica → Avenir Next → Roboto → … → DejaVu Sans; ≥ 36 px-equivalent at 1080p for anything meant to be read; credits cards hold ≥ 3 s, crawls ≈ 97 px/s at 1080p; reveals 300–500 ms. Sources and the full rationale: [`misc/docs/style.md`](misc/docs/style.md). No fonts ship in the package — system discovery with Pillow's embedded Aileron as the fallback, so a bare CI box still renders.
+
+## Optional extras
+
+| extra | adds |
+|---|---|
+| `shaping` | `uharfbuzz` + `freetype-py`: ligatures, kerning, complex scripts, outline rotation |
+| `saliency` | `burns` for `avoid=salient_box` |
+| `lacing` | the body schema |
+| `cli` | `cw` for `python -m tituli` |
+
+## Skills
+
+`gh skill install thorwhalen/tituli tituli` — or, after `pip install`, link `tituli/data/skills/tituli` into your agent's skills directory.

tituli-0.0.2/README.md

@@ -0,0 +1,118 @@
+# tituli
+
+Text in video, with tasteful defaults: **title cards**, **credits**, **captions with a tiny attribution**, **lower thirds**, **context notes**, and **calligrams** — from one layout model, rendered with Pillow, composited with ffmpeg.
+
+```bash
+pip install tituli            # Pillow only; ffmpeg on PATH for video output
+```
+
+```python
+from tituli import Frame, title_card, caption, render
+
+frame = Frame.blank((1920, 1080), color="#101014")
+render(
+    title_card("Il pleut", "Apollinaire, 1918", kicker="Episode 3", frame=frame), frame
+).save("title.png")
+
+frame = Frame.from_image(
+    "still.jpg", delivery="youtube"
+)  # add avoid=burns.salient_box to keep off the subject
+render(
+    caption("Eliza Hamilton", "Ralph Earl, 1787 · public domain", frame=frame), frame
+).save("captioned.png")
+```
+
+Or from the shell (`pip install tituli[cli]`):
+
+```bash
+python -m tituli title_card "The Apple" "a concrete poem" --background "#101014" --out title.png
+python -m tituli credits credits.json --mode crawl --out credits.mp4
+python -m tituli caption still.jpg "Angelica Schuyler Church" "John Trumbull, 1785" --out cap.png
+python -m tituli calligram "round and round the apple goes" --shape circle --out calligram.png
+```
+
+## One model
+
+Every use case fills a `Layout` — placed `Run`s (a string, a baseline origin, an angle, a resolved face, a colour) over `Plate`s (scrims, rules) — on a `Frame`. A block of prose is one run per line; a calligram is one run per glyph. The humble cases are the degenerate calligram. `render(layout, frame)` gives an RGBA overlay (frame without a background) or an RGB composite; `tituli.video` puts either onto footage.
+
+### The frame-knowledge ladder
+
+"A video that *is* text" and "text over a video" are the same problem; what differs is **how much the layout engine knows about the picture**. `Frame` carries all four rungs, every one optional, and the engine *asks* rather than branching:
+
+| rung | the Frame knows | so the engine can |
+|---|---|---|
+| a | its size | place by anchor in the title-safe area; assume the worst → white on a dark scrim |
+| b | a solid colour (`Frame.blank(size, color=…)`) | pick ink by WCAG contrast; no scrim |
+| c | the pixels (`Frame.from_image(still)` or `Frame.over(stills)`) | sample luminance under the candidate box; ink by contrast; scrim only if the patch is mid-toned or busy |
+| d | c + regions to keep clear (`avoid=`) | rank the nine anchor positions by how little they cover the subject |
+
+`Frame.over(stills)` samples every frame a camera move will pass through and reports the *worst instant*, so a scrim over a Ken Burns pan is as light as the whole window allows. `delivery="youtube"` hard-excludes the bottom 22 % (subtitle track + control bar) from placement — modelled as named reserved zones, not a rule to remember.
+
+### Pipeline order (it matters)
+
+**shape/wrap → measure → decide ink → cut the scrim to the measured block → compose.** Text whose length you don't control (a licence template pasted into an artist field) is wrapped to a width fraction and hard-truncated with an ellipsis *inside the package*. And never burn text into stills that a camera move will pan and zoom — composite onto the finished motion video (`tituli.video.overlay`).
+
+## What you get
+
+| call | what it makes |
+|---|---|
+| `title_card(title, subtitle, kicker=…, frame=…)` | opening card; title fitted (shrunk, never clipped) to 80 % of the safe width |
+| `caption(text, attribution, frame=…)` | museum label: what's on screen + a small credit line; subject-avoiding; corner-falloff scrim |
+| `lower_third(name, role, frame=…)` | who is speaking |
+| `note(lines, headline=…, frame=…)` | editorial context: a headline over equal-weight lines ("what *Hamilton* is") |
+| `intertitle(text, frame=…)` | silent-film card, serif italic |
+| `Credits.from_dict(…)` → `credits_cards` / `credits_crawl` | structured roll: sections, role/name pairs on a gutter, tracked small-cap headings; **never truncates** (paginates, or raises if you cap the cards) |
+| `on_path(text, shape="circle"\|"wave"\|SVG d\|Path)` | glyphs riding any path, rotated to the tangent or kept upright |
+| `rain(lines)` | Apollinaire's *Il pleut*: upright letters stepping down fanning streaks (the 1918 measurements as defaults) |
+| `in_shape(text, mask)` | prose poured into a silhouette |
+| `schedule_labels(spans, label_for, suppressed_by=cards)` | one label per shot with first-appearance, repeat-gap and suppression rules **inside** the loop |
+| `tituli.video.still / overlay / crawl / frames_to_video` | ffmpeg output; only `overlay`/`fade`/`crop` needed — never `drawtext`/`libass` |
+
+All sizes are fractions of frame height, so a style reads the same at 720p and 4K. The presets (`tituli.style`) are one type ramp shared by overlays and the end card, so a film is one design.
+
+### Scheduling: tituli owns it, or you do — no middle
+
+`schedule_labels` derives labels from a cut with the three rules built in. A label suppressed by a heavier overlay is *truncated* to the time before it, kept if what remains is readable, and otherwise skipped **without being recorded as shown** — so the portrait a cold viewer most needs named still gets labelled the next time it appears. `resolve()` applies the identical rule to hand-built overlays (one overlay per slot at a time; equal weights colliding raise). `label_for` returns a `Label` or the explicit `UNLABELLED`; `None` raises — "no caption" is a stated choice, never the cheap default, because an unlabelled still beside a labelled one is an implicit claim.
+
+## Seams
+
+| # | seam | v1 default (no new dependency) | replacement you can point at |
+|---|---|---|---|
+| 1 | subject avoidance — `Frame.from_image(avoid=)` | none (boxes you pass) | `burns.salient_box`, any `burns.FacesDetector` (`pip install tituli[saliency]`) |
+| 2 | the rasteriser — `render(engine=)` | `PillowEngine` (FreeType via Pillow, bitmap rotation) | `HarfBuzzEngine` — shaping + outline transforms (`pip install tituli[shaping]`) |
+| 3 | the shape — `on_path(shape=)` | named presets | an SVG `d` string or any `Path` (a traced outline) |
+| 4 | delivery zones — `Frame(delivery=)` | none | `DELIVERY_RESERVED["youtube"]`; add a target, not a rule |
+| 5 | the graph — `tituli.bodies` | plain dict from `body_for()` | `annot://schema/text-overlay/v1` registered with lacing (`pip install tituli[lacing]`) |
+
+Surface for v1: **CLI** (`python -m tituli`, `cw.dispatch` over `tituli.tools._dispatch_funcs`). MCP/HTTP would project the same list. Agent skill shipped (`tituli/data/skills/tituli`).
+NOT seams: the scrim design, the anchor grid, the type ramp, the ffmpeg encode args — written directly, on purpose.
+
+## Where this sits in the fleet
+
+- **`an` — [thorwhalen/an#155](https://github.com/thorwhalen/an/issues/155)** asked whether per-glyph text belongs in `an` or a sibling package. tituli is the sibling: it owns *typesetting for video* (shaping, metrics, wrap, contrast, safe area, reserved zones, path placement, the title/credits/caption conventions) and emits placed glyphs (`Run` with `unit=glyph|word|line` and an `index`). `an` keeps *motion as structure* and can consume those placements as its option-2 "svg_sprite per glyph, converted at compile time". tituli's own time envelope is deliberately small (fades, stagger, crawl).
+- **`muvid`** keeps its lyric-video vocabulary and ASS burn-in; its `calligram` archetype's streak solver is `tituli.rain`, generalised over real glyph metrics and any frame, and `text_on_path` / `concrete_page` ceilings (a hardcoded sine; centred rows only; a 0.62-em character estimate) are what `on_path` / `in_shape` / real `Face.length` remove.
+- **`braidio.video.credits_card`** is the plain-list case: `Credits.from_lines(lines)` → `credits_cards`, same never-truncate rule, designed type.
+- **`burns`** owns saliency and the Ken Burns move; tituli only consumes `salient_box`.
+- **`mixing`** owns subtitle (SRT) burn-in; tituli does not do subtitles.
+- The Hamilton film's `overlays.py` (captions + context cards → transparent PNG → one ffmpeg `overlay` chain) was the seed for `caption`, `note`, `schedule_labels` and `video.overlay`, with its lessons kept: per-input `-loop 1 -t`, fade on the still's own clock, `-c:a copy`, the corner scrim cut to the block, and the suppression check inside the scheduler.
+
+### Linked artifacts (lacing)
+
+A caption is an annotation **on the image**: `reference = MediaRef(asset_id=<image hash>)`, body `annot://schema/text-overlay/v1` (`tituli.bodies.body_for(layout, frame, text=…)` builds it; `register()` registers it, lazily, only with `tituli[lacing]`). For the (image, audio-segment) **pair** no N-ary reference is invented: as `artful.PanelBody` does, the pair annotation's `reference` is the interval on the segment and `provenance.was_derived_from` lists both the image `asset_id` and the caption annotation id. The body records `unlabelled=True` when a still was deliberately left without a label.
+
+## Style defaults (why they look right)
+
+Title-safe 90 % (SMPTE ST 2046-1); WCAG 4.5:1 aimed for, 3:1 floor; sans working set Helvetica Neue → Inter → Helvetica → Avenir Next → Roboto → … → DejaVu Sans; ≥ 36 px-equivalent at 1080p for anything meant to be read; credits cards hold ≥ 3 s, crawls ≈ 97 px/s at 1080p; reveals 300–500 ms. Sources and the full rationale: [`misc/docs/style.md`](misc/docs/style.md). No fonts ship in the package — system discovery with Pillow's embedded Aileron as the fallback, so a bare CI box still renders.
+
+## Optional extras
+
+| extra | adds |
+|---|---|
+| `shaping` | `uharfbuzz` + `freetype-py`: ligatures, kerning, complex scripts, outline rotation |
+| `saliency` | `burns` for `avoid=salient_box` |
+| `lacing` | the body schema |
+| `cli` | `cw` for `python -m tituli` |
+
+## Skills
+
+`gh skill install thorwhalen/tituli tituli` — or, after `pip install`, link `tituli/data/skills/tituli` into your agent's skills directory.

tituli-0.0.2/misc/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2026-09-14 — 0.0.1
+
+First release. Frame-knowledge ladder (`Frame`), `Layout`/`Run`/`Plate` model, Pillow renderer with rotated glyph tiles, optional HarfBuzz+FreeType engine, title card / caption / lower third / note / intertitle, structured credits (cards + crawl, never truncating), calligrams (`on_path`, `rain`, `in_shape`), scheduler with first-appearance / repeat-gap / suppression inside the loop, ffmpeg output (`still`, `overlay`, `crawl`, `frames_to_video`), CLI via `cw`, lacing body `annot://schema/text-overlay/v1`, shipped `tituli` skill.