Subtitle Forge V2.4.9

Powerful subtitle extraction, conversion, translation, and transcription for macOS, Windows, and Linux.

Subtitle Forge is a desktop application for working with subtitles across the full workflow: extract, insert, convert, OCR, translate, and transcribe. It includes a modern GUI, optional helper installers, and support for both local and remote subtitle-processing tools.

Why use Subtitle Forge

• Extract subtitles from MKV files, including batch workflows
• Insert subtitles back into video containers
• Convert subtitle formats between SRT, ASS, SSA, VTT, TXT, SUB, SUP, and more
• OCR image-based subtitles such as PGS and VobSub
• Translate subtitles with Gemini/GST or LibreTranslate
• Transcribe audio/video with Whisper
• Manage dependencies from the built-in Settings tab
• Work across platforms with macOS, Windows, and Linux release packages

Main features

GUI application

• Extract Subtitles

  • Load subtitle tracks from MKV files
  • Batch process multiple files
  • Convert OCR-based tracks to text formats when tools are available

• Insert Subtitles

  • Add external subtitles to MKV files
  • Works with multiple subtitle formats

• Convert Subtitles

  • Convert between common subtitle formats
  • Apply time offsets and text-processing options
  • Handle OCR-driven conversions when the required tools are installed

• AI Translation

  • Use Gemini-based workflows through gst
  • Supports advanced translation settings and batch jobs

• Whisper Transcription

  • Transcribe media into subtitle files
  • Supports local whisper.cpp on macOS and remote API workflows

• LibreTranslate

  • Translate subtitle files with a local or remote LibreTranslate server

• Settings and Logs

  • Dependency readiness summary
  • Install actions for supported tools
  • Logs for troubleshooting
  • UI language selection

CLI project

This repository also contains the original CLI extraction tooling. Most end users should use the packaged GUI releases, but you can still build and run the CLI from source if needed.

Quick start

If you want the shortest path to a working setup:

• Basic extraction / insertion / conversion

  • Install the app for your platform
  • Make sure ffmpeg, mkvmerge, and mkvextract are available

• OCR workflows

  • Install tesseract
  • Install deno
  • Install the OCR helper tools shown in Settings

• AI translation

  • Install the GST/Gemini dependencies
  • Provide your API key in the app

• Whisper transcription

  • On macOS, run the included Whisper setup script or use a remote server

• LibreTranslate

  • Set a remote LibreTranslate URL, or install the local macOS helper and start the server

If you are unsure what is missing, open Settings in the app. Subtitle Forge shows a setup summary and dependency status there.

Feature requirements

Use this table to understand what each workflow needs.

Workflow	Required	Optional / Notes
Extract subtitles	mkvmerge, mkvextract	ffmpeg is commonly useful
Insert subtitles	mkvmerge
Convert text subtitles	none for basic formats	ffmpeg may be used depending on workflow
OCR PGS / SUP	deno, tesseract, tessdata	PGS-to-SRT helper script
OCR VobSub	tesseract, tessdata, vobsub2srt
AI Translate (GST)	gst plus provider credentials	Gemini API key required for Gemini-based use
Whisper local	whisper-cli and model file	macOS helper script available
Whisper remote	Remote server URL	API key may be required
LibreTranslate remote	Server URL	API key optional depending on server
LibreTranslate local	Local LibreTranslate install	macOS/Windows helper script available

Installation

macOS

1. Download the latest macOS release from the Releases page.
2. Unzip the archive.
3. Remove the macOS quarantine flag:

xattr -cr "Subtitle Forge.app"

4. Move the app to /Applications or another preferred location.
5. Launch the app.

Windows

1. Download the latest Windows release.
2. Extract the archive.
3. If included in your package, run install_dependencies.ps1 or WindowsAIOInstaller.ps1 as needed.
4. Launch the application.

Linux

1. Download the latest Linux release.
2. Choose one of the package types:
   • Standard package: includes installation scripts
   • Bundle package: includes bundled dependencies where available
3. Extract the archive:

tar -xzf subtitle-forge-linux*.tar.gz

4. For the standard package, install dependencies if needed:

sudo ./install_dependencies.sh

5. Launch the application.

Optional setup helpers

Subtitle Forge can work with only the tools needed for your chosen workflow. These helper scripts make setup easier.

General dependency installer on macOS

Run:

bash ./install_dependencies.sh

This installer:

• installs common Homebrew packages such as ffmpeg, mkvtoolnix, deno, tesseract, and Python
• creates a dedicated GST virtual environment at ~/.subtitle-forge/gst-venv
• installs or updates gst
• downloads tessdata to ~/tessdata_best
• adds PATH and TESSDATA_PREFIX lines to ~/.zshrc

After installation:

gst --help
gst translate --help

If you want to remove the user-scoped items later:

bash ./uninstall_dependencies.sh

Whisper on macOS

Run:

bash ./Whisper-mac-coreml.sh install
bash ./Whisper-mac-coreml.sh download-model base.en

Optional:

bash ./Whisper-mac-coreml.sh generate-coreml base.en

The default install locations used by the app are:

• ~/.whispercpp-coreml/whisper.cpp/build/bin/whisper-cli
• ~/.whispercpp-coreml/whisper.cpp/models/ggml-base.en.bin

LibreTranslate on macOS

Run:

bash ./Libre-mac.sh install
bash ./Libre-mac.sh start

Useful commands:

bash ./Libre-mac.sh start-bg
bash ./Libre-mac.sh status

The local install is placed under:

• ~/.libretranslate

LibreTranslate on Windows

Run PowerShell as Administrator and run:

.\Libre-windows.ps1 install

Then start the server:

.\Libre-windows.ps1 start-bg

Useful commands:

.\Libre-windows.ps1 status
.\Libre-windows.ps1 stop

The local install is placed under:

• %USERPROFILE%\.libretranslate

First run guide

After launching Subtitle Forge:

1. Open Settings
2. Review the dependency summary
3. Install only the tools you need for your workflow
4. Configure any required API keys or server URLs
5. Return to the relevant tab and start working

API keys and external services

Some features need external services or credentials.

• Gemini / GST

  • Requires a Gemini API key for Gemini-backed translation workflows
  • You can create one from Google AI Studio

• Whisper remote

  • Requires a remote server URL
  • Some servers may also require an API key

• LibreTranslate remote

  • Requires a server URL
  • Some servers may require an API key

For privacy-sensitive use cases, local Whisper and local LibreTranslate setups are available on macOS.

OCR notes

OCR-based subtitle conversion depends on the quality of the source subtitles and the installed language data.

• PGS / SUP

  • Uses Deno-based tooling with Tesseract

• VobSub

  • Uses vobsub2srt with Tesseract

Better results generally require:

• correct OCR language selection
• matching tessdata files
• high-quality source subtitles

Troubleshooting

• The app says a dependency is missing

  • Open Settings and review the setup summary
  • Install the missing tool or point the app to the correct path

• OCR is not working

  • Make sure tesseract is installed
  • Make sure tessdata is present
  • For PGS workflows, make sure deno is installed

• Whisper local mode does not start

  • Verify whisper-cli exists and is executable
  • Verify the selected model file exists and is readable

• LibreTranslate local mode is not ready

  • Make sure the helper install completed successfully (Libre-mac.sh on macOS, Libre-windows.ps1 on Windows)
  • Start the local server
  • Confirm the app is using the expected local or remote URL

• Update notifications do not appear

  • Install the latest release
  • Older releases may contain outdated updater logic

• macOS says the app is damaged or blocked

  • Run:

xattr -cr "Subtitle Forge.app"

Building from source

Prerequisites

• Go 1.18 or later
• Platform dependencies required by Fyne
• Additional platform build tools as needed

Fyne setup guide:

• Fyne Getting Started

Typical examples:

• macOS

  • brew install gcc

• Linux

  • apt install gcc libgl1-mesa-dev xorg-dev

• Windows

  • install MinGW or MSYS2

Build steps

git clone https://github.com/VenimK/Subtitle-Forge.git
cd Subtitle-Forge/fyne-gui
chmod +x build.sh
./build.sh

Typical outputs:

• macOS: ./build/subtitle-forge-mac
• Linux: ./build/subtitle-forge-linux

What's new in V2.4.9

• LibreTranslate: Local LibreTranslate server support is now available on Windows via the included Libre-windows.ps1 helper. Install, start, stop, and check status directly from the LibreTranslate tab on Windows, just like on macOS
• LibreTranslate: The Settings dependency summary and local-server UI no longer describe the helper as macOS-only

What's new in V2.4.8

• Whisper: The log pane now shows live progress on Windows and Linux during local transcription — whisper-cli reports progress by rewriting the same line with \r, which the previous line scanner never displayed, leaving the log looking frozen. \r and \n are now both treated as line breaks, with throttling and dedupe. The same fix applies to the whisper-cli install/build output

What's new in V2.4.7

• Whisper: New "Check & Install whisper-cli" button — detects an existing install (path entry, PATH, or default location) and, if missing, installs whisper-cli with one click: official whisper-bin-x64.zip release binaries on Windows, or a git clone + cmake build on macOS (with Core ML) and Linux
• Whisper: Fixed whisper-cli detection on Windows — executables are now recognized by extension (.exe, .bat, .cmd, .com, .ps1) since Windows has no exec permission bits
• Whisper: Default whisper-cli path now uses whisper-cli.exe on Windows and falls back to a PATH lookup
• Whisper: Clearer error when ffmpeg is missing and the input needs WAV conversion; the "Stream logs in Terminal (macOS)" option is now hidden on other platforms

What's new in V2.4.6

• Whisper: The model download helper no longer requires a whisper.cpp repo checkout — if none is found, the app downloads ggml-<model>.bin directly from the official Hugging Face repo with live progress in the log pane, and auto-selects the model on success
• Whisper: Fixes "could not locate whisper.cpp root" errors for whisper-cli installs that don't ship the repo's download scripts (e.g. Homebrew or standalone binaries)

What's new in V2.4.5

• Whisper: The model download helper now works on Windows and Linux, not just macOS. On Windows it uses whisper.cpp's download-ggml-model.cmd; on Linux/other Unix it uses download-ggml-model.sh. Downloads run in-app with live progress in the log pane, and the downloaded model is auto-selected on success
• Whisper: whisper.cpp root detection also recognizes the Windows download-ggml-model.cmd script

What’s new in V2.4.3

• Performance: Fixed O(n²) log rendering — all log areas (LibreTranslate, Whisper, AI Translation, Logs tab) now use capped line buffers instead of unbounded string concatenation
• Performance: Eliminated goroutine-per-log-entry leak in the application logger
• Performance: Removed duplicate filterTracks dead code in the Extract tab
• Performance: Reduced window position polling from every 1 second to every 5 seconds
• UX: Tab icons added to all tabs for visual consistency (📂 Extract, ➕ Insert, 🔄 Convert, ⚙️ Settings)
• UX: LibreTranslate server log panel now has a Clear button
• UX: LibreTranslate API key is auto-filled from ~/.libretranslate/api_key.txt when the server is running and the field is empty
• UX: Theme selector no longer applies the theme on every scroll through options — theme is applied only when the Apply button is clicked, eliminating UI flicker
• LibreTranslate: Default port changed from 5000 to 5100 to avoid conflict with macOS ControlCenter; existing saved preferences are automatically migrated

What's new in V2.4.2

• Improved update detection for version comparisons
• Better installer/app path synchronization
• More accurate LibreTranslate readiness checks
• Better Whisper default path detection and persistence
• Cleaner packaging behavior for Linux releases

For the full release history, see:

• GitHub Releases

Contributing

Bug reports, feature requests, and pull requests are welcome.

License

MIT License