ffm-script

KO | EN

gitlite — search

#data-science #docker #chatbot #gpt #containers #web #tensorflow #pdf #ruby #agents

(★ 9)

Lib TypeScript Node.js pour le traitement de fichiers media

File Explorer

ZIP Download

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
  - release.yml
- CODEOWNERS
- PULL_REQUEST_TEMPLATE.md
- .gitkeep
- animation.test.ts
- audio-filters.test.ts
- audio.test.ts
- batch.test.ts
- binary.test.ts
- chain.test.ts
- concat.test.ts
- container.test.ts
- convert.test.ts
- errors.test.ts
- extract.test.ts
- filtergraph.test.ts
- formats.test.ts
- helpers.ts
- hls-args.test.ts
- hls.test.ts
- hwaccel.test.ts
- keyframes.test.ts
- loudnorm.test.ts
- metadata.test.ts
- mp4.test.ts
- operations-validation.test.ts
- overlay.test.ts
- parallel.test.ts
- probe-parse.test.ts
- probe.test.ts
- progress-parse.test.ts
- quality.test.ts
- run.test.ts
- scale.test.ts
- skill.test.ts
- spawn.test.ts
- sprites-args.test.ts
- sprites.test.ts
- stream-spawn.test.ts
- stream.test.ts
- subtitles.test.ts
- thumbnail.test.ts
- time.test.ts
- trim.test.ts
- validate.test.ts
- _shared.ts
- animation.ts
- audio-hls.ts
- audio.ts
- batch.ts
- chain.ts
- concat.ts
- convert.ts
- extract-audio.ts
- filters.ts
- hls.ts
- hwaccel.ts
- metadata.ts
- overlay.ts
- parallel.ts
- probe.ts
- progress.ts
- run-raw.ts
- run-stream.ts
- run.ts
- sprites.ts
- subtitles.ts
- thumbnail.ts
- trim.ts
- sample.mp4
- - SKILL.md
- - animation.ts
  - audio.ts
  - binary.ts
  - concat.ts
  - container.ts
  - filtergraph.ts
  - formats.ts
  - hls.ts
  - hwaccel.ts
  - keyframes.ts
  - loudnorm.ts
  - metadata.ts
  - mp4.ts
  - overlay.ts
  - pool.ts
  - quality.ts
  - scale.ts
  - segments.ts
  - spawn.ts
  - sprites.ts
  - subtitles.ts
  - time.ts
  - validate.ts
- - index.ts
- - animation.ts
  - audio.ts
  - batch.ts
  - chain.ts
  - concat.ts
  - convert.ts
  - extract.ts
  - hls.ts
  - metadata.ts
  - overlay.ts
  - parallel.ts
  - probe.ts
  - run.ts
  - sprites.ts
  - subtitles.ts
  - thumbnail.ts
  - trim.ts
- - index.ts
- index.ts
.gitignore
.prettierignore
.prettierrc
CHANGELOG.md
CODE_OF_CONDUCT.md
codecov.yml
CONTRIBUTING.md
eslint.config.js
jest.config.ts
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
SECURITY.md
tsconfig.json
tsup.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
codecov Visit
npm version Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A modern, TypeScript-native wrapper around the **FFmpeg binary** for common media operations — a spiritual successor to [`fluent-ffmpeg`](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg) (archived in May 2025).

- 🟦 **TypeScript-first** — strict types, full JSDoc, dual ESM + CJS builds.
- 🪶 **Zero runtime dependencies** — it shells out to the FFmpeg binary you already have.
- 🎯 **Fluent, chainable API** — `probe`, `convert`, `trim`, `extractAudio`, `thumbnail` and more.
- 🤖 **AI-agent ready** — ships an [Agent Skill](#ai-agent-skill) so **Claude Code, Cursor & Codex** know the exact API instead of hallucinating options.
- ⏳ **Progress & cancellation** — `onProgress` callbacks and `AbortSignal` support.
- 🧱 **Typed errors** — catch exactly what went wrong.

## Quick start

```ts
import { ffmscript } from 'ffm-script';

// Fluent, typed, and zero-dependency
await ffmscript('input.mp4')
  .trim({ start: 60, end: 180 })
  .convert({ width: 1280, quality: 'high' })
  .save('output.mp4', { onProgress: (p) => console.log(`${p.percent}%`) });
```

Chained `trim` + `convert` run in a **single** FFmpeg pass, not one process per step. Prefer standalone functions? Every operation is also exported on its own — jump to [Usage](#usage).

## The best fluent-ffmpeg alternative in 2026

`fluent-ffmpeg` was the de-facto way to drive FFmpeg from Node, but it was archived in May 2025. The remaining options are low-level native C bindings (`node-av`, `@mmomtchev/ffmpeg`) — powerful but complex and segfault-prone — or `ffmpeg.wasm`, which doesn't run server-side in Node. `ffm-script` is the modern, TypeScript-native replacement: a small, high-level API that wraps the FFmpeg **binary** for the operations applications actually need.

## Prerequisites

FFmpeg (which provides both `ffmpeg` and `ffprobe`) must be installed and available:

| Platform | Install                            |
| -------- | ---------------------------------- |
| macOS    | `brew install ffmpeg`              |
| Ubuntu   | `sudo apt-get install ffmpeg`      |
| Windows  | `winget install Gyan.FFmpeg`       |
| Other    | <https://ffmpeg.org/download.html> |

If the binaries aren't on your `PATH`, point the library at them with the `FFMPEG_PATH` and `FFPROBE_PATH` environment variables.

Requires **Node.js >= 22**.

## Install

```sh
pnpm add ffm-script
# or: npm install ffm-script / yarn add ffm-script
```

> **Formats:** input MP4 / MOV / WebM / MKV (plus MP3 / AAC / WAV / FLAC / M4A for audio); video output is MP4. Audio extraction targets MP3/AAC, the audio toolkit also writes WAV/FLAC; thumbnails target JPEG/PNG, storyboard sprite sheets JPEG/PNG/WebP.

## Usage

> **Runnable examples:** every snippet below has an executable counterpart in
> [`examples/`](examples/) — one script per feature. Run them all against the
> bundled fixture with `pnpm examples`, or one at a time: `pnpm examples trim`.

### Check FFmpeg is available

Fail fast at startup with a clear, actionable message:

```ts
import { checkDependencies } from 'ffm-script';

checkDependencies(); // throws FFmpegNotFoundError if ffmpeg/ffprobe are missing
```

### Read metadata — `probe`

```ts
import { probe } from 'ffm-script';

const info = await probe('video.mp4');
console.log(info.duration); // 124.5 (seconds)
console.log(info.video?.codec); // "h264"
console.log(info.video?.width); // 1920
console.log(info.audio?.codec); // "aac"
console.log(info.tags.title); // container metadata (title, artist, creation_time…)
console.log(info.audio?.tags.language); // per-stream metadata (e.g. "eng")
```

`tags` is a `Record<string, string>` of metadata. It's present at the top level (container tags such as `title`, `artist`, `album`, `creation_time`) and on every stream (per-track tags such as `language`), defaulting to an empty object when the file carries none. Write these tags back with [`setMetadata`](#read--write-metadata--setmetadata).

### Read & write metadata — `setMetadata`

Write or strip metadata tags. Streams are stream-copied (`-c copy`), so it's **lossless and near-instant** — editing tags never re-encodes the media:

```ts
import { setMetadata } from 'ffm-script';

// Set tags on top of the existing metadata
await setMetadata('input.mp4', 'output.mp4', {
  tags: { title: 'My Movie', artist: 'Me', comment: 'Shot on location' },
});

// Replace: drop the input's tags first, keep only the new ones
await setMetadata('input.mp4', 'output.mp4', { tags: { title: 'Clean' }, clear: true });

// Strip everything (anonymise) — clear with no tags
await setMetadata('input.mp4', 'output.mp4', { clear: true });
```

Keys are FFmpeg metadata keys (`title`, `artist`, `album`, `comment`, `copyright`, `creation_time`, …). Works on **audio-only files** (MP3/AAC/WAV/FLAC/M4A) as well as video. Use the same container for the output as the input so the stream copy stays valid. Calling it with neither `tags` nor `clear` is a no-op and throws `InvalidOptionsError`.

### Transcode — `convert`

```ts
import { convert } from 'ffm-script';

await convert('input.mp4', 'output.mp4', {
  videoCodec: 'libx264', // default for MP4/MOV/MKV
  audioBitrate: '192k',
  width: 1280, // height auto-scaled to preserve aspect ratio
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
});
```

#### Output container

The output container is chosen from the **output extension** — no extra option. Codecs default to the container's natural pair when you don't pass `videoCodec`/`audioCodec`:

```ts
await convert('input.mp4', 'output.webm'); // → VP9 + Opus, no config needed
await convert('input.mp4', 'output.mkv'); // → h264 + AAC
```

| Extension                | Default video      | Default audio    |
| ------------------------ | ------------------ | ---------------- |
| `.mp4` / `.mov` / `.mkv` | `libx264` (h264)   | `aac`            |
| `.webm`                  | `libvpx-vp9` (vp9) | `libopus` (opus) |

An explicit codec the container can't carry (e.g. `videoCodec: 'libx264'` with `.webm`) throws `InvalidFormatError`. MKV accepts any codec. `parallelConvert` writes `.mp4`/`.mov`/`.mkv` (not `.webm` — its copy-based join produces h264/aac; use `convert` for WebM).

#### Quality presets

`convert`, `parallelConvert` and the chainable `.convert(...)` accept a semantic `quality` preset instead of fiddling with bitrates:

```ts
await convert('input.mp4', 'output.mp4', { quality: 'high' });
```

| Preset     | Means                      | Use it for                      |
| ---------- | -------------------------- | ------------------------------- |
| `high`     | Near-transparent quality   | Visually lossless, larger files |
| `balanced` | Sensible default trade-off | Most transcodes                 |
| `small`    | Noticeably compressed      | Smaller files, lower quality    |

`quality` is **constant-quality** encoding, so it's mutually exclusive with an explicit video bitrate (`videoBitrate`, which targets a _size_) — setting both throws `InvalidOptionsError`. Pick one.

Every encoder exposes that dial under a different flag and on a different scale, so the preset is translated for the encoder you actually picked:

| Encoder family             | `high`                       | `balanced`                   | `small`                      |
| -------------------------- | ---------------------------- | ---------------------------- | ---------------------------- |
| `libx264` / `libx265`      | `-crf 18 -preset slow`       | `-crf 23 -preset medium`     | `-crf 28 -preset medium`     |
| `*_nvenc` (NVIDIA)         | `-cq 19 -preset p6`          | `-cq 23 -preset p4`          | `-cq 28 -preset p4`          |
| `*_qsv` (Intel Quick Sync) | `-global_quality 19`         | `-global_quality 23`         | `-global_quality 28`         |
| `*_videotoolbox` (Apple)   | `-q:v 65`                    | `-q:v 55`                    | `-q:v 40`                    |
| `*_vaapi` (Linux)          | `-qp 19`                     | `-qp 23`                     | `-qp 28`                     |
| `*_amf` (AMD)              | `-rc cqp -qp_i 19 -qp_p 19`  | `… 23`                       | `… 28`                       |
| `libvpx-vp9`               | `-crf 24 -b:v 0`             | `-crf 31 -b:v 0`             | `-crf 37 -b:v 0`             |
| `libsvtav1`                | `-crf 28 -preset 6`          | `-crf 35 -preset 8`          | `-crf 45 -preset 8`          |
| `libaom-av1`               | `-crf 25 -b:v 0 -cpu-used 4` | `-crf 32 -b:v 0 -cpu-used 5` | `-crf 40 -b:v 0 -cpu-used 6` |

Hardware encoders are matched by **API suffix**, so `hevc_nvenc` and `av1_nvenc` follow the `*_nvenc` row. Note that `*_videotoolbox`'s scale is inverted (higher `-q:v` = better). An encoder in no known family (e.g. `mpeg4`) has no equivalent dial and throws `InvalidOptionsError` — use `videoBitrate` there.

#### Hardware acceleration

`hwaccel` decodes the input on the GPU. Pair it with a hardware `videoCodec` to move the encode there too:

```ts
import { listHwaccels, convert } from 'ffm-script';

const accels = await listHwaccels(); // e.g. ['videotoolbox']

await convert('input.mp4', 'output.mp4', {
  hwaccel: 'videotoolbox', // -hwaccel: hardware decoding
  videoCodec: 'h264_videotoolbox', // -c:v: hardware encoding
  quality: 'balanced', // → -q:v 55, this encoder's dialect
});
```

Common pairs: `cuda` + `h264_nvenc` (NVIDIA), `qsv` + `h264_qsv` (Intel), `videotoolbox` + `h264_videotoolbox` (macOS), `vaapi` + `h264_vaapi` (Linux).

A few things worth knowing:

- **`hwaccel` alone only accelerates decoding.** Frames are handed back to system memory afterwards, which is exactly what keeps it composable with `width`/`height` and every other filter-based option.
- **`listHwaccels()` reports what the FFmpeg _build_ supports**, not what this machine can run — a build compiled with CUDA still lists `cuda` on a laptop with no NVIDIA GPU. Treat it as a shortlist and keep a software fallback.
- **The value is passed to FFmpeg untouched**, so a method that isn't usable surfaces as an `FFmpegError` rather than a typed rejection. That's deliberate: validating against a fixed list would reject methods a newer FFmpeg supports.
- **Full-GPU pipelines are out of scope.** Keeping frames on the device (`-hwaccel_output_format cuda` with `scale_cuda`) needs a filter chain this API doesn't build — reach for [`run`](#raw-ffmpeg--run) if you want that.

`parallelConvert` takes both options too, applying them to every chunk — see [Parallel transcode](#parallel-transcode--parallelconvert).

### Cut — `trim`

```ts
import { trim } from 'ffm-script';

await trim('input.mp4', 'output.mp4', {
  start: '00:01:00',
  end: '00:03:00',
  mode: 'fast', // 'fast' = no re-encode, cuts on the nearest keyframe (default)
  // 'precise' = re-encode for a frame-accurate cut (slower)
});
```

### Extract audio — `extractAudio`

```ts
import { extractAudio } from 'ffm-script';

await extractAudio('input.mp4', 'output.mp3', {
  codec: 'mp3', // or inferred from the .mp3 / .aac / .m4a extension
  bitrate: '320k',
});
```

### Normalize loudness — `normalizeAudio`

EBU R128 loudness normalization, run as **two FFmpeg passes**: the first measures the input, the
second corrects it with those measurements in hand. A single-pass `loudnorm` has to ride the level
as it goes, which audibly pumps on anything with dynamics.

```ts
import { normalizeAudio } from 'ffm-script';

// Streaming/podcast target (the defaults: -16 LUFS, -1.5 dBTP, LRA 11)
await normalizeAudio('episode.wav', 'episode.mp3', { audioBitrate: '192k' });

// Broadcast target, and the video stream copied through untouched
await normalizeAudio('input.mp4', 'output.mp4', {
  targetLoudness: -23, // EBU R128
  truePeak: -2,
  loudnessRange: 7,
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`), // spans both passes
});
```

Accepts video or audio input. Writing to `.mp4` / `.mov` / `.mkv` / `.webm` **copies** the video
stream (`-c:v copy`, no generation loss); writing to `.mp3` / `.aac` / `.m4a` / `.wav` / `.flac`
drops it. Budget roughly twice the wall time of a one-pass encode — the input is decoded twice.

The output sample rate is always pinned (to the input's own rate unless you pass `sampleRate`):
`loudnorm` resamples to 192 kHz internally, and an unpinned output would inherit that.

### Resample — `resampleAudio`

```ts
import { resampleAudio } from 'ffm-script';

// What a speech-to-text pipeline usually wants
await resampleAudio('input.mp4', 'speech.wav', { sampleRate: 16000, channels: 1 });
```

At least one of `sampleRate` / `channels` is required. Same input/output formats as
`normalizeAudio`, and the video stream travels the same way.

### Trim silence — `trimSilence`

```ts
import { trimSilence } from 'ffm-script';

// Cut the dead air at both ends, keeping 0.2s of lead-in
await trimSilence('take.wav', 'tight.wav', { keepSilence: 0.2 });

// Also collapse the interior gaps down to one second
await trimSilence('take.wav', 'tight.wav', { mode: 'all', minDuration: 1, threshold: -45 });
```

| Option        | Default  | Meaning                                                                |
| ------------- | -------- | ---------------------------------------------------------------------- |
| `mode`        | `'both'` | `'start'` / `'end'` / `'both'` trim the edges; `'all'` also the middle |
| `threshold`   | `-50`    | dB below which audio counts as silence                                 |
| `minDuration` | `1`      | `'all'` only: interior silence is shortened to this many seconds       |
| `keepSilence` | `0`      | seconds of lead-in left in place                                       |

**Audio in, audio out.** A video input is rejected on purpose: cutting the audio timeline without
cutting the picture to match would desynchronize them. There is no `onProgress` either — the output
is shorter than the input by design, so any percentage derived from FFmpeg's timestamps would be
wrong. Note that the `end` / `both` / `all` modes reverse the stream internally (`areverse`), which
buffers it whole in memory: fine for an episode, not for a multi-hour recording.

### Capture a thumbnail — `thumbnail`

```ts
import { thumbnail } from 'ffm-script';

await thumbnail('input.mp4', 'thumb.jpg', {
  timestamp: 30, // seconds, or '00:00:30'
  width: 640,
});
```

### Package as HLS — `toHLS`

```ts
import { toHLS } from 'ffm-script';

await toHLS('input.mp4', './output/', {
  segmentDuration: 6,
  resolutions: [
    { width: 1920, bitrate: '5000k' },
    { width: 1280, bitrate: '2500k' },
    { width: 854, bitrate: '1000k' },
  ],
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
});
// → output/master.m3u8 + output/1920/ + output/1280/ + output/854/
```

Pass `segmentType: 'fmp4'` for fragmented-MP4 / CMAF segments (`.m4s` + a per-variant init MP4) instead of the default MPEG-TS `.ts` — for modern and low-latency HLS players.

### Package audio as HLS — `audioToHLS`

The audio-only counterpart of `toHLS`: an AAC **bitrate** ladder (no scaling) for streaming sound — radio, podcasts. Accepts MP3/AAC/WAV/FLAC/M4A input.

```ts
import { audioToHLS } from 'ffm-script';

await audioToHLS('podcast.wav', './output/', {
  bitrates: ['128k', '64k'], // default: ['128k']
  segmentType: 'fmp4', // 'ts' (default) | 'fmp4'
  segmentDuration: 6,
});
// → output/master.m3u8 + output/128k/ + output/64k/
```

A `master.m3u8` is written even for a single bitrate, so players always target the same URL. Each variant folder is named after its bitrate.

### Scrubbing storyboard — `toSprites`

The preview that appears when a viewer hovers the progress bar. Samples thumbnails at a fixed interval, packs them into sprite sheets, and writes the WebVTT that maps each moment of the timeline to its tile — the natural companion to `toHLS`.

```ts
import { toSprites } from 'ffm-script';

await toSprites('input.mp4', './output/', {
  interval: 10, // seconds between thumbnails (default 10)
  width: 160, // thumbnail width; height keeps the aspect ratio (default 160)
  columns: 5, // thumbnails per row (default 5)
  rows: 5, // rows per sheet (default 5)
  format: 'jpg', // 'jpg' (default) | 'png' | 'webp'
});
// → output/sprite_000.jpg, output/sprite_001.jpg, … + output/storyboard.vtt
```

| Option     | Type                       | Default | Notes                                                                  |
| ---------- | -------------------------- | ------- | ---------------------------------------------------------------------- |
| `interval` | `number`                   | `10`    | Seconds between thumbnails. Lower it for short clips.                  |
| `width`    | `number`                   | `160`   | Thumbnail width in px; height is derived from the source.              |
| `columns`  | `number`                   | `5`     | Thumbnails per sheet row.                                              |
| `rows`     | `number`                   | `5`     | Rows per sheet — a new sheet starts every `columns * rows` thumbnails. |
| `format`   | `'jpg' \| 'png' \| 'webp'` | `'jpg'` | Sheet image format, and the extension used in the VTT URLs.            |

The generated `storyboard.vtt` points at the sheets by **relative** URL with an [`#xywh=`](https://www.w3.org/TR/media-frags/) media fragment, so serving the output directory as-is is enough:

```
WEBVTT

00:00:00.000 --> 00:00:10.000
sprite_000.jpg#xywh=0,0,160,90

00:00:10.000 --> 00:00:20.000
sprite_000.jpg#xywh=160,0,160,90
```

Point your player's thumbnail track at that file — video.js, hls.js, Plyr and JW all read this format.

Two details worth knowing: the thumbnail **height is computed from the source** (rotation included) rather than left to FFmpeg, so the `#xywh=` fragments are pixel-exact; and the file names are fixed, like the HLS playlists — give it a dedicated directory. A grid whose sheet would exceed 16384px on either edge is rejected with `InvalidOptionsError`, since browsers and mobile decoders refuse images that large.

### Chainable API — `ffmscript`

Fuse `trim` and `convert` into a **single** FFmpeg pass (not separate processes):

```ts
import { ffmscript } from 'ffm-script';

await ffmscript('input.mp4')
  .trim({ start: 60, end: 180 })
  .convert({ width: 1280 })
  .save('output.mp4', { onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`) });
```

#### Composable filters — one pass, one re-encode

`.burnSubtitles()` and `.overlay()` join the same pass, so resizing, burning in subtitles and stamping a watermark cost **one** re-encode instead of three (three decodes, three encodes, a lost generation each round):

```ts
await ffmscript('input.mp4')
  .trim({ start: 2, end: 30 })
  .convert({ width: 1280, quality: 'balanced' })
  .burnSubtitles({ subtitles: 'subs.srt' }) // or { track: 0 } for an embedded one
  .overlay({ watermark: 'logo.png', position: 'top-right', opacity: 0.6, width: 120 })
  .save('output.mp4');
```

They take the same options as [`burnSubtitles`](#subtitles--extractsubtitles--burnsubtitles) and [`overlay`](#watermark--overlay) — minus `onProgress`/`signal`, which belong to `.save()`. The last call of each wins.

The filters always run in a **fixed order**, whatever the call order: **scale → subtitles → overlay**. Scaling first renders the subtitles at the output resolution (crisp text, instead of being burnt in and then resampled), and the watermark comes last so it sits on top of them.

Two things to know:

- With `.trim()`, subtitle cues land on the **trimmed** timeline: the input seek restarts timestamps, so a cue at `00:00:01` shows one second after the cut, not one second into the original file.
- A watermark needs a second input, so that pass is built as a `-filter_complex` with explicit stream mapping. `.raw()` flags that would override it (`-vf`, `-filter:v`, `-filter_complex`, `-map`) throw an `InvalidOptionsError` rather than silently producing a wrong output — build the whole graph yourself with `.raw()` or [`run`](#raw-ffmpeg--run) in that case.

Need a flag the typed options don't expose? `.raw(args)` injects arbitrary FFmpeg arguments into the same fused pass — the in-pipeline counterpart to [`run`](#raw-ffmpeg--run):

```ts
await ffmscript('input.mp4')
  .trim({ start: 60, end: 180 })
  .raw(['-vf', 'eq=contrast=1.2', '-crf', '18'])
  .save('output.mp4');
```

Raw flags are appended to the **output** side, after the options generated from `trim`/`convert`, so an explicit flag wins over a generated one (a `-vf` here overrides the scale from `.convert({ width })`). `.raw()` forces a re-encode — for pure stream-copy or muxer-only tweaks, use [`run`](#raw-ffmpeg--run) instead.

### Parallel transcode — `parallelConvert`

Splits the video on keyframe boundaries, re-encodes the chunks across N workers, then joins them without re-encoding (artefact-free). The audio is encoded in a single continuous pass and muxed back, so the joins stay drift-free no matter how many chunks the video is cut into. Accepts MP4, MOV, WebM and MKV inputs (output is always MP4) — keyframes come from the ISOBMFF `stss` box when available, otherwise from ffprobe:

```ts
import { parallelConvert } from 'ffm-script';

await parallelConvert('input.mp4', 'output.mp4', {
  workers: 4,
  videoBitrate: '2000k',
  width: 1280, // height auto-scaled to preserve aspect ratio
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
});
```

> **Don't expect a speedup on a single machine.** FFmpeg (libx264) already saturates every core with its internal threading — splitting the video and running N local workers only re-shares the same cores. At equal settings, a local `parallelConvert` finishes in about the same time as `convert` (sometimes slightly slower, from the split/concat overhead). This is expected, not a bug.

#### Performance model: one machine vs many

The chunked model — the one YouTube and Netflix run — pays off when the chunks are encoded on **independent hardware**: compute power then adds up instead of being re-shared, and throughput scales near-linearly with the number of machines. `ffm-script` implements the building block (keyframe-accurate splitting, segment planning, chunks that re-join without re-encoding); the distribution itself — queue, remote workers, moving chunks around — is your orchestration layer.

What `parallelConvert` guarantees locally is the **correctness** of that chunked pipeline: the output keeps the source duration and both tracks, with artefact-free joins and drift-free audio. That's the validation of the building block, not a speed promise.

`workers` is optional. It defaults to **half the host's logical cores** (at least 1) so the machine stays usable during the transcode — each FFmpeg worker is itself multithreaded, so one worker per core would oversubscribe the CPU. That same internal threading is why adding local workers doesn't speed anything up. A value above the core count is capped to it.

#### Distributing chunks across machines — `executor`

To actually get that scaling, hand `parallelConvert` an `executor`: a function that encodes one segment and returns its chunk path. `parallelConvert` keeps doing everything else — planning the keyframe split, encoding the audio in one continuous pass, joining the chunks — and just calls your executor to produce each **video** chunk, so you decide _where_ each encode runs:

```ts
import { parallelConvert, type SegmentExecutor } from 'ffm-script';

const executor: SegmentExecutor = async (segment, ctx) => {
  // `segment` = { index, startTime, endTime? }; the last segment has no endTime (runs to EOF).
  // `ctx.encodeArgs` = the shared video-encode flags every chunk must use, e.g.
  //   ['-an', '-c:v', 'libx264', '-b:v', '2000k', '-vf', 'scale=1280:-2'].
  // `ctx.inputArgs` = flags that must come BEFORE the -i (the hardware decoder); [] when none.
  // Dispatch it to a remote worker (HTTP, queue, …) that runs:
  //   ffmpeg <ctx.inputArgs> -ss <segment.startTime> -i <ctx.input> [-t <ctx.duration>] <ctx.encodeArgs> -y chunk.mp4
  // then return the path to the retrieved chunk (readable on this machine for the join).
  return sendToRemoteWorker(segment, ctx);
};

await parallelConvert('input.mp4', 'output.mp4', {
  executor,
  concurrency: 16, // segments in flight — NOT capped to local cores when an executor is set
  videoBitrate: '2000k',
  retries: 2, // re-attempt a segment whose (remote) encode fails, before giving up
  retryDelay: 1000, // optional wait (ms) between attempts
});
```

Without an `executor`, `parallelConvert` uses a built-in **local** executor (a plain FFmpeg process per chunk) — so a bare call is unchanged. Two rules the executor must respect: every chunk uses `ctx.encodeArgs` unchanged (identical encoding on all chunks is what lets the joins stream-copy), and the returned path must be readable by the machine running `parallelConvert` when it joins them. The audio is always encoded locally in one continuous pass and muxed back — never split across chunks, which would accumulate gaps and A/V drift.

**Failure recovery.** Across a fleet, a worker dying mid-encode is normal. Set `retries` and a failed segment is re-attempted (calling your executor again, so a retrying executor can route it to a healthy worker); `retryDelay` spaces the attempts. An **aborted** run is never retried — cancellation is intentional. Without `retries`, the first failure rejects the whole call (the default, unchanged).

Prefer the low-level pieces? `resolveKeyframes` and `planSegments` are also exported, so you can plan the split and run the joins yourself with [`concat`](#concatenate-files--concat) — the `executor` seam is just the ergonomic path that reuses `parallelConvert`'s audio handling and joining.

`width` / `height` resize the output just like [`convert`](#transcode--convert) — set one to preserve the aspect ratio, or both to force exact dimensions. The same scale is applied to every chunk, so the joins stay artefact-free.

`videoCodec` picks the chunk encoder (default `libx264`), and `hwaccel` decodes each chunk on the GPU — the same options as [`convert`](#hardware-acceleration), applied identically to every chunk, which is what keeps the joins stream-copyable:

```ts
await parallelConvert('input.mp4', 'output.mp4', {
  hwaccel: 'cuda',
  videoCodec: 'h264_nvenc',
  quality: 'balanced', // → -cq 23 -preset p4, this encoder's dialect
});
```

The encoder must be muxable in the output container (checked up front, `InvalidFormatError` otherwise) since the chunks are joined and muxed with a stream copy. With a custom `executor`, `hwaccel` is handed over as `ctx.inputArgs` rather than used locally.

The output container follows the extension — `.mp4`, `.mov` or `.mkv`. WebM is rejected: the chunks and the aac audio are stream-copied at the joins, which WebM can't carry — use [`convert`](#output-container) for WebM.

### Batch many files — `processBatch`

`parallelConvert` parallelises the chunks of **one** file. To run an operation across **many** files with a bounded number in flight at once, use `processBatch`:

```ts
import { processBatch, convert } from 'ffm-script';

const files = ['a.mov', 'b.mov', 'c.mov'];

await processBatch(files, (file, i) => convert(file, `out/${i}.mp4`, { quality: 'balanced' }), {
  concurrency: 4, // at most 4 encodes running at a time
  onProgress: (done, total) => console.log(`${done}/${total} done`),
});
```

The task is any async function, so `processBatch` composes with every operation (or your own work). It resolves with **each task's result in input order**, whatever order they finish in:

```ts
const infos = await processBatch(files, (file) => probe(file));
// infos[0] is probe(files[0]), infos[1] is probe(files[1]), …
```

- **`concurrency`** defaults to half the host's logical cores (at least 1) — the right default when each task is itself an FFmpeg process that already saturates the CPU. It isn't capped, so raise it for I/O-bound tasks.
- **`onProgress(done, total)`** is a plain file counter (not the `Progress` object the FFmpeg operations report), fired after each task completes.
- **Fail-fast:** the first task to reject rejects the whole batch (like `Promise.all`). Tasks already running aren't cancelled by the library — pass your own `signal` into the task if you need to stop them mid-flight. A `signal` on `processBatch` itself stops the pool from launching further tasks.

### Concatenate files — `concat`

Join several videos into one MP4. FFmpeg has two concat mechanisms and the classic trap is picking the wrong one, so `concat` exposes both behind a familiar `fast` / `precise` choice — plus `auto`, which probes the inputs and decides for you:

```ts
import { concat } from 'ffm-script';

await concat(['intro.mp4', 'main.mp4', 'outro.mp4'], 'out.mp4', {
  mode: 'auto', // 'fast' | 'precise' | 'auto' (default)
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
});
```

| Mode      | Mechanism                                | Re-encode?  | Constraint                                                                        |
| --------- | ---------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `fast`    | concat demuxer (`-c copy`)               | No, fast    | Inputs must share the same codecs/resolution/parameters, or the output is corrupt |
| `precise` | concat filter (`-filter_complex concat`) | Yes, slower | Handles heterogeneous inputs                                                      |
| `auto`    | probes the inputs                        | When needed | Picks `fast` for compatible inputs, `precise` otherwise                           |

`precise` needs every input to agree on whether it carries an audio track (all or none); mixing the two throws `InvalidOptionsError`.

### Watermark — `overlay`

Burn an image (PNG/JPEG/WebP) onto a video. Anchor it to a corner or the centre, inset it from the edges, fade it, and scale it. The video is re-encoded; the audio is copied through untouched:

```ts
import { overlay } from 'ffm-script';

await overlay('input.mp4', 'output.mp4', {
  watermark: 'logo.png',
  position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center'
  margin: 20, // px from the edges (ignored for 'center'); default 10
  opacity: 0.6, // 0–1; default 1 (opaque)
  width: 160, // scale the watermark; height preserves aspect ratio
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
});
```

Only `watermark` is required — it defaults to a fully opaque logo in the bottom-right corner at its native size.

### Subtitles — `extractSubtitles` / `burnSubtitles`

Pull a subtitle track out into a standalone file (`.srt`, `.vtt` or `.ass`) — the embedded codec is converted to the format you ask for via the output extension:

```ts
import { extractSubtitles } from 'ffm-script';

await extractSubtitles('movie.mkv', 'subs.srt', { track: 0 }); // track defaults to 0
```

Or hardcode subtitles into the picture (burn-in) — from an external file, or from a track already embedded in the input. The video is re-encoded; the audio is copied through:

```ts
import { burnSubtitles } from 'ffm-script';

// From an external file
await burnSubtitles('input.mp4', 'output.mp4', { subtitles: 'subs.srt' });

// From an embedded track
await burnSubtitles('movie.mkv', 'output.mp4', { track: 0 });
```

### Animated GIF / WebP — `toAnimation`

Export a slice of a video as an animated image. The format is taken from the output extension — `.gif` (with a per-clip generated palette for crisp colours) or `.webp` (truecolour animated WebP):

```ts
import { toAnimation } from 'ffm-script';

await toAnimation('input.mp4', 'clip.gif', {
  start: 3, // seconds, or 'HH:MM:SS[.ms]'; default 0
  end: 6, // default end of the input
  fps: 12, // default 15
  width: 480, // scaled, aspect ratio preserved
  loop: 0, // 0 loops forever (default), -1 plays once
});

await toAnimation('input.mp4', 'clip.webp', { end: 4 }); // animated WebP
```

GIFs are capped at 256 colours, so `toAnimation` generates an optimal palette per clip and reuses it — much better than FFmpeg's default fixed palette. Keep `fps`, `width` and the range small to keep the file light.

### Raw FFmpeg — `run`

The escape hatch for anything the typed operations don't cover. Pass an arbitrary argument list straight to `ffmpeg` and still get progress parsing, cancellation, timeout and the typed error hierarchy. Arguments are forwarded verbatim — you own the inputs, the output, and any `-y` to overwrite:

```ts
import { run } from 'ffm-script';

await run(['-i', 'input.mp4', '-vf', 'scale=1280:-2', '-crf', '18', '-y', 'out.mp4'], {
  duration: 124, // optional, enables the progress percentage
  onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`),
  timeout: 60_000,
});
```

For a progress percentage, pass the media `duration` — the input is **not** auto-probed, since there's no reliable way to tell which token is the input in a free-form argument list. Without it the run still works, it just emits no progress.

### Streaming — `runStream`

The streaming counterpart to [`run`](#raw-ffmpeg--run), for very large files. Pipe a Node `Readable` into FFmpeg's stdin and/or its stdout into a `Writable` — the data flows **straight through the process without being buffered in memory**, so the footprint stays bounded whatever the file size. Reference the piped ends as `pipe:0` / `pipe:1` in the args:

```ts
import { runStream } from 'ffm-script';
import { createReadStream, createWriteStream } from 'node:fs';

await runStream(
  [
    '-i',
    'pipe:0',
    '-c:v',
    'libx264',
    '-movflags',
    'frag_keyframe+empty_moov',
    '-f',
    'mp4',
    'pipe:1',
  ],
  {
    input: createReadStream('big.mov'),
    output: createWriteStream('out.mp4'),
    onProgress: (p) => console.log(`${p.percent.toFixed(0)}%`), // needs duration
  },
);
```

`input` and `output` are both optional — omit either to read from / write to a file path in the args instead. Common cases: transcode an incoming HTTP upload to a response (`{ input: req, output: res }`), or read a file and stream the result somewhere.

> **Pipes can't seek.** FFmpeg can't rewind a stream, so the args must use a _streamable_ format: a streamable container (MPEG-TS, Matroska) or **fragmented MP4** (`-movflags frag_keyframe+empty_moov`) for piped output, and a linearly-decodable input for piped input. A plain `moov`-at-end MP4 can be neither read from nor written to a pipe. This is the same escape-hatch contract as `run` — you own the args.

It resolves once the process exits **and** the sink has flushed; it rejects with `FFmpegError` on a non-zero exit (or the underlying error if a stream fails), and supports `signal` and `timeout` like every other operation.

## Progress

`convert` and `trim` accept an `onProgress` callback. The percentage is parsed from FFmpeg's output against the known duration:

```ts
await convert('input.mp4', 'output.mp4', {
  onProgress: ({ percent, currentTime, totalTime }) => {
    console.log(`${percent.toFixed(1)}% — ${currentTime}/${totalTime}s`);
  },
});
```

## Cancellation

Every operation accepts an `AbortSignal`. Aborting kills the FFmpeg process and rejects with an `AbortError`:

```ts
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await convert('input.mp4', 'output.mp4', { signal: controller.signal });
```

## Error handling

All errors extend `FfmScriptError`, so you can catch the base class or narrow by type:

```ts
import {
  FfmScriptError,
  FFmpegNotFoundError,
  FileNotFoundError,
  InvalidFormatError,
  InvalidOptionsError,
  FFmpegError,
  FFmpegTimeoutError,
} from 'ffm-script';

try {
  await probe('video.mp4');
} catch (err) {
  if (err instanceof FFmpegNotFoundError) console.error(err.message); // install instructions included
  if (err instanceof FFmpegError) {
    console.error(err.exitCode); // FFmpeg's exit code
    console.error(err.stderr); // raw FFmpeg stderr
  }
}
```

| Error                 | Thrown when                                                 |
| --------------------- | ----------------------------------------------------------- |
| `FFmpegNotFoundError` | `ffmpeg`/`ffprobe` cannot be located                        |
| `FileNotFoundError`   | the input file does not exist                               |
| `InvalidFormatError`  | the file extension is not supported                         |
| `InvalidOptionsError` | options are invalid (bad timestamp, range, width…)          |
| `FFmpegError`         | FFmpeg exited with a non-zero code (`.stderr`, `.exitCode`) |
| `FFmpegTimeoutError`  | a process exceeded its timeout (`.duration`)                |

**Inputs are validated before FFmpeg is ever spawned** (file existence, extension, timestamps), so you get fast, typed errors instead of parsing FFmpeg's stderr.

## AI agent skill

The package ships an **Agent Skill** (`skills/ffm-script/SKILL.md`) that teaches your AI coding agent this library's exact API — signatures, option names, format constraints, the typed error hierarchy and ready-made recipes — so it stops guessing or hallucinating options. It uses the shared [Agent Skills](https://github.com/vercel-labs/skills) format, so the same skill works with Claude Code, Codex, Cursor and 70+ other agents.

### Install with the `skills` CLI (recommended)

The cross-agent installer pulls the skill straight from GitHub and drops it into the right folder for whichever agent you use:

```sh
npx skills add Doud75/ffm-script
```

### Manual install (from your installed dependency)

If you prefer to use the copy versioned with the package you installed (always matching your API version), copy `SKILL.md` into your agent's skills folder, e.g. for Claude Code:

```sh
mkdir -p .claude/skills/ffm-script
cp node_modules/ffm-script/skills/ffm-script/SKILL.md .claude/skills/ffm-script/
```

For Codex or Cursor, use `.agents/skills/ffm-script/` instead. The agent then loads it automatically when you work with `ffm-script` code.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, project layout, branch and commit conventions, and the checks CI expects before a pull request can be merged. Bugs and feature requests go through the [issue templates](https://github.com/Doud75/ffm-script/issues/new/choose). Participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).

## Security

Found a vulnerability? Please don't open a public issue — report it privately as described in [SECURITY.md](SECURITY.md), which also covers what's in scope for a wrapper around the FFmpeg binaries.

## License

MIT

ffm-script

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README