subtitle-burner-cli

Subtitle Burner

A Node.js CLI tool to extract subtitles from MP4 videos and burn them into the video with customizable font size.

Features

• 🎬 Extract embedded subtitles from MP4 videos
• 🔥 Burn subtitles directly into video frames
• 🎨 Customizable font size (default: 14px)
• 📁 Automatic output file naming
• 🧹 Temporary file cleanup
• 🎯 Perfect for social media platforms (Xiaohongshu, Douyin, etc.)

Installation

Global Installation

npm install -g subtitle-burner

Local Installation

npm install subtitle-burner

Prerequisites

• FFmpeg must be installed and available in your PATH
• Node.js 14.0.0 or higher

Install FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Windows: Download from FFmpeg official website and add to PATH.

Usage

Basic Usage

subtitle-burner -i video.mp4

Custom Font Size

subtitle-burner -i video.mp4 -f 16

Custom Output File

subtitle-burner -i video.mp4 -o output-video.mp4

Keep Temporary Files

subtitle-burner -i video.mp4 --keep-temp

Custom Temporary Directory

subtitle-burner -i video.mp4 --temp-dir ./my-temp

Command Line Options

Option	Alias	Description	Default
--input	-i	Input MP4 file path	Required
--output	-o	Output MP4 file path	Auto-generated
--fontsize	-f	Subtitle font size	14
--temp-dir		Temporary directory for subtitle extraction	./temp
--keep-temp		Keep temporary subtitle files	false
--help	-h	Show help
--version	-V	Show version number

Output Naming

If no output file is specified, the tool will automatically generate a name:

• Input: video.mp4
• Output: video-burned-fs14.mp4 (with 14px font)

Examples

Process a video with default settings (14px font)

subtitle-burner -i "my-video.mp4"

Process with larger font (18px)

subtitle-burner -i "my-video.mp4" -f 18

Process with custom output path

subtitle-burner -i "my-video.mp4" -o "final-video.mp4"

Process video for social media (smaller font)

subtitle-burner -i "my-video.mp4" -f 12 -o "social-media-video.mp4"

Programmatic Usage

const { extractSubtitles, burnSubtitles } = require('subtitle-burner');

async function processVideo() {
  try {
    // Extract subtitles
    const subtitleFile = await extractSubtitles('input.mp4', './temp');
    
    // Burn subtitles with custom font size
    const outputFile = await burnSubtitles('input.mp4', subtitleFile, 'output.mp4', 16);
    
    console.log('Processing complete:', outputFile);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

processVideo();

Font Size Recommendations

• 12px: Ideal for social media platforms
• 14px: Default, good balance
• 16px: Better for mobile viewing
• 18px: Large, accessible option
• 20px: Very large, for accessibility

Error Handling

The tool will check for:

• FFmpeg availability
• Input file existence
• Valid subtitle streams in the video
• Write permissions for output directory

License

MIT License - see LICENSE file for details.

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Support

If you encounter any issues:

• Make sure FFmpeg is properly installed
• Check that your input video contains subtitles
• Verify write permissions for the output directory

Create an issue on GitHub for bug reports or feature requests.