ipc

package
v1.63.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package ipc provides Unix socket IPC for remote playback control of cliamp. The protocol is newline-delimited JSON over a Unix domain socket.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultSocketPath 

func DefaultSocketPath() string

DefaultSocketPath returns the default IPC socket path (~/.config/cliamp/cliamp.sock).

func StreamBands 

func StreamBands(ctx context.Context, sockPath string, interval time.Duration, out io.Writer) error

StreamBands holds one IPC connection open and writes one NDJSON line per tick containing the current visualizer bands and mode. It exits cleanly when ctx is cancelled or the server closes the socket.

Types

type AlbumInfo added in v1.61.0 

type AlbumInfo struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Artist     string `json:"artist,omitempty"`
	ArtistID   string `json:"artist_id,omitempty"`
	Year       int    `json:"year,omitempty"`
	TrackCount int    `json:"track_count,omitempty"`
	Genre      string `json:"genre,omitempty"`
}

type ArtistInfo added in v1.61.0 

type ArtistInfo struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	AlbumCount int    `json:"album_count,omitempty"`
}

type BandsRequestMsg 

type BandsRequestMsg struct {
	Reply chan Response
}

BandsRequestMsg asks the TUI for the current visualizer band values (smoothed) and the active visualizer mode name. Lightweight compared to StatusRequestMsg — intended for high-rate polling from external widgets.

type DeviceInfo added in v1.61.0 

type DeviceInfo struct {
	Name   string `json:"name"`
	Active bool   `json:"active"`
}

type DeviceMsg 

type DeviceMsg struct {
	Name  string
	Reply chan Response
}

DeviceMsg requests switching the audio output device or listing devices. If Name is "list", returns available devices. Otherwise switches to named device.

type Dispatcher 

type Dispatcher interface {
	Send(msg any)
}

Dispatcher is how the server sends commands to the TUI. In main.go, this is wired to prog.Send().

type DispatcherFunc 

type DispatcherFunc func(msg any)

DispatcherFunc adapts a plain function to the Dispatcher interface.

func (DispatcherFunc) Send 

func (f DispatcherFunc) Send(msg any)

Send implements Dispatcher.

type EQMsg 

type EQMsg struct {
	Name  string
	Band  int
	Value float64
	Reply chan Response
}

EQMsg requests setting EQ preset by name or a single band's gain. If Band >= 0, sets that band to Value dB. Otherwise applies preset Name.

type HistoryInfo added in v1.61.0 

type HistoryInfo struct {
	Track    TrackInfo `json:"track"`
	PlayedAt string    `json:"played_at"`
}

type HistoryRequestMsg added in v1.61.0 

type HistoryRequestMsg struct {
	Op    string
	Limit int
	Reply chan Response
}

type LibraryRequestMsg added in v1.61.0 

type LibraryRequestMsg struct {
	Op       string
	Provider string
	Playlist string
	Query    string
	Artist   string
	Album    string
	Sort     string
	Offset   int
	Limit    int
	Index    int
	NewName  string
	Track    *TrackInfo
	Reply    chan Response
}

type LoadMsg 

type LoadMsg struct {
	Playlist string
	Reply    chan Response
}

LoadMsg requests loading a playlist by name. Reply receives the result so the client can report errors.

type LyricLine added in v1.61.0 

type LyricLine struct {
	Start float64 `json:"start"`
	Text  string  `json:"text"`
}

type LyricsRequestMsg added in v1.61.0 

type LyricsRequestMsg struct {
	Reply chan Response
}

type MonoMsg 

type MonoMsg struct {
	Name  string
	Reply chan Response
}

MonoMsg requests toggling or setting mono mode. If Name is "on"/"off", it sets the mode explicitly; "toggle" toggles.

type PauseMsg 

type PauseMsg struct{}

PauseMsg requests playback to pause (pause only, not toggle).

type PlayMsg 

type PlayMsg struct{}

PlayMsg requests playback to start (unpause only, not toggle).

type PlaylistInfo added in v1.61.0 

type PlaylistInfo struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Provider     string `json:"provider"`
	Section      string `json:"section,omitempty"`
	TrackCount   int    `json:"track_count,omitempty"`
	DurationSecs int    `json:"duration_secs,omitempty"`
	Favoritable  bool   `json:"favoritable,omitempty"`
	Favorite     bool   `json:"favorite,omitempty"`
}

type PluginDispatcher 

type PluginDispatcher interface {
	EmitCommand(plugin, command string, args []string) (string, error)
	CommandList() []string
}

PluginDispatcher is the hook the IPC server calls to forward plugin.call and plugin.commands requests to the Lua plugin manager. Optional — if nil, those subcommands return an error.

type ProviderInfo added in v1.61.0 

type ProviderInfo struct {
	Key           string `json:"key"`
	Name          string `json:"name"`
	Searchable    bool   `json:"searchable"`
	BrowseArtists bool   `json:"browse_artists,omitempty"`
	BrowseAlbums  bool   `json:"browse_albums,omitempty"`
	Catalog       bool   `json:"catalog,omitempty"`
}

type QueueMsg 

type QueueMsg struct{ Path string }

QueueMsg requests queuing a file path for playback.

type QueueRequestMsg added in v1.61.0 

type QueueRequestMsg struct {
	Op    string
	Index int
	To    int
	Track *TrackInfo
	Reply chan Response
}

type RepeatMsg 

type RepeatMsg struct {
	Name  string
	Reply chan Response
}

RepeatMsg requests setting or cycling the repeat mode. Name is "off", "all", "one", or "cycle".

type Request 

type Request struct {
	Cmd      string     `json:"cmd"`
	Value    float64    `json:"value,omitempty"`
	Playlist string     `json:"playlist,omitempty"`
	Path     string     `json:"path,omitempty"`
	Name     string     `json:"name,omitempty"`
	Band     int        `json:"band,omitempty"`
	Sub      string     `json:"sub,omitempty"`
	Args     []string   `json:"args,omitempty"`
	Provider string     `json:"provider,omitempty"`
	Query    string     `json:"query,omitempty"`
	Artist   string     `json:"artist,omitempty"`
	Album    string     `json:"album,omitempty"`
	Sort     string     `json:"sort,omitempty"`
	Offset   int        `json:"offset,omitempty"`
	Index    int        `json:"index,omitempty"`
	To       int        `json:"to,omitempty"`
	Limit    int        `json:"limit,omitempty"`
	NewName  string     `json:"new_name,omitempty"`
	Track    *TrackInfo `json:"track,omitempty"`
}

Request is the JSON command sent by the client.

type Response 

type Response struct {
	OK         bool           `json:"ok"`
	Error      string         `json:"error,omitempty"`
	State      string         `json:"state,omitempty"`
	Track      *TrackInfo     `json:"track,omitempty"`
	Position   float64        `json:"position,omitempty"`
	Duration   float64        `json:"duration,omitempty"`
	Volume     float64        `json:"volume,omitempty"`
	Playlist   string         `json:"playlist,omitempty"`
	Index      int            `json:"index,omitempty"`
	Total      int            `json:"total,omitempty"`
	Visualizer string         `json:"visualizer,omitempty"`
	Shuffle    *bool          `json:"shuffle,omitempty"`
	Repeat     string         `json:"repeat,omitempty"`
	Mono       *bool          `json:"mono,omitempty"`
	Speed      float64        `json:"speed,omitempty"`
	EQPreset   string         `json:"eq_preset,omitempty"`
	Device     string         `json:"device,omitempty"`
	Output     string         `json:"output,omitempty"`
	Items      []string       `json:"items,omitempty"`
	Theme      *ThemeInfo     `json:"theme,omitempty"`
	Bands      []float64      `json:"bands,omitempty"`
	EQBands    []float64      `json:"eq_bands,omitempty"`
	Tracks     []TrackInfo    `json:"tracks,omitempty"`
	Playlists  []PlaylistInfo `json:"playlists,omitempty"`
	Providers  []ProviderInfo `json:"providers,omitempty"`
	Artists    []ArtistInfo   `json:"artists,omitempty"`
	Albums     []AlbumInfo    `json:"albums,omitempty"`
	Sorts      []SortInfo     `json:"sorts,omitempty"`
	Lyrics     []LyricLine    `json:"lyrics,omitempty"`
	History    []HistoryInfo  `json:"history,omitempty"`
	Devices    []DeviceInfo   `json:"devices,omitempty"`
}

Response is the JSON response sent by the server.

func Send 

func Send(sockPath string, req Request) (Response, error)

Send connects to the IPC socket, sends a request, and returns the response. The connection is closed after a single request/response exchange.

func SendWithDeadline 

func SendWithDeadline(sockPath string, req Request, deadline time.Duration) (Response, error)

SendWithDeadline is like Send but lets the caller override the exchange deadline. Plugin commands can legitimately run for minutes (downloads), so the generic 5s cap is too short for them.

type SaveRequestMsg added in v1.61.0 

type SaveRequestMsg struct {
	Reply chan Response
}

type SeekMsg 

type SeekMsg struct{ Offset time.Duration }

SeekMsg requests a relative seek.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server listens on a Unix socket and dispatches IPC commands.

func NewServer 

func NewServer(sockPath string, disp Dispatcher) (*Server, error)

NewServer creates and starts the IPC server. It cleans up stale sockets before binding. The socket is created with 0600 permissions (owner only).

func (*Server) Close 

func (s *Server) Close() error

Close shuts down the server, removes socket and PID file.

func (*Server) SetPluginDispatcher 

func (s *Server) SetPluginDispatcher(p PluginDispatcher)

SetPluginDispatcher wires in the Lua plugin manager after the server starts. Plugin dispatch is optional — without it, plugin subcommands return an error.

type ShuffleMsg 

type ShuffleMsg struct {
	Name  string
	Reply chan Response
}

ShuffleMsg requests toggling or setting shuffle mode. If Name is "on"/"off", it sets the mode explicitly; "toggle" toggles.

type SortInfo added in v1.61.0 

type SortInfo struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

type SpeedMsg 

type SpeedMsg struct {
	Speed float64
	Reply chan Response
}

SpeedMsg requests setting the playback speed.

type StatusRequestMsg 

type StatusRequestMsg struct {
	Reply chan Response
}

StatusRequestMsg asks the TUI for current state. The TUI writes the response to Reply and closes the channel.

type ThemeInfo 

type ThemeInfo struct {
	Name     string `json:"name"`
	Accent   string `json:"accent,omitempty"`
	Fg       string `json:"fg,omitempty"`
	BrightFg string `json:"bright_fg,omitempty"`
	Green    string `json:"green,omitempty"`
	Yellow   string `json:"yellow,omitempty"`
	Red      string `json:"red,omitempty"`
}

ThemeInfo carries the active theme name and its resolved hex colors. Empty hex fields mean the default (ANSI fallback) theme is active.

type ThemeMsg 

type ThemeMsg struct {
	Name  string
	Reply chan Response
}

ThemeMsg requests changing the TUI theme by name. Reply receives confirmation or error if theme not found.

type TrackInfo 

type TrackInfo struct {
	Title         string `json:"title,omitempty"`
	Artist        string `json:"artist,omitempty"`
	Album         string `json:"album,omitempty"`
	Genre         string `json:"genre,omitempty"`
	Path          string `json:"path"`
	AlbumArtURL   string `json:"album_art_url,omitempty"`
	Year          int    `json:"year,omitempty"`
	TrackNumber   int    `json:"track_number,omitempty"`
	DurationSecs  int    `json:"duration_secs,omitempty"`
	Index         int    `json:"index,omitempty"`
	QueuePosition int    `json:"queue_position,omitempty"`
	Stream        bool   `json:"stream,omitempty"`
	Realtime      bool   `json:"realtime,omitempty"`
	Bookmark      bool   `json:"bookmark,omitempty"`
	Unplayable    bool   `json:"unplayable,omitempty"`
}

TrackInfo is the track metadata in a status response.

type URLRequestMsg added in v1.61.0 

type URLRequestMsg struct {
	URL   string
	Reply chan Response
}

type VisMsg 

type VisMsg struct {
	Name  string
	Reply chan Response
}

VisMsg requests changing the active visualizer by name. If Name is "next", the visualizer cycles to the next mode. Reply receives confirmation or error if mode not found.

type VolumeMsg 

type VolumeMsg struct{ DB float64 }

VolumeMsg requests a relative volume change in dB.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.