meta-sort/packages/shared/filename-tool/README.md

Filename Tool

TypeScript library for extracting metadata from media filenames, designed for the Meta Orbit ecosystem.

Overview

Filename Tool parses media filenames to extract structured metadata such as titles, seasons, episodes, quality, languages, and other relevant information. It's designed to work with various naming conventions used in media files.

Features

• Title Extraction: Identifies show/movie titles from filenames
• Episode & Season Detection: Parses episode and season numbers in various formats
• Quality Detection: Identifies resolution (1080p, 720p, 4K) and quality indicators
• Language Detection: Extracts language codes and audio track information
• Release Group: Identifies fansub/release group tags
• Format Support: Handles multiple filename patterns and conventions
• Platform Agnostic: Dual builds for Node.js and browser environments

Installation

From the monorepo root:

pnpm install

When using as a dependency:

{
  "dependencies": {
    "@metazla/filename-tool": "workspace:*"
  }
}

Usage

import { FilenameParser } from '@metazla/filename-tool';

// Parse a filename
const result = FilenameParser.parse('[SubsPlease] Naruto - 01 (1080p) [12345678].mkv');

console.log(result);
// {
//   title: 'Naruto',
//   episode: 1,
//   season: 1,
//   quality: '1080p',
//   releaseGroup: 'SubsPlease',
//   hash: '12345678',
//   extension: 'mkv'
// }

Supported Filename Patterns

TV Shows

• ShowName S01E01.mkv
• ShowName - 01.mkv
• [Group] ShowName - 01 (1080p).mkv
• ShowName.S01E01.1080p.WEB-DL.mkv

Movies

• MovieName (2024) 1080p BluRay.mkv
• MovieName.2024.1080p.BluRay.x264.mkv
• [Group] MovieName (2024).mkv

Quality Detection

• Resolution: 1080p, 720p, 2160p, 4K, 8K
• Source: BluRay, WEB-DL, HDTV, DVDRip
• Codec: x264, x265, HEVC, AV1

Language Detection

• Audio languages: eng, jpl, spa, fre, etc.
• Subtitle languages: [eng sub], [multiple subs]
• Dual audio: [eng+jpl]

Architecture

Build Configuration

Built with tsup for dual output:

• Node.js: dist/index.js (ESM) and dist/index.cjs (CommonJS)
• Browser: dist/index-browser.js (ESM) and dist/index-browser.cjs (CommonJS)

Pattern Matching

Uses regex patterns and heuristics to handle various filename formats:

• Episode number detection with multiple patterns
• Title cleanup (remove tags, group names)
• Quality and resolution parsing
• Hash/CRC extraction

Development

Building

# From monorepo root
pnpm run build

# From package directory
cd packages/filename-tool
pnpm run build

Testing

cd packages/filename-tool
pnpm test

Uses Vitest for unit tests with comprehensive filename pattern coverage.

Integration

Used by:

• meta-mesh: Primary metadata extraction from filenames
• meta-orbit: Filename normalization for distributed queries
• meta-ui: Display and search filename metadata

Examples

Anime Filenames

const result = FilenameParser.parse('[HorribleSubs] Attack on Titan - 25 [1080p].mkv');
// { title: 'Attack on Titan', episode: 25, quality: '1080p', releaseGroup: 'HorribleSubs' }

Movie Filenames

const result = FilenameParser.parse('The.Matrix.1999.1080p.BluRay.x264-GROUP.mkv');
// { title: 'The Matrix', year: 1999, quality: '1080p', source: 'BluRay', codec: 'x264' }

Multi-Episode

const result = FilenameParser.parse('Show.Name.S01E01-E03.1080p.mkv');
// { title: 'Show Name', season: 1, episodes: [1, 2, 3], quality: '1080p' }

Contributing

This package is part of the Meta Orbit monorepo. See the root README for contribution guidelines.

License

MIT - Same as Meta Orbit monorepo