# Fonts

Every font a text layer uses must be available when you render. Pick a font from Blitframe's font library, or add your own font file to the project.

## Use a library font

Search the font library, which Blitframe provides to every workspace:

`GET /v1/fonts?q=mont&limit=20`

```json
{
  "items": [
    {
      "family": "Montserrat",
      "style": "Bold",
      "slug": "montserrat-bold",
      "declaration": { "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" },
      "license": "ofl",
      "previewUrl": "https://…/montserrat-bold.png"
    }
  ],
  "next": null
}
```

Copy the font's `declaration` into `fonts.list` in `data.json`, and use its `fName` as the text document's `f`. Agents search with the `list_fonts` MCP tool.

| Parameter | Description |
|---|---|
| `q` | Part of the family, style or slug, any case. |
| `limit` | 1 to 1,000, default 100. |
| `after` | The `next` value of the previous page, while it is not `null`. |

Fonts are listed by `slug`. `GET /v1/fonts/{slug}` returns one font.

| Field | Meaning |
|---|---|
| `previewUrl` | A PNG of the font's name set in the font, valid for an hour, or `null` when the font has no preview. |
| `license` | `ofl` (SIL Open Font License), `apache` or `ufl` (Ubuntu Font Licence) when it is recorded, otherwise `null`. |

## Add your own font

For any other typeface, add the font file to the project as `fonts/Family-Style.ttf`. Name it after the family and style it has in `fonts.list` ([how fonts are matched](#how-fonts-are-matched)). This [edit](/docs/blitframe/projects#editing-a-project) adds one and confirms you are licensed to render with it:

```json
{
  "fontLicenseAccepted": true,
  "files": [{ "path": "fonts/Inter-Bold.ttf", "contentBase64": "AAEAAA…" }]
}
```

Fonts can be TTF, OTF, WOFF or WOFF2, up to 64 MB each. [Text fitting](/docs/blitframe/text-fitting#checking-and-rendering) measures only TTF and OTF files.

Each font is checked and prepared for rendering when it comes in: inline in an edit, when you complete its [upload](/docs/blitframe/uploads#complete-it), or in an imported ZIP. A file that isn't a valid font is rejected.

## How fonts are matched

Blitframe looks for each font in two places, in this order:

1. Project fonts: font files in the version.
2. The font library.

In `data.json`, each entry in `fonts.list` has a family and a style:

```json
{ "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" }
```

Blitframe builds a lookup name from them: lower case, no spaces, joined with a hyphen. For the entry above that is `montserrat-bold`.

| Source | Matches by |
|---|---|
| Project fonts | File name, lower-cased and with spaces removed. Add the font above as `fonts/Montserrat-Bold.ttf`. Any folder works. |
| Library fonts | Their `slug`. |

Only fonts that a text layer uses need to be available. A project font with the same lookup name as a library font takes priority.

## Licensing

Only upload fonts you are licensed to use for rendering video. Project fonts are used only for your own renders.

A request that adds a font file (`.ttf`, `.otf`, `.woff` or `.woff2`) to a version must confirm it with `"fontLicenseAccepted": true`. That applies to:

- [edits](/docs/blitframe/projects#editing-a-project) that add a font file,
- creating a project from a ZIP, or importing a ZIP into a project, when the ZIP contains a font file.

Without it, the request fails with `400 font_license_required` and nothing changes. A large ZIP import that answered `202` reports it in its `error`.

You don't need it for:

- other files,
- replacements that use a library font or a font already in the version,
- a font copied from another version of your workspace with `fromVersionId`,
- [duplicating a project](/docs/blitframe/projects#duplicating-a-project), since the license was confirmed when the font first came in,
- renders, since a render's replacements can't add a font file.

[File capabilities](/docs/blitframe/uploads#file-capabilities) mark the font types with `fontLicenseRequired: true`.

## When a font is missing

The version's `problems` name the missing font and the file name to add, for example:

```
Font 'Montserrat-Bold' (Montserrat Bold) is not in the project or the font library. Upload it as fonts/Montserrat-Bold.ttf.
```
