feat: support media controller on mac (#172)

* feat: support media controller on mac

* fix(notifications): publish current playback state when media notifier attaches

* fix(darwin): lock startup to the Cocoa main thread

* refactor: cleanup and simplify

* missed cleanup

Author: gjermundgaraba

README.md

@@ -122,7 +122,7 @@ Or without Make: `go build -o cliamp .`
 - [SSH Streaming](docs/ssh-streaming.md)
 - [Remote Control (IPC)](docs/remote-control.md)
 - [Audio Quality](docs/audio-quality.md)
-- [MPRIS](docs/mpris.md)
+- [Media Controls](docs/mediactl.md)
 - [Lua Plugins](docs/plugins.md)
   - [Community Plugins](docs/community-plugins.md)
   - [Soap Bubbles Visualizer](https://github.com/bjarneo/cliamp-plugin-soap-bubbles)

docs/mediactl.md

@@ -0,0 +1,118 @@
+# Media Controls
+
+Cliamp integrates with the operating system's media control infrastructure so that desktop environments, hardware media keys, and command line tools can control playback, read track metadata, and adjust volume without touching the TUI.
+
+## Platform Support
+
+| Platform | Backend | Requirements |
+|---|---|---|
+| Linux | [MPRIS2](https://specifications.freedesktop.org/mpris-spec/latest/) over D-Bus | A running D-Bus session bus (provided by most desktop environments and Wayland compositors) |
+| macOS | MPNowPlayingInfoCenter / MPRemoteCommandCenter | None (frameworks are built-in) |
+| Other | No-op stub | — |
+
+## Linux (MPRIS2)
+
+### Bus Name
+
+Cliamp registers itself as:
+
+```
+org.mpris.MediaPlayer2.cliamp
+```
+
+Only one instance can hold this name at a time. If a second Cliamp process tries to start, the MPRIS registration will fail silently and that instance will run without D-Bus integration.
+
+### Playback Control
+
+All standard transport commands are supported through the `org.mpris.MediaPlayer2.Player` interface:
+
+| playerctl command | Effect |
+|---|---|
+| `playerctl play-pause` | Toggle play / pause |
+| `playerctl play` | Resume playback |
+| `playerctl pause` | Pause playback |
+| `playerctl stop` | Stop playback |
+| `playerctl next` | Skip to the next track |
+| `playerctl previous` | Go to the previous track (or restart if more than 3 seconds in) |
+
+### Seeking
+
+Relative and absolute seeking are both supported:
+
+```sh
+playerctl position 30          # seek to 30 seconds
+playerctl position 5+          # seek forward 5 seconds
+playerctl position 5-          # seek backward 5 seconds
+```
+
+Desktop widgets that display a progress bar will receive `Seeked` signals and stay in sync.
+
+### Volume
+
+Volume is exposed as a linear value between 0.0 and 1.0. Internally Cliamp uses a decibel scale (from -30 dB to +6 dB), and the conversion happens automatically.
+
+```sh
+playerctl volume               # print current volume (0.0 to 1.0)
+playerctl volume 0.5           # set volume to 50%
+```
+
+Setting volume through `playerctl` updates the player immediately. Changing volume with the `+` and `-` keys in the TUI is reflected back to D-Bus clients on the next tick.
+
+### Metadata
+
+Track metadata is published under the standard MPRIS keys:
+
+| Key | Description |
+|---|---|
+| `mpris:trackid` | D-Bus object path identifying the current track |
+| `xesam:title` | Track title |
+| `xesam:artist` | Artist name (as a list with one entry) |
+| `xesam:album` | Album name, when available |
+| `xesam:url` | File path or stream URL |
+| `mpris:length` | Duration in microseconds |
+
+Query metadata with:
+
+```sh
+playerctl metadata              # all keys
+playerctl metadata artist       # just the artist
+playerctl metadata title        # just the title
+```
+
+For live radio streams that provide ICY metadata, the artist and title fields update dynamically as the station reports new track information.
+
+### Status
+
+```sh
+playerctl status                # prints Playing, Paused, or Stopped
+```
+
+## macOS
+
+On macOS, Cliamp publishes now-playing information to the system's MPNowPlayingInfoCenter. This enables:
+
+- Control Centre and Lock Screen media controls
+- Touch Bar playback buttons
+- Hardware media keys (play/pause, next, previous)
+- Bluetooth headphone buttons
+
+The macOS implementation requires the media-control runtime to pin the main goroutine to thread 0 (via `runtime.LockOSThread`) so that the Cocoa run loop can pump events. Bubbletea runs on a background goroutine instead.
+
+## Architecture
+
+The app-owned playback command and notifier boundary lives in `internal/playback`. The `mediactl` package translates platform APIs to and from that boundary and owns the platform-specific interactive runtime helper.
+
+Platform-specific `Service` implementations:
+
+- `internal/playback/*` — app-level playback commands and outbound notifier state.
+- `mediactl/service_linux.go` — connects to the session bus, claims the MPRIS bus name, translates D-Bus calls into playback commands, and publishes outbound state through MPRIS properties.
+- `mediactl/service_darwin.go` — initialises NSApplication as an accessory process, registers MPRemoteCommandCenter handlers, translates them into playback commands, and publishes now-playing state on the main-thread run loop.
+- `mediactl/service_stub.go` — no-op implementation for unsupported platforms.
+
+The model publishes playback state through the playback notifier whenever state changes. On Linux, `mediactl` uses `SetMust` rather than `Set` to bypass the property library's writable checks and callback triggers, which are intended for external D-Bus writes. For writable properties like Volume, the D-Bus callback is translated into an app playback command and dispatched back into the Bubbletea event loop.
+
+## Limitations
+
+Shuffle and loop status are not exposed. The `z` and `r` keys in the TUI control shuffle and repeat locally, but these states are not visible to or controllable from external tools.
+
+The `HasTrackList` property is set to false on Linux. Cliamp does not implement the optional `org.mpris.MediaPlayer2.TrackList` interface.

docs/mpris.md

@@ -0,0 +1,49 @@
+package playback
+
+import "time"
+
+type (
+	PlayPauseMsg   struct{}
+	PlayMsg        struct{}
+	PauseMsg       struct{}
+	NextMsg        struct{}
+	PrevMsg        struct{}
+	StopMsg        struct{}
+	QuitMsg        struct{}
+	SeekMsg        struct{ Offset time.Duration }
+	SetPositionMsg struct {
+		Position time.Duration
+	}
+	SetVolumeMsg struct{ VolumeDB float64 }
+)
+
+type Status string
+
+const (
+	StatusStopped Status = "Stopped"
+	StatusPlaying Status = "Playing"
+	StatusPaused  Status = "Paused"
+)
+
+type Track struct {
+	Title       string
+	Artist      string
+	Album       string
+	Genre       string
+	TrackNumber int
+	URL         string
+	Duration    time.Duration
+}
+
+type State struct {
+	Status   Status
+	Track    Track
+	VolumeDB float64
+	Position time.Duration
+	Seekable bool
+}
+
+type Notifier interface {
+	Update(State)
+	Seeked(time.Duration)
+}

internal/playback/playback.go

@@ -2,6 +2,8 @@
 // The protocol is newline-delimited JSON over a Unix domain socket.
 package ipc
 
+import "time"
+
 // Compile-time interface check.
 var _ Dispatcher = DispatcherFunc(nil)
 
@@ -50,7 +52,7 @@ type DispatcherFunc func(msg interface{})
 func (f DispatcherFunc) Send(msg interface{}) { f(msg) }
 
 // IPC-specific messages sent to the TUI via prog.Send().
-// For shared types (NextMsg, PrevMsg, StopMsg, ToggleMsg), see internal/control.
+// For shared types (NextMsg, PrevMsg, StopMsg, PlayPauseMsg), see internal/playback.
 
 // PlayMsg requests playback to start (unpause only, not toggle).
 type PlayMsg struct{}
@@ -61,8 +63,8 @@ type PauseMsg struct{}
 // VolumeMsg requests a relative volume change in dB.
 type VolumeMsg struct{ DB float64 }
 
-// SeekMsg requests a relative seek in seconds.
-type SeekMsg struct{ Secs float64 }
+// SeekMsg requests a relative seek.
+type SeekMsg struct{ Offset time.Duration }
 
 // LoadMsg requests loading a playlist by name.
 // Reply receives the result so the client can report errors.

ipc/protocol.go

@@ -13,7 +13,7 @@ import (
 	"syscall"
 	"time"
 
-	"cliamp/internal/control"
+	"cliamp/internal/playback"
 )
 
 // Dispatcher is how the server sends commands to the TUI.
@@ -144,27 +144,27 @@ func (s *Server) dispatch(req Request) Response {
 		return Response{OK: true}
 
 	case "toggle":
-		s.disp.Send(control.ToggleMsg{})
+		s.disp.Send(playback.PlayPauseMsg{})
 		return Response{OK: true}
 
 	case "stop":
-		s.disp.Send(control.StopMsg{})
+		s.disp.Send(playback.StopMsg{})
 		return Response{OK: true}
 
 	case "next":
-		s.disp.Send(control.NextMsg{})
+		s.disp.Send(playback.NextMsg{})
 		return Response{OK: true}
 
 	case "prev":
-		s.disp.Send(control.PrevMsg{})
+		s.disp.Send(playback.PrevMsg{})
 		return Response{OK: true}
 
 	case "volume":
 		s.disp.Send(VolumeMsg{DB: req.Value})
 		return Response{OK: true}
 
 	case "seek":
-		s.disp.Send(SeekMsg{Secs: req.Value})
+		s.disp.Send(SeekMsg{Offset: time.Duration(req.Value * float64(time.Second))})
 		return Response{OK: true}
 
 	case "load":

ipc/server.go

@@ -0,0 +1,29 @@
+package ipc
+
+import (
+	"testing"
+	"time"
+)
+
+func TestDispatchSeekSendsIPCSeekMsgWithDuration(t *testing.T) {
+	var sent any
+	s := &Server{
+		disp: DispatcherFunc(func(msg interface{}) {
+			sent = msg
+		}),
+	}
+
+	resp := s.dispatch(Request{Cmd: "seek", Value: 12.25})
+	if !resp.OK {
+		t.Fatalf("dispatch() response = %#v, want OK", resp)
+	}
+
+	got, ok := sent.(SeekMsg)
+	if !ok {
+		t.Fatalf("dispatch() sent %T, want ipc.SeekMsg", sent)
+	}
+	want := SeekMsg{Offset: 12250 * time.Millisecond}
+	if got != want {
+		t.Fatalf("dispatch() sent %#v, want %#v", got, want)
+	}
+}