Skip to content
onyxdevsPublic

About

A powerful subtitle file converter that ensures proper UTF-8 encoding. Supports multiple subtitle formats with a simple command-line interface and flexible configuration.

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Repository files navigation

SubZilla 🦎

CI License: ISC Latest release

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.

Features ✨

  • 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>, &nbsp;, ASS \N and 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.

Installation 🚀

Prerequisites

  • Node.js (v14 or higher)
  • Yarn package manager

Global Installation

# Install globally using yarn
yarn global add subzilla

# Or using npm
npm install -g subzilla

Local Development Setup

# 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

Usage 💻

Basic Usage

# 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-colors

Batch Processing

Convert 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 -b

Options:

  • -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 &nbsp; 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

Backup Management

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 backups

Backup Behavior Summary:

  • overwriteBackup: true (default): Clean backup management - always overwrites existing backup
  • overwriteBackup: false: Legacy behavior - creates numbered backups (.bak.1, .bak.2, etc.)
  • CLI override: Use --no-overwrite-backup to temporarily disable backup overwriting

Advanced Options

# 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 --help

Mac App 🖥️

SubZilla includes a native macOS desktop application built with Electron, featuring a drag-and-drop interface for easy subtitle conversion.

Download

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.

Running the Mac App

Development Mode:

# Build all packages first
yarn build

# Run the Mac app in development mode
yarn workspace @subzilla/mac dev

Building for Distribution: