Skip to content

docs: font support in compose and caption.burn #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
a-essawy merged 3 commits into from
Aug 25, 2026
Merged

docs: font support in compose and caption.burn #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ecae693
docs: font support in compose and caption.burn
a-essawy Aug 25, 2026
f3fc0a5
docs: caption.burn font is the live param, fontFamily is the alias
a-essawy Aug 25, 2026
eeae841
docs: captions.animate resolves Google Fonts by name too
a-essawy Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions jobs/captions/animate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,13 +138,15 @@ curl -X POST https://api.rendobar.com/jobs \
</ParamField>

<ParamField body="font" type="string">
URL of a TTF or OTF font file. Set `style.font` to that font's family name to render captions in it. See [Fonts](#fonts).
URL of your own font file (TTF, OTF, TTC, WOFF, WOFF2). Captions render in it, and it takes priority over `style.font`, so you do not need to know the family name inside your own file. See [Fonts](#fonts).
</ParamField>

## Fonts

Eleven presets ship with sensible default fonts. To pick a different one, set `style.font` to a bundled family. No upload needed.

Any [Google Fonts](https://fonts.google.com) family also works by name and is fetched at render time, and `style.font` accepts a CSS fallback stack like `"Lato, Inter, sans-serif"` that falls through in order.

| Bundled family | Pass as `style.font` |
| --- | --- |
| Inter | `"Inter"` |
Expand All @@ -155,10 +157,8 @@ Eleven presets ship with sensible default fonts. To pick a different one, set `s
| Roboto | `"Roboto"` |
| Oswald | `"Oswald"` |

To use your own font, pass two values together:

1. The font file URL as the `font` input.
2. The font's real family name as `style.font`.
To use your own font, pass its URL as the `font` input. It wins over
`style.font`, so nothing else is required:

```json
{
Expand All @@ -167,13 +167,13 @@ To use your own font, pass two values together:
"source": "https://cdn.rendobar.com/assets/examples/sample.mp4",
"font": "https://example.com/MyBrand.ttf"
},
"params": {
"preset": "gold",
"style": { "font": "My Brand" }
}
"params": { "preset": "gold" }
}
```

Naming the family embedded in the file as `style.font` still works, so an
existing integration that does both keeps rendering the same way.

`style.font` must match the family name baked into the file, not the filename or URL. If it does not match, the renderer falls back to the preset font.

Like every job, this returns the standard response. See [Job output](/concepts/job#the-output) for the shape and how to read the result.
Expand Down
12 changes: 10 additions & 2 deletions jobs/captions/burn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,14 +97,22 @@ Omit `subtitles` to auto-transcribe. The spoken language is detected by default
URL of an SRT, VTT, or ASS subtitle file. A provided ASS file is burned as-is, preserving its own styling. Omit to auto-transcribe the audio.
</ParamField>

<ParamField body="font" type="string">
URL of your own font file (TTF, OTF, TTC, WOFF, WOFF2). Captions render in it, and it takes priority over `fontFamily`, so you do not need to know the family name inside your own file. An uploaded asset's content URL works here.
</ParamField>

## Parameters

<ParamField body="language" type="enum" default="auto">
Spoken language for the auto-transcribe path, as an ISO-639-1 code (e.g. `en`, `es`, `ja`) or `auto` to detect. English uses a faster model. Everything else routes to multilingual transcription. Ignored when a subtitle file is provided.
</ParamField>

<ParamField body="fontFamily" type="string" default="Inter">
Font family. Must resolve to a font available to the renderer.
<ParamField body="font" type="string" default="Inter">
Font family, or a CSS fallback stack. Any [Google Fonts](https://fonts.google.com) family works by name and is fetched at render time. Seven are bundled and resolve instantly: `Inter`, `Roboto`, `Montserrat`, `Poppins`, `Oswald`, `Anton`, `Bebas Neue`. A stack falls through in order, so `"Lato, Inter, sans-serif"` tries each in turn. To render in your own file, pass its URL as the `font` **input**, which wins over this parameter.
</ParamField>

<ParamField body="fontFamily" type="string" deprecated>
Deprecated alias for `font`. Still accepted so existing clients keep working. `font` wins when both are present.
</ParamField>

<ParamField body="fontSize" type="integer" default="48">
Expand Down
104 changes: 102 additions & 2 deletions jobs/compose.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ Effects are fields on a clip. Stack as many as you like on one clip. Each exampl

## Text and titles

A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`, `position`, and an `animate` entrance (`fade`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`). Put one text clip on its own track for a title card, another low and left for a lower-third name tag.
A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`, `position`, and an `animate` entrance (`fade`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`). Put one text clip on its own track for a title card, another low and left for a lower-third name tag. `font` takes any Google Fonts family by name, or a family from your own file. See [Fonts](#fonts).

```json
"asset": {
Expand All @@ -291,6 +291,106 @@ A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`
<video src="https://cdn.rendobar.com/assets/showcase/fx/title-lowerthird.mp4" autoPlay loop muted playsInline />
</Frame>

## Fonts

Name any [Google Fonts](https://fonts.google.com) family in `style.font` and it
is fetched at render time. Nothing to upload, no configuration.

```json
"style": { "font": "Bebas Neue", "size": 96, "weight": 700 }
```

Seven families are bundled into the render image and resolve instantly, with no
fetch: `Inter`, `Roboto`, `Montserrat`, `Poppins`, `Oswald`, `Anton`,
`Bebas Neue`.

### Your own font files

Put the file URLs in the job's `fonts` input, each under a family name **you**
choose, then reference that name in `style.font`.

```json
{
"type": "compose",
"inputs": {
"fonts": [
{ "family": "Display", "src": "https://cdn.example.com/BrandDisplay.woff2" },
{ "family": "Body", "src": "https://cdn.example.com/BrandText.otf" }
]
},
"params": {
"schemaVersion": 1,
"timeline": {
"tracks": [
{ "clips": [{ "asset": { "type": "text", "text": "LAUNCH", "style": { "font": "Display", "size": 140 } }, "start": 0, "length": 3 }] },
{ "clips": [{ "asset": { "type": "text", "text": "in stores now", "style": { "font": "Body", "size": 54 } }, "start": 0, "length": 3 }] }
]
},
"output": { "format": "mp4", "size": "1080p" }
}
}
```

There is no limit on how many you declare. TTF, OTF, TTC, WOFF and WOFF2 all
work, and an [uploaded asset's](/api-reference/assets) content URL works in
`src` like any other input URL.

Naming your own font is the point. The alternative is to reference the family
name buried inside the file, which you have to discover with a font inspector
and which is frequently not what the file is called. Omit `family` and that
embedded name is read for you, so `{ "src": "..." }` on its own is also valid.

A family you declare shadows a bundled one of the same name, exactly the way an
`@font-face` rule beats a system font in CSS. Declare a font called `Inter` and
yours is the one that renders.

For a single file, `inputs.font` is the shorthand. It is addressed as `custom`:

```json
"inputs": { "font": "https://cdn.example.com/BrandDisplay.ttf" },
"style": { "font": "custom", "size": 96 }
```

### Fallback stacks

`style.font` takes a CSS-style list, and it falls through in order:

```json
"style": { "font": "Display, Bebas Neue, sans-serif" }
```

This is a failure policy, not just a preference. If your CDN is unreachable or
a Google family cannot be fetched, the render continues with the next entry
instead of failing the job or silently substituting whatever the system happens
to have. Every substitution is reported on the job:

```json
"steps": [
{
"id": "execute-engine",
"meta": {
"fontFallbacks": [
"font \"Display\" is not available; trying the next entry in \"Display, Bebas Neue\""
]
}
}
]
```

A value naming nothing resolvable is rejected at submit, which catches the
common mistake of pasting a font URL into `style.font` instead of into `fonts`.

### Weights and languages

`weight` runs 100 to 1000. Variable fonts honour it exactly; a static family
snaps to its nearest available cut, rounding up on a tie.

Latin, Cyrillic, Greek, Vietnamese, Turkish, Arabic, Hebrew, Thai, Devanagari,
Bengali, Tamil, Amharic, Khmer, Chinese, Japanese and Korean all render, with
right-to-left joining and conjunct shaping handled by the engine. Colour emoji
does not render in text assets.


## Set the canvas

`output` controls the resolution, frame rate, and format. A `9:16` canvas with a `crop` on the clip turns landscape footage into a vertical Reel that fills the frame, no black bars.
Expand Down Expand Up @@ -451,7 +551,7 @@ Fields on a text asset's `style`:

| Field | Notes |
| --- | --- |
| `font` | Font family name. Available: `Inter`, `Roboto`, `Montserrat`, `Poppins`, `Oswald`, `Anton`, `Bebas Neue` |
| `font` | Font family, or a CSS fallback stack like `"Display, Inter, sans-serif"`. Any Google Fonts family works by name. Families you declare in the `fonts` input win over both. See [Fonts](#fonts) |
| `size` | Point size |
| `weight` | 100..1000 (default 400) |
| `color` | Hex fill |
Expand Down
Loading