guessit-js

Extract metadata (title, year, season, episode, codec, language, etc.) from media filenames — TypeScript port of Python guessit.

Live Demo · API Docs · npm

Features

• 100% compatibility with Python guessit (1035/1035 tests passing)
• 3.5x faster than Python (6.87ms vs 23.86ms per parse)
• 40+ properties detected: title, year, season, episode, resolution, codec, language, and more
• Single dependency (rebulk-js)
• Dual format: ESM and CommonJS
• TypeScript: full type definitions included
• WASM: runs in any WASI-compatible runtime

Install

npm install guessit-js

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'
// }

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); // 2

Options

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'] });

Detected Properties

Category	Properties
Title	title, alternative_title, episode_title
Episode	season, episode, episode_details, episode_count, season_count, absolute_episode, disc, part
Date	year, date
Video	screen_size, aspect_ratio, frame_rate, video_codec, video_profile, color_depth
Audio	audio_codec, audio_profile, audio_channels, audio_bit_rate
Source	source, streaming_service
Release	release_group, edition, other, proper_count
File	container, mimetype, size, crc32, uuid
Metadata	language, subtitle_language, country, type

REST API

npm start  # port 3847
curl "http://localhost:3847/api/guessit?filename=Movie.2024.1080p.mkv"

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

Performance

Runtime	ms/parse	vs Python
Python 3.8	23.86 ms	baseline
Node.js 22	6.87 ms	3.5x faster
Browser	~2-3 ms	~10x faster

License

LGPL-3.0