โโโโโโ โโโ โโโโโโ โโโโโโ โโโโโโ
โโโโ โโโโโโโ โโ โ โโโโ โโโโโโโ โโโ
โโโโ โโโโโโโ โโโโ โโโโ โโโโโโโ โโโ
โโโ โโโโโโโ โโโ โ โโโ โโโโโโ โโโ
โ โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโ โโโโโโโ
โ โโโโโโ โ โโโ โโโ โโ โโ โโโโโโ โ โโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| Scene/P2P/Warez release name parser |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ดโโ ๏ธโจ๐ - Named after an old French warez forum
closed in 2008
Oleoo parses media release names (movies and TV shows from scene/P2P sources) and extracts structured metadata: title, year, quality, language, and more, across many common (and uncommon) naming conventions.
It exists in **JavaScript**, **Go** and **Rust**. The three packages read the same [`rules.json`](./rules.json), follow the same [`SPEC.md`](./SPEC.md), and give the same result on the 6697 releases of [`tests/fixtures/`](./tests/fixtures). They share one version number and are released together.
| Language | Package | Directory | Regex engine |
|---|---|---|---|
| JavaScript | [`oleoo`](https://www.npmjs.com/package/oleoo) on npm, zero dependency | [`packages/js`](./packages/js) (reference) | built-in `RegExp` |
| Go | [`github.com/thcolin/oleoo/packages/go/v3`](https://pkg.go.dev/github.com/thcolin/oleoo/packages/go/v3) | [`packages/go`](./packages/go) | [`dlclark/regexp2`](https://github.com/dlclark/regexp2) |
| Rust | [`oleoo`](https://crates.io/crates/oleoo) on crates.io | [`packages/rust`](./packages/rust) | [`fancy-regex`](https://github.com/fancy-regex/fancy-regex) |
## 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
# JavaScript
yarn add oleoo # or: npm install oleoo
# Go (1.26 or later)
go get github.com/thcolin/oleoo/packages/go/v3
# Rust
cargo add oleoo
```
## Basic Usage
### JavaScript
```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": [],
// "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.2023.ENGLiSH-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
}
```
### Go
Options are functions, `Parse` and `Guess` return an `error` instead of throwing, and a `null` field is a `nil` pointer. A `Release` marshals to the same JSON as the JavaScript result.
```go
import "github.com/thcolin/oleoo/packages/go/v3"
release, err := oleoo.Parse("Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.H264-ARK01")
if err != nil {
log.Fatal(err)
}
fmt.Println(release.Title, *release.Season, *release.Language, *release.Resolution)
// Mr Robot 1 VOSTFR 720p
fmt.Println(release.Generated)
// Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.h264-ARK01
language := "ENGLiSH"
guessed, _ := oleoo.Guess("My Movie (2023)", oleoo.Defaults(oleoo.Release{Language: &language}))
fmt.Println(guessed.Generated)
// My.Movie.2023.ENGLiSH-NOTEAM
_, err = oleoo.Parse("Not.a.Movie-v28.1-macOS", oleoo.Strict(true))
fmt.Println(err)
// "Not.a.Movie-v28.1-macOS" does't follow scene release naming rules
```
The options are `Strict(bool)`, `Flagged(bool)`, `Erase(patterns ...string)`, `Defaults(Release)` and `CurrentYear(int)`.
### Rust
`parse` and `guess` take an `Options` and return a `Result`. `Release` implements `serde::Serialize` and serializes to the same JSON as the JavaScript result.
```rust
use oleoo::{guess, parse, Defaults, Options};
let release = parse("Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.H264-ARK01", &Options::default())?;
println!("{} {:?} {:?} {:?}", release.title, release.season, release.language, release.resolution);
// Mr Robot Some(1) Some("VOSTFR") Some("720p")
println!("{}", release.generated);
// Mr.Robot.S01.PROPER.VOSTFR.720p.WEB-DL.DD5.1.h264-ARK01
let options = Options {
defaults: Defaults { language: Some("ENGLiSH".into()), ..Defaults::default() },
..Options::default()
};
println!("{}", guess("My Movie (2023)", &options)?.generated);
// My.Movie.2023.ENGLiSH-NOTEAM
let strict = Options { strict: true, ..Options::default() };
if let Err(error) = parse("Not.a.Movie-v28.1-macOS", &strict) {
println!("{error}");
// "Not.a.Movie-v28.1-macOS" does't follow scene release naming rules
}
```
`Options` holds `strict`, `flagged`, `erase`, `defaults` and `current_year`.
## API Reference
The reference below is the JavaScript one. Go and Rust take the same options under their own names, and return the same fields.
### `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