API reference#

This part of the documentation lists the full API reference of all public classes and functions.

High level#

The simplest and easiest to use interface to the TV. This is probably what you should use, unless you plan some advanced API operations. One of the examples where this will not be enough is manipulating individual Ambilight light points.

class philipstv.PhilipsTVRemote(api: PhilipsTVAPI)#

High level interface to the TV.

Wraps the API into convenient methods simulating functions that could be found on a TV remote.

Can be used either with existing PhilipsTVAPI instance, or create it itself. In the following example remote_one and remote_two are equivalent:

api = PhilipsTVAPI(PhilipsTV("192.169.0.100", auth=("id", "key")))
remote_one = PhilipsTVRemote(api)
remote_two = PhilipsTVRemote.new("192.168.0.100", ("id", "key"))

Parameters:: api – Instance of an API to be used by the remote.

property host: str#: IP address of the underlying PhilipsTVAPI instance.

Warning

This value is read-only.

property auth: Tuple[str, str] | None#: Credentials used for authentication in the underlying PhilipsTVAPI instance.

Hint

This value can be set and changed at any moment during PhilipsTVRemote usage.

classmethod new(host: str, auth: Tuple[str, str] | None = None) → PhilipsTVRemote#

Create a new remote for given host without the need to inject:class:PhilipsTVAPI instance.

Parameters:

host – IP address of the TV.
auth – Authentication credentials. If not given, the only feature you will be able to use is pairing: pair().

pair(pin_callback: Callable[[], str], id: str | None = None) → Tuple[str, str]#

Perform pairing with the TV.

After successful pairing this remote instance will be authenticated, even if you didn’t provide credentials when creating it.

Parameters:

pin_callback – A function taking no arguments and returning the PIN displayed on TV as a string.
id – Device ID to use for pairing. This will be later used as a first value in credentials tuple. If not given, a random, 16 characters, alphanumeric string will be used.

Returns:

A tuple of acquired authentication credentials.

get_power() → bool#

Return the current power state.

Returns:: A power state. True means on, False means standby.

set_power(power: bool) → None#

Set current power state.

Parameters:: power – Power state to set. True means on, False means standby.

get_volume() → int#: Return current volume.

set_volume(volume: int) → None#

Set current volume.

Parameters:: volume – Volume value to set.

get_current_channel() → str#

Return current TV channel.

If the TV currently displays something different than television (any app), this will return the last watched channel.

Returns:: Current TV channel name.

set_channel(channel: int | str) → None#

Change to the given TV channel.

Use get_all_channels() to find valid values.

If the TV currently displays something different than television (any app), it will go to the television.

Parameters:: channel – Number or name of the channel to change to.
Raises:: PhilipsTVRemoteError – If invalid channel number or name is given.

get_all_channels() → Dict[int, str]#

Return all available channels and their numbers.

Returns:: A mapping of channel number to channel name.

input_key(key: InputKeyValue) → None#

Emulate pressing a key on the TV remote.

Parameters:: key – A key value to send to the TV.

get_ambilight_power() → bool#

Return current ambilight power state.

Returns:: Ambilight power state. True means on, False means off.

set_ambilight_power(power: bool) → None#

Set ambilight power state.

Parameters:: power – Ambilight power state to set. True means on, False means off.

Set ambilight color.

On sides without given color, the color will not be changed. color defines color for all sides. If any of left, top, right or bottom args are given, they override color on that side.

Parameters:

color – A color to set on all sides.
left – A color to set on the left side.
top – A color to set on the top side.
right – A color to set on the right side.
bottom – A color to set on the bottom side.

get_applications() → List[str]#

Return a list of available applications.

Returns:: List of application names.

launch_application(application: str) → None#

Launch an application.

Use get_applications() to find valid values.

Parameters:: application – An application name.
Raises:: PhilipsTVRemoteError – If invalid application name is given.

Low level#

More complicated, but also more powerful interface.

class philipstv.PhilipsTVAPI(tv: PhilipsTV)#

Wrapper around Philips TV API.

Each method mirrors a single GET or POST request to one of the available API endpoints. The original shape of request payloads and responses in preserved, but they’re wrapped in pydantic models.

Parameters:: tv – Instance of the PhilipsTV to which the API requestes will be sent.

property host: str#: IP address of the underlying PhilipsTV instance.

Warning

This value is read-only.

property auth: Tuple[str, str] | None#: Credentials used for authentication in the underlying PhilipsTV instance.

Hint

This value can be set and changed at any moment during PhilipsTVAPI usage.

pair_request(payload: PairingRequestPayload) → PairingRequestResponse#

Send request initiating the pairing process.

Use pair_grant() to finalize the pairing using data from response to this request.

Parameters:: payload – Request payload.
Returns:: The TV response containing authentication details.

pair_grant(payload: PairingGrantPayload) → PairingResponse#

Send request finalizing the pairing process.

This requires some data from response to request initiating the pairing: pair_request().

Parameters:: payload – Request payload.
Returns:: The TV response containing pairing confirmation or rejection.

get_powerstate() → PowerState#: Send request to get the current power state.

set_powerstate(powerstate: PowerState) → None#: Send request to set the power state.

get_volume() → CurrentVolume#: Send request to get the current volume, mute status, and volume limits.

set_volume(volume: Volume) → None#: Send request to set the volume.

get_current_channel() → CurrentChannel#: Send request to get current TV app activity.

get_all_channels() → AllChannels#: Send request to get all available channels.

set_channel(channel: SetChannel) → None#: Send request to set the channel.

input_key(key: InputKey) → None#: Send request to simulate pressing key on the remote.

get_ambilight_power() → AmbilightPower#: Send request to get Ambilight power state.

set_ambilight_power(power: AmbilightPower) → None#: Send request to set Ambilight power state.

get_ambilight_topology() → AmbilightTopology#: Send request to get Ambilight topology.

get_ambilight_mode() → AmbilightMode#: Send request to get current Ambilight mode.

set_ambilight_mode(mode: AmbilightMode) → None#: Send request to set ambilight mode.

get_ambilight_measured() → AmbilightColors#

Send request to get measured color values from Ambilight system.

Those are the colors taken directly from the displayed image, before processing by internal Ambilight algorithm.

get_ambilight_processed() → AmbilightColors#

Send request to get processed color values from Ambilight system.

Those are the measured values after processing by the internal Ambilight algorithm, based on the currently active Ambilight style.

get_ambilight_cached() → AmbilightColors#

Send request to get cached color values from Ambilight system.

Those are the values that were previously set by some user via API.

set_ambilight_cached(colors: AmbilightColor | AmbilightColors) → None#

Send request to set cached color values in Ambilight system.

If those values are set, they override other Ambilight settings. This effectively just sets the Ambilight color.

Note

The actual TV API allows sending the colors in one of the following ways:

All pixels on all layers to the same color.
All pixels on a single layer to the same color.
Specific colors for pixels on chosen sides (left, top, etc.) of a single layer.
Specific color for any pixel addressed by layer, side and index.

This implementation allows only options 1 and 4. I have no idea what are the “layers”. The TVs I have access to have only one. I wasn’t able to find any information about it so I decided to ignore it. Option 3 could actually be useful, I’ll consider implementing it, but right now the same effect can be achieved using option 4.

All pixels which color’s are not set in a given request (e.g. setting a single pixel’s color), will keep their color.

References

Philips JointSpace API Documentation

get_applications() → Applications#: Send request to get the list of installed applications.

launch_application(application: ApplicationShort) → None#

Send request to launch an application activity.

Use values returned by get_applications().

Note

“Activity” means that this can go directly to a specific screen in the application. Unfortunately, I don’t know where to get valid “activities” for specific applications.

class philipstv.PhilipsTVPairer(api: PhilipsTVAPI, device_info: DeviceInfo)#

Encapsulates the pairing process and allows to perform it in a single call.

Parameters:

api – PhilipsTVAPI instance with which pairing will be performed.
device_info – Informations about the device which requests the pairing. This doesn’t really seem to have any effect, besides the fact that id given here serves as a “username” and later will be the first value in the credentials tuple.

pair(pin_callback: Callable[[], str]) → Tuple[str, str]#

Perfom the pairing.

Hint

If the pairing is successful, this leaves the underlying PhilipsTVAPI instance in authenticated state, so you don’t have to set PhilipsTVAPI.auth with the received credentials.

Parameters:: pin_callback – Callback function which should return the PIN displayed on the TV screen as a string. It’s impossible to know the PIN before requesting pairing so this function should be used to prompt the user for the PIN.
Returns:: Authentication credentials tuple. This value can be used to authenticate with the TV at any point in future.

class philipstv.PhilipsTV(host: str, port: int = 1926, auth: Tuple[str, str] | None = None)#

Lowest level interface with the TV.

Used to send raw (without using model objects) GET and POST requests to any API path.

This handles authentication, exception handling, logging and URL building so higher layers don’t have to worry about this.

Parameters:

host – TV IP address to connect to.
port – TV port to connect to.
auth – Authentication credentials tuple.

property auth: Tuple[str, str] | None#: Credentials used for authentication.

Hint

This value can be set and changed at any moment during PhilipsTV usage.

post(path: str, payload: Any | None = None) → Any#

Send POST request.

Parameters:

path – The path to send the request to.
payload – Request payload to send.

Returns:

The TV’s JSON response body or None.

get(path: str) → Any#

Send GET request.

Parameters:: path – The path to send the request to.
Returns:: The TV’s JSON response body or None.

Exceptions#

exception philipstv.PhilipsError(message: str)#: Base exception for all exceptions raised by this package.

exception philipstv.PhilipsTVError(method: str, url: str, status_code: int | None = None)#

Raised if error occured during communication with the TV.

method#: HTTP method of the request.

url#: URL of the request.

status_code#: HTTP status_code if response was received.

exception philipstv.PhilipsTVPairingError(response: PairingResponse)#

Raised if pairing process failed.

This could happen e.g. when requesting pairing during another pairing in progress, or if provided PIN is incorrect.

response#: Response to the pairing request, containing error details.

exception philipstv.PhilipsTVAPIError(message: str)#: Raised when something goes wrong with API communication.

exception philipstv.PhilipsTVAPIUnauthorizedError(method: str, path: str)#

Raised when trying to use the API without, or with invalid credentials.

method#: HTTP method of the request.

path#: Path of the request.

exception philipstv.PhilipsTVAPIMalformedResponseError(method: str, path: str, response: Any)#

Raised when response received from the API is unparsable into known object.

method#: HTTP method of the request.

path#: Path of the request.

response#: Raw response JSON returned by the API.

exception philipstv.PhilipsTVRemoteError(message: str)#

Raised if there was some incorrect interaction with PhilipsTVRemote.

This can happen e.g. when trying to launch application which is not installed. This exception does NOT come from the TV. It comes from the PhilipsTVRemote class logic.

API models#

Wrappers around API request payloads and responses.

Base#

class philipstv.model.APIObject#

Base for all API objects.

Note

In all APIObject subclassess, all attributes are also parameters accepted in a constructor.

dump() → Any#

Dump the object’s JSON data.

This JSON data (usually a dict) represents a body of some API request or response.

Returns:: Model’s JSON data.

classmethod parse(raw: Any) → _SelfAPIObject#

Construct the API object from given JSON data.

Each APIObject can be created from JSON data (usually a dict) of some API request or response body.

Parameters:: raw – Request or response body JSON data.
Returns:: An instance of a subclass this is called on.
Raises:: ValidationError – if given JSON data cannot be parsed into this model.

class philipstv.model.StrEnum(value)#: Enum with string values.

Pairing#

class philipstv.model.DeviceInfo(*, id: str, device_name: str, device_os: str, app_id: str, app_name: str, type: str)#

Model of information about device requesting pairing.

id: str#: ID of the device.

device_name: str#: Name of the device.

device_os: str#: OS of the device.

app_id: str#: ID of the application.

app_name: str#: Name of the application.

type: str#: Type of the application.

class philipstv.model.PairingAuthInfo(*, pin: str, auth_timestamp: int, auth_signature: str)#

Model of authentication information in pairing confirmation request.

pin: str#: Value of the PIN displayed on the TV.

auth_timestamp: int#: Timestamp value from response to the pairing request.

auth_signature: str#: HMAC signature created from the PIN value.

class philipstv.model.PairingRequestPayload(*, scope: List[str], device: DeviceInfo)#

Model of a pairing request.

scope: List[str]#: Requested permissions scope. Available options are read, write, control.

device: DeviceInfo#: Requesting device info.

class philipstv.model.PairingGrantPayload(*, auth: PairingAuthInfo, device: DeviceInfo)#

Model of pairing confirmation request.

auth: PairingAuthInfo#: Authentication info.

device: DeviceInfo#: Requesting device info.

class philipstv.model.PairingResponse(*, error_id: str, error_text: str)#

Model of response the pairing request or confirmation request.

Note

Even tough there’s “error” in the field names it doesn’t mean an actual error occured. The TV communicates successful states using those fields as well.

error_id: str#: ID of the pairing process state.

error_text: str#: Description of the pairing process state.

class philipstv.model.PairingRequestResponse(*, error_id: str, error_text: str, auth_key: str | None = None, timestamp: int | None = None, timeout: int | None = None)#

Bases: PairingResponse

Model of a response to the pairing request.

Note

Even tough there’s “error” in the field names it doesn’t mean an actual error occured. The TV communicates successful states using those fields as well.

error_id: str#: ID of the pairing process state.

error_text: str#: Description of the pairing process state.

auth_key: str | None#: Authentication key.

timestamp: int | None#: Timestamp sent by TV.

timeout: int | None#: Timeout before the pairing is cancelled.

General#

enum philipstv.model.PowerStateValue(value)#

TV power state values.

Member Type:: str

Valid values are as follows:

ON = <PowerStateValue.ON: 'On'>#

STANDBY = <PowerStateValue.STANDBY: 'Standby'>#

class philipstv.model.PowerState(*, powerstate: PowerStateValue)#

Model of a power state request and response.

powerstate: PowerStateValue#: A power state value.

Audio#

class philipstv.model.Volume(*, current: int, muted: bool = False)#

Model of a volume set request.

current: int#: Volume value.

muted: bool#: Whether the TV is muted.

class philipstv.model.CurrentVolume(*, current: int, muted: bool = False, min: int, max: int)#

Model of a volume response.

current: int#: Volume value.

muted: bool#: Whether the TV is muted.

min: int#: Minimum allowed volume value.

max: int#: Maximum allowed volume value.

Channels#

class philipstv.model.ChannelID(*, ccid: int)#

Model of a channel change request.

ccid: int#: ID of the channel.

class philipstv.model.ChannelShort(*, ccid: int, preset: str, name: str)#

Bases: ChannelID

Model of a channel definition in current channel response.

preset: str#: Number by which the channel is available on the TV.

name: str#: Name of the channel.

ccid: int#: ID of the channel.

class philipstv.model.Channel(*, ccid: int, preset: str, name: str, onid: int, tsid: int, sid: int, serviceType: str, type: str, logoVersion: int)#

Bases: ChannelShort

Model of a channel definition in channels list response.

onid: int#: Original Network ID.

tsid: int#: Transport Stream ID.

sid: int#: Service ID.

service_type: str#: Service type.

type: str#: Channel type.

logo_version: int#: Channel logo version.

ccid: int#: ID of the channel.

preset: str#: Number by which the channel is available on the TV.

name: str#: Name of the channel.

class philipstv.model.ChannelListID(*, id: str = 'allcab')#

Model of a channels list definition in channel change request.

id: str#: ID of the channel list.

class philipstv.model.ChannelList(*, id: str = 'allcab', version: str)#

Model of a channels list definition in channels list response.

version: str#: Channel list version.

id: str#: ID of the channel list.

class philipstv.model.CurrentChannel(*, channel: ChannelShort, channelList: ChannelList)#

Model of a current channel response.

channel: ChannelShort#: Current channel definition.

channel_list: ChannelList#: Current channel list definition.

class philipstv.model.SetChannel(*, channel: ChannelID, channelList: ChannelListID = None)#

Model of a channel change request.

channel: ChannelID#: Definition of a channel to change to.

channel_list: ChannelListID#: Definition of a list this channel is on.

class philipstv.model.AllChannels(*, version: int, id: str, listType: str, medium: str, operator: str, installCountry: str, Channel: List[Channel])#

Model of all channels list response.

version: int#: List version.

id: str#: List ID.

list_type: str#: List type.

medium: str#: TV reception medium.

operator: str#: TC operator name.

install_country: str#: Country the TV service is installed in.

channel: List[Channel]#: List of channel definitions.

Input#

enum philipstv.model.InputKeyValue(value)#

Values of remote key names.

Member Type:: str

Valid values are as follows:

STANDBY = <InputKeyValue.STANDBY: 'Standby'>#

BACK = <InputKeyValue.BACK: 'Back'>#

FIND = <InputKeyValue.FIND: 'Find'>#

RED = <InputKeyValue.RED: 'RedColour'>#

GREEN = <InputKeyValue.GREEN: 'GreenColour'>#

YELLOW = <InputKeyValue.YELLOW: 'YellowColour'>#

BLUE = <InputKeyValue.BLUE: 'BlueColour'>#

HOME = <InputKeyValue.HOME: 'Home'>#

VOLUME_UP = <InputKeyValue.VOLUME_UP: 'VolumeUp'>#

VOLUME_DOWN = <InputKeyValue.VOLUME_DOWN: 'VolumeDown'>#

MUTE = <InputKeyValue.MUTE: 'Mute'>#

OPTIONS = <InputKeyValue.OPTIONS: 'Options'>#

DOT = <InputKeyValue.DOT: 'Dot'>#

DIGIT_0 = <InputKeyValue.DIGIT_0: 'Digit0'>#

DIGIT_1 = <InputKeyValue.DIGIT_1: 'Digit1'>#

DIGIT_2 = <InputKeyValue.DIGIT_2: 'Digit2'>#

DIGIT_3 = <InputKeyValue.DIGIT_3: 'Digit3'>#

DIGIT_4 = <InputKeyValue.DIGIT_4: 'Digit4'>#

DIGIT_5 = <InputKeyValue.DIGIT_5: 'Digit5'>#

DIGIT_6 = <InputKeyValue.DIGIT_6: 'Digit6'>#

DIGIT_7 = <InputKeyValue.DIGIT_7: 'Digit7'>#

DIGIT_8 = <InputKeyValue.DIGIT_8: 'Digit8'>#

DIGIT_9 = <InputKeyValue.DIGIT_9: 'Digit9'>#

INFO = <InputKeyValue.INFO: 'Info'>#

CURSOR_UP = <InputKeyValue.CURSOR_UP: 'CursorUp'>#

CURSOR_DOWN = <InputKeyValue.CURSOR_DOWN: 'CursorDown'>#

CURSOR_LEFT = <InputKeyValue.CURSOR_LEFT: 'CursorLeft'>#

CURSOR_RIGHT = <InputKeyValue.CURSOR_RIGHT: 'CursorRight'>#

CONFIRM = <InputKeyValue.CONFIRM: 'Confirm'>#

NEXT = <InputKeyValue.NEXT: 'Next'>#

PREVIOUS = <InputKeyValue.PREVIOUS: 'Previous'>#

ADJUST = <InputKeyValue.ADJUST: 'Adjust'>#

WATCH_TV = <InputKeyValue.WATCH_TV: 'WatchTV'>#

VIEWMODE = <InputKeyValue.VIEWMODE: 'Viewmode'>#

TELETEXT = <InputKeyValue.TELETEXT: 'Teletext'>#

SUBTITLE = <InputKeyValue.SUBTITLE: 'Subtitle'>#

CHANNEL_STEP_UP = <InputKeyValue.CHANNEL_STEP_UP: 'ChannelStepUp'>#

CHANNEL_STEP_DOWN = <InputKeyValue.CHANNEL_STEP_DOWN: 'ChannelStepDown'>#

SOURCE = <InputKeyValue.SOURCE: 'Source'>#

AMBILIGHT_ON_OFF = <InputKeyValue.AMBILIGHT_ON_OFF: 'AmbilightOnOff'>#

PLAY_PAUSE = <InputKeyValue.PLAY_PAUSE: 'PlayPause'>#

PAUSE = <InputKeyValue.PAUSE: 'Pause'>#

FAST_FORWARD = <InputKeyValue.FAST_FORWARD: 'FastForward'>#

STOP = <InputKeyValue.STOP: 'Stop'>#

REWIND = <InputKeyValue.REWIND: 'Rewind'>#

RECORD = <InputKeyValue.RECORD: 'Record'>#

ONLINE = <InputKeyValue.ONLINE: 'Online'>#

class philipstv.model.InputKey(*, key: InputKeyValue)#

Model of remote key input request.

key: InputKeyValue#: Value of the key.

Ambilight#

enum philipstv.model.AmbilightPowerValue(value)#

Ambilight power state values.

Member Type:: str

Valid values are as follows:

ON = <AmbilightPowerValue.ON: 'On'>#

OFF = <AmbilightPowerValue.OFF: 'Off'>#

class philipstv.model.AmbilightPower(*, power: AmbilightPowerValue)#

Ambilight power state request and response model.

power: AmbilightPowerValue#: Ambilight power state value.

class philipstv.model.AmbilightTopology(*, layers: int, left: int, top: int, right: int, bottom: int)#

Ambilight topology response model.

layers: int#: Number of layers.

left: int#: Number of pixels on the left edge.

top: int#: Number of pixels on the top edge.

right: int#: Number of pixels on the right edge.

bottom: int#: Number of pixels on the bottom edge.

enum philipstv.model.AmbilightModeValue(value)#

Ambilight mode values.

Member Type:: str

Valid values are as follows:

INTERNAL = <AmbilightModeValue.INTERNAL: 'internal'>#

MANUAL = <AmbilightModeValue.MANUAL: 'manual'>#

EXPERT = <AmbilightModeValue.EXPERT: 'expert'>#

class philipstv.model.AmbilightMode(*, current: AmbilightModeValue)#

Ambilight mode request and response model.

current: AmbilightModeValue#: Ambiglight mode value.

class philipstv.model.AmbilightColor(*, r: int, g: int, b: int)#

Ambilight color model.

r: int#: Red color component.

g: int#: Green color component.

b: int#: Blue color component.

classmethod from_tuple(color_tuple: Tuple[int, int, int]) → AmbilightColor#

Create AmbilightColor instance from a tuple.

Parameters:: color_tuple – Tuple of three integers representing RGB color.
Returns:: Model instance.

class philipstv.model.AmbilightLayer(*, left: Dict[str, AmbilightColor] = None, top: Dict[str, AmbilightColor] = None, right: Dict[str, AmbilightColor] = None, bottom: Dict[str, AmbilightColor] = None)#

Model of a single Ambilight layer per-pixel colors definition.

Each edge is a mappping of a pixel name to it’s color:

layer = AmbilightLayer(top={"0": AmbilightColor(...), "1": AmbilightColor(...)})

left: Dict[str, AmbilightColor]#: Colors of pixels on the left edge.

top: Dict[str, AmbilightColor]#: Colors of pixels on the top edge.

right: Dict[str, AmbilightColor]#: Colors of pixels on the right edge.

bottom: Dict[str, AmbilightColor]#: Colors of pixels on the bottom edge.

class philipstv.model.AmbilightColors(root: RootModelRootType = PydanticUndefined)#

Model of full Amblight per-pixel color definition.

This model is actually a wrapper around a dict since layer names are not predefined. Values should be set as dict passed to constructor and accessed as in normal dict using indexing:

colors = AmbilightColors({"layer1": AmbilightLayer()})
layer1 = colors["layer1"]

root: Dict[str, AmbilightLayer]#: Mapping of layer name to AmbilightLayer.

Applications#

class philipstv.model.ApplicationComponent(*, packageName: str, className: str)#

Model of application component API object.

package_name: str#: Application package name.

class_name: str#: Application class name.

class philipstv.model.ApplicationIntent(*, component: ApplicationComponent, action: str)#

Model of application intent API object.

component: ApplicationComponent#: Application component.

action: str#: Action within application.

class philipstv.model.ApplicationShort(*, intent: ApplicationIntent)#

Model of an activity launch request body.

intent: ApplicationIntent#: Definition of application intent.

class philipstv.model.Application(*, intent: ApplicationIntent, label: str, order: int, id: str, type: str)#

Bases: ApplicationShort

Model of an application in application list response body.

label: str#: Application name.

intent: ApplicationIntent#: Definition of application intent.

order: int#: Application order.

id: str#: Application ID.

type: str#: Application type.

class philipstv.model.Applications(*, version: int, applications: List[Application])#

Model of applications list response body.

version: int#: List version.

applications: List[Application]#: List of application definitions.