@profullstack/transcoder

A lightweight Node.js module for transcoding videos to web-friendly MP4 format using FFmpeg. This module is designed for server-side use and ensures compatibility with all modern browsers including Safari, Chrome, and Firefox on both desktop and mobile devices.



Features

- Transcodes any video format to web-friendly MP4 (H.264/AAC)
- Transcodes audio files between formats (MP3, AAC, FLAC, OGG, etc.)
- Converts and optimizes images with various transformations (using ImageMagick)
- Ensures compatibility across all modern browsers
- Modern ESM (ECMAScript Modules) implementation
- Async/await API with real-time progress reporting
- Event-based progress tracking
- Customizable encoding options
- Smart Presets for popular platforms (Instagram, YouTube, Twitter, etc.)
- Audio enhancement features (normalization, noise reduction, fades)
- Thumbnail Generation at specified intervals or timestamps
- Batch processing of multiple files with a fancy terminal UI
- No file storage - just passes through to FFmpeg
- Lightweight with minimal dependencies

Prerequisites

This module requires the following software to be installed on your system:

1. FFmpeg and ffprobe - For video and audio processing
- Download from ffmpeg.org or build from source

2. ImageMagick - For image processing
- Download from imagemagick.org
- Required for image transformations, especially for PNG with transparency

$3

The package includes a script to automatically build FFmpeg from source with custom flags optimized for video transcoding and thumbnail generation:

``bash


Using npm

npm run install-ffmpeg

Using yarn

yarn install-ffmpeg

Using pnpm

pnpm install-ffmpeg

Or directly

./bin/build-ffmpeg.sh
`

The build script:
- Builds FFmpeg from source with optimized flags
- Enables all necessary codecs and libraries for maximum compatibility
- Includes support for ffprobe and thumbnail generation
- Installs all required dependencies

The script supports:
- macOS
- Ubuntu/Debian
- Arch Linux
- Windows (via WSL - Windows Subsystem for Linux)

$3

The package includes a script to automatically install ImageMagick with all necessary dependencies:

`bash


Using npm

npm run install-imagemagick

Using yarn

yarn install-imagemagick

Using pnpm

pnpm install-imagemagick

Or directly

./bin/install-imagemagick.sh
`

The script supports:
- macOS (via Homebrew)
- Ubuntu/Debian
- Arch Linux
- Windows (via Chocolatey)

If you already have FFmpeg installed but need to rebuild it (for example, if thumbnail generation is not working), you can use the --force flag:

`bash


Force rebuild of FFmpeg from source

pnpm install-ffmpeg -- --force

Or directly

./bin/build-ffmpeg.sh --force
`

The custom build includes support for:
- H.264/H.265 encoding and decoding
- AAC, MP3, and Opus audio codecs
- VP8/VP9 video codecs
- Hardware acceleration (when available)
- Rubberband library (required for ffprobe and thumbnail generation)
- And many other optimizations for video processing

If you prefer to install FFmpeg manually:

Ubuntu/Debian:
`bash
sudo apt update
sudo apt install ffmpeg
`

macOS (using Homebrew):
`bash
brew install ffmpeg
`

Windows (using Scoop - recommended):
`bash


Install Scoop if not already installed

iwr -useb get.scoop.sh | iex

Install FFmpeg

scoop install ffmpeg
`

Windows (using Chocolatey):
`bash
choco install ffmpeg
`

Arch Linux:
`bash
sudo pacman -S ffmpeg
`

Installation

`bash
npm install @profullstack/transcoder


or

yarn add @profullstack/transcoder

or

pnpm add @profullstack/transcoder
`

Usage

$3

`javascript
import { transcode } from '@profullstack/transcoder';

async function transcodeVideo() {
try {
const { outputPath, emitter } = await transcode('input.mov', 'output.mp4');

// Listen for progress events
emitter.on('progress', (progress) => {
console.log(Progress: ${JSON.stringify(progress)});
// Example output: {"frame":120,"fps":30,"time":4.5,"bitrate":1500,"size":1024000,"speed":2.5}
});

console.log('Transcoding completed successfully:', outputPath);
} catch (error) {
console.error('Transcoding failed:', error.message);
}
}

transcodeVideo();
`

$3

`javascript
import { transcode } from '@profullstack/transcoder';

async function transcodeWithOptions() {
try {
const options = {
videoCodec: 'libx264',
audioBitrate: '192k',
videoBitrate: '2500k',
width: 1280,
height: 720,
fps: 30,
preset: 'slow', // Higher quality but slower encoding
overwrite: true // Overwrite existing file if it exists
};

const { outputPath, emitter } = await transcode('input.mov', 'output.mp4', options);

// Create a progress bar
emitter.on('progress', (progress) => {
if (progress.time) {
const percent = Math.min(100, Math.round((progress.time / 60) * 100)); // Assuming 1-minute video
const barLength = 30;
const filledLength = Math.round(barLength * percent / 100);
const bar = '█'.repeat(filledLength) + '░'.repeat(barLength - filledLength);

process.stdout.write(\r[${bar}] ${percent}% | ${progress.fps || 0} fps | ${progress.bitrate || 0} kbps);
}
});

console.log('\nTranscoding completed successfully:', outputPath);
} catch (error) {
console.error('Transcoding failed:', error.message);
}
}

transcodeWithOptions();
`

$3

The module automatically extracts metadata from the input video during transcoding:

`javascript
import { transcode } from '@profullstack/transcoder';

async function extractMetadata() {
try {
const { outputPath, metadata } = await transcode('input.mp4', 'output.mp4');

// Display format information
console.log('Format:', metadata.format.formatName);
console.log('Duration:', metadata.format.duration, 'seconds');
console.log('File Size:', metadata.format.size, 'bytes');
console.log('Bitrate:', metadata.format.bitrate, 'bps');

// Display video stream information
console.log('Video Codec:', metadata.video.codec);
console.log('Resolution:', metadata.video.width + 'x' + metadata.video.height);
console.log('Frame Rate:', metadata.video.fps, 'fps');
console.log('Pixel Format:', metadata.video.pixelFormat);

// Display audio stream information
console.log('Audio Codec:', metadata.audio.codec);
console.log('Sample Rate:', metadata.audio.sampleRate, 'Hz');
console.log('Channels:', metadata.audio.channels);
console.log('Channel Layout:', metadata.audio.channelLayout);
} catch (error) {
console.error('Transcoding failed:', error.message);
}
}

extractMetadata();
`

$3

The module supports batch processing of multiple files with a fancy terminal UI:

`javascript
import { batchProcessDirectory, attachBatchUI } from '@profullstack/transcoder';

// Directory containing media files
const inputDir = './videos';

// Batch processing options
const batchOptions = {
// Output directory
outputDir: './processed',

// Add a prefix to output filenames
outputPrefix: 'processed-',

// Transcoding options (same as for single file transcoding)
transcodeOptions: {
// Use the 'web' preset
preset: 'web',

// Generate thumbnails
thumbnails: {
count: 1,
format: 'jpg'
},

// Always overwrite existing files
overwrite: true
},

// Process 2 files concurrently
concurrency: 2
};

// Scan options
const scanOptions = {
// Only process video files
mediaTypes: ['video'],

// Recursively scan subdirectories
recursive: true
};

console.log(Starting batch processing of files in ${inputDir}...);

// Start batch processing
batchProcessDirectory(inputDir, batchOptions, scanOptions)
.then(({ results, emitter }) => {
// Attach terminal UI to emitter
const ui = attachBatchUI(emitter);

// Listen for batch processing completion
emitter.on('complete', () => {
// Give user time to see the results before exiting
setTimeout(() => {
ui.destroy();

// Print summary
console.log(\nBatch processing completed!);
console.log(Processed ${results.total} files: ${results.successful.length} successful, ${results.failed.length} failed);
}, 3000);
});
})
.catch(err => {
console.error(Error: ${err.message});
});
`

$3

The module includes pre-configured settings optimized for specific platforms and use cases:

`javascript
import { transcode } from '@profullstack/transcoder';

// Transcode for Instagram (square format 1080x1080)
await transcode('input.mp4', 'instagram-output.mp4', { preset: 'instagram' });

// Transcode for YouTube HD (1920x1080)
await transcode('input.mp4', 'youtube-output.mp4', { preset: 'youtube-hd' });

// Transcode for Twitter with custom overrides
await transcode('input.mp4', 'twitter-output.mp4', {
preset: 'twitter',
videoBitrate: '6000k' // Override the preset's videoBitrate
});
`

Available presets:

Video Presets:

| Preset | Description | Resolution | Optimized For |
|--------|-------------|------------|---------------|
| instagram | Square format | 1080x1080 | Instagram feed |
| instagram-stories | Vertical format | 1080x1920 | Instagram stories |
| youtube-hd | HD format | 1920x1080 | YouTube |
| youtube-4k | 4K format | 3840x2160 | YouTube |
| twitter | HD format | 1280x720 | Twitter |
| facebook | HD format | 1280x720 | Facebook |
| tiktok | Vertical format | 1080x1920 | TikTok |
| vimeo-hd | HD format | 1920x1080 | Vimeo |
| web | Optimized for web | 1280x720 | Web playback |
| mobile | Optimized for mobile | 640x360 | Mobile devices |

Audio Presets:

| Preset | Description | Codec | Bitrate | Sample Rate | Channels |
|--------|-------------|-------|---------|-------------|----------|
| audio-high | High quality audio | AAC | 320k | 48000 Hz | 2 (stereo) |
| audio-medium | Medium quality audio | AAC | 192k | 44100 Hz | 2 (stereo) |
| audio-low | Low quality audio | AAC | 96k | 44100 Hz | 2 (stereo) |
| audio-voice | Voice optimized | AAC | 128k | 44100 Hz | 1 (mono) |
| mp3-high | High quality MP3 | MP3 | 320k | 44100 Hz | 2 (stereo) |
| mp3-medium | Medium quality MP3 | MP3 | 192k | 44100 Hz | 2 (stereo) |
| mp3-low | Low quality MP3 | MP3 | 96k | 44100 Hz | 2 (stereo) |

Image Presets:

| Preset | Description | Format | Quality | Optimized For |
|--------|-------------|--------|---------|---------------|
| jpeg-high | High quality JPEG | JPEG | 95% | High quality images |
| jpeg-medium | Medium quality JPEG | JPEG | 85% | Web images |
| jpeg-low | Low quality JPEG | JPEG | 70% | Small file size |
| webp-high | High quality WebP | WebP | 90% | Modern browsers |
| webp-medium | Medium quality WebP | WebP | 80% | Web images |
| webp-low | Low quality WebP | WebP | 65% | Small file size |
| png | Standard PNG | PNG | Lossless | Images with transparency |
| png-optimized | Optimized PNG | PNG | Lossless | Smaller PNG files |
| avif-high | High quality AVIF | AVIF | 80% | Modern browsers |
| avif-medium | Medium quality AVIF | AVIF | 60% | Small file size |
| thumbnail | Thumbnail size | JPEG | 80% | Thumbnails (300x300) |
| social-media | Social media size | JPEG | 90% | Social sharing (1200x630) |
| square | Square with padding | PNG | Lossless | Square images with transparent padding |
| square-white | Square with white padding | JPEG | 90% | Square images with white background |
| instagram-square | Instagram square | JPEG | 90% | Instagram (1080x1080) |

You can also override any preset setting by providing your own options:

`javascript
// Use YouTube HD preset but with a higher bitrate
await transcode('input.mp4', 'output.mp4', {
preset: 'youtube-hd',
videoBitrate: '15000k'
});
`

$3

You can add image or text watermarks to your videos:

`javascript
import { transcode } from '@profullstack/transcoder';

// Add an image watermark
await transcode('input.mp4', 'output.mp4', {
watermark: {
image: 'logo.png',
position: 'bottomRight', // Options: topLeft, topRight, bottomLeft, bottomRight, center
opacity: 0.7, // 0.0 to 1.0
margin: 10 // Margin from the edge in pixels
}
});

// Add a text watermark
await transcode('input.mp4', 'output.mp4', {
watermark: {
text: '© Copyright 2025',
position: 'bottomRight',
fontColor: 'white',
fontSize: 24,
fontFile: '/path/to/your/font.ttf', // Optional path to a font file
boxColor: 'black@0.5', // Optional background box with opacity
opacity: 0.8
}
});

// Audio enhancement for videos
await transcode('input.mp4', 'output.mp4', {
audio: {
normalize: true, // Normalize audio levels
noiseReduction: 0.3, // Reduce background noise (0.0 to 1.0)
fadeIn: 1.5, // Fade in duration in seconds
fadeOut: 2.0, // Fade out duration in seconds
volume: 1.2 // Adjust volume (1.0 = original volume)
}
});
`

$3

The module includes powerful audio enhancement features to improve the quality of audio in your videos:

`javascript
import { transcode } from '@profullstack/transcoder';

// Basic audio normalization
await transcode('input.mp4', 'output.mp4', {
preset: 'web',
audio: {
normalize: true // Normalize audio levels for consistent volume
}
});

// Noise reduction
await transcode('input.mp4', 'output.mp4', {
preset: 'web',
audio: {
noiseReduction: 0.3 // Value between 0 and 1, higher values = more noise reduction
}
});

// Add fade in/out
await transcode('input.mp4', 'output.mp4', {
preset: 'web',
audio: {
fadeIn: 1.5, // Fade in duration in seconds
fadeOut: 2.0 // Fade out duration in seconds
}
});

// Adjust volume
await transcode('input.mp4', 'output.mp4', {
preset: 'web',
audio: {
volume: 1.5 // Increase volume by 50%
}
});

// Combine multiple audio enhancements
await transcode('input.mp4', 'output.mp4', {
preset: 'web',
audio: {
normalize: true,
noiseReduction: 0.2,
fadeIn: 0.5,
fadeOut: 1.0,
volume: 1.2
}
});
`

Important Note: The audio enhancement features are primarily designed for enhancing audio tracks in video files. They work best when used with the transcode function for video files.

For standalone audio files, the support varies by format:
- WAV and AAC files are fully supported for audio enhancement
- MP3, FLAC, and OGG files are not fully supported for direct enhancement and will be skipped with a warning

When batch processing audio files with enhancements:
- WAV and AAC files will be processed normally
- MP3, FLAC, and OGG files will be skipped with a warning message
- No error will be thrown, allowing the batch process to continue with supported files

When applying audio enhancements to video files, the audio track is processed while preserving the video quality.

For the best results with standalone audio files, consider using a two-step approach:
1. First, convert to a well-supported format like WAV
2. Then apply audio enhancements

`javascript
// Example for enhancing standalone audio files
import { transcodeAudio } from '@profullstack/transcoder';

// First convert to WAV (if needed)
await transcodeAudio('input.mp3', 'temp.wav', {
audioCodec: 'pcm_s16le'
});

// Then apply enhancements
await transcodeAudio('temp.wav', 'enhanced.wav', {
normalize: true,
noiseReduction: 0.2
});
`

You can also use the batch processing feature to enhance multiple audio files:

`javascript
import { batchProcessDirectory } from '@profullstack/transcoder';

// Batch enhance audio files
const result = await batchProcessDirectory('./audio-files', {
outputDir: './enhanced-audio',
transcodeOptions: {
audio: {
normalize: true,
noiseReduction: 0.2,
fadeIn: 0.5,
fadeOut: 0.5
}
}
}, {
mediaTypes: ['audio']
});

// Check for skipped files
const skippedFiles = result.results.failed.filter(file => file.skipped);
if (skippedFiles.length > 0) {
console.log('Skipped files:');
skippedFiles.forEach(file => {
console.log(- ${file.input}: ${file.warning});
});
}
`

$3

The module includes a command-line interface (CLI) for easy video transcoding, thumbnail generation, and watermarking directly from your terminal:

`bash


Basic usage

transcoder input.mp4 output.mp4

Using a preset

transcoder input.mp4 output.mp4 --preset youtube-hd

Generate thumbnails during transcoding

transcoder input.mp4 output.mp4 --thumbnails 3

Generate thumbnails without transcoding

transcoder --thumbnails-only input.mp4 --count 5

Customize video settings

transcoder input.mp4 output.mp4 --width 1280 --height 720 --bitrate 2M

Trim a video

transcoder input.mp4 output.mp4 --trim --start 00:00:10 --end 00:00:30

Pass custom ffmpeg arguments directly

transcoder input.mp4 output.mp4 --ffmpeg-args="-vf eq=brightness=0.1:saturation=1.5"

Batch process all videos in a directory

transcoder --path ./videos --preset web --output-dir ./processed

Batch process with recursive directory scanning

transcoder --path ./videos --recursive --preset mobile --output-dir ./processed
`

The CLI tool features a cool progress bar with real-time information:

!Progress Bar

- Colorful progress visualization
- Percentage completion
- Current FPS (frames per second)
- Elapsed time
- Estimated time remaining (ETA)
- Fast and efficient thumbnail generation

For batch processing, the CLI tool provides a fancy terminal UI:

- Overall progress tracking
- Individual file progress
- Real-time statistics (completed files, success/failure rate)
- Estimated time remaining
- Detailed log output

#### CLI Options

| Option | Description |
|--------|-------------|
| --preset, -p | Use a predefined preset (e.g., youtube-hd, twitter, instagram) |
| --width, -w | Output video width |
| --height, -h | Output video height |
| --bitrate, -b | Output video bitrate (e.g., 1M, 5M) |
| --fps, -f | Output video frame rate |
| --codec, -c | Video codec to use (e.g., h264, h265) |
| --audio-codec, -a | Audio codec to use (e.g., aac, mp3) |
| --audio-bitrate | Audio bitrate (e.g., 128k, 256k) |
| --thumbnails, -t | Number of thumbnails to generate during transcoding |
| --thumbnails-only | Generate thumbnails without transcoding |
| --count | Number of thumbnails to generate (for thumbnails-only mode) |
| --format | Thumbnail format (jpg or png) |
| --timestamps | Specific timestamps for thumbnails (comma-separated, in seconds or HH:MM:SS format) |
| --thumbnail-output | Output pattern for thumbnails (e.g., "thumb-%d.jpg") |
| --trim | Enable video trimming |
| --start | Start time for trimming (in seconds or HH:MM:SS format) |
| --end | End time for trimming (in seconds or HH:MM:SS format) |
| --watermark-image | Path to image file to use as watermark |
| --watermark-text | Text to use as watermark |
| --watermark-position | Position of the watermark (topLeft, topRight, bottomLeft, bottomRight, center) |
| --watermark-opacity | Opacity of the watermark (0.0 to 1.0) |
| --watermark-margin | Margin from the edge in pixels |
| --watermark-font-size | Font size for text watermark in pixels |
| --watermark-font-color | Font color for text watermark |
| --watermark-font | Path to font file for text watermark |
| --watermark-box-color | Background box color for text watermark |
| --path | Path to directory containing media files for batch processing |
| --recursive | Recursively process files in subdirectories (for batch processing) |
| --output-dir | Output directory for batch processed files |
| --output-prefix | Prefix to add to output filenames (for batch processing) |
| --output-suffix | Suffix to add to output filenames (for batch processing) |
| --output-extension | Extension for output files (for batch processing) |
| --media-types | Media types to process (for batch processing) |
| --concurrency | Number of files to process concurrently (for batch processing) |
| --fancy-ui | Use fancy terminal UI for batch processing |
| --ffmpeg-args | Pass custom arguments directly to ffmpeg (e.g., "--ffmpeg-args='-vf eq=brightness=0.1'") |
| --verbose, -v | Show detailed progress information |
| --help, -? | Show help |

#### Installation

The CLI tool is automatically installed when you install the package:

`bash


Install globally

npm install -g @profullstack/transcoder

Now you can use the 'transcoder' command from anywhere

transcoder input.mp4 output.mp4 --preset youtube-hd

Or use npx without installing

npx @profullstack/transcoder input.mp4 output.mp4 --preset youtube-hd
`

When installed globally, you can use the transcoder command from any directory:

`bash


Basic usage

transcoder input.mp4 output.mp4

With options

transcoder input.mp4 output.mp4 --preset youtube-hd --thumbnails 3

Generate thumbnails only

transcoder --thumbnails-only input.mp4 --count 5

Batch processing

transcoder --path ./videos --preset web --output-dir ./processed
`

API Reference

$3

Transcodes a video file to web-friendly MP4 format.

Parameters:

- inputPath (string): Path to the input video file
- outputPath (string): Path where the transcoded video will be saved
- options (object, optional): Transcoding options or preset name
- Can include a preset property with one of the predefined platform presets
- Can include a thumbnails property for generating thumbnails during transcoding

Returns:

- Promise that resolves with an object containing:
- outputPath (string): Path to the transcoded video
- emitter (TranscodeEmitter): Event emitter for progress tracking
- thumbnails (Array, optional): Array of thumbnail paths if thumbnails were requested
- metadata (Object, optional): Video metadata extracted from the input file
- format: Format information (duration, size, bitrate, etc.)
- video: Video stream information (codec, resolution, fps, etc.)
- audio: Audio stream information (codec, sample rate, channels, etc.)

$3

Transcodes an audio file to another format with various enhancements. Can also extract audio from video files.

Parameters:

- inputPath (string): Path to the input audio or video file
- outputPath (string): Path where the transcoded audio will be saved
- options (object, optional): Transcoding options or preset name
- Can include a preset property with one of the predefined audio presets
- Can include audio enhancement options like normalize, fadeIn, fadeOut, etc.

Returns:

- Promise that resolves with an object containing:
- outputPath (string): Path to the transcoded audio
- emitter (TranscodeEmitter): Event emitter for progress tracking
- metadata (Object, optional): Audio metadata extracted from the input file
- format: Format information (duration, size, bitrate, etc.)
- audio: Audio stream information (codec, sample rate, channels, etc.)

$3

Transcodes an image file to another format with various transformations.

Parameters:

- inputPath (string): Path to the input image file
- outputPath (string): Path where the transcoded image will be saved
- options (object, optional): Transcoding options or preset name
- Can include a preset property with one of the predefined image presets
- Can include transformation options like resize, rotate, crop, squarePad, etc.
- squarePad (boolean): Convert rectangular image to square with padding
- padColor (string): Color for padding (e.g., 'transparent', 'white', 'black')
- padSize (number): Additional padding size in pixels

Returns:

- Promise that resolves with an object containing:
- outputPath (string): Path to the transcoded image
- emitter (TranscodeEmitter): Event emitter for progress tracking
- metadata (Object, optional): Image metadata extracted from the input file
- format: Format information (size, format name, etc.)
- image: Image information (width, height, codec, etc.)

$3

Transcodes multiple images in batch with shared global options.

Parameters:

- items (Array