PsyMP3 2-CURRENT

A simplistic audio media player with a flashy Fourier transform.

Table of Contents

1. Overview
2. System Requirements
3. Building
4. Usage
5. Integrations
6. Testing
7. Notes

Overview

PsyMP3 2.x is a radical departure from the code of the 1.x series. Whereas 1.x was written in FreeBASIC, 2.x is written in C++17, and is portable!

Highlights:

• Real-time FFT spectrum visualizer with adjustable intensity, decay, and draw modes
• A faithful Windows 3.1-style in-app UI: menu bar, movable windows (Playlist Manager, Equalizer, Media Information, About), buttons, scrollbars, and dialogs — all software-rendered
• Wide format support through a modular demuxer/codec architecture, with several codecs vendored so they work with no external libraries
• Synced lyrics display (.lrc files)
• Last.fm scrobbling (Web Services API 2.0), MPRIS desktop control, and Discord Rich Presence
• Session persistence: with Persist Playlist enabled, PsyMP3 reopens your playlist at the track you were playing

Note: The "2-CURRENT" version tag represents the active development branch. End users should be aware that this is pre-release software.

Contact: segin2005@gmail.com

System Requirements

Windows

• Windows 10 or later
• Official builds are cross-compiled with llvm-mingw (x86_64, i686, and ARM64), statically linked against SDL3; building under MSYS2 is also possible

Linux/BSD

Core dependencies (always required):

• SDL3 3.0 or later (sdl3)
• FreeType2 (freetype2)
• HarfBuzz (harfbuzz) — shapes Arabic and the Indic scripts
• taglib 1.6 or later (taglib; taglib 2.x works too)
• OpenSSL 1.0 or later (openssl)
• libcurl 7.20.0 or later (libcurl)

Optional codec dependencies (auto-detected; each can be disabled at build time):

• libogg (ogg) — required for Vorbis, Opus, and Ogg FLAC (container parsing)
• libopus (opus) — Opus
• FDK-AAC (fdk-aac) — the whole AAC family: AAC-LC, HE-AACv1, HE-AACv2 and xHE-AAC / MPEG-D USAC. Note that it is not packaged everywhere: Debian keeps it in non-free, openSUSE in Packman, and Ubuntu in universe. Fedora ships only the stripped fdk-aac-free, against which PsyMP3 builds without AAC rather than decoding HE-AAC at half its bandwidth.
• speex 1.2 or later (speex) — Speex

Bundled codecs (vendored, no external dependency):

• FLAC — native decoder (no libFLAC needed)
• Vorbis — stb_vorbis (third_party/stb; needs only libogg for the container)
• MP3 — minimp3 (third_party/minimp3)
• MP2 — kjmp2 (third_party/kjmp2)
• ALAC — Apple's reference decoder (third_party/alac)
• MLP / Dolby TrueHD — bundled decoder (third_party/mlp), derived from truehdd © 2025 Rainbaby (Apache-2.0)
• G.711 µ-law/A-law, and raw PCM formats

Optional integration dependencies:

• D-Bus 1.0 or later (dbus-1) — MPRIS desktop media control
• A GUI toolkit for the native file-open/save dialog. Configure probes, in order, and uses the first one found: Qt 6 (Qt6Widgets) → Qt 5 (Qt5Widgets) → Qt 4 (QtGui) → Qt 3 (no pkg-config; opt in with --with-qt3-dir=PREFIX) → GTK 4 (gtk4) → GTK+ 3 (gtk+-3.0) → GTK+ 2 (gtk+-2.0). Without any of these, the file dialogs are unavailable but PsyMP3 still builds and plays files given on the command line.

Build Requirements

• C++17 compliant compiler (GCC 9+, Clang 10+, MSVC 2019+)
• Autotools: autoconf, automake, libtool, and autoconf-archive (required — it supplies AX_CXX_COMPILE_STDCXX_17; without it autoreconf silently drops the C++17 check and the build fails with -std=c++17 errors)
• pkg-config
• Optional, for make check: RapidCheck (property-based tests, enabled with --enable-rapidcheck)

Building

From a release tarball:

./configure
make -j$(nproc)

From git (requires autoconf-archive):

./generate-configure.sh
./configure
make -j$(nproc)

Build Options:

• --enable-flac / --enable-vorbis / --enable-opus / --enable-aac / --enable-speex / --enable-g722 / --enable-g711 — per-codec toggles (default: yes)
• --enable-mpris — MPRIS desktop integration over D-Bus (default: auto)
• --enable-final — unity build: all sources in one translation unit (much faster full rebuilds; used for release builds)
• --enable-static-binary — fully static, self-contained executable (used for the Windows release builds)
• --enable-test-harness — build the test harness (default: yes)
• --enable-asan / --enable-ubsan / --enable-tsan — sanitizer builds (debug only)

Distribution packages

package/ holds native packaging, built for every push by the Linux packages workflow:

Format	Targets
.deb	Debian 13 (trixie), Ubuntu 26.04 LTS
.rpm	Fedora, openSUSE Tumbleweed

./package/dpkg/build-deb.sh      # -> package/dpkg/out/*.deb
./package/rpm/build-rpm.sh       # -> package/rpm/out/*.rpm

Both build from a clean export of HEAD, so commit before packaging. See package/README.md for the dependency-installation one-liners and how the version label is mapped to a legal package version.

Usage

Pass the paths of audio files or playlists (.m3u/.m3u8) as program arguments; they are played in order. Supported formats include MP3, MP2, Ogg Vorbis, Opus, FLAC (native and Ogg), WAV/RIFF, AAC/M4A, xHE-AAC, ALAC, Speex, MLP/Dolby TrueHD (.thd/.truehd/.mlp), G.711 (µ-law/A-law), G.722, and raw PCM.

PsyMP3 has a full mouse-driven UI — a menu bar (File, Playback, Settings, Help — Alt+F/P/S mnemonics work) plus movable in-app windows like the Playlist Manager, Equalizer, and Media Information — and everything is also reachable from the keyboard.

Keyboard Controls

Key	Action
ESC, Q	Quit PsyMP3
Space	Pause (or resume) playback
R	Restart the current track from the beginning
N / P	Next / previous track
Up / Down	Volume up / down
E	Cycle loop mode (Shift+E opens the Equalizer)
M	Playlist Manager
F	Cycle FFT draw mode
G	Toggle 2× zoom
0–4	Spectrum intensity
Z / X / C	Spectrum decay (fast/normal/slow)
Ctrl+O	Open tracks (replaces playlist)
I / L	Queue tracks next / play a track now
Ctrl+S	Save playlist
Ctrl+F4	Close the focused in-app window

Command-line Options

• --version - Print version and licensing information
• --debug <channels> - Enable debug logging (comma-separated channels, or all)
• --logfile <file> - Write debug logs to the specified file

Integrations

Last.fm Scrobbling

PsyMP3 scrobbles through the Last.fm Web Services API 2.0 with its own registered API key. The easiest way to set it up is in the app: Settings → Last.fm Credentials... — enter your username and password, press Test to verify, and OK to save. The password is only needed once: after the first successful authentication PsyMP3 stores a permanent session key and wipes the password.

Configuration lives in:

• Linux/Unix: ~/.config/psymp3/lastfm.conf
• Windows: %APPDATA%\PsyMP3\lastfm.conf

and can also be created by hand:

# Last.fm configuration
username=your_lastfm_username
password=your_lastfm_password

Scrobbles and now-playing updates include MusicBrainz recording IDs when your files are tagged with them (e.g. by MusicBrainz Picard), and failed submissions are cached and retried across sessions.

MPRIS Desktop Integration

PsyMP3 implements MPRIS (Media Player Remote Interfacing Specification) for desktop media-control integration — play/pause/seek from your desktop environment, media keys, and now-playing applets (Linux/BSD only).

Discord Rich Presence

With Discord running on the same machine, PsyMP3 shows what you're listening to as a Discord activity: artist in the header, track and album on the card, a live progress bar, and album art from the Cover Art Archive (via your files' MusicBrainz tags, or a live MusicBrainz lookup for untagged files). Toggle it under Settings → Discord Presence. No Discord SDK or account linking is required.

Testing

To run the full test suite:

make check

For detailed testing information, see TESTING.md.

Notes

Unicode Support: Unicode ID3 tags are supported. PsyMP3 renders UI text through the built-in FreeType path, with HarfBuzz shaping each run and a vendored SheenBidi resolving direction, so complex scripts are laid out properly rather than drawn one codepoint at a time, left to right.

The bundled vera.ttf (DejaVu Sans) covers rather more than Latin, Greek and Cyrillic. It also carries Armenian, Georgian, Lao, Hebrew, N'Ko and the Arabic script — Arabic itself along with Persian, Sindhi, Sorani Kurdish and Uyghur, and most of Urdu and Pashto. Arabic letters join properly with the bundled font: shaping selects the contextual forms, and the renderer composites overlapping glyph boxes so the stroke that joins one letter to the next survives instead of being overwritten by its neighbour. Hebrew and N'Ko read right to left.

Scripts that DejaVu Sans does not cover draw as empty boxes — Chinese, Japanese and Korean are the most common example, along with many Indic and Southeast Asian scripts, among others — until you give PsyMP3 a second font.

Adding languages with extra.ttf

extra.ttf is an optional second font. PsyMP3 uses it for any character vera.ttf cannot draw, so a single file can add whichever languages you need. Any TrueType or OpenType font works; a family with broad coverage, such as Noto, covers most scripts at once. Without an extra.ttf, nothing changes.

Where PsyMP3 looks for it:

Platform	Location
Windows	next to psymp3.exe; otherwise extra.ttf or res\extra.ttf in the working directory
Linux/BSD	the installed data directory, $(prefix)/share/psymp3/data/extra.ttf (/usr/local/share/psymp3/data for a default install); otherwise res/extra.ttf in the working directory, for running from the source tree

How it works alongside vera.ttf:

• It adds to the bundled font rather than replacing it. On Windows that includes the copy of vera.ttf built into the executable, so no rebuild is needed.
• Anything vera.ttf can draw keeps vera.ttf, so adding a font for one language does not restyle the rest of the interface.
• One exception: scripts that are shaped or reordered. For right-to-left scripts such as Arabic and Hebrew, and scripts that combine or rearrange characters, such as the Indic ones, extra.ttf is used wherever it covers the script, even for characters vera.ttf also has. A font added for one language can therefore change how those scripts look, if it happens to cover them too. They render correctly with DejaVu Sans alone, so this changes which typeface you get, not whether the text is readable.

Replacing vera.ttf itself still works too. On Windows, a vera.ttf next to the executable or in the working directory overrides the built-in copy.