MediaVault

A lightweight watch tracker for your local movie and TV show files. Point it at a folder and it tracks what you've watched, where you left off, and your notes — all stored as small human-readable sidecar files next to your media. No server, no database, no media indexing. Not a media center like Plex or Jellyfin — just watch state tracking that stays out of your way.

Features

• Stateless sidecar persistence — watch state, bookmarks, and comments are stored as human-editable TOML/Markdown files next to your media
• Three frontends — GUI (egui), CLI (clap), and TUI (ratatui), all sharing the same core library
• TMDB poster integration — automatic poster fetching and caching with a free API key
• Smart media detection — movies and shows are auto-detected from folder structure and filenames
• Torrent filename parsing — handles scene naming, anime fansubs, unicode lookalikes, and bracket-heavy release tags
• Fuzzy title matching — 4-tier scoring (exact, starts-with, word-starts, contains) for CLI queries
• Watch tracking — per-movie watched state with timestamped history, per-episode bookmarks with auto-advancing next-up
• Comments — free-form Markdown notes per entry, editable in-app or in any text editor

Roadmap

• Cross-platform support (Linux, macOS)
• Bulk operations in CLI
• Search and filtering in GUI/TUI

Getting Started

Requirements

• Rust toolchain (1.70+)
• Windows (Linux/macOS support planned)
• Optional: TMDB API key for poster fetching

Installation

1. Clone the repository:

   git clone https://github.com/bornacvitanic/mediavault.git
   cd mediavault
   

2. Build all frontends:

   cargo build --release
   

3. Binaries are at:

   • target/release/mediavault.exe (GUI)
   • target/release/mediavault-cli.exe (CLI)
   • target/release/mediavault-tui.exe (TUI)

Usage

GUI

mediavault

Open Settings to set your library path and TMDB API key.

CLI

# List all entries
mediavault-cli ls

# Show details for a specific entry
mediavault-cli get "breaking bad"

# Mark a movie as watched
mediavault-cli done "tron legacy"

# Get next episode for a show
mediavault-cli next "dr stone"

# Open entry status
mediavault-cli status "frieren"

TUI

mediavault-tui

Library Detection Rules

Sidecar Files

MediaVault only ever creates files with these names. It never touches your video files.

{video_stem}.watched.toml

# MediaVault — movie watch state

watched = true



[[watch_history]]

watched_at = "2024-11-01T20:30:00Z"

note = "Watched with Alice"

show.bookmarks.toml

# MediaVault — show bookmark state

watched_episodes = [

    "Season 1/S01E01.mkv",

    "Season 1/S01E02.mkv",

]

next_up = "Season 1/S01E03.mkv"

{video_stem}.media.comments.md

Free-form markdown. Edited directly in the app or in any text editor.

{video_stem}.media.poster.jpg

Cached poster downloaded from TMDB. Delete this file to force a re-fetch.

TMDB API Key

Get a free key at https://www.themoviedb.org/settings/api

The key is saved to:

%APPDATA%\mediavault\config.toml

Project Structure

mediavault/
├── mediavault-core/   # Shared library — scanning, sidecar I/O, TMDB, metadata parsing
│   └── src/
│       ├── lib.rs
│       ├── models.rs  # Domain types
│       ├── scanner.rs # Directory scanning
│       ├── sidecar.rs # Sidecar file read/write
│       ├── tmdb.rs    # TMDB integration and filename parsing
│       ├── player.rs  # System media player launch
│       └── library.rs # Library path resolution
├── mediavault-gui/    # egui desktop frontend
├── mediavault-cli/    # clap CLI frontend
└── mediavault-tui/    # ratatui TUI frontend

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License — see the LICENSE.md file for details.

Acknowledgements

• egui — immediate mode GUI framework
• clap — command-line argument parser
• ratatui — terminal user interface framework
• TMDB — movie and TV show metadata
• serde / toml — serialization
• chrono — date/time handling

Contact

• Email: borna.cvitanic@gmail.com
• Issues: https://github.com/bornacvitanic/mediavault/issues