guessit-js
guessit-js
Extract metadata (title, year, season, episode, codec, language, etc.) from media filenames — TypeScript port of Python guessit.
Features
Runs 2191 of the 2229 cases in Python guessit's own test suite (upstream 4.5.1, its corpus and its per-rule files) — and is more correct: fixes for 32 historical upstream bugs, Python's still-open #877, and 114 of the 276 cross-parser cases Python admits failing (see Differences from Python)
Drop-in output: results use Python guessit's own notation (
"language": "French","country": "UNITED STATES","date": "2024-03-15") in the library, CLI, REST API and WASM; guessit-js only parses better. Richer codes are opt-in withoutput: 'codes'AI-agent ready: an MCP server (
npx -y guessit-js --mcp, or the hostedhttps://guessit.opensubtitles.com/mcp) and anllms.txt~2x faster than Python per parse (measured)
56 properties detected: title, year, season, episode, resolution, codec, language, ids, and more — with a machine-readable schema
Batch parsing:
guessitMany()in-process, or one POST for up to 100 namesZero runtime dependencies (rebulk-js is bundled at build time)
Dual format: ESM and CommonJS
TypeScript: full, precise type definitions (typed
GuessItResult, enum'd value fields)WASM: runs in any WASI-compatible runtime, bit-identical to the JS build
Related MCP server: ParseJet - Universal File & URL Parser
Install
npm install guessit-jsCLI
Drop-in replacement for the Python guessit command — same flags, same
output formats, byte-compared against the real Python CLI in CI on every push.
The one field excluded from that comparison is mimetype: Python reads it from
the operating system's MIME table, so the same .mkv is video/matroska on a
GitHub runner and video/x-matroska on macOS, while this port returns the
conventional x- spelling everywhere. Installs both guessit-js and guessit
binaries:
npx guessit-js "The.Dark.Knight.2008.1080p.BluRay.x264-GROUP.mkv"
# title: The Dark Knight
# year: 2008
# ...
npx guessit-js -j "Mob Psycho 100 - 09.mkv" # JSON (-y YAML, --jsonl streaming)
npx guessit-js -P title "Movie.2020.mkv" # single property
npx guessit-js -t episode "ambiguous.file.mkv" # force type
npx guessit-js @list.txt # filenames from file (also -f list.txt)
find . -name '*.mkv' | npx guessit-js --jsonl # from stdin, one JSON per line
npx guessit-js -a "Movie.2020.mkv" # advanced: value/raw/start/end
npx guessit-js -p # list detectable properties (-V with values)Parsing options match the Python CLI: -n name-only, -Y/-D date order,
-L/-C allowed languages/countries, -E episode-prefer-number,
-T/-G expected title/group, --includes/--excludes, -s single-value,
-v verbose. User config is auto-loaded from ~/.guessit/options.json and
~/.config/guessit/options.json (.yaml/.yml too; disable with
--no-user-config), plus explicit -c <file>. See npx guessit-js --help.
Extras beyond the Python CLI:
npx guessit-js --serve 3847 # instant REST API (see below)
npx guessit-js --benchmark 1000 "Movie.2020.1080p.mkv" # throughput report
eval "$(npx guessit-js --completion bash)" # shell completion (bash/zsh)Usage
import { guessit } from 'guessit-js';
const result = guessit('The.Dark.Knight.2008.1080p.BluRay.x264-GROUP.mkv');
// {
// title: 'The Dark Knight',
// year: 2008,
// screen_size: '1080p',
// source: 'Blu-ray',
// video_codec: 'H.264',
// release_group: 'GROUP',
// container: 'mkv',
// type: 'movie'
// }
// Short titles are handled correctly too:
guessit('X2.2003.720p.DSNP.WEB-DL.DDP5.1.H.264-EVO.mkv');
// { title: 'X2', year: 2003, screen_size: '720p',
// streaming_service: 'Disney+', source: 'Web', ... }Output notation
Results are a drop-in for Python guessit: the same keys and the same notation
Python's guessit --json prints, so code written against Python guessit keeps
working. guessit-js parses many names better (see
Differences); it never formats differently
by default.
Value | default ( |
|
|
|
|
region / script | dropped, as in Python: | kept: |
|
|
|
|
|
|
guessit('Movie.2020.PT-BR.1080p.mkv');
// { title: 'Movie', year: 2020, language: 'Portuguese', ... }
guessit('Movie.2020.PT-BR.1080p.mkv', { output: 'codes' });
// { title: 'Movie', year: 2020, language: { alpha3: 'por', country: 'BR' }, ... }The same switch exists everywhere: ?output=codes or "options": {"output": "codes"}
on the REST API, --output-codes on the CLI, {"options": {"output": "codes"}}
for WASM. The names are generated from babelfish, the library Python guessit uses
(scripts/python-names.py). toPythonNotation(), pythonLanguageName() and
pythonCountryName() are exported for converting codes yourself.
Batch
guessitMany() parses a list in one pass. guessit() re-parses the options and
re-merges them with the whole config on every call — more work than matching a
short name — so hoisting that out of the loop is the point. Each entry carries
the input_string plus either a result or the error that name produced, so
one unparseable name cannot abort the rest, and entries can be correlated without
relying on array position.
import { guessitMany } from 'guessit-js';
guessitMany(['A.2020.1080p.mkv', 'B.S01E02.mkv'], { type: 'episode' });
// [
// { input_string: 'A.2020.1080p.mkv', result: { title: 'A', year: 2020, ... } },
// { input_string: 'B.S01E02.mkv', result: { title: 'B', season: 1, ... } }
// ]In-process there is no cap — pass the whole library. The 100-name cap applies only to the HTTP surfaces, where it bounds one request's shape.
CommonJS
const { guessit } = require('guessit-js');
const result = guessit('Breaking.Bad.S01E02.720p.BluRay.x264-DEMAND.mkv');
console.log(result.title); // 'Breaking Bad'
console.log(result.season); // 1
console.log(result.episode); // 2Options
guessit('file.mkv', { type: 'episode' });
guessit('my 720p show S01E02', { expected_title: ['my 720p show'] });
guessit('file.mkv', { allowed_languages: ['en', 'fr'] });
guessit('file.mkv', { excludes: ['release_group'] });
guessit('file.mkv', { output: 'codes' }); // guessit-js codes instead of Python namesimport { version } from 'guessit-js'; // package version stringDetected Properties
All 56, the same set properties() advertises:
Category | Properties |
Title |
|
Episode |
|
Date |
|
Video |
|
Audio |
|
Source |
|
Release |
|
Ids |
|
File |
|
Metadata |
|
Output schema
The result is fully typed — import GuessItResult for autocomplete and type-checking:
import { guessit, properties, GUESSIT_SCHEMA, type GuessItResult } from 'guessit-js';
const r: GuessItResult = guessit('The.Dark.Knight.2008.1080p.BluRay.x264-GRP.mkv');
r.source; // typed as the closed enum: "Blu-ray" | "Web" | "HDTV" | …
properties(); // { source: ["Blu-ray", "Web", …], type: ["episode","movie"], … } for all 56 properties
GUESSIT_SCHEMA.source.enum; // the allowed values, programmaticallyproperties()— returns every emittable property with its possible values (value-constrained props list their full enum; free/computed props list[null]), mirroring Python guessit'sproperties().GUESSIT_SCHEMA— the machine-readable schema (type, cardinality, enum) for all properties.docs/output-schema.json— a JSON Schema (draft-07) of the output, for validating results or generating clients in other languages.
Regenerate the schema (after parsing changes) with npm run schema. A test (test/schema.test.ts) guarantees it never goes stale — every value emitted across the corpus must be in the schema.
REST API
Hosted demo (testing only):
curl "https://guessit.opensubtitles.com/api/guessit?filename=Movie.2024.1080p.mkv"
curl -X POST https://guessit.opensubtitles.com/api/guessit \
-H 'Content-Type: application/json' \
-d '{"filenames": ["A.2020.mkv", "B.S01E02.mkv"]}'⚠️ For testing and evaluation only — never use in production. It runs on a free Cloudflare Workers tier with a hard daily request cap and no uptime guarantee; it can be throttled, rate-limited, or removed at any time. For production, self-host (
npx guessit-js --serve, one command) or better, call the library in-process (~1.5 ms per parse, no HTTP at all).
Runs on Cloudflare Workers at the edge, CORS enabled, batch up to 100 filenames per POST, redeployed automatically with every release.
Self-hosted — no install needed beyond the package itself:
npx guessit-js --serve # port 3847 (or --serve 8080 / PORT env)
curl "http://localhost:3847/api/guessit?filename=Movie.2024.1080p.mkv"
curl -X POST http://localhost:3847/api/guessit \
-H 'Content-Type: application/json' \
-d '{"filenames": ["A.2020.mkv", "B.S01E02.mkv"], "options": {"type": "episode"}}'CLI parsing flags become server defaults: guessit-js --serve -t episode -L en.
Every surface answers in Python guessit's notation; add ?output=codes (GET) or
"options": {"output": "codes"} (POST) for guessit-js codes
(Output notation). Any other output value is a 400.
The repo also ships a fuller dev server (npm start) with the demo page,
Swagger UI at /docs, and static WASM serving.
Batch contract, identical on all three HTTP surfaces (hosted worker,
--serve, npm start):
Request |
|
Response | one entry per name, in request order, each |
Limits | 100 names per request, 1024 characters per name, 1 MiB body |
Errors |
|
A name that fails to parse becomes an error entry — the request still answers
200. The caps bound the shape of one request, not throughput: for 10k names,
send 100 requests, or skip HTTP and call guessitMany() in-process.
AI agents (MCP)
guessit-js is a Model Context Protocol server, so AI agents (Claude, Cursor, VS Code Copilot, any MCP client) can call it as a tool. Three read-only tools:
Tool | Input | Output |
|
| the result, same JSON as the library |
|
|
|
|
| every property with its possible values |
Claude Desktop: download guessit-js.mcpb
from the latest release and open it (Settings → Extensions). Runs locally, offline.
Local (stdio), no server to run:
claude mcp add guessit -- npx -y guessit-js --mcp # Claude Code{ "mcpServers": { "guessit": { "command": "npx", "args": ["-y", "guessit-js", "--mcp"] } } }(Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json, VS Code
.vscode/mcp.json with "servers" instead of "mcpServers".)
Docker: docker run -i --rm ghcr.io/opensubtitles/guessit-js node bin/cli.mjs --mcp
Remote (Streamable HTTP), nothing to install: https://guessit.opensubtitles.com/mcp
(demo tier, same limits as the hosted API), or POST /mcp on a self-hosted
npm start server.
claude mcp add --transport http guessit https://guessit.opensubtitles.com/mcpProtocol: dual-era. Stateless MCP 2026-07-28 (server/discover, per-request
_meta, no handshake) and the initialize handshake of 2025-11-25 back to
2024-11-05, on both stdio and HTTP. Every tool has an outputSchema and
returns structuredContent. Listed in the official MCP Registry
as com.opensubtitles/guessit-js.
For language models reading about the project: llms.txt
(also at /llms.txt on the hosted API) and the OpenAPI spec.
WASM
For non-JS environments (Rust, Go, C++, edge compute). Uses Javy (QuickJS → WASM).
npm run wasm
echo '{"filename":"Movie.2024.1080p.mkv"}' | wasmtime wasm/guessit.wasm
echo '{"filename":"Movie.PT-BR.mkv","options":{"output":"codes"}}' | wasmtime wasm/guessit.wasmThe WASM build is bit-identical to the JS build across the entire test corpus
(1035/1035, including accented titles) — verified by test/wasm-full.test.ts
(skipped locally until you've built the module and installed wasmtime).
Prebuilt binaries ship with every GitHub release
and as the npm package @opensubtitles/guessit-wasm
(guessit.wasm + a small node:wasi helper). Binaries are never committed to git.
wasm/build.sh downloads Javy pinned by version and sha256.
Versioning
One version number for everything built from a release tag: the guessit-js
npm package, @opensubtitles/guessit-wasm, the WASM binaries on the GitHub
release, the Docker image (ghcr.io/opensubtitles/guessit-js:<version>) and the
hosted API (/api/health reports it).
Differences from Python guessit
guessit-js is a faithful port (tracking Python 4.5.4, plus the unreleased
castellano fix #1007), but it
is not bug-for-bug identical — where Python has a genuine parsing bug,
guessit-js is corrected. Run against a live Python guessit 4.5.1 over all 2490 corpus inputs,
2247 (90.2%) come back identical; every remaining difference is listed, with a
verdict, in docs/python-parity.md. Highlights:
Cases the released Python 4.5.1 still gets wrong (each verified against the real Python CLI; the demo shows live side-by-sides):
X2.2003…(Python:bonus: 2, no title), Python's #875 (fixed upstream in 4.5.1, years after it was fixed here) and still-open #877 (Season 3 - 11, anchored weak episodes,0x539ids), Python's deadRemoveLessSpecificSeasonEpisode("episode")pass (#961 — diagnosed from this port in #962, fixed upstream by rebulk 6.0.2 plus #982, which carries this port's specificity guard), and 114 of the 276 cross-parser cases Python's own test data admits failing — fullwidth CJK bracket groups, UFC event numbers, anime compound dash titles, fully-bracketed titles, and more.32 historical upstream bugs were fixed here ahead of upstream during the 4.x catch-up (many since adopted by Python 4.4 — e.g.
Us.2019,The.Collector,grown-ish,imdb_id/tmdb_id,volume, artwork and month-date detection are now correct in both). Full ledger with dispositions:docs/upstream-issues.md.Typed, schema-described output: a precise
GuessItResultinterface with enum'd value fields,properties()mirroring Python's API, and a JSON Schema (draft-07) of the output — none of which Python provides as machine-readable artifacts.No Python runtime: zero runtime dependencies, ESM + CJS + WASM, ~2x faster.
Intentional divergences (cases where guessit-js is more correct than Python) are catalogued per-example in
docs/python-parity.md.
Where guessit-js beats Python on real traffic
Measured on ~26,000 distinct filenames from production traffic (IPTV .strm
playlists, typed search phrases, IMDb-style names, release names), the classes
below parse correctly in guessit-js and not in Python guessit 4.5.4. Every row is
a test case in test/fixtures/better-than-python.yml;
scripts/check-better-than-python.py re-runs
them through a real Python guessit and fails when Python has caught up (then the
case moves to the normal fixtures). Regenerate this table with
scripts/check-better-than-python.py --table.
Input | guessit-js | Python guessit 4.5.4 |
| title 'Some Drama', season 1, episode 16 | title "Some Drama", episode [1, 16], no season |
| title 'Top Show', season 24, episode 3 | title "Top Show", episode 24, episode_title "3" (season read as the episode) |
| title 'Quoted Series', season 1, episode 2 | title '"Quoted Series"', episode 1 (episode number dropped, quotes kept) |
| title 'Os 12 Signos', season 1, episode 4 | title '"Os', episode [12, 1] (number inside the quoted title taken as episode) |
| title 'some show', language 'en', season 4, episode 6, episode_title 'an episode' | language eng, but title "★ some show" (the list-marker symbol leaks into the title) |
| title 'some movie', language 'nl' | language nld, title "▎ some movie" |
| title 'Some Movie', year 2020, language 'da' | no language (Danish is not in Python's default allowed_languages) |
| title 'Some Movie', year 2021, language 'ta' | no language |
| title 'some movie', year 2016, language 'ml' | no language |
| title 'some show', season 1, episode 4, episode_title 'the few', year 2025, country 'US', streaming_service 'Netflix' | title "nf", alternative_title "some show", episode_title "the few" |
| title 'other show', season 1, episode 4, streaming_service 'Netflix' | title "nf", release_group "sa" (a region code), episode_title = the show |
| title 'third show', episode_title 'half loop', screen_size '2160p', streaming_service 'AppleTV' | title "a" (half of "a+"); "4k" in the provider tag is the resolution |
| title 'fourth show', episode_title 'a storm' | title "vp"; an unknown provider tag is dropped |
| title 'مسلسل', language 'ar', season 1, episode 12 | title "ar-kh", no language; v4.10: language ara with country KH (Cambodia) |
| title 'مسلسل آخر', language 'ar', season 1, episode 21 | title "ar-bdy", alternative_title = the show |
| title 'some show', season 5, episode 1 | episode_title "some show" (a copy of the title); v4.10: alternative_title "some show" |
| title 'some show', episode_title 'the real episode' | episode_title "some show" (the real episode title is lost) |
| title 'The Show', streaming_service 'Netflix' | no streaming_service, episode_title "NF" |
| streaming_service 'Amazon Prime' | no streaming_service |
| title 'X2', year 2003 | bonus 2, no title |
| title 'Some Show', video_codec 'AV1', release_group 'GRP' | no video_codec, release_group "AV1-GRP" (Python has no AV1) |
| title '1917' | year 1917, no title (a lone number is the film's title) |
| title 'how to rob a bank', source 'Camera' | release_group "cam" |
Known issues
Music files are not supported (#599):
Artist - Album/01 Track.flacis parsed with the video vocabulary (title / alternative_title), notartist/album/track. Out of scope for now.No composite
qualityfield (#802):screen_size,sourceandvideo_codecare returned separately, not combined into one string (the request is underspecified).A few ambiguous anime conventions remain (#690/#696/#747): e.g.
Re ZERO …- Season 2 - 15, romaji +(English title)— no unambiguous correct parse.Differences that are nobody's bug — a bare
2012read as a title here and a year there, Python's 23 allowed languages against this port's 60 — are listed with a verdict each indocs/python-parity.md, and the 38 upstream cases this port does not satisfy yet are parked intest/fixtures/upstream-rules-pending.yml.
Performance
Warm per-parse. The Node and Python numbers below come from one run of the same 400 corpus names through each parser on the same machine (Apple silicon, Node 20, Python 3.11, guessit 4.5.1), best of three passes after a warm-up — absolute numbers are hardware-dependent, and the live demo times it in your browser:
Runtime | ms/parse | Notes |
Node.js 20 (V8) | ~1.7 ms | ~2× faster than Python guessit on identical input — recommended for servers/CLI |
Python guessit 4.5.1 | ~3.5 ms | reference, same 400 names |
WASM (QuickJS/Javy) | ~35 ms warm · ~150 ms cold | for portability, not speed (see below) |
About the WASM build. It exists so you can run guessit in environments without a JS engine (Rust, Go, C/C++, edge/WASI runtimes). Javy compiles the bundle to QuickJS, which is an interpreter (no JIT), so per-parse compute (~35 ms) is slower than V8 and even than Python — that's inherent to the engine, not the code. If you want speed, use the Node/browser build (V8). If you need WASM, the levers that actually help:
Amortize startup — instantiate the module once and parse many filenames; most of the ~150 ms single-shot cost is wasmtime + module init, not parsing.
AOT-compile the module (
wasmtime compile guessit.wasm -o guessit.cwasm) to skip per-run JIT of the wasm itself (~30 ms off cold start).The ~35 ms warm floor is QuickJS interpretation; beating it would require a JIT-capable WASI JS engine (none production-ready) or a native port — out of scope. WASM correctness is bit-identical to the JS build.
License
Copyright (C) 2024-2026 OpenSubtitles
Licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0), the same license as the original Python guessit library this project is ported from.
Build-time and embedded third-party components (Javy, QuickJS) are covered in THIRD_PARTY_NOTICES.md.
Available Tools
3 toolsguessitParse a media filenameARead-onlyIdempotentInspect
Extract metadata from one movie or TV episode filename or release name: title, year, season, episode, episode_title, screen_size, source, video_codec, audio_codec, language, subtitle_language, release_group, streaming_service, container, type (movie or episode) and more (56 properties). Output matches Python guessit's JSON. Pass just the file name or a full path; directory names help (e.g. "Show/Season 2/episode.mkv").
Inputs: filename (required), options. Returns: Python guessit JSON: only the properties found; several values become an array.…
guessit_batchParse many media filenamesARead-onlyIdempotentInspect
Parse up to 1000 filenames in one call with the same options. Returns one entry per name, in order: {input_string, result} or {input_string, error}. Faster than calling guessit repeatedly.
Inputs: filenames (required), options. Returns: results
guessit_propertiesList guessit propertiesARead-onlyIdempotentInspect
List every property guessit can return with its possible values (enum values such as source: ["Blu-ray", "Web", ...]; [null] for free-form ones such as title).
Inputs: no named parameters. Returns: Property name -> possible values
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have clearly distinct roles: single-filename parsing, bulk parsing, and schema/introspection. An agent can trivially choose between guessit and guessit_batch based on input volume, and guessit_properties is unmistakably a metadata-listing tool.
All names are snake_case and share a predictable 'guessit_' prefix family, so the grouping is obvious. The only minor deviation is that the base parsing tool is just 'guessit' with no action suffix while its siblings carry one.
Three tools is well-scoped for a focused filename-parsing library: one core operation, one performance variant, and one introspection helper. No tool feels redundant or padding.
Core parsing, batch parsing, and property enumeration cover the main workflows end to end. A minor gap is that no tool exposes the available parsing options (e.g. type, includes/excludes) even though guessit_batch refers to 'the same options'.
Maintenance
Related MCP Connectors
Parse WebVTT, SRT, or TTML for conformance, timing, overlaps, line length, and reading speed.
Open-source developer, PDF, image, SEO and security tools over a stateless HTTP MCP server. No key.
Movie and series ranking as MCP tools: top titles, search, lookup by IMDb id. Free, no key.
Convert, clean, retime and validate SRT, WebVTT, ASS/SSA, SBV and TTML subtitles. 8 tools.
Related MCP Servers
AlicenseAqualityCmaintenanceGiving AI assistants the ability to search movies and TV shows, find torrents with magnet links, check streaming availability, and explore cast/crew metadata.521052 npm18MIT- AlicenseBqualityDmaintenanceParse any file or URL into structured text. Extract text from PDF, DOCX, YouTube, web pages, images, and 25+ formats via one API. Tools: parse_url, parse_file, get_youtube_transcript.36 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides tools for AI clients to scan, match, and scrape TMDB metadata for local media files, with safe sidecar writing or full Jellyfin-style reorganization including file renaming and NFO generation.MIT
- AlicenseAqualityCmaintenanceGives MCP clients such as Claude Code and OpenCode a static-analysis toolbox for binaries, executables, DLLs, shared objects, and web-app code, covering file identification and hashing, string extraction, PE/ELF/Mach-O/WASM parsing, disassembly, Ghidra decompilation, YARA scanning, and JavaScript deobfuscation. All inspection is read-only and never executes the target.16MIT