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

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

Support

If you encounter any issues:

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

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