# 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](#createplaylist) - Create a Playlist * [getPlaylists](#getplaylists) - Get All Playlists * [getPlaylist](#getplaylist) - Retrieve Playlist * [deletePlaylist](#deleteplaylist) - Deletes a Playlist * [updatePlaylist](#updateplaylist) - Update a Playlist * [getPlaylistContents](#getplaylistcontents) - Retrieve Playlist Contents * [clearPlaylistContents](#clearplaylistcontents) - Delete Playlist Contents * [addPlaylistContents](#addplaylistcontents) - Adding to a Playlist * [uploadPlaylist](#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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; import { QueryParamType, Smart } from "@lukehagar/plexjs/models/operations"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const result = await plexAPI.playlists.createPlaylist({ title: "", type: QueryParamType.Photo, smart: Smart.One, uri: "https://inborn-brochure.biz", }); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `request` | [operations.CreatePlaylistRequest](../../models/operations/createplaylistrequest.md) | :heavy_check_mark: | The request object to use for the request. | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.CreatePlaylistResponse](../../models/operations/createplaylistresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | --------------------------------- | --------------------------------- | --------------------------------- | | errors.CreatePlaylistResponseBody | 401 | application/json | | errors.SDKError | 4xx-5xx | */* | ## getPlaylists Get All Playlists given the specified filters. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; import { PlaylistType, QueryParamSmart } from "@lukehagar/plexjs/models/operations"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistType = PlaylistType.Audio; const smart = QueryParamSmart.Zero; const result = await plexAPI.playlists.getPlaylists(playlistType, smart); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistType` | [operations.PlaylistType](../../models/operations/playlisttype.md) | :heavy_minus_sign: | limit to a type of playlist. | | `smart` | [operations.QueryParamSmart](../../models/operations/queryparamsmart.md) | :heavy_minus_sign: | type of playlists to return (default is all). | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.GetPlaylistsResponse](../../models/operations/getplaylistsresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | ------------------------------- | ------------------------------- | ------------------------------- | | errors.GetPlaylistsResponseBody | 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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 4109.48; const result = await plexAPI.playlists.getPlaylist(playlistID); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.GetPlaylistResponse](../../models/operations/getplaylistresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | ------------------------------ | ------------------------------ | ------------------------------ | | errors.GetPlaylistResponseBody | 401 | application/json | | errors.SDKError | 4xx-5xx | */* | ## deletePlaylist This endpoint will delete a playlist ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 216.22; const result = await plexAPI.playlists.deletePlaylist(playlistID); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.DeletePlaylistResponse](../../models/operations/deleteplaylistresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | --------------------------------- | --------------------------------- | --------------------------------- | | errors.DeletePlaylistResponseBody | 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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 3915; const title = ""; const summary = ""; const result = await plexAPI.playlists.updatePlaylist(playlistID, title, summary); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | `title` | *string* | :heavy_minus_sign: | name of the playlist | | `summary` | *string* | :heavy_minus_sign: | summary description of the playlist | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.UpdatePlaylistResponse](../../models/operations/updateplaylistresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | --------------------------------- | --------------------------------- | --------------------------------- | | errors.UpdatePlaylistResponseBody | 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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 5004.46; const type = 9403.59; const result = await plexAPI.playlists.getPlaylistContents(playlistID, type); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | `type` | *number* | :heavy_check_mark: | the metadata type of the item to return | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.GetPlaylistContentsResponse](../../models/operations/getplaylistcontentsresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | -------------------------------------- | -------------------------------------- | -------------------------------------- | | errors.GetPlaylistContentsResponseBody | 401 | application/json | | errors.SDKError | 4xx-5xx | */* | ## clearPlaylistContents Clears a playlist, only works with dumb playlists. Returns the playlist. ### Example Usage ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 1893.18; const result = await plexAPI.playlists.clearPlaylistContents(playlistID); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | ### Response **Promise<[operations.ClearPlaylistContentsResponse](../../models/operations/clearplaylistcontentsresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | | errors.ClearPlaylistContentsResponseBody | 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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const playlistID = 8502.01; const uri = "server://12345/com.plexapp.plugins.library/library/metadata/1"; const playQueueID = 123; const result = await plexAPI.playlists.addPlaylistContents(playlistID, uri, playQueueID); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | Example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `playlistID` | *number* | :heavy_check_mark: | the ID of the playlist | | | `uri` | *string* | :heavy_check_mark: | the content URI for the playlist | [object Object] | | `playQueueID` | *number* | :heavy_minus_sign: | the play queue to add to a playlist | [object Object] | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | | ### Response **Promise<[operations.AddPlaylistContentsResponse](../../models/operations/addplaylistcontentsresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | -------------------------------------- | -------------------------------------- | -------------------------------------- | | errors.AddPlaylistContentsResponseBody | 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 ```typescript import { PlexAPI } from "@lukehagar/plexjs"; import { Force } from "@lukehagar/plexjs/models/operations"; const plexAPI = new PlexAPI({ accessToken: "", xPlexClientIdentifier: "Postman", }); async function run() { const path = "/home/barkley/playlist.m3u"; const force = Force.Zero; const result = await plexAPI.playlists.uploadPlaylist(path, force); // Handle the result console.log(result) } run(); ``` ### Parameters | Parameter | Type | Required | Description | Example | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | *string* | :heavy_check_mark: | 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.Force](../../models/operations/force.md) | :heavy_check_mark: | 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.
| | | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. | | | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | 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. | | ### Response **Promise<[operations.UploadPlaylistResponse](../../models/operations/uploadplaylistresponse.md)>** ### Errors | Error Object | Status Code | Content Type | | --------------------------------- | --------------------------------- | --------------------------------- | | errors.UploadPlaylistResponseBody | 401 | application/json | | errors.SDKError | 4xx-5xx | */* |