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.
Functions
-
def retrieve_commands(obj: object)
-
Retrieve all commands and help texts from an API object.
Classes
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.
Ancestors
- abc.ABC
- StateProducer
Subclasses
- pyatv.support.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 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.
Methods
-
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.
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.
-
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.
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.
Subclasses
- pyatv.raop.RaopAudio
- pyatv.support.facade.FacadeAudio
Instance variables
var volume -> float
-
Feature: FeatureName.Volume, Supported by: Protocol.RAOP
Return current volume level.
Methods
-
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.
Subclasses
Instance variables
var identifier -> Optional[str]
-
Return unique identifier associated with this service.
Methods
-
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.
Ancestors
- abc.ABC
Subclasses
- pyatv.scripts.atvremote.DeviceListener
- pyatv.scripts.atvscript.DevicePrinter
Methods
-
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.
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.
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.
-
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.
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.
var artwork_id -> str
-
Return a unique identifier for current artwork.
var device_id -> Optional[str]
-
Return a unique identifier for current device.
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.
-
async def playing(self) -> Playing
-
Return what is currently playing.
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.
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.
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.
Methods
-
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.
Ancestors
- 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.
Ancestors
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.
Methods
-
async def turn_off(self, await_new_state: bool = False) -> NoneType
-
Feature: FeatureName.TurnOff, Supported by: Protocol.Companion, Protocol.MRP
Turn device off.
-
async def turn_on(self, await_new_state: bool = False) -> NoneType
-
Feature: FeatureName.TurnOn, Supported by: Protocol.Companion, Protocol.MRP
Turn device on.
Inherited members
class PowerListener
-
Listener interface for power updates.
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.
class PushListener
-
Listener interface for push updates.
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.
-
def playstatus_update(self, updater, playstatus: Playing) -> NoneType
-
Inform about changes to what is currently playing.
class PushUpdater (loop: asyncio.events.AbstractEventLoop)
-
Base class for push/async updates from an Apple TV.
Listener interface:
PushListener
Initialize a new PushUpdater.
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.
Methods
-
def post_update(self, playing: Playing) -> NoneType
-
Post an update to listener.
-
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.
-
def stop(self) -> NoneType
-
No longer forward updates to listener.
Inherited members
class RemoteControl
-
Base class for API used to control an Apple TV.
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.
-
async def home(self, action: InputAction = InputAction.SingleTap) -> NoneType
-
Feature: FeatureName.Home, Supported by: Protocol.Companion, Protocol.MRP
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
-
Feature: FeatureName.Left, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
Press key left.
-
Feature: FeatureName.Menu, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
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
-
Feature: FeatureName.PlayPause, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
Toggle between play and pause.
-
async def previous(self) -> NoneType
-
Feature: FeatureName.Previous, Supported by: Protocol.DMAP, Protocol.MRP
Press key previous.
-
async def right(self, action: InputAction = InputAction.SingleTap) -> NoneType
-
Feature: FeatureName.Right, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
Press key right.
-
async def select(self, action: InputAction = InputAction.SingleTap) -> NoneType
-
Feature: FeatureName.Select, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
Press key select.
-
async def set_position(self, pos: int) -> NoneType
-
Feature: FeatureName.SetPosition, Supported by: Protocol.DMAP, Protocol.MRP
Seek in the current playing media.
-
async def set_repeat(self, repeat_state: RepeatState) -> NoneType
-
Feature: FeatureName.SetRepeat, Supported by: Protocol.DMAP, Protocol.MRP
Change repeat state.
-
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.
-
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.
-
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.
-
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.
-
Feature: FeatureName.TopMenu, Supported by: Protocol.DMAP, Protocol.MRP
Go to main menu (long press menu).
-
async def up(self, action: InputAction = InputAction.SingleTap) -> NoneType
-
Feature: FeatureName.Up, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP
Press key up.
-
async def volume_down(self) -> NoneType
-
Feature: FeatureName.VolumeDown, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP
Press key volume down.
-
async def volume_up(self) -> NoneType
-
Feature: FeatureName.VolumeUp, Supported by: Protocol.Companion, Protocol.DMAP, Protocol.MRP, Protocol.RAOP
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.
Subclasses
- AppleTV
- Power
- PushUpdater
- pyatv.mrp.connection.MrpConnection
Instance variables
var listener
-
Return current listener object.
class Stream
-
Base class for stream functionality.
Subclasses
- pyatv.airplay.AirPlayStream
- pyatv.raop.RaopStream
- pyatv.support.facade.FacadeStream
Methods
-
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.
INCUBATING METHOD - MIGHT CHANGE IN THE FUTURE!