Installation

Package


npm install simple-ffmpegjs

Prerequisites

FFmpeg must be installed and available in your PATH.

macOS


brew install ffmpeg

Ubuntu / Debian


apt-get install ffmpeg

For text overlays, also install font support:


apt-get install -y ffmpeg fontconfig fonts-dejavu-core

Alpine Linux


apk add --no-cache ffmpeg fontconfig ttf-dejavu

Windows

Download from ffmpeg.org/download.html and add the bin/ folder to your PATH.

For text overlays, your FFmpeg build should include libfreetype and fontconfig. Most standard package manager builds include these by default. On minimal Linux environments (Docker, Alpine), you may need to install a font package explicitly — see the Alpine and Ubuntu tabs above.

Optional: Emoji rendering

By default, emoji characters in text overlays are detected and silently stripped to prevent blank glyphs (tofu). To render emoji instead, provide a path to an emoji font at construction time:


import SIMPLEFFMPEG from "simple-ffmpegjs";
 
const project = new SIMPLEFFMPEG({
  width: 1920,
  height: 1080,
  emojiFont: "/path/to/NotoEmoji-Regular.ttf",
});

Recommended font: Noto Emoji (~2 MB, SIL OFL license). Download from Google Fonts or GitHub .

Emoji render as monochrome outlines. This is a limitation of libass, which does not yet support color emoji font formats. The shapes are correct and legible — just not multi-colored.

Behavior	Without `emojiFont`	With `emojiFont`
Emoji in text	Stripped silently	Rendered via `libass`
Rendering style	—	Monochrome outline
One-time warning	Logged on first strip	Not logged