plexpy/docs/sdks/devices

Devices

(devices)

Overview

Media grabbers provide ways for media to be obtained for a given protocol. The simplest ones are stream and download. More complex grabbers can have associated devices

Network tuners can present themselves on the network using the Simple Service Discovery Protocol and Plex Media Server will discover them. The following XML is an example of the data returned from SSDP. The deviceType, serviceType, and serviceId values must remain as they are in the example in order for PMS to properly discover the device. Other less-obvious fields are described in the parameters section below.

Example SSDP output

<root xmlns="urn:schemas-upnp-org:device-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <device>
        <deviceType>urn:plex-tv:device:Media:1</deviceType>
        <friendlyName>Turing Hopper 3000</friendlyName>
        <manufacturer>Plex, Inc.</manufacturer>
        <manufacturerURL>https://plex.tv/</manufacturerURL>
        <modelDescription>Turing Hopper 3000 Media Grabber</modelDescription>
        <modelName>Plex Media Grabber</modelName>
        <modelNumber>1</modelNumber>
        <modelURL>https://plex.tv</modelURL>
        <UDN>uuid:42fde8e4-93b6-41e5-8a63-12d848655811</UDN>
        <serviceList>
            <service>
                <URLBase>http://10.0.0.5:8088</URLBase>
                <serviceType>urn:plex-tv:service:MediaGrabber:1</serviceType>
                <serviceId>urn:plex-tv:serviceId:MediaGrabber</serviceId>
            </service>
        </serviceList>
    </device>
</root>

• UDN: (string) A UUID for the device. This should be unique across models of a device at minimum.
• URLBase: (string) The base HTTP URL for the device from which all of the other endpoints are hosted.

Available Operations

• get_available_grabbers - Get available grabbers
• list_devices - Get all devices
• add_device - Add a device
• discover_devices - Tell grabbers to discover devices
• remove_device - Remove a device
• get_device_details - Get device details
• modify_device - Enable or disable a device
• set_channelmap - Set a device's channel mapping
• get_devices_channels - Get a device's channels
• set_device_preferences - Set device preferences
• stop_scan - Tell a device to stop scanning for channels
• scan - Tell a device to scan for channels
• get_thumb - Get device thumb

get_available_grabbers

Get available grabbers visible to the server

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.get_available_grabbers(request={
        "protocol": "livetv",
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

Parameter	Type	Required	Description
request	operations.GetAvailableGrabbersRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetAvailableGrabbersResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

list_devices

Get the list of all devices present

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.list_devices()

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.ListDevicesResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

add_device

This endpoint adds a device to an existing grabber. The device is identified, and added to the correct grabber.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.add_device(request={
        "uri": "http://10.0.0.5",
    })

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
request	operations.AddDeviceRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.AddDeviceResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

discover_devices

Tell grabbers to discover devices

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.discover_devices()

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.DiscoverDevicesResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

remove_device

Remove a devices by its id along with its channel mappings

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.remove_device(request={
        "device_id": 685908,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

Parameter	Type	Required	Description
request	operations.RemoveDeviceRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.RemoveDeviceResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

get_device_details

Get a device's details by its id

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.get_device_details(request={
        "device_id": 170949,
    })

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
request	operations.GetDeviceDetailsRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetDeviceDetailsResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

modify_device

Enable or disable a device by its id

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.modify_device(request={
        "device_id": 879135,
        "enabled": components.BoolInt.TRUE,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

Parameter	Type	Required	Description
request	operations.ModifyDeviceRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.ModifyDeviceResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

set_channelmap

Set a device's channel mapping

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.set_channelmap(request={
        "device_id": 937661,
        "channel_mapping": {},
        "channel_mapping_by_key": {},
        "channels_enabled": [
            "4",
            "6",
            ".",
            "1",
            ",",
            "4",
            "4",
            ".",
            "1",
            ",",
            "4",
            "5",
            ".",
            "1",
        ],
    })

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
request	operations.SetChannelmapRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.SetChannelmapResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

get_devices_channels

Get a device's channels by its id

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.get_devices_channels(request={
        "device_id": 517209,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

Parameter	Type	Required	Description
request	operations.GetDevicesChannelsRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetDevicesChannelsResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

set_device_preferences

Set device preferences by its id

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.set_device_preferences(request={
        "device_id": 420973,
    })

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
request	operations.SetDevicePreferencesRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.SetDevicePreferencesResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

stop_scan

Tell a device to stop scanning for channels

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.stop_scan(request={
        "device_id": 576494,
    })

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
request	operations.StopScanRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.StopScanResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

scan

Tell a device to scan for channels

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.scan(request={
        "device_id": 57391,
        "source": "Cable",
    })

    assert res.media_container_with_device is not None

    # Handle response
    print(res.media_container_with_device)

Parameters

Parameter	Type	Required	Description
request	operations.ScanRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.ScanResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*

get_thumb

Get a device's thumb for display to the user

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import components


with PlexAPI(
    accepts=components.Accepts.APPLICATION_XML,
    client_identifier="abc123",
    product="Plex for Roku",
    version="2.4.1",
    platform="Roku",
    platform_version="4.3 build 1057",
    device="Roku 3",
    model="4200X",
    device_vendor="Roku",
    device_name="Living Room TV",
    marketplace="googlePlay",
    token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.devices.get_thumb(request={
        "device_id": 960617,
        "version_path_parameter": 1025,
    })

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
request	operations.GetThumbRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetThumbResponse

Errors

Error Type	Status Code	Content Type
errors.SDKError	4XX, 5XX	*/*