// Zaparoo Core
// Copyright (c) 2026 The Zaparoo Project Contributors.
// SPDX-License-Identifier: GPL-3.0-or-later
//
// This file is part of Zaparoo Core.
//
// Zaparoo Core is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Zaparoo Core is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Zaparoo Core. If not, see .
package plex
import (
"context"
"encoding/xml"
"errors"
"fmt"
"net"
"net/http"
"net/url"
"strconv"
"strings"
"sync/atomic"
"time"
"github.com/ZaparooProject/zaparoo-core/v2/pkg/config"
"github.com/rs/zerolog/log"
)
// Player commands, named as the Companion protocol names them.
const (
cmdPlay = "play"
cmdPause = "pause"
cmdStop = "stop"
cmdNext = "skipNext"
cmdPrevious = "skipPrevious"
cmdStepForward = "stepForward"
cmdStepBack = "stepBack"
)
const (
playerKindCompanion = "Companion"
playerKindCast = "Cast"
)
// companionTimeout bounds one Companion command. A working player answers
// at once; a wedged one leaves the request open until the server gives up.
const companionTimeout = 10 * time.Second
// errPlayerNoAnswer is a Companion command the player never answered.
var errPlayerNoAnswer = errors.New("plex player did not answer")
// commandID numbers Companion commands. Players use it to order commands
// from one controller, so it only ever increases within a process.
var commandID atomic.Int64
func nextCommandID() string {
return strconv.FormatInt(commandID.Add(1), 10)
}
// serverInfo is how a player reaches the Plex server to fetch media.
type serverInfo struct {
MachineID string
Version string
Protocol string
Address string
Token string
Port int
}
func newServerInfo(client PlexClient, id *Identity) (serverInfo, error) {
u, err := url.Parse(client.ServerURL())
if err != nil || u.Hostname() == "" {
return serverInfo{}, fmt.Errorf("invalid plex server URL %q", client.ServerURL())
}
protocol := strings.ToLower(u.Scheme)
port := 80
if protocol == "https" {
port = 443
}
if p := u.Port(); p != "" {
port, err = strconv.Atoi(p)
if err != nil {
return serverInfo{}, fmt.Errorf("invalid plex server port %q: %w", p, err)
}
}
return serverInfo{
MachineID: id.MachineIdentifier,
Version: id.Version,
Protocol: protocol,
Address: u.Hostname(),
Port: port,
Token: client.ServerToken(),
}, nil
}
// playRequest is a queue to start on a player.
type playRequest struct {
Queue *PlayQueue
First *Metadata
Kind *mediaKind
Server serverInfo
}
// playerState is what a player says it is doing.
type playerState struct {
RatingKey string
Playing bool
Paused bool
}
// player is a device a Plex queue can be sent to.
type player interface {
Name() string
Kind() string
Play(ctx context.Context, req *playRequest) error
Command(ctx context.Context, cmd string, kind *mediaKind) error
State(ctx context.Context) (*playerState, error)
}
// companionPlayer is a player driven over the Plex Companion HTTP protocol.
type companionPlayer struct {
http *http.Client
name string
machineID string
baseURL string
clientID string
token string
// timeout overrides companionTimeout in tests.
timeout time.Duration
}
func (p *companionPlayer) Name() string { return p.name }
func (*companionPlayer) Kind() string { return playerKindCompanion }
func (p *companionPlayer) headers() http.Header {
h := plexHeaders(p.clientID, p.token)
h.Set("X-Plex-Target-Client-Identifier", p.machineID)
return h
}
func (p *companionPlayer) get(ctx context.Context, path string, query url.Values) ([]byte, error) {
timeout := p.timeout
if timeout <= 0 {
timeout = companionTimeout
}
cmdCtx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
query.Set("commandID", nextCommandID())
body, err := doRawRequest(cmdCtx, p.http, http.MethodGet, p.baseURL+path+"?"+query.Encode(), p.headers())
if err != nil {
if cmdCtx.Err() != nil && ctx.Err() == nil {
return nil, fmt.Errorf("%w: %q gave no answer to %s within %s, restarting the Plex app may help",
errPlayerNoAnswer, p.name, path, timeout)
}
return nil, fmt.Errorf("plex player %q: %w", p.name, err)
}
return body, nil
}
func (p *companionPlayer) Play(ctx context.Context, req *playRequest) error {
query := url.Values{}
query.Set("key", "/library/metadata/"+req.First.RatingKey)
query.Set("containerKey", fmt.Sprintf("/playQueues/%d?own=1&window=200", req.Queue.ID))
query.Set("machineIdentifier", req.Server.MachineID)
query.Set("address", req.Server.Address)
query.Set("port", strconv.Itoa(req.Server.Port))
query.Set("protocol", req.Server.Protocol)
query.Set("token", req.Server.Token)
query.Set("offset", "0")
query.Set("type", req.Kind.controlType)
// Some players build their own queue only through createPlayQueue and
// others do not know it, so its failure is not the launch's.
create := url.Values{}
for k, v := range query {
create[k] = v
}
create.Set("uri", libraryURI(req.Server.MachineID, req.First.RatingKey))
if _, err := p.get(ctx, "/player/playback/createPlayQueue", create); err != nil {
if errors.Is(err, errPlayerNoAnswer) {
return err
}
log.Debug().Err(err).Str("player", p.name).Msg("plex player did not take createPlayQueue")
}
_, err := p.get(ctx, "/player/playback/playMedia", query)
return err
}
func (p *companionPlayer) Command(ctx context.Context, cmd string, kind *mediaKind) error {
query := url.Values{}
query.Set("type", kind.controlType)
_, err := p.get(ctx, "/player/playback/"+cmd, query)
return err
}
type timeline struct {
Type string `xml:"type,attr"`
State string `xml:"state,attr"`
RatingKey string `xml:"ratingKey,attr"`
Key string `xml:"key,attr"`
}
type timelineContainer struct {
Timelines []timeline `xml:"Timeline"`
}
func (p *companionPlayer) State(ctx context.Context) (*playerState, error) {
query := url.Values{}
query.Set("wait", "0")
body, err := p.get(ctx, "/player/timeline/poll", query)
if err != nil {
return nil, err
}
var tl timelineContainer
if err := xml.Unmarshal(body, &tl); err != nil {
return nil, fmt.Errorf("plex player %q sent an unreadable timeline: %w", p.name, err)
}
state := &playerState{}
for _, t := range tl.Timelines {
key := t.RatingKey
if key == "" {
key = keyFromPath(t.Key)
}
switch strings.ToLower(t.State) {
case "playing", "buffering":
return &playerState{Playing: true, RatingKey: key}, nil
case "paused":
state = &playerState{Paused: true, RatingKey: key}
}
}
return state, nil
}
// keyFromPath takes the rating key off a /library/metadata/ path.
func keyFromPath(path string) string {
path = strings.TrimRight(path, "/")
if i := strings.LastIndex(path, "/"); i >= 0 {
path = path[i+1:]
}
if validKey(path) {
return path
}
return ""
}
// playerFinder finds the configured player among the Companion players the
// server and plex.tv know and the Cast devices on the network.
type playerFinder struct {
http *http.Client
browseCast func(ctx context.Context) ([]castDevice, error)
dialCast castDialer
}
func newCompanionFromServer(f *playerFinder, client PlexClient, c *ServerClient) *companionPlayer {
host := c.Address
if host == "" {
host = c.Host
}
if host == "" || c.Port <= 0 || c.MachineIdentifier == "" {
return nil
}
if c.ProtocolCapabilities != "" && !strings.Contains(c.ProtocolCapabilities, "playback") {
return nil
}
return &companionPlayer{
http: f.http,
name: c.Name,
machineID: c.MachineIdentifier,
baseURL: "http://" + net.JoinHostPort(host, strconv.Itoa(int(c.Port))),
clientID: client.ClientIdentifier(),
token: client.ServerToken(),
}
}
func newCompanionFromResource(f *playerFinder, client PlexClient, r *Resource) *companionPlayer {
if r.ClientIdentifier == "" {
return nil
}
conn := pickConnection(r.Connections)
if conn == nil {
return nil
}
token := r.AccessToken
if token == "" {
token = client.AccountToken()
}
return &companionPlayer{
http: f.http,
name: r.Name,
machineID: r.ClientIdentifier,
baseURL: strings.TrimRight(conn.URI, "/"),
clientID: client.ClientIdentifier(),
token: token,
}
}
// pickConnection prefers a local connection, then any direct one. Relays
// are never used.
func pickConnection(conns []Connection) *Connection {
var direct *Connection
for i := range conns {
c := &conns[i]
if c.Relay || c.URI == "" {
continue
}
if c.Local {
return c
}
if direct == nil {
direct = c
}
}
return direct
}
func (f *playerFinder) companionPlayers(ctx context.Context, client PlexClient) []player {
var players []player
seen := map[string]bool{}
clients, err := client.Clients(ctx)
if err != nil {
log.Warn().Err(err).Msg("failed to list players known to the plex server")
}
for i := range clients {
if p := newCompanionFromServer(f, client, &clients[i]); p != nil && !seen[p.machineID] {
seen[p.machineID] = true
players = append(players, p)
}
}
resources, err := client.PlayerResources(ctx)
if err != nil {
log.Warn().Err(err).Msg("failed to list players registered with plex.tv")
}
for i := range resources {
if p := newCompanionFromResource(f, client, &resources[i]); p != nil && !seen[p.machineID] {
seen[p.machineID] = true
players = append(players, p)
}
}
return players
}
func (f *playerFinder) castPlayers(ctx context.Context, client PlexClient) []player {
if f.browseCast == nil {
return nil
}
devices, err := f.browseCast(ctx)
if err != nil {
log.Warn().Err(err).Msg("failed to look for cast devices")
}
players := make([]player, 0, len(devices))
for i := range devices {
d := devices[i]
if d.Name == "" || d.Host == "" {
continue
}
players = append(players, &castPlayer{
name: d.Name,
addr: net.JoinHostPort(d.Host, strconv.Itoa(d.Port)),
dial: f.dialCast,
clientID: client.ClientIdentifier(),
})
}
return players
}
func matchPlayer(players []player, name string) player {
for _, p := range players {
if strings.EqualFold(strings.TrimSpace(p.Name()), name) {
return p
}
}
return nil
}
// find returns the player the client setting names, or the only player
// there is when it names none.
func (f *playerFinder) find(ctx context.Context, client PlexClient) (player, error) {
name := strings.TrimSpace(client.PlayerName())
companions := f.companionPlayers(ctx, client)
if name != "" {
if p := matchPlayer(companions, name); p != nil {
return p, nil
}
}
all := append(companions, f.castPlayers(ctx, client)...) //nolint:gocritic // companions is not used after this
if name != "" {
if p := matchPlayer(all, name); p != nil {
return p, nil
}
return nil, fmt.Errorf("plex player %q not found; %s", name, describePlayers(all))
}
switch len(all) {
case 1:
return all[0], nil
case 0:
return nil, errors.New(
"no plex players found; open Plex on the player or set client in the plex launcher settings")
default:
return nil, fmt.Errorf("several plex players found, set client in the plex launcher settings; %s",
describePlayers(all))
}
}
func describePlayers(players []player) string {
if len(players) == 0 {
return "no players found"
}
names := make([]string, 0, len(players))
for _, p := range players {
names = append(names, fmt.Sprintf("%q (%s)", p.Name(), p.Kind()))
}
return "players found: " + strings.Join(names, ", ")
}
// clientForConfig is the shape of NewClientWithLauncherID, replaced in tests.
type clientForConfig func(cfg *config.Instance, id string, groups []string) PlexClient