Skip to content
omerninyoPublic

About

🎬 Smart AI Subtitle Translation & Mastering Suite (Windows & macOS). Multi-agent Hebrew translation, Plex BiDi repair, SDH cleaning & audio sync.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

143 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

RightSub β€” Universal Subtitle Mastering & Translation Suite

🎬 RightSub β€” Universal Subtitle Mastering & Translation Suite

Language / Χ©Χ€Χ”: English | Χ’Χ‘Χ¨Χ™Χͺ

License: MIT Python 3.9+ Platform: Windows & macOS Plex & Infuse Verified Tests: 100% Pass Web App: 100% Local Browser Fixer Benchmark: 101/101 Episodes

Subtitles Done Right β€” from Instant Browser & 1-Click Plex BiDi Repair to Autonomous Multi-Agent AI Translation.

🌐 New in v1.5.0 β€” Official Web App & Instant Browser .srt Master: Fix broken Hebrew .srt files directly in your browser with 0 installation and 100% client-side privacy via rightsub.ninyo.co (or locally at http://localhost:8775/ui when running rightsub serve). Includes a live single-line BiDi sandbox and free-text natural-language Troubleshooting & Solution Finder (#help).

RightSub is a high-performance CLI suite and Python framework designed to repair, clean, synchronize, translate, and format subtitles for ANY movie or television series across Windows and macOS.

Whether you want to fix reversed question marks in Plex on your Apple TV, convert unreadable Windows-1255 CP1255 Hebrew gibberish to clean UTF-8, strip annoying [MUSIC PLAYING] noise cues, fix framerate sync drifts, or translate an entire TV season using AI agents, RightSub gives you a dead-simple, reliable workflow.


⚑ Quickstart in 30 Seconds

Got a video or subtitle file that needs fixing or translation? You only need one command.

Type rightsub auto and simply drag & drop the file or folder into your terminal:

Windows (Command Prompt / PowerShell):

rightsub auto "C:\Movies\Inception.he.srt"
:: Or for an entire TV season:
rightsub auto "C:\TV Shows\Breaking Bad Season 1"

macOS / Linux (Terminal):

rightsub auto ~/Movies/Inception.he.srt
# Or for an entire TV season:
rightsub auto ~/Movies/Breaking_Bad_S01/

What happens automatically?

  • Content-Based Hebrew .srt Discovery & Seed-Safe Torrent Protection: RightSub does not rely only on .he.srt filenames. It inspects the content of every .srt file (including plain Movie.srt, Movie.heb.srt, or Subs/*.srt in UTF-8 or CP1255). When a Hebrew .srt lacks the .he.srt suffix, RightSub leaves the original .srt 100% untouched on disk (preserving torrent hashes for seeding) and writes the fixed output to a separate Movie.he.srt file.
  • Hebrew Subtitle Mastering (.srt $\rightarrow$ .he.srt): Instantly fixes reversed punctuation (? ! .), un-flips legacy Subabi visual reversals, converts legacy encodings to UTF-8, strips ads, and masters the file for Plex & Infuse (\u200F UAX #9 Rule N1).
  • Video File (.mkv / .mp4): Extracts embedded subtitles, transcribes audio if needed, and builds AI-ready translation waves.
  • Home Media Automation (Set-and-Forget): Plug RightSub into qBittorrent, Sonarr, Radarr, Bazarr, or Transmission to run seamlessly in the background without needing a heavy 24/7 daemon. See Home Media Integrations Guide.

🎯 Choose Your Track (Deterministic vs. AI Decision Matrix)

RightSub strictly separates technical mastering (0% AI) from translation & rare semantic rehabilitation (AI-assisted) based on the task and whether an AI API key is configured:

Track 1: Fix Existing Subtitles (100% Deterministic, Offline & Free β€” 99% of Existing Subtitles)

No AI required. No API keys. Zero cloud bandwidth. Never alters intact human phrasing.

  • Automatic Content Detection & Seed-Safe .he.srt Creation: Detects any .srt with Hebrew text, keeps the original torrent .srt untouched, and saves the fixed .he.srt separately.
  • 3-Stage Canonical BiDi & Un-Flipping Engine: Reverses 18 legacy visual-flipping (Subabi) patterns and wraps lines with leading and trailing RLM (\u200F) after trailing punctuation (UAX #9 Rule N1) for Apple TV, Android TV, LG WebOS, Infuse, and VLC.
  • Bilingual Deterministic Cross-Check (0 AI): When a companion .en.srt is present, deterministically un-flips reversed 2-digit numbers (84 $\rightarrow$ 48 verified against the English cue) and validates structural cue alignment (validate_anchor_alignment).
  • Encoding & Homoglyph Rescue: Automatically converts CP1255 / Windows-1255 / ISO-8859-8 to UTF-8 and repairs foreign homoglyphs (Arabic, Cyrillic, Georgian, Greek) with conditional final-letter safety.
  • SDH & Ad Stripper: Removes translator watermarks, promo URLs, and multi-line credits.

πŸ’‘ When is an AI Key used on existing subtitles (rightsub polish)?
For 99% of normal human subtitles (Wizdom, Ktuvit, Subscenter), Track 1 (0 AI tokens) is all you ever need. An AI key in rightsub polish is used only for rare edge cases β€” specifically very old, OCR-corrupted (PGS/VobSub), or low-quality machine translations that suffer from pervasive grammatical gender errors or severe terminology drift. If no AI key is configured, rightsub polish automatically runs in 100% deterministic offline mode.

# Recommended autonomous fix (detects plain .srt, protects torrents, creates .he.srt):
rightsub auto "C:\Movies\Season 01"

# Direct BiDi fix:
rightsub fix-plex ~/Movies/Season_01 --recursive --clean-ads

Track 2: Translate English Media to Hebrew with AI

Translate entire movies or 24-episode seasons with full character context and zero hallucinations.

RightSub structures the translation process so you can use any AI model or assistant you already have:

  1. Prepare Batches & Context:

    rightsub auto "Movie.mkv"

    RightSub splits dialogue into optimal ~210-cue batches, resolves character genders via TMDb (e.g. אΧͺ/היא vs אΧͺΧ”/הוא), and produces ready-to-use prompts.

  2. Translate with Your AI Assistant:

    • Coding AI Agents: Antigravity, Claude Code, Cursor, Codex β€” paste the generated wave prompts.
    • Free Local LLM (100% Offline): Run with Ollama using:
      rightsub auto "Movie.mkv" --ollama
  3. Auto-Merge & Validate: RightSub automatically merges translated JSON batches back into a pristine .he.srt file, enforces 1:1 line matching, and applies full BiDi formatting.


πŸ”„ Home Media Automation & Integrations (Set-and-Forget)

Key Integrations & Keywords: qBittorrent β€’ Sonarr β€’ Radarr β€’ Bazarr β€’ Transmission β€’ Tautulli/Plex β€’ Background Watchers & Daemons β€’ Seed-Safe

RightSub is engineered to integrate natively into automated home media and seedbox stacks in a 100% hands-off workflow.

The Recommended 2-Phase Strategy

  1. Retroactive Batch Fix (Run Once): Clean and master your entire existing media library:
    # Windows:
    rightsub auto "C:\Media\TV Shows"
    
    # macOS / Linux:
    rightsub auto /Volumes/Media/TV_Shows
  2. Ongoing Event-Driven Ingress (Set-and-Forget): Attach RightSub to your downloaders or *arr managers to process new media the millisecond it finishes downloading.

Why Event-Driven Hooks Beat a 24/7 Background Daemon

Unlike heavy background daemons that poll filesystems 24/7 and risk corrupting multi-gigabyte files while they are still being written, RightSub's Event-Driven Hook Architecture operates with:

  • πŸ›‘οΈ Zero Race Conditions: Executes only on completed, hash-verified files.
  • ⚑ Zero Idle Overhead: 0% CPU and 0 MB RAM when idle.
  • πŸ”’ Seed-Safe by Default: Duplicates into .he.srt, leaving original downloaded torrent files 100% bit-for-bit intact so active seeding never breaks.

🐳 Native Docker & Webhook Daemon (rightsub serve)

For containerized NAS environments (Unraid, TrueNAS SCALE, Synology DSM, Docker Compose) where running host scripts is impossible, RightSub includes a native HTTP Webhook server consuming under 15 MB RAM:

# Run standalone daemon:
rightsub serve --port 8775 --path-map "/data/media:/media"

# Or deploy via Docker Compose:
docker compose up -d
  • Sonarr Webhook URL: http://rightsub:8775/webhook/sonarr (Triggers: On Download, On Upgrade)
  • Radarr Webhook URL: http://rightsub:8775/webhook/radarr (Triggers: On Download, On Movie Imported)
  • Bazarr Webhook URL: http://rightsub:8775/webhook/bazarr (Triggers: On Subtitles Download)
  • Automatic Path Translation: PATH_MAP="/data/media:/media" bridges container volume differences.

πŸ‘‰ Read the full Home Media & Download Integrations Guide for copy-pasteable configurations for qBittorrent, Sonarr, Radarr, Bazarr, Transmission, and native OS Folder Watchers.


πŸ“¦ Installation & Setup

RightSub offers equal, first-class support for both Windows and macOS/Linux:

Windows (CMD / PowerShell)

  1. Clone or Download the repository:
    git clone https://github.com/omerninyo/RightSub.git
    cd RightSub
  2. Run the Windows Installer: Double-click install.bat (or execute it in CMD):
    install.bat
    The installer verifies Python 3, installs dependencies from requirements.txt, and prepares global wrappers.
  3. Run from anywhere: Use rightsub.bat or python rightsub.py:
    rightsub auto "Movie.mkv"

macOS / Linux (Terminal)

Choose any of the following 3 options:

  • Option A: Official Homebrew Tap (Recommended for macOS): Instant 1-second installation via pre-packaged universal bottles (supports both Apple Silicon & Intel):

    brew tap omerninyo/tap
    brew install rightsub
  • Option B: Fast Local Clone:

    git clone https://github.com/omerninyo/RightSub.git
    cd RightSub
    ./install.sh

    Symlinks rightsub globally to ~/.local/bin/rightsub.

  • Option C: One-Liner Remote Script:

    curl -fsSL https://raw.githubusercontent.com/omerninyo/RightSub/main/install.sh | bash

πŸ’» Everyday CLI Recipes

Recipe 0: Autonomous One-Command Runner (Zero Flags / Zero Hassle)

# Auto-repair Hebrew subtitle (BiDi RLM, ad stripping, automatic backup):
rightsub auto "Movie.he.srt"

# Auto-process video file (extract/transcribe subtitles and build batches):
rightsub auto "Movie.mkv"

# 100% offline, free local translation using Ollama (Llama 3, Qwen):
rightsub auto "Movie.mkv" --ollama

# Auto-scan and process entire TV season or complete media library:
rightsub auto "/path/to/Season 01/"

Recipe 1: Standalone Hebrew Fix for Plex / Infuse Library

# Option A: Fix a single file in-place:
rightsub fix-plex "Movie.he.srt" --in-place

# Option B: Fix multiple specific files:
rightsub fix-plex "Ep01.he.srt" "Ep02.he.srt" "Ep03.he.srt" --in-place

# Option C: Preview changes safely on a whole folder (Dry Run):
rightsub fix-plex /path/to/TV_Shows/ --recursive --clean-ads --dry-run

# Option D: Apply in-place recursively with automatic backups (.srt.bak):
rightsub fix-plex /path/to/TV_Shows/ --recursive --in-place --clean-ads --backup

Recipe 2: Extract Embedded Subtitles from Video Containers

rightsub extract "Movie.mkv" -o "Movie.en.srt" --lang eng

Recipe 3: Fix 25 FPS to 23.976 FPS (Framerate Desync)

Stretch subtitles extracted from PAL DVDs or European TV to match US Web-DL / BluRay rips:

rightsub adjust-fps "PAL_sub.srt" -o "synced_sub.srt"

Recipe 4: Translate a Movie or Episode with AI

# 1. Generate translation batches and agent wave prompts:
rightsub prompt-gen "Episode01.en.srt" -t "Inception" -g "Sci-Fi Action"

# 2. Merge translated JSON batches into final Hebrew SRT with full SubRefine BiDi:
rightsub merge "Episode01.en.srt" "prompts_Inception" -o "Episode01.he.srt"

# 3. Run comprehensive Red Team QA audit:
rightsub qa "Episode01.en.srt" "Episode01.he.srt"

Recipe 5: Semantic AI Proofreading & Subtitle QC (rightsub polish)

Modernize and proofread an existing Hebrew subtitle without re-translating from scratch (preserves 85%–90% of intact lines):

# Option A: Polish existing Hebrew subtitle directly against media container:
rightsub polish "Star Wars (1977).mkv"

# Option B: Polish specific Hebrew subtitle against companion English master:
rightsub polish "Movie.he.srt" --en "Movie.en.srt"

# Option C: Dry run generating a Markdown diff report without altering files:
rightsub polish "Movie.he.srt" --diff-only

# Option D: In-place mastering with automatic seed-safe backup (.he.original.srt):
rightsub polish "Movie.he.srt" --in-place

Recipe 6: Interactive Mastering Wizard, End-to-End Setup & Multi-Agent MCP Server

# Launch the Interactive Terminal / Windows CMD Mastering Wizard (Drag & Drop + File Browser):
rightsub
# (or explicitly: rightsub wizard)

# Run the all-in-one Setup, Downloader Hooks & MCP Agent Wizard:
rightsub setup

# Auto-register RightSub's local MCP server across all installed AI agents
# (Antigravity, Claude Desktop, Cursor, Windsurf, Claude Code):
rightsub mcp --install

# Interactive line-by-line diff review when polishing a subtitle ([Y] Approve / [N] Reject / [E] Edit):
rightsub polish "Movie.he.srt" --interactive

# 10-second interactive setup wizard for Gemini & TMDb API keys + downloader hooks:
rightsub config
rightsub config --install-hooks

# End-to-end environment inspector (FFmpeg, Python, Gemini, TMDb, Quicksubs, MCP Agents):
rightsub doctor

πŸ›οΈ Advanced Architecture & Core Engines

For developers and power users, RightSub cleanly separates high-level workflow commands from its two underlying core algorithmic engines:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                           RightSub CLI (rightsub)                       β”‚
β”‚    extract Β· clean Β· fix-plex Β· sync Β· adjust-fps Β· split Β· merge Β· qa  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                     β”‚
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β–Ό                                                       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚     SubRefine Engine            β”‚   β”‚      SubSwarm AI Engine           β”‚
β”‚  (Sanitization & BiDi Core)     β”‚   β”‚   (Multi-Agent Orchestration)     β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€   β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ β€’ SDH Hearing-Impaired Cleaner  β”‚   β”‚ β€’ Optimal SRT Chunker (~210 cues) β”‚
β”‚ β€’ CP1255 / ISO -> UTF-8 Auto    β”‚   β”‚ β€’ Character & Entity Bible Parser β”‚
β”‚ β€’ BiDi / RLM (U+200F) Injection β”‚   β”‚ β€’ Dynamic Minimum Baseline:       β”‚
β”‚ β€’ Cyrillic/Arabic Homoglyphs    β”‚   β”‚   Gemini 3.5 Flash-Lite           β”‚
β”‚ β€’ Hebrew Gershayim (Χ΄) Fix      β”‚   β”‚ β€’ Concurrent Wave Translation     β”‚
β”‚ β€’ Ad & Promo Spam Stripper      β”‚   β”‚ β€’ 1:1 Block Alignment Guarantee   β”‚
β”‚ β€’ Framerate (FPS) Stretcher     β”‚   β”‚ β€’ Red Team QA Zero-Hallucination  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

1. 🧼 The SubRefine Engine (Sanitization, SDH & BiDi)

  • Zero-Reverse Punctuation on Plex & Infuse: Automatically injects invisible Right-to-Left Marks (\u200F / RLM) at line starts and trailing punctuation (?, !, ., :, -), preventing punctuation from flipping to the wrong side of the screen on Apple TV, Android TV, Infuse, and VLC.
  • Hearing-Impaired (SDH) Cleaner: Intelligently removes descriptive auditory noise like [DOOR CLOSES], (CHEERING), β™ͺ Pop music β™ͺ while strictly preserving dialogue timing blocks.
  • Auto-Charset & Mojibake Rescue: Detects legacy Hebrew encodings (Windows-1255 / CP1255 / ISO-8859-8) and seamlessly converts them into clean UTF-8.
  • Homoglyph & Typography Repair: Normalizes accidental Cyrillic (ΠΌ, Ρ€, с) and Arabic letters into native Hebrew characters. Automatically converts standard quotes in Hebrew acronyms into typographic gershayim (e.g., Χ’Χ•"Χ“ βž” Χ’Χ•Χ΄Χ“, ארה"Χ‘ βž” ארה״ב).
  • Ad & Spam Stripper: Cleans watermark lines from release groups, Torec, OpenSubtitles, Wizdom, and Telegram channels.

2. 🐝 The SubSwarm Engine (High-Throughput AI Translation)

  • Concurrent Agent Waves: Splits subtitles into optimal batches (~210 cues per batch) to translate entire seasons (20+ episodes, 20,000+ lines) in minutes.
  • Pre-Locked Translation Bible: Pre-extracts character names, legal/technical terms, and gender assignments to eliminate intra-season inconsistencies.
  • 1:1 Alignment Guarantee: Every index and timing range matches the audio and English master file. Zero dropped cues, zero hallucinations.

3. πŸŽ™οΈ On-Device Speech & Audio Alignment (quicksubs Integration)

  • Zero-Cloud STT Ingestion: Powered by quicksubs (by Matt Birchler). Transcribes raw media on-device using Apple SpeechAnalyzer (Apple Silicon Neural Engine), OpenAI Whisper, or NVIDIA Parakeet with zero bandwidth and zero API costs.
  • Audio-Guided Retiming: Extracts authoritative dialogue speech timestamps directly from the video file's audio track to re-align drifted, cut, or framerate-mismatched subtitles automatically.

4. 🎬 Ground-Truth Entity & Gender Resolution (TMDb Integration)

  • Deterministic Gender Mapping: Automatically resolves character genders and episodic guest stars via The Movie Database (TMDb) API, guaranteeing 100% accurate second-person Hebrew pronouns (אΧͺ/היא vs אΧͺΧ”/הוא) with zero hallucinations.
  • Narrative Context & Dialect Priming: Injects episodic plot synopses, genre terms, and regional dialect guidance (e.g. British English idioms) directly into the translation prompts.

5. πŸ’Ž The Semantic AI Polish & Subtitle QC Engine (rightsub polish)

  • Minimal Edit Distance Principle: Selectively proofreads and modernizes existing human subtitles, preserving 85%–90% of intact dialogue blocks and eliminating gratuitous cosmetic churn.
  • Hierarchical Domain Knowledge Engine: 3-tier intelligent context classifier (TMDb metadata, title/franchise patterns, and offline lexical cue vocabulary fingerprinting) with dedicated domain packs (SCI_FI, MILITARY, LEGAL, MEDICAL, FANTASY, UNIVERSAL_IDIOMS) and Bilingual Anchor Validation to prevent false positives across unrelated genres.
  • Forward Anticipation Drift Guard: Robust split-cue partitioning (split_part) and real-time drift protection that strictly prevents language models from leaking or anticipating future dialogue lines, ensuring 100% timing alignment.
  • Network Storage (SMB/NAS) Timestamp Synchronization: Forces immediate kernel filesystem metadata flushes (os.utime) on all mastered subtitles, diff audit reports, and backups to prevent macOS SMB clients from falling back to Apple's CoreFoundation epoch (2001-01-01).
  • Automated Markdown Diff Audit Reporting: Automatically outputs a detailed, cue-by-cue audit report (_polish_diff.md) comparing original English, prior Hebrew, polished Hebrew, and explicit reasoning for every single modification.

πŸ“– CLI Commands Reference

Command Engine Description Windows Example macOS / Linux Example
auto All Zero-flag autonomous runner for files, seasons, or directories rightsub auto "Movie.mkv" rightsub auto "Movie.mkv"
wizard Interactive Interactive Terminal / CMD Mastering Wizard (Drag & Drop, File Browser) rightsub or rightsub wizard rightsub or rightsub wizard
setup Core End-to-end environment setup, downloader hooks & MCP agent wizard rightsub setup rightsub setup
mcp MCP / Agents Native stdio MCP server & 1-command multi-agent installer (--install) rightsub mcp --install rightsub mcp --install
serve Daemon Native Webhook daemon for Sonarr, Radarr, and Bazarr automation rightsub serve --port 8775 rightsub serve --port 8775
polish SubRefine & AI Semantic AI proofreading, canon harmonization & interactive diff review (-i) rightsub polish "Star Wars.he.srt" -i rightsub polish "Star Wars.he.srt" -i
translate-ollama SubSwarm 100% offline local subtitle translation via Ollama rightsub translate-ollama prompts rightsub translate-ollama prompts
fix-plex SubRefine Fix BiDi, RLM, punctuation, CP1255 encoding & ads rightsub fix-plex ./Season1/ -r -i rightsub fix-plex ./Season1/ -r -i
adjust-fps SubRefine Stretch framerate (25.0 <-> 23.976) or shift offset rightsub adjust-fps in.srt -o out.srt rightsub adjust-fps in.srt -o out.srt
extract SubRefine Extract subtitle tracks from MKV/MP4 using FFmpeg rightsub extract video.mp4 -o out.srt rightsub extract video.mp4 -o out.srt
transcribe quicksubs On-device Speech-to-Subtitle transcription (Apple / Whisper) rightsub transcribe video.mp4 rightsub transcribe video.mp4
audio-sync quicksubs Subtitle retiming guided by authoritative audio rightsub audio-sync bad.srt -v vid.mp4 -o ok.srt rightsub audio-sync bad.srt -v vid.mp4 -o ok.srt
sync SubRefine Compare timing delta between English & Hebrew SRTs rightsub sync master.en.srt dl.he.srt rightsub sync master.en.srt dl.he.srt
bible SubSwarm Generate Character & Terminology Bible from SRTs & TMDb rightsub bible Season1/*.srt -o b.json --tmdb rightsub bible Season1/*.srt -o b.json --tmdb
split SubSwarm Split master English SRT into ~210 cue JSON chunks rightsub split ep.en.srt -o ./batches/ rightsub split ep.en.srt -o ./batches/
prompt-gen SubSwarm Generate AI translation prompt waves with Bible & Context rightsub prompt-gen ep.en.srt -t "Title" rightsub prompt-gen ep.en.srt -t "Title"
config Core Interactive API key onboarding, downloader hooks (--install-hooks) & services rightsub config --install-hooks rightsub config --install-hooks
doctor Core System diagnostics & health check for dependencies, services & MCP agents rightsub doctor rightsub doctor
merge Both Assemble translated JSONs into Hebrew SRT with RLM rightsub merge ep.en.srt ./b/ -o ep.he.srt rightsub merge ep.en.srt ./b/ -o ep.he.srt
qa Both Zero-discrepancy 1:1 validation & gender mismatch audit rightsub qa ep.en.srt ep.he.srt rightsub qa ep.en.srt ep.he.srt

πŸ† Proven at Scale: The Boston Legal Benchmark (Theoretical Case Study)

Note

Legal Disclaimer & Theoretical Benchmark Notice: References to the television series Boston Legal are presented strictly as a theoretical, hypothetical benchmark and synthetic case study for algorithmic stress-testing, timing synchronization research, and software demonstration purposes. All title names, character names, trademarks, and copyrights belong entirely to their respective copyright holders (20th Century Fox / Disney, David E. Kelley Productions). No copyrighted video files, audio tracks, or proprietary media assets are included, hosted, or distributed within this repository or software.

RightSub was validated across an end-to-end dataset modeled on the 5-season run of the courtroom drama Boston Legal:

  • 101 / 101 Episodes Translated & Mastered (100% Completion).
  • 78,000+ Dialogue Cues synchronized with 0 dropped lines.
  • 100% Plex & Infuse BiDi Compliance across all devices (Apple TV, LG WebOS, Android TV).
  • Universal Multi-Lingual Homoglyph Sanitization: Automatic neutralization and conversion of 7 foreign writing systems (Georgian, Armenian, Greek, Tibetan, Bengali, Thai, Katakana) into pure Hebrew.
  • Full details in the Boston Legal Case Study.

πŸ§ͺ Testing & Verification

RightSub comes with a comprehensive automated test suite (194 automated tests: 169 unit tests + 25 dataset integration tests):

pytest -v

Tests cover:

  • BiDi trailing punctuation, 18-pattern legacy visual un-flipping (Subabi recovery), and RLM idempotency.
  • Client-side JavaScript SubRefine engine (site/subrefine.js) 1:1 parity against Python 07_fix_plex_punctuation.py across all 15 Red Team vectors, CP1255 browser byte decoding, and bilingual number un-flipping.
  • Hebrew acronym gershayim conversion (Χ’Χ•Χ΄Χ“, ארה״ב).
  • Multi-lingual homoglyph normalization (Georgian Χ“αƒ”Χ™Χ™Χ˜ $\rightarrow$ Χ“Χ™Χ™Χ˜, Armenian, Greek, Arabic, Cyrillic, Asian).
  • Bilingual 2-digit number cross-check (cross_check_bilingual_numbers, 84 $\rightarrow$ 48) and content-based Seed-Safe .srt $\rightarrow$ .he.srt protection.
  • Translation Bible prompt injection & context overlap continuity.
  • Direct-address vocative & intra-line morphological gender mismatch detection.
  • CP1255 Windows-1255 charset detection and conversion.
  • SDH auditory noise and commercial promo cleaning.
  • Framerate arithmetic, time shifting, and validate_anchor_alignment cue drift detection.
  • On-device STT CLI wrappers, fallback handlers, and audio-guided retiming algorithms.
  • TMDb API metadata resolution, smart media filename parsing, and deterministic gender mapping.
  • Native MCP Server JSON-RPC 2.0 protocol framing (Content-Length + JSONL), stdout isolation, and multi-agent auto-installer (--install / --uninstall / --status).
  • Interactive CLI Wizard (rightsub), Drag-and-Drop path normalization, interactive file browser, and line-by-line polish --interactive reviewer.
  • Container Webhook Daemon (rightsub serve), PATH_MAP longest-prefix precedence, path traversal guards, and thread-safe atomic writes.
  • Documentation consistency, SemVer single source of truth, cross-platform parity, and valid link resolution.
  • Live verification of all 101 episodes in the media dataset.

πŸ“š Documentation & Guides


🀝 Acknowledgements & Credits

  • quicksubs by Matt Birchler β€” High-performance on-device macOS speech-to-text CLI engine powering local transcription and audio-guided subtitle retiming.
  • Quick Subtitles β€” The companion Mac application for desktop subtitle and transcript workflows.
  • The Movie Database (TMDb) β€” Community-built movie and TV database providing the rich metadata, cast, episodic guest star, and gender APIs (This product uses the TMDb API but is not endorsed or certified by TMDb).

πŸ“„ License

This project is licensed under the MIT License β€” see the LICENSE file for details.

About

🎬 Smart AI Subtitle Translation & Mastering Suite (Windows & macOS). Multi-agent Hebrew translation, Plex BiDi repair, SDH cleaning & audio sync.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages