A powerful Python tool with GUI for automatically hard-coding subtitles into video files using FFmpeg
Features • Installation • Usage • Configuration • Contributing
- Overview
- Features
- Prerequisites
- Installation
- Usage
- Configuration Options
- Supported Formats
- Examples
- Progress Tracking
- Troubleshooting
- Version History
- Contributing
- License
HardSubber Automator is a sophisticated Python application with both GUI and command-line interfaces that automatically matches video files with their corresponding subtitle files and hard-codes the subtitles directly into the video using FFmpeg. The tool features intelligent subtitle matching, real-time progress tracking, advanced subtitle customization, and flexible configuration options.
- 🖥️ Modern GUI Interface: User-friendly PyQt6-based graphical interface with drag-and-drop support
- 🔍 Intelligent Subtitle Matching: Automatically finds matching subtitle files using fuzzy string matching
- 📊 Real-time Progress Tracking: Live progress bar with ETA and file size monitoring
- 🎨 Advanced Subtitle Customization: Font, color, border, and positioning controls with live preview
- ⚙️ Flexible Configuration: Customizable encoding speeds, quality settings, and file locations
- 🎯 Manual Override: Manual subtitle selection when automatic matching fails
- 📁 Batch Processing: Process multiple video files in one run
- 💾 Size Monitoring: Track input vs output file sizes
- 🔄 Restart Capability: Easy restart functionality after completion
- 💾 Save/Load Configurations: Save and load your preferred settings
Before using HardSubber Automator, ensure you have:
- Python 3.6+ installed on your system
- FFmpeg installed and accessible from command line
- Video files and corresponding subtitle files in supported formats
- PyQt6 for GUI functionality (automatically installed)
# Using Chocolatey
choco install ffmpeg
# Or download from https://ffmpeg.org/download.html# Using Homebrew
brew install ffmpeg# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# CentOS/RHEL
sudo yum install ffmpeg-
Clone the repository:
git clone https://github.com/yourusername/hardsubber-automator.git cd hardsubber-automator -
Install dependencies:
pip install PyQt6 qtawesome pillow
-
Verify FFmpeg installation:
ffmpeg -version
-
Run the application:
# GUI Version (Recommended) python Hardsubber_V4_GUI.py # Command Line Version python Hardsubber_V3.5.py
- Launch the GUI: Run
python Hardsubber_V4_GUI.py - Load Videos: Click "Browse" to select your video folder or drag-and-drop files
- Configure Settings: Use the Advanced Settings to customize subtitle appearance
- Preview: Use the built-in video preview to see how subtitles will look
- Process: Click "Start Processing" to begin hardsubbing
- Monitor Progress: Watch real-time progress with ETA and file size info
- Place your files: Put video files and subtitle files in the same directory
- Run the script: Execute
python Hardsubber_V3.5.py - Configure settings: Choose encoding speed and file locations
- Monitor progress: Watch the real-time progress bar
- Collect output: Find your hard-subbed videos with
_subbed.mp4suffix
# Your folder structure should look like:
📁 MyVideos/
├── Episode01.mp4
├── Episode01.srt
├── Episode02.mkv
├── Episode02.vtt
└── Hardsubber_V4_GUI.py
# Run the GUI
python Hardsubber_V4_GUI.py| Speed | Quality | File Size | Processing Time |
|---|---|---|---|
| Slow | Highest | Smallest | Longest |
| Medium (default) | High | Moderate | Moderate |
| Fast | Good | Large | Fast |
| Ultrafast | Lower | Largest | Fastest |
- Font: Choose from system fonts with size control
- Color: Full color picker with transparency support
- Border: Customizable border thickness and color
- Position: Adjust subtitle placement on screen
- Quality: CRF (Constant Rate Factor) control for output quality
- Automatic: Uses current working directory
- Manual Input: Specify custom input directory
- Manual Output: Specify custom output directory
.mp4- MPEG-4 Video.mkv- Matroska Video.mov- QuickTime Movie.avi- Audio Video Interleave.wmv- Windows Media Video.flv- Flash Video.webm- WebM Video
.srt- SubRip Subtitle.vtt- WebVTT Subtitle
Input Files:
- Movie.mp4
- Movie.srt
Output:
- Movie_subbed.mp4 (with hard-coded subtitles)
Input Files:
- Episode1-720p.mp4
- episode1 english.srt
Result: ✅ Automatically matched despite different naming
Input Files:
- Show_S01E01.mkv
- Sub1.srt
- Sub2.srt
- Sub3.srt
Process: GUI will allow you to manually select the correct subtitle
The latest version includes comprehensive progress tracking:
Processing: Episode01.mp4 + Episode01.srt |========================================----------| 80%
E.T.A: 00:02:15 | Out: 145.3MB (120.5%)
Progress Information:
- Progress Bar: Visual representation of encoding progress
- Percentage: Current completion percentage
- ETA: Estimated time remaining
- Output Size: Current output file size
- Size Ratio: Output size compared to input (video + subtitle)
Error: 'ffmpeg' is not recognized as an internal or external command
Solution: Install FFmpeg and ensure it's in your system PATH
ModuleNotFoundError: No module named 'PyQt6'
Solution: Install PyQt6 with pip install PyQt6 qtawesome
(;_;) About to skip: Movie.mp4 (No matching subtitle found)
Solution:
- Check subtitle file naming
- Use manual selection in GUI
- Ensure subtitle files are in supported formats
Error: Permission denied when writing output file
Solution:
- Check write permissions in output directory
- Run as administrator if necessary
- Ensure output directory exists
✅ Good Examples:
Movie.mp4 ↔ Movie.srt
Episode_01.mkv ↔ Episode_01.vtt
Show-S01E01-720p.mp4 ↔ Show-S01E01-English.srt
❌ Problematic Examples:
Movie.mp4 ↔ Subtitle.srt (too different)
Video1.mp4 ↔ Sub2.srt (numbers don't match)
- 🎨 NEW: Modern PyQt6-based GUI interface
- 🎬 NEW: Built-in video preview with subtitle overlay
- 🎨 NEW: Advanced subtitle customization (fonts, colors, borders)
- 💾 NEW: Save/Load configuration profiles
- 📁 NEW: Drag-and-drop file support
- 🔊 NEW: Audio feedback for completion
- 📊 NEW: Enhanced progress tracking in GUI
- ✅ Real-time progress tracking with FFmpeg integration
- ✅ File size monitoring and comparison
- ✅ Improved error handling and user feedback
- ✅ Better filename sanitization for cross-platform compatibility
- ✅ Enhanced progress bar with animations
- ✅ Improved user interface with colored output
- ✅ Better subtitle matching algorithm
- ✅ Basic functionality with FFmpeg integration
- ✅ Fuzzy string matching for subtitle files
- ✅ Manual subtitle selection option
We welcome contributions! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow PEP 8 style guidelines
- Add comments for complex logic
- Test with multiple video/subtitle format combinations
- Update documentation for new features
- Test both GUI and command-line interfaces
This project is licensed under the MIT License - see the LICENSE file for details.
Nexus // MD_nexus
- GitHub: @MD-nexus
- Email: [Contact via GitHub]
- FFmpeg team for the powerful multimedia framework
- Qt/PyQt6 team for the excellent GUI framework
- Python community for excellent libraries
- Contributors and users for feedback and improvements
Made with ❤️ by Nexus