initial commit

2026-01-11 17:26:49 +01:00
commit 888790fd11
240 changed files with 48691 additions and 0 deletions
@@ -0,0 +1,147 @@
+# 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:
+```bash
+pnpm install
+```
+
+When using as a dependency:
+```json
+{
+  "dependencies": {
+    "@metazla/filename-tool": "workspace:*"
+  }
+}
+```
+
+## Usage
+
+```typescript
+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
+
+```bash
+# From monorepo root
+pnpm run build
+
+# From package directory
+cd packages/filename-tool
+pnpm run build
+```
+
+### Testing
+
+```bash
+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
+```typescript
+const result = FilenameParser.parse('[HorribleSubs] Attack on Titan - 25 [1080p].mkv');
+// { title: 'Attack on Titan', episode: 25, quality: '1080p', releaseGroup: 'HorribleSubs' }
+```
+
+### Movie Filenames
+```typescript
+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
+```typescript
+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