npm package: @t-agent/subtitle-burner
Description: Extract and burn subtitles from MP4 videos with customizable font size
Latest version: 1.0.0

# 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
```bash
npm install -g subtitle-burner
```

### Local Installation
```bash
npm install subtitle-burner
```

## Prerequisites

- [FFmpeg](https://ffmpeg.org/) must be installed and available in your PATH
- Node.js 14.0.0 or higher

### Install FFmpeg

**macOS:**
```bash
brew install ffmpeg
```

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

**Windows:**
Download from [FFmpeg official website](https://ffmpeg.org/download.html) and add to PATH.

## Usage

### Basic Usage
```bash
subtitle-burner -i video.mp4
```

### Custom Font Size
```bash
subtitle-burner -i video.mp4 -f 16
```

### Custom Output File
```bash
subtitle-burner -i video.mp4 -o output-video.mp4
```

### Keep Temporary Files
```bash
subtitle-burner -i video.mp4 --keep-temp
```

### Custom Temporary Directory
```bash
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)
```bash
subtitle-burner -i "my-video.mp4"
```

### Process with larger font (18px)
```bash
subtitle-burner -i "my-video.mp4" -f 18
```

### Process with custom output path
```bash
subtitle-burner -i "my-video.mp4" -o "final-video.mp4"
```

### Process video for social media (smaller font)
```bash
subtitle-burner -i "my-video.mp4" -f 12 -o "social-media-video.mp4"
```

## Programmatic Usage

```javascript
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.