plex

package
v0.3.22 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package plex provides a client for interacting with Plex Media Server. It supports authentication, library browsing, and stream URL generation. The client handles API versioning gracefully and logs warnings for unexpected responses.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SetAPILogger added in v0.2.2

func SetAPILogger(l *log.Logger)

SetAPILogger allows customizing the logger for API warnings

func SilenceAPIWarnings added in v0.2.2

func SilenceAPIWarnings()

SilenceAPIWarnings disables API warning logging

Types

type Client

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

func New

func New(serverURL, token string) (*Client, error)

New creates a new Plex client

func NewWithName

func NewWithName(serverURL, token, serverName string) (*Client, error)

NewWithName creates a new Plex client with a server name

func (*Client) GetAllMedia

func (c *Client) GetAllMedia(ctx context.Context, progressCallback ProgressCallback) ([]MediaItem, error)

GetAllMedia returns all media items from all libraries.

func (*Client) GetLibraries

func (c *Client) GetLibraries(ctx context.Context) ([]Library, error)

GetLibraries returns all library sections using direct HTTP to avoid unmarshaling issues

func (*Client) GetMediaFromSection

func (c *Client) GetMediaFromSection(ctx context.Context, sectionKey, sectionType string) ([]MediaItem, error)

GetMediaFromSection returns media items from a specific library section. It pages through the section rather than requesting everything at once, because large libraries make the Plex server return HTTP 500 for a single unpaginated /all request.

func (*Client) GetMediaSince added in v0.2.2

func (c *Client) GetMediaSince(ctx context.Context, sinceFor func(libType string) int64, progressCallback ProgressCallback) ([]MediaItem, error)

GetMediaSince returns only items added since a per-library-type threshold, for incremental cache updates. sinceFor receives the library type ("movie" or "show") and returns the newest addedAt already known for that type (return 0 to fetch the whole library).

func (*Client) GetStreamURL

func (c *Client) GetStreamURL(mediaKey string) (string, error)

GetStreamURL returns the direct stream URL for a media item This gets the actual file URL that can be streamed by MPV

func (*Client) SetPathMappings added in v0.2.2

func (c *Client) SetPathMappings(mappings []PathMapping)

SetPathMappings configures the rclone path-translation rules used when building media items. Mappings are tried longest-prefix-first.

func (*Client) Test

func (c *Client) Test() error

Test validates the connection to the Plex server

func (*Client) TestContext added in v0.2.9

func (c *Client) TestContext(ctx context.Context) error

TestContext validates the connection to the Plex server, honoring the caller's context for cancellation and deadlines.

func (*Client) UpdateTimeline added in v0.2.2

func (c *Client) UpdateTimeline(ratingKey string, state string, timeMs int, durationMs int) error

UpdateTimeline reports playback progress to the Plex server. This updates the resume position and shows "Now Playing" on the Plex dashboard. state should be "playing", "paused", or "stopped". timeMs is the current position in milliseconds. durationMs is the total duration in milliseconds.

type Library

type Library struct {
	Key   string
	Title string
	Type  string
}

Library represents a Plex library section

type MediaItem

type MediaItem struct {
	Key              string
	Title            string
	Year             int
	Type             string // movie, show, season, episode
	Summary          string
	Rating           float64
	Duration         int
	FilePath         string
	RclonePath       string
	ParentTitle      string // For episodes: show name
	GrandTitle       string // For episodes: season name
	Index            int64  // Episode or season number
	ParentIndex      int64  // Season number for episodes
	Thumb            string // Poster/thumbnail URL path (episode still for episodes)
	GrandparentThumb string // For episodes: the show poster path (grandparentThumb)
	ServerName       string // Name of the Plex server this item belongs to
	ServerURL        string // URL of the Plex server this item belongs to
	ViewOffset       int    // Playback position in milliseconds (0 if not started)
	ViewCount        int    // Number of times fully watched
	LastViewedAt     int64  // Unix timestamp of last playback (0 if never viewed)
	ContentRating    string // e.g., "PG-13", "TV-MA"
	Studio           string // Production studio
	Director         string // Director name(s)
	Genre            string // Genre(s), comma-separated
	Cast             string // Cast members, comma-separated
	AddedAt          int64  // Unix timestamp when added to library
	OriginallyAired  string // Original air date for episodes
}

func GetAllMediaFromServers

func GetAllMediaFromServers(ctx context.Context, serverConfigs []struct{ Name, URL, Token string }, mappings []PathMapping, progressCallback ServerProgressCallback) ([]MediaItem, error)

GetAllMediaFromServers returns all media items from multiple Plex servers. mappings configures rclone path translation (see PathMapping); pass nil to use the legacy fallback.

func GetNewMediaFromServers added in v0.2.2

func GetNewMediaFromServers(ctx context.Context, serverConfigs []struct{ Name, URL, Token string }, mappings []PathMapping, sinceFor func(serverName, libType string) int64, progressCallback ServerProgressCallback) ([]MediaItem, error)

GetNewMediaFromServers returns only items added since a per-server, per-library-type threshold across multiple Plex servers, for incremental cache updates. sinceFor receives the server name and library type ("movie"/"show") and returns the newest addedAt already known (0 to fetch the whole library).

func (*MediaItem) FormatMediaTitle

func (m *MediaItem) FormatMediaTitle() string

FormatMediaTitle returns a formatted title for display

type PathMapping added in v0.2.2

type PathMapping struct {
	Prefix string
	Remote string
}

PathMapping describes how to translate a Plex on-disk file path into an rclone remote path. A file path beginning with Prefix has that prefix replaced by Remote. For example {Prefix: "/home/joshkerr/plexcloudservers2/", Remote: "plexcloudservers2:"} turns "/home/joshkerr/plexcloudservers2/Media/TV/x.mkv" into "plexcloudservers2:Media/TV/x.mkv".

type ProgressCallback

type ProgressCallback func(libraryName string, itemCount int, totalItems int, totalLibraries int, currentLibrary int)

ProgressCallback is called during media fetching to report progress. It may be called multiple times per library as pages are fetched: itemCount is the number of items retrieved so far in the current library, and totalItems is the library's total (0 if unknown).

type Server

type Server struct {
	Name        string
	URL         string
	Local       bool
	Owned       bool
	Connections []string
	// AccessToken is the per-server token issued by plex.tv. For shared
	// (non-owner) users this is the only token the server accepts; the
	// account token used to talk to plex.tv gets a 401.
	AccessToken string
}

Server represents a Plex server

func Authenticate

func Authenticate(username, password string) (string, []Server, error)

Authenticate authenticates with Plex using username and password Returns auth token and list of available servers

type ServerProgressCallback

type ServerProgressCallback func(serverName, libraryName string, itemCount int, totalItems int, totalLibraries int, currentLibrary int, serverNum int, totalServers int)

ServerProgressCallback is called during multi-server media fetching. As with ProgressCallback, it may fire repeatedly per library with the running itemCount and the library's totalItems.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL