{"id":14982627,"url":"https://github.com/olegantonyan/mpz","last_synced_at":"2026-05-30T06:04:42.847Z","repository":{"id":45271015,"uuid":"208877839","full_name":"olegantonyan/mpz","owner":"olegantonyan","description":"Music player for big local collections","archived":false,"fork":false,"pushed_at":"2026-05-23T05:37:18.000Z","size":22543,"stargazers_count":104,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-05-23T07:33:10.054Z","etag":null,"topics":["audio","audio-player","linux","linux-app","linux-desktop","linux-desktop-app","multimedia","music","music-player","music-player-application","player","qt","qt-gui","qt5","qt6","qtmultimedia"],"latest_commit_sha":null,"homepage":"https://mpz-player.org/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olegantonyan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-09-16T19:10:58.000Z","updated_at":"2026-05-23T05:33:09.000Z","dependencies_parsed_at":"2024-02-16T19:44:38.386Z","dependency_job_id":"d7d6a7fe-a8ca-41b1-9b8b-a196a4eace38","html_url":"https://github.com/olegantonyan/mpz","commit_stats":{"total_commits":787,"total_committers":2,"mean_commits":393.5,"dds":"0.0012706480304955914","last_synced_commit":"e2b67fd8fafa54f04bccf4135dc4bc2383b27a8b"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/olegantonyan/mpz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olegantonyan%2Fmpz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olegantonyan%2Fmpz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olegantonyan%2Fmpz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olegantonyan%2Fmpz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olegantonyan","download_url":"https://codeload.github.com/olegantonyan/mpz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olegantonyan%2Fmpz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33681815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audio-player","linux","linux-app","linux-desktop","linux-desktop-app","multimedia","music","music-player","music-player-application","player","qt","qt-gui","qt5","qt6","qtmultimedia"],"created_at":"2024-09-24T14:05:46.072Z","updated_at":"2026-05-30T06:04:42.832Z","avatar_url":"https://github.com/olegantonyan.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GPLv3 License](https://img.shields.io/badge/license-GPL--3.0-blue)](https://github.com/olegantonyan/mpz/blob/master/license.txt)\n[![tests](https://github.com/olegantonyan/mpz/actions/workflows/tests.yml/badge.svg)](https://github.com/olegantonyan/mpz/actions/workflows/tests.yml)\n[![OmniPackage repositories badge](https://repositories.omnipackage.org/mpz/stable/badge.svg)](https://repositories.omnipackage.org/mpz/stable/install.html)\n[![OmniPackage repositories badge](https://repositories.omnipackage.org/mpz/next/badge.svg)](https://repositories.omnipackage.org/mpz/next/install.html)\n\n# Music player for big local collections\n\n![image](https://raw.githubusercontent.com/olegantonyan/mpz/gh-pages/images/mpz-workflow.apng)\n\nIf you like organizing your music in folders, then this player might be for you. It doesn't try to index all the files into a library, but rather treats your files and folders as the library and provides a convenient way to create playlists directly from folders. Similar to Foobar2000's Album List, but it's not an attempt to clone.\n\nMore screenshots here: https://mpz-player.org\n\nThis player is an attempt to create the \"perfect\" player for the author. It doesn't try to be groundbreaking — it just gets the job done. The main feature is the 3-column UI and the way you manage playlists. Choose library folders, middle-click on a folder, and a playlist will be created from it.\n\nWhy \"big local collections\"? \"Local\" as opposed to streaming services (which are fine, but this player's goal is playing music you have on your hard drive); \"big\" means the collection is large enough that managing it becomes hard. Internet radio streaming is also supported.\n\nIn version 2.0.0 an experimental [mpd](https://musicpd.org) client mode was added. You can add an mpd server as a library folder. There are limitations and caveats, see below.\n\n## Features\n\n- 3-column UI which allows you to quickly create playlists from folders and switch between playlists;\n- Built with C++/Qt - fast and responsive native UI;\n- Supports internet radio in `m3u` and `pls` playlists formats;\n- Supports CUE sheets;\n- Supports MPRIS on Linux for remote control (for example, via [KDE Connect](https://kdeconnect.kde.org/));\n- Configuration in 2 yaml files: one for global (portable between computers) and one local (for settings specific to the current installation);\n- [mpd](https://musicpd.org) client mode support (version 2.0.0+);\n- Tags editor.\n\n## Installation\n\n#### openSUSE, Debian, Fedora, Ubuntu, RedHat, Mageia\n\n**New users:** install from the omnipackage repositories — [stable releases](https://repositories.omnipackage.org/mpz/stable/install.html) (recommended) or [unstable builds aka \"next\"](https://repositories.omnipackage.org/mpz/next/install.html). These are the primary repositories going forward.\n\n\u003cdetails\u003e\n\u003csummary\u003eAlready using the old Open Build Service repositories?\u003c/summary\u003e\n\nThe previous [Open Build Service repositories](https://software.opensuse.org//download.html?project=home%3Aoleg_antonyan\u0026package=mpz) still exist and existing installations will keep working, but existing users are also encouraged to switch — future packaging effort is focused on omnipackage. The new repositories are signed with different GPG keys, so switching means removing the old repository and adding the new one (the install pages linked above walk through this).\n\nNote: on Debian-based distros (Debian, Ubuntu) the OBS builds were always built against Qt5, even on releases that ship a recent enough Qt6 — making OBS produce working `.deb` packages with Qt6 turned out to be very painful. The omnipackage builds use Qt6 where the distro supports it.\n\n\u003c/details\u003e\n\n#### Arch\n\nUse AUR package: https://aur.archlinux.org/packages/mpz/\n\n```\ngit clone https://aur.archlinux.org/mpz.git\ncd mpz\nmakepkg -si\n```\n\nFor Qt5 version use this package: https://aur.archlinux.org/packages/mpz-qt5\n\n#### Windows\n\nGrab installer or portable binary from releases page: https://github.com/olegantonyan/mpz/releases/.\n\n#### macOS (experimental)\n\nGrab the `.dmg` from the releases page: https://github.com/olegantonyan/mpz/releases/. Universal binary, runs on Apple Silicon and Intel Macs (macOS 11 Big Sur or later).\n\nThe build is not signed with an Apple Developer ID, so macOS Gatekeeper blocks it on first launch. After dragging `mpz music player.app` to `/Applications`, use either method below.\n\n**Terminal:** remove the quarantine flag, then open the app normally:\n\n```\nxattr -dr com.apple.quarantine \"/Applications/mpz music player.app\"\n```\n\n**System Settings:** try to open `mpz music player.app` once and dismiss the warning, then go to *System Settings → Privacy \u0026 Security*. Near the bottom you'll see a message that mpz was blocked — click *Open Anyway* and confirm.\n\nThe app will then launch normally.\n\n#### From sources\n\nDependencies: gcc, make, cmake, qt development headers (libqt5-qtbase-devel, libqt5-qtmultimedia-devel, libqt5-qtx11extras-devel for Qt5 and qt6-base-common-devel, qt6-multimedia-devel, qt6-widgets-devel, qt6-concurrent-devel for Qt6 on openSUSE).\nPackages' names may differ in different distros.\n\n```\ncmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_BUILD_TYPE=Release\ncmake --build build --parallel\n\n# now you can use build/mpz binary directly\n# optionally, install to /usr/local:\nsudo cmake --install build\n```\n\nTo build Qt5 version add `-DUSE_QT5=ON` to cmake cli.\n\nYou can also link against shared libraries Taglib, yaml-cpp, or libmpdclient installed on your OS instead of using vendored statically compiled versions. To do this add `-DUSE_SYSTEM_TAGLIB=ON -DUSE_SYSTEM_YAMLCPP=ON -DUSE_SYSTEM_LIBMPDCLIENT=ON` to cmake cli.\n\n## Configuration\n\nStarting from version 2.0.8 there is settings dialog where all these options can be changed via GUI.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual yaml configuration\u003c/summary\u003e\n\nThe default config location on Linux is `~/.config/mpz`, on Windows - `C:/Users/$USERNAME/AppData/Local/mpz/mpz`. There are 2 files:\n- `local.yml` - for the settings specific to this computer, like windows' sizes, playlists, etc;\n- `global.yml` - for portable settings that make sense to share between computers.\n\nThe available config options are:\n\n- `inhibit_sleep_while_playing` in `global.yml` - when `true` player will prevent your OS from automatic sleep while playing (on Linux requires `systemd-inhibit`);\n- `stream_buffer_size` in `global.yml` - minimal stream buffer size in bytes. The default is 128KB;\n- `single_instance` in `global.yml` - when `true` the player will reuse 1 instance, launching another instance with files as command line arguments will send these files to running instance as a new playlist;\n- `single_instance_ipc_port` in `global.yml` - single instance functionality uses TCP socket, this option allows you to specify a port;\n- `playback_log_size` in `global.yml` - max size of playback log, default is 100;\n- `columns_config` in `global.yml` - configure columns in playlist section, more on this below;\n- `playlist_row_height` in `global.yml` - sets playlist's row height in pixels, by default it comes from your desktop theme, but in KDE Plasma 5.27 this height was increased for no apparent reason, can be useful in other DEs;\n- `stop_when_track_removed` in `global.yml` - when `true` removing the currently playing track (or the playlist that contains it) stops playback and clears the playlist view;\n\nIf you messed up any of the config options you can remove it completely (or even remove the whole file) and it will reset to default.\n\n#### Columns config\n\nYou can change the default columns in the playlist view via `columns_config` option in `global.yml` file. The defaults are:\n\n```\ncolumns_config:\n  - align: left\n    field: artist\n    stretch: false\n    width_percent: 28\n  - align: left\n    field: album\n    stretch: false\n    width_percent: 28\n  - align: left\n    field: title\n    stretch: false\n    width_percent: 28\n  - align: right\n    field: year\n    stretch: false\n    width_percent: 5\n  - align: right\n    field: length\n    stretch: true\n    width_percent: 0\n```\n\nAvailable fields: artist, album, title, year, length, path, url, sample_rate, bitrate, channels, track_number, format, filename.\n\nAvailable alignments: left, right.\n\nThe sum of `width_percent` of all columns must add up to 100 or below. Sometimes it has to be below 100 to get rid of horizontal scroll; this may happen due to padding and a few extra pixels in your desktop theme.\n\n`stretch` will stretch the column to fit the window width to the right. It's advised to have the last column stretched and the sum of all `width_percent` below 100, but you can experiment with it and see how it looks on your desktop.\n\n#### Lyrics\n\nThe track info dialog (right-click a track → \"Track info\") shows lyrics next to the metadata. Three providers are available, tried in order until one returns lyrics:\n\n1. `embedded` - lyrics stored in tags (ID3v2 USLT, Vorbis Comment LYRICS, MP4 ©lyr, APE LYRICS);\n2. `sidecar` - a `\u003cfilename\u003e.lrc` or `\u003cfilename\u003e.txt` file next to the audio file. LRC timestamps are stripped for plain-text rendering;\n3. `lrclib` - online lookup via [LRCLIB](https://lrclib.net) (open, no API key required).\n\nThe default order is `[embedded, sidecar, lrclib]`. To override (for example, to disable online lookup, or change the order), add a `lyrics:` block to `global.yml`:\n\n```\nlyrics:\n  providers: [embedded, sidecar]\n```\n\n#### Block certain MPRIS senders\n\nYou can ignore MPRIS commands from certain senders, for example, in `global.yml` file:\n```\nmpris_blacklist: [\"wireplumber\"]\n```\n\nThis will ignore commands issued by Wireplumber. Starting with version around 0.5 it has a feature that cannot be disabled - whenever the audio device disconnects it issues an MPRIS Pause command. Until they make it configurable, blocking wireplumber is a viable workaround if you also find this feature annoying.\n\n\u003c/details\u003e\n\n## Limitations\n\n- Uses external codecs installed on your OS (through QtMultimedia, using ffmpeg or GStreamer backend on Linux);\n- Global hotkeys don't work in Wayland.\n\nStarting at Qt 6.4, QtMultimedia supports ffmpeg backend on Linux. You can enable it via environment variable QT_MEDIA_BACKEND: `QT_MEDIA_BACKEND=ffmpeg mpz`.\n\nNOTE: currently on openSUSE Tumbleweed (~ year 2024) they seem to be using ffmpeg by default and this may cause issues. You can switch to gstreamer via the same environment variable `QT_MEDIA_BACKEND=gstreamer mpz`.\n\n### mpd impedance mismatch\nWhen used as an [mpd](https://musicpd.org) client, there is a fundamental difference that can lead to some weird behavior. By design mpz does not have an explicit playback queue - the playlist itself is the queue. In mpd, there's an explicit playback queue and playlists are merely lists of tracks that can be loaded into the queue to play.\n\nKnown issues:\n- when another client modifies the playback queue, mpz cannot pick up these changes;\n- upon start, if mpd is already playing a song, mpz can recognize it only if this song is from the last selected playlist, i.e. the one loaded at startup;\n- \"playback follows cursor\" cannot follow into a different playlist;\n\n## [Changelog](https://github.com/olegantonyan/mpz/blob/master/CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folegantonyan%2Fmpz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folegantonyan%2Fmpz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folegantonyan%2Fmpz/lists"}