Getting started with Lumehush.

Install and first run

Early access. Lumehush isn't available to download yet. This guide describes the app as it is today so you know what to expect. Join early access to hear when it's ready.

1. Run the installer. It installs for your Windows account only and doesn't need admin rights. If the Microsoft WebView2 runtime is missing, the installer adds it.
2. Choose a library folder. This is where Lumehush keeps its database and artwork cache. Pick a drive with some free space; your media stays where it is.
3. Pick the options you want. A desktop shortcut (on by default) and "Open with Lumehush" for video and music files (off by default). Lumehush is added to the right-click Open with list only; it never makes itself your default player.
4. Add your media folders. Tell Lumehush where your films, TV shows and music live. If Jellyfin is installed, you can import its library here too.
5. Let the first scan run. You'll see live counts as titles are found, and you can start browsing straight away.

Where your media comes from

Lumehush only reads your folders. It never moves, renames or changes a media file. New files appear by themselves: Lumehush notices when Windows reports a change, so you don't need a full rescan.

Coming from Jellyfin

The import brings across films, shows, episodes, collections, music, watched state, resume points and intro and credits markers. It works from a read-only copy, so Jellyfin's database and settings are never touched.

Profiles and PINs

Each person gets their own profile, with their own Continue watching, watch history, My List, Liked songs, playlists, queue and settings. Everyone shares the library itself, so it's scanned once.

• Choose a profile: on start, Who's watching? shows everyone. If a profile has a PIN, type its 4 digits. A wrong PIN shakes and clears.
• Switch or sign out: click your avatar in the top-right corner. Switching is instant because the library doesn't reload.
• Add or edit: set a name (up to 24 characters), pick an avatar, and set, change or remove a PIN. PINs are stored scrambled, never as plain text.
• Delete a profile: removes that person's history, likes, playlists and settings. The library isn't touched.

Kids profiles

Turn on Kids profile and choose a limit. Titles above it don't appear anywhere in that profile.

Which profile opens at start

In Settings → Appearance: ask who's watching every time, continue as the last profile (a PIN is still asked for), or always start as one profile without a PIN.

Browsing and search

The bar at the top holds Home · Movies · TV Shows · Music · My List, plus search and your avatar. The arrows beside the logo go back and forward, like a browser.

• Home: a featured banner with Play and More info, then rows for Continue watching (with time left or the next episode), Recently added, New episodes, My List, Collections and genres. Hover a poster for quick Play and Add buttons.
• Movies and TV Shows: a grid of every title with sorting, genre chips and a Watched / Unwatched filter. The toolbar stays at the top as you scroll.
• Title pages: rating and quality badges (for example 4K, DV, Atmos, 5.1), the story, Play, My List, Mark watched, cast and crew, a File card, More like this, and for shows the seasons and episodes with air dates.
• Search: press Ctrl + K or / anywhere. Results are grouped into films, shows and people.

Watching

• Resume: if you stopped part-way, Lumehush offers to resume or start over. Your position is saved as you watch and whenever you pause or stop.
• Watched: a title counts as watched once you pass 90 % of it.
• Controls: the control bar appears when you move the mouse and hides by itself. It has play and pause, back and forward 10 s, next episode, volume, a scrubber with chapter marks and previews, the time the film ends, an audio chip such as 5.1 → Stereo · Night, and the subtitle, audio and fullscreen buttons.
• Skip intro and credits: a Skip button appears during intros and recaps. In Settings → Playback choose Off, Ask or Always for intros and for credits, and whether the next episode plays automatically.
• Subtitles: .srt, .ass and .vtt files with the same name as the video, or in a Subs folder, load by themselves. Choose preferred audio and subtitle languages in Settings, plus the subtitle size and background.
• Music pauses when a film starts.

Sound settings, explained plainly

Films are mixed for cinemas, so explosions are huge and voices are quiet. Open the Sound panel in the player, or Settings → Sound. Each profile has its own choices, and you can keep a different choice for one title only.

Surround to stereo

Auto (the default) mixes 5.1 and 7.1 down to stereo itself when you're on headphones, TV or laptop speakers, and leaves a real surround system alone. Off always passes surround through; Always always mixes down. The Dialogue boost style turns the voice channel up and the surrounds and bass down, balanced so nothing clips.

Night mode

Makes loud scenes quieter and quiet voices louder. Light takes the edge off; Strong keeps everything at a steady level for late nights and laptop speakers. It doesn't delay the sound, so lips stay in sync.

Clear dialogue

A gentle lift of the voice range that leaves music and effects panned to the sides untouched. It combines with either setting above.

Level volume

Plays every title at the same overall loudness. Lumehush measures a title once, quietly in the background after you first play it, and the audio chip says "normalised" only when it really is.

Whenever any of these are on, a limiter keeps peaks from crackling. Reset audio turns them off; choices saved for single titles stay.

Music

Music has a rail on the left: Listen now, Albums, Artists, and under Collection your Liked songs and playlists. The player bar stays along the bottom while you browse.

• Liked songs: click the heart, or press Alt + Shift + L for the playing song. Newest likes are always at the top. Click a column header to sort, and use the filter box to find songs as you type.
• Right-click a song for Play next, Add to queue, Add to playlist, Go to album or artist, and Remove from Liked songs (with Undo). You can also drag songs onto the queue or a playlist.
• The queue: Play next puts a song at the front; Add to queue puts it at the end. Shuffle avoids the same artist twice in a row. Each profile's queue is remembered.
• Mixes: Liked songs mix, Artist radio, Rediscover (likes you haven't played for 60 days) and Recently added.
• Lyrics: synced lyrics highlight line by line in the full-screen player. Lumehush uses a .lrc file beside the song first, then lyrics in the file.
• Gapless and crossfade: albums play with no gap. Crossfade (0 to 12 s) never fades between tracks of the same album, and Smart crossfade skips the fade when a song already ends quietly.
• Volume levelling: ReplayGain Auto (the default) uses album levels when an album plays in order and track levels on shuffle. Turn on Measure untagged songs to level songs that have no tags.

Library health

Find it in Settings → Library → Library health. It lists what's wrong and fixes it in one click. Every fix is a correction stored in Lumehush's own library; your files are never renamed or edited. Recent changes lists every fix with an Undo button.

• Mismatches: a remake matched to the original, for example. Re-match against TMDB (needs your key) or type the right title and year.
• Duplicates: Lumehush recommends which copy to keep and says why. Keeping one hides the other from the library; the file stays on disk.
• Episode numbering: fixes proposed from file names such as S03E06, with a preview before applying them all.
• Artwork: accept newly found covers side by side with the old ones, or choose a poster or cover yourself.
• Files: files Lumehush couldn't place, and library entries whose file has gone or moved. Relink or remove; nothing on disk is touched.

Settings

Open Settings from the avatar menu or press Ctrl + ,. Categories are Playback, Sound, Music, Profiles, Library, Appearance and About. Use ↑ and ↓ to move between them.

• Media folders: Add folder asks whether it holds Movies, TV shows or Music. Scan now checks every folder while you keep using the app.
• Video: hardware decoding (on by default) and which graphics card to use. Automatic picks the dedicated card if you have one.
• Appearance: Reduce effects turns off blur and large shadows; Reduce motion swaps slides and zooms for quick changes.

Get your free TMDB key (2 minutes)

TMDB (The Movie Database) is a free, community-built film and TV database. Each Lumehush user adds their own free key, and with it Lumehush can fill in missing posters, backdrops and details, and re-match wrong titles in Library health.

1. Create a free account at themoviedb.org and confirm your email.
2. Open your account's Settings → API and request an API key. Choose personal use; a short description such as "my home media library" is fine.
3. Copy the API Key (32 letters and numbers). The longer read access token works too.
4. In Lumehush, open Settings → Library → TMDB API key, paste it and press Test. When the green Working tick appears, press Save.

No key? No problem. Lumehush still works without one. It uses the artwork and details already in your files and folders (and anything brought across from Jellyfin), and music covers come from MusicBrainz and the Cover Art Archive, which need no key.

The key stays on your PC, and you can change or remove it at any time. Lumehush asks TMDB for at most one thing a second and remembers every answer.

This product uses the TMDB API but is not endorsed or certified by TMDB.

Data, backups, updates and uninstalling

Everything Lumehush knows lives in the library folder you chose at install. Settings → Library → Data folder shows the exact path and can move it to another drive.

Backing up

1. Close Lumehush.
2. Copy library.db, plus library.db-wal and library.db-shm if they exist, somewhere safe.

Updates

Settings → About → Check for updates looks for a new version only when you click; nothing runs in the background. Install and restart checks the download is intact before installing. Your library and settings are kept.

Uninstalling

Windows Settings → Apps → Installed apps → Lumehush → Uninstall. Your library is kept by default, so a reinstall picks up where you left off. Tick the box to remove it too; even then Lumehush deletes only its own database, cache and logs, never your media.

Troubleshooting

Frequently asked questions