{"id":24128206,"url":"https://github.com/vanyauhalin/osub","last_synced_at":"2026-06-07T18:32:37.743Z","repository":{"id":215623457,"uuid":"624840558","full_name":"vanyauhalin/osub","owner":"vanyauhalin","description":"OpenSubtitles in your terminal.","archived":false,"fork":false,"pushed_at":"2024-01-05T13:24:00.000Z","size":199,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-11T18:45:33.188Z","etag":null,"topics":["cli","opensubtitles","subtitles","swift"],"latest_commit_sha":null,"homepage":"https://osub.vanyauhalin.me","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanyauhalin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-07T11:41:56.000Z","updated_at":"2024-08-28T05:11:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"bd312609-5d5a-4f1c-b342-718e1e63a42f","html_url":"https://github.com/vanyauhalin/osub","commit_stats":null,"previous_names":["vanyauhalin/osub"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanyauhalin%2Fosub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanyauhalin%2Fosub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanyauhalin%2Fosub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanyauhalin%2Fosub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanyauhalin","download_url":"https://codeload.github.com/vanyauhalin/osub/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241313177,"owners_count":19942417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","opensubtitles","subtitles","swift"],"created_at":"2025-01-11T18:40:24.040Z","updated_at":"2026-06-07T18:32:37.686Z","avatar_url":"https://github.com/vanyauhalin.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osub\n\nosub is a command line tool for downloading subtitles from [OpenSubtitles](https://www.opensubtitles.com).\n\n```sh\n$ osub auth login username password\nThe authentication token has been successfully generated.\n```\n\n```sh\n$ osub --file Aliens.mp4 --languages en\n\nPrinting 1 page of 1 for 4 subtitles.\n\nFILE ID  FILE NAME            LANGUAGE  UPLOADED         DOWNLOADS  SUBTITLES ID\n169957   Aliens.1986.Spec...  English   2 October 2010   88136      169952      \n171816   Aliens.1986.Spec...  English   30 October 2010  57706      171510      \n4872906  Aliens.Vs.Predat...  English   2 March 2008     31408      4749878     \n178825   Alien[1986]Speci...  English   2 February 2014  3956       177188      \n```\n\n```sh\n$ osub download --file-id 169957\nThe subtitles have been successfully downloaded to /Users/vanyauhalin/Downloads/\nAliens.1986.Special.Edition.720p.BluRay.x264.DTS-WiKi.EN.srt\n```\n\nFeel free to open an [issue](https://github.com/vanyauhalin/osub/issues), create a [pull request](https://github.com/vanyauhalin/osub/pulls), or contact me via [email](mailto:vanyauhalin@mail.com) or [Telegram](https://t.me/vanyauhalin) 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.\n\n## Contents\n\n- [Installation](#installation)\n  - [Using Homebrew](#using-homebrew)\n  - [Using a release binary](#using-a-release-binary)\n  - [Build from sources](#build-from-sources)\n- [Usage](#usage)\n  - [Manage configuration](#manage-configuration)\n    - [Configuration locations](#configuration-locations)\n    - [Configuration file its values](#configuration-file-its-values)\n    - [`osub config`](#osub-config)\n    - [`osub config get`](#osub-config-get)\n    - [`osub config list`](#osub-config-list)\n    - [`osub config locations`](#osub-config-locations)\n    - [`osub config get`](#osub-config-get)\n  - [Manage authentication](#manage-authentication)\n    - [`osub auth`](#osub-auth)\n    - [`osub auth list`](#osub-auth-list)\n    - [`osub auth login`](#osub-auth-login)\n    - [`osub auth logout`](#osub-auth-logout)\n    - [`osub auth refresh`](#osub-auth-refresh)\n    - [`osub auth status`](#osub-auth-status)\n  - [Search management](#search-management)\n    - [`osub search`](#osub-search)\n    - [`osub search features`](#osub-search-features)\n    - [`osub search subtitles`](#osub-search-subtitles)\n  - [Download subtitles](#download-subtitles)\n    - [`osub download`](#osub-download)\n  - [Utility commands](#utility-commands)\n    - [`osub formats`](#osub-formats)\n    - [`osub hash`](#osub-hash)\n    - [`osub languages`](#osub-languages)\n    - [`osub version`](#osub-version)\n  - [Formatting options](#formatting-options)\n- [Contribution](#contribution)\n- [Gratitude](#gratitude)\n- [License](#license)\n\n## Installation\n\nAt 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.\n\n### Using Homebrew\n\n```\n$ brew tap vanyauhalin/osub\n$ brew install osub\n```\n\n### Using a release binary\n\nDownload the [latest release binary](https://github.com/vanyauhalin/osub/releases) and unzip it.\n\n### Build from sources\n\nosub 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](https://opensubtitles.stoplight.io/docs/opensubtitles-api/e3750fd63a100-getting-started#api-key).\n\nTo build, you need the following tools with minimum versions:\n\n- [Xcode 14.0](https://developer.apple.com/xcode)\n- [Swift 5.7.0](https://www.swift.org)\n- [Make 3.0](https://www.gnu.org/software/make)\n- [Tuist 3.12.0](https://tuist.io)\n\nOnce you have everything installed, download the source code or clone the Git repository. Then, in the root directory, execute the following command:\n\n```sh\n$ make build API_KEY=\u003capi-key\u003e\n```\n\nThe build result will be in the `.build` directory.\n\n## Usage\n\n### Manage configuration\n\nosub can run without configuration, so if you wish, you can skip to the [next section](#manage-authentication).\n\n#### Configuration locations\n\nTo determine the working locations, osub first accesses the environment variables. In case the environment variables are not set, it then checks the system settings.\n\nSo, the configuration location is defined as follows:\n\n| Base path                                          | Additional path        |\n| :------------------------------------------------- | :--------------------- |\n| `$OSUB_CONFIG_HOME`                                |                        |\n| `$XDG_CONFIG_HOME`                                 | `osub/`                |\n| Application support directory for the current user | `me.vanyauhalin.osub/` |\n| The home directory for the current user            | `.config/osub/`        |\n\nThe state location:\n\n| Base path                               | Additional path      |\n| :-------------------------------------- | :------------------- |\n| `$XDG_STATE_HOME`                       | `osub/`              |\n| The home directory for the current user | `.local/state/osub/` |\n\nThe downloads location:\n\n| Base path                               | Additional path |\n| :-------------------------------------- | :-------------- |\n| `$XDG_DOWNLOAD_DIR`                     |                 |\n| The downloads for the current user      |                 |\n| The home directory for the current user | `Downloads/`    |\n\nTo find out which locations are currently in use, refer to the [`osub config locations`](#osub-config-locations) command.\n\n#### Configuration file its values\n\nThe configuration values can be manipulated using the [`osub config get`](#osub-config-get) and [`osub config set`](#osub-config-set) commands. But at the same time, osub supports loading a configuration file in the [TOML](https://toml.io) format (`config.toml`) with the following values:\n\n| Value      | Type   | Description                                                                                                                                                                                                                                         |\n| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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](https://opensubtitles.stoplight.io/docs/opensubtitles-api/e3750fd63a100-getting-started#api-key). |\n| `username` | String | The OpenSubtitles account name.                                                                                                                                                                                                                     |\n| `password` | String | The OpenSubtitles account username.                                                                                                                                                                                                                 |\n\n#### `osub config`\n\nRoot command for configuration management.\n\n```sh\n$ osub config \u003csubcommand\u003e\n```\n\n#### `osub config get`\n\nPrint the [value](#configuration-file-its-values) of the given configuration [key](#configuration-file-its-values).\n\n```sh\n$ osub config get \u003ckey\u003e\n```\n\n#### `osub config list`\n\nPrint a list of configuration [keys](#configuration-file-its-values) and [values](#configuration-file-its-values).\n\n```sh\n$ osub config list\n```\n\n#### `osub config locations`\n\nPrint a [locations](#configuration-locations) used by osub.\n\n```sh\n$ osub config locations\n```\n\n#### `osub config get`\n\nUpdate the configuration with a [value](#configuration-file-its-values) for the given [key](#configuration-file-its-values).\n\n```sh\n$ osub config set \u003ckey\u003e \u003cvalue\u003e\n```\n\n### Manage authentication\n\nIn order to be able to download subtitles, you must [log in](#osub-auth-login). Once you are authorized, a token will be generated and saved for future use. Simply [refresh](#osub-auth-refresh) the token when necessary.\n\n#### `osub auth`\n\nRoot command for authentication management.\n\n```sh\n$ osub auth \u003csubcommand\u003e\n```\n\n#### `osub auth list`\n\nPrint a list of authentication keys and values.\n\n```sh\n$ osub auth list\n```\n  \n#### `osub auth login`\n\nLogin by generating an authentication token.\n\n```sh\n$ osub auth login \u003cusername\u003e \u003cpassword\u003e\n```\n\n#### `osub auth logout`\n\nLogout by destroying the authentication token.\n\n```sh\n$ osub auth logout\n```\n\n#### `osub auth refresh`\n\nRefresh the authentication token.\n\n```sh\n$ osub auth refresh\n```\n\n#### `osub auth status`\n\nPrint authentication status.\n\n```sh\n$ osub auth status\n```\n\n### Search management\n\nWith osub, you can search for both subtitles and features. A feature refers to a movie, TV show, or episode of a TV show.\n\n#### `osub search`\n\nRoot command for search management.\n\n```sh\n$ osub search \u003csubcommand\u003e\n```\n\n#### `osub search features`\n\nSearch for features.\n\n```sh\n$ osub search features \u003coptions\u003e\n```\n\nQuery options:\n\n- `--feature-id \u003cint\u003e`  \nSearch by feature ID.\n- `--imdb-id \u003cstring\u003e`  \nSearch by feature IMDB ID.\n- `--query \u003cstring\u003e`  \nSearch by file name or string query.\n- `--tmdb-id \u003cstring\u003e`  \nSearch by feature TMDB ID.\n- `--type \u003cenum\u003e`  \nSearch on feature type: `episode`, `movie` or `tvshow`.\n- `--year \u003cint\u003e`  \nSearch by year.\n\n#### `osub search subtitles`\n\nSearch for subtitles.\n\n```sh\n$ osub search subtitles \u003coptions\u003e\n```\n\nQuery options:\n\n- `--ai-translated \u003cenum\u003e`  \nRestrict search to AI-translated subtitles: `exclude` or `include`.\n- `--episode-number \u003cint\u003e`  \nSearch by TV Show episode number.\n- `--foreign-parts-only \u003cenum\u003e`  \nRestrict search to Foreign Parts Only (FPO) subtitles: `exclude`, `include` or `only`.\n- `--hearing-impaired \u003cenum\u003e`  \nRestrict search to subtitles for the hearing impaired: `exclude`, `include` or `only`.\n- `--id \u003cint\u003e`  \nSearch by feature ID from the features search results.\n- `--imdb-id \u003cint\u003e`  \nSearch by feature IMDB ID.\n- `--languages \u003c[string]\u003e`  \nSearch on space-separated list of subtag languages.\n- `--machine-translated \u003cenum\u003e`  \nRestrict search to machine-translated subtitles: `exclude` or `include`.\n- `--moviehash-match \u003cenum\u003e`  \nRestrict search to subtitles with feature hash match: `include` and `only`.\n- `--moviehash \u003cstring\u003e`  \nSearch by feature hash.\n- `--order-by \u003cenum\u003e`  \nOrder 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`.\n- `--order-direction \u003cenum\u003e`  \nOrder of returned results by direction: `asc` or `desc`.\n- `--page \u003cint\u003e`  \nSearch on the page.\n- `--parent-feature-id \u003cint\u003e`  \nSearch for the TV Show by parent feature ID from the features search results.\n- `--parent-imdb-id \u003cint\u003e`  \nSearch for the TV Show by parent IMDB ID.\n- `--parent-tmdb-id \u003cint\u003e`  \nSearch for the TV Show by parent TMDB ID.\n- `--query \u003cstring\u003e`  \nSearch by file name or string query.\n- `--season-number \u003cint\u003e`  \nSearch for the TV Show by season number.\n- `--tmdb-id \u003cint\u003e`  \nSearch by feature TMDB ID.\n- `--trusted-sources \u003cenum\u003e`  \nRestrict search to trusted sources: `include` or `only`.\n- `--type \u003cenum\u003e`  \nRestrict search to feature type: `episode`, `movie` or `tvshow`.\n- `--user-id \u003cint\u003e`  \nSearch for uploaded subtitles by user ID.\n- `--year \u003cint\u003e`  \nSearch by year.\n\nUtility options:\n\n- `--file \u003cpath\u003e`  \nThe path to the file that needs subtitles.\n\n### Download subtitles\n\n#### `osub download`\n\nRoot command for download subtitles.\n\n```sh\n$ osub download --file-id \u003cint\u003e \u003coptions\u003e\n```\n\nQuery options:\n\n- `--file-id \u003cint\u003e`  \nFile ID from subtitles search results.\n- `--file-name \u003cstring\u003e`  \nDesired subtitle file name to save on disk.\n- `--in-fps \u003cint\u003e`  \nInput FPS for subtitles.\n- `--out-fps \u003cint\u003e`  \nOutput FPS for subtitles.\n- `--sub-format \u003cstring\u003e`  \nSubtitles format from formats results.\n- `--timeshift \u003cint\u003e`  \nTimeshift for subtitles.\n\n### Utility commands\n\nBesides the primary commands, osub also includes some useful utility commands.\n\n#### `osub formats`\n\nPrint a list of formats for subtitles.\n\n```sh\n$ osub formats\n```\n\n#### `osub hash`\n\nCalculate the hash of the file.\n\n```sh\n$ osub hash \u003cpath\u003e\n```\n\n#### `osub languages`\n\nPrint a list of languages for subtitles.\n\n```sh\n$ osub languages\n```\n\n#### `osub version`\n\nPrint the current osub version.\n\n```sh\n$ osub version\n```\n\n### Formatting options\n\nSome commands offer simple formatting options:\n\n- `--fields \u003c[enum]\u003e`  \nSpace-separated list of fields to print.\n- `--frame/--no-frame`  \nConsider the window size when formatting.\n\nTo view a list of available fields, run an invalid command with the `--fields` option, for example:\n\n```sh\n$ osub \u003csubcommand\u003e --fields ?\n```\n\n## Contribution\n\nTo contribute, you need the following tools with minimum versions:\n\n- [Xcode 14.0](https://developer.apple.com/xcode)\n- [Swift 5.7.0](https://www.swift.org)\n- [Make 3.0](https://www.gnu.org/software/make)\n- [Tuist 3.12.0](https://tuist.io)\n- [SwiftLint 0.50.0](https://realm.github.io/SwiftLint) — optional, but recommended.\n\nOnce you have everything installed, in the root directory, execute the following commands:\n\n```sh\n$ make install\n$ make dev\n```\n\n## Gratitude\n\nI 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](https://cli.github.com), whose product was a significant source of inspiration for me.\n\n## License\n\nosub is distributed under the [MIT License](./License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanyauhalin%2Fosub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanyauhalin%2Fosub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanyauhalin%2Fosub/lists"}