# parse-torrent-title
> Extract media information from torrent-like filename
Originally based off of [this JavaScript
library](https://github.com/jzjzjzj/parse-torrent-name).
Extract all possible media information from a filename. Multiple regex
rules are applied on the filename, each of which extracts appropriate
information. If a rule matches, the corresponding part
is removed from the filename. Finally, what remains is taken as the
title of the content.
## Install
PTN can be installed automatically using `pip`.
```sh
$ pip install parse-torrent-title
```
### Requirements
Requirements are **optional**. That being said, the `regex` library increases performance on Python 2 by more than 10x, so it might be worth installing with:
```sh
$ pip install -r requirements.txt
```
With Python 3, the default `re` module is faster than `regex`, so it will always be used regardless of installed requirements.
## Why?
Online APIs by providers like
[TMDb](https://www.themoviedb.org/documentation/api),
[TVDb](http://thetvdb.com/wiki/index.php?title=Programmers_API), and
[OMDb](http://www.omdbapi.com/) don't react well to
queries which include any kind of extra information. To get proper results from
these APIs, only the title of the content should be provided in the search
query. The accuracy of the results can be
improved by passing in the year, which can also be extracted using this library.
## Examples
Movies, series (seasons & episodes), and subtitles can be parsed. All meaningful information is
extracted and returned in a dictionary. Text which couldn't be
parsed is returned in the `excess` field.
```py
import PTN
PTN.parse('The Walking Dead S05E03 720p HDTV x264-ASAP[ettv]')
# {
# 'encoder': 'ASAP',
# 'title': 'The Walking Dead',
# 'season': 5,
# 'episode': 3,
# 'resolution': '720p',
# 'codec': 'H.264',
# 'quality': 'HDTV',
# 'website': 'ettv'
# }
PTN.parse('Vacancy (2007) 720p Bluray Dual Audio [Hindi + English] ⭐800 MB⭐ DD - 2.0 MSub x264 - Shadow (BonsaiHD)')
# {
# 'encoder': 'Shadow',
# 'title': 'Vacancy',
# 'resolution': '720p',
# 'codec': 'H.264',
# 'year': 2007,
# 'audio': 'Dolby Digital 2.0',
# 'quality': 'Blu-ray',
# 'language': ['Hindi', 'English'],
# 'subtitles': 'Available',
# 'size': 800MB,
# 'website': BonsaiHD
# 'excess': '⭐⭐'
# }
PTN.parse('Deadliest.Catch.S00E66.No.Safe.Passage.720p.AMZN.WEB-DL.DDP2.0.H.264-NTb[TGx]')
# {
# 'encoder': 'NTb',
# 'title': 'Deadliest Catch',
# 'resolution': '720p',
# 'codec': 'H.264',
# 'audio' : 'Dolby Digital Plus 2.0',
# 'network': 'Amazon Studios',
# 'season': 0,
# 'episode': 66,
# 'quality': 'WEB-DL',
# 'episodeName': 'No Safe Passage',
# 'website': 'TGx'
# }
PTN.parse('Insecure.S04.COMPLETE.720p.AMZN.WEBRip.x264-GalaxyTV')
# {
# 'title': 'Insecure'
# 'encoder': 'GalaxyTV',
# 'codec': 'H.264',
# 'season': 4,
# 'resolution': '720p',
# 'network': 'Amazon Studios',
# 'quality': 'WEBRip',
# }
```
More examples (inputs and outputs) can be found looking through `tests/files`.
## CLI
You can use PTN from your command line, where the output will be printed as JSON:
```sh
$ python cli.py 'Insecure.S04.COMPLETE.720p.AMZN.WEBRip.x264-GalaxyTV'
{
'title': 'Insecure'
'encoder': 'GalaxyTV',
'codec': 'H.264',
'season': 4,
'resolution': '720p',
'network': 'Amazon Studios',
'quality': 'WEBRip',
}
```
For help, use the `-h` or `--help` flag:
```sh
$ python cli.py --help
```
This will provide a brief overview of the available options and their usage.
### Raw info
The matches in the torrent name are standardised into specific strings, according to scene rules where possible - `'WEBDL'`, `'WEB DL'`, and `'HDRip'` are all converted to `'WEB-DL'`, for example. `'DDP51'` becomes `'Dolby Digital Plus 5.1'`. `['ita', 'eng']` becomes `['Italian', 'English']`.To disable this, and return just what was matched in the torrent, run:
```py
PTN.parse('A freakishly cool movie or TV episode', standardise=False)
```
In the CLI, you can use the `--raw` flag:
```sh
$ python cli.py --raw 'A freakishly cool movie or TV episode'
```
### Types of parts
The types of parts can be strings, integers, booleans, or lists of the first 2. To simplify this, you can enable the `coherent_types` flag. This will override the types described below according to these rules:
- `title` and `episodeName` will always be strings.
- All other non-boolean fields will become lists of the type they currently are. For example, `language` will always be a list of strings, and `episode` a list of episodes. This can be weird for some fields, but it avoids a lot of `isinstance` calls - just always use `x in y` and you should be fine.
- Boolean types will remain as booleans.
To enable this flag:
```py
PTN.parse('An even cooler movie or TV episode', coherent_types=True)
```
In the CLI, you can use the `--coherent-types` flag:
```sh
$ python cli.py --coherent-types 'A freakishly cool movie or TV episode'
```
### Parts extracted
* **audio** *(string)*
* **bitDepth** *(integer)*
* **codec** *(string)*
* **day** *(integer)*
* **directorsCut** *(boolean)*
* **documentary** *(boolean)*
* **encoder** *(string)*
* **episode** *(integer, integer list)*
* **episodeName** *(string)*
* **excess** *(string, string list)*
* **extended** *(boolean)*
* **filetype** *(string)*
* **fps** *(integer)*
* **genre** *(string, string list)*
* **hardcoded** *(boolean)*
* **hdr** *(boolean)*
* **internal** *(boolean)*
* **internationalCut** *(boolean)*
* **language** *(string, string list)*
* **limited** *(boolean)*
* **month** *(integer)*
* **network** *(string)*
* **proper** *(boolean)*
* **quality** *(string)*
* **readnfo** *(boolean)*
* **region** *(string)*
* **remastered** *(boolean)*
* **remux** *(boolean)*
* **repack** *(boolean)*
* **resolution** *(string)*
* **sbs** *(string)*
* **season** *(integer, integer list)*
* **site** *(string)*
* **size** *(string)*
* **subtitles** *(string, string list)*
* **title** *(string)*
* **unrated** *(boolean)*
* **untouched** *(boolean)*
* **upscaled** *(boolean)*
* **widescreen** *(boolean)*
* **year** *(integer)*
* **3d** *(boolean)*
## Contributing
Submit a PR on the `dev` branch, including tests for what gets newly matched (if applicable), having run the `pre-commit` hooks. Add the titles you want to add to the tests in `tests/test_generator`'s main method (in `add_titles()`), it will automatically add what's needed to `files/input.json`, `files/output_raw.json`, and `files/output_standard.json`. The fields `encoder`, `excess`, `site`, and `episodeName` don't always have to be correct - if they're giving you issues, or seem wrong, feel free to remove them from the output test files.
(What it does: `add_titles()` adds input torrent names to `tests/files/input.json` and full output json objects (with `standardise=False`) to `tests/files/output_raw.json`. It also adds the standardised output to `tests/files/output_standard.json`, only including fields that are changed, along with `title`.)
## Additions to parse-torrent-name
Below are the additions that have been made to [/u/divijbindlish's original repo](https://github.com/divijbindlish/parse-torrent-name), including other contributors' work. parse-torrent-title was initially forked from [here](https://github.com/roidayan/parse-torrent-name/tree/updates), but a lot of extra work has been done since, and given that the original repo is inactive, it was unforked.
### Updates on top of [/u/roidayan's work](https://github.com/roidayan/parse-torrent-name/tree/updates)
- Added standardisation of output strings.
- Added multi-language support.
- Added multi-episode support.
- Added a basic CLI.
- Added thread safety.
- Improved support for anime tv releases.
- Improved support for Indian releases.
- Added various fields (see field list above).
- Added proper subtitle support.
- Added proper support for matching episode names.
- Added support for full `YYYY-MM-DD`-type dates, usually useful for daily shows that otherwise have no episode name.
- Added support for 2020s release years.
- Added exceptions list for media with known, non-fixable issues.
- Expanded and improved matching for various fields.
- Fixed incorrect parsing of titles containing years.
- Fixed groups/encoders/websites mixups: a group/encoder is now just called an encoder, and a public tracker site goes under website.
- Added more tests and cleaned up previous ones.
### [/u/roidayan's work](https://github.com/roidayan/parse-torrent-name/tree/updates) on top of [the original](https://github.com/divijbindlish/parse-torrent-name)
- Added support for complete season parsing (either just a full season, or a range), not just single episodes.
- Added to various fields' patterns.
- Improved season & episode matching.
- Fixed group names from having the container & bt site name.
- Added more tests.
## License
MIT © 2015-2017 [Divij Bindlish](http://divijbindlish.in)
MIT © 2020 [Giorgio Momigliano](https://github.com/platelminto)
Raw data
{
"_id": null,
"home_page": "https://github.com/platelminto/parse-torrent-title",
"name": "parse-torrent-title",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "parse parser torrent torrents name names proper rename movie movies tv show shows series extract find quality group codec audio resolution title season episode year information filename filenames file files meaningful",
"author": "Giorgio Momigliano",
"author_email": "gmomigliano@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/df/f6/4b02b9997d2c0ba50dfebcb8306ab7643da7e6ea06a63e29f7cd76590e40/parse-torrent-title-2.8.1.tar.gz",
"platform": null,
"description": "# parse-torrent-title\n\n> Extract media information from torrent-like filename\n\n\n\nOriginally based off of [this JavaScript\nlibrary](https://github.com/jzjzjzj/parse-torrent-name).\n\nExtract all possible media information from a filename. Multiple regex\nrules are applied on the filename, each of which extracts appropriate\ninformation. If a rule matches, the corresponding part\nis removed from the filename. Finally, what remains is taken as the\ntitle of the content.\n\n\n## Install\n\nPTN can be installed automatically using `pip`.\n\n```sh\n$ pip install parse-torrent-title\n```\n\n### Requirements\n\nRequirements are **optional**. That being said, the `regex` library increases performance on Python 2 by more than 10x, so it might be worth installing with:\n\n```sh\n$ pip install -r requirements.txt\n```\n\nWith Python 3, the default `re` module is faster than `regex`, so it will always be used regardless of installed requirements.\n\n## Why?\n\nOnline APIs by providers like\n[TMDb](https://www.themoviedb.org/documentation/api),\n[TVDb](http://thetvdb.com/wiki/index.php?title=Programmers_API), and\n[OMDb](http://www.omdbapi.com/) don't react well to\nqueries which include any kind of extra information. To get proper results from\nthese APIs, only the title of the content should be provided in the search\nquery. The accuracy of the results can be\nimproved by passing in the year, which can also be extracted using this library.\n\n## Examples\n\nMovies, series (seasons & episodes), and subtitles can be parsed. All meaningful information is\nextracted and returned in a dictionary. Text which couldn't be\nparsed is returned in the `excess` field.\n\n```py\nimport PTN\n\n\nPTN.parse('The Walking Dead S05E03 720p HDTV x264-ASAP[ettv]')\n# {\n# 'encoder': 'ASAP',\n# 'title': 'The Walking Dead',\n# 'season': 5,\n# 'episode': 3,\n# 'resolution': '720p',\n# 'codec': 'H.264',\n# 'quality': 'HDTV',\n# 'website': 'ettv'\n# }\n\nPTN.parse('Vacancy (2007) 720p Bluray Dual Audio [Hindi + English] \u2b50800 MB\u2b50 DD - 2.0 MSub x264 - Shadow (BonsaiHD)')\n# {\n# 'encoder': 'Shadow',\n# 'title': 'Vacancy',\n# 'resolution': '720p',\n# 'codec': 'H.264',\n# 'year': 2007,\n# 'audio': 'Dolby Digital 2.0',\n# 'quality': 'Blu-ray',\n# 'language': ['Hindi', 'English'],\n# 'subtitles': 'Available',\n# 'size': 800MB,\n# 'website': BonsaiHD\n# 'excess': '\u2b50\u2b50'\n# }\n\nPTN.parse('Deadliest.Catch.S00E66.No.Safe.Passage.720p.AMZN.WEB-DL.DDP2.0.H.264-NTb[TGx]')\n# {\n# 'encoder': 'NTb',\n# 'title': 'Deadliest Catch',\n# 'resolution': '720p',\n# 'codec': 'H.264',\n# 'audio' : 'Dolby Digital Plus 2.0',\n# 'network': 'Amazon Studios',\n# 'season': 0,\n# 'episode': 66,\n# 'quality': 'WEB-DL',\n# 'episodeName': 'No Safe Passage',\n# 'website': 'TGx'\n# }\n\nPTN.parse('Insecure.S04.COMPLETE.720p.AMZN.WEBRip.x264-GalaxyTV')\n# {\n# 'title': 'Insecure'\n# 'encoder': 'GalaxyTV',\n# 'codec': 'H.264',\n# 'season': 4,\n# 'resolution': '720p',\n# 'network': 'Amazon Studios',\n# 'quality': 'WEBRip',\n# }\n```\n\nMore examples (inputs and outputs) can be found looking through `tests/files`.\n\n## CLI\n\nYou can use PTN from your command line, where the output will be printed as JSON:\n\n```sh\n$ python cli.py 'Insecure.S04.COMPLETE.720p.AMZN.WEBRip.x264-GalaxyTV'\n\n {\n 'title': 'Insecure'\n 'encoder': 'GalaxyTV',\n 'codec': 'H.264',\n 'season': 4,\n 'resolution': '720p',\n 'network': 'Amazon Studios',\n 'quality': 'WEBRip',\n }\n```\n\nFor help, use the `-h` or `--help` flag:\n\n```sh\n$ python cli.py --help\n```\n\nThis will provide a brief overview of the available options and their usage.\n\n### Raw info\n\nThe matches in the torrent name are standardised into specific strings, according to scene rules where possible - `'WEBDL'`, `'WEB DL'`, and `'HDRip'` are all converted to `'WEB-DL'`, for example. `'DDP51'` becomes `'Dolby Digital Plus 5.1'`. `['ita', 'eng']` becomes `['Italian', 'English']`.To disable this, and return just what was matched in the torrent, run:\n\n```py\nPTN.parse('A freakishly cool movie or TV episode', standardise=False)\n```\n\nIn the CLI, you can use the `--raw` flag:\n\n```sh\n$ python cli.py --raw 'A freakishly cool movie or TV episode'\n```\n\n### Types of parts\n\nThe types of parts can be strings, integers, booleans, or lists of the first 2. To simplify this, you can enable the `coherent_types` flag. This will override the types described below according to these rules:\n- `title` and `episodeName` will always be strings.\n- All other non-boolean fields will become lists of the type they currently are. For example, `language` will always be a list of strings, and `episode` a list of episodes. This can be weird for some fields, but it avoids a lot of `isinstance` calls - just always use `x in y` and you should be fine.\n- Boolean types will remain as booleans.\n\nTo enable this flag:\n```py\nPTN.parse('An even cooler movie or TV episode', coherent_types=True)\n```\n\nIn the CLI, you can use the `--coherent-types` flag:\n\n```sh\n$ python cli.py --coherent-types 'A freakishly cool movie or TV episode'\n```\n\n### Parts extracted\n\n* **audio** *(string)*\n* **bitDepth** *(integer)*\n* **codec** *(string)*\n* **day** *(integer)*\n* **directorsCut** *(boolean)*\n* **documentary** *(boolean)*\n* **encoder** *(string)*\n* **episode** *(integer, integer list)*\n* **episodeName** *(string)*\n* **excess** *(string, string list)*\n* **extended** *(boolean)*\n* **filetype** *(string)*\n* **fps** *(integer)*\n* **genre** *(string, string list)*\n* **hardcoded** *(boolean)*\n* **hdr** *(boolean)*\n* **internal** *(boolean)*\n* **internationalCut** *(boolean)*\n* **language** *(string, string list)*\n* **limited** *(boolean)*\n* **month** *(integer)*\n* **network** *(string)*\n* **proper** *(boolean)*\n* **quality** *(string)*\n* **readnfo** *(boolean)*\n* **region** *(string)*\n* **remastered** *(boolean)*\n* **remux** *(boolean)*\n* **repack** *(boolean)*\n* **resolution** *(string)*\n* **sbs** *(string)*\n* **season** *(integer, integer list)*\n* **site** *(string)*\n* **size** *(string)*\n* **subtitles** *(string, string list)*\n* **title** *(string)*\n* **unrated** *(boolean)*\n* **untouched** *(boolean)*\n* **upscaled** *(boolean)*\n* **widescreen** *(boolean)*\n* **year** *(integer)*\n* **3d** *(boolean)*\n\n## Contributing\n\nSubmit a PR on the `dev` branch, including tests for what gets newly matched (if applicable), having run the `pre-commit` hooks. Add the titles you want to add to the tests in `tests/test_generator`'s main method (in `add_titles()`), it will automatically add what's needed to `files/input.json`, `files/output_raw.json`, and `files/output_standard.json`. The fields `encoder`, `excess`, `site`, and `episodeName` don't always have to be correct - if they're giving you issues, or seem wrong, feel free to remove them from the output test files.\n\n(What it does: `add_titles()` adds input torrent names to `tests/files/input.json` and full output json objects (with `standardise=False`) to `tests/files/output_raw.json`. It also adds the standardised output to `tests/files/output_standard.json`, only including fields that are changed, along with `title`.)\n\n## Additions to parse-torrent-name\n\nBelow are the additions that have been made to [/u/divijbindlish's original repo](https://github.com/divijbindlish/parse-torrent-name), including other contributors' work. parse-torrent-title was initially forked from [here](https://github.com/roidayan/parse-torrent-name/tree/updates), but a lot of extra work has been done since, and given that the original repo is inactive, it was unforked.\n\n### Updates on top of [/u/roidayan's work](https://github.com/roidayan/parse-torrent-name/tree/updates)\n\n- Added standardisation of output strings.\n- Added multi-language support.\n- Added multi-episode support.\n- Added a basic CLI.\n- Added thread safety.\n- Improved support for anime tv releases.\n- Improved support for Indian releases.\n- Added various fields (see field list above).\n- Added proper subtitle support.\n- Added proper support for matching episode names.\n- Added support for full `YYYY-MM-DD`-type dates, usually useful for daily shows that otherwise have no episode name.\n- Added support for 2020s release years.\n- Added exceptions list for media with known, non-fixable issues.\n- Expanded and improved matching for various fields.\n- Fixed incorrect parsing of titles containing years.\n- Fixed groups/encoders/websites mixups: a group/encoder is now just called an encoder, and a public tracker site goes under website.\n- Added more tests and cleaned up previous ones.\n\n\n### [/u/roidayan's work](https://github.com/roidayan/parse-torrent-name/tree/updates) on top of [the original](https://github.com/divijbindlish/parse-torrent-name)\n\n- Added support for complete season parsing (either just a full season, or a range), not just single episodes.\n- Added to various fields' patterns.\n- Improved season & episode matching.\n- Fixed group names from having the container & bt site name.\n- Added more tests.\n\n## License\n\nMIT \u00a9 2015-2017 [Divij Bindlish](http://divijbindlish.in)\n\nMIT \u00a9 2020 [Giorgio Momigliano](https://github.com/platelminto)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extract media information from torrent-like filename",
"version": "2.8.1",
"project_urls": {
"Homepage": "https://github.com/platelminto/parse-torrent-title"
},
"split_keywords": [
"parse",
"parser",
"torrent",
"torrents",
"name",
"names",
"proper",
"rename",
"movie",
"movies",
"tv",
"show",
"shows",
"series",
"extract",
"find",
"quality",
"group",
"codec",
"audio",
"resolution",
"title",
"season",
"episode",
"year",
"information",
"filename",
"filenames",
"file",
"files",
"meaningful"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb56b86975a0a8abe27d35abbb34c82ba2f942fb85c67eef9cd15122f74df7af",
"md5": "486d9596a6e729f7c88bd2fa55cc6592",
"sha256": "0467809b5004065e29c60dfe120499f44832c0be49dc0e7583a1325dd81bbc88"
},
"downloads": -1,
"filename": "parse_torrent_title-2.8.1-py2-none-any.whl",
"has_sig": false,
"md5_digest": "486d9596a6e729f7c88bd2fa55cc6592",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": null,
"size": 20532,
"upload_time": "2024-01-14T18:42:17",
"upload_time_iso_8601": "2024-01-14T18:42:17.957934Z",
"url": "https://files.pythonhosted.org/packages/eb/56/b86975a0a8abe27d35abbb34c82ba2f942fb85c67eef9cd15122f74df7af/parse_torrent_title-2.8.1-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "200911b2a48c84fdae6c20c29fbf585af41253396815edca9684c9b541360c36",
"md5": "2ef7f18cd5199403ab5ee15d8853b7ba",
"sha256": "b96ee593b25fbf07150066d9d8de488b17c15c92b8b05745f984ff47db7f9fcb"
},
"downloads": -1,
"filename": "parse_torrent_title-2.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ef7f18cd5199403ab5ee15d8853b7ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20532,
"upload_time": "2024-01-14T18:42:19",
"upload_time_iso_8601": "2024-01-14T18:42:19.960879Z",
"url": "https://files.pythonhosted.org/packages/20/09/11b2a48c84fdae6c20c29fbf585af41253396815edca9684c9b541360c36/parse_torrent_title-2.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dff64b02b9997d2c0ba50dfebcb8306ab7643da7e6ea06a63e29f7cd76590e40",
"md5": "f1caefe4eb03add32096113357a9fed2",
"sha256": "939647c4bfacd2b3b878503a7bf79fcdbb11e74a895a4550eb84406d62742457"
},
"downloads": -1,
"filename": "parse-torrent-title-2.8.1.tar.gz",
"has_sig": false,
"md5_digest": "f1caefe4eb03add32096113357a9fed2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 51791,
"upload_time": "2024-01-14T18:42:21",
"upload_time_iso_8601": "2024-01-14T18:42:21.814883Z",
"url": "https://files.pythonhosted.org/packages/df/f6/4b02b9997d2c0ba50dfebcb8306ab7643da7e6ea06a63e29f7cd76590e40/parse-torrent-title-2.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-14 18:42:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "platelminto",
"github_project": "parse-torrent-title",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "parse-torrent-title"
}
JSON
