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
• Subtitle detection — reads embedded MKV subtitle tracks and finds external subtitle files (.srt, .ass, etc.)
• Subtitle fetching — search and download subtitles from OpenSubtitles.com with file-hash matching
• Comments — free-form Markdown notes per entry, editable in-app or in any text editor

Roadmap

• Subtitle detection and display in metadata tags
• Subtitle fetching (OpenSubtitles integration)
• Bulk operations in CLI
• Search and filtering in GUI/TUI
• macOS support

Getting Started

Requirements

• Rust toolchain (1.70+)
• Windows or Linux (macOS untested but may work)
• Optional: TMDB API key for poster fetching
• Optional: OpenSubtitles API key for subtitle 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 (GUI) — .exe on Windows
   • target/release/mediavault-cli (CLI)
   • target/release/mediavault-tui (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"

# Show subtitle info
mediavault-cli subs "tron legacy"

# Fetch subtitles from OpenSubtitles
mediavault-cli fetch-subs "tron legacy" --auto
mediavault-cli fetch-subs "frieren" --episode s01e04 --lang en

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.

API Keys

Both keys are saved to the shared config file:

Windows: %APPDATA%\mediavault\config.toml
Linux:   ~/.config/mediavault/config.toml

TMDB — poster fetching. Get a free key at https://www.themoviedb.org/settings/api

OpenSubtitles — subtitle fetching. Get a free key at https://www.opensubtitles.com/consumers

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
│       ├── subtitles.rs     # Embedded MKV and external subtitle detection
│       ├── opensubtitles.rs # OpenSubtitles.com API client
│       ├── 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
• matroska — MKV container parsing for subtitle track extraction
• serde / toml — serialization
• chrono — date/time handling

Contact

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