The short version of every setting lives in the app. This page is the long version — what each option actually does and when you'd want it.
Viboplr can play audio through two different engines: the browser engine and mpv.
The Browser engine plays audio through the system webview. It works everywhere, and it is what Viboplr falls back to if mpv can't load or can't play a particular track.
The mpv engine is a native audio engine built on libmpv, the same playback core used by the mpv media player. Compared to the browser engine it:
The mpv engine is built on libmpv, which ships bundled with every copy of Viboplr — there is one download, there are no editions to choose between, and mpv is the engine Viboplr uses by default. It works offline out of the box. (On the rare machine where the bundled library can't load, Settings → Playback says so and offers to fetch a replacement copy.) If the engine can't play a particular track, Viboplr automatically falls back to the browser engine for that track.
Bypass the operating system's mixer and talk to your audio device directly.
Normally every app's sound goes through the OS mixer, which can resample and requantize audio before it reaches your DAC. With exclusive access (CoreAudio "hog mode" on macOS, WASAPI exclusive mode on Windows), Viboplr opens the output device for itself: samples travel from the file to the device untouched. This is the foundation of bit-perfect playback, and it matters most with an external DAC and lossless files.
For truly bit-perfect output, the whole chain has to leave the samples alone:
You don't have to keep that checklist in your head: while exclusive access is on, the settings row shows a live ● Bit-perfect indicator, and when the stream isn't bit-perfect it names exactly what's in the way.
Trade-offs while it's active:
Fade the current track out while the next one fades in.
The slider sets the overlap length, up to 10 seconds. At 0 (Off), tracks instead play gapless — the next track starts the instant the current one ends, which is what you want for live albums and continuous mixes. With the mpv engine, gapless transitions are sample-accurate.
Video tracks never crossfade, and crossfade is unavailable while exclusive audio access is active.
Even out loudness differences between tracks, using tags stored in your files.
Albums are mastered at wildly different loudness levels, so shuffling your library means riding the volume knob. ReplayGain fixes this: a tagging tool analyzes each file once and writes the measured loudness into its tags, and players adjust playback volume to match. Viboplr reads these tags — it doesn't compute them. Popular taggers include foobar2000, MusicBrainz Picard, and loudgain; files without tags simply play at their original volume.
Get pre-release builds through the normal auto-updater.
With beta updates on, the updater also offers beta releases — new features land there first, with a bit less polish. You're never stranded on the beta track: as soon as a stable release newer than your beta ships, the updater moves you back to stable automatically. Every update, beta or stable, is cryptographically signature-verified before install.
A few features rely on well-known command-line tools — currently ffmpeg and yt-dlp.
Some plugins and features (YouTube playback and downloads, video thumbnails, format conversion) shell out to these tools rather than reimplementing them. Settings → Dependencies shows what's needed, what's installed, and where each copy comes from:
Keep dependencies up to date automatically applies only to managed copies: Viboplr checks daily and silently installs new releases. This matters most for yt-dlp, where an outdated version is the usual reason YouTube stops working.
Completely separate libraries in one app — like browser profiles.
Each profile has its own library database, collections, play history, settings, plugins, and skin. Nothing is shared. Use them to keep contexts apart: your music vs. a shared family library, audiobooks, DJ sets, or a scratch profile for experiments.
Create and switch profiles from Settings → General. Switching restarts the app into the chosen profile, and the window title shows the profile name whenever you're not on the default one. You can also create a desktop shortcut that launches straight into a specific profile.
Choose whether video playback counts toward your listening history.
By default, only audio tracks are recorded to play history (and scrobbled to Last.fm, if you use the plugin) — watching music videos won't skew your most-played charts. Turn this on if you want video plays recorded too. The usual rules still apply: a play counts after half the track or 4 minutes, whichever comes first, and tracks under 30 seconds are never recorded.
Play the music video instead of the audio, whenever one can be found.
With Prefer video on, every track that isn't already a video — songs you queue as well as tracks picked automatically to keep the music going — is first looked up through your video providers (for example the YouTube plugin). If a music video is found, it plays in the theater; if not, the track simply plays as normal audio. Because the lookup can hit the network, there may be a short pause before playback starts, and nothing changes for tracks that are already videos.
Toggle it from the button in the queue header, or from Settings → Playback → Prefer video. It's a preference, not a hard filter: it never overrides your source ordering, and it falls back to audio whenever no video exists.
Optional, anonymous data that helps us understand how Viboplr is used — with no way to identify you.
Viboplr is local-first, and this is the one place it phones home. When enabled, it sends anonymous usage events to our own self-hosted Aptabase instance — a privacy-first analytics tool with no cookies and no persistent device identifier. Each event carries only coarse system properties (operating system, app version, language) and a session id that resets after inactivity.
What's sent: that the app was installed and launched (along with your OS, app version, and a rough bucketed library size — e.g. "1k–10k tracks"), plus a handful of anonymous, count-only signals — a track was played, music was started from somewhere (an album, artist, radio station, or playlist), a radio station was started, a plugin feature was used, a playlist or mixtape was saved or loaded, the sidebar was used to navigate, which playback engine you picked, a music source was added, a plugin was installed, a skin was applied. It also reports reliability signals when something breaks — a track that failed to play, a fallback between playback engines, a failed download or scan, a missing companion tool — so problems can be found and fixed even when no one files a report.
What's never sent: track, artist, or album names; file paths; your library contents; or anything that could identify you personally.
It's on by default and completely optional — turn it off any time in Settings → General → Anonymous usage statistics. There's nothing to lose by leaving it on, and it directly helps decide what to build and fix next.
Let an AI assistant on this computer search your library, control playback, and edit playlists, tags and likes.
One switch — Settings → General → AI control — and it's off by default. Behind it are three small pieces that work together, all of them on your own machine:
127.0.0.1, never reachable from the network. Every request must carry the access token shown in Settings, so other apps and websites can't drive your player without it. Regenerate revokes the old token any time, and switching the toggle off stops the server immediately.What an assistant can do: search tracks, artists, albums and tags; read and change the queue; play, pause, seek and skip; create and edit playlists; apply tags; like or dislike music; start radio stations; and rescan your collections. What it can never do: delete files, rewrite your audio files' metadata, install extensions, or reach anything outside your library.
Choose which sources Viboplr uses for artwork, metadata, streaming, and downloads — and the order it tries them in.
Viboplr is an orchestrator: most artwork, extra metadata, streaming, and downloading are done by plugins, and more than one plugin can often do the same job. This screen decides who goes first. Every list works the same way — drag a row by its handle to reorder it (higher = tried first), and use the switch to turn a provider on or off. When Viboplr needs something, it walks the list top-to-bottom and the first provider that succeeds wins; disabled providers are skipped entirely.
Your order and on/off choices are remembered across restarts. Reset to Defaults restores the built-in ordering at any time.
Never hit silence — when your queue runs out, Viboplr picks something else from your library and keeps playing.
With Auto Continue on, reaching the end of the queue doesn't stop the music: Viboplr chooses another track from your library and plays on. The sliders are weights that bias how it chooses — they're relative, so what matters is how large each one is compared to the others. A strategy at zero never fires.
Same format restricts the picks to the current track's file format — handy if you're keeping a listening session all-FLAC. The reset button returns every weight to its default mix. Auto Continue only runs during normal playback; it's off in Repeat All and Repeat One, where the queue already loops.
Shape the sound — boost the bass, tame harsh highs, or dial in a preset.
The equalizer has two modes, switched at the top of the panel:
Boosting Bass or Treble in Simple mode pushes the loudest moments of a track past what digital audio can represent, and something has to give. Boost clip protection chooses what:
Cuts never clip, so the protection only engages while a boost is active — with Bass and Treble flat or negative, both settings sound identical. Advanced mode has no such switch: its Pre-gain slider is the manual version of the same idea.
Use the On/Off switch to toggle the whole thing, and "Show controls in player bar" to keep a compact version within reach next to the volume. Each mode remembers its own settings.
The line under the title in the mini player — it cycles through whatever you want to know about the track.
Instead of one fixed subtitle, the mini player rotates through a list of info items: Artist · Album, Quality, Duration, Source, Plays · Rank, Tags, the lyric line currently being sung, and anything plugins add (Last.fm adds Scrobbles). Configure the list in Settings → Playback → Now playing info, or right-click the mini player and choose Now playing info… to jump straight there.
Each track begins with a preview pass that shows every enabled item once, then settles into the rotation. Items that have nothing to say for the current track (no lyrics, no tags, no play count) simply sit out rather than showing a blank. Reset to defaults puts the whole list back the way it shipped.
Give Claude Desktop, Claude Code, or any MCP client a set of typed Viboplr tools — search, playback, queue, playlists, tags, likes and more.
The MCP server is a single small script that translates an assistant's tool calls into requests against the private control server. It runs on your computer, finds the app automatically via the discovery file, and keeps the access token to itself — the assistant never sees it. The assistant must run on the same computer as Viboplr: web-based assistants (and cloud sandboxes) can't reach a server that only listens on 127.0.0.1.
Before you start: install Node.js 18 or newer and switch on Settings → General → AI control in Viboplr. No npm install needed — the script is self-contained.
The quick way — let the app write it for you. The server script ships inside Viboplr, so there is nothing to download. With the toggle on, the same settings card shows a Connect an AI assistant row:
claude mcp add form for Claude Code.Both copied forms use the absolute path of a node found on your computer, which is what avoids the most common setup failure (see the troubleshooting note below), and add --profile= automatically when you are running a named profile. Paste, then fully quit and relaunch your client.
The manual way. Point your client at the bundled copy (on macOS /Applications/Viboplr.app/Contents/Resources/mcp/viboplr-mcp.mjs), or save
viboplr-mcp.mjs
somewhere permanent (for example ~/viboplr/viboplr-mcp.mjs) — needed on older versions of Viboplr, which did not yet bundle it.
Claude Desktop — open Settings → Developer → Edit Config and add the server. Use your real paths — for command, the output of which node in a terminal, not a bare "node" (the most common setup failure; see the troubleshooting note below):
{
"mcpServers": {
"viboplr": {
"command": "/opt/homebrew/bin/node",
"args": ["/Users/you/viboplr/viboplr-mcp.mjs"]
}
}
}Then fully quit Claude Desktop (not just the window) and relaunch — MCP servers connect at startup. The Viboplr tools appear under the tools icon beneath the message box.
Claude Code — one command in the terminal, then start a new session:
claude mcp add viboplr -- node /Users/you/viboplr/viboplr-mcp.mjs
What can you ask for? Anything the app can do, in plain language. Some places to start:
--tier=full after the script path to also expose the power tools: extensions and skins, window control, logs, plugin actions and entity images. The default is deliberate — it bounds what web content flowing through the assistant could ever reach.launch_app tool launches the installed app and waits for it to answer. This works because the AI control setting persists: enable it once and every later launch brings the private server up on its own."node" that your client can't resolve — it launches outside your shell profile, so it doesn't see your PATH. Copy config above already writes the absolute path; wiring it by hand, use the full path from which node in your terminal.default profile (or the only running one); add --profile=name to target another.Three switches that let a connected AI assistant change things — not just read and play. All off by default, each one scoped, everything journaled.
With Settings → General → AI control on, the same card shows three permission rows. They gate what an assistant may write; searching, playback, queue and playlist edits, database tags and likes never need them.
.lrc/.txt) and cover.jpg next to your music, and move or rename files inside a collection. Moves are two-step by design: the assistant first gets back an exact from → to plan (nothing touched), shows it to you, and only a second call carrying that plan's fingerprint applies it — if anything on disk changed in between, the plan is rejected. Moved tracks keep their identity: tags, likes, playlists and history all follow the file.Guardrails that hold no matter which switches are on:
Ask a question or report a problem — issues and ideas are equally welcome.