> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Asset

> Overlay text elements on videos with customizable fonts, colors, and positioning

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/editor/feature/text_asset_titles_overlays.ipynb)

`TextAsset` creates static text for titles, labels, lower-thirds, and other overlays. It defines the text and its styling; a `Clip` controls how long it appears, while `Track` and `Timeline` place it in the composition.

For speech-synchronized subtitles, use [Caption Asset](https://docs.videodb.io/pages/act/programmable-editing/caption-asset.md) instead.

## Create a text overlay

Start with the smallest useful composition: centered white text on a black canvas.

```python Python theme={null}
from videodb.editor import Clip, Font, TextAsset, Timeline, Track

timeline = Timeline(conn)
timeline.background = "#000000"
timeline.resolution = "1280x720"

text_asset = TextAsset(
    text="Hello World",
    font=Font(family="Clear Sans", size=48, color="#FFFFFF"),
)

track = Track()
track.add_clip(0, Clip(asset=text_asset, duration=5))
timeline.add_track(track)

stream_url = timeline.generate_stream()
```

```javascript Node.js theme={null}
import { Clip, EditorTextAsset, EditorTimeline, Font, Track } from 'videodb';

const timeline = new EditorTimeline(conn);
timeline.background = "#000000";
timeline.resolution = "1280x720";

const textAsset = new EditorTextAsset({
    text: "Hello World",
    font: new Font({ family: "Clear Sans", size: 48, color: "#FFFFFF" }),
});

const track = new Track();
track.addClip(0, new Clip({ asset: textAsset, duration: 5 }));
timeline.addTrack(track);

const streamUrl = await timeline.generateStream();
```

<video controls width="100%">
  <source src="https://play.videodb.io/v1/b2906c4e-c7dd-4791-b610-99cdbaad86c5.m3u8" type="application/x-mpegURL" />
</video>

***

## TextAsset Parameters

| Parameter | Type | Description |
| :- | :- | :- |
| `text` | str / string | The text to display |
| `font` | Font | Font styling (family, size, color, opacity) |
| `background` | Background | Background box styling |
| `alignment` | Alignment | Position on screen |
| `border` | Border | Border styling |
| `shadow` | Shadow | Shadow styling |
| `tabsize` | int / number | Tab size for text formatting |
| `line_spacing` / `lineSpacing` | float / number | Spacing between lines in Python / Node.js |
| `width` | int / number | Width of text box in pixels |
| `height` | int / number | Height of text box in pixels |

***

## Font

Controls text appearance.

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `family` | str / string | `"Clear Sans"` | Font family name |
| `size` | int / number | `48` | Font size in pixels |
| `color` | str / string | `"#FFFFFF"` | Text color (hex) |
| `opacity` | float / number | `1.0` | Text opacity (0.0 to 1.0) |

```python Python theme={null}
from videodb.editor import Font

font = Font(
    family="Inter",
    size=56,
    color="#FFFFFF"
)
```

```javascript Node.js theme={null}
const font = new Font({
    family: "Inter",
    size: 56,
    color: "#FFFFFF"
});
```

**Supported fonts:** Sans, Inter, Roboto, Open Sans, Lato, Montserrat, Oswald, Raleway, Poppins, Ubuntu, Clear Sans, Arial, Times New Roman, Courier New, Georgia, Verdana

Node.js also accepts `weight` in `new Font({ ... })`. Python's `Font` constructor does not take that option.

***

## Background

Controls the background box behind text.

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `color` | str / string | `"#000000"` | Background color (hex) |
| `opacity` | float / number | `1.0` | Background opacity (0.0 to 1.0) |
| `width` | float / number | `0` | Box width in pixels |
| `height` | float / number | `0` | Box height in pixels |
| `border_width` / `borderWidth` | float / number | `0` | Border thickness in Python / Node.js |
| `text_alignment` / `textAlignment` | TextAlignment | `center` | Text alignment within box in Python / Node.js |

```python Python theme={null}
from videodb.editor import Background, TextAlignment

background = Background(
    color="#000000",
    width=600,
    height=120,
    border_width=2.0,
    text_alignment=TextAlignment.center
)
```

```javascript Node.js theme={null}
const background = new Background({
    color: "#000000",
    width: 600,
    height: 120,
    borderWidth: 2.0,
    textAlignment: TextAlignment.center
});
```

***

## Border and Shadow

Use `Border(color, width)` and `Shadow(color, x, y)` in Python, or `new Border({ color, width })` and `new Shadow({ color, x, y })` in Node.js. Both are optional TextAsset fields. `width`, `x`, and `y` default to `0`; the default color is `"#000000"`.

***

## Multiline Text

Use `line_spacing` in Python and `lineSpacing` in Node.js to control the space between lines.

```python Python theme={null}
title = TextAsset(
    text="Line One \n Line Two \n Line Three",
    font=Font(family="Clear Sans", size=48, color="#FFFFFF"),
    line_spacing=0.8,
)
```

```javascript Node.js theme={null}
const title = new EditorTextAsset({
    text: "Line One \n Line Two \n Line Three",
    font: new Font({ family: "Clear Sans", size: 48, color: "#FFFFFF" }),
    lineSpacing: 0.8,
});
```

<video controls width="100%">
  <source src="https://play.videodb.io/v1/566e7688-f38a-4ff2-b76f-8e82466e0909.m3u8" type="application/x-mpegURL" />
</video>

***

## Alignment

Controls where the text appears on screen.

| Parameter | Type | Description |
| :- | :- | :- |
| `horizontal` | HorizontalAlignment | `left`, `center`, `right` |
| `vertical` | VerticalAlignment | `top`, `center`, `bottom` |

```python Python theme={null}
from videodb.editor import (
    Alignment, Border, Clip, Font, HorizontalAlignment,
    TextAsset, Timeline, Track, VerticalAlignment
)

timeline = Timeline(conn)
timeline.background = "#2B2B2B"
timeline.resolution = "1280x720"

positions = [
    (HorizontalAlignment.left, VerticalAlignment.top, "Top-Left"),
    (HorizontalAlignment.center, VerticalAlignment.top, "Top-Center"),
    (HorizontalAlignment.right, VerticalAlignment.top, "Top-Right"),
    (HorizontalAlignment.left, VerticalAlignment.center, "Mid-Left"),
    (HorizontalAlignment.center, VerticalAlignment.center, "Center"),
    (HorizontalAlignment.right, VerticalAlignment.center, "Mid-Right"),
    (HorizontalAlignment.left, VerticalAlignment.bottom, "Bot-Left"),
    (HorizontalAlignment.center, VerticalAlignment.bottom, "Bot-Center"),
    (HorizontalAlignment.right, VerticalAlignment.bottom, "Bot-Right"),
]

track = Track()
for horizontal, vertical, label in positions:
    text_asset = TextAsset(
        text=label,
        font=Font(family="Clear Sans", size=60, color="#FFD700"),
        border=Border(color="#000000", width=2.0),
        alignment=Alignment(horizontal=horizontal, vertical=vertical),
    )
    track.add_clip(0, Clip(asset=text_asset, duration=5))
timeline.add_track(track)
```

```javascript Node.js theme={null}
import {
    Alignment, Border, Clip, EditorTextAsset, EditorTimeline, Font,
    HorizontalAlignment, Track, VerticalAlignment
} from 'videodb';

const timeline = new EditorTimeline(conn);
timeline.background = "#2B2B2B";
timeline.resolution = "1280x720";

const positions = [
    [HorizontalAlignment.left, VerticalAlignment.top, "Top-Left"],
    [HorizontalAlignment.center, VerticalAlignment.top, "Top-Center"],
    [HorizontalAlignment.right, VerticalAlignment.top, "Top-Right"],
    [HorizontalAlignment.left, VerticalAlignment.center, "Mid-Left"],
    [HorizontalAlignment.center, VerticalAlignment.center, "Center"],
    [HorizontalAlignment.right, VerticalAlignment.center, "Mid-Right"],
    [HorizontalAlignment.left, VerticalAlignment.bottom, "Bot-Left"],
    [HorizontalAlignment.center, VerticalAlignment.bottom, "Bot-Center"],
    [HorizontalAlignment.right, VerticalAlignment.bottom, "Bot-Right"],
];

const track = new Track();
positions.forEach(([horizontal, vertical, label]) => {
    const textAsset = new EditorTextAsset({
        text: label,
        font: new Font({ family: "Clear Sans", size: 60, color: "#FFD700" }),
        border: new Border({ color: "#000000", width: 2.0 }),
        alignment: new Alignment({ horizontal, vertical }),
    });
    track.addClip(0, new Clip({ asset: textAsset, duration: 5 }));
});
timeline.addTrack(track);
```

<video controls width="100%">
  <source src="https://play.videodb.io/v1/f0e2c8d2-1268-4f25-978d-57fa6c9620c0.m3u8" type="application/x-mpegURL" />
</video>

***

## Branded Lower-Third

```python Python theme={null}
from videodb.editor import (
    Timeline, Track, Clip, VideoAsset, TextAsset,
    Font, Background, Border, Shadow, Alignment,
    HorizontalAlignment, VerticalAlignment, Offset, Transition
)

video_clip = Clip(
    asset=VideoAsset(id=video.id, start=0, volume=0),
    duration=5,
)

lower_third = TextAsset(
    text="Dr. Sarah Chen: Tech Officer",
    font=Font(family="Clear Sans", size=36, color="#FFFFFF", opacity=1.0),
    background=Background(
        width=600,
        height=120,
        color="#1E88E5",
        opacity=0.95,
    ),
    border=Border(color="#FFC107", width=4.0),
    shadow=Shadow(color="#000000", x=3, y=3),
    alignment=Alignment(
        horizontal=HorizontalAlignment.left,
        vertical=VerticalAlignment.bottom,
    ),
)

lower_third_clip = Clip(
    asset=lower_third,
    duration=6,
    offset=Offset(x=0.03, y=-0.05),
    transition=Transition(in_="fade", out="fade", duration=2),
)

timeline = Timeline(conn)
track = Track()
track.add_clip(0, video_clip)
track.add_clip(0, lower_third_clip)

timeline.add_track(track)

stream_url = timeline.generate_stream()
```

```javascript Node.js theme={null}
import {
    EditorTimeline, Track, Clip, EditorVideoAsset, EditorTextAsset,
    Font, Background, Border, Shadow, Alignment,
    HorizontalAlignment, VerticalAlignment, Offset, Transition
} from 'videodb';

const videoClip = new Clip({
    asset: new EditorVideoAsset({ id: video.id, start: 0, volume: 0 }),
    duration: 5,
});

const lowerThird = new EditorTextAsset({
    text: "Dr. Sarah Chen: Tech Officer",
    font: new Font({ family: "Clear Sans", size: 36, color: "#FFFFFF", opacity: 1.0 }),
    background: new Background({
        width: 600,
        height: 120,
        color: "#1E88E5",
        opacity: 0.95,
    }),
    border: new Border({ color: "#FFC107", width: 4.0 }),
    shadow: new Shadow({ color: "#000000", x: 3, y: 3 }),
    alignment: new Alignment({
        horizontal: HorizontalAlignment.left,
        vertical: VerticalAlignment.bottom,
    }),
});

const lowerThirdClip = new Clip({
    asset: lowerThird,
    duration: 6,
    offset: new Offset({ x: 0.03, y: -0.05 }),
    transition: new Transition({ in: "fade", out: "fade", duration: 2 }),
});

const timeline = new EditorTimeline(conn);
const track = new Track();
track.addClip(0, videoClip);
track.addClip(0, lowerThirdClip);
timeline.addTrack(track);

const streamUrl = await timeline.generateStream();
```

<video controls width="100%">
  <source src="https://play.videodb.io/v1/8fe87b46-1038-4edf-ad17-20b38f812ff7.m3u8" type="application/x-mpegURL" />
</video>

***

## Next Steps

> [card] [Text Asset Titles and Overlays Notebook](https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/editor/feature/text_asset_titles_overlays.ipynb)
>
> Build titles, lower-thirds, multiline overlays, and text styling examples.

> [card] [CaptionAsset](https://docs.videodb.io/pages/act/programmable-editing/caption-asset.md)
>
> Auto-generated subtitles synced to speech

> [card] [Timeline Architecture](https://docs.videodb.io/pages/act/programmable-editing/timeline-architecture.md)
>
> Complete guide to the 4-layer editing system


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.