ffmpeg-simplified

ffmpeg-simplified is a batteries-included toolkit built on top of ffmpeggy. It exposes an ergonomic, Promise-based API for everyday audio and video automation tasks while leaning on your locally installed ffmpeg binary.

Features

• ✅ Zero-configuration access to common ffmpeg workflows (noise reduction, slicing, merging, frame capture, audio swapping, audio syncing and more).
• ✅ Written in TypeScript with rich type definitions and detailed JSDoc comments for every function.
• ✅ Ships prebuilt bundles via tsdown and targets modern Node/Bun runtimes.
• ✅ Test suite powered by bun test and real media fixtures to ensure behaviour parity with ffmpeg.
• ✅ Built on the lightweight and modern ffmpeggy wrapper.

Requirements

• Node.js ≥ 22.0.0 or Bun ≥ 1.0.
• A working ffmpeg installation available on your PATH. The package intentionally avoids bundling ffmpeg-static so that you can manage codecs and updates yourself.
• Optional: set FFMPEG_PATH and/or FFPROBE_PATH environment variables if the binaries live somewhere other than your shell PATH.

Built with ffmpeggy

The library uses ffmpeggy, a minimal event-driven wrapper that shells out to locally installed ffmpeg and ffprobe executables. The wrapper:

• Automatically detects system-installed ffmpeg/ffprobe binaries using the which utility
• Provides a clean Promise-based API with event hooks for progress tracking
• Supports Node.js streams for input and output
• Includes built-in FFprobe integration for media analysis
• Emits detailed progress events during encoding operations

Installation

Install with your preferred package manager:

bun add ffmpeg-simplified
# or
npm install ffmpeg-simplified
# or
yarn add ffmpeg-simplified

Quick start

import {
  delayAudio,
  detectSilences,
  formatMedia,
  getFrames,
  getMediaDuration,
  getVideoDimensions,
  mergeSlices,
  replaceAudio,
  slice,
  sliceAndMerge,
  splitFileOnSilences,
  type Logger,
} from "ffmpeg-simplified";

const duration = await getMediaDuration("./samples/interview.mp4");
const silences = await detectSilences("./samples/interview.wav", {
  silenceThreshold: -45,
  silenceDuration: 0.3,
});
await formatMedia("./samples/interview.wav", "./output/clean.wav", {
  fast: true,
  noiseReduction: { dialogueEnhance: true },
});
await delayAudio("./samples/video.mp4", "./output/synced.mp4", 0.5);

Custom logging

Most functions accept an optional logger parameter that conforms to the Logger interface (compatible with console and popular logging libraries):

import type { Logger } from "ffmpeg-simplified";

// Use the built-in console
await formatMedia(input, output, options, callbacks, console);

// Or your own logger (pino, winston, etc.)
import pino from "pino";
const logger = pino();
await sliceAndMerge(input, output, options, logger);

// Minimal custom logger
const customLogger: Logger = {
  info: (msg) => console.log(`[INFO] ${msg}`),
  error: (msg) => console.error(`[ERROR] ${msg}`),
};
await splitFileOnSilences(file, outputDir, options, callbacks, customLogger);

The Logger interface is simple and all methods are optional:

interface Logger {
  info?: (message: string, ...args: any[]) => void;
  debug?: (message: string, ...args: any[]) => void;
  warn?: (message: string, ...args: any[]) => void;
  error?: (message: string, ...args: any[]) => void;
}

API overview

delayAudio(inputFile, outputFile, delayInSeconds, logger?)

Adjusts audio synchronization in a video by applying a delay (positive) or advance (negative) to the audio track.

detectSilences(filePath, options)

Finds quiet sections in an audio file using silencedetect.

formatMedia(input, outputPath, options?, callbacks?, logger?)

Preprocess audio streams (noise reduction, mono downmixing, fast mode, callback hooks).

getMediaDuration(filePath) / getVideoDimensions(filePath)

Lightweight wrappers around ffprobe for duration and resolution metadata.

splitFileOnSilences(filePath, outputDir, options?, callbacks?, logger?)

Chunk long-form audio into natural speaking segments and normalizes short clips.

slice(filePath, options, logger?) / sliceAndMerge(filePath, outputFile, options, logger?)

Slice videos by absolute timestamps or human-friendly timecodes, then optionally merge back together.

mergeSlices(inputFiles, outputFile, options?, logger?)

Concat arbitrary files using the efficient concat demuxer.

replaceAudio(videoFile, audioFile, outputFile, logger?)

Swap a video's audio track without re-encoding the video stream.

getFrames(videoFile, options, logger?)

Extract thumbnails at a fixed cadence with optional cropping and preprocessing presets.

Refer to the inline JSDoc comments for parameter details and return types—every exported function documents accepted options and callback hooks.

Development

Install dependencies and run the toolchain with Bun:

bun install
bun run build
bun test

• Builds are handled by tsdown, producing ESM output and declaration files in dist/.
• Tests rely on Bun's native test runner and preload setupTests.ts to expose fixture paths (testing/sample.*). The suite exercises real audio/video transformations, so ensure ffmpeg and ffprobe binaries are reachable.

Contributing

1. Fork the repo and create a feature branch.
2. Install dependencies with bun install.
3. Run bun test and bun run build before submitting a pull request.

License

MIT © Ragaeeb Haq