🚀 ffmpeg-eloquent

A lightweight, fluent, and powerful FFmpeg wrapper for Bun and Node.js, built from the ground up with TypeScript. Designed for simplicity, reliability, and modern developer experience.

⚠️ Beta Notice: This package is currently in Beta. Some APIs might evolve, and we are actively working on stability and features.

✨ Features

• Fluent API: Chainable methods that read like a story.
• Modern Runtimes: Optimized for Bun and Node.js.
• TypeScript First: Full type safety for options and methods.
• Stream Support: Handle input and output using native Node.js/Bun streams.
• Lightweight: Zero heavy dependencies.

🛠 Prerequisites

This package leverages modern FFmpeg features.

• FFmpeg: v8.1 or higher (Recommended for full feature support)
• Node.js (v18+) or Bun (v1.0+)

Make sure FFmpeg is installed and added to your system's PATH.

📦 Installation

# Using Bun (Recommended)
bun add ffmpeg-eloquent

# Using NPM
npm install ffmpeg-eloquent

# Using PNPM
pnpm add ffmpeg-eloquent

🚀 Quick Start

Basic Conversion

Easily convert a video to another format with a few lines.

import Ffmpeg from 'ffmpeg-eloquent';

const ffmpeg = new Ffmpeg();

await ffmpeg
  .addInput('input.mp4')
  .toFormat('webp')
  .save('output.webp');

console.log('Conversion finished!');

Working with Streams

Pipe your data directly into FFmpeg or get a stream back.

import Ffmpeg from 'ffmpeg-eloquent';
import { createReadStream, createWriteStream } from 'node:fs';

const inputStream = createReadStream('video.mp4');
const ffmpeg = new Ffmpeg();

ffmpeg
  .addInput(inputStream)
  .toFormat('mp3')
  .audioCodec('libmp3lame')
  .duration(30); // Grab first 30 seconds

// Get a Readable stream
const outputStream = ffmpeg.stream();
outputStream.pipe(createWriteStream('preview.mp3'));

Detailed Input Options

Configure your inputs precisely.

import Ffmpeg from 'ffmpeg-eloquent';

const ffmpeg = new Ffmpeg();

ffmpeg.addInput('video.mkv', {
  seek: '00:00:05',   // Start at 5 seconds
  duration: 10,       // Process 10 seconds
  fps: 24,            // Force frame rate
  loop: 1             // Loop input once
});

await ffmpeg.save('clip.mp4');

📖 API Reference

Ffmpeg Class

| Method | Description | | :--- | :--- | | .addInput(media, options?) | Adds an input source (path or Stream) with optional InputOptions. | | .toFormat(format) | Sets the output format (e.g., mp4, mp3, webp). | | .noAudio() | Disables audio in the output. | | .duration(seconds) | Sets the output duration. | | .audioCodec(codec) | Sets the audio codec (e.g., libmp3lame, aac). | | .customArgs(...args) | Pass any raw FFmpeg arguments directly. | | .save(path) | Starts the process and saves the output to a file. Returns Promise<void>. | | .stream() | Starts the process and returns a Readable stream of the output. |

InputOptions

• seek: -ss (string, e.g., '00:00:01')
• duration: -t (number in seconds)
• loop: -stream_loop (number)
• fps: -r (number)
• format: -f (string)
• channel: -ac (number, 1 or 2)
• rate: -ar (number, e.g., 44100)

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitLab.

1. Fork the repository.
2. Create your feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a new Pull/Merge Request.

📄 License

This project is licensed under the GPL-3.0. See the LICENSE file for details.

Built with ❤️ by xaliazhar