VideoHandler

A powerful, easy-to-use FFmpeg wrapper for Node.js that provides common video manipulation operations.

Prerequisites

FFmpeg must be installed on your system:

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Docker:

RUN wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz && \
    tar xvf ffmpeg-release-amd64-static.tar.xz && \
    mv ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/ && \
    mv ffmpeg-*-amd64-static/ffprobe /usr/local/bin/ && \
    rm -rf ffmpeg-release-amd64-static.tar.xz ffmpeg-*-amd64-static

Installation

npm install videohandler

Usage

import videoHandler from 'videohandler';

// Or import the class for custom instances
import { VideoHandler } from 'videohandler';

API

trimVideo(inputPath, outputPath, startTime, duration)

Trim/cut a video to a specific duration.

await videoHandler.trimVideo(
    'input.mp4',
    'output.mp4',
    10,  // start at 10 seconds
    30   // duration of 30 seconds
);

convertFormat(inputPath, outputPath, format)

Convert video to different format.

await videoHandler.convertFormat('input.avi', 'output.mp4', 'mp4');

compressVideo(inputPath, outputPath, options)

Compress video with custom quality settings.

await videoHandler.compressVideo('input.mp4', 'output.mp4', {
    crf: 28,           // Quality: 0-51 (lower = better quality)
    preset: 'medium',  // Speed: ultrafast, fast, medium, slow, veryslow
    bitrate: '1000k'   // Optional: set specific bitrate
});

extractAudio(inputPath, outputPath)

Extract audio track from video.

await videoHandler.extractAudio('video.mp4', 'audio.mp3');

addWatermark(videoPath, watermarkPath, outputPath, position)

Add image watermark to video.

await videoHandler.addWatermark(
    'video.mp4',
    'logo.png',
    'output.mp4',
    'bottom-right'  // top-left, top-right, bottom-left, bottom-right
);

getMetadata(inputPath)

Get video metadata (duration, codec, resolution, etc.).

const metadata = await videoHandler.getMetadata('video.mp4');
console.log(metadata);

generateThumbnail(inputPath, outputPath, timestamp)

Generate thumbnail from video at specific time.

await videoHandler.generateThumbnail('video.mp4', 'thumb.png', 5);

resizeVideo(inputPath, outputPath, size)

Resize video to specific dimensions.

await videoHandler.resizeVideo('input.mp4', 'output.mp4', '1280x720');

mergeVideos(inputPaths, outputPath)

Concatenate multiple videos into one.

await videoHandler.mergeVideos(
    ['video1.mp4', 'video2.mp4', 'video3.mp4'],
    'merged.mp4'
);

extractFrames(inputPath, outputDir, fps)

Extract frames from video.

await videoHandler.extractFrames('video.mp4', './frames', 1);
// Extracts 1 frame per second

addAudioToVideo(videoPath, audioPath, outputPath)

Replace or add audio track to video.

await videoHandler.addAudioToVideo('video.mp4', 'audio.mp3', 'output.mp4');

Custom Instance

If you need to specify custom FFmpeg paths:

import { VideoHandler } from 'videohandler';

const customHandler = new VideoHandler({
    ffmpegPath: '/custom/path/to/ffmpeg',
    ffprobePath: '/custom/path/to/ffprobe'
});

await customHandler.trimVideo('input.mp4', 'output.mp4', 0, 10);

Error Handling

All methods return Promises and should be used with try/catch:

try {
    await videoHandler.trimVideo('input.mp4', 'output.mp4', 0, 10);
    console.log('Video processed successfully!');
} catch (error) {
    console.error('Error processing video:', error);
}

License

ISC

Author

Rupendra Vadlamudi