Class Library

Index

Constructors

Properties

allowSync art content directories identifier mediaTagPrefix mediaTagVersion size title1 title2 key

Methods

add all cancelUpdate cleanBundles deleteMediaPreviews emptyTrash history hubs onDeck optimize recentlyAdded refresh search section sectionByID sections tags update

Constructors

constructor

new Library(server: PlexServer, data: LibraryRootResponse): Library
Parameters
- server: PlexServer
- data: LibraryRootResponse
Returns Library
- Defined in src/library.ts:274

Properties

allowSync

allowSync: boolean

Whether sync is allowed for the root library endpoint.

art

art: string

Root library artwork path.

content

content: string

Root library content type.

directories

directories: Directory[]

Root library directories returned by Plex.

identifier

identifier: string

Unknown ('com.plexapp.plugins.library')

mediaTagPrefix

mediaTagPrefix: string

Unknown (/system/bundle/media/flags/)

mediaTagVersion

mediaTagVersion: number

Version for media tag assets.

size

size: number

Number of root library entries returned by Plex.

title1

title1: string

'Plex Library' (not sure how useful this is)

title2

title2: string

Second title (this is blank on my setup)

`Static`key

key: string = '/library'

Methods

add

add<T extends LibrarySectionCreateType>(
options: LibraryAddOptions<T>,
): Promise<SectionForCreateType<T>>

Creates a library section and returns the newly created typed section.

Pass server-visible paths in locations. Preference keys should be bare Plex setting ids; this method encodes them as prefs[...].

Type Parameters

T extends LibrarySectionCreateType

Parameters

options: LibraryAddOptions<T>

Returns Promise<SectionForCreateType<T>>

Example

const section = await library.add({
  name: 'Movies',
  type: 'movie',
  agent: 'tv.plex.agents.movie',
  scanner: 'Plex Movie',
  locations: ['/data/Movies', '/data/Archived Movies'],
  preferences: { enableBIFGeneration: false },
})

Parameters: name (str): Name of the library agent (str): Example com.plexapp.agents.imdb type (str): movie, show, # check me location (str): /path/to/files language (str): Two letter language fx en kwargs (dict): Advanced options should be passed as a dict. where the id is the key.

Photo Preferences

* **agent** (str): com.plexapp.agents.none
* **enableAutoPhotoTags** (bool): Tag photos. Default value false.
* **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
* **includeInGlobal** (bool): Include in dashboard. Default value true.
* **scanner** (str): Plex Photo Scanner

Movie Preferences

* **agent** (str): com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb
* **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
* **enableCinemaTrailers** (bool): Enable Cinema Trailers. Default value true.
* **includeInGlobal** (bool): Include in dashboard. Default value true.
* **scanner** (str): Plex Movie Scanner, Plex Video Files Scanner

IMDB Movie Options (com.plexapp.agents.imdb)

* **title** (bool): Localized titles. Default value false.
* **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
* **only_trailers** (bool): Skip extras which aren't trailers. Default value false.
* **redband** (bool): Use red band (restricted audiences) trailers when available. Default value false.
* **native_subs** (bool): Include extras with subtitles in Library language. Default value false.
* **cast_list** (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
* **ratings** (int): Ratings Source, Default value 0 Possible options:
  0:Rotten Tomatoes, 1:IMDb, 2:The Movie Database.
* **summary** (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
* **country** (int): Default value 46 Possible options 0:Argentina, 1:Australia, 2:Austria,
  3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica,
  11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador,
  16:France, 17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland,
  22:Italy, 23:Jamaica, 24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands,
  29:New Zealand, 30:Nicaragua, 31:Panama, 32:Paraguay, 33:Peru, 34:Portugal,
  35:Peoples Republic of China, 36:Puerto Rico, 37:Russia, 38:Singapore, 39:South Africa,
  40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad, 45:United Kingdom,
  46:United States, 47:Uruguay, 48:Venezuela.
* **collections** (bool): Use collection info from The Movie Database. Default value false.
* **localart** (bool): Prefer artwork based on library language. Default value true.
* **adult** (bool): Include adult content. Default value false.
* **usage** (bool): Send anonymous usage data to Plex. Default value true.

TheMovieDB Movie Options (com.plexapp.agents.themoviedb)

* **collections** (bool): Use collection info from The Movie Database. Default value false.
* **localart** (bool): Prefer artwork based on library language. Default value true.
* **adult** (bool): Include adult content. Default value false.
* **country** (int): Country (used for release date and content rating). Default value 47 Possible
  options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada,
  9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador,
  16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland,
  23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands,
  30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa, 41:Spain,
  42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States, 48:Uruguay,
  49:Venezuela.

Show Preferences

* **agent** (str): com.plexapp.agents.none, com.plexapp.agents.thetvdb, com.plexapp.agents.themoviedb
* **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
* **episodeSort** (int): Episode order. Default -1 Possible options: 0:Oldest first, 1:Newest first.
* **flattenSeasons** (int): Seasons. Default value 0 Possible options: 0:Show,1:Hide.
* **includeInGlobal** (bool): Include in dashboard. Default value true.
* **scanner** (str): Plex Series Scanner

TheTVDB Show Options (com.plexapp.agents.thetvdb)

* **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
* **native_subs** (bool): Include extras with subtitles in Library language. Default value false.

TheMovieDB Show Options (com.plexapp.agents.themoviedb)

* **collections** (bool): Use collection info from The Movie Database. Default value false.
* **localart** (bool): Prefer artwork based on library language. Default value true.
* **adult** (bool): Include adult content. Default value false.
* **country** (int): Country (used for release date and content rating). Default value 47 options
  0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada, 9:Chile,
  10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador,
  16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland,
  23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands,
  30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa,
  41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States,
  48:Uruguay, 49:Venezuela.

Other Video Preferences

* **agent** (str): com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb
* **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
* **enableCinemaTrailers** (bool): Enable Cinema Trailers. Default value true.
* **includeInGlobal** (bool): Include in dashboard. Default value true.
* **scanner** (str): Plex Movie Scanner, Plex Video Files Scanner

IMDB Other Video Options (com.plexapp.agents.imdb)

* **title** (bool): Localized titles. Default value false.
* **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
* **only_trailers** (bool): Skip extras which aren't trailers. Default value false.
* **redband** (bool): Use red band (restricted audiences) trailers when available. Default value false.
* **native_subs** (bool): Include extras with subtitles in Library language. Default value false.
* **cast_list** (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
* **ratings** (int): Ratings Source Default value 0 Possible options:
  0:Rotten Tomatoes,1:IMDb,2:The Movie Database.
* **summary** (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
* **country** (int): Country: Default value 46 Possible options: 0:Argentina, 1:Australia, 2:Austria,
  3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica,
  11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador, 16:France,
  17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland, 22:Italy, 23:Jamaica,
  24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands, 29:New Zealand, 30:Nicaragua,
  31:Panama, 32:Paraguay, 33:Peru, 34:Portugal, 35:Peoples Republic of China, 36:Puerto Rico,
  37:Russia, 38:Singapore, 39:South Africa, 40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad,
  45:United Kingdom, 46:United States, 47:Uruguay, 48:Venezuela.
* **collections** (bool): Use collection info from The Movie Database. Default value false.
* **localart** (bool): Prefer artwork based on library language. Default value true.
* **adult** (bool): Include adult content. Default value false.
* **usage** (bool): Send anonymous usage data to Plex. Default value true.

TheMovieDB Other Video Options (com.plexapp.agents.themoviedb)

* **collections** (bool): Use collection info from The Movie Database. Default value false.
* **localart** (bool): Prefer artwork based on library language. Default value true.
* **adult** (bool): Include adult content. Default value false.
* **country** (int): Country (used for release date and content rating). Default
  value 47 Possible options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize,
  6:Bolivia, 7:Brazil, 8:Canada, 9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic,
  13:Denmark, 14:Dominican Republic, 15:Ecuador, 16:El Salvador, 17:France, 18:Germany,
  19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland, 23:Italy, 24:Jamaica,
  25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands, 30:New Zealand,
  31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore,
  40:South Africa, 41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad,
  46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.

all

all<
    T extends
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem",
>(
    options: Omit<Partial<SearchArgs>, "maxresults" | "libtype"> & {
        libtype?:
            | "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 media from every library section.

Use the options object for sorting, paging, and type-specific results. When libtype is provided, each section is asked for that Plex item type and the returned array is typed to the matching model.
Type Parameters
- T extends
      | "track"
      | "artist"
      | "album"
      | "movie"
      | "show"
      | "season"
      | "episode"
      | "trailer"
      | "comic"
      | "person"
      | "picture"
      | "clip"
      | "photo"
      | "photoalbum"
      | "playlist"
      | "playlistFolder"
      | "collection"
      | "optimizedVersion"
      | "userPlaylistItem"
Parameters
- options: Omit<Partial<SearchArgs>, "maxresults" | "libtype"> & {
      libtype?:
          | "track"
          | "artist"
          | "album"
          | "movie"
          | "show"
          | "season"
          | "episode"
          | "trailer"
          | "comic"
          | "person"
          | "picture"
          | "clip"
          | "photo"
          | "photoalbum"
          | "playlist"
          | "playlistFolder"
          | "collection"
          | "optimizedVersion"
          | "userPlaylistItem";
      maxResults?: number;
  } & { libtype: T }
  - Optionallibtype?:
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem"
    
    Return a specific library item type instead of the section default.
    
    Passing this narrows section.all({ libtype }) to the matching model type.
  - OptionalmaxResults?: number
    
    Maximum number of items to return.
    
    Plex may ignore the container size hint on some endpoints, so this method also applies the limit locally before returning.
  - libtype: T
Returns Promise<SearchClassForLibtype<T>[]>
Example
```
const everything = await library.all()
const movies = await library.all({ libtype: 'movie', sort: 'titleSort', maxResults: 25 })
```
- Defined in src/library.ts:561
all(): Promise<SectionType[]>
Returns media from every library section.

Use the options object for sorting, paging, and type-specific results. When libtype is provided, each section is asked for that Plex item type and the returned array is typed to the matching model.

Returns Promise<SectionType[]>
Example
```
const everything = await library.all()
const movies = await library.all({ libtype: 'movie', sort: 'titleSort', maxResults: 25 })
```
- Defined in src/library.ts:564
all(options: LibrarySectionAllOptions): Promise<LibrarySearchItem[]>
Returns media from every library section.

Use the options object for sorting, paging, and type-specific results. When libtype is provided, each section is asked for that Plex item type and the returned array is typed to the matching model.
Parameters
- options: LibrarySectionAllOptions
Returns Promise<LibrarySearchItem[]>
Example
```
const everything = await library.all()
const movies = await library.all({ libtype: 'movie', sort: 'titleSort', maxResults: 25 })
```
- Defined in src/library.ts:565

cancelUpdate

cancelUpdate(): Promise<void>
Cancel an active full-library scan.

Returns Promise<void>
- Defined in src/library.ts:637

cleanBundles

cleanBundles(): Promise<void>
Clean old metadata bundles from the server.

Returns Promise<void>
- Defined in src/library.ts:606

deleteMediaPreviews

deleteMediaPreviews(): Promise<void>
Delete preview thumbnails for all library sections.

Returns Promise<void>
- Defined in src/library.ts:651

emptyTrash

emptyTrash(): Promise<void>
If a library has items in the Library Trash, use this option to empty the Trash.

Returns Promise<void>
- Defined in src/library.ts:613

history

history(options?: LibraryHistoryOptions): Promise<HistoryResult[]>
Get watched history for all library sections for the owner.
Parameters
- options: LibraryHistoryOptions = {}
Returns Promise<HistoryResult[]>
- Defined in src/library.ts:659

hubs

hubs(__namedParameters?: LibraryHubsOptions): Promise<Hub[]>
Returns hubs across all library sections.
Parameters
- __namedParameters: LibraryHubsOptions = {}
Returns Promise<Hub[]>
- Defined in src/library.ts:521

onDeck

onDeck(): Promise<LibrarySearchItem[]>
Returns a list of all on-deck items from all library sections. On-deck items are media that is currently in progress.

Returns Promise<LibrarySearchItem[]>
- Defined in src/library.ts:543

optimize

optimize(): Promise<void>
The Optimize option cleans up the server database from unused or fragmented data. For example, if you have deleted or added an entire library or many items in a library, you may like to optimize the database.

Returns Promise<void>
- Defined in src/library.ts:623

recentlyAdded

recentlyAdded(): Promise<LibrarySearchItem[]>
Returns recently added media from all library sections.

Returns Promise<LibrarySearchItem[]>
- Defined in src/library.ts:575

refresh

refresh(): Promise<void>
Force refresh metadata for every library section.

Returns Promise<void>
- Defined in src/library.ts:644

search

search<
    T extends
        | "track"
        | "artist"
        | "album"
        | "movie"
        | "show"
        | "season"
        | "episode"
        | "trailer"
        | "comic"
        | "person"
        | "picture"
        | "clip"
        | "photo"
        | "photoalbum"
        | "playlist"
        | "playlistFolder"
        | "collection"
        | "optimizedVersion"
        | "userPlaylistItem",
>(
    options: LibrarySearchOptions & { libtype: T },
): Promise<SearchClassForLibtype<T>[]>
Search across all library sections. Section search is more powerful and validates filters.
Type Parameters
- T extends
      | "track"
      | "artist"
      | "album"
      | "movie"
      | "show"
      | "season"
      | "episode"
      | "trailer"
      | "comic"
      | "person"
      | "picture"
      | "clip"
      | "photo"
      | "photoalbum"
      | "playlist"
      | "playlistFolder"
      | "collection"
      | "optimizedVersion"
      | "userPlaylistItem"
Parameters
- options: LibrarySearchOptions & { libtype: T }
Returns Promise<SearchClassForLibtype<T>[]>
- Defined in src/library.ts:583
search(options?: LibrarySearchOptions): Promise<LibrarySearchItem[]>
Search across all library sections. Section search is more powerful and validates filters.
Parameters
- Optionaloptions: LibrarySearchOptions
Returns Promise<LibrarySearchItem[]>
- Defined in src/library.ts:586

section

section<T extends Section = Section>(title: string): Promise<T>
Type Parameters
- T extends Section = Section
Parameters
- title: string
Returns Promise<T>
- Defined in src/library.ts:302

sectionByID

sectionByID<T extends Section = Section>(sectionId: string | number): Promise<T>
Type Parameters
- T extends Section = Section
Parameters
- sectionId: string | number
Returns Promise<T>
- Defined in src/library.ts:315

sections

sections(): Promise<Section[]>
Returns Promise<Section[]>
a list of all media sections in this library. Library sections may be any of
- Defined in src/library.ts:282

update

update(): Promise<void>
Scan every library section for new media.

Returns Promise<void>
- Defined in src/library.ts:630

Class Library

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Library

Properties

allowSync

art

content

directories

identifier

mediaTagPrefix

mediaTagVersion

size

title1

title2

Statickey

Methods

add

Type Parameters

Parameters

Returns Promise<SectionForCreateType<T>>

Example

all

Type Parameters

Parameters

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

OptionalmaxResults?: number

libtype: T

Returns Promise<SearchClassForLibtype<T>[]>

Example

Returns Promise<SectionType[]>

Example

Parameters

Returns Promise<LibrarySearchItem[]>

Example

cancelUpdate

Returns Promise<void>

cleanBundles

Returns Promise<void>

deleteMediaPreviews

Returns Promise<void>

emptyTrash

Returns Promise<void>

history

Parameters

Returns Promise<HistoryResult[]>

hubs

Parameters

Returns Promise<Hub[]>

onDeck

Returns Promise<LibrarySearchItem[]>

optimize

Returns Promise<void>

recentlyAdded

Returns Promise<LibrarySearchItem[]>

refresh

Returns Promise<void>

search

Type Parameters

Parameters

Returns Promise<SearchClassForLibtype<T>[]>

Parameters

Returns Promise<LibrarySearchItem[]>

section

Type Parameters

Parameters

Returns Promise<T>

sectionByID

Type Parameters

Parameters

Returns Promise<T>

sections

Returns Promise<Section[]>

tags

Type Parameters

`Static`key

`Optional`libtype?:
| "track"
| "artist"
| "album"
| "movie"
| "show"
| "season"
| "episode"
| "trailer"
| "comic"
| "person"
| "picture"
| "clip"
| "photo"
| "photoalbum"
| "playlist"
| "playlistFolder"
| "collection"
| "optimizedVersion"
| "userPlaylistItem"

`Optional`maxResults?: number