From 0447acd6c5f2000f7128939f6e816458b50c6f0e Mon Sep 17 00:00:00 2001 From: Jarian Cottingham Date: Thu, 20 Aug 2026 20:18:56 +0000 Subject: [PATCH] docs: rewrite README, add GitHub Actions CI --- .github/workflows/test.yml | 38 ++++++++++ README.md | 146 ++++++++++++++++++++++++++++++++----- 2 files changed, 165 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/test.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..5ba0155 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,38 @@ +name: Test + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + js: + name: JavaScript (vitest) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - run: npm test + + rust: + name: Rust (workspace) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + components: clippy rustfmt + - uses: Swatinem/rust-cache@v2 + with: + workspaces: Rust->target backend->target ui->target + - name: Check + run: cargo check --workspace + - name: Clippy + run: cargo clippy --workspace --all-targets + - name: Test + run: cargo test --workspace diff --git a/README.md b/README.md index fc25c88..4cd4be0 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,138 @@ # MovieMapper -A desktop application for organizing and managing movie and TV show collections. +Desktop application for organizing and managing movie and TV show collections. +Scan media directories, extract metadata with FFmpeg, tag files as extras or +commentary, and move them into Jellyfin-compatible folder structures — with a +full audit trail. + +[![CI](https://github.com/actions/workflows/test.yml/badge.svg)](https://github.com/actions/workflows/test.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ## Features -- Browse and scan directories for media files -- Search TV shows using TheTVDB API -- View show details, seasons, and episodes -- Rename files by clicking on the file name -- Display video durations in mm:ss format +- **Directory scanning** — non-recursive folder browsing with real-time progress +- **Metadata extraction** — duration, video quality, and FPS via `ffprobe` +- **File tagging** — mark files as `extra` or `commentary` with visual state +- **Jellyfin-compatible moves** — tagged files move into spec-compliant folders + (`extras/`, `commentary/`, `behind the scenes/`, ...) +- **TheTVDB integration** — search shows, browse seasons/episodes, map episodes + to `SxxExx` naming convention +- **Audit logging** — every move/rename writes a `.audit` entry in the target + directory; nothing happens silently +- **Progress reporting** — IPC-driven progress updates during scans -## Installation +## Architecture -1. Clone the repository -2. Install dependencies: `npm install` -3. Run the application: `npm start` or `electron .` +Three implementations share the same core concepts (scanner → metadata → +tagging → mapping → audit): -## Dependencies +``` +┌─────────────────────────────────────────────────────────────┐ +│ MovieMapper │ +├──────────────┬──────────────────────────┬───────────────────┤ +│ Electron │ Rust core (crate) │ iOS (Swift) │ +│ desktop app │ movie_mapper │ companion client │ +│ ├──────────────────────────┤ │ +│ main.js │ model/ Show, Season, │ SharedModels/ │ +│ renderer.js │ Episode │ Swift mirrors │ +│ index.html │ service/ │ │ +│ utils/ │ FileScanner │ build.sh │ +│ │ MetadataExtractor │ archive.sh │ +│ Electron │ TVDBClient │ Xcode project │ +│ IPC bridge │ FileMapper │ │ +│ │ TagManager │ │ +│ │ AuditLogger │ │ +└──────────────┴──────────────────────────┴───────────────────┘ +``` -- Electron -- fluent-ffmpeg (for video duration detection) -- TheTVDB API integration +| Component | Stack | Role | +|-----------|-------|------| +| `main.js`, `renderer.js` | Electron (Node 20) | Desktop UI, IPC handlers, filesystem ops | +| `utils/fileUtils.js` | Node + fluent-ffmpeg | Directory scanning, ffprobe metadata | +| `Rust/` (crate `movie_mapper`) | Rust, tokio, reqwest | Reusable core: scanner, TVDB client, mapper, tags, audit | +| `backend/` (crate) | Rust | Async backend integration layer | +| `ui/` (crate) | Rust, Iced | Native Rust UI prototype | +| `SharedModels/` | Swift | Data models for the iOS companion | -## Usage +### Data flow -1. Click "Select Directory" to choose a folder containing media files -2. The application will scan the directory and display media files with their durations -3. Click on any file name to rename it -4. Use the search functionality to find TV shows and their details \ No newline at end of file +``` +directory scan ──▶ ffprobe metadata ──▶ tag (extra/commentary) + │ + ▼ + Jellyfin folder mapping + │ + ▼ + .audit log entry per operation +``` + +## Project structure + +``` +├── main.js # Electron main process (IPC, file ops, TVDB) +├── renderer.js # Renderer process (UI state, events) +├── index.html # UI (dark theme) +├── preload.js # Context bridge +├── utils/fileUtils.js # Directory scan + ffprobe metadata +├── tests/ # vitest suite (118 tests) +│ └── legacy/ # Earlier node:test integration tests +├── Rust/ # Rust core crate (movie_mapper) +│ ├── src/service/ # Scanner, TVDB client, mapper, tags, audit +│ ├── src/model/ # Show, Season, Episode, MediaFile +│ └── tests/ # Unit, integration, e2e, benchmarks +├── backend/ # Rust backend integration crate +├── ui/ # Rust Iced UI prototype +├── SharedModels/ # Swift models (iOS companion) +└── docs/ # Design docs, phase summaries, plans +``` + +## Getting started + +### Desktop app (Electron) + +Prerequisites: Node.js 20+, npm, `ffmpeg`/`ffprobe` on PATH. + +```bash +npm install +cp .env.example .env # add your TVDB_API_KEY +npm start +``` + +### Rust core + +```bash +cargo build --workspace +cargo test --workspace +``` + +### Tests + +```bash +npm test # vitest suite (JS) +cargo test --workspace # Rust unit + integration +``` + +## Configuration + +| Variable | Required | Description | +|----------|----------|-------------| +| `TVDB_API_KEY` | for TVDB search | TheTVDB v4 API token | + +## Jellyfin folder compatibility + +Moves target the [Jellyfin extras folder specification](https://docs.jellyfin.org/): +`behind the scenes`, `deleted scenes`, `interviews`, `scenes`, `samples`, +`shorts`, `featurettes`, `clips`, `other`, `extras`, `trailers`, +`theme-music`, `backdrops`. + +## Documentation + +- [Project overview](docs/PROJECT_OVERVIEW.md) +- [Feature matrix](docs/FEATURES.md) +- [Rust implementation notes](docs/RUST_IMPLEMENTATION.md) +- [Folder navigation design](docs/FOLDER_NAVIGATION_PLAN.md) +- [iOS plan](docs/iOS_PLAN.md) + +## License + +[MIT](LICENSE)