A powerful subtitle file converter that ensures proper UTF-8 encoding with robust support for Arabic and other languages. SubZilla automatically detects the input file encoding and converts it to UTF-8, making it perfect for fixing subtitle encoding issues. Built with SOLID, YAGNI, KISS, and DRY principles in mind.
- Automatic encoding detection that stays accurate on markup-heavy files (detection runs on the dialogue text only, so
<font>tags and timestamps cannot out-vote a windows-1256 Arabic payload). - Converts subtitle files to UTF-8.
- Supports multiple subtitle formats (
.srt,.sub,.ass,.ssa,.txt). - Strong support for Arabic and other non-Latin scripts: removing formatting never glues two words together (
<br>,<p>/<div>, , ASS\Nand exotic Unicode line breaks all become real separators) and never splits a cue. - Strips HTML, Markdown, ASS/SSA styles and colors, and bidirectional control characters.
- Simple command-line interface.
- Native macOS desktop application with drag-and-drop for files and whole folders.
- Batch processing with glob pattern support.
- Parallel processing for better performance.
- Preserves original file formatting.
- Creates backup of original files.
- Node.js (v14 or higher)
- Yarn package manager
# Install globally using yarn
yarn global add subzilla
# Or using npm
npm install -g subzilla# Clone the repository
git clone https://github.com/onyxdevs/subzilla.git
cd subzilla
# Install dependencies (installs all workspace packages)
yarn install
# Build all packages
yarn build
# Run the CLI
yarn start
# Development mode (watch for changes)
yarn dev# Convert a single subtitle file
subzilla convert path/to/subtitle.srt
# The converted file will be saved as path/to/subtitle.utf8.srt
# Strip HTML formatting
subzilla convert input.srt --strip-html
# Strip color codes
subzilla convert input.srt --strip-colors
# Strip style tags
subzilla convert input.srt --strip-styles
# Replace URLs with [URL]
subzilla convert input.srt --strip-urls
# Strip all formatting
subzilla convert input.srt --strip-all
# Create backup and strip formatting
subzilla convert input.srt -b --strip-all
# Create numbered backups instead of overwriting existing backup
subzilla convert input.srt -b --no-overwrite-backup
# Combine multiple strip options
subzilla convert input.srt --strip-html --strip-colorsConvert multiple subtitle files at once using glob patterns:
# Convert all .srt files in current directory
subzilla batch "*.srt"
# Convert files recursively in all subdirectories
subzilla batch "**/*.srt" -r
# Convert multiple formats
subzilla batch "**/*.{srt,sub,txt}" -r
# Specify output directory
subzilla batch "**/*.srt" -o converted/
# Process files in parallel for better performance
subzilla batch "**/*.srt" -p
# Skip existing UTF-8 files
subzilla batch "**/*.srt" -s
# Combine basic options for maximum efficiency
subzilla batch "**/*.{srt,sub,txt}" -r -p -s -o converted/
# Advanced Directory Processing
# Limit recursive depth to 2 levels
subzilla batch "**/*.srt" -r -d 2
# Only process files in specific directories
subzilla batch "**/*.srt" -r -i "movies" "series"
# Exclude specific directories
subzilla batch "**/*.srt" -r -x "temp" "backup"
# Preserve directory structure in output
subzilla batch "**/*.srt" -r -o converted/ --preserve-structure
# Complex example combining all features
subzilla batch "**/*.{srt,sub,txt}" -r -p -s -o converted/ \
-d 3 -i "movies" "series" -x "temp" "backup" --preserve-structure
# Strip formatting in batch mode
subzilla batch "**/*.srt" -r --strip-all
# Strip specific formatting in batch mode
subzilla batch "**/*.srt" -r --strip-html --strip-colors
# Create backups and strip formatting
subzilla batch "**/*.srt" -r -b --strip-all
# Create numbered backups instead of overwriting existing ones
subzilla batch "**/*.srt" -r -b --no-overwrite-backup --strip-all
# Complex example with formatting options
subzilla batch "**/*.{srt,sub,txt}" -r -p -s -o converted/ \
-d 3 -i "movies" "series" -x "temp" "backup" \
--preserve-structure --strip-all -bOptions:
-o, --output-dir <dir>: Save converted files to specified directory.-r, --recursive: Search for files in subdirectories.-p, --parallel: Process files in parallel (faster for many files).-s, --skip-existing: Skip files that already have a UTF-8 version.-d, --max-depth <depth>: Maximum directory depth for recursive search.-i, --include-dirs <dirs...>: Only process files in these directories.-x, --exclude-dirs <dirs...>: Exclude files in these directories.--preserve-structure: Preserve directory structure in output.-b, --backup: Create backup of original files.--no-overwrite-backup: Create numbered backups instead of overwriting existing backup.--strip-html: Strip HTML tags (block tags and<br>become line breaks, entities like are decoded).--strip-markdown: Strip Markdown formatting (**bold**,*italic*,~~strike~~,`code`,[text](url),## headings). Subtitle conventions that merely look like Markdown — dialogue dashes,# song lyrics #,f**k,>> Speaker:— are left alone.--strip-colors: Strip color codes.--strip-styles: Strip style tags.--strip-urls: Replace URLs with [URL].--strip-all: Strip all formatting (equivalent to all strip options).
Features:
- Progress bar showing conversion status.
- Per-directory progress tracking.
- Detailed statistics after completion.
- Error tracking and reporting.
- Parallel processing support.
- Skip existing files option.
- Time tracking and performance metrics.
- Directory structure preservation.
- Directory filtering and depth control.
- HTML tag stripping.
- Markdown stripping.
- Color code removal.
- Style tag removal.
- URL replacement.
- Whitespace normalization.
- Original file backup.
Example Output:
🔍 Found 25 files in 5 directories...
Converting |==========| 100% | 25/25 | Total Progress
Converting |==========| 100% | 8/8 | Processing movies
Converting |==========| 100% | 7/7 | Processing series/season1
Converting |==========| 100% | 5/5 | Processing series/season2
Converting |==========| 100% | 3/3 | Processing series/specials
Converting |==========| 100% | 2/2 | Processing extras
📊 Batch Processing Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━
Total files processed: 25
Directories processed: 5
✅ Successfully converted: 23
❌ Failed: 1
⏭️ Skipped: 1
⏱️ Total time: 5.32s
⚡ Average time per file: 0.22s
📂 Directory Statistics:
━━━━━━━━━━━━━━━━━━━━
movies:
Total: 8
✅ Success: 8
❌ Failed: 0
⏭️ Skipped: 0
series/season1:
Total: 7
✅ Success: 6
❌ Failed: 1
⏭️ Skipped: 0
series/season2:
Total: 5
✅ Success: 5
❌ Failed: 0
⏭️ Skipped: 0
series/specials:
Total: 3
✅ Success: 2
❌ Failed: 0
⏭️ Skipped: 1
extras:
Total: 2
✅ Success: 2
❌ Failed: 0
⏭️ Skipped: 0
❌ Errors:
━━━━━━━━━
series/season1/broken.srt: Failed to detect encoding
SubZilla provides flexible backup options to protect your original files:
# Basic backup creation
subzilla convert input.srt -b
# By default, subsequent runs overwrite the existing backup
# First run: creates input.srt.bak
# Second run: overwrites input.srt.bak (clean, no accumulation)
# Create numbered backups instead (legacy behavior)
subzilla convert input.srt -b --no-overwrite-backup
# First run: creates input.srt.bak
# Second run: creates input.srt.bak.1
# Third run: creates input.srt.bak.2
# Configure backup behavior in config file
# .subzillarc:
# output:
# createBackup: true
# overwriteBackup: false # Creates numbered backupsBackup Behavior Summary:
overwriteBackup: true(default): Clean backup management - always overwrites existing backupoverwriteBackup: false: Legacy behavior - creates numbered backups (.bak.1,.bak.2, etc.)- CLI override: Use
--no-overwrite-backupto temporarily disable backup overwriting
# Specify output file (single file conversion)
subzilla convert input.srt -o output.srt
# Get help
subzilla --help
# Get version
subzilla --version
# Get help for specific command
subzilla convert --help
subzilla batch --helpSubZilla includes a native macOS desktop application built with Electron, featuring a drag-and-drop interface for easy subtitle conversion.
Grab the latest .dmg from the releases page: Subzilla-<version>-arm64.dmg for Apple Silicon, Subzilla-<version>.dmg for Intel.
The app is not signed with an Apple Developer ID (it is ad-hoc signed, so its signature is valid but not tied to a verified developer), so macOS blocks it on first launch. Open it once via System Settings → Privacy & Security → Open Anyway (or run xattr -cr /Applications/Subzilla.app). For the same reason the built-in auto-updater cannot install updates on its own; download new versions from the releases page.
Development Mode:
# Build all packages first
yarn build
# Run the Mac app in development mode
yarn workspace @subzilla/mac devBuilding for Distribution: