GuessIt JS (WASM) 🎬

High-performance JavaScript port of GuessIt - Extract metadata from video filenames with WebAssembly speed

GuessIt JS is a JavaScript/WebAssembly port of the popular GuessIt Python library. It extracts metadata from video filenames with 2000x better performance than the original Python version.

🌐 Live Interactive Demos

Try GuessIt JS right now in your browser:

| Demo | Description | Link | |------|-------------|------| | 🎬 Interactive Demo | Beautiful landing page with all features and examples | Try Now → |

Experience the difference: See how WebAssembly delivers 900K+ operations/sec vs 12K ops/sec in pure JavaScript!

✨ Features

• 🚀 High Performance: WebAssembly provides native-speed parsing
• 🌐 Universal: Works in browsers and Node.js
• 📱 Lightweight: Only 38KB WASM binary + 11KB JS loader
• 🎯 Compatible: Same API and results as Python GuessIt
• 🔧 Zero Dependencies: No external libraries required
• 📊 Comprehensive: Detects 20+ metadata properties

🚀 Quick Start

Installation

npm install guessit-js

Basic Usage

import { guessit } from 'guessit-js';

const result = guessit('The.Matrix.1999.1080p.BluRay.x264-GROUP.mkv');
console.log(result);

// Output:
// {
//   title: 'The Matrix',
//   year: 1999,
//   screen_size: '1080p',
//   source: 'BluRay',
//   video_codec: 'H.264',
//   release_group: 'GROUP',
//   container: 'mkv'
// }

WebAssembly (Maximum Performance)

import { guessitWasm, initWasm } from 'guessit-js/src/wasm/wasm-real.js';

// Initialize WASM module
await initWasm();

// Parse with native speed
const result = await guessitWasm('Movie.2023.2160p.UHD.BluRay.x265.mkv');
console.log(result);
// 70x faster than JavaScript, 2000x faster than Python!

Command Line

# Install globally
npm install -g guessit-js

# Parse filenames
guessit-js "The.Matrix.1999.1080p.BluRay.x264-GROUP.mkv"
guessit-js "Game.of.Thrones.S01E01.Winter.Is.Coming.HDTV.x264-LOL.mkv"

# Batch processing
guessit-js *.mkv

🎯 What Can It Detect?

GuessIt JS can extract these properties from video filenames:

| Property | Example Values | Description | |----------|---------------|-------------| | title | "The Matrix", "Game of Thrones" | Movie/show title | | year | 1999, 2023 | Release year | | season | 1, 2, 3 | TV show season | | episode | 1, 5, 12 | TV show episode | | episode_title | "Winter Is Coming" | Episode name | | screen_size | "720p", "1080p", "2160p", "4K" | Video resolution | | video_codec | "H.264", "H.265", "XviD", "DivX" | Video encoding | | audio_codec | "DTS", "AC3", "AAC" | Audio encoding | | source | "BluRay", "HDTV", "WEB", "DVD" | Source media | | container | "mkv", "mp4", "avi" | File format | | release_group | "GROUP", "TEAM" | Release group | | language | "English", "French" | Audio language | | subtitle_language | "English", "Spanish" | Subtitle language |

✅ All features fully implemented! Every property type is now supported with comprehensive parsing rules.

📊 Performance Comparison

Latest Benchmark Results (10,000 iterations):

Python GuessIt:      ~400 ops/sec       (baseline)
GuessIt JS:       ~12,716 ops/sec      (32x faster) 
GuessIt JS + WASM: ~905,408 ops/sec    (2,264x faster!)

Memory Efficiency:

• JavaScript: ~2-5MB heap usage
• WebAssembly: ~200KB optimized binary
• Python: ~10-20MB with dependencies

Key Improvements:

• ✅ Fixed memory leaks and infinite loops
• ✅ Implemented all missing property detection rules
• ✅ Added comprehensive test coverage (91/91 tests passing)
• ✅ Optimized conflict resolution algorithms

🌐 Browser Support

Works in all modern browsers with WebAssembly support:

• Chrome 57+ ✅
• Firefox 52+ ✅
• Safari 11+ ✅
• Edge 16+ ✅

Try it now: 🌐 Interactive Demo

📖 Examples

Movies

import { guessit } from 'guessit-js';

// Comprehensive movie parsing
const movies = [
  'The.Matrix.1999.1080p.BluRay.x264-GROUP.mkv',
  'Avengers.Endgame.2019.2160p.UHD.BluRay.x265.10bit.HDR.DTS-X.7.1.mkv',
  'Parasite.2019.KOREAN.720p.BluRay.H264.AAC-VXT.mp4'
];

movies.forEach(filename => {
  const result = guessit(filename);
  console.log(`${result.title} (${result.year}) - ${result.screen_size}`);
});

TV Shows

import { guessit } from 'guessit-js';

// TV show episode parsing
const episodes = [
  'Game.of.Thrones.S01E01.Winter.Is.Coming.1080p.HDTV.x264-LOL.mkv',
  'Breaking.Bad.S03E07.One.Minute.720p.HDTV.XviD-FQM.avi',
  'The.Office.US.S02E01.The.Dundies.WEB.x264-GROUP.mp4'
];

episodes.forEach(filename => {
  const result = guessit(filename, { type: 'episode' });
  console.log(`${result.title} S${result.season}E${result.episode}: ${result.episode_title}`);
});

Batch Processing

import { guessitWasm, initWasm } from 'guessit-js/src/wasm/wasm-real.js';
import { promises as fs } from 'fs';

async function processDirectory(dirPath) {
  await initWasm();
  
  const files = await fs.readdir(dirPath);
  const videoFiles = files.filter(f => /\.(mkv|mp4|avi|mov)$/i.test(f));
  
  const results = await Promise.all(
    videoFiles.map(async filename => {
      const metadata = await guessitWasm(filename);
      return { filename, metadata };
    })
  );
  
  return results;
}

Browser Integration

<!DOCTYPE html>
<html>
<head>
    <title>GuessIt JS Demo</title>
</head>
<body>
    <input type="text" id="filename" placeholder="Enter video filename...">
    <button onclick="parseFilename()">Parse</button>
    <pre id="result"></pre>

    <script type="module">
        import { guessit } from './node_modules/guessit-js/src/index.js';
        
        window.parseFilename = () => {
            const filename = document.getElementById('filename').value;
            const result = guessit(filename);
            document.getElementById('result').textContent = JSON.stringify(result, null, 2);
        };
    </script>
</body>
</html>

🔧 API Reference

guessit(filename, options)

Parses a video filename and extracts metadata.

Parameters:

• filename (string): The video filename to parse
• options (object, optional): Parsing options
  • type ('movie' | 'episode'): Expected content type
  • single_value (boolean): Return single values instead of arrays
  • output_input_string (boolean): Include original filename in result

Returns: Object with extracted metadata

properties()

Returns information about all detectable properties.

Returns: Object describing available properties and their possible values

WASM API

initWasm()

Initializes the WebAssembly module. Must be called before using WASM functions.

guessitWasm(filename, options)

WebAssembly-powered parsing for maximum performance.

Parameters: Same as guessit() Returns: Promise with extracted metadata

🛠️ Development

Setup

git clone https://github.com/opensubtitles/guessit-js.git
cd guessit-js
npm install

Building

# Build JavaScript bundle
npm run build

# Build WebAssembly (requires Emscripten)
npm run build:wasm

# Build for development
npm run build:dev

Testing

# Run all tests
npm test

# Run simple tests
npm run test:simple

# Run benchmarks
npm run benchmark

Examples

# Basic demo
npm run demo

# WebAssembly demo
npm run demo:wasm

# Browser demo
npm run demo:browser

# Live WASM performance demo  
open https://opensubtitles.github.io/guessit-js/wasm-performance.html

🚀 Interactive WASM Demo

Experience the performance difference firsthand with our interactive browser demo:

📱 Live Interactive Demo: https://opensubtitles.github.io/guessit-js/demo-index.html

This demo showcases:

• Side-by-side comparison of JavaScript vs WebAssembly performance
• Real-time benchmarking with configurable iterations
• Memory usage analysis and bundle size comparison
• Interactive parsing with multiple test files
• Performance metrics including operations per second and speedup ratios

Features demonstrated:

• ⚡ 70x faster parsing with WebAssembly (vs JavaScript)
• 📦 Smaller memory footprint compared to Python GuessIt
• 🌐 Universal compatibility across modern browsers
• 🎯 Identical results between JS and WASM engines
• 🧪 Complete test coverage with 91/91 tests passing

🌐 Live Demo:

• Interactive Demo: Beautiful landing page with all features, examples, and performance comparisons

📋 Requirements

Runtime

• Node.js 14+ (tested on 14.x, 16.x, 18.x, 20.x, 21.x)
• Modern browser with WebAssembly support (for browser usage)

Development

• Node.js 14+
• Emscripten SDK (for building WASM)

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the LGPL-3.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• Original GuessIt Python library by the GuessIt team
• Emscripten for WebAssembly compilation
• All contributors who helped make this project possible

📚 Related Projects

• GuessIt (Python) - Original Python library
• Rebulk - Pattern matching library used by GuessIt

🔗 Links

• Documentation
• Examples
• Changelog
• Issues
• NPM Package

Made with ❤️ by the OpenSubtitles team