tituli.tools

The SSOT of dispatchable operations: flat, JSON-able in, JSON-able out.

These are the functions every surface projects: the CLI (python -m tituli) today, an MCP server or HTTP route tomorrow, an agent skill in prose. Nothing here imports a surface library; each function takes paths and strings, writes a file, and returns a dict describing what it wrote.

>>> sorted(f.__name__ for f in _dispatch_funcs)
['calligram', 'caption', 'credits', 'fonts', 'lower_third', 'overlay_video', 'title_card']

Functions

calligram(text, *[, out, shape, size, ...])	Lay text along a shape (circle, wave, arc, an SVG path, rain).
caption(image, text[, attribution, out, ...])	Put a museum-label caption and a tiny attribution on image.
credits(spec, *[, out, mode, size, speed, ...])	Render credits from a JSON spec file (or JSON string) to out.
fonts([query])	List installed font families (optionally filtered by substring).
lower_third(name[, role, out, background, ...])	A name + role block, bottom-left, as a transparent overlay (or on a picture).
overlay_video(video, overlays, *[, out, ...])	Composite captions/lower thirds/images onto a finished video in one ffmpeg pass.
title_card(title[, subtitle, out, ...])	Render a title card to out (PNG, or MP4 when duration is given).

tituli.tools.calligram(text, *, out='calligram.png', shape='wave', size=None, background='#f4f1e8', upright=False, mask=None, reveal=None)

Lay text along a shape (circle, wave, arc, an SVG path, rain).

shape="rain" is Apollinaire’s Il pleut (lines become streaks; give it a portrait size). mask (an image path, light = inside) pours the text into a silhouette instead. reveal (seconds) writes an MP4 with a glyph-by-glyph reveal rather than a PNG.

Return type:

dict

tituli.tools.caption(image, text, attribution='', *, out='captioned.png', anchor='auto', avoid='saliency', delivery='youtube', size=None, overlay_only=False)

Put a museum-label caption and a tiny attribution on image.

Placement avoids the subject (avoid="saliency" uses burns when installed, otherwise nothing is avoided) and the delivery target’s reserved zones. overlay_only writes a transparent PNG to composite onto motion video instead of the flattened picture.

Return type:

dict

tituli.tools.credits(spec, *, out='credits.mp4', mode='crawl', size=None, speed=None, hold=None, background=None, audio=None)

Render credits from a JSON spec file (or JSON string) to out.

Spec: {"title": ..., "sections": [{"heading": ..., "entries": [["Role", "Name"], "Name", ...]}], "closing": [...]} — or a plain JSON list of lines. mode is "crawl" (one MP4) or "cards" (PNG per card, or one MP4 when out ends in .mp4). Never truncates.

Return type:

dict

tituli.tools.fonts(query='')

List installed font families (optionally filtered by substring).

Return type:

dict

tituli.tools.lower_third(name, role='', *, out='lower_third.png', background=None, size=None, delivery='youtube')

A name + role block, bottom-left, as a transparent overlay (or on a picture).

Return type:

dict

tituli.tools.overlay_video(video, overlays, *, out='overlaid.mp4', delivery='youtube', pad_start=0.0)

Composite captions/lower thirds/images onto a finished video in one ffmpeg pass.

overlays is a JSON file/string: a list of {"start", "end", "text", "attribution"?, "kind"?: "caption"|"lower_third", "role"?, "anchor"?} or {"start", "end", "image", "fade_in"?, "fade_out"?} (a frame-sized PNG, e.g. a title page; it occupies its own slot and suppresses no caption — time captions after it). Text is laid out against the video’s frame size; the picture under each overlay is not sampled (pass a still through caption for that). pad_start seconds are added at the head (first frame held, audio delayed); overlay times are on the padded timeline.

Return type:

dict

tituli.tools.title_card(title, subtitle='', *, out='title.png', background=None, size=None, kicker='', anchor='center', avoid=None, duration=None)

Render a title card to out (PNG, or MP4 when duration is given).

background is a colour (#101014), an image path, or nothing (a transparent overlay). anchor is a grid position; avoid is "saliency" or "x,y,w,h" to keep the title off the subject.

Return type:

dict