plexjs/docs/sdks/playlists/README.md

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

import { PlexAPI } from "@lukehagar/plexjs";
import { CreatePlaylistQueryParamType, Smart } from "@lukehagar/plexjs/sdk/models/operations";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.createPlaylist({
    title: "<value>",
    type: CreatePlaylistQueryParamType.Audio,
    smart: Smart.One,
    uri: "https://short-term-disconnection.name/",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsCreatePlaylist } from "@lukehagar/plexjs/funcs/playlistsCreatePlaylist.js";
import { CreatePlaylistQueryParamType, Smart } from "@lukehagar/plexjs/sdk/models/operations";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsCreatePlaylist(plexAPI, {
    title: "<value>",
    type: CreatePlaylistQueryParamType.Audio,
    smart: Smart.One,
    uri: "https://short-term-disconnection.name/",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsCreatePlaylist failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
request	operations.CreatePlaylistRequest	✔️	The request object to use for the request.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.CreatePlaylistResponse>

Errors

Error Type	Status Code	Content Type
errors.CreatePlaylistBadRequest	400	application/json
errors.CreatePlaylistUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

getPlaylists

Get All Playlists given the specified filters.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.getPlaylists();

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsGetPlaylists } from "@lukehagar/plexjs/funcs/playlistsGetPlaylists.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsGetPlaylists(plexAPI);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsGetPlaylists failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
playlistType	operations.PlaylistType	➖	limit to a type of playlist.
smart	operations.QueryParamSmart	➖	type of playlists to return (default is all).
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetPlaylistsResponse>

Errors

Error Type	Status Code	Content Type
errors.GetPlaylistsBadRequest	400	application/json
errors.GetPlaylistsUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

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

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.getPlaylist(8419.53);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsGetPlaylist } from "@lukehagar/plexjs/funcs/playlistsGetPlaylist.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsGetPlaylist(plexAPI, 8419.53);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsGetPlaylist failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
playlistID	number	✔️	the ID of the playlist
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetPlaylistResponse>

Errors

Error Type	Status Code	Content Type
errors.GetPlaylistBadRequest	400	application/json
errors.GetPlaylistUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

deletePlaylist

This endpoint will delete a playlist

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.deletePlaylist(3432.93);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsDeletePlaylist } from "@lukehagar/plexjs/funcs/playlistsDeletePlaylist.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsDeletePlaylist(plexAPI, 3432.93);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsDeletePlaylist failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
playlistID	number	✔️	the ID of the playlist
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.DeletePlaylistResponse>

Errors

Error Type	Status Code	Content Type
errors.DeletePlaylistBadRequest	400	application/json
errors.DeletePlaylistUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

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

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.updatePlaylist(1579.66);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsUpdatePlaylist } from "@lukehagar/plexjs/funcs/playlistsUpdatePlaylist.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsUpdatePlaylist(plexAPI, 1579.66);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsUpdatePlaylist failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
playlistID	number	✔️	the ID of the playlist
title	string	➖	name of the playlist
summary	string	➖	summary description of the playlist
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.UpdatePlaylistResponse>

Errors

Error Type	Status Code	Content Type
errors.UpdatePlaylistBadRequest	400	application/json
errors.UpdatePlaylistUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

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

import { PlexAPI } from "@lukehagar/plexjs";
import { GetPlaylistContentsQueryParamType } from "@lukehagar/plexjs/sdk/models/operations";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.getPlaylistContents(5535.42, GetPlaylistContentsQueryParamType.TvShow);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsGetPlaylistContents } from "@lukehagar/plexjs/funcs/playlistsGetPlaylistContents.js";
import { GetPlaylistContentsQueryParamType } from "@lukehagar/plexjs/sdk/models/operations";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsGetPlaylistContents(plexAPI, 5535.42, GetPlaylistContentsQueryParamType.TvShow);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsGetPlaylistContents failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description	Example
playlistID	number	✔️	the ID of the playlist
type	operations.GetPlaylistContentsQueryParamType	✔️	The type of media to retrieve or filter by. 1 = movie 2 = show 3 = season 4 = episode E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetPlaylistContentsResponse>

Errors

Error Type	Status Code	Content Type
errors.GetPlaylistContentsBadRequest	400	application/json
errors.GetPlaylistContentsUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

clearPlaylistContents

Clears a playlist, only works with dumb playlists. Returns the playlist.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.clearPlaylistContents(4137.37);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsClearPlaylistContents } from "@lukehagar/plexjs/funcs/playlistsClearPlaylistContents.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsClearPlaylistContents(plexAPI, 4137.37);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsClearPlaylistContents failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
playlistID	number	✔️	the ID of the playlist
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.ClearPlaylistContentsResponse>

Errors

Error Type	Status Code	Content Type
errors.ClearPlaylistContentsBadRequest	400	application/json
errors.ClearPlaylistContentsUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

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

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.addPlaylistContents(7013.44, "server://12345/com.plexapp.plugins.library/library/metadata/1", 123);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsAddPlaylistContents } from "@lukehagar/plexjs/funcs/playlistsAddPlaylistContents.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsAddPlaylistContents(plexAPI, 7013.44, "server://12345/com.plexapp.plugins.library/library/metadata/1", 123);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsAddPlaylistContents failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description	Example
playlistID	number	✔️	the ID of the playlist
uri	string	✔️	the content URI for the playlist	[object Object]
playQueueID	number	➖	the play queue to add to a playlist	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.AddPlaylistContentsResponse>

Errors

Error Type	Status Code	Content Type
errors.AddPlaylistContentsBadRequest	400	application/json
errors.AddPlaylistContentsUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*

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

import { PlexAPI } from "@lukehagar/plexjs";
import { QueryParamForce } from "@lukehagar/plexjs/sdk/models/operations";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.playlists.uploadPlaylist("/home/barkley/playlist.m3u", QueryParamForce.One, 1);

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { playlistsUploadPlaylist } from "@lukehagar/plexjs/funcs/playlistsUploadPlaylist.js";
import { QueryParamForce } from "@lukehagar/plexjs/sdk/models/operations";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const res = await playlistsUploadPlaylist(plexAPI, "/home/barkley/playlist.m3u", QueryParamForce.One, 1);
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("playlistsUploadPlaylist failed:", res.error);
  }
}

run();

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.	[object Object]
force	operations.QueryParamForce	✔️	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.
sectionID	number	✔️	Possibly the section ID to upload the playlist to, we are not certain.	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.UploadPlaylistResponse>

Errors

Error Type	Status Code	Content Type
errors.UploadPlaylistBadRequest	400	application/json
errors.UploadPlaylistUnauthorized	401	application/json
errors.SDKError	4XX, 5XX	*/*