subdx-dl


Namesubdx-dl JSON
Version 2.0.0 PyPI version JSON
download
home_pageNone
SummaryA command line tool to download the best matching subtitle from subdivx.com
upload_time2025-07-15 19:09:02
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseNone
keywords cli-tool subdivx subdivx-downloader subtitles
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Subdx-dl

[![en readme](https://img.shields.io/badge/readme-en-red?logo=readme&logoColor=red&label=readme)](https://github.com/Spheres-cu/subdx-dl#subdx-dl)
[![es readme](https://img.shields.io/badge/readme-es-brightgreen?logo=readme&logoColor=brightgreen&label=readme)](https://github.com/Spheres-cu/subdx-dl/blob/main/README.es.md#subdx-dl)

[![GitHub Downloads](https://img.shields.io/badge/downloads-green?logo=github&logoColor=1f1f23&labelColor=fbfbfb&color=brightblue)](https://github.com/Spheres-cu/subdx-dl/releases/latest)
[![latest release windows portable](https://img.shields.io/github/downloads/Spheres-cu/subdx-dl/subdx-dl.exe?logo=artifacthub&logoColor=brightblue&label=%20&labelColor=fbfbfb)](https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl.exe)
[![latest release linux binario](https://img.shields.io/github/downloads/Spheres-cu/subdx-dl/subdx-dl?logo=linux&logoColor=1f1f23&label=%20&labelColor=fbfbfb)](https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/subdx-dl?logo=pypi&logoColor=1f1f23&labelColor=fbfbfb&label=%20)](https://pypistats.org/packages/subdx-dl)

![PyPI - Python Version](https://img.shields.io/pypi/pyversions/subdx-dl?logo=python&logoSize=auto&label=%20&labelColor=1f1f23)
![GitHub Release](https://img.shields.io/github/v/release/Spheres-cu/subdx-dl?logo=github&logoSize=auto&label=%20&labelColor=1f1f23)
[![PyPI - Version](https://img.shields.io/pypi/v/subdx-dl?logo=pypi&logoSize=auto&label=%20&labelColor=1f1f23)](https://pypi.org/project/subdx-dl/)
![GitHub License](https://img.shields.io/github/license/Spheres-cu/subdx-dl)
![GitHub Repo stars](https://img.shields.io/github/stars/Spheres-cu/subdx-dl)

A cli tool for download subtitle from [www.subdivx.com](https://www.subdivx.com) with the better possible matching results.

## Install

```bash
pip install -U subdx-dl
```

### Portable Version

You can download the portable version for Windows x64 (subdx-dl.exe) and x86 (subdx-dl_x86.exe), as well as the binary for Linux (subdx-dl) from: [release](https://github.com/Spheres-cu/subdx-dl/releases/latest)

#### Tips for portable usage

Try to put the executable version in the environment variables **PATH** ,  here some examples:

_In Linux:_

```bash
mkdir -p ~/.local/bin && \
curl --progress-bar -L "https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl" -o ~/.local/bin/subdx-dl && \
chmod +x ~/.local/bin/subdx-dl && \
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```

or

```bash
mkdir -p ~/.local/bin && \
wget --show-progress --progress=bar:force -qO ~/.local/bin/subdx-dl "https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl" && \
chmod +x ~/.local/bin/subdx-dl && \
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```

_In Windows:_

```powershell
$dir = "$env:APPDATA\subdx-dl"; mkdir -Force $dir; `
Invoke-WebRequest -Uri "https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl.exe" -OutFile "$dir\subdx-dl.exe"; `
$path = [Environment]::GetEnvironmentVariable("PATH", "User"); `
if ($path -notlike "*$dir*") { [Environment]::SetEnvironmentVariable("PATH", "$path;$dir", "User") }; `
Write-Host "Added to PATH. Restart terminal for changes to take effect."
```

### Special case installing on Termux (Android) for first time

```bash
pkg install python-lxml && pip install -U subdx-dl
```

### For testing use a virtual env and install it there

_For linux:_

```shell
mkdir subdx
python3 -m venv subdx
source subdx/bin/activate
git clone https://github.com/Spheres-cu/subdx-dl.git
cd subdx-dl
pip install -e .
```

_For Windows:_

```batch
mkdir subdx
python -m venv subdx
.\subdx\Scripts\activate
git clone https://github.com/Spheres-cu/subdx-dl.git
cd subdx-dl
pip install -e .
```

## Usage

```text
usage: sdx-dl [-h or --help] [optional arguments] search
```

_positional arguments_:

```text
search                  file, directory or movie/series title or IMDB Id to retrieve subtitles
```

_optional arguments_:

```text
  -h, --help            show this help message and exit
  --quiet, -q           No verbose mode
  --verbose, -v         Be in verbose mode
  --force, -f           override existing file
  --no-choose, -nc      No Choose sub manually
  --no-filter, -nf      Do not filter search results
  --nlines [], -nl []   Show nl(5,10,15,20) availables records per screen. Default 10 records
  --lang [], -l []      Show messages in language es or en
  --version, -V         Show program version
  --check-version, -cv  Check for new version

Download:
  --path PATH, -p PATH  Path to download subtitles
  --proxy x, -x x       Set a http(s) proxy(x) connection

Search by:
  --Season, -S          Search by Season
  --kword kw, -k kw     Add keywords to search among subtitles descriptions
  --title t, -t t       Set the title to search
  --imdb, -i            Search first for the IMDB id or title

Config:
  --view-config, -vc    View config file
  --save-config, -sc    Save options to config file
  --load-config, -lc    Load config file options
  --config [o], -c [o]  Save an option[o] to config file
  --reset [o], -r [o]   Reset an option[o] in the config file
```

## Examples

_Search a single TV-Show by: Title, Season number or simple show name:_

```shell
sdx-dl "Abbott Elementary S04E01"

sdx-dl "Abbott Elementary 04x01"

sdx-dl "Abbott Elementary"
```

_or search for complete  Season:_

```shell
sdx-dl -S "Abbott Elementary S04E01"
```

_Search for a Movie by Title, Year or simple title, even by **IMDB ID**_:

```shell
sdx-dl "Deadpool and Wolverine 2024"

sdx-dl "Deadpool 3"

sdx-dl tt6263850
```

_Search by a file reference:_

```shell
sdx-dl Harold.and.the.Purple.Crayon.2024.720p.AMZN.WEBRip.800MB.x264-GalaxyRG.mkv
```

_Search first for the _IMDB ID_ or  correct tv show _Title_ if don't know they name or it's in another language:

```shell
sdx-dl --imdb "Los Caza fantasmas"

sdx-dl -i "Duna S1E3"
```

- _IMDB search:_

![![IMDB search film]](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/imdb_search01.png?raw=true)

![![IMDB search film reults]](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/imdb_search02.png?raw=true)

## Config options

With config file arguments you can save some options for use any time, thats options are: quiet, verbose, force, no_choose, no_filter, nlines, path, proxy, Season, imdb, lang.

The arguments for settings this options are:

--view-config, -vc to view what config you have saved.

--save-config, -sc this argument can save all allowed options you pass in search session, keeping the options already saved, merging, with preferer the new passed options.

--config, -c with this argument you can save an option to the config file. The options to save always be the allowed one.

--reset, -r opposite to --config, -c this argument simply reset an option.

--load-config, -lc this is for load all saved options and run the search with they. If you pass some others options those will merged, maintaining preference over the loaded options.

## Tips

- Always try to search with _Title, Year or season number_ for better results.

- Search by filename reference.
  > Search in this way have advantage because the results are filtered and ordered by the metadata of the filename (e.g.: 1080p, Web, Blu-ray, DDP5.1., Atmos, PSA, etc.).

- Try to pass the _IMDB ID_ of the movie or TV Show.

- Pass keywords (```--kword, -k "<str1 str2 str3 ...>"```) of the subtitle   you are searching for better ordered results.

- If the search not found any records by a single chapter number (exe. S01E02) try search by the complete Seasson with ``` --Seasson, -S ``` parameter.

- If you don't wanna filter the search results for a better match and, instead,  improved response time use ``` --no-filter, -nf ``` argument.

- Sometimes our display is a little tiny and the amount of results don't fix well, a way to fix that is using the  --nlines, -nl argument with an amount of records who fix in the screen size.

- _Very important!_: You need to be installed some rar decompression tool for example: [unrar](https://www.rarlab.com/) (preferred), [unar](https://theunarchiver.com/command-line), [7zip](https://www.7-zip.org/) or [bsdtar](https://github.com/libarchive/libarchive). Otherwise, subtitle file will do not decompress.

## Some Captures

### _Performing search:_

- _Navigable searches results:_
- _Subtitle description:_
- _User comments:_
  
![Performing search](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/search_view.gif?raw=true)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "subdx-dl",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "\"C. S. M.\" <sasuke.pc@gmail.com>",
    "keywords": "cli-tool, subdivx, subdivx-downloader, subtitles",
    "author": null,
    "author_email": "Spheres-cu <sasuke.pc@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/52/20/eb83718f5ea10b7be2196fcaae5f68715bf27d2aa8984fd180fa8650590e/subdx_dl-2.0.0.tar.gz",
    "platform": null,
    "description": "# Subdx-dl\n\n[![en readme](https://img.shields.io/badge/readme-en-red?logo=readme&logoColor=red&label=readme)](https://github.com/Spheres-cu/subdx-dl#subdx-dl)\n[![es readme](https://img.shields.io/badge/readme-es-brightgreen?logo=readme&logoColor=brightgreen&label=readme)](https://github.com/Spheres-cu/subdx-dl/blob/main/README.es.md#subdx-dl)\n\n[![GitHub Downloads](https://img.shields.io/badge/downloads-green?logo=github&logoColor=1f1f23&labelColor=fbfbfb&color=brightblue)](https://github.com/Spheres-cu/subdx-dl/releases/latest)\n[![latest release windows portable](https://img.shields.io/github/downloads/Spheres-cu/subdx-dl/subdx-dl.exe?logo=artifacthub&logoColor=brightblue&label=%20&labelColor=fbfbfb)](https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl.exe)\n[![latest release linux binario](https://img.shields.io/github/downloads/Spheres-cu/subdx-dl/subdx-dl?logo=linux&logoColor=1f1f23&label=%20&labelColor=fbfbfb)](https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/subdx-dl?logo=pypi&logoColor=1f1f23&labelColor=fbfbfb&label=%20)](https://pypistats.org/packages/subdx-dl)\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/subdx-dl?logo=python&logoSize=auto&label=%20&labelColor=1f1f23)\n![GitHub Release](https://img.shields.io/github/v/release/Spheres-cu/subdx-dl?logo=github&logoSize=auto&label=%20&labelColor=1f1f23)\n[![PyPI - Version](https://img.shields.io/pypi/v/subdx-dl?logo=pypi&logoSize=auto&label=%20&labelColor=1f1f23)](https://pypi.org/project/subdx-dl/)\n![GitHub License](https://img.shields.io/github/license/Spheres-cu/subdx-dl)\n![GitHub Repo stars](https://img.shields.io/github/stars/Spheres-cu/subdx-dl)\n\nA cli tool for download subtitle from [www.subdivx.com](https://www.subdivx.com) with the better possible matching results.\n\n## Install\n\n```bash\npip install -U subdx-dl\n```\n\n### Portable Version\n\nYou can download the portable version for Windows x64 (subdx-dl.exe) and x86 (subdx-dl_x86.exe), as well as the binary for Linux (subdx-dl) from: [release](https://github.com/Spheres-cu/subdx-dl/releases/latest)\n\n#### Tips for portable usage\n\nTry to put the executable version in the environment variables **PATH** ,  here some examples:\n\n_In Linux:_\n\n```bash\nmkdir -p ~/.local/bin && \\\ncurl --progress-bar -L \"https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl\" -o ~/.local/bin/subdx-dl && \\\nchmod +x ~/.local/bin/subdx-dl && \\\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc && source ~/.bashrc\n```\n\nor\n\n```bash\nmkdir -p ~/.local/bin && \\\nwget --show-progress --progress=bar:force -qO ~/.local/bin/subdx-dl \"https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl\" && \\\nchmod +x ~/.local/bin/subdx-dl && \\\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc && source ~/.bashrc\n```\n\n_In Windows:_\n\n```powershell\n$dir = \"$env:APPDATA\\subdx-dl\"; mkdir -Force $dir; `\nInvoke-WebRequest -Uri \"https://github.com/Spheres-cu/subdx-dl/releases/latest/download/subdx-dl.exe\" -OutFile \"$dir\\subdx-dl.exe\"; `\n$path = [Environment]::GetEnvironmentVariable(\"PATH\", \"User\"); `\nif ($path -notlike \"*$dir*\") { [Environment]::SetEnvironmentVariable(\"PATH\", \"$path;$dir\", \"User\") }; `\nWrite-Host \"Added to PATH. Restart terminal for changes to take effect.\"\n```\n\n### Special case installing on Termux (Android) for first time\n\n```bash\npkg install python-lxml && pip install -U subdx-dl\n```\n\n### For testing use a virtual env and install it there\n\n_For linux:_\n\n```shell\nmkdir subdx\npython3 -m venv subdx\nsource subdx/bin/activate\ngit clone https://github.com/Spheres-cu/subdx-dl.git\ncd subdx-dl\npip install -e .\n```\n\n_For Windows:_\n\n```batch\nmkdir subdx\npython -m venv subdx\n.\\subdx\\Scripts\\activate\ngit clone https://github.com/Spheres-cu/subdx-dl.git\ncd subdx-dl\npip install -e .\n```\n\n## Usage\n\n```text\nusage: sdx-dl [-h or --help] [optional arguments] search\n```\n\n_positional arguments_:\n\n```text\nsearch                  file, directory or movie/series title or IMDB Id to retrieve subtitles\n```\n\n_optional arguments_:\n\n```text\n  -h, --help            show this help message and exit\n  --quiet, -q           No verbose mode\n  --verbose, -v         Be in verbose mode\n  --force, -f           override existing file\n  --no-choose, -nc      No Choose sub manually\n  --no-filter, -nf      Do not filter search results\n  --nlines [], -nl []   Show nl(5,10,15,20) availables records per screen. Default 10 records\n  --lang [], -l []      Show messages in language es or en\n  --version, -V         Show program version\n  --check-version, -cv  Check for new version\n\nDownload:\n  --path PATH, -p PATH  Path to download subtitles\n  --proxy x, -x x       Set a http(s) proxy(x) connection\n\nSearch by:\n  --Season, -S          Search by Season\n  --kword kw, -k kw     Add keywords to search among subtitles descriptions\n  --title t, -t t       Set the title to search\n  --imdb, -i            Search first for the IMDB id or title\n\nConfig:\n  --view-config, -vc    View config file\n  --save-config, -sc    Save options to config file\n  --load-config, -lc    Load config file options\n  --config [o], -c [o]  Save an option[o] to config file\n  --reset [o], -r [o]   Reset an option[o] in the config file\n```\n\n## Examples\n\n_Search a single TV-Show by: Title, Season number or simple show name:_\n\n```shell\nsdx-dl \"Abbott Elementary S04E01\"\n\nsdx-dl \"Abbott Elementary 04x01\"\n\nsdx-dl \"Abbott Elementary\"\n```\n\n_or search for complete  Season:_\n\n```shell\nsdx-dl -S \"Abbott Elementary S04E01\"\n```\n\n_Search for a Movie by Title, Year or simple title, even by **IMDB ID**_:\n\n```shell\nsdx-dl \"Deadpool and Wolverine 2024\"\n\nsdx-dl \"Deadpool 3\"\n\nsdx-dl tt6263850\n```\n\n_Search by a file reference:_\n\n```shell\nsdx-dl Harold.and.the.Purple.Crayon.2024.720p.AMZN.WEBRip.800MB.x264-GalaxyRG.mkv\n```\n\n_Search first for the _IMDB ID_ or  correct tv show _Title_ if don't know they name or it's in another language:\n\n```shell\nsdx-dl --imdb \"Los Caza fantasmas\"\n\nsdx-dl -i \"Duna S1E3\"\n```\n\n- _IMDB search:_\n\n![![IMDB search film]](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/imdb_search01.png?raw=true)\n\n![![IMDB search film reults]](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/imdb_search02.png?raw=true)\n\n## Config options\n\nWith config file arguments you can save some options for use any time, thats options are: quiet, verbose, force, no_choose, no_filter, nlines, path, proxy, Season, imdb, lang.\n\nThe arguments for settings this options are:\n\n--view-config, -vc to view what config you have saved.\n\n--save-config, -sc this argument can save all allowed options you pass in search session, keeping the options already saved, merging, with preferer the new passed options.\n\n--config, -c with this argument you can save an option to the config file. The options to save always be the allowed one.\n\n--reset, -r opposite to --config, -c this argument simply reset an option.\n\n--load-config, -lc this is for load all saved options and run the search with they. If you pass some others options those will merged, maintaining preference over the loaded options.\n\n## Tips\n\n- Always try to search with _Title, Year or season number_ for better results.\n\n- Search by filename reference.\n  > Search in this way have advantage because the results are filtered and ordered by the metadata of the filename (e.g.: 1080p, Web, Blu-ray, DDP5.1., Atmos, PSA, etc.).\n\n- Try to pass the _IMDB ID_ of the movie or TV Show.\n\n- Pass keywords (```--kword, -k \"<str1 str2 str3 ...>\"```) of the subtitle   you are searching for better ordered results.\n\n- If the search not found any records by a single chapter number (exe. S01E02) try search by the complete Seasson with ``` --Seasson, -S ``` parameter.\n\n- If you don't wanna filter the search results for a better match and, instead,  improved response time use ``` --no-filter, -nf ``` argument.\n\n- Sometimes our display is a little tiny and the amount of results don't fix well, a way to fix that is using the  --nlines, -nl argument with an amount of records who fix in the screen size.\n\n- _Very important!_: You need to be installed some rar decompression tool for example: [unrar](https://www.rarlab.com/) (preferred), [unar](https://theunarchiver.com/command-line), [7zip](https://www.7-zip.org/) or [bsdtar](https://github.com/libarchive/libarchive). Otherwise, subtitle file will do not decompress.\n\n## Some Captures\n\n### _Performing search:_\n\n- _Navigable searches results:_\n- _Subtitle description:_\n- _User comments:_\n  \n![Performing search](https://github.com/Spheres-cu/subdx-dl/blob/main/screenshots/search_view.gif?raw=true)\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A command line tool to download the best matching subtitle from subdivx.com",
    "version": "2.0.0",
    "project_urls": {
        "Examples": "https://github.com/Spheres-cu/subdx-dl#examples",
        "Homepage": "https://github.com/Spheres-cu/subdx-dl",
        "Issues": "https://github.com/Spheres-cu/subdx-dl/issues"
    },
    "split_keywords": [
        "cli-tool",
        " subdivx",
        " subdivx-downloader",
        " subtitles"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ab330cb9710ffc12c73a37e5472a4b5476bdab6b09d8c44e74bd4e82ad126788",
                "md5": "12c6fc0cb1a81435eec8a9cf962aeb19",
                "sha256": "34b6700bf97302a455e6e94cd8ae80e630f5e01139365bd600137ce866f01d30"
            },
            "downloads": -1,
            "filename": "subdx_dl-2.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "12c6fc0cb1a81435eec8a9cf962aeb19",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 57920,
            "upload_time": "2025-07-15T19:09:00",
            "upload_time_iso_8601": "2025-07-15T19:09:00.465949Z",
            "url": "https://files.pythonhosted.org/packages/ab/33/0cb9710ffc12c73a37e5472a4b5476bdab6b09d8c44e74bd4e82ad126788/subdx_dl-2.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5220eb83718f5ea10b7be2196fcaae5f68715bf27d2aa8984fd180fa8650590e",
                "md5": "37606710da3e2eb58f300b42c96ab9ac",
                "sha256": "06aa711b7574565ba0527ac51c54932e1f8e762963ffc8147e64776f340ca2f2"
            },
            "downloads": -1,
            "filename": "subdx_dl-2.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "37606710da3e2eb58f300b42c96ab9ac",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 59120,
            "upload_time": "2025-07-15T19:09:02",
            "upload_time_iso_8601": "2025-07-15T19:09:02.112773Z",
            "url": "https://files.pythonhosted.org/packages/52/20/eb83718f5ea10b7be2196fcaae5f68715bf27d2aa8984fd180fa8650590e/subdx_dl-2.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-15 19:09:02",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Spheres-cu",
    "github_project": "subdx-dl#examples",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "subdx-dl"
}
        
Elapsed time: 1.71959s