Getting Started

pnpm add parsium-media

import { parse } from 'parsium-media';

// Analyze a title
const result = parse("The.Matrix.1999.1080p.BluRay.x264-YTS");

console.log(result.title); // "The Matrix"
console.log(result.year); // 1999
console.log(result.resolution); // "1080p"

const result = parse('Movie.2024.1080p.mkv', { explain: true });
// result.explanation = the step-by-step trace
//   { proposer: 'resolution', value: '1080p', range: [11, 16], reason: '...' }

const why = parse('Movie.2024.1080p.mkv', { explain: 'summary' });
// why.explain.fields.resolution = what it was decided on, and what lost
// 'full' adds every claim and rejection the parse considered

const result = parse('Movie.2024.1080p.mkv', { fieldConfidence: true });
// result.confidence = 1        (always present, no option needed)
// result.fieldConfidence = {
//   resolution: { certainty: 1, contested: 0 },
//   title:      { certainty: 0.5, contested: 0 }
// }
// An evidence margin, NOT a probability. It ranks and compares;
// you cannot read 0.97 as "97% likely correct".

# Parse a single filename
npx parsium-media "The.Matrix.1999.1080p.BluRay.x264-GROUP.mkv"

# With step-by-step extraction reasoning
npx parsium-media --explain "Movie.2024.1080p.BluRay.x265-GROUP.mkv"

# JSON output (truthy fields only)
npx parsium-media --json "Movie.2024.mkv"

# Parse from a file (one filename per line)
npx parsium-media --file torrents.txt --json --progress

import { createParser, claim, ev } from 'parsium-media';
import type { ParsiumPlugin } from 'parsium-media';

const TRACKER = /\[(INTERNAL|FREELEECH)\]/i;

const trackerTags: ParsiumPlugin = {
  name: 'tracker-tags',
  proposers: [{
    name: 'tracker-meta',
    propose(ctx) {
      const m = TRACKER.exec(ctx.normalized);
      if (!m) return { claims: [], rejections: [] };
      return {
        claims: [claim({
          field: 'trackerTag' as never,
          span: { start: m.index, end: m.index + m[0].length },
          tokSpan: [0, 1],
          value: m[1].toUpperCase(),
          evidence: [ev('vocab-exact'), ev('in-bracket')],
          origin: 'tracker-meta',
        })],
        rejections: [],
      };
    },
  }],
};

const parser = createParser({ plugins: [trackerTags] });
parser.parse('[INTERNAL] Movie.2024.mkv');
// -> { title: 'Movie', year: 2024, trackerTag: 'INTERNAL' }

{
  "filename": "The.Boys.S05E02.1080p.WEB.H264-TyHD.mkv",
  "options": {
    "explain": false,
    "fieldConfidence": false
  }
}

{
  "success": true,
  "data": {
    "title": "The Boys",
    "contentType": "series",
    "seasons": [5],
    "episodes": [2],
    "resolution": "1080p",
    "codec": "H.264",
    "releaseGroup": "TyHD",
    "container": "mkv",
    "confidence": 1
  },
  "meta": { "parseTimeMs": 0.6 }
}

GET https://api.parsium.nepiraw.com/v1/parse?filename=The.Boys.S05E02.1080p.WEB.H264-TyHD.mkv

{
  "filenames": [
    "Movie.2024.2160p.UHD.BluRay.x265-GROUP.mkv",
    "Anime.S01E01.1080p.WEB.H264-Sub.mkv"
  ]
}

import { createCachedParser } from 'parsium-media';

// LRU cache with 10,000 entries
const { parse, size, clear } = createCachedParser(10000);

const result = parse('Same.File.Again.mkv');
// Second call with same input is instant (cache hit)

import { parseBatch } from 'parsium-media';

const results = parseBatch(filenames, {
  onProgress: (completed, total) => {
    console.log(`${completed}/${total}`);
  },
});