Multi-Media

A TypeScript/Node.js library for working with video files through FFmpeg and FFprobe.

@abdu-selam/multi-media provides a simple, strongly typed API for video metadata extraction, format conversion, audio extraction, trimming, splitting, and common file operations without requiring you to work directly with FFmpeg commands.

Features

• Video metadata extraction
• Audio metadata extraction
• Format metadata extraction
• Complete media metadata
• Video format conversion
• Video to audio conversion
• Video trimming
• Video splitting
• Rename, move, copy, and delete video files
• Conversion progress callbacks
• Custom error classes
• Full TypeScript type definitions
• ESM and CommonJS support

Requirements

• FFmpeg (if your system doesn't have FFmpeg this package can't do anything for you)
• FFprobe
• Node.js >=18

FFmpeg and FFprobe must be installed and available in your system's PATH.

You can verify the installation with:

ffmpeg -version
ffprobe -version

Installation

npm install @abdu-selam/multi-media

Basic Usage

import { Video } from "@abdu-selam/multi-media";

const video = new Video("./input.mp4");

Metadata

Video Metadata

const metadata = await video.videoMeta();

console.log(metadata);

Returns information such as:

• Codec
• Resolution
• Frame rate
• Bitrate
• Aspect ratio
• Duration

Audio Metadata

const audio = await video.audioMeta();

console.log(audio);

Returns audio information such as codec, sample rate, channels, bitrate, and duration.

Format Metadata

const format = await video.formatMeta();

console.log(format);

Complete Metadata

const metadata = await video.meta();

console.log(metadata);

You can also retrieve metadata without creating a Video instance:

const metadata = await Video.meta("./input.mp4");

Video Conversion

Convert a video into another supported video format:

await video.toMime("webm", "./output");

Supported video formats:

mp4, mkv, webm, avi, mov, mpeg, ogv, flv, m4v, 3gp

The library automatically configures the appropriate FFmpeg container and codecs for the selected format.

Video to Audio

Extract the audio track from a video:

await video.toAudio("mp3", "./output");

Supported audio formats:

mp3
m4a
wav
flac
ogg
aiff

Trimming

Trim a video between two points:

await video.trim(10, 30, "./output");

This creates a new video containing the section between 10 and 30 seconds.

Trim From a Specific Point

await video.trimStart(10, "./output");

This keeps the video from 10 seconds until the end.

Trim Until a Specific Point

await video.trimEnd(30, "./output");

This keeps the video from the beginning until 30 seconds.

Splitting

Split a video at a specific point:

await video.split(30, "./output");

For example, a 60-second video split at 30 seconds produces two video files:

0s  ─────────  30s  ─────────  60s
      part 1          part 2

The generated paths are reported when the operation completes.

Progress Tracking

Conversion and processing methods support a progress callback.

await video.toMime("webm", "./output", false, (progress) => {
  console.log(progress);
});

The callback receives information such as:

{
  time: number;
  speed: string | undefined;
  size: number;
  status: string | undefined;
  duration: number;
  progress: number;
}

progress is represented as a value between 0 and 1.

For example:

await video.toAudio("mp3", "./output", false, (progress) => {
  console.log(`${(progress.progress * 100).toFixed(2)}%`);
});

Logging

Processing methods display terminal progress by default.

You can disable terminal logging by passing false:

await video.toMime("mp4", "./output", false);

The progress callback can still be used when terminal logging is disabled.

File Operations

The Video class also provides common file operations.

Check Whether a File Exists and Is a Video

const exists = await video.isExist();

Or:

const exists = await Video.isExist("./input.mp4");

Rename

await video.rename("new-video");

Move

await video.move("./videos");

Copy

await video.copy("./backup");

Delete

await video.delete();

Static versions of these operations are also available:

await Video.rename("./input.mp4", "new-video");

await Video.move("./input.mp4", "./videos");

await Video.copy("./input.mp4", "./backup");

await Video.delete("./input.mp4");

Error Handling

The package provides custom errors for common failures, including:

• InvalidVideoError
• FFprobeNotFound
• FFmpegNotFound
• InvalidPath
• InvalidSecond
• InvalidSecondLimit
• InvalidSecondLimitStart
• FFmpegError
• InvalidMime

For example:

import { Video } from "@abdu-selam/multi-media";

try {
  const video = new Video("./input.mp4");

  await video.toMime("webm", "./output");
} catch (error) {
  console.error(error);
}

Supported Formats

Video

| Format | Extension | | ------------ | --------- | | MPEG-4 | .mp4 | | Matroska | .mkv | | WebM | .webm | | AVI | .avi | | QuickTime | .mov | | MPEG | .mpeg | | Ogg Video | .ogv | | Flash Video | .flv | | MPEG-4 Video | .m4v | | 3GPP | .3gp |

Audio

| Format | Extension | | ------------ | --------- | | MP3 | .mp3 | | MPEG-4 Audio | .m4a | | WAV | .wav | | FLAC | .flac | | Ogg Vorbis | .ogg | | AIFF | .aiff |

API Overview

Video

| Method | Description | | -------------- | ---------------------------------------- | | videoMeta() | Get video stream metadata | | audioMeta() | Get audio stream metadata | | fileMeta() | Get file metadata | | formatMeta() | Get container/format metadata | | meta() | Get complete metadata | | isExist() | Check whether the input is a valid video | | rename() | Rename the video | | move() | Move the video | | copy() | Copy the video | | delete() | Delete the video | | toMime() | Convert to another video format | | toAudio() | Extract/convert audio | | trim() | Trim between two timestamps | | trimStart() | Trim from a timestamp to the end | | trimEnd() | Trim from the beginning to a timestamp | | split() | Split a video at a timestamp |

How It Works

The package uses:

• FFprobe for inspecting media files and extracting metadata.
• FFmpeg for video conversion, audio conversion, trimming, and splitting.
• Node.js filesystem APIs for file management.

The library handles the FFmpeg command construction and exposes a higher-level API so applications can perform common video operations without manually constructing FFmpeg arguments.

Development

Clone the repository:

git clone https://github.com/abdu-selam/multi-media.git
cd multi-media

Install dependencies:

npm install

Build the package:

npm run build

The compiled package is generated in the dist directory.

License

This project is licensed under the MIT License.

See the LICENSE file for details.

Author

Abduselam Awel

GitHub: https://github.com/abdu-selam

Repository

https://github.com/abdu-selam/multi-media

If you find the package useful, consider giving the repository a ⭐.