## Text and fonts

A text layer (`ty:5`) shows the copy of its first text document. This is a layer's `t`, with `fonts.list` holding `{"fName":"Montserrat-Bold","fFamily":"Montserrat","fStyle":"Bold"}`:

```json
{"d":{"k":[{"t":0,"s":{"t":"Summer sale","f":"Montserrat-Bold","s":48,"lh":56,"ls":0,"tr":0,"j":2,"fc":[1,1,1]}}]},"a":[]}
```

- The copy is at `/layers/{arrayIndex}/t/d/k/0/s/t`, or the same pointer in a precomposition. The layer's `nm` does not change it.
- Text document properties are plain values, not `{a,k}` property objects.
- Only the first document, `t.d.k[0]`, is read: later document keyframes change neither the text nor the font. Font, size and paragraph settings belong there. For changing captions, use separate text layers with distinct visibility intervals, not document keyframes.
- `t.a` holds the [text animators](#text-animators). Write `[]` without any. With animators, write `t.m` too.
- The render stops (`problems`) unless `t.d.k[0].s` is an object holding copy `t` with a visible character, and font `f`. The font must be declared in `fonts.list`, and be in the version or the font library.

### Fonts

- Find the available fonts before you choose the typography: `GET /v1/fonts`, or MCP `list_fonts`. Each library font has a ready `declaration` for `fonts.list`. Don't assume the example's font exists. For another typeface, add its file to the version ([Fonts](/docs/blitframe/fonts)).
- `f` matches `fonts.list[].fName` exactly, including case and whitespace.
- Declare every font you use with its actual `fName`, `fFamily` and `fStyle`. Keep `fPath` absent or empty, and never write machine paths.
- An unused declaration needs no font file, but every entry, used or not, needs a text `fName`.
- Use text layers and fonts for all copy. Don't convert glyphs to shapes or images to get around font discovery. Animate text with [text animators](#text-animators), or an [expression selector](#per-character-expression-selectors) when the animation needs expressions.

### Text document fields

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `t` | text | Required | The copy. `\r`, `\n` and ETX (`\u0003`) each break the line: write one per line break. At most 64 lines and the first 16,383 characters draw. |
| `f` | text | Required | Font name, matching a `fonts.list[].fName` |
| `s` | number | 0 | Font size in pixels |
| `lh` | number | 1.2 × `s` | Line height in pixels. 0 or less also means 1.2 × `s`. |
| `ls` | number | 0 | Baseline shift in pixels |
| `tr` | number | 0 | Tracking in thousandths of an em: at size 40, tracking 100 adds 4 pixels per glyph. Preserve it for copy-only edits. |
| `j` | whole number | 0, left | 0 left, 1 right, 2 center. Any other value, such as After Effects' justified paragraphs (3 to 6), renders centered. |
| `dir` | whole number | The first character with a strong direction decides | 1 lays the text out right to left, any other value left to right |
| `fc` | list of 3 numbers | None | RGB fill, 0–1. Without it, a stroked text draws only its outline, and unstroked text fills white. |
| `sc` | list of 3 numbers | None | RGB stroke, 0–1. A stroke needs `sc` and `sw`. |
| `sw` | number | None | Stroke width in pixels. 0.01 or less draws no stroke. Text strokes always have round caps and joins. |
| `of` | boolean | `false` | `true` draws the stroke over the fill, otherwise it draws behind |
| `sz` | list of 2 numbers | None | Paragraph box size `[width,height]` ([point and paragraph text](#point-and-paragraph-text)) |
| `ps` | list of 2 numbers | Required with `sz` | The box's top-left corner `[x,y]` |
| `ca` | whole number | None | Not applied: All Caps and Small Caps (`ca` 1 and 2) render text as `t` is written. Write `"WOMEN\rSHOES"`, not `"women\rshoes"` with `ca: 2`. |

Write `s`, `lh`, `tr` and `j` explicitly: a missing one is listed in `warnings`.

### Point and paragraph text

Point text has no `sz` or `ps`. `j: 2` centers it horizontally only: it still sits on a baseline, not centered vertically. Measure the rendered glyph bounds when you align text to a plate or logo.

Paragraph text sits in a box:

- `ps` is in the layer's own coordinates, like its anchor `ks.a`. With `a:[0,0,0]`, the box's top-left corner sits `ps` from the position `p`. To center a W × H box on `p`, use `a:[0,0,0]` and `ps:[-W/2,-H/2]`.
- Text is top-aligned, and `j` aligns lines within the box width. There is no vertical alignment: to center a block vertically, size the box to the text or move `ps`.
- Lines wrap at the box width after a space, `-` or `/`. A word wider than the box breaks where it overflows.
- A letter wider than the box ends the text there: nothing from it on is laid out.
- A line draws while at least half its `lh` fits in the box, so the last can reach half a line below it. The first line always draws.

### Scripts and type styles

- Text supports Unicode, mixed right-to-left and left-to-right layout, and the font's metric kerning by default.
- Use the real bold or italic font face, not faux styles.
- Don't rely on document-level text scaling, custom kerning, ligature switches, inter-character blending or emoji.
- Scale glyphs with an animator's scale, or the whole block with the layer transform.
- Check multilingual and mixed-direction copy visually with the exact font: glyph coverage alone does not prove correct shaping or layout.
- For a decorative symbol the font can't show, use an image, and keep the copy around it as text.

### Fit text to a layer

Add `t.textFit` to fit the text to a layer in the same composition:

```json
{"wrap":true,"shrink":"toFit","grow":"none","region":{"source":"layer","ref":"Plate","margin":10},"minSize":12,"maxSize":48}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `wrap` | boolean | `false` | `true` wraps the text into the region. `false` fits one width. |
| `shrink` | text | None | Any text but `"none"` shrinks, such as `"toFit"` |
| `grow` | text | None | Only `"toFill"` grows |
| `minSize` | number | 1 | The smallest size when shrinking |
| `maxSize` | number | None | The largest size when growing. Without it, growth stops at the region height with `wrap: true`, and has no ceiling with `wrap: false`. |
| `region.source` | text | Required | `"layer"`. Inline fitting has no `box`, `rect` or `originalBounds` sources: those belong in a version's [text_fitting.json](/docs/blitframe/text-fitting). An applied rule there replaces an inline one on the same layer. |
| `region.ref` | text | Required | The name of a shape, solid, image, video, 3D model, precomposition or adjustment layer in the same composition. The first layer in `layers` with that name counts, skipping audio layers. |
| `region.margin` | number | 0 | The margin inside the region |

The engine reads no other fields. Set `wrap`, shrinking, growth and limits explicitly.

- `wrap: false` fits the width only, from the widest line before wrapping. The size can have a fraction, and the text keeps its placement.
- `wrap: true` picks a whole-pixel size, rounded down. With shrinking or growth, it is the largest size whose wrapped lines fit the region within the limits. Otherwise it is the text's own size.
- With `wrap: true`, lines break after a space, `-` or `/`, and at each line break, which stays single. A size that cuts a word does not fit.
- With `wrap: true`, the block is centered vertically in the region and aligned by `j`: left (`0`), right (`1`) or center (`2`). Preserve `j` unless the design needs another. Moving only the layer's anchor or position is compensated.
- With `wrap: true`, the engine writes its line breaks into the text. So a "lines" selector and line grouping follow the fitted lines. Text past the line limit, or past a letter wider than the region, is dropped.
- Text that does not fit at the smallest size the fit allows (`minSize` when it shrinks, otherwise its own size) overflows, and a word wider than the region is broken.
- The fit runs once, when the composition loads. It uses the two layers' position, anchor and scale as written, not their animation, rotation or parenting. It fits the current text, not replacement copy.
- At most 15 fit directives apply per composition, in layer order.
- Preserve referenced layer names, make sure the layer exists, and check the rendered placement, including parent transforms and depth.

On paragraph text the box still applies: wrapping at its width, alignment in it, and clipping at its height. With `wrap: true`, the box's top-left corner moves to where the engine would anchor centered point text. That is the region's left edge, center or right edge by alignment, at the first line's baseline. So the block sits lower than centered, and further right for center or right alignment: fit point text. If a fit could leave paragraph text nothing to draw in its box, Blitframe leaves the fit out (`warnings`). It does the same when it cannot tell the fitted size.

### Text animators

Text animators go in `t.a`, a list of objects. Each has `a`, its properties, and `s`, a [selector](#selectors) object or list. This animator makes the selected first half of the text transparent. Animate the selector boundaries for a reveal:

```json
{"a":{"o":{"a":0,"k":0}},"s":{"t":0,"r":1,"b":1,"m":1,"sh":1,"s":{"a":0,"k":0},"e":{"a":0,"k":50},"o":{"a":0,"k":0},"a":{"a":0,"k":100},"ne":{"a":0,"k":0},"xe":{"a":0,"k":0},"sm":{"a":0,"k":100}}}
```

With animators, also supply `t.m:{"g":1,"a":{"a":0,"k":[0,0]}}`. Properties can be static or keyframed, and the selector sets how strongly they affect each element. A property left out leaves that aspect unchanged:

| Property | Type | Notes |
| --- | --- | --- |
| `p` | property: 3 numbers | Position offset in text-local pixels, such as `[0,24,0]` |
| `a` | property: 3 numbers | Anchor point offset in text-local pixels. It moves the point each element scales, rotates and skews about, from where `t.m` puts it. Without scale, rotation or skew, it shifts the elements by minus its value. |
| `s` | property: 3 numbers | Scale in percent: `[100,100,100]` is unchanged |
| `r` | property: number | In-plane rotation in degrees |
| `rx`, `ry` | property: number | X and Y rotation in degrees, as a flat projection without perspective: elements narrow or flatten about their anchor, they do not recede |
| `o` | property: number | Target opacity in percent: 0 makes fully selected elements transparent. It fades the fill and the stroke together. |
| `fc` | property: RGB, 0–1 | Fill color. The stroke keeps its own color. |
| `sc` | property: RGB, 0–1 | Stroke color |
| `t` | property: number | Added tracking in text-local pixels, a different unit from the document's `tr` |
| `ls` | property: 2 numbers | Line-spacing offset `[x,y]` in pixels, not the document's baseline shift `ls` |
| `sk`, `sa` | property: number | Skew, limited to ±70°, and skew axis, in degrees |

- These belong in animators, not the text document, and an animator cannot replace the text.
- Fill or stroke hue, saturation, brightness and opacity (`fh`, `fs`, `fb`, `sh`, `ss`, `sb`, `fo`, `so`) are not supported. Nor are stroke width `sw` and blur `bl`. `warnings` name each.
- Animated tracking keeps each line's left edge in place on left-aligned text, its right edge on right-aligned text and its middle on centered text. On justified paragraphs (`j` 3 to 6), it keeps the left edge while the lines are centered.
- An animator with no selector, or whose only selector is an expression that fails to compile, applies to the whole text.
- Use a separate animator for properties that need a different selector.

`t.m` groups the text: `g` is 1 character, 2 word, 3 line or 4 all. Without `t.m`, animators group by character.

- Keep its alignment `t.m.a` a static `{"a":0,"k":[x,y]}`, two numbers in percent of the group's bounds.
- For word and line grouping, `[0,0]` is the horizontal center on each word's or line's baseline. For all grouping, it is on the last line's baseline.
- Character grouping ignores `t.m.a`: each character turns and scales about its own center on the baseline.
- Grouping sets the pivot scope, and the selector's `b` sets which elements animate.

### Selectors

Each selector is an object whose `t` is 0 (range) or 1 (expression). A range selector's fields:

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `t` | whole number | Required | 0 range, 1 expression |
| `r` | whole number | 1 | Units: 1 percent, 2 index |
| `b` | whole number | 1 | Based On: 1 characters, 2 characters without spaces, 3 words, 4 lines |
| `m` | whole number | 1 | Mode: every value adds |
| `sh` | whole number | 1 | Shape: 1 square, 2 ramp up, 3 ramp down, 4 triangle, 5 round, 6 smooth |
| `s` | property: number | 0 | Start, in the selected units. Animatable. |
| `e` | property: number | 100 | End. Animatable. |
| `o` | property: number | 0 | Offset. Animatable. |
| `a` | property: number | 100 | Amount, in percent from −100 to 100. Animatable. |
| `ne`, `xe` | property: number | 0 | Low and high easing, in percent from −100 to 100. Animatable. |
| `sm` | property: number | 100 | Smoothness, 0–100, for the square shape (`sh: 1`) only. Animatable. |

An expression selector has `t: 1`, `b` and a script string `x`, and needs no range fields ([per-character expression selectors](#per-character-expression-selectors)).

In a list of selectors, order matters. Range selectors add influence, clamped to −100–100%. An expression selector multiplies the influence before it by its returned percentage. So a range followed by `{"t":1,"b":1,"x":"50;"}` halves that range's influence, and leaves unselected characters alone. An expression selector placed first starts from full influence. This avoids separate text layers where it expresses the selection.

### Text on a path

`t.p.m` is a zero-based index into the same layer's `masksProperties`. Supply the path and all its options:

```json
{"m":0,"f":{"a":0,"k":0},"l":{"a":0,"k":0},"r":{"a":0,"k":0},"p":{"a":0,"k":1},"a":{"a":0,"k":0}}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `m` | whole number | None | The index of one of the layer's masks |
| `f`, `l` | property: number | 0 | First and last margins. They may animate. |
| `r` | property: whole number | 0 | Static. `1` reverses the direction. |
| `p` | property: whole number | 0 | Static. `1` makes glyphs perpendicular to the path. Without it, glyphs stand upright. |
| `a` | property: whole number | 0 | Static. `1` forces alignment. |

- The engine uses the mask path's first keyframe: path morphs don't move the text. Use a static path.
- The path's mask is not also a coverage mask.
- Path text takes precedence over the paragraph box.

### Edge cases

- On a layer that never draws, text without a visible character is only in `warnings`.
- A `fonts.list` entry without a text `fName`, used or not, fails the render (`problems`). If a name is declared more than once, the last declaration decides its font.
- A missing `s`, `tr` or `j` reads as 0, and a missing `lh` as 1.2 times the size (`warnings`). So do values that are not finite numbers, and a `j` with a decimal point.
- `\r\n` is two breaks, with an empty line between. A break at the very end adds no line. A NUL character ends the text.
- `fc` or `sc` (with `sw` above 0.01) that is not a list, or is empty, fails the render (`problems`). So do `sz` or `ps` that is not a list, and `sz` without `ps`.
- A missing `t.a` reads as `[]`.
- Text whose drawn lines hold no glyph stops the render (`problems`, or only `warnings` on a layer that never draws).
- A paragraph box side of 0 or less clips no lines. The text wraps at the box width when that is positive. Otherwise it is laid out like point text: `j` aligns lines about the box's left edge, and the first baseline sits at its top. A negative side is listed in `warnings`.
- `wrap` other than the boolean `true` does not wrap. A `shrink` that is not text does not shrink. A `region.ref` that is not text turns the fit off.
- These fits leave the text at its own size (`warnings`): one past the fifteenth, one with another `source`, and one whose `ref` names no layer. So does a `ref` whose first match is the text itself, or any text, null or camera layer.
- An adjustment layer is a region only when it has an `ef` list and positive `sw` and `sh`. Otherwise it is a plain null, and the text keeps its size.
- The text also keeps its size when a margin leaves no room, or when the text layer's scale is 0 on X or Y. So it does with a shape region whose bounds are empty, and a size or widest line of 0.
- A `t.a` that is not a list of objects fails the render (`problems`). So does an animator whose `a` is not an object.
- A property or selector value written bare, instead of `{"a":0,"k":value}` or keyframes, fails the render (`problems`).
- `t.m.g` outside 1 to 4 is clamped. With animators, a `t.m` that is not an object, or a `t.m.a` that is not an object with a `k` list, fails the render (`problems`).
- A selector that is not an object, or a list of selectors with a `t` other than 0 or 1, fails the render (`problems`).
- `m` reads every value as additive. `sh` of 0 or outside 1 to 6 reads as square.
- An expression selector `x` that is not a string cannot run, so the selector is skipped (`warnings`). After Effects exports a selector without `x` when it reduces the expression to a constant. That one is skipped too, so the animator applies through its other selectors, or to the whole text when it has none (`warnings`).
- Text on a path: any nonzero whole number in `r`, `p` or `a` turns the option on. `true` and `1.0` read as 0. A missing option reads as 0.
- Text on a path: an `m` that is not a whole-number index of one of the layer's masks lays the text out without the path. So does a mask path with no length, such as one whose points and tangents all meet in one spot.
- A whole-number `m` reads `masksProperties` whatever `hasMask` says. The render fails (`problems`) when that is not a list of mask objects, or when the named mask's `pt` is not an object. So it does when an option `f`, `l`, `r`, `p` or `a` is present but not an object.
- An empty `t.p:{}` does not turn on text on a path.
