PlexAPI Documentation

To control Sonos speakers via the Plex API, you must have:

1. An active Plex Pass subscription.
2. A Sonos account linked to your Plex account.
3. Plex remote access enabled.

Control is performed through a PlexSonosPlayer instance obtained from a MyPlexAccount object. Note that media playback routes through https://sonos.plex.tv and back via the Plex server's remote access.

from plexapi.myplex import MyPlexAccount
from plexapi.server import PlexServer

baseurl = 'http://plexserver:32400'
token = '2ffLuB84dqLswk9skLos'

account = MyPlexAccount(token)
server = PlexServer(baseurl, token)

# List available speakers
for speaker in account.sonos_speakers():
    print(speaker.title)

# Control a specific speaker
speaker = account.sonos_speaker("Kitchen")
album = server.library.section('Music').get('Stevie Wonder').album('Innervisions')

speaker.playMedia(album)
speaker.pause()
speaker.setVolume(10)
speaker.skipNext()

The PlexServer instance provides access to your media library and various playback controls. Here are common patterns:

Searching and Filtering

• List unwatched movies: Use plex.library.section('Movies').search(unwatched=True).
• Search by title: Use plex.search('query') to search all content.
• Filter by metadata: Search for content by specific attributes like director.

Library Management

• Marking content as played: Use .markPlayed() on a library item.
• Rating content: Use .rate(rating) where rating is a float (e.g., 8.0 for 4 stars).
• Accessing episodes: Use .episodes() on a show to get its episode list.

Client and Playback Control

• List connected clients: Use plex.clients().
• Play media on a specific client: Use client.playMedia(media_item) where the client is obtained via plex.client("Client Name").

# List unwatched movies
movies = plex.library.section('Movies')
for video in movies.search(unwatched=True):
    print(video.title)

# Mark Game of Thrones as played
plex.library.section('TV Shows').get('Game of Thrones').markPlayed()

# List connected clients
for client in plex.clients():
    print(client.title)

# Play Cars on Michael's iPhone
cars = plex.library.section('Movies').get('Cars')
client = plex.client("Michael's iPhone")
client.playMedia(cars)

# Search for 'Game' in titles
for video in plex.search('Game'):
    print(f'{video.title} ({video.TYPE})')

# List movies by a specific director
movies = plex.library.section('Movies')
director = movies.get('Elephants Dream').directors[0]
for movie in movies.search(None, director=director):
    print(movie.title)

# Rate a show
plex.library.section('TV Shows').get('The 100').rate(8.0)

Python-PlexAPI uses an optional configuration file to control default behaviors. The default location is ~/.config/plexapi/config.ini. You can override this default path by setting the PLEXAPI_CONFIG_PATH environment variable.

An example config.ini structure is provided below. Note that all variables are optional.

Security Warning: If you include sensitive information like myplex_password, server_token, or client_token in your config file, ensure the file permissions are restricted (e.g., chmod 600 ~/.config/plexapi/config.ini) so other users cannot read them.

# ~/.config/plexapi/config.ini
[plexapi]
container_size = 50
timeout = 30
timezone = false

[auth]
myplex_username = johndoe
myplex_password = kodi-stinks
server_baseurl = http://127.0.0.1:32400
server_token = XBHSMSJSDJ763JSm
client_baseurl = http://127.0.0.1:32433
client_token = BDFSLCNSNL789FH7

[header]
identifier = 0x485b314307f3L
platorm = Linux
platform_version = 4.4.0-62-generic
product = PlexAPI
version = 3.0.0

[log]
backup_count = 3
format = %(asctime)s %(module)12s:%(lineno)-4s %(levelname)-9s %(message)s
level = INFO
path = ~/.config/plexapi/plexapi.log
rotate_bytes = 512000
show_secrets = false