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.

pip install tituli            # Pillow only; ffmpeg on PATH for video output

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]):

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 Runs (a string, a baseline origin, an angle, a resolved face, a colour) over Plates (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:

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 → fit → measure → decide ink → cut the scrim to the measured block → compose. Your words are set complete or not at all: caption, lower_third and note shrink the type until it fits and raise TextDoesNotFit rather than ship a cut label — because 1981 · Centr… is not a shortened label, it is a wrong one, and only the caller can choose between shorter wording, more lines and no overlay. Text whose length you genuinely don't control (a licence template pasted into an artist field) still truncates, asked for by name: on_overflow="truncate". 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

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

A reserved zone binds every anchor, not just anchor="auto": with delivery="youtube" a block that would land in the subtitle band is slid the shortest way clear of it, keeping the anchor you named. anchor="bottom-left" therefore means "as low as the platform allows".

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

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 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 consumes those placements as its option-2 "svg_sprite per glyph, converted at compile time": run_outline turns each run into SVG path data, so an's runtime never learns what text is. 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. No fonts ship in the package — system discovery with Pillow's embedded Aileron as the fallback, so a bare CI box still renders. When output must not depend on what is installed, ask for family=(EMBEDDED,): it never scans the system, and face_digest(face) (sha256 of the font's bytes) is the identity to record.

Optional extras

Skills

gh skill install thorwhalen/tituli tituli — or, after pip install, link tituli/data/skills/tituli into your agent's skills directory.