Crystal MPD

A desktop MPD client written in Crystal using GTK4 bindings.

Screenshots

Features

• Playback controls: play/pause, previous, next
• Shuffle and repeat toggle buttons
• Seek slider with elapsed / total time display
• Window title updates to reflect the current track
• Settings window for MPD host / port configuration

Requirements

• Crystal >= 1.19.1
• GTK4 and GObject Introspection libraries
  • Arch: pacman -S gtk4 gobject-introspection
  • Ubuntu: apt-get install libgtk-4-1 libgtk-4-dev libgirepository1.0-dev
• A running MPD server

Installation

git clone https://github.com/mamantoha/mpd-gtk4
cd mpd-gtk4
shards install
./bin/gi-crystal        # generate GTK4 bindings (required once)
shards build --release
./bin/mpd-gtk4

Dependencies

Shard	Purpose
hugopl/gtk4.cr	GTK4 bindings via GObject Introspection
mamantoha/crystal_mpd	MPD protocol client

Platform support

Tested on Linux (GTK4). macOS and Windows are untested.

Architecture notes

• Dual MPD clients: a regular MPD::Client for commands and a second client with with_callbacks: true running in a background Thread for push events (song change, state, elapsed, random, repeat)
• UI thread safety: all UI mutations from the callback thread go through GLib.idle_add { ...; false }
• Sync guard: a @syncing flag prevents toggled_signal on Gtk::ToggleButton from dispatching MPD commands during programmatic state sync (e.g. when external random/repeat changes arrive via callbacks)

License

MIT