Typography

Text in a video comes in two kinds. Dynamic text changes with time: captions that follow the voice. Static text stays put: a watermark, a title, a source line. Both are styled with the same TextStyle.

TextStyle

from imaginaryarts import TextStyle, Fonts, Color, Shadow

style = TextStyle(
    font=Fonts.PlayfairDisplay,
    size=70,
    color=Color(system="white"),
    shadow=Shadow.md,
    opacity=1.0,
    bold=True,
    italic=False,
    lowercase=True,
    text_spacing=-1.5,
)

Field	Default	Meaning
`font`	`Fonts.PlayfairDisplay`	One of the bundled fonts, below.
`size`	`70`	Font size in pixels, on the 1080 by 1920 canvas.
`color`	`Color(system="white")`	The text color. See Color.
`shadow`	`Shadow.md`	The drop shadow: `Shadow.sm`, `Shadow.md`, `Shadow.lg`, or `None`.
`opacity`	`1.0`	`0` is invisible, `1` is solid. Useful for watermarks.
`bold`	`False`	Uses the font's bold face.
`italic`	`False`	Uses the font's italic face.
`lowercase`	`True`	Renders the text in lowercase. The reference caption look; turn it off for titles and names.
`text_spacing`	`-1.5`	Letter spacing in pixels. Slightly negative tightens the text.

bold and italic pick a real face of the font rather than thickening or slanting the regular one. Where a font has no such face, the closest one it does have is used: Carrois Gothic comes in regular only, and Instrument Serif has an italic but no bold.

Fonts

The fonts ship with the library, so a script renders the same everywhere.

Font	Character
`Fonts.PlayfairDisplay`	A high-contrast serif. Elegant captions for quotes and narration. The default.
`Fonts.Cormorant`	A lighter, classical serif. Literary.
`Fonts.InstrumentSerif`	A condensed, modern serif with a strong italic.
`Fonts.Barlow`	A clean, slightly rounded grotesque. Neutral and readable at small sizes; good for watermarks and explainer captions.
`Fonts.CarroisGothic`	A humanist sans with a friendly, hand-set feel.
`Fonts.TikTokSans`	The bold, tightly spaced sans of short-form social video. Use it when captions should feel native to TikTok and Reels.

Shadows

A shadow is what keeps light text legible over bright footage. There is no outline; the shadow does that job.

Shadow	Offset
`Shadow.sm`	2 px down
`Shadow.md`	3 px down
`Shadow.lg`	5 px down

Positions

Position	Where
`Position.TOP`	8% down from the top of the frame.
`Position.MIDDLE`	46% down. The usual caption line for vertical video.
`Position.BOTTOM`	92% down. The usual place for a watermark.

Dynamic text

Captions are a DynamicText added with add_dynamic_text. It needs the timestamped words to show, a style, a flow and a position:

from imaginaryarts import DynamicText, DynamicTextFlow, Position

video.add_dynamic_text(DynamicText(
    words=placed.words,
    text_style=style,
    flow=DynamicTextFlow.WordByWord(max_words=30, max_lines=1),
    position=Position.MIDDLE,
))

The flow decides how words appear. WordByWord reveals each word the instant it is spoken; SentenceBySentence shows one sentence at a time. The details, and where the words come from, are in Creating subtitles.

Static text

A watermark or title is add_static_text. It takes the text, a style, a position, and optionally an interval; without an interval it shows for the whole video.

video.add_static_text(
    "maximsbook.com",
    text_style=TextStyle(font=Fonts.Barlow, size=40, color=Color(system="gray"),
                         opacity=0.7, shadow=Shadow.sm),
    position=Position.BOTTOM,
)

# A title card for the first three seconds only.
video.add_static_text(
    "Part one",
    text_style=TextStyle(font=Fonts.InstrumentSerif, size=110, lowercase=False),
    position=Position.MIDDLE,
    interval=[0, 3000],
)

Static text is drawn above the captions, so a watermark stays visible while captions run underneath it.