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.

Browse git

Functions

def retrieve_commands(obj: object)

Retrieve all commands and help texts from an API object.

Browse git

Classes

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

Information about an app.

Initialize a new App instance.

Browse git

Instance variables

var identifier -> str

Return a unique bundle id for the app.

Browse git

var name -> Optional[str]

User friendly name of app.

Browse git

class AppleTV

Base class representing an Apple TV.

Listener interface: pyatv.interfaces.DeviceListener

Initialize a new StateProducer instance.

Browse git

Ancestors

• abc.ABC
• StateProducer

Subclasses

• pyatv.support.facade.FacadeAppleTV

Instance variables

var apps -> Apps

Return apps interface.

Browse git

var audio -> Audio

Return audio interface.

Browse git

var device_info -> DeviceInfo

Return API for device information.

Browse git

var features -> Features

Return features interface.

Browse git

var metadata -> Metadata

Return API for retrieving metadata from the Apple TV.

Browse git

var power -> Power

Return API for power management.

Browse git

var push_updater -> PushUpdater

Return API for handling push update from the Apple TV.

Browse git

var remote_control -> RemoteControl

Return API for controlling the Apple TV.

Browse git

var service -> BaseService

Return service used to connect to the Apple TV.

Browse git

var stream -> Stream

Return API for streaming media.

Browse git

Methods

def close(self) -> NoneType

Close connection and release allocated resources.

Browse git

async def connect(self) -> NoneType

Initiate connection to device.

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

Browse git

Inherited members

• StateProducer:
  • listener

class Apps

Base class for app handling.

Browse git

Subclasses

• pyatv.companion.CompanionApps
• pyatv.support.facade.FacadeApps

Methods

async def app_list(self) -> List[App]

Feature: FeatureName.AppList, Supported by: Protocol.Companion

Fetch a list of apps that can be launched.

Browse git

async def launch_app(self, bundle_id: str) -> NoneType

Feature: FeatureName.LaunchApp, Supported by: Protocol.Companion

Launch an app based on bundle ID.

Browse git

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

Artwork information.

Browse git

Ancestors

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

Browse git

Subclasses

• pyatv.raop.RaopAudio
• pyatv.support.facade.FacadeAudio

Instance variables

var volume -> float

Feature: FeatureName.Volume, Supported by: Protocol.RAOP

Return current volume level.

Browse git

Methods

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

Feature: FeatureName.SetVolume, Supported by: Protocol.RAOP

Change current volume level.

Browse git

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

Base class for protocol services.

Initialize a new BaseService.

Browse git

Subclasses

• AirPlayService
• CompanionService
• DmapService
• MrpService
• RaopService

Instance variables

var identifier -> Optional[str]

Return unique identifier associated with this service.

Browse git

Methods

def merge(self, other) -> NoneType

Merge with other service of same type.

Browse git

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.

Browse git

Instance variables

var build_number -> Optional[str]

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

Browse git

var mac -> Optional[str]

Device MAC address.

Browse git

var model -> DeviceModel

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

Browse git

var operating_system -> OperatingSystem

Operating system running on device.

Browse git

var version -> Optional[str]

Operating system version.

Browse git

class DeviceListener

Listener interface for generic device updates.

Browse git

Ancestors

• abc.ABC

Subclasses

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

Methods

def connection_closed(self) -> NoneType

Device connection was (intentionally) closed.

Browse git

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

Device was unexpectedly disconnected.

Browse git

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

Feature state and options.

Browse git

Ancestors

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

Browse git

Subclasses

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

Methods

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

Return state of all features.

Browse git

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

Return current state of a feature.

Browse git

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.

Browse git

class Metadata

Base class for retrieving metadata from an Apple TV.

Browse git

Subclasses

• pyatv.dmap.DmapMetadata
• pyatv.mrp.MrpMetadata
• pyatv.raop.RaopMetadata
• pyatv.support.facade.FacadeMetadata

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.

Browse git

var artwork_id -> str

Return a unique identifier for current artwork.

Browse git

var device_id -> Optional[str]

Return a unique identifier for current device.

Browse git

Methods

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

Feature: FeatureName.Artwork, Supported by: Protocol.DMAP, Protocol.MRP

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.

Browse git

async def playing(self) -> Playing

Return what is currently playing.

Browse git

class PairingHandler (session_manager: pyatv.support.http.ClientSessionManager, service: Optional[BaseService])

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

Initialize a new instance of PairingHandler.

Browse git

Ancestors

• abc.ABC

Subclasses

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

Browse git

var has_paired -> bool

If a successful pairing has been performed.

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

Browse git

var service -> BaseService

Return service used for pairing.

Browse git

Methods

async def begin(self) -> NoneType

Start pairing process.

Browse git

async def close(self) -> NoneType

Call to free allocated resources after pairing.

Browse git

async def finish(self) -> NoneType

Stop pairing process.

Browse git

def pin(self, pin) -> NoneType

Pin code used for pairing.

Browse git

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.

Browse git

Ancestors

• abc.ABC

Instance variables

var album -> Optional[str]

Feature: FeatureName.Album, Supported by:

Album of the currently playing song.

Browse git

var artist -> Optional[str]

Feature: FeatureName.Artist, Supported by:

Artist of the currently playing song.

Browse git

var device_state -> DeviceState

Device state, e.g. playing or paused.

Browse git

var episode_number -> Optional[int]

Feature: FeatureName.EpisodeNumber, Supported by:

Episode number of TV series.

Browse git

var genre -> Optional[str]

Feature: FeatureName.Genre, Supported by:

Genre of the currently playing song.

Browse git

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.

Browse git

var media_type -> MediaType

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

Browse git

var position -> Optional[int]

Feature: FeatureName.Position, Supported by:

Position in the playing media (seconds).

Browse git

var repeat -> Optional[RepeatState]

Feature: FeatureName.Repeat, Supported by:

Repeat mode.

Browse git

var season_number -> Optional[int]

Feature: FeatureName.SeasonNumber, Supported by:

Season number of TV series.

Browse git

var series_name -> Optional[str]

Feature: FeatureName.SeriesName, Supported by:

Title of TV series.

Browse git

var shuffle -> Optional[ShuffleState]

Feature: FeatureName.Shuffle, Supported by:

If shuffle is enabled or not.

Browse git

var title -> Optional[str]

Feature: FeatureName.Title, Supported by:

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

Browse git

var total_time -> Optional[int]

Feature: FeatureName.TotalTime, Supported by:

Total play time in seconds.

Browse git

class Power

Base class for retrieving power state from an Apple TV.

Listener interface: pyatv.interfaces.PowerListener

Initialize a new StateProducer instance.

Browse git

Ancestors

• StateProducer

Subclasses

• pyatv.companion.CompanionPower
• pyatv.mrp.MrpPower
• pyatv.support.facade.FacadePower

Instance variables

var power_state -> PowerState

Feature: FeatureName.PowerState, Supported by: Protocol.MRP

Return device power state.

Browse git

Methods

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

Feature: FeatureName.TurnOff, Supported by: Protocol.Companion, Protocol.MRP

Turn device off.

Browse git

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

Feature: FeatureName.TurnOn, Supported by: Protocol.Companion, Protocol.MRP

Turn device on.

Browse git

Inherited members

• StateProducer:
  • listener

class PowerListener

Listener interface for power updates.

Browse git

Ancestors

• abc.ABC

Subclasses

• pyatv.scripts.atvscript.PowerPrinter
• pyatv.support.facade.FacadePower

Methods

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

Device power state was updated.

Browse git

class PushListener

Listener interface for push updates.

Browse git

Ancestors

• abc.ABC

Subclasses

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

Methods

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

Inform about an error when updating play status.

Browse git

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

Inform about changes to what is currently playing.

Browse git

class PushUpdater (loop: asyncio.events.AbstractEventLoop)

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

Listener interface: PushListener

Initialize a new PushUpdater.

Browse git

Ancestors

• abc.ABC
• StateProducer

Subclasses

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

Instance variables

var active -> bool

Return if push updater has been started.

Browse git

Methods

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

Post an update to listener.

Browse git

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

Feature: FeatureName.PushUpdates, Supported by: Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Begin to listen to updates.

If an error occurs, start must be called again.

Browse git

def stop(self) -> NoneType

No longer forward updates to listener.

Browse git

Inherited members

• StateProducer:
  • listener

class RemoteControl

Base class for API used to control an Apple TV.

Browse git

Subclasses

• pyatv.companion.CompanionRemoteControl
• pyatv.dmap.DmapRemoteControl
• pyatv.mrp.MrpRemoteControl
• pyatv.raop.RaopRemoteControl
• pyatv.support.facade.FacadeRemoteControl

Methods

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

Feature: FeatureName.Down, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key down.

Browse git

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

Feature: FeatureName.Home, Supported by: Protocol.Companion, Protocol.MRP

Press key home.

Browse git

async def home_hold(self) -> NoneType

Feature: FeatureName.HomeHold, Supported by: Protocol.MRP

Hold key home.

Browse git

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

Feature: FeatureName.Left, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key left.

Browse git

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

Feature: FeatureName.Menu, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key menu.

Browse git

async def next(self) -> NoneType

Feature: FeatureName.Next, Supported by: Protocol.DMAP, Protocol.MRP

Press key next.

Browse git

async def pause(self) -> NoneType

Feature: FeatureName.Pause, Supported by: Protocol.DMAP, Protocol.MRP

Press key play.

Browse git

async def play(self) -> NoneType

Feature: FeatureName.Play, Supported by: Protocol.DMAP, Protocol.MRP

Press key play.

Browse git

async def play_pause(self) -> NoneType

Feature: FeatureName.PlayPause, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Toggle between play and pause.

Browse git

async def previous(self) -> NoneType

Feature: FeatureName.Previous, Supported by: Protocol.DMAP, Protocol.MRP

Press key previous.

Browse git

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

Feature: FeatureName.Right, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key right.

Browse git

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

Feature: FeatureName.Select, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key select.

Browse git

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

Feature: FeatureName.SetPosition, Supported by: Protocol.DMAP, Protocol.MRP

Seek in the current playing media.

Browse git

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

Feature: FeatureName.SetRepeat, Supported by: Protocol.DMAP, Protocol.MRP

Change repeat state.

Browse git

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

Feature: FeatureName.SetShuffle, Supported by: Protocol.DMAP, Protocol.MRP

Change shuffle mode to on or off.

Browse git

async def skip_backward(self) -> NoneType

Feature: FeatureName.SkipBackward, Supported by: Protocol.DMAP, Protocol.MRP

Skip backwards a time interval.

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

Browse git

async def skip_forward(self) -> NoneType

Feature: FeatureName.SkipForward, Supported by: Protocol.DMAP, Protocol.MRP

Skip forward a time interval.

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

Browse git

async def stop(self) -> NoneType

Feature: FeatureName.Stop, Supported by: Protocol.DMAP, Protocol.MRP

Press key stop.

Browse git

async def suspend(self) -> NoneType

Feature: FeatureName.Suspend, Supported by: Protocol.MRP

Suspend the device.

Browse git

async def top_menu(self) -> NoneType

Feature: FeatureName.TopMenu, Supported by: Protocol.DMAP, Protocol.MRP

Go to main menu (long press menu).

Browse git

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

Feature: FeatureName.Up, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key up.

Browse git

async def volume_down(self) -> NoneType

Feature: FeatureName.VolumeDown, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key volume down.

Browse git

async def volume_up(self) -> NoneType

Feature: FeatureName.VolumeUp, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key volume up.

Browse git

async def wakeup(self) -> NoneType

Feature: FeatureName.WakeUp, Supported by: Protocol.MRP

Wake up the device.

Browse git

class StateProducer

Base class for objects announcing state changes to a listener.

Initialize a new StateProducer instance.

Browse git

Subclasses

• AppleTV
• Power
• PushUpdater
• pyatv.mrp.connection.MrpConnection

Instance variables

var listener

Return current listener object.

Browse git

class Stream

Base class for stream functionality.

Browse git

Subclasses

• pyatv.airplay.AirPlayStream
• pyatv.raop.RaopStream
• pyatv.support.facade.FacadeStream

Methods

def close(self) -> NoneType

Close connection and release allocated resources.

Browse git

async def play_url(self, url: str, **kwargs) -> NoneType

Feature: FeatureName.PlayUrl, Supported by: Protocol.AirPlay

Play media from an URL on the device.

Browse git

async def stream_file(self, file: Union[str, _io.BufferedReader], **kwargs) -> NoneType

Feature: FeatureName.StreamFile, Supported by: Protocol.RAOP

Stream local file to device.

INCUBATING METHOD - MIGHT CHANGE IN THE FUTURE!

Browse git