tituli 0.0.2__py3-none-any.whl

tituli/__init__.py

@@ -0,0 +1,127 @@
+"""tituli — text in video: title cards, credits, captions and calligrams.
+
+One model underneath: a :class:`Layout` of placed :class:`Run`s on a
+:class:`Frame` that knows as much (or as little) about the picture as you tell
+it. Everything else is a convenience over that.
+
+Quick start::
+
+    from tituli import Frame, title_card, caption, credits_crawl, on_path, render
+
+    frame = Frame.blank((1920, 1080), color="#101014")
+    render(title_card("Il pleut", "Apollinaire, 1918", frame=frame), frame).save("title.png")
+
+    frame = Frame.from_image("still.jpg", delivery="youtube")   # add avoid=burns.salient_box
+    render(caption("Eliza Hamilton", "Ralph Earl, 1787 · public domain", frame=frame), frame).save("cap.png")
+
+Optional layers, none imported here: ``tituli[shaping]`` (HarfBuzz engine),
+``tituli[saliency]`` (``burns`` subject avoidance), ``tituli[lacing]`` (the
+text-overlay body schema), ``tituli[cli]`` (``python -m tituli``).
+"""
+
+from tituli.calligram import in_shape, on_path, rain, resolve_shape
+from tituli.color import contrast_ratio, ink_for, parse_color
+from tituli.compose import (
+    caption,
+    decide_ink,
+    intertitle,
+    lower_third,
+    note,
+    title_card,
+    truncate,
+)
+from tituli.credits import (
+    Credits,
+    CreditsStyle,
+    Entry,
+    Section,
+    credits_cards,
+    credits_crawl,
+    credits_frame,
+)
+from tituli.fonts import Face, families, find_font, resolve_face
+from tituli.frame import DELIVERY_RESERVED, Frame, cover_fit, reserved_zones
+from tituli.geometry import ANCHORS, TITLE_SAFE, Box, Path, safe_area
+from tituli.layout import Layout, Plate, Run, along_path, block, fit_size, measure, wrap
+from tituli.render import frames, make_engine, render, render_overlay
+from tituli.schedule import (
+    UNLABELLED,
+    Label,
+    Span,
+    TimedOverlay,
+    resolve,
+    schedule_labels,
+)
+from tituli.style import (
+    ATTRIBUTION,
+    CALLIGRAM,
+    CAPTION,
+    CREDITS_NAME,
+    KICKER,
+    SUBTITLE,
+    TITLE,
+    TextStyle,
+)
+
+__all__ = [
+    "Frame",
+    "Layout",
+    "Run",
+    "Plate",
+    "Box",
+    "Path",
+    "TextStyle",
+    "Face",
+    "title_card",
+    "caption",
+    "lower_third",
+    "note",
+    "intertitle",
+    "truncate",
+    "decide_ink",
+    "Credits",
+    "CreditsStyle",
+    "Entry",
+    "Section",
+    "credits_cards",
+    "credits_crawl",
+    "credits_frame",
+    "on_path",
+    "rain",
+    "in_shape",
+    "resolve_shape",
+    "block",
+    "along_path",
+    "wrap",
+    "measure",
+    "fit_size",
+    "render",
+    "render_overlay",
+    "frames",
+    "make_engine",
+    "Label",
+    "Span",
+    "TimedOverlay",
+    "UNLABELLED",
+    "schedule_labels",
+    "resolve",
+    "families",
+    "find_font",
+    "resolve_face",
+    "contrast_ratio",
+    "ink_for",
+    "parse_color",
+    "safe_area",
+    "ANCHORS",
+    "TITLE_SAFE",
+    "DELIVERY_RESERVED",
+    "reserved_zones",
+    "cover_fit",
+    "TITLE",
+    "SUBTITLE",
+    "KICKER",
+    "CAPTION",
+    "ATTRIBUTION",
+    "CREDITS_NAME",
+    "CALLIGRAM",
+]

tituli/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m tituli`` — the CLI over :data:`tituli.tools._dispatch_funcs`."""
+
+from tituli.tools import _dispatch_funcs
+
+if __name__ == "__main__":
+    import cw
+
+    raise SystemExit(cw.dispatch(_dispatch_funcs))

tituli/bodies.py

@@ -0,0 +1,119 @@
+"""A lacing body schema for a rendered caption (``pip install tituli[lacing]``).
+
+URI: ``annot://schema/text-overlay/v1``. A caption is an annotation **on the
+image** (``MediaRef(asset_id=<image hash>)``), and when that image sits under an
+audio segment the pair is expressed the way ``artful.PanelBody`` does it: the
+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. No N-ary reference type is invented; the timing lives
+on the reference, not in this body.
+
+Registration is lazy and idempotent (:func:`register`), so ``import tituli``
+never touches lacing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+TEXT_OVERLAY_V1 = "annot://schema/text-overlay/v1"
+_REGISTERED = False
+
+
+def _model():
+    from pydantic import BaseModel, Field
+
+    class TextOverlayBodyV1(BaseModel):
+        """What was written over the picture, and how. Placement is normalised."""
+
+        model_config = {"frozen": True, "extra": "forbid"}
+
+        text: str = Field(
+            ..., description="The caption as displayed (after wrapping/truncation)."
+        )
+        attribution: str = Field(
+            "", description="The small credit line under the caption, if any."
+        )
+        kind: str = Field(
+            "caption",
+            description="Free string: 'caption', 'lower_third', 'title', 'intertitle', ...",
+        )
+        anchor: str = Field(
+            "", description="Grid position the block was placed at ('top-left', ...)."
+        )
+        box: tuple[float, float, float, float] | None = Field(
+            None, description="Normalised (x, y, w, h) of the text block in the frame."
+        )
+        ink: str | None = Field(None, description="Ink colour as #rrggbb, if recorded.")
+        scrim: bool | None = Field(
+            None, description="Whether a scrim was drawn under the text."
+        )
+        reason: str | None = Field(
+            None, description="The ink/scrim decision the frame's knowledge led to."
+        )
+        style: dict[str, Any] | None = Field(
+            None, description="The TextStyle fields used, for re-rendering."
+        )
+        unlabelled: bool = Field(
+            False,
+            description="True when the still was deliberately shown without a label (an explicit choice, not an omission).",
+        )
+        overlay_asset_id: str | None = Field(
+            None, description="asset_id of the rendered transparent PNG, if stored."
+        )
+
+    return TextOverlayBodyV1
+
+
+def register() -> str:
+    """Register the schema with lacing (once). Returns the URI."""
+    global _REGISTERED
+    if _REGISTERED:
+        return TEXT_OVERLAY_V1
+    from lacing import register_body_schema
+
+    register_body_schema(TEXT_OVERLAY_V1, _model())
+    _REGISTERED = True
+    return TEXT_OVERLAY_V1
+
+
+def body_for(
+    layout,
+    frame,
+    *,
+    text: str,
+    attribution: str = "",
+    kind: str = "caption",
+    unlabelled: bool = False,
+) -> dict:
+    """The body dict for a rendered layout — plain data, no lacing needed.
+
+    >>> from tituli.frame import Frame
+    >>> from tituli.compose import caption
+    >>> f = Frame.blank((1920, 1080))
+    >>> b = body_for(caption("A still", "PD", frame=f), f, text="A still", attribution="PD")
+    >>> b["kind"], b["anchor"], len(b["box"])
+    ('caption', 'bottom-left', 4)
+    """
+    bb = layout.bbox()
+    ink = None
+    if layout.runs:
+        r, g, b, _ = layout.runs[0].color
+        ink = f"#{r:02x}{g:02x}{b:02x}"
+    return {
+        "text": text,
+        "attribution": attribution,
+        "kind": kind,
+        "anchor": str(layout.meta.get("anchor", "")),
+        "box": tuple(round(v, 4) for v in bb.to_norm(frame.width, frame.height)),
+        "ink": ink,
+        "scrim": any(p.kind != "box" or p.color[3] < 255 for p in layout.plates)
+        or None,
+        "reason": layout.meta.get("ink"),
+        "style": None,
+        "unlabelled": unlabelled,
+        "overlay_asset_id": None,
+    }
+
+
+__all__ = ["TEXT_OVERLAY_V1", "register", "body_for"]

tituli/calligram.py

@@ -0,0 +1,164 @@
+"""Calligrams and concrete poems: text whose shape is part of the meaning.
+
+Three treatments, all producing an ordinary :class:`~tituli.layout.Layout`:
+
+* :func:`on_path` — glyphs ride a :class:`~tituli.geometry.Path` (any shape:
+  circle, wave, Bézier, SVG ``d``), rotated to the tangent or kept upright;
+* :func:`rain` — Apollinaire's *Il pleut*: upright letters stepping down
+  fanning streaks (a preset of the same machinery, with the 1918 measurements
+  as defaults);
+* :func:`in_shape` — prose poured into a silhouette, the concrete-page case.
+
+``shape=`` accepts a named preset, an SVG path string, or a
+:class:`~tituli.geometry.Path`, so a caller can say ``"circle"`` and a
+designer can hand over a traced outline — the same seam.
+
+>>> from tituli.frame import Frame
+>>> lay = on_path("round and round", shape="circle", frame=Frame.blank((800, 800)))
+>>> len(lay.runs) == len("round and round".replace(" ", ""))
+True
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Sequence
+
+from tituli.frame import Frame
+from tituli.geometry import Box, Path
+from tituli.layout import Layout, along_path, fill_shape, glyph_columns
+from tituli.style import CALLIGRAM, TextStyle
+
+# Measured from the 1918 Mercure de France setting of "Il pleut".
+IL_PLEUT_SLANTS: tuple[float, ...] = (0.186, 0.220, 0.257, 0.298, 0.353)
+IL_PLEUT_HEAD_OFFSETS: tuple[float, ...] = (0.0, 7.0, 11.7, 16.4, 19.3)
+IL_PLEUT_SIZE_RATIO = 0.86
+
+_SHAPE_INSET = 0.12  # fraction of the safe box kept clear around a shape
+_WAVE_AMPLITUDE = 0.12  # of the box height
+_ARC_SWEEP = (200.0, 340.0)  # a gentle smile-shaped arc, degrees (screen coords)
+
+ShapeSpec = "str | Path"
+
+
+def resolve_shape(shape: "str | Path", box: Box) -> Path:
+    """Turn a name, an SVG ``d`` string or a Path into a Path fitted to ``box``.
+
+    Names: ``"line"``, ``"circle"``, ``"arc"``, ``"wave"``, ``"diagonal"``,
+    ``"s-curve"``. Anything starting with ``M``/``m`` is parsed as SVG.
+    """
+    if isinstance(shape, Path):
+        return shape.fit(box)
+    name = shape.strip()
+    if name[:1] in "Mm" and any(c.isdigit() for c in name):
+        return Path.from_svg(name).fit(box)
+    cx, cy = box.center
+    r = min(box.width, box.height) / 2
+    if name == "line":
+        return Path.line((box.x0, cy), (box.x1, cy))
+    if name == "circle":
+        return Path.circle((cx, cy), r)
+    if name == "arc":
+        return Path.arc((cx, cy + r * 0.6), r * 1.1, *_ARC_SWEEP).fit(box)
+    if name == "wave":
+        return Path.wave(
+            (box.x0, cy),
+            (box.x1, cy),
+            amplitude=box.height * _WAVE_AMPLITUDE,
+            cycles=1.0,
+        )
+    if name == "diagonal":
+        return Path.line((box.x0, box.y0), (box.x1, box.y1))
+    if name == "s-curve":
+        return Path.bezier(
+            (box.x0, box.y1),
+            (box.x0 + box.width * 0.9, box.y0 + box.height * 0.9),
+            (box.x1 - box.width * 0.9, box.y0 + box.height * 0.1),
+            (box.x1, box.y0),
+        )
+    raise ValueError(
+        f"unknown shape {shape!r}; use a preset name, an SVG path string, or a Path"
+    )
+
+
+def on_path(
+    text: str,
+    *,
+    shape: "str | Path" = "wave",
+    frame: Frame,
+    style: TextStyle = CALLIGRAM,
+    box: Box | None = None,
+    upright: bool = False,
+    align: Literal["start", "center", "end"] = "center",
+    fit_text: bool = True,
+) -> Layout:
+    """Set ``text`` along a shape inside ``box`` (default: the safe area, inset).
+
+    With ``fit_text`` the type is shrunk until the whole string fits the path
+    length (never clipped); the resulting size is in ``meta["size"]``.
+    """
+    box = box or frame.safe.inset(
+        frame.safe.width * _SHAPE_INSET, frame.safe.height * _SHAPE_INSET
+    )
+    path = resolve_shape(shape, box)
+    st = style
+    lay = along_path(text, path, st, frame, upright=upright, align=align)
+    while fit_text and lay.meta.get("overflow", 0) > 0 and st.size > 0.008:
+        st = st.with_(size=st.size * 0.92)
+        lay = along_path(text, path, st, frame, upright=upright, align=align)
+    return Layout(
+        lay.runs, lay.plates, {**lay.meta, "size": st.size, "path_length": path.length}
+    )
+
+
+def rain(
+    lines: Sequence[str] | str,
+    *,
+    frame: Frame,
+    style: TextStyle = CALLIGRAM,
+    box: Box | None = None,
+    slants: Sequence[float] = IL_PLEUT_SLANTS,
+    head_offsets: Sequence[float] = IL_PLEUT_HEAD_OFFSETS,
+    size_ratio: float = IL_PLEUT_SIZE_RATIO,
+) -> Layout:
+    """*Il pleut*: each line a streak of upright letters falling across the frame.
+
+    Wants a portrait frame. ``slants`` (dx per step down) and ``head_offsets``
+    (where each streak starts, in slot units) are shape parameters, not
+    coordinates — the defaults are Apollinaire's.
+    """
+    if isinstance(lines, str):
+        lines = [l for l in lines.split("\n") if l.strip()]
+    box = box or frame.safe
+    return glyph_columns(
+        list(lines),
+        style,
+        frame,
+        box=box,
+        slants=slants,
+        head_offsets=head_offsets,
+        size_ratio=size_ratio,
+    )
+
+
+def in_shape(
+    text: str,
+    mask,
+    *,
+    frame: Frame,
+    style: TextStyle = CALLIGRAM,
+    box: Box | None = None,
+    repeat: bool = True,
+) -> Layout:
+    """Pour prose into a silhouette (light = inside). See :func:`tituli.layout.fill_shape`."""
+    box = box or frame.safe
+    return fill_shape(text, mask, style, frame, box=box, repeat=repeat)
+
+
+__all__ = [
+    "on_path",
+    "rain",
+    "in_shape",
+    "resolve_shape",
+    "IL_PLEUT_SLANTS",
+    "IL_PLEUT_HEAD_OFFSETS",
+]

tituli/color.py

@@ -0,0 +1,158 @@
+"""Colours, WCAG contrast, and the ink-for-this-background decision.
+
+Everything here is pure arithmetic on ``(r, g, b[, a])`` tuples in 0–255, so it
+costs nothing to import and is easy to test.
+
+>>> contrast_ratio((255, 255, 255), (0, 0, 0))
+21.0
+>>> ink_for(luminance=0.9)   # light background -> dark ink
+(17, 17, 17)
+>>> ink_for(luminance=0.1)   # dark background -> light ink
+(255, 255, 255)
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+RGB = tuple[int, int, int]
+RGBA = tuple[int, int, int, int]
+Color = Union[RGB, RGBA, str]
+
+WHITE: RGB = (255, 255, 255)
+BLACK: RGB = (0, 0, 0)
+NEAR_BLACK: RGB = (17, 17, 17)  # #111 — reads as black without the harshness
+OFF_WHITE: RGB = (245, 245, 243)  # a warm paper white for solid title cards
+CREDITS_BLACK: RGB = (8, 8, 10)
+
+# WCAG 2.x thresholds (AA): 4.5:1 for normal text, 3:1 for large text
+WCAG_NORMAL_MIN = 4.5
+WCAG_LARGE_MIN = 3.0
+# "Large" text per WCAG is >= 18pt regular or >= 14pt bold; on a 1080p canvas
+# every tituli default is well above that, so 3:1 is the operative floor and
+# 4.5:1 is what we *aim* for.
+
+_SRGB_THRESHOLD = 0.03928
+_SRGB_LINEAR_DIVISOR = 12.92
+_SRGB_GAMMA = 2.4
+_SRGB_OFFSET = 0.055
+_SRGB_SCALE = 1.055
+_LUMA_R, _LUMA_G, _LUMA_B = 0.2126, 0.7152, 0.0722
+_CONTRAST_OFFSET = 0.05
+
+
+def parse_color(color: Color) -> RGBA:
+    """Accept ``"#rgb"``, ``"#rrggbb"``, ``"#rrggbbaa"``, a Pillow name or a tuple.
+
+    >>> parse_color("#fff")
+    (255, 255, 255, 255)
+    >>> parse_color((10, 20, 30))
+    (10, 20, 30, 255)
+    """
+    if isinstance(color, str):
+        s = color.strip()
+        if s.startswith("#"):
+            h = s[1:]
+            if len(h) in (3, 4):
+                h = "".join(c * 2 for c in h)
+            if len(h) == 6:
+                h += "ff"
+            if len(h) != 8:
+                raise ValueError(f"bad hex colour: {color!r}")
+            return tuple(int(h[i : i + 2], 16) for i in (0, 2, 4, 6))  # type: ignore[return-value]
+        from PIL import ImageColor
+
+        return ImageColor.getcolor(s, "RGBA")  # type: ignore[return-value]
+    t = tuple(int(c) for c in color)
+    if len(t) == 3:
+        return (*t, 255)  # type: ignore[return-value]
+    if len(t) == 4:
+        return t  # type: ignore[return-value]
+    raise ValueError(f"bad colour tuple: {color!r}")
+
+
+def _channel(c: int) -> float:
+    v = c / 255.0
+    if v <= _SRGB_THRESHOLD:
+        return v / _SRGB_LINEAR_DIVISOR
+    return ((v + _SRGB_OFFSET) / _SRGB_SCALE) ** _SRGB_GAMMA
+
+
+def relative_luminance(color: Color) -> float:
+    """WCAG relative luminance in 0..1.
+
+    >>> round(relative_luminance((255, 255, 255)), 3)
+    1.0
+    >>> relative_luminance((0, 0, 0))
+    0.0
+    """
+    r, g, b, _ = parse_color(color)
+    return _LUMA_R * _channel(r) + _LUMA_G * _channel(g) + _LUMA_B * _channel(b)
+
+
+def contrast_ratio(a: Color, b: Color) -> float:
+    """WCAG contrast ratio between two colours (1..21).
+
+    >>> round(contrast_ratio("#777", "#fff"), 2)
+    4.48
+    """
+    la, lb = relative_luminance(a), relative_luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return round((hi + _CONTRAST_OFFSET) / (lo + _CONTRAST_OFFSET), 4)
+
+
+def contrast_from_luminance(ink: Color, luminance: float) -> float:
+    """Contrast of ``ink`` over a background of known relative luminance."""
+    li = relative_luminance(ink)
+    hi, lo = max(li, luminance), min(li, luminance)
+    return (hi + _CONTRAST_OFFSET) / (lo + _CONTRAST_OFFSET)
+
+
+def ink_for(
+    *,
+    luminance: float,
+    light: RGB = WHITE,
+    dark: RGB = NEAR_BLACK,
+) -> RGB:
+    """Pick the ink (light or dark) with more contrast against ``luminance``."""
+    if contrast_from_luminance(light, luminance) >= contrast_from_luminance(
+        dark, luminance
+    ):
+        return light
+    return dark
+
+
+def needs_scrim(
+    ink: Color, luminance: float, *, minimum: float = WCAG_NORMAL_MIN
+) -> bool:
+    """Whether ``ink`` over that background falls short of ``minimum`` contrast.
+
+    >>> needs_scrim((255, 255, 255), luminance=0.5)
+    True
+    >>> needs_scrim((255, 255, 255), luminance=0.02)
+    False
+    """
+    return contrast_from_luminance(ink, luminance) < minimum
+
+
+def mix(a: Color, b: Color, t: float) -> RGBA:
+    """Linear blend, ``t=0`` -> ``a``, ``t=1`` -> ``b``."""
+    pa, pb = parse_color(a), parse_color(b)
+    return tuple(round(x + (y - x) * t) for x, y in zip(pa, pb))  # type: ignore[return-value]
+
+
+def with_alpha(color: Color, alpha: float) -> RGBA:
+    """Same colour with opacity ``alpha`` in 0..1.
+
+    >>> with_alpha("#000", 0.5)
+    (0, 0, 0, 128)
+    """
+    r, g, b, _ = parse_color(color)
+    return (r, g, b, round(255 * alpha))
+
+
+def mean_luminance(pixels: Sequence[RGB]) -> float:
+    """Mean relative luminance of a pixel sample."""
+    if not pixels:
+        return 0.0
+    return sum(relative_luminance(p) for p in pixels) / len(pixels)