subg

command module

v0.2.0 Latest Latest Go to latest Published: Aug 28, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kakeetopius/subg

Links

Open Source Insights

README ¶

subg

A command-line tool for searching, downloading, generating, and converting subtitles.

Features

Search for subtitles by movie/series name, IMDB ID, or other criteria
Filter by language, release year, season, and episode
Download subtitles in multiple formats (SRT, VTT, ASS, SSA, TTML, STL)
Convert subtitles from one format to another
Generate subtitles from video or audio files using Whisper
Fallback to other subtitle providers in case the primary one fails
Support for both movies and TV series
Automatic subtitle selection

Installation

go install github.com/kakeetopius/subg@latest

Subtitle Providers

subg can download subtitles from different providers. The following is a list of supported providers in order of priority together with their codes that can be passed via the --providers flag or in the configuration file (see below).

Provider	Code
subdl.com	sd
opensubtitles.org	os
addic7ed.com	a7

[!NOTE] If no provider is specified via the --providers flag or the configuration file, all providers are tried in the order shown above.
The order of trial can be changed by using the --provider flag or via the configuration file (See Below) e.g. --providers a7,sd,os. Providers are then tried in the order given.

Quick Start

1. Download Subtitles

# Download a movie subtitle in English
subg download "In the Heights"

# Download a TV series subtitle
subg download "Bridge and Tunnel" --season 1 --episode 5 --lang en

# Download with custom output
subg download "Grown Ups 2" --lang en --output-file GU2.srt --output-dir ./subtitles

2. Generate Subtitles from Video or Audio

# Generate subtitles from a video file
subg generate movie.mp4

# Generate and translate to English
subg generate movie.mp4 --translate

# Use a specific Whisper model
subg generate movie.mp4 --model large-v3

3. Convert Subtitles

# Convert an SRT file to VTT
subg convert --in subtitle.srt --out subtitle.vtt

# Convert using the --convert-to flag (output filename is derived from input with only the extension changed)
subg convert --in subtitle.srt --convert-to ass

Sample Usage

download

Search and download subtitles for a movie or TV show. Aliases: dl, d.

subg download <query> [flags]

Flags

--lang, -l - Subtitle language code (default: "en")
--season, -s - TV series season number
--episode, -e - TV series episode number
--format, -f - Subtitle format to download (default: "srt")
--year, -y - Release year to reduce ambiguity
--output-file, -o - Custom output filename
--output-dir - Output directory for downloaded subtitle
--imdb-id - Search using IMDB ID
--movie - Specify that the query is for a movie
--serie - Specify that the query is for a TV series
--providers, -p - The provider(s) to use as a comma-separated list (e.g. os,sd). If set, no fallback is done on failure.
--auto - Automatically select the first result without prompting

generate

Generate subtitles from a video or audio file using whisper-ctranslate2. Aliases: gen, g.

[!IMPORTANT] This command requires Python and FFmpeg to be installed on your system. Other dependencies are installed automatically by subg.

subg generate files... [flags]

Flags

--lang, -l - The language of the input file(s) (default: "en")
--format, -f - The subtitle format to save as (default: "srt")
--output-dir - The directory to save the subtitle files to
--translate, -t - Translate the audio to English instead of transcribing in the original language
--model, -m - The Whisper model to use: tiny, medium, large-v3, turbo, etc. (default: "turbo"). See the model card for more information.
--hf-token - A Hugging Face access token to access transcribing models
--verbose - Print extra information about what is happening

convert

Convert a subtitle file from one format to another. Alias: c.

Supported formats: srt, vtt, ass, ssa, ttml, stl.

subg convert --in <input-file> [flags]

Flags

--in, -i - The input subtitle file (required)
--out, -o - The output file name. If not given, the output filename is derived from the input filename.
--convert-to, -c - The format to convert to. Required if --out is not given with a recognizable extension.

Configuration

Configuration can be set via:

Configuration file
Environment variables
Command-line flags (highest priority)

Configuration File

Place a subg.toml file this location:

On Linux:

$XDG_CONFIG_HOME/subg/subg.toml or ~/.config/subg/subg.toml

On Windows:

%APPDATA%\subg\subg.toml

Example subg.toml:

# Specify one or more providers to use by default. (See above for codes.)
providers = ["os", "sd"]

# Directory to store temporary information like JWT tokens for an OpenSubtitles session.
cache_dir = "$HOME/.cache/subg"

[transcriber]
# Hugging Face access token to use when accessing Whisper transcribing models.
# This is optional but can offer higher rate limits  and possibly faster downloads if provided.
# It can be set here or passed via the --hf-token flag or via the env variable HF_TOKEN
hf_token = "your-hf-token-here"

The config file can be also given using the --config flag.

Environment Variables

HF_TOKEN - Hugging Face Access Token. (It is optional, but it can offer higher rate limits and faster downloads.)

Optional: Configure Authenticated Providers

By default, subg can search and download subtitles using subdl.com, opensubtitles.org, and addic7ed.com without requiring an account or API key.

For improved search capabilities, higher reliability, or access to the official APIs, subg also supports the API-based providers below:

opensubtitles.com

To use the official opensubtitles.com API:

Create an account here if you don't have one already.
Log in using:

subg login --provider os_api

Obtain an API key from your opensubtitles.com here.
Add the API key to your subg.toml configuration file:

[opensubtitles]
api_key = "your-api-key"

The provider code for the API-based provider is os_api. You can include it in the provider list to give it priority, for example:

providers = ["os_api", "sd", "os", "a7"]

subdl.com

Although subg can use subdl.com without authentication, you may also use the official SubDL API.

Obtain an API key from the website here
Add it to your configuration file:

[subdl]
api_key = "your-api-key"

The provider code for the API-based provider is sd_api. To prioritize it, include it in your provider list, for example:

providers = ["sd_api", "os", "a7"]

The API-backed providers (os_api and sd_api) are separate from the providers os and sd. This allows you to choose whether to use the official APIs, the normal providers, or both.

Future Plans

Support for additional subtitle providers
Batch downloading capabilities
Subtitle synchronization and adjustment tools

License

MIT
See LICENSE file for details.

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package cmd is used for command line argument passing	Package cmd is used for command line argument passing
internal
generate Package generate is used to transcribe and translate subtitles from audio or video files.	Package generate is used to transcribe and translate subtitles from audio or video files.
httpclient Package httpclient contains an http client	Package httpclient contains an http client
providers Package providers contains functions to interact with different subtitle providers.	Package providers contains functions to interact with different subtitle providers.
providers/addic7ed Package addic7ed is used to interface with the addic7ed subtitle provider using a wrapper.	Package addic7ed is used to interface with the addic7ed subtitle provider using a wrapper.
providers/opensubtitles Package opensubtitles is used to talk to opensubtitles API via a wrapper.	Package opensubtitles is used to talk to opensubtitles API via a wrapper.
providers/opensubtitles_org Package opensubtitlesorg is used to get subtitles from opensubtitles.org	Package opensubtitlesorg is used to get subtitles from opensubtitles.org
providers/subdl Package subdl is used to search for subtitles from subdl.com	Package subdl is used to search for subtitles from subdl.com
providers/subdl_api Package subdlapi used to search for subtitles from subdl.com using the official subdl api.	Package subdlapi used to search for subtitles from subdl.com using the official subdl api.
sessions Package sessions manages authenticated sessions for HTTP providers that require it.	Package sessions manages authenticated sessions for HTTP providers that require it.
subformat Package subformat is used to manipulate different subtitle formats.	Package subformat is used to manipulate different subtitle formats.
ui Package ui is used to display various ui componenets to the terminal.	Package ui is used to display various ui componenets to the terminal.
util Package util contains some helper functions.	Package util contains some helper functions.
zip Package zip is used to work with zip files returned by subtitle providers.	Package zip is used to work with zip files returned by subtitle providers.