control

Documentation

Overview

Package control exposes the OpenDeezer remote-control API: a small HTTP/JSON server that a controller (another OpenDeezer client, an MCP agent, a phone web remote) can drive, and a matching client that talks to one.

Host a control server

srv := control.NewServer(
    control.Config{
        Addr:  ":7654",      // LAN-accessible
        Token: "s3cr3t",     // bearer-token auth
    },
    func() control.State { return snapshot() },
    func() control.Account { return control.Account{UserID: uid, Name: name} },
    control.Commands{
        PlayPause: player.TogglePause,
        Next:      queue.Next,
        Prev:      queue.Prev,
        Stop:      player.Stop,
        SetVolume: player.SetVolume,
        Seek:      player.SeekMS,
    },
    dzClient, // pass nil to disable browse (/search, /playlists)
)
srv.SetVersion("1.0")
if err := srv.Start(); err != nil { log.Fatal(err) }
defer srv.Close()

Drive a remote server

client := control.NewClient("http://192.168.1.5:7654", "s3cr3t", "")
st, _ := client.Status()
fmt.Println(st.State, st.Track.Title)

Phone web remote

When [Config.WebRemote] is true, GET /remote serves a mobile-friendly SPA. Pair a phone by calling Server.EnablePairing to get a 6-digit code, then entering it in the SPA. Pairing issues a session token stored in localStorage; no cookie is used (CSRF-safe).

Auth modes

• token — bearer token in X-OpenDeezer-Token; set [Config.Token]
• account — controller proves it is the same Deezer account; set [Config.SameAccountOnly] = true
• session — phone web remote; set [Config.WebRemote] = true
• none — open (safe only on localhost)

Index

• type Account
• type Client
  • func NewClient(base, token, accountID string) *Client
  • func (c *Client) Next() (State, error)
  • func (c *Client) PlayPause() (State, error)
  • func (c *Client) PlayPlaylist(id string) (State, error)
  • func (c *Client) PlayTrack(id string) (State, error)
  • func (c *Client) Prev() (State, error)
  • func (c *Client) Restart() (State, error)
  • func (c *Client) SeekMS(ms int64) (State, error)
  • func (c *Client) SetRepeat(mode string) (State, error)
  • func (c *Client) SetShuffle(on bool) (State, error)
  • func (c *Client) SetVolume(v float64) (State, error)
  • func (c *Client) Status() (State, error)
  • func (c *Client) Stop() (State, error)
  • func (c *Client) Whoami() (Whoami, error)
• type Commands
• type Config
• type Server
  • func NewServer(cfg Config, status func() State, account func() Account, cmds Commands, ...) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Close()
  • func (s *Server) DisablePairing()
  • func (s *Server) EnablePairing() string
  • func (s *Server) PairingActive() bool
  • func (s *Server) PairingCode() string
  • func (s *Server) SetClientInfo(client, device string)
  • func (s *Server) SetVersion(v string)
  • func (s *Server) Start() error
• type State
• type Track
• type Whoami

Types

type Account

type Account = internalcontrol.Account

Account is the controlled client's Deezer identity, provided to NewServer via a snapshot callback. UserID is the credential in same-account auth mode.

type Client

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

Client talks to a Server (or any compatible control endpoint) over HTTP. All mutation methods return the post-command playback snapshot. The snapshot may lag the command by one server tick; poll GET /status if you need the settled state.

Client is safe for concurrent use.

func NewClient

func NewClient(base, token, accountID string) *Client

NewClient builds a control client.

• base — server URL, e.g. "http://192.168.1.5:7654"
• token — X-OpenDeezer-Token value; "" to omit
• accountID — X-OpenDeezer-Account value for same-account auth; "" to omit

func (*Client) Next

func (c *Client) Next() (State, error)

Next skips to the next track.

func (*Client) PlayPause

func (c *Client) PlayPause() (State, error)

PlayPause toggles play/pause on the server.

func (*Client) PlayPlaylist

func (c *Client) PlayPlaylist(id string) (State, error)

PlayPlaylist instructs the server to play the playlist with the given id.

func (*Client) PlayTrack

func (c *Client) PlayTrack(id string) (State, error)

PlayTrack instructs the server to play the track with the given Deezer id.

func (*Client) Prev

func (c *Client) Prev() (State, error)

Prev jumps to the previous track.

func (*Client) Restart

func (c *Client) Restart() (State, error)

Restart seeks to position 0 in the current track.

func (*Client) SeekMS

func (c *Client) SeekMS(ms int64) (State, error)

SeekMS seeks to ms milliseconds from the start of the current track.

func (*Client) SetRepeat

func (c *Client) SetRepeat(mode string) (State, error)

SetRepeat sets the repeat mode: "off", "all", or "one".

func (*Client) SetShuffle

func (c *Client) SetShuffle(on bool) (State, error)

SetShuffle enables (true) or disables (false) shuffle.

func (*Client) SetVolume

func (c *Client) SetVolume(v float64) (State, error)

SetVolume sets the volume (0.0 = silent, 1.0 = full).

func (*Client) Status

func (c *Client) Status() (State, error)

Status returns the current playback snapshot.

func (*Client) Stop

func (c *Client) Stop() (State, error)

Stop halts playback.

func (*Client) Whoami

func (c *Client) Whoami() (Whoami, error)

Whoami fetches the server's identity and auth mode. This endpoint is unauthenticated and is safe to call before supplying credentials.

type Commands

type Commands = internalcontrol.Commands

Commands are the playback actions a Server dispatches. Set only the functions your application implements; nil entries cause the corresponding endpoint to be a no-op.

type Config

type Config = internalcontrol.Config

Config configures a Server.

• Addr — listen address (e.g. "127.0.0.1:7654" or ":7654")
• Token — bearer token; set to enable token auth
• SameAccountOnly — when Token is empty, require the controller to prove it is logged into the same Deezer account
• WebRemote — serve the phone web-remote SPA at GET /remote and use pairing (6-digit code) as the auth mechanism

type Server

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

Server hosts the OpenDeezer remote-control API. Construct one with NewServer; call Server.Start to bind the port; call Server.Close when done.

Server is safe for concurrent use once started.

func NewServer

func NewServer(
	cfg Config,
	status func() State,
	account func() Account,
	cmds Commands,
	dz *sdkdeezer.Client,
) *Server

NewServer builds a control server.

• cfg — listen address and auth mode
• status — called on each request; must return a race-free snapshot of the current playback state
• account — called on each request; must return the logged-in identity
• cmds — the actions the server can dispatch to your player
• dz — Deezer client used to serve GET /search and GET /playlists; pass nil to disable browse endpoints

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the actual listen address (valid after Server.Start).

func (*Server) Close

func (s *Server) Close()

Close stops the server and releases the port.

func (*Server) DisablePairing

func (s *Server) DisablePairing()

DisablePairing clears the pairing code. Existing valid session tokens remain usable for their remaining TTL (12 hours).

func (*Server) EnablePairing

func (s *Server) EnablePairing() string

EnablePairing mints a fresh 6-digit pairing code, activates the pairing flow, and returns the code. Display it to the user; they enter it in the phone web remote at http://<addr>/remote. Each call resets the code.

func (*Server) PairingActive

func (s *Server) PairingActive() bool

PairingActive reports whether a pairing code is currently active.

func (*Server) PairingCode

func (s *Server) PairingCode() string

PairingCode returns the current 6-digit code, or an empty string when pairing is not active.

func (*Server) SetClientInfo

func (s *Server) SetClientInfo(client, device string)

SetClientInfo records the client/platform id and human device label for GET /whoami (e.g. "myapp", "My Player v1.0").

func (*Server) SetVersion

func (s *Server) SetVersion(v string)

SetVersion records the app version reported by GET /whoami.

func (*Server) Start

func (s *Server) Start() error

Start binds the port and begins serving in a background goroutine.

type State

type State = internalcontrol.State

State is the playback snapshot returned by GET /status and all mutation endpoints. It is also the return type of all Client mutation methods.

type Track

type Track = internalcontrol.Track

Track is a now-playing or queue entry in a State.

type Whoami

type Whoami = internalcontrol.Whoami

Whoami is the unauthenticated identity returned by GET /whoami. It carries the account display Name but never the UserID (which is the credential in same-account mode).