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

Base class representing an Apple TV.

Listener interface: pyatv.interfaces.DeviceListener

Initialize a new StateProducer instance.




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 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 stream -> Stream

Return API for streaming media.


def close(self) -> NoneType

Close connection and release allocated resources.

async def connect(self) -> NoneType

Initiate connection to device.

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

Inherited members

class Apps

Base class for app handling.


  • pyatv.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: str) -> NoneType
Feature: FeatureName.LaunchApp, Supported by: Protocol.Companion

Launch an app based on bundle ID.

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

Base class for audio functionality.

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


  • pyatv.raop.RaopAudio

Instance variables

var volume -> float
Feature: FeatureName.Volume, Supported by: Protocol.RAOP

Return current volume level.


async def set_volume(self, level: float) -> NoneType
Feature: FeatureName.SetVolume, Supported by: Protocol.RAOP

Change current volume level.

class BaseService (identifier: Optional[str], protocol: Protocol, port: int, properties: Optional[Mapping[str, str]])

Base class for protocol services.

Initialize a new BaseService.


Instance variables

var identifier -> Optional[str]

Return unique identifier associated with this service.


def merge(self, other) -> NoneType

Merge with other service of same type.

class DeviceInfo (os: OperatingSystem, version: Optional[str], build_number: Optional[str], model: DeviceModel, mac: Optional[str])

General information about device.

Initialize a new DeviceInfo instance.

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 operating_system -> OperatingSystem

Operating system running on device.

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) -> NoneType

Device connection was (intentionally) closed.

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

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.airplay.AirPlayFeatures
  • pyatv.companion.CompanionFeatures
  • pyatv.dmap.DmapFeatures
  • pyatv.mrp.MrpFeatures
  • pyatv.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)

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 Metadata

Base class for retrieving metadata from an Apple TV.


  • pyatv.dmap.DmapMetadata
  • pyatv.mrp.MrpMetadata
  • pyatv.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 PairingHandler (session_manager:, service: Optional[BaseService])

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

Initialize a new instance of PairingHandler.


  • abc.ABC


  • pyatv.airplay.pairing.AirPlayPairingHandler
  • pyatv.companion.pairing.CompanionPairingHandler
  • pyatv.dmap.pairing.DmapPairingHandler
  • pyatv.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) -> NoneType

Start pairing process.

async def close(self) -> NoneType

Call to free allocated resources after pairing.

async def finish(self) -> NoneType

Stop pairing process.

def pin(self, pin) -> NoneType

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)

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 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

Base class for retrieving power state from an Apple TV.

Listener interface: pyatv.interfaces.PowerListener

Initialize a new StateProducer instance.



  • pyatv.companion.CompanionPower
  • pyatv.mrp.MrpPower

Instance variables

var power_state -> PowerState
Feature: FeatureName.PowerState, Supported by: Protocol.MRP

Return device power state.


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

Turn device off.

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

Turn device on.

Inherited members

class PowerListener

Listener interface for power updates.


  • abc.ABC


  • pyatv.scripts.atvscript.PowerPrinter


def powerstate_update(self, old_state: PowerState, new_state: PowerState)

Device power state was updated.

class PushListener

Listener interface for push updates.


  • abc.ABC


  • pyatv.scripts.atvremote.PushListener
  • pyatv.scripts.atvscript.PushPrinter


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

Inform about an error when updating play status.

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

Inform about changes to what is currently playing.

class PushUpdater (loop:

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

Listener interface: PushListener

Initialize a new PushUpdater.



  • pyatv.dmap.DmapPushUpdater
  • pyatv.mrp.MrpPushUpdater
  • pyatv.raop.RaopPushUpdater

Instance variables

var active -> bool

Return if push updater has been started.


def post_update(self, playing: Playing) -> NoneType

Post an update to listener.

def start(self, initial_delay: int = 0) -> NoneType

Begin to listen to updates.

If an error occurs, start must be called again.

def stop(self) -> NoneType

No longer forward updates to listener.

Inherited members

class RemoteControl

Base class for API used to control an Apple TV.


  • pyatv.companion.CompanionRemoteControl
  • pyatv.dmap.DmapRemoteControl
  • pyatv.mrp.MrpRemoteControl
  • pyatv.raop.RaopRemoteControl


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

Press key down.

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

Press key home.

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

Hold key home.

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

Press key left.

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

Press key menu.

async def next(self) -> NoneType
Feature: FeatureName.Next, Supported by: Protocol.DMAP, Protocol.MRP

Press key next.

async def pause(self) -> NoneType
Feature: FeatureName.Pause, Supported by: Protocol.DMAP, Protocol.MRP

Press key play.

async def play(self) -> NoneType
Feature: FeatureName.Play, Supported by: Protocol.DMAP, Protocol.MRP

Press key play.

async def play_pause(self) -> NoneType

Toggle between play and pause.

async def previous(self) -> NoneType

Press key previous.

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

Press key right.

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

Press key select.

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

Seek in the current playing media.

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

Change repeat state.

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

Change shuffle mode to on or off.

async def skip_backward(self) -> NoneType

Skip backwards a time interval.

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

async def skip_forward(self) -> NoneType

Skip forward a time interval.

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

async def stop(self) -> NoneType
Feature: FeatureName.Stop, Supported by: Protocol.DMAP, Protocol.MRP

Press key stop.

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

Suspend the device.

async def top_menu(self) -> NoneType

Go to main menu (long press menu).

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

Press key up.

async def volume_down(self) -> NoneType

Press key volume down.

async def volume_up(self) -> NoneType

Press key volume up.

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

Wake up the device.

class StateProducer

Base class for objects announcing state changes to a listener.

Initialize a new StateProducer instance.


Instance variables

var listener

Return current listener object.

class Stream

Base class for stream functionality.


  • pyatv.airplay.AirPlayStream
  • pyatv.raop.RaopStream


def close(self) -> NoneType

Close connection and release allocated resources.

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

Play media from an URL on the device.

async def stream_file(self, file: Union[str, _io.BufferedReader], **kwargs) -> NoneType
Feature: FeatureName.StreamFile, Supported by: Protocol.RAOP

Stream local file to device.