androidtv.basetv.basetv module

Communicate with an Android TV or Amazon Fire TV device via ADB over a network.

ADB Debugging must be enabled.

class androidtv.basetv.basetv.BaseTV(adb, host, port=5555, adbkey='', adb_server_ip='', adb_server_port=5037, state_detection_rules=None)[source]

Bases: object

Base class for representing an Android TV / Fire TV device.

The state_detection_rules parameter is of the format:

state_detection_rules = {'com.amazon.tv.launcher': ['idle'],
                         'com.netflix.ninja': ['media_session_state'],
                         'com.ellation.vrv': ['audio_state'],
                         'com.hulu.plus': [{'playing': {'wake_lock_size' : 4}},
                                           {'paused': {'wake_lock_size': 2}}],
                         'com.plexapp.android': [{'paused': {'media_session_state': 3, 'wake_lock_size': 1}},
                                                 {'playing': {'media_session_state': 3}},
                                                 'idle']}

The keys are app IDs, and the values are lists of rules that are evaluated in order.

VALID_STATES

VALID_STATES = ('idle', 'off', 'playing', 'paused', 'standby')

Valid rules:

  • 'idle', 'playing', 'paused', 'standby', or 'off' = always report the specified state when this app is open

  • 'media_session_state' = try to use the media_session_state() property to determine the state

  • 'audio_state' = try to use the audio_state() property to determine the state

  • {'<VALID_STATE>': {'<PROPERTY1>': VALUE1, '<PROPERTY2>': VALUE2, ...}} = check if each of the properties is equal to the specified value, and if so return the state

    • The valid properties are 'media_session_state', 'audio_state', and 'wake_lock_size'

Parameters:
  • adb (ADBPythonSync, ADBServerSync, ADBPythonAsync, ADBServerAsync) – The handler for ADB commands

  • host (str) – The address of the device; may be an IP address or a host name

  • port (int) – The device port to which we are connecting (default is 5555)

  • adbkey (str) – The path to the adbkey file for ADB authentication

  • adb_server_ip (str) – The IP address of the ADB server

  • adb_server_port (int) – The port for the ADB server

  • state_detection_rules (dict, None) – A dictionary of rules for determining the state (see above)

DEVICE_ENUM = 0
static _audio_output_device(stream_music)[source]

Get the current audio playback device from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters:

stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio

Returns:

The current audio playback device, or None if it could not be determined

Return type:

str, None

static _audio_state(audio_state_response)[source]

Parse the audio_state() property from the ADB shell output.

Parameters:

audio_state_response (str, None) – The output from the ADB command androidtv.basetv.basetv.BaseTV._cmd_audio_state`

Returns:

The audio state, or None if it could not be determined

Return type:

str, None

_cmd_audio_state()[source]

Get the command used to retrieve the current audio state for this device.

Returns:

The device-specific ADB shell command used to determine the current audio state

Return type:

str

_cmd_current_app()[source]

Get the command used to retrieve the current app for this device.

Returns:

The device-specific ADB shell command used to determine the current app

Return type:

str

_cmd_current_app_media_session_state()[source]

Get the command used to retrieve the current app and media session state for this device.

Returns:

The device-specific ADB shell command used to determine the current app and media session state

Return type:

str

_cmd_hdmi_input()[source]

Get the command used to retrieve the current HDMI input for this device.

Returns:

The device-specific ADB shell command used to determine the current HDMI input

Return type:

str

_cmd_launch_app(app)[source]

Get the command to launch the specified app for this device.

Parameters:

app (str) – The app that will be launched

Returns:

The device-specific command to launch the app

Return type:

str

_cmd_running_apps()[source]

Get the command used to retrieve the running apps for this device.

Returns:

The device-specific ADB shell command used to determine the running apps

Return type:

str

_cmd_turn_off()[source]

Get the command used to turn off this device.

Returns:

The device-specific ADB shell command used to turn off the device

Return type:

str

_cmd_turn_on()[source]

Get the command used to turn on this device.

Returns:

The device-specific ADB shell command used to turn on the device

Return type:

str

_cmd_volume_set(new_volume)[source]

Get the command used to set volume for this device.

Parameters:

new_volume (int) – The new volume level

Returns:

The device-specific ADB shell command used to set volume

Return type:

str

static _conditions_are_true(conditions, media_session_state=None, wake_lock_size=None, audio_state=None)[source]

Check whether the conditions in conditions are true.

Parameters:
  • conditions (dict) – A dictionary of conditions to be checked (see the state_detection_rules parameter in BaseTV)

  • media_session_state (int, None) – The media_session_state() property

  • wake_lock_size (int, None) – The wake_lock_size() property

  • audio_state (str, None) – The audio_state() property

Returns:

Whether or not all the conditions in conditions are true

Return type:

bool

static _current_app(current_app_response)[source]

Get the current app from the output of the command androidtv.basetv.basetv.BaseTV._cmd_current_app.

Parameters:

current_app_response (str, None) – The output from the ADB command androidtv.basetv.basetv.BaseTV._cmd_current_app

Returns:

The current app, or None if it could not be determined

Return type:

str, None

_current_app_media_session_state(current_app_media_session_state_response)[source]

Get the current app and the media session state properties from the output of androidtv.basetv.basetv.BaseTV._cmd_current_app_media_session_state.

Parameters:

current_app_media_session_state_response (str, None) – The output of androidtv.basetv.basetv.BaseTV._cmd_current_app_media_session_state

Returns:

  • current_app (str, None) – The current app, or None if it could not be determined

  • media_session_state (int, None) – The state from the output of the ADB shell command, or None if it could not be determined

_custom_state_detection(current_app=None, media_session_state=None, wake_lock_size=None, audio_state=None)[source]

Use the rules in self._state_detection_rules to determine the state.

Parameters:
  • current_app (str, None) – The current_app() property

  • media_session_state (int, None) – The media_session_state() property

  • wake_lock_size (int, None) – The wake_lock_size() property

  • audio_state (str, None) – The audio_state() property

Returns:

The state, if it could be determined using the rules in self._state_detection_rules; otherwise, None

Return type:

str, None

static _get_hdmi_input(hdmi_response)[source]

Get the HDMI input from the from the ADB shell output`.

Parameters:

hdmi_response (str, None) – The output from the ADB command androidtv.basetv.basetv.BaseTV._cmd_hdmi_input`

Returns:

The HDMI input, or None if it could not be determined

Return type:

str, None

static _get_installed_apps(installed_apps_response)[source]

Get the installed apps from the output of androidtv.constants.CMD_INSTALLED_APPS.

Parameters:

installed_apps_response (str, None) – The output of androidtv.constants.CMD_INSTALLED_APPS

Returns:

A list of the installed apps, or None if it could not be determined

Return type:

list, None

static _is_volume_muted(stream_music)[source]

Determine whether or not the volume is muted from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters:

stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio

Returns:

Whether or not the volume is muted, or None if it could not be determined

Return type:

bool, None

_parse_device_properties(properties)[source]

Return a dictionary of device properties.

Parameters:
  • properties (str, None) – The output of the ADB command that retrieves the device properties

  • attribute (This method fills in the device_properties) –

  • keys (which is a dictionary with) –

  • 'serialno'

  • 'manufacturer'

  • 'model'

  • 'sw_version' (and) –

static _parse_getevent_line(line)[source]

Parse a line of the output received in learn_sendevent.

Parameters:

line (str) – A line of output from learn_sendevent

Returns:

The properly formatted sendevent command

Return type:

str

static _parse_mac_address(mac_response)[source]

Parse a MAC address from the ADB shell response.

Parameters:

mac_response (str, None) – The response from the MAC address ADB shell command

Returns:

The parsed MAC address, or None if it could not be determined

Return type:

str, None

static _parse_stream_music(stream_music_raw)[source]

Parse the output of the command androidtv.constants.CMD_STREAM_MUSIC.

Parameters:

stream_music_raw (str, None) – The output of the command androidtv.constants.CMD_STREAM_MUSIC

Returns:

The STREAM_MUSIC block from the output of androidtv.constants.CMD_STREAM_MUSIC, or None if it could not be determined

Return type:

str, None

static _remove_adb_shell_prefix(cmd)[source]

Remove the ‘adb shell ‘ prefix from cmd, if present.

Parameters:

cmd (str) – The ADB shell command

Returns:

cmd with the ‘adb shell ‘ prefix removed, if it was present

Return type:

str

static _running_apps(running_apps_response)[source]

Get the running apps from the output of androidtv.constants.CMD_RUNNING_APPS.

Parameters:

running_apps_response (str, None) – The output of androidtv.constants.CMD_RUNNING_APPS

Returns:

A list of the running apps, or None if it could not be determined

Return type:

list, None

static _screen_on_awake_wake_lock_size(output)[source]

Check if the screen is on and the device is awake, and get the wake lock size.

Parameters:

output (str, None) – The output from androidtv.constants.CMD_SCREEN_ON_AWAKE_WAKE_LOCK_SIZE

Returns:

  • bool, None – Whether or not the device is on, or None if it could not be determined

  • bool, None – Whether or not the device is awake (screensaver is not running), or None if it could not be determined

  • int, None – The size of the current wake lock, or None if it could not be determined

_volume(stream_music, audio_output_device)[source]

Get the absolute volume level from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters:
  • stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio

  • audio_output_device (str, None) – The current audio playback device

Returns:

The absolute volume level, or None if it could not be determined

Return type:

int, None

_volume_level(volume)[source]

Get the relative volume level from the absolute volume level.

Parameters:

volume (int, None) – The absolute volume level

Returns:

The volume level (between 0 and 1), or None if it could not be determined

Return type:

float, None

static _wake_lock_size(wake_lock_size_response)[source]

Get the size of the current wake lock from the output of androidtv.constants.CMD_WAKE_LOCK_SIZE.

Parameters:

wake_lock_size_response (str, None) – The output of androidtv.constants.CMD_WAKE_LOCK_SIZE

Returns:

The size of the current wake lock, or None if it could not be determined

Return type:

int, None

property available

Whether the ADB connection is intact.

Returns:

Whether or not the ADB connection is intact

Return type:

bool

customize_command(custom_command, value)[source]

Customize a command used to retrieve properties.

Parameters:
  • custom_command (str) – The name of the command that will be customized; it must be in constants.CUSTOMIZABLE_COMMANDS

  • value (str, None) – The custom ADB command that will be used, or None if the custom command should be deleted

androidtv.basetv.basetv.state_detection_rules_validator(rules, exc=<class 'KeyError'>)[source]

Validate the rules (i.e., the state_detection_rules value) for a given app ID (i.e., a key in state_detection_rules).

For each rule in rules, this function checks that:

See BaseTV for more info about the state_detection_rules parameter.

Parameters:
  • rules (list) – A list of the rules that will be used to determine the state

  • exc (Exception) – The exception that will be raised if a rule is invalid

Returns:

rules – The provided list of rules

Return type:

list