Building MiraVault: a local-first media library app for Windows

#opensource #electron #react #desktopapp

Building MiraVault: a local-first media library app for Windows

I have been working on MiraVault, an open-source desktop app for Windows focused on organizing and watching local media libraries.

The idea came from a simple problem: many people keep series, movies, IPTV playlists, subtitles, and downloads spread across different folders and drives. Existing solutions are powerful, but they often expect a server, an account, a cloud service, or a very specific library structure.

MiraVault tries to solve a smaller, more local problem:

Take the media files you already have and make them easier to organize, browse, play, and continue watching.

Repository:
https://github.com/Destr0code/MiraVault

What MiraVault does

MiraVault is still in beta, but it already includes:

A visual library for local series and movies.
Automatic watch progress.
Watched and unwatched episode tracking.
Folder organization for series, seasons, and episodes.
Metadata enrichment without private API keys.
Covers, synopsis, ratings, cast, and episode information where available.
VLC integration for robust playback.
IPTV playlist support from M3U/M3U8 sources.
Subtitle handling.
Early torrent/download management experiments.

It does not provide media content, IPTV lists, torrent indexes, trackers, or providers.

Why local-first?

I wanted MiraVault to work without an account and without a hosted backend.

The app stores user data locally: library paths, settings, watch progress, metadata cache, and preferences. External requests only happen when a feature needs them, such as checking GitHub releases, fetching metadata, resolving subtitles, or loading a user-provided IPTV playlist.

That design keeps the project simple and transparent.

Tech stack

MiraVault is built with:

Electron
React 19
Vite
Tailwind CSS
Zustand
better-sqlite3
electron-store
hls.js
WebTorrent experiments
Electron Builder

The app is currently Windows-focused.

Some technical challenges

A few parts turned out to be more interesting than expected.

Organizing messy folders

Detecting series from filenames is harder than it sounds. MiraVault has to handle different naming styles, season/episode formats, quality tags, subtitle files, incomplete downloads, duplicated episodes, and residual files like .txt, .url, or archives.

The organizer now uses a preview-first approach so users can see planned changes before applying them.

Playback

I originally explored internal playback more deeply, but codec support quickly became a practical issue. VLC is still the most reliable fallback for MKV, HEVC/H.265, multichannel audio, subtitles, and some IPTV streams.

The current direction is: use internal playback where possible, but integrate VLC for serious compatibility.

Metadata without API keys

I want the project to stay easy to clone and run, so I avoided private API keys. MiraVault uses public/fallback metadata sources where possible and caches results locally.

This is not perfect, especially with movies or shows that share the same name, but it keeps the app open-source friendly.