guessit-js

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

Live Demo · API Docs · WASM Test

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

Compiles to WebAssembly via Javy (QuickJS engine). For non-JS environments (Rust, Go, C++, edge compute).

npm run wasm
echo '{"filename":"Movie.2024.1080p.mkv"}' | wasmtime wasm/guessit.wasm

Performance

| Runtime | ms/parse | vs Python | |---------|----------|-----------| | Python 3.8 (guessit 3.8.0) | 23.86 ms | baseline | | Node.js 22 (guessit-js) | 6.87 ms | 3.5x faster | | Browser (IIFE bundle) | ~2-3 ms | ~10x faster |

License

LGPL-3.0