https://github.com/thcolin/oleoo
🏴☠️✨🎟 Oleoo - Scene/P2P/Warez release name parser
https://github.com/thcolin/oleoo
p2p release scene torrent warez
Last synced: 4 months ago
JSON representation
🏴☠️✨🎟 Oleoo - Scene/P2P/Warez release name parser
- Host: GitHub
- URL: https://github.com/thcolin/oleoo
- Owner: thcolin
- License: mit
- Created: 2017-09-11T19:58:40.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-06-18T22:29:39.000Z (12 months ago)
- Last Synced: 2025-11-27T10:25:45.821Z (6 months ago)
- Topics: p2p, release, scene, torrent, warez
- Language: JavaScript
- Homepage:
- Size: 698 KB
- Stars: 61
- Watchers: 3
- Forks: 11
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Oleoo
[](https://www.npmjs.com/package/oleoo)
[](./LICENSE.md)
[](https://deepwiki.com/thcolin/oleoo)
▒█████ ██▓ ▓█████ ▒█████ ▒█████
▒██▒ ██▒▓██▒ ▓█ ▀ ▒██▒ ██▒▒██▒ ██▒
▒██░ ██▒▒██░ ▒███ ▒██░ ██▒▒██░ ██▒
▒██ ██░▒██░ ▒▓█ ▄ ▒██ ██░▒██ ██░
░ ████▓▒░░██████▒░▒████▒░ ████▓▒░░ ████▓▒░
░ ▒░▒░▒░ ░ ▒░▓ ░░░ ▒░ ░░ ▒░▒░▒░ ░ ▒░▒░▒░
┌─────────────────────────────────────┐
| Scene/P2P/Warez release name parser |
└─────────────────────────────────────┘
🏴☠️✨🎟 - Named after an old French warez forum closed in 2008
Oleoo is a robust Javascript zero-dependency library for parsing media release names (like movies and TV shows from scene/P2P sources) to extract structured metadata. It intelligently identifies components like title, year, quality, language, and more, handling many common (and uncommon) naming conventions.
## Features
* **Comprehensive Metadata Extraction** identifying:
* Title (with intelligent cleaning and formatting)
* Alternative Title (from parentheses, brackets, or after `-`)
* Year (including ranges like `2001-2003` for `COLLECTION`)
* Type (**only** `movie` or `tvshow`)
* Source (BluRay, WEB-DL, HDTV, CAM, etc.)
* Resolution (1080p, 720p, 4K/2160p, SD, etc.)
* Encoding (x264, x265/HEVC, XviD, etc.)
* Audio details (AC3, DTS, AAC, Atmos, channels like 5.1, etc.)
* Language(s) (MULTi, MULTi-VFF, MULTI-VF2, FRENCH, VOSTFR, VFQ, TRUEFRENCH, ENGLiSH, etc., including combinations)
* Season and Episode number(s) for TV shows (handles various formats like S01E01, S01E01-E03, 1x01)
* Release Group
* Numerous Flags (Extended, Unrated, Director's Cut, Repack, Proper, Collection, Internal, 3D, HDR, Remux, etc.)
* **Robust Parsing:** Handles various delimiters (`.`, ` `, `-`, `_`) and common scene/P2P naming patterns.
* **Flexible Modes:**
* `parse()`: Strict parsing based on recognized tags.
* `guess()`: Best-effort parsing that fills in missing year/resolution details.
* **Standardized Output:** Generates a clean, standardized filename based on extracted data.
* **Customizable:** Allows providing default values and custom patterns to erase before parsing.
## Installation
```bash
yarn add oleoo
# or
npm install oleoo
```
## Basic Usage
```javascript
import oleoo from 'oleoo'
oleoo.parse('Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.H264-ARK01')
// {
// "original": "Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.H264-ARK01",
// "language": "VOSTFR",
// "languages": ["VOSTFR"],
// "source": "WEB-DL",
// "encoding": "h264",
// "resolution": "720p",
// "dub": null,
// "year": null,
// "flags": ["PROPER", "DD5.1"],
// "season": 1,
// "episode": null,
// "episodes": [],
// "type": "tvshow",
// "group": "ARK01",
// "title": "Mr Robot",
// "generated": "Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.h264-ARK01",
// "score": 6
// }
oleoo.parse('Zero Dark Thirty (2012) [1080p BluRay HDR] [FR(VFF)-EN] [x265 10-bit AC3] [GWEN]')
// {
// "original": "Zero Dark Thirty (2012) [1080p BluRay HDR] [FR(VFF)-EN] [x265 10-bit AC3] [GWEN]",
// "language": "MULTi-VF2",
// "languages": ["TRUEFRENCH", "FRENCH", "ENGLiSH"],
// "source": "BLURAY",
// "encoding": "x265",
// "resolution": "1080p",
// "dub": "AC3",
// "year": "2012",
// "flags": ["10bit", "HDR"],
// "season": null,
// "episode": null,
// "episodes": [],
// "type": "movie",
// "group": "GWEN",
// "title": "Zero Dark Thirty",
// "generated": "Zero.Dark.Thirty.2012.MULTi-VF2.1080p.10bit.BLURAY.HDR.x265.AC3-GWEN",
// "score": 8
// }
oleoo.guess('My Movie (2023)', { defaults: { language: 'ENGLiSH', resolution: 'SD' } })
// {
// "original": "My Movie (2023)",
// "language": "ENGLiSH",
// "languages": ["ENGLiSH"],
// "source": null,
// "encoding": null,
// "resolution": "SD",
// "dub": null,
// "year": "2023",
// "flags": [],
// "season": null,
// "episode": null,
// "episodes": [],
// "type": "movie",
// "group": null,
// "title": "My Movie",
// "generated": "My.Movie.ENGLiSH.2023-NOTEAM",
// "score": 1
// }
try {
oleoo.parse('Not.a.Movie-v28.1-macOS', { strict: true })
} catch (error) {
console.error(error.message)
// "Not.a.Movie-v28.1-macOS" does't follow scene release naming rules
}
```
## API Reference
### `oleoo.parse(name, [options])`
Parses the release `name` string and returns an object with extracted metadata.
* `name` (String): The release name to parse.
* `options` (Object, optional):
* `strict` (Boolean, default: `false`): If `true`, throws an error if essential tags (like source, encoding, resolution, or dub) are not found. If `false`, it attempts to parse as much as possible.
* `flagged` (Boolean, default: `true`): If `true`, includes detected flags (like `EXTENDED`, `DC`, `PROPER`, etc.) in the `generated` output string, placed according to standard conventions. If `false`, these flags are omitted from the `generated` string (but still present in the `flags` array of the result).
* `erase` (Array, default: `[]`): An array of additional regular expression patterns (as strings or RegExp objects) to remove from the input `name` *before* parsing begins. Useful for removing recurring junk specific to your source.
* `defaults` (Object, default: `{}`): An object to provide fallback values for specific fields if they cannot be parsed. Supported keys: `language`, `resolution`, `year`.
### `oleoo.guess(name, [options])`
Similar to `parse`, but always uses `strict: false` and attempts to infer missing details:
* If `year` is missing, defaults to the current system year (2025).
* If `resolution` is missing, infers based on source (e.g., BluRay -> 1080p) or flags (e.g., UHD -> 2160p), otherwise defaults to `SD`.
* Accepts the same `options` object as `parse` (though `strict` is ignored).
### Return Value (Object)
Both `parse` and `guess` return an object with the following structure:
```typescript
{
original: string | null, // Input string after basic cleanup (extension removal, erase patterns)
language: string | null, // Primary/combined language code (e.g., "FRENCH", "MULTi", "MULTi-VFF")
languages: Array, // Array of all detected language codes (e.g., ["FRENCH", "ENGLiSH"])
source: string | null, // Standardized source tag (e.g., "BluRay", "WEB-DL", "HDTV")
encoding: string | null, // Standardized encoding tag (e.g., "x264", "x265")
resolution: string | null, // Standardized resolution tag (e.g., "1080p", "720p", "2160p", "SD")
dub: string | null, // Primary detected audio tag (e.g., "AC3", "DTS", "AAC-5.1") - *See Limitations*
year: string | null, // Detected year or year range (e.g., "2023", "2001-2003")
flags: Array | null, // Array of detected flags (e.g., ["EXTENDED", "PROPER"]), null if none
season: number | null, // Detected season number for TV shows
episode: string | null, // Formatted episode number(s) for TV shows (e.g., "01", "01-03")
episodes: Array, // Array of detected episode numbers (e.g., [1], [1, 2, 3])
type: 'movie' | 'tvshow', // Detected media type
group: string | null, // Detected release group
title: string | null, // Cleaned and formatted title
alternativeTitle?: string, // Optional: Extracted alternative title
completeTitle?: string, // Optional: Combined title and alternative title
generated: string | null, // Standardized filename generated based on parsed data and `flagged` option
score: number // Parsing score (0-8), higher is better (points for Year, Source, Encoding, Resolution, Dub, Language, Group, Flags)
}
```
## Limitations / Known Issues
While Oleoo aims for broad compatibility, some release name patterns can be challenging:
* **Group Detection:** Can sometimes be confused by tags, alternative titles in parentheses, or multiple hyphenated parts near the end of the filename.
* **Title Boundaries:** Occasionally, tags (especially language tags) might be incorrectly included in the extracted title if the structure is unusual. Filenames without clear separators are difficult.
* **Complex Structures:** Very unconventional filenames, heavy use of nested brackets/parentheses, or ambiguous terms might lead to partial or incorrect parsing.
## Help Improve Oleoo! ❤️
The real world has countless release name variations! Help make Oleoo more robust by testing it with *your* own filenames. More diverse test cases lead to a better parser for everyone.
Contributing test cases is easy:
1. **Get Ready:** Clone the repo (`git clone https://github.com/thcolin/oleoo.git`) and install dependencies (`cd oleoo && yarn install`).
2. **Add Your Filenames:** Append your movie/TV show filenames (one per line) to the `./tests/fixtures/releases.txt` file.
> [!TIP]
>
> You can quickly add many names using a command like `ls /path/to/your/movies >> tests/fixtures/releases.txt` (but please review and clean up the added list!).
3. **Check Parsing & Update Tests:** Run the interactive script:
```bash
yarn test
```
This command parses all names in `releases.txt`. For any new or changed results, it will show the parsed output and ask you to confirm if it's correct (`y`) or incorrect (`n`). If incorrect, add a comment explaining the problem. This updates the `accepted.json` (correct) and `refused.json` (incorrect) fixture files.
4. **Share Your Findings (Create a PR):**
* The best way to contribute your new test cases is to **open a Pull Request** on GitHub.
* Please include your updated versions of these three files in the PR:
* `./tests/fixtures/releases.txt`
* `./tests/fixtures/accepted.json`
* `./tests/fixtures/refused.json`
* If you were also able to **fix any parsing issues** you found in `src/index.js`, include those code changes in the same PR! **Important:** Modifying the parsing logic (`src/index.js`) can easily introduce regressions (breaking previously correct parses). **This is the main challenge!** Carefully use the `yarn test` script to confirm that your changes only fix the intended issue and do not negatively affect other entries in `accepted.json`.
**Reporting Issues without a PR:**
Found a filename Oleoo doesn't handle correctly? Your bug reports are valuable! If you don't want to create a Pull Request with updated test fixtures, please **open an Issue** on the [project's GitHub Issues page](https://github.com/thcolin/oleoo/issues).
To help fix the issue quickly, please include as much detail as possible in your report:
* **Essential:** The **full original filename** that failed to parse correctly.
* **Highly Recommended:**
* The **actual JSON output** you got from Oleoo for that filename. You can copy this from the output of the `yarn test` script when you mark the parse as incorrect, or by running `oleoo.parse()` directly. Please format it using Markdown code blocks (\`\`\`json ... \`\`\`).
* A **description of what's wrong** with the actual output, or what you **expected** the output to be (e.g., "Expected group to be 'XYZ' but got 'ABC'", "Year '2023' was missed", "Flag 'REPACK' should be present").
* If you used `yarn test` and marked the parse as incorrect, include the **comment** you added explaining the error.
Even just providing the problematic filename is helpful, but more detail makes debugging much faster! Thank you for contributing!
## License
[MIT](./LICENSE.md)