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 (max_calls: int = 0)

Base class representing an Apple TV.

Listener interface: pyatv.interfaces.DeviceListener

Initialize a new StateProducer instance.

Browse git

Ancestors

abc.ABC
pyatv.support.state_producer.StateProducer
typing.Generic

Subclasses

pyatv.core.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) -> Set[_asyncio.Task]: Close connection and release allocated resources.

Browse git
async def connect(self) -> None: Initiate connection to device.

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

Browse git

class Apps

Base class for app handling.

Browse git

Subclasses

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

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) -> None: 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.core.facade.FacadeAudio
pyatv.protocols.companion.CompanionAudio
pyatv.protocols.dmap.DmapAudio
pyatv.protocols.mrp.MrpAudio
pyatv.protocols.raop.RaopAudio

Instance variables

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

Return current volume level.

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

Browse git

Methods

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

Change current volume level.

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

Browse git
async def volume_down(self) -> None: Feature: FeatureName.VolumeDown, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

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

Browse git
async def volume_up(self) -> None: Feature: FeatureName.VolumeUp, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

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

Browse git

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.

Browse git

Ancestors

abc.ABC

Subclasses

AppleTV

Instance variables

var address -> ipaddress.IPv4Address: IP address of device.

Browse git
var all_identifiers -> List[str]: Return all unique identifiers for this device.

Browse git
var deep_sleep -> bool: If device is in deep sleep.

Browse git
var device_info -> DeviceInfo: Return general device information.

Browse git
var identifier -> Optional[str]: Return the main identifier associated with this device.

Browse git
var name -> str: Name of device.

Browse git
var properties -> Mapping[str, Mapping[str, str]]: Return Zeroconf properties.

Browse git
var ready -> bool: Return if configuration is ready, (at least one service with identifier).

Browse git
var services -> List[BaseService]: Return all supported services.

Browse git

Methods

def add_service(self, service: BaseService) -> None: Add a new service.

If the service already exists, it will be merged.

Browse git
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.

Browse git
def main_service(self, protocol: Optional[Protocol] = None) -> BaseService: Return suggested service used to establish connection.

Browse git
def set_credentials(self, protocol: Protocol, credentials: str) -> bool: Set credentials for a protocol if it exists.

Browse git

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.

Browse git

Ancestors

abc.ABC

Subclasses

ManualService
pyatv.core.MutableService

Instance variables

var enabled -> bool: Return True if service is enabled.

Browse git
var identifier -> Optional[str]: Return unique identifier associated with this service.

Browse git
var pairing -> PairingRequirement: Return if pairing is required by service.

Browse git
var port -> int: Return service port number.

Browse git
var properties -> Mapping[str, str]: Return service Zeroconf properties.

Browse git
var protocol -> Protocol: Return protocol type.

Browse git
var requires_password -> bool: Return if a password is required to access service.

Browse git

Methods

def merge(self, other) -> None: Merge with other service of same type.

Merge will only include credentials, password and properties.

Browse git

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

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

Browse git
var operating_system -> OperatingSystem: Operating system running on device.

Browse git
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).

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) -> None: Device connection was (intentionally) closed.

Browse git
def connection_lost(self, exception: Exception) -> None: 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.core.facade.FacadeFeatures
pyatv.protocols.airplay.AirPlayFeatures
pyatv.protocols.companion.CompanionFeatures
pyatv.protocols.dmap.DmapFeatures
pyatv.protocols.mrp.MrpFeatures
pyatv.protocols.raop.RaopFeatures

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

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

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) -> None: Start pairing process.

Browse git
async def close(self) -> None: Call to free allocated resources after pairing.

Browse git
async def finish(self) -> None: Stop pairing process.

Browse git
def pin(self, pin) -> None: 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, content_identifier: Optional[str] = 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 content_identifier -> Optional[str]: Feature: FeatureName.ContentIdentifier, Supported by:

Content identifier (app specific).

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 (max_calls: int = 0)

Base class for retrieving power state from an Apple TV.

Listener interface: pyatv.interfaces.PowerListener

Initialize a new StateProducer instance.

Browse git

Ancestors

abc.ABC
pyatv.support.state_producer.StateProducer
typing.Generic

Subclasses

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

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) -> None: Feature: FeatureName.TurnOff, Supported by: Protocol.Companion, Protocol.MRP

Turn device off.

Browse git
async def turn_on(self, await_new_state: bool = False) -> None: Feature: FeatureName.TurnOn, Supported by: Protocol.Companion, Protocol.MRP

Turn device on.

Browse git

class PowerListener

Listener interface for power updates.

Browse git

Ancestors

abc.ABC

Subclasses

pyatv.core.facade.FacadePower
pyatv.scripts.atvscript.PowerPrinter

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.core.facade.FacadePushUpdater
pyatv.scripts.atvremote.PushListener
pyatv.scripts.atvscript.PushPrinter

Methods

def playstatus_error(self, updater, exception: Exception) -> None: Inform about an error when updating play status.

Browse git
def playstatus_update(self, updater, playstatus: Playing) -> None: Inform about changes to what is currently playing.

Browse git

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.

Browse git

Ancestors

abc.ABC
pyatv.support.state_producer.StateProducer
typing.Generic

Subclasses

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

Instance variables

var active -> bool: Return if push updater has been started.

Browse git

Methods

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.

Browse git
def stop(self) -> None: No longer forward updates to listener.

Browse git

class RemoteControl

Base class for API used to control an Apple TV.

Browse git

Subclasses

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

Methods

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

Select previous channel.

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

Select next channel.

Browse git
async def down(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Down, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key down.

Browse git
async def home(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Home, Supported by: Protocol.Companion, Protocol.MRP

Press key home.

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

Hold key home.

Browse git
async def left(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Left, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key left.

Browse git
async def menu(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Menu, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key menu.

Browse git
async def next(self) -> None: Feature: FeatureName.Next, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key next.

Browse git
async def pause(self) -> None: Feature: FeatureName.Pause, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key play.

Browse git
async def play(self) -> None: Feature: FeatureName.Play, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key play.

Browse git
async def play_pause(self) -> None: Feature: FeatureName.PlayPause, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Toggle between play and pause.

Browse git
async def previous(self) -> None: Feature: FeatureName.Previous, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key previous.

Browse git
async def right(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Right, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key right.

Browse git
async def select(self, action: InputAction = InputAction.SingleTap) -> None: Feature: FeatureName.Select, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key select.

Browse git
async def set_position(self, pos: int) -> None: 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) -> None: Feature: FeatureName.SetRepeat, Supported by: Protocol.DMAP, Protocol.MRP

Change repeat state.

Browse git
async def set_shuffle(self, shuffle_state: ShuffleState) -> None: Feature: FeatureName.SetShuffle, Supported by: Protocol.DMAP, Protocol.MRP

Change shuffle mode to on or off.

Browse git
async def skip_backward(self) -> None: 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) -> None: 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) -> None: Feature: FeatureName.Stop, Supported by: Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key stop.

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

Suspend the device.

DEPRECATED: Use Power.turn_off() instead.

Browse git
async def top_menu(self) -> None: 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) -> None: Feature: FeatureName.Up, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP

Press key up.

Browse git
async def volume_down(self) -> None: Feature: FeatureName.VolumeDown, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key volume down.

DEPRECATED: Use Audio.volume_down() instead.

Browse git
async def volume_up(self) -> None: Feature: FeatureName.VolumeUp, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP

Press key volume up.

DEPRECATED: Use Audio.volume_up() instead.

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

Wake up the device.

DEPRECATED: Use Power.turn_on() instead.

Browse git

class Stream

Base class for stream functionality.

Browse git

Subclasses

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

Methods

def close(self) -> None: Close connection and release allocated resources.

Browse git
async def play_url(self, url: str, **kwargs) -> None: 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) -> 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.

INCUBATING METHOD - MIGHT CHANGE IN THE FUTURE!

Browse git