24 KiB
Playlists
(Playlists)
Overview
Playlists are ordered collections of media. They can be dumb (just a list of media) or smart (based on a media query, such as "all albums from 2017"). They can be organized in (optionally nesting) folders. Retrieving a playlist, or its items, will trigger a refresh of its metadata. This may cause the duration and number of items to change.
Available Operations
- CreatePlaylist - Create a Playlist
- GetPlaylists - Get All Playlists
- GetPlaylist - Retrieve Playlist
- DeletePlaylist - Deletes a Playlist
- UpdatePlaylist - Update a Playlist
- GetPlaylistContents - Retrieve Playlist Contents
- ClearPlaylistContents - Delete Playlist Contents
- AddPlaylistContents - Adding to a Playlist
- UploadPlaylist - Upload Playlist
CreatePlaylist
Create a new playlist. By default the playlist is blank. To create a playlist along with a first item, pass:
uri- The content URI for what we're playing (e.g.server://1234/com.plexapp.plugins.library/library/metadata/1).playQueueID- To create a playlist from an existing play queue.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
CreatePlaylistRequest req = new CreatePlaylistRequest() {
Title = "<value>",
Type = QueryParamType.Photo,
Smart = Smart.One,
Uri = "https://inborn-brochure.biz",
};
var res = await sdk.Playlists.CreatePlaylistAsync(req);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
request |
CreatePlaylistRequest | ✔️ | The request object to use for the request. |
Response
GetPlaylists
Get All Playlists given the specified filters.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.GetPlaylistsAsync(
playlistType: PlaylistType.Audio,
smart: QueryParamSmart.Zero);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistType |
PlaylistType | ➖ | limit to a type of playlist. |
Smart |
QueryParamSmart | ➖ | type of playlists to return (default is all). |
Response
GetPlaylist
Gets detailed metadata for a playlist. A playlist for many purposes (rating, editing metadata, tagging), can be treated like a regular metadata item:
Smart playlist details contain the content attribute. This is the content URI for the generator. This can then be parsed by a client to provide smart playlist editing.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.GetPlaylistAsync(playlistID: 4109.48D);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist |
Response
DeletePlaylist
This endpoint will delete a playlist
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.DeletePlaylistAsync(playlistID: 216.22D);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist |
Response
UpdatePlaylist
From PMS version 1.9.1 clients can also edit playlist metadata using this endpoint as they would via PUT /library/metadata/{playlistID}
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.UpdatePlaylistAsync(
playlistID: 3915D,
title: "<value>",
summary: "<value>");
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist |
Title |
string | ➖ | name of the playlist |
Summary |
string | ➖ | summary description of the playlist |
Response
GetPlaylistContents
Gets the contents of a playlist. Should be paged by clients via standard mechanisms.
By default leaves are returned (e.g. episodes, movies). In order to return other types you can use the type parameter.
For example, you could use this to display a list of recently added albums vis a smart playlist.
Note that for dumb playlists, items have a playlistItemID attribute which is used for deleting or moving items.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.GetPlaylistContentsAsync(
playlistID: 5004.46D,
type: 9403.59D);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist |
Type |
double | ✔️ | the metadata type of the item to return |
Response
ClearPlaylistContents
Clears a playlist, only works with dumb playlists. Returns the playlist.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.ClearPlaylistContentsAsync(playlistID: 1893.18D);
// handle response
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist |
Response
AddPlaylistContents
Adds a generator to a playlist, same parameters as the POST to create. With a dumb playlist, this adds the specified items to the playlist.
With a smart playlist, passing a new uri parameter replaces the rules for the playlist. Returns the playlist.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.AddPlaylistContentsAsync(
playlistID: 8502.01D,
uri: "server://12345/com.plexapp.plugins.library/library/metadata/1",
playQueueID: 123D);
// handle response
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
PlaylistID |
double | ✔️ | the ID of the playlist | |
Uri |
string | ✔️ | the content URI for the playlist | server://12345/com.plexapp.plugins.library/library/metadata/1 |
PlayQueueID |
double | ➖ | the play queue to add to a playlist | 123 |
Response
UploadPlaylist
Imports m3u playlists by passing a path on the server to scan for m3u-formatted playlist files, or a path to a single playlist file.
Example Usage
using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;
var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");
var res = await sdk.Playlists.UploadPlaylistAsync(
path: "/home/barkley/playlist.m3u",
force: Force.Zero);
// handle response
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
Path |
string | ✔️ | absolute path to a directory on the server where m3u files are stored, or the absolute path to a playlist file on the server. If the path argument is a directory, that path will be scanned for playlist files to be processed. Each file in that directory creates a separate playlist, with a name based on the filename of the file that created it. The GUID of each playlist is based on the filename. If the path argument is a file, that file will be used to create a new playlist, with the name based on the filename of the file that created it. The GUID of each playlist is based on the filename. |
/home/barkley/playlist.m3u |
Force |
Force | ✔️ | Force overwriting of duplicate playlists. By default, a playlist file uploaded with the same path will overwrite the existing playlist. The force argument is used to disable overwriting. If the force argument is set to 0, a new playlist will be created suffixed with the date and time that the duplicate was uploaded. |