Node / Video Ffmpeg · guide

Text overlays on video

Current Apexify.js 6.0.0 documentation for Text overlays on video.

apexify.jsRuntime: nodeCURRENTSince 6.0.0

Burn captions and titles onto video on a timeline. Apexify offers two tiers:

API	Styling	When to use
`addTextOverlay` (recommended)	Full `TextProperties` — same as `createText`	Product UI, brand type, gradients, glow, wrap, curved text
`addText` / `addAnimatedText` (legacy)	FFmpeg `drawtext` only	Quick labels; deprecated

Pipeline: videoPipeline().text(...) uses the same overlay types as addTextOverlay — best when combined with trim/splice/audio (Advanced → Video pipeline).

addTextOverlay — createText on video

What it does:

Renders each overlay with the canvas text engine (identical styling path to painter.createText).
Composites transparent PNGs over the video with FFmpeg overlay.
Applies enter/exit motion via filter expressions (fade, slide, zoom, …).

When to use: Any time subtitle/caption look must match generated images, cards, or scenes.

Per-overlay fields

Besides normal TextProperties (text, x, y, font, fill, effects, decorations, layout, placement, stroke, textOnCurve, …):

Field	Required	Effect
`startTime`	✓	Seconds when overlay appears.
`endTime`	✓	Seconds when overlay hides.
`transitionIn`	—	Enter preset or `custom` expressions.
`transitionOut`	—	Exit preset or `custom` expressions.
`overlayOpacity`	—	Master 0–1 (default 1), multiplied with transition fades.

Transitions

Presets: fade, fadeIn, fadeOut, slideLeft, slideRight, slideUp, slideDown, slideIn, slideOut, zoomIn, zoomOut, bounce.

transitionIn.custom / transitionOut.custom (advanced):

Key	FFmpeg role
`x`, `y`	Position expressions (`t` = seconds).
`alpha`	Layer opacity 0–1.
`scale`	Layer scale multiplier.

typewriter is listed for forward compatibility; true per-glyph typing needs a frame pipeline — today it behaves like a timed fade unless you customize.

Multiple overlays at once

Pass several objects in overlays[]. Overlapping startTime–endTime windows are allowed — use different x / y. Later array entries stack above earlier ones.

Example — styled caption

1await painter.createVideo({2  source: './talk.mp4',3  addTextOverlay: {4    outputPath: './talk-captioned.mp4',5    overlays: [6      {7        text: 'Key takeaway',8        x: 64,9        y: 900,10        startTime: 4,11        endTime: 12,12        font: { size: 40, family: 'Arial' },13        decorations: { bold: true },14        fill: { color: '#ffffff' },15        effects: {16          shadow: {17            color: 'rgba(0,0,0,0.55)',18            offsetX: 0,19            offsetY: 4,20            blur: 14,21          },22        },23        layout: { maxWidth: 920 },24        transitionIn: { type: 'slideLeft', duration: 0.35 },25        transitionOut: { type: 'fade', duration: 0.25 },26      },27    ],28  },29});

Example — gradient + two lines same window

1await painter.createVideo({2  source: './promo.mp4',3  addTextOverlay: {4    outputPath: './promo-titled.mp4',5    overlays: [6      {7        text: 'NEW',8        x: 48,9        y: 120,10        startTime: 0.5,11        endTime: 5,12        font: { size: 28, family: 'Arial' },13        fill: { color: '#fbbf24' },14      },15      {16        text: 'Summer drop',17        x: 48,18        y: 170,19        startTime: 0.5,20        endTime: 5,21        font: { size: 56, family: 'Arial' },22        decorations: { bold: true },23        fill: {24          gradient: {25            type: 'linear',26            colors: [27              { stop: 0, color: '#ffffff' },28              { stop: 1, color: '#e2e8f0' },29            ],30          },31        },32        transitionIn: { type: 'fade', duration: 0.4 },33      },34    ],35  },36});

Note: addTextOverlay re-encodes video (H.264). Plan for CPU time on long 4K clips.

Legacy: addText (deprecated)

Uses FFmpeg drawtext only — preset positions, solid fontColor, boxed background. No gradients, glow, or wrap parity.

When (if ever): Tiny server without canvas text deps — prefer addTextOverlay in current releases.

Field	Default	Effect
`text`	✓	Caption string.
`position`	`bottom-center`	Named anchors only — not free `x,y`.
`fontSize`, `fontColor`, `backgroundColor`	basic	FFmpeg styling.
`startTime`, `endTime`	always on	Visibility window.

1await painter.createVideo({2  source: './demo.mp4',3  addText: {4    text: 'DRAFT',5    position: 'top-right',6    fontSize: 20,7    startTime: 0,8    endTime: 999,9    outputPath: './demo-draft.mp4',10  },11});

Legacy: addAnimatedText (deprecated)

drawtext with optional fade or slide expression motion. TypeScript lists many animation names; only fade and slide add motion filters today.

{ x, y } position is supported. fontPath fields are reserved (not wired).

Prefer addTextOverlay with transitionIn / transitionOut.

Choose an API (summary)

1// ✅ Editor / brand / multi-caption2await painter.videoPipeline(src).text([...]).render({ outputPath });3 4// ✅ Single-pass captions on existing file5await painter.createVideo({ source: src, addTextOverlay: { overlays: [...], outputPath } });6 7// ⚠️ Legacy simple burned text only8await painter.createVideo({ source: src, addText: { ... } });

#addTextOverlay — createText on video

##Per-overlay fields

##Transitions

##Multiple overlays at once

##Example — styled caption

##Example — gradient + two lines same window

#Legacy: addText (deprecated)

#Legacy: addAnimatedText (deprecated)

#Choose an API (summary)

Related guides and reference

Next steps