--- layout: template title: API - pyatv.interface permalink: /api//interface link_group: api ---

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

  Base class for protocol services.

  Initialize a new BaseService.

  Browse git

  ### Ancestors

  - abc.ABC

  ### Subclasses

  - ManualService
  - pyatv.core.MutableService

  ### Instance variables

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

  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 (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.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 (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
  - pyatv.support.state_producer.StateProducer
  - typing.Generic

  ### Subclasses

  - pyatv.protocols.dmap.DmapPushUpdater
  - pyatv.protocols.mrp.MrpPushUpdater
  - pyatv.protocols.raop.RaopPushUpdater

  ### Instance variables

  `var active -> bool`

    Return if push updater has been started.

    Browse git

  ### Methods

  `def post_update(self, playing: Playing) -> None`

    Post an update to listener.

    Browse git
  `def start(self, initial_delay: int = 0) -> None`
    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) -> 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 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.DMAP, Protocol.MRP

    Press key next.

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

    Press key play.

    Browse git
  `async def play(self) -> None`
    Feature: FeatureName.Play, Supported by: 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.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

    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 file to device.

    INCUBATING METHOD - MIGHT CHANGE IN THE FUTURE!

    Browse git