API

This page contains documentation for all public APIs in pyatv.

NOTE: Currently, the content on this page is far from complete. It will be updated as time goes. Feel free to help out.

Module contents

Library for controlling an Apple TV.

async pyatv.connect_to_apple_tv(details, loop, protocol=None, session=None)[source]

Connect and logins to an Apple TV.

async pyatv.scan_for_apple_tvs(loop, timeout=5, abort_on_found=False, device_ip=None, only_usable=True, protocol=None)[source]

Scan for Apple TVs using zeroconf (bonjour) and returns them.

Submodules

pyatv.const module

Constants used in the public API.

pyatv.const.MEDIA_TYPE_MUSIC = 3

Media type is music

pyatv.const.MEDIA_TYPE_TV = 4

Media type is TV

pyatv.const.MEDIA_TYPE_UNKNOWN = 1

Media type is unknown

pyatv.const.MEDIA_TYPE_VIDEO = 2

Media type is video

pyatv.const.PLAY_STATE_FAST_BACKWARD = 6

Media is being rewinded

pyatv.const.PLAY_STATE_FAST_FORWARD = 5

Media is being fast forwarded

pyatv.const.PLAY_STATE_IDLE = 0

Device is in idle state

pyatv.const.PLAY_STATE_LOADING = 2

Media is loading/buffering

pyatv.const.PLAY_STATE_NO_MEDIA = 1

No media is currently select/playing

pyatv.const.PLAY_STATE_PAUSED = 3

Media is paused

pyatv.const.PLAY_STATE_PLAYING = 4

Media is playing

pyatv.const.PROTOCOL_AIRPLAY = 3

Protocol is AirPlay

pyatv.const.PROTOCOL_DMAP = 1

Protocol is DMAP (Apple TV 1, 2 and 3)

pyatv.const.PROTOCOL_MRP = 2

Protocol is MediaRemote (Apple TV 4 and later)

pyatv.const.REPEAT_STATE_ALL = 2

Repeat all tracks

pyatv.const.REPEAT_STATE_OFF = 0

No repeat

pyatv.const.REPEAT_STATE_TRACK = 1

Repeat current track

pyatv.exceptions module

Local exceptions used by library.

exception pyatv.exceptions.AsyncUpdaterRunningError[source]

Bases: Exception

Thrown when performing an invalid action in AsyncUpdater..

exception pyatv.exceptions.AuthenticationError[source]

Bases: Exception

Thrown when login fails.

exception pyatv.exceptions.DeviceAuthenticationError[source]

Bases: Exception

Thrown when device authentication fails.

exception pyatv.exceptions.InvalidDmapDataError[source]

Bases: Exception

Thrown when invalid DMAP data is parsed.

exception pyatv.exceptions.NoAsyncListenerError[source]

Bases: Exception

Thrown when starting AsyncUpdater with no listener.

exception pyatv.exceptions.NoCredentialsError[source]

Bases: Exception

Thrown if performing an action before initialize is called.

exception pyatv.exceptions.NoUsableServiceError[source]

Bases: Exception

Thrown when connecting to a device with no usable service.

exception pyatv.exceptions.NotSupportedError[source]

Bases: NotImplementedError

Thrown when trying to perform an action that is not supported.

exception pyatv.exceptions.UnknownMediaKind[source]

Bases: Exception

Thrown when an unknown media kind is found.

exception pyatv.exceptions.UnknownPlayState[source]

Bases: Exception

Thrown when an unknown play state is found.

exception pyatv.exceptions.UnknownServerResponseError[source]

Bases: Exception

Thrown when somethins unknown is send back from the Apple TV.

pyatv.helpers module

Various helper methods.

pyatv.helpers.auto_connect(handler, timeout=5, not_found=None)[source]

Short method for connecting to a device.

This is a convenience method that create an event loop, auto discovers devices, picks the first device found, connects to it and passes it to a user provided handler. An optional error handler can be provided that is called when no device was found. Very inflexible in many cases, but can be handys sometimes when trying things.

Note: both handler and not_found must be coroutines

pyatv.interface module

API exposed by the library.

class pyatv.interface.AirPlay[source]

Bases: object

Base class for AirPlay functionality.

abstract finish_authentication(pin)[source]

End authentication process with PIN code.

abstract generate_credentials()[source]

Create new credentials for authentication.

Credentials that have been authenticated shall be saved and loaded with load_credentials before playing anything. If credentials are lost, authentication must be performed again.

abstract load_credentials(credentials)[source]

Load existing credentials.

abstract play_url(url, **kwargs)[source]

Play media from an URL on the device.

abstract start_authentication()[source]

Begin authentication proces (show PIN on screen).

abstract verify_authenticated()[source]

Check if loaded credentials are verified.

class pyatv.interface.AppleTV[source]

Bases: object

Base class representing an Apple TV.

abstract property airplay

Return API for working with AirPlay.

abstract login()[source]

Perform an explicit login.

Not needed as login is performed automatically.

abstract logout()[source]

Perform an explicit logout.

Must be done when session is no longer needed to not leak resources.

abstract property metadata

Return API for retrieving metadata from the Apple TV.

abstract property pairing

Return API for pairing with the Apple TV.

abstract property push_updater

Return API for handling push update from the Apple TV.

abstract property remote_control

Return API for controlling the Apple TV.

abstract property service

Return service used to connect to the Apple TV..

class pyatv.interface.Metadata[source]

Bases: object

Base class for retrieving metadata from an Apple TV.

abstract artwork()[source]

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

abstract artwork_url()[source]

Return artwork URL for what is currently playing.

abstract property device_id

Return a unique identifier for current device.

abstract playing()[source]

Return what is currently playing.

class pyatv.interface.PairingHandler[source]

Bases: object

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

abstract property credentials

Credentials that were generated during pairing.

abstract property device_provides_pin

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

abstract property has_paired

If a successful pairing has been performed.

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

abstract pin(pin)[source]

Pin code used for pairing.

abstract start(**kwargs)[source]

Start pairing process.

abstract stop(**kwargs)[source]

Stop pairing process.

class pyatv.interface.Playing[source]

Bases: object

Base class for retrieving what is currently playing.

abstract property album

Album of the currently playing song.

abstract property artist

Artist of the currently playing song.

abstract property genre

Genre of the currently playing song.

property hash

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.

abstract property media_type

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

abstract property play_state

Play state, e.g. playing or paused.

abstract property position

Position in the playing media (seconds).

abstract property repeat

Repeat mode.

abstract property shuffle

If shuffle is enabled or not.

abstract property title

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

abstract property total_time

Total play time in seconds.

class pyatv.interface.PushUpdater[source]

Bases: object

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

property listener

Object (PushUpdaterListener) that receives updates.

abstract start(initial_delay=0)[source]

Begin to listen to updates.

If an error occurs, start must be called again.

abstract stop()[source]

No longer listen for updates.

class pyatv.interface.RemoteControl[source]

Bases: object

Base class for API used to control an Apple TV.

abstract down()[source]

Press key down.

abstract left()[source]

Press key left.

abstract menu()[source]

Press key menu.

abstract next()[source]

Press key next.

abstract pause()[source]

Press key play.

abstract play()[source]

Press key play.

abstract previous()[source]

Press key previous.

abstract right()[source]

Press key right.

abstract select()[source]

Press key select.

abstract set_position(pos)[source]

Seek in the current playing media.

abstract set_repeat(repeat_mode)[source]

Change repeat mode.

abstract set_shuffle(is_on)[source]

Change shuffle mode to on or off.

abstract stop()[source]

Press key stop.

abstract suspend()[source]

Suspend the device.

abstract top_menu()[source]

Go to main menu (long press menu).

abstract up()[source]

Press key up.

pyatv.interface.retrieve_commands(obj)[source]

Retrieve all commands and help texts from an API object.