Module pyatv.interface

Public interface exposed by library.

This module contains all the interfaces that represents a generic Apple TV device and all its features.


def retrieve_commands(obj: object)

Retrieve all commands and help texts from an API object.


class App (name: Optional[str], identifier: str)

Information about an app.

Initialize a new App instance.

Instance variables

var identifier -> str

Return a unique bundle id for the app.

var name -> Optional[str]

User friendly name of app.

class AppleTV (max_calls: int = 0)

Base class representing an Apple TV.

Listener interface: pyatv.interfaces.DeviceListener

Initialize a new StateProducer instance.


  • abc.ABC
  • typing.Generic


  • pyatv.core.facade.FacadeAppleTV

Instance variables

var apps -> Apps

Return apps interface.

var audio -> Audio

Return audio interface.

var device_info -> DeviceInfo

Return API for device information.

var features -> Features

Return features interface.

var keyboard -> Keyboard

Return keyboard interface.

var metadata -> Metadata

Return API for retrieving metadata from the Apple TV.

var power -> Power

Return API for power management.

var push_updater -> PushUpdater

Return API for handling push update from the Apple TV.

var remote_control -> RemoteControl

Return API for controlling the Apple TV.

var service -> BaseService

Return service used to connect to the Apple TV.

var settings -> Settings

Return device settings used by pyatv.

var stream -> Stream

Return API for streaming media.

var user_accounts -> UserAccounts

Return user accounts interface.


def close(self) -> Set[_asyncio.Task]

Close connection and release allocated resources.

async def connect(self) -> None

Initiate connection to device.

No need to call it yourself, it's done automatically.

class Apps

Base class for app handling.


  • pyatv.core.facade.FacadeApps
  • pyatv.protocols.companion.CompanionApps


async def app_list(self) -> List[App]
Feature: FeatureName.AppList, Supported by: Protocol.Companion

Fetch a list of apps that can be launched.

async def launch_app(self, bundle_id_or_url: str) -> None
Feature: FeatureName.LaunchApp, Supported by: Protocol.Companion

Launch an app based on bundle ID or URL.

class ArtworkInfo (bytes: bytes, mimetype: str, width: int, height: int)

Artwork information.


  • builtins.tuple

Instance variables

var bytes -> bytes

Alias for field number 0

var height -> int

Alias for field number 3

var mimetype -> str

Alias for field number 1

var width -> int

Alias for field number 2

class Audio (max_calls: int = 0)

Base class for audio functionality.

Volume level is managed in percent where 0 is muted and 100 is max volume.

Listener interface: pyatv.interfaces.AudioListener

Initialize a new StateProducer instance.


  • abc.ABC
  • typing.Generic


  • pyatv.core.facade.FacadeAudio
  • pyatv.protocols.companion.CompanionAudio
  • pyatv.protocols.dmap.DmapAudio
  • pyatv.protocols.mrp.MrpAudio
  • pyatv.protocols.raop.RaopAudio

Instance variables

var output_devices -> List[OutputDevice]
Feature: FeatureName.OutputDevices, Supported by: Protocol.MRP

Return current list of output device IDs.

var volume -> float

Return current volume level.

Range is in percent, i.e. [0.0-100.0].


async def add_output_devices(self, *devices: List[str]) -> None
Feature: FeatureName.AddOutputDevices, Supported by: Protocol.MRP

Add output devices.

async def remove_output_devices(self, *devices: List[str]) -> None

Remove output devices.

async def set_output_devices(self, *devices: List[str]) -> None
Feature: FeatureName.SetOutputDevices, Supported by: Protocol.MRP

Set output devices.

async def set_volume(self, level: float) -> None

Change current volume level.

Range is in percent, i.e. [0.0-100.0].

async def volume_down(self) -> None

Decrease volume by one step.

Step size is device dependent, but usually around 2.5% of the total volume range. It is not necessarily linear.

Call will block until volume change has been acknowledged by the device (when possible and supported).

async def volume_up(self) -> None

Increase volume by one step.

Step size is device dependent, but usually around 2,5% of the total volume range. It is not necessarily linear.

Call will block until volume change has been acknowledged by the device (when possible and supported).

class AudioListener

Listener interface for audio updates.


  • abc.ABC


  • pyatv.scripts.atvscript.AudioPrinter


def outputdevices_update(self, old_devices: List[OutputDevice], new_devices: List[OutputDevice]) -> None

Output devices were updated.

def volume_update(self, old_level: float, new_level: float) -> None

Device volume was updated.

class BaseConfig (properties: Mapping[str, Mapping[str, Any]])

Representation of a device configuration.

An instance of this class represents a single device. A device can have several services depending on the protocols it supports, e.g. DMAP or AirPlay.

Initialize a new BaseConfig instance.


  • abc.ABC


Instance variables

var address -> ipaddress.IPv4Address

IP address of device.

var all_identifiers -> List[str]

Return all unique identifiers for this device.

var deep_sleep -> bool

If device is in deep sleep.

var device_info -> DeviceInfo

Return general device information.

var identifier -> Optional[str]

Return the main identifier associated with this device.

var name -> str

Name of device.

var properties -> Mapping[str, Mapping[str, str]]

Return Zeroconf properties.

var ready -> bool

Return if configuration is ready, (at least one service with identifier).

var services -> List[BaseService]

Return all supported services.


def add_service(self, service: BaseService) -> None

Add a new service.

If the service already exists, it will be merged.

def apply(self, settings: Settings) -> None

Apply settings to configuration.

def get_service(self, protocol: Protocol) -> Optional[BaseService]

Look up a service based on protocol.

If a service with the specified protocol is not available, None is returned.

def main_service(self, protocol: Optional[Protocol] = None) -> BaseService

Return suggested service used to establish connection.

def set_credentials(self, protocol: Protocol, credentials: str) -> bool

Set credentials for a protocol if it exists.

class BaseService (identifier: Optional[str], protocol: Protocol, port: int, properties: Optional[Mapping[str, str]], credentials: Optional[str] = None, password: Optional[str] = None, enabled: bool = True)

Base class for protocol services.

Initialize a new BaseService.


  • abc.ABC


Instance variables

var enabled -> bool

Return True if service is enabled.

var identifier -> Optional[str]

Return unique identifier associated with this service.

var pairing -> PairingRequirement

Return if pairing is required by service.

var port -> int

Return service port number.

var properties -> Mapping[str, str]

Return service Zeroconf properties.

var protocol -> Protocol

Return protocol type.

var requires_password -> bool

Return if a password is required to access service.


def apply(self, settings: Mapping[str, Any]) -> None

Apply settings to service.

Expects the same format as returned by settings() method. Unknown properties are silently ignored. Settings with a None value are also ignore (keeps original value).

def merge(self, other) -> None

Merge with other service of same type.

Merge will only include credentials, password and properties.

def settings(self) -> Mapping[str, Any]

Return settings and their values.

class DeviceInfo (device_info: Mapping[str, Any])

General information about device.

Initialize a new DeviceInfo instance.

Class variables


Instance variables

var build_number -> Optional[str]

Operating system build number, e.g. 17K795.

var mac -> Optional[str]

Device MAC address.

var model -> DeviceModel

Hardware model name, e.g. 3, 4 or 4K.

var model_str -> str

Return model name as string.

This property will return the model name as a string and fallback to raw_model if it is not available.

var operating_system -> OperatingSystem

Operating system running on device.

var output_device_id -> Optional[str]

Output device identifier.

var raw_model -> Optional[str]

Return raw model description.

If DeviceInfo.model returns DeviceModel.Unknown then this property contains the raw model string (if any is available).

var version -> Optional[str]

Operating system version.

class DeviceListener

Listener interface for generic device updates.


  • abc.ABC


  • pyatv.scripts.atvremote.DeviceListener
  • pyatv.scripts.atvscript.DevicePrinter


def connection_closed(self) -> None

Device connection was (intentionally) closed.

def connection_lost(self, exception: Exception) -> None

Device was unexpectedly disconnected.

class FeatureInfo (state: FeatureState, options: Optional[Dict[str, object]] = {})

Feature state and options.


  • builtins.tuple

Instance variables

var options -> Optional[Dict[str, object]]

Alias for field number 1

var state -> FeatureState

Alias for field number 0

class Features

Base class for supported feature functionality.


  • pyatv.core.facade.FacadeFeatures
  • pyatv.protocols.airplay.AirPlayFeatures
  • pyatv.protocols.companion.CompanionFeatures
  • pyatv.protocols.dmap.DmapFeatures
  • pyatv.protocols.mrp.MrpFeatures
  • pyatv.protocols.raop.RaopFeatures


def all_features(self, include_unsupported=False) -> Dict[FeatureNameFeatureInfo]

Return state of all features.

def get_feature(self, feature_name: FeatureName) -> FeatureInfo

Return current state of a feature.

def in_state(self, states: Union[List[FeatureState], FeatureState], *feature_names: FeatureName) -> bool

Return if features are in a specific state.

This method will return True if all given features are in the state specified by "states". If "states" is a list of states, it is enough for the feature to be in one of the listed states.

class Keyboard (max_calls: int = 0)

Base class for keyboard handling.

Listener interface: pyatv.interfaces.KeyboardListener

Initialize a new StateProducer instance.


  • abc.ABC
  • typing.Generic


  • pyatv.core.facade.FacadeKeyboard
  • pyatv.protocols.companion.CompanionKeyboard

Instance variables

var text_focus_state -> KeyboardFocusState

Return keyboard focus state.


async def text_append(self, text: str) -> None
Feature: FeatureName.TextAppend, Supported by: Protocol.Companion

Input text into virtual keyboard.

async def text_clear(self) -> None
Feature: FeatureName.TextClear, Supported by: Protocol.Companion

Clear virtual keyboard text.

async def text_get(self) -> Optional[str]
Feature: FeatureName.TextGet, Supported by: Protocol.Companion

Get current virtual keyboard text.

async def text_set(self, text: str) -> None
Feature: FeatureName.TextSet, Supported by: Protocol.Companion

Replace text in virtual keyboard.

class KeyboardListener

Listener interface for keyboard updates.


  • abc.ABC


  • pyatv.scripts.atvscript.KeyboardPrinter


def focusstate_update(self, old_state: KeyboardFocusState, new_state: KeyboardFocusState) -> None

Keyboard focus state was updated.

class MediaMetadata (title: Optional[str] = None, artist: Optional[str] = None, album: Optional[str] = None, artwork: Optional[bytes] = None, duration: Optional[float] = None)

Container for media (e.g. audio or video) metadata.

Class variables

var album -> Optional[str]
var artist -> Optional[str]
var artwork -> Optional[bytes]
var duration -> Optional[float]
var title -> Optional[str]
class Metadata

Base class for retrieving metadata from an Apple TV.


  • pyatv.core.facade.FacadeMetadata
  • pyatv.protocols.dmap.DmapMetadata
  • pyatv.protocols.mrp.MrpMetadata
  • pyatv.protocols.raop.RaopMetadata

Instance variables

var app -> Optional[App]
Feature: FeatureName.App, Supported by: Protocol.MRP

Return information about current app playing something.

Do note that this property returns which app is currently playing something and not which app is currently active. If nothing is playing, the corresponding feature will be unavailable.

var artwork_id -> str

Return a unique identifier for current artwork.

var device_id -> Optional[str]

Return a unique identifier for current device.


async def artwork(self, width: Optional[int] = 512, height: Optional[int] = None) -> Optional[ArtworkInfo]

Return artwork for what is currently playing (or None).

The parameters "width" and "height" makes it possible to request artwork of a specific size. This is just a request, the device might impose restrictions and return artwork of a different size. Set both parameters to None to request default size. Set one of them and let the other one be None to keep original aspect ratio.

async def playing(self) -> Playing

Return what is currently playing.

class OutputDevice (name: Optional[str], identifier: str)

Information about an output device.

Initialize a new OutputDevice instance.

Instance variables

var identifier -> str

Return a unique id for the output device.

var name -> Optional[str]

User friendly name of output device.

class PairingHandler (session_manager:, service: BaseService)

Base class for API used to pair with an Apple TV.

Initialize a new instance of PairingHandler.


  • abc.ABC


  • pyatv.protocols.airplay.pairing.AirPlayPairingHandler
  • pyatv.protocols.companion.pairing.CompanionPairingHandler
  • pyatv.protocols.dmap.pairing.DmapPairingHandler
  • pyatv.protocols.mrp.pairing.MrpPairingHandler

Instance variables

var device_provides_pin -> bool

Return True if remote device presents PIN code, else False.

var has_paired -> bool

If a successful pairing has been performed.

The value will be reset when stop() is called.

var service -> BaseService

Return service used for pairing.


async def begin(self) -> None

Start pairing process.

async def close(self) -> None

Call to free allocated resources after pairing.

async def finish(self) -> None

Stop pairing process.

def pin(self, pin) -> None

Pin code used for pairing.

class Playing (media_type: MediaType = MediaType.Unknown, device_state: DeviceState = DeviceState.Idle, title: Optional[str] = None, artist: Optional[str] = None, album: Optional[str] = None, genre: Optional[str] = None, total_time: Optional[int] = None, position: Optional[int] = None, shuffle: Optional[ShuffleState] = None, repeat: Optional[RepeatState] = None, hash: Optional[str] = None, series_name: Optional[str] = None, season_number: Optional[int] = None, episode_number: Optional[int] = None, content_identifier: Optional[str] = None)

Base class for retrieving what is currently playing.

Initialize a new Playing instance.


  • abc.ABC

Instance variables

var album -> Optional[str]
Feature: FeatureName.Album, Supported by:

Album of the currently playing song.

var artist -> Optional[str]
Feature: FeatureName.Artist, Supported by:

Artist of the currently playing song.

var content_identifier -> Optional[str]
Feature: FeatureName.ContentIdentifier, Supported by:

Content identifier (app specific).

var device_state -> DeviceState

Device state, e.g. playing or paused.

var episode_number -> Optional[int]
Feature: FeatureName.EpisodeNumber, Supported by:

Episode number of TV series.

var genre -> Optional[str]
Feature: FeatureName.Genre, Supported by:

Genre of the currently playing song.

var hash -> str

Create a unique hash for what is currently playing.

The hash is based on title, artist, album and total time. It should always be the same for the same content, but it is not guaranteed.

var media_type -> MediaType

Type of media is currently playing, e.g. video, music.

var position -> Optional[int]
Feature: FeatureName.Position, Supported by:

Position in the playing media (seconds).

var repeat -> Optional[RepeatState]
Feature: FeatureName.Repeat, Supported by:

Repeat mode.

var season_number -> Optional[int]
Feature: FeatureName.SeasonNumber, Supported by:

Season number of TV series.

var series_name -> Optional[str]
Feature: FeatureName.SeriesName, Supported by:

Title of TV series.

var shuffle -> Optional[ShuffleState]
Feature: FeatureName.Shuffle, Supported by:

If shuffle is enabled or not.

var title -> Optional[str]
Feature: FeatureName.Title, Supported by:

Title of the current media, e.g. movie or song name.

var total_time -> Optional[int]
Feature: FeatureName.TotalTime, Supported by:

Total play time in seconds.

class Power (max_calls: int = 0)

Base class for retrieving power state from an Apple TV.

Listener interface: pyatv.interfaces.PowerListener

Initialize a new StateProducer instance.


  • abc.ABC
  • typing.Generic


  • pyatv.core.facade.FacadePower
  • pyatv.protocols.companion.CompanionPower
  • pyatv.protocols.mrp.MrpPower

Instance variables

var power_state -> PowerState

Return device power state.


async def turn_off(self, await_new_state: bool = False) -> None

Turn device off.

async def turn_on(self, await_new_state: bool = False) -> None

Turn device on.

class PowerListener

Listener interface for power updates.


  • abc.ABC


  • pyatv.core.facade.FacadePower
  • pyatv.scripts.atvremote.PowerListener
  • pyatv.scripts.atvscript.PowerPrinter


def powerstate_update(self, old_state: PowerState, new_state: PowerState) -> None

Device power state was updated.

class PushListener

Listener interface for push updates.


  • abc.ABC


  • pyatv.core.facade.FacadePushUpdater
  • pyatv.scripts.atvremote.PushListener
  • pyatv.scripts.atvscript.PushPrinter


def playstatus_error(self, updater, exception: Exception) -> None

Inform about an error when updating play status.

def playstatus_update(self, updater, playstatus: Playing) -> None

Inform about changes to what is currently playing.

class PushUpdater (max_calls: int = 0)

Base class for push/async updates from an Apple TV.

A PushUpdater shall only publish update in case the state actually changes.

Listener interface: PushListener.

Initialize a new StateProducer instance.


  • abc.ABC
  • typing.Generic


  • pyatv.core.AbstractPushUpdater
  • pyatv.core.facade.FacadePushUpdater

Instance variables

var active -> bool

Return if push updater has been started.


def start(self, initial_delay: int = 0) -> None
Feature: FeatureName.PushUpdates, Supported by:

Begin to listen to updates.

If an error occurs, start must be called again.

def stop(self) -> None

No longer forward updates to listener.

class RemoteControl

Base class for API used to control an Apple TV.


  • pyatv.core.facade.FacadeRemoteControl
  • pyatv.protocols.airplay.AirPlayRemoteControl
  • pyatv.protocols.companion.CompanionRemoteControl
  • pyatv.protocols.dmap.DmapRemoteControl
  • pyatv.protocols.mrp.MrpRemoteControl
  • pyatv.protocols.raop.RaopRemoteControl


async def channel_down(self) -> None

Select previous channel.

async def channel_up(self) -> None
Feature: FeatureName.ChannelUp, Supported by: Protocol.Companion

Select next channel.

async def down(self, action: InputAction = InputAction.SingleTap) -> None

Press key down.

async def home(self, action: InputAction = InputAction.SingleTap) -> None

Press key home.

async def home_hold(self) -> None
Feature: FeatureName.HomeHold, Supported by: Protocol.MRP

Hold key home.

async def left(self, action: InputAction = InputAction.SingleTap) -> None

Press key left.

async def menu(self, action: InputAction = InputAction.SingleTap) -> None

Press key menu.

async def next(self) -> None

Press key next.

async def pause(self) -> None

Press key pause.

async def play(self) -> None

Press key play.

async def play_pause(self) -> None

Toggle between play and pause.

async def previous(self) -> None

Press key previous.

async def right(self, action: InputAction = InputAction.SingleTap) -> None

Press key right.

async def screensaver(self) -> None

Activate screen saver..

async def select(self, action: InputAction = InputAction.SingleTap) -> None

Press key select.

async def set_position(self, pos: int) -> None

Seek in the current playing media.

async def set_repeat(self, repeat_state: RepeatState) -> None

Change repeat state.

async def set_shuffle(self, shuffle_state: ShuffleState) -> None

Change shuffle mode to on or off.

async def skip_backward(self) -> None

Skip backwards a time interval.

Skip interval is typically 15-30s, but is decided by the app.

async def skip_forward(self) -> None

Skip forward a time interval.

Skip interval is typically 15-30s, but is decided by the app.

async def stop(self) -> None

Press key stop.

async def suspend(self) -> None
Feature: FeatureName.Suspend, Supported by: Protocol.MRP

Suspend the device.

DEPRECATED: Use Power.turn_off() instead.

async def top_menu(self) -> None

Go to main menu (long press menu).

async def up(self, action: InputAction = InputAction.SingleTap) -> None

Press key up.

async def volume_down(self) -> None

Press key volume down.

DEPRECATED: Use Audio.volume_down() instead.

async def volume_up(self) -> None

Press key volume up.

DEPRECATED: Use Audio.volume_up() instead.

async def wakeup(self) -> None
Feature: FeatureName.WakeUp, Supported by: Protocol.MRP

Wake up the device.

DEPRECATED: Use Power.turn_on() instead.

class Storage

Base class for storage modules.


  • abc.ABC


Instance variables

var settings -> Sequence[Settings]

Return settings for all devices.


async def get_settings(self, config: BaseConfig) -> Settings

Return settings for a specific configuration (device).

The returned Settings object is a reference to an object in the storage module. Changes made can/will be written back to the storage in case "save" is called.

If no settings exists for the current configuration, new settings are created automatically and returned. If the configuration does not contain any valid identitiers, DeviceIdMissingError will be raised.

async def load(self) -> None

Load settings from active storage.

async def remove_settings(self, settings: Settings) -> bool

Remove settings from storage.

Returns True if settings were removed, otherwise False.

async def save(self) -> None

Save settings to active storage.

async def update_settings(self, config: BaseConfig) -> None

Update settings based on config.

This method extracts settings from a configuration and writes them back to the storage.

class Stream

Base class for stream functionality.


  • pyatv.core.facade.FacadeStream
  • pyatv.protocols.airplay.AirPlayStream
  • pyatv.protocols.raop.RaopStream


def close(self) -> None

Close connection and release allocated resources.

async def play_url(self, url: str, **kwargs) -> None
Feature: FeatureName.PlayUrl, Supported by: Protocol.AirPlay

Play media from an URL on the device.

async def stream_file(self, file: Union[str, io.BufferedIOBase, asyncio.streams.StreamReader], /, metadata: Optional[MediaMetadata] = None, override_missing_metadata: bool = False, **kwargs) -> None
Feature: FeatureName.StreamFile, Supported by: Protocol.RAOP

Stream local or remote file to device.

Supports either local file paths or a HTTP(s) address.


class UserAccount (name: str, identifier: str)

Information about a user account.

Initialize a new UserAccount instance.

Instance variables

var identifier -> str

Return a unique id for the account.

var name -> Optional[str]

User name.

class UserAccounts

Base class for account handling.


  • pyatv.core.facade.FacadeUserAccounts
  • pyatv.protocols.companion.CompanionUserAccounts


async def account_list(self) -> List[UserAccount]

Fetch a list of user accounts that can be switched.

async def switch_account(self, account_id: str) -> None

Switch user account by account ID.