androidtv.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
(host, port=5555, adbkey='', adb_server_ip='', adb_server_port=5037, state_detection_rules=None, auth_timeout_s=0.1)[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': ['standby'], '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}}, 'standby']}
The keys are app IDs, and the values are lists of rules that are evaluated in order.
VALID_STATES = ('idle', 'off', 'playing', 'paused', 'standby')
Valid rules:
'standby'
,'playing'
,'paused'
,'idle'
, or'off'
= always report the specified state when this app is open'media_session_state'
= try to use themedia_session_state
property to determine the state'audio_state'
= try to use theaudio_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 stateThe valid properties are
'media_session_state'
,'audio_state'
, and'wake_lock_size'
- Parameters
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 authenticationadb_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)
auth_timeout_s (float) – Authentication timeout (in seconds)
-
static
_audio_output_device
(stream_music)[source]¶ Get the current audio playback device from the
STREAM_MUSIC
block fromadb shell dumpsys audio
.- Parameters
stream_music (str, None) – The
STREAM_MUSIC
block fromadb 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 output of the commandandroidtv.constants.CMD_AUDIO_STATE
.- Parameters
audio_state_response (str, None) – The output of the command
androidtv.constants.CMD_AUDIO_STATE
- Returns
The audio state, or
None
if it could not be determined- Return type
str, None
-
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 inBaseTV
)media_session_state (int, None) – The
media_session_state
propertywake_lock_size (int, None) – The
wake_lock_size
propertyaudio_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.constants.CMD_CURRENT_APP
.- Parameters
current_app_response (str, None) – The output from the ADB command
androidtv.constants.CMD_CURRENT_APP
- Returns
The current app, or
None
if it could not be determined- Return type
str, None
-
_current_app_media_session_state
(media_session_state_response)[source]¶ Get the current app and the media session state properties from the output of
androidtv.constants.CMD_MEDIA_SESSION_STATE_FULL
.- Parameters
media_session_state_response (str, None) – The output of
androidtv.constants.CMD_MEDIA_SESSION_STATE_FULL
- Returns
current_app (str, None) – The current app, or
None
if it could not be determinedmedia_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
propertymedia_session_state (int, None) – The
media_session_state
propertywake_lock_size (int, None) – The
wake_lock_size
propertyaudio_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
-
_get_stream_music
(stream_music_raw=None)[source]¶ Get the
STREAM_MUSIC
block from the output of the commandandroidtv.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 ofandroidtv.constants.CMD_STREAM_MUSIC
, orNone
if it could not be determined- Return type
str, None
-
static
_is_volume_muted
(stream_music)[source]¶ Determine whether or not the volume is muted from the
STREAM_MUSIC
block fromadb shell dumpsys audio
.- Parameters
stream_music (str, None) – The
STREAM_MUSIC
block fromadb shell dumpsys audio
- Returns
Whether or not the volume is muted, or
None
if it could not be determined- Return type
bool, None
-
static
_media_session_state
(media_session_state_response, current_app)[source]¶ Get the state from the output of
androidtv.constants.CMD_MEDIA_SESSION_STATE
.- Parameters
media_session_state_response (str, None) – The output of
androidtv.constants.CMD_MEDIA_SESSION_STATE
current_app (str, None) – The current app, or
None
if it could not be determined
- Returns
The state from the output of the ADB shell command, or
None
if it could not be determined- Return type
int, None
-
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
-
_send_intent
(pkg, intent, count=1)[source]¶ Send an intent to the device.
- Parameters
pkg (str) – The command that will be sent is
monkey -p <pkg> -c <intent> <count>; echo $?
intent (str) – The command that will be sent is
monkey -p <pkg> -c <intent> <count>; echo $?
count (int, str) – The command that will be sent is
monkey -p <pkg> -c <intent> <count>; echo $?
- Returns
A dictionary with keys
'output'
and'retcode'
, if they could be determined; otherwise, an empty dictionary- Return type
dict
-
_volume
(stream_music, audio_output_device)[source]¶ Get the absolute volume level from the
STREAM_MUSIC
block fromadb shell dumpsys audio
.- Parameters
stream_music (str, None) – The
STREAM_MUSIC
block fromadb 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
-
adb_close
()[source]¶ Close the ADB connection.
This only works for the Python ADB implementation (see
androidtv.adb_manager.ADBPython.close()
). For the ADB server approach, this doesn’t do anything (seeandroidtv.adb_manager.ADBServer.close()
).
-
adb_connect
(always_log_errors=True, auth_timeout_s=0.1)[source]¶ Connect to an Android TV / Fire TV device.
- Parameters
always_log_errors (bool) – If True, errors will always be logged; otherwise, errors will only be logged on the first failed reconnect attempt
auth_timeout_s (float) – Authentication timeout (in seconds)
- Returns
Whether or not the connection was successfully established and the device is available
- Return type
bool
-
adb_pull
(local_path, device_path)[source]¶ Pull a file from the device.
This calls
androidtv.adb_manager.ADBPython.pull()
orandroidtv.adb_manager.ADBServer.pull()
, depending on whether the Python ADB implementation or an ADB server is used for communicating with the device.- Parameters
local_path (str) – The path where the file will be saved
device_path (str) – The file on the device that will be pulled
-
adb_push
(local_path, device_path)[source]¶ Push a file to the device.
This calls
androidtv.adb_manager.ADBPython.push()
orandroidtv.adb_manager.ADBServer.push()
, depending on whether the Python ADB implementation or an ADB server is used for communicating with the device.- Parameters
local_path (str) – The file that will be pushed to the device
device_path (str) – The path where the file will be saved on the device
-
adb_shell
(cmd)[source]¶ Send an ADB command.
This calls
androidtv.adb_manager.ADBPython.shell()
orandroidtv.adb_manager.ADBServer.shell()
, depending on whether the Python ADB implementation or an ADB server is used for communicating with the device.- Parameters
cmd (str) – The ADB command to be sent
- Returns
The response from the device, if there is a response
- Return type
str, None
-
property
audio_output_device
¶ Get the current audio playback device.
- Returns
The current audio playback device, or
None
if it could not be determined- Return type
str, None
-
property
audio_state
¶ Check if audio is playing, paused, or idle.
- Returns
The audio state, as determined from the ADB shell command
androidtv.constants.CMD_AUDIO_STATE
, orNone
if it could not be determined- Return type
str, None
-
property
available
¶ Check whether the ADB connection is intact.
- Returns
Whether or not the ADB connection is intact
- Return type
bool
-
property
awake
¶ Check if the device is awake (screensaver is not running).
- Returns
Whether or not the device is awake (screensaver is not running)
- Return type
bool
-
property
current_app
¶ Return the current app.
- Returns
The ID of the current app, or
None
if it could not be determined- Return type
str, None
-
get_device_properties
()[source]¶ Return a dictionary of device properties.
- Returns
props – A dictionary with keys
'wifimac'
,'ethmac'
,'serialno'
,'manufacturer'
,'model'
, and'sw_version'
- Return type
dict
-
property
is_volume_muted
¶ Whether or not the volume is muted.
- Returns
Whether or not the volume is muted, or
None
if it could not be determined- Return type
bool, None
-
launch_app
(app)[source]¶ Launch an app.
- Parameters
app (str) – The ID of the app that will be launched
-
property
media_session_state
¶ Get the state from the output of
dumpsys media_session
.- Returns
The state from the output of the ADB shell command
dumpsys media_session
, orNone
if it could not be determined- Return type
int, None
Send menu action.
-
property
screen_on
¶ Check if the screen is on.
- Returns
Whether or not the device is on
- Return type
bool
-
set_volume_level
(volume_level)[source]¶ Set the volume to the desired level.
- Parameters
volume_level (float) – The new volume level (between 0 and 1)
- Returns
The new volume level (between 0 and 1), or
None
ifself.max_volume
could not be determined- Return type
float, None
-
start_intent
(uri)[source]¶ Start an intent on the device.
- Parameters
uri (str) – The intent that will be sent is
am start -a android.intent.action.VIEW -d <uri>
-
stop_app
(app)[source]¶ Stop an app.
- Parameters
app (str) – The ID of the app that will be stopped
- Returns
The output of the
am force-stop
ADB shell command, orNone
if the device is unavailable- Return type
str, None
-
property
volume
¶ Get the absolute volume level.
- Returns
The absolute volume level, or
None
if it could not be determined- Return type
int, None
-
volume_down
(current_volume_level=None)[source]¶ Send volume down action.
- Parameters
current_volume_level (float, None) – The current volume level (between 0 and 1); if it is not provided, it will be determined
- Returns
The new volume level (between 0 and 1), or
None
ifself.max_volume
could not be determined- Return type
float, None
-
property
volume_level
¶ Get the relative volume level.
- Returns
The volume level (between 0 and 1), or
None
if it could not be determined- Return type
float, None
-
volume_up
(current_volume_level=None)[source]¶ Send volume up action.
- Parameters
current_volume_level (float, None) – The current volume level (between 0 and 1); if it is not provided, it will be determined
- Returns
The new volume level (between 0 and 1), or
None
ifself.max_volume
could not be determined- Return type
float, None
-
property
wake_lock_size
¶ Get the size of the current wake lock.
- Returns
The size of the current wake lock, or
None
if it could not be determined- Return type
int, None
-
androidtv.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 instate_detection_rules
).For each
rule
inrules
, this function checks that:rule
is a string or a dictionaryIf
rule
is a string:Check that
rule
is inVALID_STATES
orVALID_STATE_PROPERTIES
If
rule
is a dictionary:Check that each key is in
VALID_STATES
Check that each value is a dictionary
Check that each key is in
VALID_PROPERTIES
Check that each value is of the right type, according to
VALID_PROPERTIES_TYPES
See
BaseTV
for more info about thestate_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