Class Playlist

Hierarchy

Playable
- Playlist

Index

Constructors

Accessors

artwork hasPreviewThumbnails hasVoiceActivity isAudio isFullObject isPhoto isPlayed isVideo metadataDirectory metadataType thumb

Constructors

constructor

new Playlist(
    server: PlexServer,
    data: unknown,
    initpath?: string,
    parent?: PlexObject,
): Playlist
Parameters
- server: PlexServer
- data: unknown
- Optionalinitpath: string
- Optionalparent: PlexObject
Returns Playlist
Inherited from Playable.constructor
- Defined in src/base/plexObject.ts:24

Properties

_INCLUDES

_INCLUDES: {
    checkFiles: number;
    includeAllConcerts: number;
    includeBandwidths: number;
    includeChapters: number;
    includeChildren: number;
    includeConcerts: number;
    includeExternalMedia: number;
    includeExtras: number;
    includeFields: string;
    includeGeolocation: number;
    includeLoudnessRamps: number;
    includeMarkers: number;
    includeOnDeck: number;
    includePopularLeaves: number;
    includePreferences: number;
    includeRelated: number;
    includeRelatedCount: number;
    includeReviews: number;
    includeStations: number;
} = ...

`Optional`addedAt

addedAt?: Date

Missing on generated radio stations.

`Optional`allowSync

allowSync?: boolean

`Optional`centroid

centroid?: Artist

Artist that a personalized "Mix For You" playlist is centered on.

composite

composite: string

`Optional`content

content?: string

`Optional`duration

duration?: number

`Optional`durationInSeconds

durationInSeconds?: number

fields

fields: Field[]

guid

guid: string

`Optional`icon

icon?: string

key

key: string

Plex relative url of this metadata item.

leafCount

leafCount: number

`Optional`librarySectionID

librarySectionID?: number

`Optional`librarySectionKey

librarySectionKey?: string

`Optional`librarySectionTitle

librarySectionTitle?: string

`Optional`live

live?: boolean

Whether the active session is live TV.

`Optional` `Readonly`parent

parent?: WeakRef<PlexObject>

WeakRef to the parent object that this object is built from.

`Optional`player

player?: PlexSessionPlayer

Client currently playing this item.

players

players: PlexSessionPlayer[] = []

Clients associated with this active playback.

`Optional`playlistItemID

playlistItemID?: number

Playlist item ID, only populated for items loaded from a Playlist.

playlistType

playlistType: string

`Optional`playQueueItemID

playQueueItemID?: number

Queue-local item ID (only populated for PlayQueue items).

radio

radio: boolean

`Optional`ratingKey

ratingKey?: string

`Readonly`server

server: PlexServer

`Optional`session

session?: PlexPlaybackSession

Bandwidth allocation for the active playback, when one exists.

`Optional`sessionKey

sessionKey?: number

Server-local key for an active playback session.

sessions

sessions: PlexPlaybackSession[] = []

Bandwidth allocations associated with this active playback.

smart

smart: boolean

summary

summary: string

`Optional`title

title?: string

`Optional`transcodeSession

transcodeSession?: PlexTranscodeSession

Active transcode associated with this playback, when Plex includes it.

transcodeSessions

transcodeSessions: PlexTranscodeSession[] = []

Transcodes associated with this active playback.

`Optional`type

type?: string

TYPE

TYPE: string = 'playlist'

`Optional`updatedAt

updatedAt?: Date

Missing on generated radio stations.

`Optional`user

user?: PlexSessionUser

Account currently playing this item.

usernames

usernames: string[] = []

Usernames associated with this active playback.

`Optional`viewedAt

viewedAt?: Date

Datetime item was last viewed (history).

`Optional`year

year?: number

`Static`TAG

TAG: string = 'Playlist'

xml element tag

`Static`TYPE

TYPE: string | null = null

xml element type

Accessors

artwork

get artwork(): ArtworkManager
Typed poster, background, logo, and square-art management.

Returns ArtworkManager
Inherited from Playable.artwork
- Defined in src/base/partialPlexObject.ts:72

hasPreviewThumbnails

get hasPreviewThumbnails(): boolean
Returns boolean
Inherited from Playable.hasPreviewThumbnails
- Defined in src/base/playable.ts:192

hasVoiceActivity

get hasVoiceActivity(): boolean
Returns boolean
Inherited from Playable.hasVoiceActivity
- Defined in src/base/playable.ts:196

isAudio

get isAudio(): boolean
Returns boolean
- Defined in src/playlist.ts:312

isFullObject

get isFullObject(): boolean
Retruns True if this is already a full object. A full object means all attributes were populated from the api path representing only this item. For example, the search result for a movie often only contain a portion of the attributes a full object (main url) for that movie would contain.

Returns boolean
Inherited from Playable.isFullObject
- Defined in src/base/partialPlexObject.ts:290

isPhoto

get isPhoto(): boolean
Returns boolean
- Defined in src/playlist.ts:316

isPlayed

get isPlayed(): boolean
Returns boolean
Inherited from Playable.isPlayed
- Defined in src/base/playable.ts:86

isVideo

get isVideo(): boolean
Returns boolean
- Defined in src/playlist.ts:308

metadataDirectory

get metadataDirectory(): string | undefined
Path relative to the Plex server data directory, using server-independent separators.

Returns string | undefined
Inherited from Collections.metadataDirectory
- Defined in src/base/partialPlexObject.ts:106

metadataType

get metadataType(): PlaylistMetadataType
Returns PlaylistMetadataType
- Defined in src/playlist.ts:337

thumb

get thumb(): string
Returns string
- Defined in src/playlist.ts:325

Methods

_edit

_edit(args: { summary?: string; title?: string }): Promise<void>
Parameters
- args: { summary?: string; title?: string }
Returns Promise<void>
- Defined in src/playlist.ts:371

addCollection

addCollection(collections: string[]): Promise<void>
Add a collection(s).
Parameters
- collections: string[]
Returns Promise<void>
Inherited from Playable.addCollection
- Defined in src/base/partialPlexObject.ts:439

addGenre

addGenre(genres: string[]): Promise<void>
Add a genre(s).
Parameters
- genres: string[]
Returns Promise<void>
Inherited from Playable.addGenre
- Defined in src/base/partialPlexObject.ts:459

addItems

addItems(items: PlaylistContent[]): Promise<Playlist>
Add items to a playlist.
Parameters
- items: PlaylistContent[]
Returns Promise<Playlist>
- Defined in src/playlist.ts:412

addLabel

addLabel(labels: string[]): Promise<void>
Add a label(s).
Parameters
- labels: string[]
Returns Promise<void>
Inherited from Playable.addLabel
- Defined in src/base/partialPlexObject.ts:449

analyze

analyze(): Promise<void>
Tell Plex Media Server to performs analysis on it this item to gather information. Analysis includes:
- Gather Media Properties: All of the media you add to a Library has properties that are useful to know–whether it's a video file, a music track, or one of your photos (container, codec, resolution, etc).
- Generate Default Artwork: Artwork will automatically be grabbed from a video file. A background image will be pulled out as well as a smaller image to be used for poster/thumbnail type purposes.
- Generate Video Preview Thumbnails: Video preview thumbnails are created, if you have that feature enabled. Video preview thumbnails allow graphical seeking in some Apps. It's also used in the Plex Web App Now Playing screen to show a graphical representation of where playback is. Video preview thumbnails creation is a CPU-intensive process akin to transcoding the file.
- Generate intro video markers: Detects show intros, exposing the 'Skip Intro' button in clients.
Returns Promise<void>
Inherited from Playable.analyze
- Defined in src/base/partialPlexObject.ts:264

audioStreams

audioStreams(): AudioStream[]
Returns all audio streams from all parts.

Returns AudioStream[]
Inherited from Playable.audioStreams
- Defined in src/base/playable.ts:172

copyToUser

copyToUser(user: string | number | MyPlexUser): Promise<Playlist>
Copy the current playlist contents into another user's account on this server.
Parameters
- user: string | number | MyPlexUser
Returns Promise<Playlist>
- Defined in src/playlist.ts:207

createPlayQueue

createPlayQueue(options?: CreatePlayQueueOptions): Promise<PlayQueue>
Returns a new PlayQueue from this media item.
Parameters
- options: CreatePlayQueueOptions = {}
  Options for creating the PlayQueue
Returns Promise<PlayQueue>
New PlayQueue instance
Inherited from Playable.createPlayQueue
- Defined in src/base/playable.ts:114

defaultAdvanced

defaultAdvanced(): Promise<void>
Returns Promise<void>
Inherited from Playable.defaultAdvanced
- Defined in src/base/partialPlexObject.ts:224

delete

delete(): Promise<void>
Delete the playlist.

Returns Promise<void>
Overrides Playable.delete
- Defined in src/playlist.ts:489

download

download(options?: DownloadOptions): AsyncGenerator<MediaDownload, void>
Stream original media files; consume each body before advancing the iterator.
Parameters
- options: DownloadOptions = {}
Returns AsyncGenerator<MediaDownload, void>
Inherited from Playable.download
- Defined in src/base/partialPlexObject.ts:101

edit

edit(changes: Record<string, string | number>): Promise<void>
Update playlist metadata directly; playlists do not use section-wide edit endpoints.
Parameters
- changes: Record<string, string | number>
Returns Promise<void>
Overrides Playable.edit
- Defined in src/playlist.ts:199

editAdvanced

editAdvanced(values: Record<string, SettingValue>): Promise<void>
Validate values against Plex's advertised preferences before submitting them.
Parameters
- values: Record<string, SettingValue>
Returns Promise<void>
Inherited from Playable.editAdvanced
- Defined in src/base/partialPlexObject.ts:208

editContentRating

editContentRating(contentRating: string): Promise<void>
Set the content rating (e.g. PG-13, R, TV-MA).
Parameters
- contentRating: string
Returns Promise<void>
Inherited from Playable.editContentRating
- Defined in src/base/partialPlexObject.ts:529

editFields

editFields(
fields: MetadataFieldUpdates,
options?: MetadataEditOptions,
): Promise<void>
Edit several typed metadata fields in one request.
Parameters
- fields: MetadataFieldUpdates
- options: MetadataEditOptions = {}
Returns Promise<void>
Inherited from Playable.editFields
- Defined in src/base/partialPlexObject.ts:173

editOriginallyAvailableAt

editOriginallyAvailableAt(date: string): Promise<void>
Set the originally available at date (release date).
Parameters
- date: string
Returns Promise<void>
Inherited from Playable.editOriginallyAvailableAt
- Defined in src/base/partialPlexObject.ts:539

editSortTitle

editSortTitle(sortTitle: string): Promise<void>
Set the sort title.
Parameters
- sortTitle: string
Returns Promise<void>
Inherited from Playable.editSortTitle
- Defined in src/base/partialPlexObject.ts:519

editStudio

editStudio(studio: string): Promise<void>
Set the studio.
Parameters
- studio: string
Returns Promise<void>
Inherited from Playable.editStudio
- Defined in src/base/partialPlexObject.ts:534

editSummary

editSummary(summary: string): Promise<void>
Set the summary.
Parameters
- summary: string
Returns Promise<void>
Inherited from Playable.editSummary
- Defined in src/base/partialPlexObject.ts:524

editTags

editTags(__namedParameters: MetadataTagEditOptions): Promise<void>
Edit a server-defined tag, such as genre, collection, country, director, or mood.
Parameters
- __namedParameters: MetadataTagEditOptions
Returns Promise<void>
Inherited from Playable.editTags
- Defined in src/base/partialPlexObject.ts:141

editTitle

editTitle(title: string): Promise<void>
Set the title.
Parameters
- title: string
Returns Promise<void>
Inherited from Playable.editTitle
- Defined in src/base/partialPlexObject.ts:514

extras

extras(): Promise<Extra[]>
Returns Promise<Extra[]>
Inherited from Playable.extras
- Defined in src/base/partialPlexObject.ts:89

filters

filters(): URLSearchParams | undefined
Ordered query parameters defining this smart collection or playlist.

Returns URLSearchParams | undefined
- Defined in src/playlist.ts:321

fixMatch

fixMatch(
    options?: {
        agent?: string;
        auto?: boolean;
        searchResult?: SearchResult;
    },
): Promise<void>
Use match result to update show metadata.
Parameters
- options: { agent?: string; auto?: boolean; searchResult?: SearchResult } = {}
  Match options.
Returns Promise<void>
Inherited from Playable.fixMatch
- Defined in src/base/partialPlexObject.ts:298

getStreamURL

getStreamURL(params?: Readonly<StreamUrlOptions>): string
Returns a stream URL that can be used for playback.
Parameters
- params: Readonly<StreamUrlOptions> = {}
  Additional URL parameters for transcoding options.
Returns string
Inherited from Playable.getStreamURL
- Defined in src/base/playable.ts:122

getWebURL

getWebURL(__namedParameters?: { base?: string }): string
Parameters
- __namedParameters: { base?: string } = {}
Returns string
Overrides Playable.getWebURL
- Defined in src/playlist.ts:329

history

history(options?: Omit<HistoryOptions, "ratingKey">): Promise<HistoryResult[]>
Get Play History for a media item.
Parameters
- options: Omit<HistoryOptions, "ratingKey"> = {}
  Filter and paging options.
Returns Promise<HistoryResult[]>
Inherited from Playable.history
- Defined in src/base/partialPlexObject.ts:405

hubs

hubs(): Promise<Hub[]>
Returns Promise<Hub[]>
Inherited from Playable.hubs
- Defined in src/base/partialPlexObject.ts:78

isChildOf

isChildOf(cls: new (...args: any[]) => PlexObject): boolean
Returns true if this object was built from a parent of the given class.
Parameters
- cls: new (...args: any[]) => PlexObject
Returns boolean
Inherited from Playable.isChildOf
- Defined in src/base/plexObject.ts:61

isLocked

isLocked(name: string): boolean
Whether a loaded field is locked against metadata refreshes.
Parameters
- name: string
Returns boolean
Inherited from Playable.isLocked
- Defined in src/base/partialPlexObject.ts:181

item

item(title: string): Promise<PlaylistContent | null>
Parameters
- title: string
Returns Promise<PlaylistContent | null>
the item in the playlist that matches the specified title.
- Defined in src/playlist.ts:380

items

items<T extends PlaylistContent = PlaylistContent>(): Promise<T[]>
Type Parameters
- T extends PlaylistContent = PlaylistContent
Returns Promise<T[]>
- Defined in src/playlist.ts:386
items<T extends PlaylistItemLibtype>(
options: PlaylistItemsOptions<T>,
): Promise<SearchClassForLibtype<T>[]>
Type Parameters
- T extends PlaylistItemLibtype
Parameters
- options: PlaylistItemsOptions<T>
Returns Promise<SearchClassForLibtype<T>[]>
- Defined in src/playlist.ts:387

iterParts

iterParts(): MediaPart[]
Returns all MediaPart objects across all Media entries.

Returns MediaPart[]
Inherited from Playable.iterParts
- Defined in src/base/playable.ts:158

lyricStreams

lyricStreams(): LyricStream[]
Returns LyricStream[]
Inherited from Playable.lyricStreams
- Defined in src/base/playable.ts:188

markPlayed

markPlayed(): Promise<void>
Returns Promise<void>
Inherited from Playable.markPlayed
- Defined in src/base/playable.ts:90

markUnplayed

markUnplayed(): Promise<void>
Returns Promise<void>
Inherited from Playable.markUnplayed
- Defined in src/base/playable.ts:97

matches

matches(
    options?: {
        agent?: string;
        language?: string;
        title?: string;
        year?: string;
    },
): Promise<SearchResult[]>
Parameters
- options: { agent?: string; language?: string; title?: string; year?: string } = {}
  Match options.
  
  Examples:
  
  video.matches()
  
  video.matches({ title: "something", year: "2020" })
  
  video.matches({ title: "something" })
  
  video.matches({ year: "2020" })
  
  video.matches({ title: "something", year: "" })
  
  video.matches({ title: "", year: "2020" })
  
  video.matches({ title: "", year: "" })
  
  The default behaviour in Plex Web = no params in plexapi
  
  Both title and year specified by user
  
  Year automatically filled in
  
  Title automatically filled in
  
  Explicitly searches for title with blank year
  
  Explicitly searches for blank title with year
  
  I don't know what the user is thinking... return the same result as 1
  
  For 2 to 7, the agent and language is automatically filled in
Returns Promise<SearchResult[]>
Inherited from Playable.matches
- Defined in src/base/partialPlexObject.ts:344

merge

merge(ratingKeys: readonly (string | number)[]): Promise<void>
Parameters
- ratingKeys: readonly (string | number)[]
Returns Promise<void>
Inherited from Playable.merge
- Defined in src/base/partialPlexObject.ts:238

moveItem

moveItem(
item: PlaylistContent,
__namedParameters?: MovePlaylistItemOptions,
): Promise<Playlist>
Move an item within a regular playlist.
Parameters
- item: PlaylistContent
- __namedParameters: MovePlaylistItemOptions = {}
Returns Promise<Playlist>
- Defined in src/playlist.ts:451

play

play(client: PlexClient, options?: PlayMediaOptions): Promise<void>
Parameters
- client: PlexClient
- options: PlayMediaOptions = {}
Returns Promise<void>
Inherited from Playable.play
- Defined in src/base/playable.ts:104

preference

preference(id: string): Promise<Preferences>
Parameters
- id: string
Returns Promise<Preferences>
Inherited from Playable.preference
- Defined in src/base/partialPlexObject.ts:199

preferences

preferences(): Promise<Preferences[]>
Returns Promise<Preferences[]>
Inherited from Playable.preferences
- Defined in src/base/partialPlexObject.ts:188

rate

rate(rating: number | null): Promise<void>
Set a personal rating from 0 to 10, or clear it with null.
Parameters
- rating: number | null
Returns Promise<void>
Inherited from Playable.rate
- Defined in src/base/partialPlexObject.ts:55

refresh

refresh(): Promise<void>
Refreshing a Library or individual item causes the metadata for the item to be refreshed, even if it already has metadata. You can think of refreshing as "update metadata for the requested item even if it already has some". You should refresh a Library or individual item if:

Returns Promise<void>
Inherited from Playable.refresh
- Defined in src/base/plexObject.ts:51

reload

reload(ekey?: string, args?: Record<string, number | boolean>): Promise<void>
load full data / reload the data for this object from this.key.
Parameters
- Optionalekey: string
- Optionalargs: Record<string, number | boolean>
Returns Promise<void>
Inherited from Playable.reload
- Defined in src/base/partialPlexObject.ts:272

removeCollection

removeCollection(collections: string[]): Promise<void>
Remove a collection(s).
Parameters
- collections: string[]
Returns Promise<void>
Inherited from Playable.removeCollection
- Defined in src/base/partialPlexObject.ts:444

removeGenre

removeGenre(genres: string[]): Promise<void>
Remove a genre(s).
Parameters
- genres: string[]
Returns Promise<void>
Inherited from Playable.removeGenre
- Defined in src/base/partialPlexObject.ts:464

removeItems

removeItems(items: PlaylistContent[]): Promise<Playlist>
Remove an item from a playlist.
Parameters
- items: PlaylistContent[]
Returns Promise<Playlist>
- Defined in src/playlist.ts:434

removeLabel

removeLabel(labels: string[]): Promise<void>
Remove a label(s).
Parameters
- labels: string[]
Returns Promise<void>
Inherited from Playable.removeLabel
- Defined in src/base/partialPlexObject.ts:454

section

section(): Promise<Section>
Return the library section associated with a smart playlist.

Returns Promise<Section>
Overrides Playable.section
- Defined in src/playlist.ts:352

split

split(): Promise<void>
Returns Promise<void>
Inherited from Playable.split
- Defined in src/base/partialPlexObject.ts:234

subtitleStreams

subtitleStreams(): SubtitleStream[]
Returns all subtitle streams from all parts.

Returns SubtitleStream[]
Inherited from Playable.subtitleStreams
- Defined in src/base/playable.ts:179

unmatch

unmatch(): Promise<unknown>
Unmatches metadata match from object.

Returns Promise<unknown>
Inherited from Playable.unmatch
- Defined in src/base/partialPlexObject.ts:396

updateFilters

updateFilters(options?: SmartPlaylistSearchOptions): Promise<Playlist>
Replace the validated search behind a smart playlist.
Parameters
- options: SmartPlaylistSearchOptions = {}
Returns Promise<Playlist>
- Defined in src/playlist.ts:470

updateProgress

updateProgress(__namedParameters: UpdateProgressOptions): Promise<void>
Set the watched progress for this item. Plex ignores progress of 60 seconds or less, use Playable.markUnplayed to clear progress instead.
Parameters
- __namedParameters: UpdateProgressOptions
Returns Promise<void>
Inherited from Playable.updateProgress
- Defined in src/base/playable.ts:207

updateTimeline

updateTimeline(__namedParameters: UpdateTimelineOptions): Promise<void>
Report playback progress for this item the way a player would. Duration defaults to the item's own duration.
Parameters
- __namedParameters: UpdateTimelineOptions
Returns Promise<void>
Inherited from Playable.updateTimeline
- Defined in src/base/playable.ts:224

videoStreams

videoStreams(): VideoStream[]
Returns all video streams from every media part.

Returns VideoStream[]
Inherited from Playable.videoStreams
- Defined in src/base/playable.ts:184

`Static`create

create(
    server: PlexServer,
    title: string,
    options: CreatePlaylistOptions,
): Promise<Playlist>
Parameters
- server: PlexServer
- title: string
- options: CreatePlaylistOptions
Returns Promise<Playlist>
- Defined in src/playlist.ts:134

`Static`fromM3U

fromM3U(
server: PlexServer,
__namedParameters: { path: string; section: MusicSection; title: string },
): Promise<Playlist>
Import an M3U file already accessible on the Plex server's filesystem.
Parameters
- server: PlexServer
- __namedParameters: { path: string; section: MusicSection; title: string }
Returns Promise<Playlist>
- Defined in src/playlist.ts:143

`Static`update

update(
    server: PlexServer,
    ratingKey: string,
    options: UpdatePlaylistOptions,
): Promise<void>
Update a playlist's metadata by ratingKey without fetching the full playlist first.
Parameters
- server: PlexServer
  The Plex server instance
- ratingKey: string
  The playlist's ratingKey
- options: UpdatePlaylistOptions
  Fields to update (title and/or summary)
Returns Promise<void>
Example
```
await Playlist.update(server, '12345', {
  title: 'My Updated Playlist',
  summary: 'A new description'
});
```
- Defined in src/playlist.ts:177

Class Playlist

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Playlist

Properties

_INCLUDES

OptionaladdedAt

OptionalallowSync

Optionalcentroid

composite

Optionalcontent

Optionalduration

OptionaldurationInSeconds

fields

guid

Optionalicon

key

leafCount

OptionallibrarySectionID

OptionallibrarySectionKey

OptionallibrarySectionTitle

Optionallive

Optional Readonlyparent

Optionalplayer

players

OptionalplaylistItemID

playlistType

OptionalplayQueueItemID

radio

OptionalratingKey

Readonlyserver

Optionalsession

OptionalsessionKey

sessions

smart

summary

Optionaltitle

OptionaltranscodeSession

transcodeSessions

Optionaltype

TYPE

OptionalupdatedAt

Optionaluser

usernames

OptionalviewedAt

Optionalyear

StaticTAG

StaticTYPE

Accessors

artwork

Returns ArtworkManager

hasPreviewThumbnails

Returns boolean

hasVoiceActivity

Returns boolean

isAudio

Returns boolean

isFullObject

Returns boolean

isPhoto

Returns boolean

isPlayed

Returns boolean

isVideo

Returns boolean

metadataDirectory

Returns string | undefined

metadataType

Returns PlaylistMetadataType

thumb

Returns string

Methods

_edit

`Optional`addedAt

`Optional`allowSync

`Optional`centroid

`Optional`content

`Optional`duration

`Optional`durationInSeconds

`Optional`icon

`Optional`librarySectionID

`Optional`librarySectionKey

`Optional`librarySectionTitle

`Optional`live

`Optional` `Readonly`parent

`Optional`player

`Optional`playlistItemID

`Optional`playQueueItemID

`Optional`ratingKey

`Readonly`server

`Optional`session

`Optional`sessionKey

`Optional`title

`Optional`transcodeSession

`Optional`type

`Optional`updatedAt

`Optional`user

`Optional`viewedAt

`Optional`year

`Static`TAG

`Static`TYPE