Class LibrarySection<SType>Abstract

constructor

• new LibrarySection<SType = SectionType>(
      server: PlexServer,
      data: any,
      initpath?: string,
      parent?: PlexObject,
  ): LibrarySection<SType>

  Type Parameters

  • SType = SectionType

  Parameters

  • server: PlexServer
  • data: any
  • Optionalinitpath: string
  • Optionalparent: PlexObject

  Returns LibrarySection<SType>

Optional_fieldTypes

Optional_filterTypes

agent

allowSync

art

composite

CONTENT_TYPE

createdAt

filters

language

locations

refreshing

scannedAt

scanner

ReadonlySECTION_TYPE

thumb

title

type

updatedAt

uuid

StaticALLOWED_FILTERS

StaticALLOWED_SORT

StaticBOOLEAN_FILTERS

addLocations

• addLocations(locations: string | string[]): Promise<Section>

  Add new file paths to the library section.

  Parameters

  • locations: string | string[]

    One or more file paths to add.

  Returns Promise<Section>

agents

• agents(): Promise<Agent[]>

  Returns Promise<Agent[]>

all

• all(sort?: string): Promise<SType[]>

  Parameters

  • sort: string = ''

  Returns Promise<SType[]>

analyze

• analyze(): Promise<void>

  Run an analysis on all of the items in this library section. See :func:~plexapi.base.PlexPartialObject.analyze for more details.

  Returns Promise<void>

cancelUpdate

• cancelUpdate(): Promise<void>

  Cancel update of this Library Section.

  Returns Promise<void>

collection

• collection(title: string): Promise<Collections<SType>>

  Returns the collection with the exact title.

  Parameters

  • title: string

  Returns Promise<Collections<SType>>

collections

• collections(
      args?: Record<string, number | string | boolean>,
  ): Promise<Collections<SType>[]>

  Parameters

  • args: Record<string, number | string | boolean> = {}

  Returns Promise<Collections<SType>[]>

common

• common(items: EditableLibraryItem | EditableLibraryItem[]): Promise<Common>

  Returns fields common to all provided items.

  Parameters

  • items: EditableLibraryItem | EditableLibraryItem[]

  Returns Promise<Common>

continueWatching

• continueWatching(): Promise<LibrarySearchItem[]>

  Returns items from this library section's Continue Watching hub.

  Returns Promise<LibrarySearchItem[]>

createCollection

• createCollection<T extends RatingKeyItem>(
      title: string,
      items: T[],
  ): Promise<Collections<T>>

  Create a regular collection in this library section.

  Type Parameters

  • T extends RatingKeyItem

  Parameters

  • title: string
  • items: T[]

  Returns Promise<Collections<T>>

createPlaylist

• createPlaylist(
      title: string,
      options:
          | CreateRegularPlaylistOptions
          | Omit<CreateSmartPlaylistOptions, "section">,
  ): Promise<Playlist>

  Create a regular or smart playlist scoped to this library section.

  Parameters

  • title: string
  • options: CreateRegularPlaylistOptions | Omit<CreateSmartPlaylistOptions, "section">

  Returns Promise<Playlist>

defaultAdvanced

• defaultAdvanced(): Promise<Section>

  Reset this library section's advanced preference settings to their defaults.

  Returns Promise<Section>

delete

• delete(): Promise<void>

  Delete a library section.

  Returns Promise<void>

deleteMediaPreviews

• deleteMediaPreviews(): Promise<void>

  Delete the preview thumbnails for items in this library. This cannot be undone. Recreating media preview files can take hours or even days.

  Returns Promise<void>

edit

• edit(kwargs: Record<string, string>): Promise<Section>

  Edit a library

  Parameters

  • kwargs: Record<string, string>

    object of settings to edit

  Returns Promise<Section>

editAdvanced

• editAdvanced(changes: SectionAdvancedSettings): Promise<Section>

  Edit this library section's advanced preference settings.

  Parameters

  • changes: SectionAdvancedSettings

  Returns Promise<Section>

emptyTrash

• emptyTrash(): Promise<void>

  If a section has items in the Trash, use this option to empty the Trash

  Returns Promise<void>

fieldTypes

• fieldTypes(): Promise<FilteringFieldType[]>

  Returns Promise<FilteringFieldType[]>

filterTypes

• filterTypes(): Promise<FilteringType[]>

  Returns Promise<FilteringType[]>

firstCharacter

• firstCharacter(): Promise<FirstCharacter[]>

  Returns the list of first characters for items in this library section. This is the data used to populate the alphabet bar in the Plex UI.

  Returns Promise<FirstCharacter[]>

folders

• folders(): Promise<Folder[]>

  Returns a list of available Folders for this library section.

  Returns Promise<Folder[]>

genres

• genres(): Promise<FilterChoice[]>

  Returns Promise<FilterChoice[]>

get

• get(title: string): Promise<SType>

  Parameters

  • title: string

    Title of the item to return.

  Returns Promise<SType>

  the media item with the specified title.

getFieldType

• getFieldType(fieldType: string): Promise<FilteringFieldType>

  Parameters

  • fieldType: string

    The data type for the field (tag, integer, string, boolean, date, subtitleLanguage, audioLanguage, resolution).

  Returns Promise<FilteringFieldType>

getFilterType

• getFilterType(
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<FilteringType>

  Parameters

  • libtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem" = ...

  Returns Promise<FilteringType>

getGuid

• getGuid(guid: string): Promise<SType>

  Returns the media item with the specified external IMDB, TMDB, or TVDB ID. Note: This search uses a PlexAPI operator so performance may be slow. All items from the entire Plex library need to be retrieved for each guid search. It is recommended to create your own lookup dictionary if you are searching for a lot of external guids.

  Parameters

  • guid: string

    The external guid of the item to return. Examples: IMDB imdb://tt0944947, TMDB tmdb://1399, TVDB tvdb://121361.

    Example:

    	.. code-block:: python
    
    			# This will retrieve all items in the entire library 3 times
    			result1 = library.getGuid('imdb://tt0944947')
    			result2 = library.getGuid('tmdb://1399')
    			result3 = library.getGuid('tvdb://121361')
    
    			# This will only retrieve all items in the library once to create a lookup dictionary
    			guidLookup = {guid.id: item for item in library.all() for guid in item.guids}
    			result1 = guidLookup['imdb://tt0944947']
    			result2 = guidLookup['tmdb://1399']
    			result3 = guidLookup['tvdb://121361']
    

  Returns Promise<SType>

getWebURL

• getWebURL(base?: { base?: string; key?: string; tab?: string }): string

  Returns the Plex Web URL for the library.

  Parameters

  • base: { base?: string; key?: string; tab?: string } = {}

    The base URL before the fragment (#!). Default is https://app.plex.tv/desktop.

    • Optionalbase?: string

      The base URL before the fragment (#!). Default is https://app.plex.tv/desktop.

    • Optionalkey?: string

      A hub key.

    • Optionaltab?: string

      The library tab (recommended, library, collections, playlists, timeline).

  Returns string

history

• history(
      __namedParameters?: LibrarySectionHistoryOptions,
  ): Promise<HistoryResult[]>

  Get watched history for this library section.

  Parameters

  • __namedParameters: LibrarySectionHistoryOptions = {}

  Returns Promise<HistoryResult[]>

hubs

• hubs(): Promise<Hub[]>

  Returns Promise<Hub[]>

hubSearch

• hubSearch(query: string, __namedParameters?: HubSearchOptions): Promise<Hub[]>

  Returns section-scoped hub search results.

  Parameters

  • query: string
  • __namedParameters: HubSearchOptions = {}

  Returns Promise<Hub[]>

listFields

• listFields(
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<FilteringField[]>

  Returns a list of available FilteringField for a specified libtype. This is the list of options in the custom filter dropdown menu

  Parameters

  • libtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem" = ...

  Returns Promise<FilteringField[]>

listFilterChoices

• listFilterChoices(
      field: string | FilteringFilter,
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<FilterChoice[]>

  Returns the available values for a custom filter field.

  Parameters

  • field: string | FilteringFilter
  • Optionallibtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem"

  Returns Promise<FilterChoice[]>

listFilters

• listFilters(
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<FilteringFilter[]>

  Parameters

  • Optionallibtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem"

    The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

  Returns Promise<FilteringFilter[]>

  Example

  const availableFilters = (await library.listFilters()).map(f => f.filter)
  Copy

listOperators

• listOperators(fieldType: string): Promise<FilteringOperator[]>

  Parameters

  • fieldType: string

    The data type for the field (tag, integer, string, boolean, date, subtitleLanguage, audioLanguage, resolution).

  Returns Promise<FilteringOperator[]>

listSorts

• listSorts(
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<FilteringSort[]>

  Returns a list of available sorting fields for the specified libtype.

  Parameters

  • Optionallibtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem"

  Returns Promise<FilteringSort[]>

lockAllField

• lockAllField(
      field: string,
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<LibrarySection<SType>>

  Lock a field for all items of a libtype in this library.

  Parameters

  • field: string
  • libtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem" = ...

  Returns Promise<LibrarySection<SType>>

managedHubs

• managedHubs(): Promise<ManagedHub[]>

  Returns the managed recommendation hubs for this library section.

  Returns Promise<ManagedHub[]>

multiEdit

• multiEdit(
      items: EditableLibraryItem | EditableLibraryItem[],
      changes: Record<string, string | number | boolean>,
  ): Promise<LibrarySection<SType>>

  Edit multiple items at once using Plex field keys.

  Parameters

  • items: EditableLibraryItem | EditableLibraryItem[]
  • changes: Record<string, string | number | boolean>

  Returns Promise<LibrarySection<SType>>

onDeck

• onDeck(): Promise<SType[]>

  Returns a list of items currently on deck (in progress) for this library section.

  Returns Promise<SType[]>

playlist

• playlist(title: string): Promise<Playlist>

  Returns the playlist with the exact title.

  Parameters

  • title: string

  Returns Promise<Playlist>

playlists

• playlists(args?: PlaylistSearchOptions): Promise<Playlist[]>

  Returns a list of playlists from this library section.

  Parameters

  • args: PlaylistSearchOptions = {}

  Returns Promise<Playlist[]>

recentlyAdded

• recentlyAdded(maxResults?: number): Promise<SType[]>

  Returns a list of recently added items for this library section.

  Parameters

  • OptionalmaxResults: number

    Maximum number of results to return. Default 50.

  Returns Promise<SType[]>

• recentlyAdded<
      T extends
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  >(
      maxResults: number,
      libtype: T,
  ): Promise<SearchClassForLibtype<T>[]>

  Returns a list of recently added items for this library section.

  Type Parameters

  • T extends
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem"

  Parameters

  • maxResults: number

    Maximum number of results to return. Default 50.

  • libtype: T

  Returns Promise<SearchClassForLibtype<T>[]>

refresh

• refresh(): Promise<void>

  Forces a download of fresh media information from the internet. This can take a long time. Any locked fields are not modified.

  Returns Promise<void>

removeLocations

• removeLocations(locations: string | string[]): Promise<Section>

  Remove file paths from the library section.

  Parameters

  • locations: string | string[]

    One or more file paths to remove.

  Returns Promise<Section>

resetManagedHubs

• resetManagedHubs(): Promise<void>

  Reset managed hub customizations for this library section.

  Returns Promise<void>

search

• search<C = SType>(args?: Partial<SearchArgs>, Cls?: Class<C>): Promise<C[]>

  Search the library. The http requests will be batched in container_size. If you are only looking for the first results, it would be wise to set the maxresults option to that amount so the search doesn't iterate over all results on the server.

  Example: "studio=Comedy%20Central" or "year=1999" "title=Kung Fu" all work. Other items such as actor= seem to work, but require you already know the id of the actor. TLDR: This is untested but seems to work. Use library section search when you can.

  Type Parameters

  • C = SType

  Parameters

  • args: Partial<SearchArgs> = {}

    Search using a number of different attributes

  • OptionalCls: Class<C>

  Returns Promise<C[]>

settings

• settings(): Promise<Setting[]>

  Returns the advanced preference settings for this library section.

  Returns Promise<Setting[]>

timeline

• timeline(): Promise<LibraryTimeline>

  Returns the current library section timeline status.

  Returns Promise<LibraryTimeline>

totalDuration

• totalDuration(): Promise<number>

  Returns the total duration of all items in the library in milliseconds, or null if unavailable.

  Returns Promise<number>

totalSize

• totalSize(): Promise<number>

  Returns the total number of items in the library, excluding collections.

  Returns Promise<number>

totalStorage

• totalStorage(): Promise<number>

  Returns the total storage size of all items in the library in bytes, or null if unavailable.

  Returns Promise<number>

totalViewSize

• totalViewSize(
      options?: { includeCollections?: boolean; libtype?: string },
  ): Promise<number>

  Returns the total number of items in the library. Queries the library without fetching any items to get the total count.

  Parameters

  • Optionaloptions: { includeCollections?: boolean; libtype?: string }

    • OptionalincludeCollections?: boolean

      Whether to include collections in the count. Default true.

    • Optionallibtype?: string

      Filter by a specific library type (movie, show, episode, etc.).

  Returns Promise<number>

unlockAllField

• unlockAllField(
      field: string,
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem",
  ): Promise<LibrarySection<SType>>

  Unlock a field for all items of a libtype in this library.

  Parameters

  • field: string
  • libtype:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem" = ...

  Returns Promise<LibrarySection<SType>>

update

• update(): Promise<void>

  Scan this section for new media.

  Returns Promise<void>