video-filename-parser

Parse movie and TV release names into normalized metadata. The parser is heavily inspired by Radarr's movie parsing.

Try the demo

Installation

npm install @ctrl/video-filename-parser

The package is ESM-only and requires Node.js 20 or newer.

Usage

Movies

import { filenameParse } from '@ctrl/video-filename-parser';

const movie = filenameParse('This.is.40.2012.PROPER.UNRATED.720p.BluRay.x264-Felony');

{
  "title": "This is 40",
  "year": "2012",
  "resolution": "720P",
  "sources": ["BLURAY"],
  "videoCodec": "x264",
  "revision": {
    "version": 2,
    "real": 0
  },
  "group": "Felony",
  "edition": {
    "unrated": true
  },
  "languages": ["English"]
}

TV shows

Pass true as the second argument to parse seasons, episodes, air dates, and other TV-specific metadata.

const show = filenameParse('The Office US S09E06 HDTV XviD-AFG', true);

show.title;
// "The Office US"

show.seasons;
// [9]

show.episodeNumbers;
// [6]

Text after the season and episode can be returned as remainder:

const episode = filenameParse('The Expanse - S01E02 - The Big Empty', true);

episode.remainder;
// "The Big Empty"

Parameters

Parameter	Type	Default	Description
name	string	—	Release name or filename to parse.
isTv	boolean	false	Enables season, episode, and air-date detection.

filenameParse returns ParsedMovie by default and ParsedShow when TV metadata is found in TV mode. The exported TypeScript types describe the full result. Metadata that is not present or cannot be inferred is generally omitted; year and group may be null.

Notes

Releases without a recognized language marker default to English. multi means the name contains a multi-language marker; it does not guess languages that are not named.

Parsing is heuristic, so ambiguous names may need application-specific handling.

Focused parsers

The package also exports the focused parsers used by filenameParse for consumers that only need one piece of metadata.

import { parseAudioCodec, parseResolution } from '@ctrl/video-filename-parser';

parseResolution('Movie.2026.2160p.WEB-DL').resolution;
// "2160P"

parseAudioCodec('Movie.2026.WEB-DL.DDP5.1').codec;
// "Dolby Digital Plus"

Revision upgrades

isRevisionUpgrade({ current, candidate, isTv }) returns true when the candidate is a newer revision of the same parsed release type.

Release identity includes title, year, resolution, sources, quality modifier, video codec, languages, multi-language status, edition flags, and TV episode or season details. Release group and audio details are ignored. HDR and Dolby Vision releases are therefore kept separate.

import { isRevisionUpgrade } from '@ctrl/video-filename-parser';

isRevisionUpgrade({
  current: 'Movie.Title.2026.HDR.2160P.WEB.H265-GROUP',
  candidate: 'Movie.Title.2026.PROPER.HDR.2160p.WEB.h265-OTHER',
});
// true

See also

• Radarr movie parser
• Sonarr TV parser
• GuessIt