@ches-o/ffmpeg

TypeScript helper functions for media file operations using ffmpeg. This library provides a clean, promise-based API for common media processing tasks including audio/video conversion, trimming, concatenation, silence detection, and chunking.

Installation

npm install @ches-o/ffmpeg
# or
yarn add @ches-o/ffmpeg

Requirements

• Node.js >= 18
• FFmpeg is automatically installed via @ffmpeg-installer/ffmpeg

Features

• 🎬 Media Information - Get detailed metadata about media files
• 🎵 Audio Conversion - Convert any media file to MP3 format with quality presets
• ✂️ Media Trimming - Trim audio/video files to specific time ranges
• 🔗 File Concatenation - Merge multiple media files into one
• 🔇 Silence Detection - Detect silent gaps in audio/video files
• 📦 Smart Chunking - Split media files into chunks based on silent gaps

API Reference

getMediaInfo

Retrieves detailed information about a media file including format, duration, size, bitrate, and stream details.

import { getMediaInfo } from '@ches-o/ffmpeg';

const info = await getMediaInfo({
  filePath: 'video.mp4'
});

console.log(`Duration: ${info.durationSec}s`);
console.log(`Format: ${info.format}`);
console.log(`Bitrate: ${info.bitrateBps} bps`);
console.log(`Size: ${info.sizeBytes} bytes`);

/* Stream information */
info.streams.forEach(stream => {
  console.log(`Stream type: ${stream.type}`);
  console.log(`Codec: ${stream.codec}`);
  if (stream.type === 'video') {
    console.log(`Resolution: ${stream.widthPx}x${stream.heightPx}`);
    console.log(`FPS: ${stream.fps}`);
  }
  if (stream.type === 'audio') {
    console.log(`Sample rate: ${stream.sampleRateHz} Hz`);
    console.log(`Channels: ${stream.channels}`);
  }
});

toMp3

Converts any media file to MP3 audio format with configurable quality presets.

import { toMp3 } from '@ches-o/ffmpeg';

await toMp3({
  inputPath: 'video.mp4',
  outputPath: 'audio.mp3',
  quality: 'medium'  /* 'lowest' | 'low' | 'medium' | 'high' */
});

/* Quality presets:
 * - lowest: 32k bitrate, 22.05kHz sample rate
 * - low: 64k bitrate, 32kHz sample rate (default)
 * - medium: 128k bitrate, 44.1kHz sample rate
 * - high: 256k bitrate, 48kHz sample rate
 */

trimMedia

Trims a media file (audio or video) to a specific time range using millisecond precision.

import { trimMedia } from '@ches-o/ffmpeg';

await trimMedia({
  inputPath: 'video.mp4',
  outputPath: 'trimmed.mp4',
  startMs: 5000,   /* Start at 5 seconds */
  endMs: 15000     /* End at 15 seconds */
});

concat

Concatenates multiple media files with the same extension into a single file.

import { concat } from '@ches-o/ffmpeg';

await concat({
  inputPaths: ['part1.mp4', 'part2.mp4', 'part3.mp4'],
  outputPath: 'combined.mp4'
});

/* Note: All input files must have the same extension */

getSilentGaps

Detects silent gaps in an audio or video file, useful for identifying natural break points.

import { getSilentGaps } from '@ches-o/ffmpeg';

const gaps = await getSilentGaps({
  filePath: 'podcast.mp3',
  noiseDb: -40,      /* Silence threshold in dB (default: -30) */
  durationMs: 300    /* Minimum gap duration in ms (default: 500) */
});

gaps.forEach(gap => {
  console.log(`Silent gap from ${gap.fromMs}ms to ${gap.toMs}ms`);
});

getChunks

Splits a media file into chunks based on silent gaps, perfect for segmenting podcasts, audiobooks, or long recordings.

import { getChunks } from '@ches-o/ffmpeg';

const chunks = await getChunks({
  filePath: 'podcast.mp3',
  outputFolder: './segments',     /* Optional: default is source folder */
  prefix: 'episode',              /* Optional: default is filename + '_chunk' */
  noiseDb: -40,                   /* Optional: silence threshold (default: -30) */
  durationMs: 300                 /* Optional: min gap duration (default: 500) */
});

chunks.forEach(chunk => {
  console.log(`Chunk ${chunk.index}: ${chunk.filePath}`);
  console.log(`  Duration: ${chunk.toMs - chunk.fromMs}ms`);
});

TypeScript Support

All functions are fully typed. Import types as needed:

import type { 
  MediaInfo, 
  StreamInfo,
  TrimMediaInput,
  SilentGap,
  GetSilentGapsInput,
  Chunk,
  GetChunksInput
} from '@ches-o/ffmpeg';

Development

# Install dependencies
yarn install

# Build TypeScript
yarn build

# Watch mode (auto-rebuild on changes)
yarn dev

# Run tests
yarn test

# Clean build artifacts
yarn clean

Testing

Tests are located in src/tests/ and use a simple test runner. Test fixtures are provided in src/tests/fixtures/, and test outputs are saved to src/tests/tmp/ for manual inspection.

# Run all tests
yarn test

Repository

• GitHub: https://github.com/ches-o/ffmpeg
• Issues: https://github.com/ches-o/ffmpeg/issues
• NPM: https://www.npmjs.com/package/@ches-o/ffmpeg

License

MIT - See LICENSE file for details

Author

Ches