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/hrl-code/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.

Current status

MiraVault is beta software. It has public releases, a Windows installer, a privacy policy, changelog, and GitHub Actions build workflow.

There is still a lot to improve before 1.0, especially around:

• metadata matching


• large libraries


• torrent/download stability


• IPTV edge cases


• installer signing


• screenshots and onboarding


• tests and release checks

What I would like feedback on

I would appreciate feedback from other developers and users around:

• Electron packaging for Windows


• local-first architecture


• metadata matching strategies


• folder organization edge cases


• UI/UX for media libraries


• how to make the project easier to trust before downloading

Repository:

https://github.com/hrl-code/MiraVault

Latest releases:

https://github.com/hrl-code/MiraVault/releases

Privacy policy:

https://github.com/hrl-code/MiraVault/blob/main/PRIVACY.md

Thanks for reading. Any feedback, issues, or ideas are welcome.