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.

class pyatv.AppleTVDevice[source]

Bases: pyatv.AppleTVDevice

Representation of an Apple TV device used when connecting.

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

Connect and logins to an Apple TV.

pyatv.pair_with_apple_tv(loop, pin_code, name, pairing_guid=None)[source]

Initialize pairing process with an Apple TV.

pyatv.scan_for_apple_tvs(loop, timeout=5, abort_on_found=False, only_home_sharing=True)[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_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.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.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, event_loop=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 1: both handler and not_found must be coroutines Note 2: An optional loop can be passed if needed (mainly for testing)

pyatv.interface module

API exposed by the library.

class pyatv.interface.AirPlay[source]

Bases: object

Base class for AirPlay functionality.

finish_authentication(pin)[source]

End authentication process with PIN code.

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.

load_credentials(credentials)[source]

Load existing credentials.

play_url(url, **kwargs)[source]

Play media from an URL on the device.

start_authentication()[source]

Begin authentication proces (show PIN on screen).

verify_authenticated()[source]

Check if loaded credentials are verified.

class pyatv.interface.AppleTV[source]

Bases: object

Base class representing an Apple TV.

airplay

Return API for working with AirPlay.

login()[source]

Perform an explicit login.

Not needed as login is performed automatically.

logout()[source]

Perform an explicit logout.

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

metadata

Return API for retrieving metadata from the Apple TV.

push_updater

Return API for handling push update from the Apple TV.

remote_control

Return API for controlling the Apple TV.

class pyatv.interface.Metadata[source]

Bases: object

Base class for retrieving metadata from an Apple TV.

artwork()[source]

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

artwork_url()[source]

Return artwork URL for what is currently playing.

playing()[source]

Return what is currently playing.

class pyatv.interface.Playing[source]

Bases: object

Base class for retrieving what is currently playing.

album

Album of the currently playing song.

artist

Artist of the currently playing song.

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.

media_type

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

play_state

Play state, e.g. playing or paused.

position

Position in the playing media (seconds).

repeat

Repeat mode.

shuffle

If shuffle is enabled or not.

title

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

total_time

Total play time in seconds.

class pyatv.interface.PushUpdater[source]

Bases: object

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

listener

Object (PushUpdaterListener) that receives updates.

start(initial_delay=0)[source]

Begin to listen to updates.

If an error occurs, start must be called again.

stop()[source]

No longer listen for updates.

class pyatv.interface.RemoteControl[source]

Bases: object

Base class for API used to control an Apple TV.

down()[source]

Press key down.

left()[source]

Press key left.

menu()[source]

Press key menu.

next()[source]

Press key next.

pause()[source]

Press key play.

play()[source]

Press key play.

previous()[source]

Press key previous.

right()[source]

Press key right.

select()[source]

Press key select.

set_position(pos)[source]

Seek in the current playing media.

set_repeat(repeat_mode)[source]

Change repeat mode.

set_shuffle(is_on)[source]

Change shuffle mode to on or off.

stop()[source]

Press key stop.

top_menu()[source]

Go to main menu (long press menu).

up()[source]

Press key up.

pyatv.interface.retrieve_commands(obj, developer=False)[source]

Retrieve all commands and help texts from an API object.