Artist - Title.ext pattern, preventing untagged files from appearing as "UNKNOWN" in the library.http://, https://, and ftp:// streams directly within .m3u playlist files.config.toml.loop_mode values default to inf.Command::spawn for mpv and yt-dlp dependency checks, reducing startup overhead and resource usage.yt-dlp optimizations without iterating through the list multiple times.play() to peek inside local playlist files; if a YouTube/HTTP link is found, mpv now loads the required yt-dlp options (JS runtimes/headers).classify_target_weight helper to centralize URL prioritization rules, removing code duplication between playback methods.AtomicBool::swap(), eliminating potential race conditions between the Ctrl+C signal handler and the Drop trait.⚠️ Pre-release / Dev Build: This release introduces major changes to the indexing engine and playlist resolution logic. Please test for regressions in file scanning and playlist playback.
Artist - Title.ext pattern, preventing untagged files from appearing as "UNKNOWN" in the library.http://, https://, and ftp:// streams directly within .m3u playlist files.config.toml.loop_mode values default to inf.Command::spawn for mpv and yt-dlp dependency checks, reducing startup overhead and resource usage.yt-dlp optimizations without iterating through the list multiple times.yt-dlp configurations (JS runtimes/User-Agents) if the first track was a local file.AtomicBool::swap(), eliminating potential race conditions between the Ctrl+C signal handler and the Drop trait.This patch focuses entirely on performance, eliminating startup lag and optimizing the TUI data pipeline for instant responsiveness.
Parallel Dependency Checks:
mpv (critical) and yt-dlp (optional) in concurrent threads.yt-dlp --version check to finish before launching. Now, it processes both checks simultaneously, effectively halving the wait time (which technically isn't much but feels instant)Batched TUI Data Loading:
skim).This patch upgrades the core TUI engine for better performance and reduced memory usage.
skim to v3.2.0: This major dependency update brings a ~25% reduction in memory usage (according to skim) for the fuzzy finder, making the TUI even lighter and snappier. src/tui/mod.rs to align with skim's new API (migrated from Option<String> wrappers to zero-allocation &str slices).toml to v1.0 (stable).lofty to v0.23 (latest tag parsing fixes).The first stable release of the full Rust rewrite!
After starting as a pure Bash script and briefly becoming a Bash+Rust hybrid during development, mpv-music is now 100% Rust — a unified, blazing-fast native binary with no shell dependencies.
skim-based interface (no external fzf dependency).rayon processes thousands of files in milliseconds. It was there in hybrid butt now handled much better.musl — run anywhere without GLIBC issues.--update (which works differently now), it is at feature parity with bash version, and enhancements have been made all over the features.--update flag: Check for new releases directly from the CLI (requires --features update).--manage-dirs provides a TUI for library management.--watch or set watch = true in config, so it always plays the video, and hen --no-watch can be utilized as a negation per session.--no-video has been introduced, which disallows the video extensions to be shown in search for the current session.curl -sL https://raw.githubusercontent.com/FurqanHun/mpv-music/master/install.sh | bash
dev tag as well (if the current build is a dev one)dev.16 > dev.15, preventing false "Update Available" notifications when your local build is ahead of the repo.mpv-music --config would fail if the config file didn't exist yet. It now auto-generates defaults before opening the editor.watch setting is now saved in config.toml.watch = true in your config to have the video window open by default for every session.--no-watch to temporarily force audio-only mode (overriding watch = true from your config).--watch (-w) flag.yt-dlp integration now respects --watch to fetch video streams instead of forcing bestaudio.--no-video flag to forcefully override video_ok=true from your config (useful for temporarily hiding video files from search).--watch or disable --video-ok per session.--audio-display=no. This prevents MPV from accidentally opening a window for cover art when you only wanted music.Cargo.toml with complete crate metadata (categories, keywords, repository links).0.23.5-dev) failed to identify the matching stable release (0.23.5) as a valid update.player.rs and update.rs to use guard clauses and flattened control flow, resolving multiple Clippy warnings.deno binary in the same directory as the yt-dlp executable, improving compatibility for portable installations.--update CLI flag logic. (for now)update cargo feature (enabled in release builds).yt-dlp check message. It now explicitly states "Attempting self-update" instead of "health check" to better reflect that dependencies are being maintained.update feature flag in release workflows, ensuring all distributed binaries ship with the self-update capability.std::process::exit(0) terminated the process before Drop implementations could run. Signal handler now uses swap() instead of load() to guarantee single-execution cleanup, ensuring queue files are deleted on interrupt in both debug and release modes.exit() rather than relying on DropAtomicBool::swap() prevents double-deletion between handler and Drop cleanupBorrow<T> generics, eliminating unnecessary cloning during searches. Filters now work with references until absolutely necessary, drastically reducing allocations for large libraries.queue-{PID}.m3u8), preventing conflicts when running multiple instances simultaneously..m3u8 files littering your temp directory! 🧹-g, -a, or -b flags, you now get an interactive picker to refine your selection before playing.Borrow<T> refactor is particularly notable for big ah libraries.yt-dlp Nightly Detection:yt-dlp.TempCleaner) to ensure the temporary playlist file (queue.m3u8) is always deleted, even if MPV crashes or exits with an error.--yt flag.main.rs into a dedicated cli.rs and tui module.tui/items.rs (data structures) and tui/mod.rs (logic) for better maintainability.-p / --play-all flag. It now correctly bypasses the menu if the flag is present.TAB before confirming.Artist A; Artist B).cargo clippy fixes and optimizations.run_skim_multi_selection helper in main.rs.-l, -t, -g, -a, and -b now open the TUI picker automatically if no value is passed.--loop, --no-loop, --repeat, and --ext overrides.And saner defaults :) you no longer get my settings as defaults.
This is a Development Preview of the upcoming Rust-native version of mpv-music. We have officially swapped the legacy Bash hybrid engine for a high-performance Rust core. This dev build is intended for testing the new architecture, TUI responsiveness, and the new indexing logic.
fzf with a native skim interface. Expec integrated metadata previews, and a more responsive UI.musl, meaning it should run on almost any Linux distro without GLIBC version conflicts.$HOME:~/.config/mpv-music/~/.local/share/mpv-music/~/.local/share/mpv-music/-a (artist), -g (genre), and -b (album) flags for direct filtering. (new as in implementation is a bit different)mpv-music --help to see currently implemented features..conf files are incompatible with this version. A fresh config.toml will be generated on your first run. Also the config defaultts aren'tt sane yet... Imma change i later on (for now you get my config as default ig)Download the binary's tar ball/archive for your architecture, extract it, make it executable (chmod +x) (you don't really have to but still as a precaution), and run it. Please report any crashes or TUI glitches on the issue tracker!
This patch resolves iterator invalidation, updater logic, and missing flags
while loop. Flags like -p before --config no longer crash the script.invoke_updater to correctly handle dev/stable arguments without forcing a default, allowing the updater script to auto-detect channels properly.--add-dirs and --remove-dirs.invoke_updater(), plus --update for multi channel.mpv-music -t angel angel was being dropped, i just switched back to for loop cause i don't wanna think about it rnThis patch refactors the initialization logic to fix logging leaks and argument parsing bugs.
LOG_MAX_SIZE_KB=0 apply immediately, preventing the script from creating unwanted log files during operations like --remove-log or --config.for loop to a while loop to correctly handle multi-part flags.-a, -p, URLs) during the pre-flight check, ensuring they reach the main execution loop intact. This shit was a side affect of using switching to while loop.This patch restores functionality that i forgot i removed while refactoring code to add resolve_editor() smh
--remove-log (alias --rm-log) flag to allow users to delete the log file directly from the command line, maintaining symmetry with --remove-config.This milestone release marks the transition to Stable, introducing a dual-channel update system, granular playback controls, and integrated management tools for logs and configuration.
--dev flag for accessing bleeding-edge pre-releasesSHUFFLE and LOOP_MODE variables in mpv-music.conf, allowing users to define default behavior without modifying complex argument arrays--log and --config flags with intelligent editor resolution (detecting nvim, nano, code, etc.) for instant access to logs and settings--no-shuffle or --loop-playlist=5 always override config defaultsless) for logs while respecting the user's $EDITOR for configurationThis patch release focuses on developer tooling and stability, completely overhauling the debug infrastructure and fixing edge-case crashes during setup.
The --debug flag has been transformed from a silent toggle into a full system tracer:
set -x) and MPV internal hooks (ytdl_hook=trace) for granular execution details.mpv-music --config would fail if the configuration file did not already exist. The configuration generator is now prioritized in the boot sequence.README.md and CLI help (--help) to accurately reflect new dependency configurations and debug behaviors.rotate_log() before writing to log file.This patch ensures compatibility with package-managed yt-dlp installations by handling missing components and resolves critical API rate limits for the project website.
YTDLP_EJS_REMOTE_GITHUB config option (default: false) to fetch missing EJS runtimes on demand, fixing playback for apt/dnf installed versions that lack internal componentslatest.json), permanently eliminating "API Rate Limit Exceeded" errors for the documentation siteThis patch resurrects direct playback functionality by fixing a critical execution oversight, implements a smart crash handler for outdated dependencies, and introduces utilities for rapid configuration resets.
yt-dlp versions—the primary cause of streaming errors—and alerts the user immediately--remove-config (and --rm-conf) to safely delete the existing configuration file, allowing for a clean reset to defaults on the next launchThis release unlocks the full potential of the Rust indexer with multi-threaded parallel scanning, adds hardware-aware controls for HDD users, and exposes comprehensive configuration options for volume and video playback.
rayon, delivering massive speed gains for SSD users--serial flag (and SERIAL_MODE config) to force single-threaded indexing, preventing thrashing on mechanical drives--volume / --vol flag and VOLUME config setting to manage playback levels directlyVIDEO_OK) and serial mode via the config fileThis release introduces a high-performance Rust-based indexer for near-instant library scanning and refactors the project structure for better maintainability.
mpv-music-indexer) that replaces the legacy Bash loopx86_64 architecture and offer the pre-compiled Rust binary from GitHub Releasescrates/ and modularizing the metadata script into distinct componentsThis patch release optimizes the indexing engine by removing dead code and refines the installer for better usability.
dirs_state logic and dirs_state.json generation, reducing unnecessary file I/O and CPU cycles during scansThis release introduces interactive library management and completely rewrites the configuration engine to support complex paths.
--manage-dirs, --add-dir, and --remove-dir CLI flags for direct library managementMUSIC_DIRS persistence to use native Bash arrays, fully supporting paths with spacesbuild_music_index always sees the latest state (fixed memory/disk desync)LOG_MAX_SIZE_KB settingsfind -printf to remove process overhead--video-ok by limiting ffprobe duration/size in get_audio_metadata. As a result, general indexing --reindex,--refresh-index is now faster too.Honorary mention: - Added clean exit trap for SIGINT (Ctrl+C). (didn't really mentioned in commits so yeah)
fix: improve stability for large libraries and weird filenames - Use piping for large playlists (avoids arg limit crash) - Preserve newlines/spaces in filenames (removed tr -d) - Allow GNU Compatible find (feature check instead of version check)
mpv-music.conf.--config, --update, and --version flag handling in the configuration module.& in YouTube mixes) would break shell commands.Context: YouTube has updated their delivery methods (forcing SABR format), which now requires yt-dlp to execute JavaScript to bypass anti-bot protections. Without a valid runtime, playback was failing with HTTP 403 Forbidden errors. This update injects the necessary flags to ensure reliable streaming. (I personally haven't used yt-dlp in ages but knew about SABR format being forced, but didn't think desktop had started to do it too)
Improved Metadata Display: Changed the playback status fallback from filename to media-title. Streams will now display the actual video title (e.g., "Artist - Song") instead of the raw URL string. This doesn't affect offline media that doesn't have proper media title tags, as it will automatically fall back to the filename.
exactly what the title says, when the script was ran with --reindex or --refresh-index and the script detected the index missing or it would first create the auto index, and then run the command to reindex or refresh it. so i added a check to avoid that
switched the index from json to jsonl for better performance and scalability
while building v0.14.0 through the build.sh it uhm ran the commands in the mpv default args, which then ofc broke the script, and this fixes the issue by dividing it into more vars and then merging in create config, while also making them string literal.
enforce minimal TUI, silence spam, and fix config parsing
split the file into modules for easier development/maintenance, however it doesn't effect the user
changed parsing from comma to tab separator, and updated the updater logic to use tagged release instead of master branch
Adds --update. This fetches a separatempv-music-updater script to handle the upgrade.
This approach ensures future architectural changes (like modularization) can be handled smoothly without breaking existing installations, and avoids race conditions caused by modifying an executing file.
--help, --version, and --config before main execution or index logic.--genre, --artist, --album, --title, etc.mpv-music --config would incorrectly build an empty music index, even though only config editing was intended--config and --config=EDITOR will only open the config file and exit—no more index creation, no find errors, just a clean setup experience--audio-display=no as a default mpv flag so embedded cover art is never shown or rendered, even with --no-videoNo changes to other features.
--genre, --artist, --album, --title, --play-all, --playlist) and interactive menu.Note:
- Recommended: Rebuild your music index after updating (mpv-music --reindex).
- The configuration file now requires this line for logging.
If set to 0, it won't store any logs (but will still display them if --debug is passed):
sh
LOG_MAX_SIZE_KB=1024
If upgrading, add this line to your config file, or delete your config and let the script regenerate it.
.m3u, .m3u8, .pls) directly from the interactive menu.jq call for all tags.Note:
- It is recommended to rebuild your music index after updating.
- The configuration file now requires this line for playlist extensions:
sh
PLAYLIST_EXTS="m3u m3u8 pls"
If upgrading, add this line to your config file, or remove your config and let the script regenerate it.
feat: Enhance script robustness with temp file management and logging for v0.9.0
feat(config): add --config flag to edit configuration
- Add --config flag to open the config in nano/vi
- Support custom editor with --config=EDITOR syntax
- Update help text to document new functionality
- Fix function order by moving create_config() definition earlier
fix(mode2): restore custom directory support in track mode - Fix regression in track mode where custom directories were ignored - Implement temporary indexing for custom directories in track mode - Maintain same preview interface for consistency
feat(ui): add media type indicators to track listing
This milestone release consolidates all work since v0.4.0.
--reindex and --refresh-index reliable.jq and ffprobe as required dependencies.mediainfo as optional dependency.yt-dlp is not found for full URL support.