LukeParke/plexruby
1
0
Fork 0
mirror of https://github.com/LukeHagar/plexruby.git synced 2025-12-06 20:57:45 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
v0.17.1
plexruby/docs/sdks/library
History

README.md

Library

(library)

Overview

API Calls interacting with Plex Media Server Libraries

Available Operations

get_file_hash

This resource returns hash values for local files

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_file_hash(url="file://C:\Image.png&type=13", type=4462.17)

if res.status_code == 200
  # handle response
end

Parameters

Parameter Type Required Description Example
url ::String ✔️ This is the path to the local file, must be prefixed by file:// file://C:\Image.png&type=13
type T.nilable(::Float) ➖ Item type

Response

T.nilable(Models::Operations::GetFileHashResponse)

get_recently_added_library

This endpoint will return the recently added content.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

req = Models::Operations::GetRecentlyAddedLibraryRequest.new(
  content_directory_id: 2,
  pinned_content_directory_id: [
    3,
    5,
    7,
    13,
    12,
    1,
    6,
    14,
    2,
    10,
    16,
    17,
  ],
  section_id: 2,
  type: Models::Operations::QueryParamType::TV_SHOW,
  include_meta: Models::Operations::QueryParamIncludeMeta::ENABLE,
  x_plex_container_start: 0,
  x_plex_container_size: 50,
)

res = s.library.get_recently_added_library(req)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::GetRecentlyAddedLibraryRequest ✔️ The request object to use for the request.

Response

T.nilable(Models::Operations::GetRecentlyAddedLibraryResponse)

get_all_libraries

A library section (commonly referred to as just a library) is a collection of media. Libraries are typed, and depending on their type provide either a flat or a hierarchical view of the media. For example, a music library has an artist > albums > tracks structure, whereas a movie library is flat.

Libraries have features beyond just being a collection of media; for starters, they include information about supported types, filters and sorts. This allows a client to provide a rich interface around the media (e.g. allow sorting movies by release year).

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_all_libraries()

if ! res.object.nil?
  # handle response
end

Response

T.nilable(Models::Operations::GetAllLibrariesResponse)

get_library_details

Library Details Endpoint

This endpoint provides comprehensive details about the library, focusing on organizational aspects rather than the content itself.

The details include:

Directories

Organized into three categories:

  • Primary Directories:

    • Used in some clients for quick access to media subsets (e.g., "All", "On Deck").
    • Most can be replicated via media queries.
    • Customizable by users.

  • Secondary Directories:

    • Marked with secondary="1".
    • Used in older clients for structured navigation.

  • Special Directories:

    • Includes a "By Folder" entry for filesystem-based browsing.
    • Contains an obsolete search="1" entry for on-the-fly search dialog creation.

Types

Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:

  • Type Object Attributes:

    • key: Endpoint for the media list of this type.
    • type: Metadata type (if standard Plex type).
    • title: Title for this content type (e.g., "Movies").

  • Filter Objects:

    • Subset of the media query language.
    • Attributes include filter (name), filterType (data type), key (endpoint for value range), and title.

  • Sort Objects:

    • Description of sort fields.
    • Attributes include defaultDirection (asc/desc), descKey and key (sort parameters), and title.

Note

: Filters and sorts are optional; without them, no filtering controls are rendered.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_library_details(section_key=9518, include_details=Models::Operations::IncludeDetails::ZERO)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
include_details T.nilable(Models::Operations::IncludeDetails) ➖ Whether or not to include details for a section (types, filters, and sorts).
Only exists for backwards compatibility, media providers other than the server libraries have it on always.

Response

T.nilable(Models::Operations::GetLibraryDetailsResponse)

delete_library

Delete a library using a specific section id

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.delete_library(section_key=9518)

if res.status_code == 200
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518

Response

T.nilable(Models::Operations::DeleteLibraryResponse)

get_library_items

Fetches details from a specific section of the library identified by a section key and a tag. The tag parameter accepts the following values:

  • all: All items in the section.
  • unwatched: Items that have not been played.
  • newest: Items that are recently released.
  • recentlyAdded: Items that are recently added to the library.
  • recentlyViewed: Items that were recently viewed.
  • onDeck: Items to continue watching.
  • collection: Items categorized by collection.
  • edition: Items categorized by edition.
  • genre: Items categorized by genre.
  • year: Items categorized by year of release.
  • decade: Items categorized by decade.
  • director: Items categorized by director.
  • actor: Items categorized by starring actor.
  • country: Items categorized by country of origin.
  • contentRating: Items categorized by content rating.
  • rating: Items categorized by rating.
  • resolution: Items categorized by resolution.
  • firstCharacter: Items categorized by the first letter.
  • folder: Items categorized by folder.
  • albums: Items categorized by album.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

req = Models::Operations::GetLibraryItemsRequest.new(
  tag: Models::Operations::Tag::EDITION,
  include_guids: Models::Operations::IncludeGuids::ENABLE,
  type: Models::Operations::GetLibraryItemsQueryParamType::TV_SHOW,
  section_key: 9518,
  include_meta: Models::Operations::GetLibraryItemsQueryParamIncludeMeta::ENABLE,
  x_plex_container_start: 0,
  x_plex_container_size: 50,
)

res = s.library.get_library_items(req)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::GetLibraryItemsRequest ✔️ The request object to use for the request.

Response

T.nilable(Models::Operations::GetLibraryItemsResponse)

get_library_sections_all

Retrieves a list of all general media data for this library.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

req = Models::Operations::GetLibrarySectionsAllRequest.new(
  section_key: 9518,
  type: Models::Operations::GetLibrarySectionsAllQueryParamType::TV_SHOW,
  include_meta: Models::Operations::GetLibrarySectionsAllQueryParamIncludeMeta::ENABLE,
  include_guids: Models::Operations::QueryParamIncludeGuids::ENABLE,
  include_advanced: Models::Operations::IncludeAdvanced::ENABLE,
  include_collections: Models::Operations::QueryParamIncludeCollections::ENABLE,
  include_external_media: Models::Operations::QueryParamIncludeExternalMedia::ENABLE,
  x_plex_container_start: 0,
  x_plex_container_size: 50,
)

res = s.library.get_library_sections_all(req)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::GetLibrarySectionsAllRequest ✔️ The request object to use for the request.

Response

T.nilable(Models::Operations::GetLibrarySectionsAllResponse)

get_refresh_library_metadata

This endpoint Refreshes all the Metadata of the library.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_refresh_library_metadata(section_key=9518, force=Models::Operations::Force::ONE)

if res.status_code == 200
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
force T.nilable(Models::Operations::Force) ➖ Force the refresh even if the library is already being refreshed. 0

Response

T.nilable(Models::Operations::GetRefreshLibraryMetadataResponse)

get_search_library

Search for content within a specific section of the library.

Types

Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:

  • Type Object Attributes:

    • type: Metadata type (if standard Plex type).
    • title: Title for this content type (e.g., "Movies").

  • Filter Objects:

    • Subset of the media query language.
    • Attributes include filter (name), filterType (data type), key (endpoint for value range), and title.

  • Sort Objects:

    • Description of sort fields.
    • Attributes include defaultDirection (asc/desc), descKey and key (sort parameters), and title.

Note

: Filters and sorts are optional; without them, no filtering controls are rendered.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_search_library(section_key=9518, type=Models::Operations::GetSearchLibraryQueryParamType::TV_SHOW)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
type Models::Operations::GetSearchLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
1 = movie
2 = show
3 = season
4 = episode
E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries
 2

Response

T.nilable(Models::Operations::GetSearchLibraryResponse)

get_genres_library

Retrieves a list of all the genres that are found for the media in this library.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_genres_library(section_key=9518, type=Models::Operations::GetGenresLibraryQueryParamType::TV_SHOW)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
type Models::Operations::GetGenresLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
1 = movie
2 = show
3 = season
4 = episode
E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries
 2

Response

T.nilable(Models::Operations::GetGenresLibraryResponse)

get_countries_library

Retrieves a list of all the countries that are found for the media in this library.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_countries_library(section_key=9518, type=Models::Operations::GetCountriesLibraryQueryParamType::TV_SHOW)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
type Models::Operations::GetCountriesLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
1 = movie
2 = show
3 = season
4 = episode
E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries
 2

Response

T.nilable(Models::Operations::GetCountriesLibraryResponse)

get_actors_library

Retrieves a list of all the actors that are found for the media in this library.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_actors_library(section_key=9518, type=Models::Operations::GetActorsLibraryQueryParamType::TV_SHOW)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
section_key ::Integer ✔️ The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
 9518
type Models::Operations::GetActorsLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
1 = movie
2 = show
3 = season
4 = episode
E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries
 2

Response

T.nilable(Models::Operations::GetActorsLibraryResponse)

get_search_all_libraries

Search the provided query across all library sections, or a single section, and return matches as hubs, split up by type.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

req = Models::Operations::GetSearchAllLibrariesRequest.new(
  query: "<value>",
  client_id: "3381b62b-9ab7-4e37-827b-203e9809eb58",
  search_types: [
    Models::Operations::SearchTypes::PEOPLE,
  ],
  include_collections: Models::Operations::GetSearchAllLibrariesQueryParamIncludeCollections::ENABLE,
  include_external_media: Models::Operations::GetSearchAllLibrariesQueryParamIncludeExternalMedia::ENABLE,
)

res = s.library.get_search_all_libraries(req)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::GetSearchAllLibrariesRequest ✔️ The request object to use for the request.

Response

T.nilable(Models::Operations::GetSearchAllLibrariesResponse)

get_media_meta_data

This endpoint will return all the (meta)data of one or more library items specified by the ratingKey. Multiple rating keys can be provided as a comma-separated list (e.g., "21119,21617").

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

req = Models::Operations::GetMediaMetaDataRequest.new(
  rating_key: "21119,21617",
  include_concerts: true,
  include_extras: true,
  include_on_deck: true,
  include_popular_leaves: true,
  include_preferences: true,
  include_reviews: true,
  include_chapters: true,
  include_stations: true,
  include_external_media: true,
  async_augment_metadata: true,
  async_check_files: true,
  async_refresh_analysis: true,
  async_refresh_local_media_agent: true,
)

res = s.library.get_media_meta_data(req)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::GetMediaMetaDataRequest ✔️ The request object to use for the request.

Response

T.nilable(Models::Operations::GetMediaMetaDataResponse)

get_media_arts

Returns the background artwork for a library item.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_media_arts(rating_key=16_099)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
rating_key ::Integer ✔️ the id of the library item to return the artwork of. 16099

Response

T.nilable(Models::Operations::GetMediaArtsResponse)

post_media_arts

Uploads an image to use as the background artwork for a library item, either from a local file or a remote URL

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.post_media_arts(rating_key=2268, url="https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b", request_body="0xee51EFC6De".encode())

if res.status_code == 200
  # handle response
end

Parameters

Parameter Type Required Description Example
rating_key ::Integer ✔️ the id of the library item to return the posters of. 2268
url T.nilable(::String) ➖ The URL of the image, if uploading a remote image https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
request_body T.nilable(::String) ➖ The contents of the image, if uploading a local file

Response

T.nilable(Models::Operations::PostMediaArtsResponse)

get_media_posters

Returns the available posters for a library item.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_media_posters(rating_key=16_099)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
rating_key ::Integer ✔️ the id of the library item to return the posters of. 16099

Response

T.nilable(Models::Operations::GetMediaPostersResponse)

post_media_poster

Uploads a poster to a library item, either from a local file or a remote URL

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.post_media_poster(rating_key=2268, url="https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b", request_body="0x7C3d45ad4B".encode())

if res.status_code == 200
  # handle response
end

Parameters

Parameter Type Required Description Example
rating_key ::Integer ✔️ the id of the library item to return the posters of. 2268
url T.nilable(::String) ➖ The URL of the image, if uploading a remote image https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
request_body T.nilable(::String) ➖ The contents of the image, if uploading a local file

Response

T.nilable(Models::Operations::PostMediaPosterResponse)

get_metadata_children

This endpoint will return the children of of a library item specified with the ratingKey.

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_metadata_children(rating_key=1539.14, include_elements="<value>")

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
rating_key ::Float ✔️ the id of the library item to return the children of.
include_elements T.nilable(::String) ➖ Adds additional elements to the response. Supported types are (Stream)

Response

T.nilable(Models::Operations::GetMetadataChildrenResponse)

get_top_watched_content

This endpoint will return the top watched content from libraries of a certain type

Example Usage

require 'plex_ruby_sdk'

s = ::PlexRubySDK::PlexAPI.new(
      security: Models::Shared::Security.new(
        access_token: "<YOUR_API_KEY_HERE>",
      ),
    )

res = s.library.get_top_watched_content(type=Models::Operations::GetTopWatchedContentQueryParamType::TV_SHOW, include_guids=Models::Operations::GetTopWatchedContentQueryParamIncludeGuids::ENABLE)

if ! res.object.nil?
  # handle response
end

Parameters

Parameter Type Required Description Example
type Models::Operations::GetTopWatchedContentQueryParamType ✔️ The type of media to retrieve or filter by.
1 = movie
2 = show
3 = season
4 = episode
E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries
 2
include_guids T.nilable(Models::Operations::GetTopWatchedContentQueryParamIncludeGuids) ➖ Adds the Guid object to the response
 1

Response

T.nilable(Models::Operations::GetTopWatchedContentResponse)