osub is a command line tool for downloading subtitles from OpenSubtitles.
$ osub auth login username password
The authentication token has been successfully generated.$ osub --file Aliens.mp4 --languages en
Printing 1 page of 1 for 4 subtitles.
FILE ID FILE NAME LANGUAGE UPLOADED DOWNLOADS SUBTITLES ID
169957 Aliens.1986.Spec... English 2 October 2010 88136 169952
171816 Aliens.1986.Spec... English 30 October 2010 57706 171510
4872906 Aliens.Vs.Predat... English 2 March 2008 31408 4749878
178825 Alien[1986]Speci... English 2 February 2014 3956 177188 $ osub download --file-id 169957
The subtitles have been successfully downloaded to /Users/vanyauhalin/Downloads/
Aliens.1986.Special.Edition.720p.BluRay.x264.DTS-WiKi.EN.srtFeel free to open an issue, create a pull request, or contact me via email or Telegram if you encounter any issues, have any questions, or wish to request a feature. I'll be happy to develop osub with you for us.
- Installation
- Usage
- Contribution
- Gratitude
- License
At the moment, osub is only available for macOS users. However, there are plans to add support for both Windows and Linux, thus making osub cross-platform.
$ brew tap vanyauhalin/osub
$ brew install osub
Download the latest release binary and unzip it.
osub is built on the OpenSubtitles REST API, so you will need to obtain an API key before starting the build. You can learn more about how to obtain the API key in the official documentation.
To build, you need the following tools with minimum versions:
Once you have everything installed, download the source code or clone the Git repository. Then, in the root directory, execute the following command:
$ make build API_KEY=<api-key>The build result will be in the .build directory.
osub can run without configuration, so if you wish, you can skip to the next section.
To determine the working locations, osub first accesses the environment variables. In case the environment variables are not set, it then checks the system settings.
So, the configuration location is defined as follows:
| Base path | Additional path |
|---|---|
$OSUB_CONFIG_HOME |
|
$XDG_CONFIG_HOME |
osub/ |
| Application support directory for the current user | me.vanyauhalin.osub/ |
| The home directory for the current user | .config/osub/ |
The state location:
| Base path | Additional path |
|---|---|
$XDG_STATE_HOME |
osub/ |
| The home directory for the current user | .local/state/osub/ |
The downloads location:
| Base path | Additional path |
|---|---|
$XDG_DOWNLOAD_DIR |
|
| The downloads for the current user | |
| The home directory for the current user | Downloads/ |
To find out which locations are currently in use, refer to the osub config locations command.
The configuration values can be manipulated using the osub config get and osub config set commands. But at the same time, osub supports loading a configuration file in the TOML format (config.toml) with the following values:
| Value | Type | Description |
|---|---|---|
api_key |
String | The API key is built-in by default, but you can override it. To learn more about how to obtain the API key, refer to the official documentation. |
username |
String | The OpenSubtitles account name. |
password |
String | The OpenSubtitles account username. |
Root command for configuration management.
$ osub config <subcommand>Print the value of the given configuration key.
$ osub config get <key>Print a list of configuration keys and values.
$ osub config listPrint a locations used by osub.
$ osub config locationsUpdate the configuration with a value for the given key.
$ osub config set <key> <value>In order to be able to download subtitles, you must log in. Once you are authorized, a token will be generated and saved for future use. Simply refresh the token when necessary.
Root command for authentication management.
$ osub auth <subcommand>Print a list of authentication keys and values.
$ osub auth listLogin by generating an authentication token.
$ osub auth login <username> <password>Logout by destroying the authentication token.
$ osub auth logoutRefresh the authentication token.
$ osub auth refreshPrint authentication status.
$ osub auth statusWith osub, you can search for both subtitles and features. A feature refers to a movie, TV show, or episode of a TV show.
Root command for search management.
$ osub search <subcommand>Search for features.
$ osub search features <options>Query options:
--feature-id <int>
Search by feature ID.--imdb-id <string>
Search by feature IMDB ID.--query <string>
Search by file name or string query.--tmdb-id <string>
Search by feature TMDB ID.--type <enum>
Search on feature type:episode,movieortvshow.--year <int>
Search by year.
Search for subtitles.
$ osub search subtitles <options>Query options:
--ai-translated <enum>
Restrict search to AI-translated subtitles:excludeorinclude.--episode-number <int>
Search by TV Show episode number.--foreign-parts-only <enum>
Restrict search to Foreign Parts Only (FPO) subtitles:exclude,includeoronly.--hearing-impaired <enum>
Restrict search to subtitles for the hearing impaired:exclude,includeoronly.--id <int>
Search by feature ID from the features search results.--imdb-id <int>
Search by feature IMDB ID.--languages <[string]>
Search on space-separated list of subtag languages.--machine-translated <enum>
Restrict search to machine-translated subtitles:excludeorinclude.--moviehash-match <enum>
Restrict search to subtitles with feature hash match:includeandonly.--moviehash <string>
Search by feature hash.--order-by <enum>
Order of returned results by field:ai_translated,download_count,foreign_parts_only,fps,from_trusted,hd,hearing_impaired,language,machine_translated,points,ratings,release,upload_date,votes.--order-direction <enum>
Order of returned results by direction:ascordesc.--page <int>
Search on the page.--parent-feature-id <int>
Search for the TV Show by parent feature ID from the features search results.--parent-imdb-id <int>
Search for the TV Show by parent IMDB ID.--parent-tmdb-id <int>
Search for the TV Show by parent TMDB ID.--query <string>
Search by file name or string query.--season-number <int>
Search for the TV Show by season number.--tmdb-id <int>
Search by feature TMDB ID.--trusted-sources <enum>
Restrict search to trusted sources:includeoronly.--type <enum>
Restrict search to feature type:episode,movieortvshow.--user-id <int>
Search for uploaded subtitles by user ID.--year <int>
Search by year.
Utility options:
--file <path>
The path to the file that needs subtitles.
Root command for download subtitles.
$ osub download --file-id <int> <options>Query options:
--file-id <int>
File ID from subtitles search results.--file-name <string>
Desired subtitle file name to save on disk.--in-fps <int>
Input FPS for subtitles.--out-fps <int>
Output FPS for subtitles.--sub-format <string>
Subtitles format from formats results.--timeshift <int>
Timeshift for subtitles.
Besides the primary commands, osub also includes some useful utility commands.
Print a list of formats for subtitles.
$ osub formatsCalculate the hash of the file.
$ osub hash <path>Print a list of languages for subtitles.
$ osub languagesPrint the current osub version.
$ osub versionSome commands offer simple formatting options:
--fields <[enum]>
Space-separated list of fields to print.--frame/--no-frame
Consider the window size when formatting.
To view a list of available fields, run an invalid command with the --fields option, for example:
$ osub <subcommand> --fields ?To contribute, you need the following tools with minimum versions:
- Xcode 14.0
- Swift 5.7.0
- Make 3.0
- Tuist 3.12.0
- SwiftLint 0.50.0 — optional, but recommended.
Once you have everything installed, in the root directory, execute the following commands:
$ make install
$ make devI would like to express my gratitude to the OpenSubtitles team for providing such an great service. I also extend my appreciation to the authors of the wrappers, applications, and scripts that utilized the OpenSubtitles REST API. It was interesting to study your work. Furthermore, I would like to thank the authors of the GitHub CLI, whose product was a significant source of inspiration for me.
osub is distributed under the MIT License.