LukeParke/plexjs
1
0
Fork 0
mirror of https://github.com/LukeHagar/plexjs.git synced 2025-12-09 20:47:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
9e28d57f158fdf9fa3669b918ae2417f4611f64e
plexjs/docs/sdks/playlists/README.md

454 lines
63 KiB
Markdown
Raw Blame History

# 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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const result = await sdk.playlists.createPlaylist({
title: "<value>",
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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistType = PlaylistType.Audio;
const smart = QueryParamSmart.Zero;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 4109.48;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 216.22;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 3915;
const title = "<value>";
const summary = "<value>";
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 5004.46;
const type = 9403.59;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 1893.18;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const playlistID = 8502.01;
const uri = "server://12345/com.plexapp.plugins.library/library/metadata/1";
const playQueueID = 123;
const result = await sdk.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";
async function run() {
const sdk = new PlexAPI({
accessToken: "<YOUR_API_KEY_HERE>",
});
const path = "/home/barkley/playlist.m3u";
const force = Force.Zero;
const result = await sdk.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. <br/>If the `path` argument is a directory, that path will be scanned for playlist files to be processed. <br/>Each file in that directory creates a separate playlist, with a name based on the filename of the file that created it. <br/>The GUID of each playlist is based on the filename. <br/>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. <br/>The GUID of each playlist is based on the filename.<br/> | [object Object] |
| `force` | [operations.Force](../../models/operations/force.md) | :heavy_check_mark: | Force overwriting of duplicate playlists. <br/>By default, a playlist file uploaded with the same path will overwrite the existing playlist. <br/>The `force` argument is used to disable overwriting. <br/>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.<br/> | |
| `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 | */* |
Reference in New Issue View Git Blame Copy Permalink