Class NodePyATVDevice

Represents an Apple TV. Use [[getState]] to query the current state (e.g. media type and title). You can also use the attribute methods (e.g. [[getTitle]] to get the state. If you want realtime updates, subscribe to it's events with an EventEmitter like API, so for example by using [[on]], [[once]] or [[addListener]]. It's also possible to send key commands by using [[pressKey]] or methods like [[pause]].

Implements

EventEmitter

Index

Basic

toJSON

toJSON(): Pick<
    NodePyATVDeviceOptions,
    "host"
    | "mac"
    | "name"
    | "id"
    | "protocol",
>
Returns an object with name, host, mac, id and protocol. Can be used to initiate a new device instance.

Returns Pick<NodePyATVDeviceOptions, "host" | "mac" | "name" | "id" | "protocol">
- Defined in src/lib/device.ts:924

toString

toString(): string
Returns a string. Just for debugging, etc.

Returns string
- Defined in src/lib/device.ts:950

Control

down

down(): Promise<void>
Send the "down" command

Returns Promise<void>
- Defined in src/lib/device.ts:218

home

home(): Promise<void>
Send the "home" command

Returns Promise<void>
- Defined in src/lib/device.ts:583

homeHold

homeHold(): Promise<void>
Send the "homeHold" command

Returns Promise<void>
- Defined in src/lib/device.ts:591

left

left(): Promise<void>
Send the "left" command

Returns Promise<void>
- Defined in src/lib/device.ts:608

menu(): Promise<void>
Send the "menu" command

Returns Promise<void>
- Defined in src/lib/device.ts:674

next(): Promise<void>
Send the "next" command

Returns Promise<void>
- Defined in src/lib/device.ts:682

pause

pause(): Promise<void>
Send the "pause" command

Returns Promise<void>
- Defined in src/lib/device.ts:736

play

play(): Promise<void>
Send the "play" command

Returns Promise<void>
- Defined in src/lib/device.ts:744

playPause

playPause(): Promise<void>
Send the "playPause" command

Returns Promise<void>
- Defined in src/lib/device.ts:752

pressKey

pressKey(key: NodePyATVKeys): Promise<void>
Send a key press to the Apple TV
```
await device.pressKey(NodePyATVKeys.home);
```
```
await device.pressKey('home');
```
Parameters
- key: NodePyATVKeys
Returns Promise<void>
- Defined in src/lib/device.ts:798

previous(): Promise<void>
Send the "previous" command

Returns Promise<void>
- Defined in src/lib/device.ts:819

right

right(): Promise<void>
Send the "right" command

Returns Promise<void>
- Defined in src/lib/device.ts:864

select

select(): Promise<void>
Send the "select" command

Returns Promise<void>
- Defined in src/lib/device.ts:872

skipBackward

skipBackward(): Promise<void>
Send the "skipBackward" command

Returns Promise<void>
- Defined in src/lib/device.ts:889

skipForward

skipForward(): Promise<void>
Send the "skipForward" command

Returns Promise<void>
- Defined in src/lib/device.ts:897

stop

stop(): Promise<void>
Send the "stop" command

Returns Promise<void>
- Defined in src/lib/device.ts:905

suspend

suspend(): Promise<void>
Send the "suspend" command

Returns Promise<void>
Deprecated
- Defined in src/lib/device.ts:914

topMenu

topMenu(): Promise<void>
Send the "topMenu" command

Returns Promise<void>
- Defined in src/lib/device.ts:941

turnOff

turnOff(): Promise<void>
Send the "turn_off" command

Returns Promise<void>
- Defined in src/lib/device.ts:958

turnOn

turnOn(): Promise<void>
Send the "turn_on" command

Returns Promise<void>
- Defined in src/lib/device.ts:966

up

up(): Promise<void>
Send the "up" command

Returns Promise<void>
- Defined in src/lib/device.ts:974

volumeDown

volumeDown(): Promise<void>
Send the "volumeDown" command

Returns Promise<void>
- Defined in src/lib/device.ts:982

volumeUp

volumeUp(): Promise<void>
Send the "volumeUp" command

Returns Promise<void>
- Defined in src/lib/device.ts:990

wakeup

wakeup(): Promise<void>
Send the "wakeup" command

Returns Promise<void>
Deprecated
- Defined in src/lib/device.ts:999

Event

addListener

addListener(
event: string | symbol,
listener: (event: NodePyATVDeviceEvent) => void,
): this
Add an event listener. Will start the event subscription with the Apple TV as long as there are listeners for any event registered.
Parameters
- event: string | symbol
- listener: (event: NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.addListener
- Defined in src/lib/device.ts:197

emit

emit(event: string | symbol, payload: NodePyATVDeviceEvent): boolean
Emit an event.
Parameters
- event: string | symbol
- payload: NodePyATVDeviceEvent
Returns boolean
Implementation of EventEmitter.emit
- Defined in src/lib/device.ts:228

eventNames

eventNames(): (string | symbol)[]
Get all event names which are currently known.

Returns (string | symbol)[]
Implementation of EventEmitter.eventNames
- Defined in src/lib/device.ts:236

getMaxListeners

getMaxListeners(): number
Get max number of listeners allowed

Returns number
Implementation of EventEmitter.getMaxListeners
- Defined in src/lib/device.ts:395

listenerCount

listenerCount(event: string | symbol): number
Get number of listeners for event
Parameters
- event: string | symbol
Returns number
Implementation of EventEmitter.listenerCount
- Defined in src/lib/device.ts:654

listeners

listeners(event: string | symbol): Function[]
Get listeners for event. Will also return node-pyatv wrappers (e.g. once)
Parameters
- event: string | symbol
Returns Function[]
Implementation of EventEmitter.listeners
- Defined in src/lib/device.ts:666

off

off(
event: string | symbol,
listener: (event: Error | NodePyATVDeviceEvent) => void,
): this
Remove an event listener. Will stop the event subscription with the Apple TV if this was the last event listener.
Parameters
- event: string | symbol
- listener: (event: Error | NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.off
- Defined in src/lib/device.ts:693

on

on(
event: string | symbol,
listener: (event: Error | NodePyATVDeviceEvent) => void,
): this
Add an event listener. Will start the event subscription with the Apple TV as long as there are listeners for any event registered.
Parameters
- event: string | symbol
- listener: (event: Error | NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.on
- Defined in src/lib/device.ts:708

once

once(
event: string | symbol,
listener: (event: Error | NodePyATVDeviceEvent) => void,
): this
Add an event listener. Will start the event subscription with the Apple TV as long as there are listeners for any event registered. Removes the listener automatically after the first occurrence.
Parameters
- event: string | symbol
- listener: (event: Error | NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.once
- Defined in src/lib/device.ts:724

prependListener

prependListener(
event: string | symbol,
listener: (event: Error | NodePyATVDeviceEvent) => void,
): this
Parameters
- event: string | symbol
- listener: (event: Error | NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.prependListener
- Defined in src/lib/device.ts:761

prependOnceListener

prependOnceListener(
event: string | symbol,
listener: (event: Error | NodePyATVDeviceEvent) => void,
): this
Parameters
- event: string | symbol
- listener: (event: Error | NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.prependOnceListener
- Defined in src/lib/device.ts:774

rawListeners

rawListeners(event: string | symbol): Function[]
Parameters
- event: string | symbol
Returns Function[]
Implementation of EventEmitter.rawListeners
- Defined in src/lib/device.ts:828

removeAllListeners

removeAllListeners(event?: string | symbol): this
Removes all listeners, either for the given event or for every event. Will stop the event subscription with the Apple TV if this was the last event listener.
Parameters
- Optionalevent: string | symbol
Returns this
Implementation of EventEmitter.removeAllListeners
- Defined in src/lib/device.ts:840

removeListener

removeListener(
event: string | symbol,
listener: (event: NodePyATVDeviceEvent) => void,
): this
Remove an event listener. Will stop the event subscription with the Apple TV if this was the last event listener.
Parameters
- event: string | symbol
- listener: (event: NodePyATVDeviceEvent) => void
Returns this
Implementation of EventEmitter.removeListener
- Defined in src/lib/device.ts:852

setMaxListeners

setMaxListeners(n: number): this
Parameters
- n: number
Returns this
Implementation of EventEmitter.setMaxListeners
- Defined in src/lib/device.ts:880

Other

constructor

new NodePyATVDevice(options: NodePyATVDeviceOptions): NodePyATVDevice
Parameters
- options: NodePyATVDeviceOptions
Returns NodePyATVDevice
- Defined in src/lib/device.ts:178

allIDs

get allIDs(): undefined | string[]
Get all IDs of the Apple TV. Requires pyatv >= 0.14.5.

Returns undefined | string[]
- Defined in src/lib/device.ts:43

debug

get debug(): undefined | true | ((msg: string) => void)
Returns true, if debugging is enabled. Returns the custom logging method, if one was specified. Otherwise, if debug log is disabled, returns undefined.

Returns undefined | true | ((msg: string) => void)
- Defined in src/lib/device.ts:51
set debug(debug: undefined | true | ((msg: string) => void)): void
Enable or disable debugging or set a custom debugging method to use.
Parameters
- debug: undefined | true | ((msg: string) => void)
Returns void
- Defined in src/lib/device.ts:60

host

get host(): undefined | string
Get the IP address of the Apple TV.

Returns undefined | string
- Defined in src/lib/device.ts:71

id

get id(): undefined | string
Get the ID of the Apple TV.

Returns undefined | string
- Defined in src/lib/device.ts:78

mac

get mac(): undefined | string
Get the MAC address of the Apple TV. Requires pyatv >= 0.14.5.

Returns undefined | string
- Defined in src/lib/device.ts:86

model

get model(): undefined | string
Get the model identifier of the device. Only set, if the device was found using [[find()]]. Requires pyatv ≧ 0.10.3.

Returns undefined | string
Example
```
device.model → "Gen4K"
```
- Defined in src/lib/device.ts:96

modelName

get modelName(): undefined | string
Get the model name of the device. Only set, if the device was found with [[find()]]. Requires pyatv ≧ 0.10.3.

Returns undefined | string
Example
```
device.modelName → "Apple TV 4K"
```
- Defined in src/lib/device.ts:106

name

get name(): string

Get the name of the Apple TV.

import pyatv from '@sebbo2002/node-pyatv';
const devices = await pyatv.find();
devices.forEach(device =>
    console.log(device.name)
);

Returns string

os

get os(): undefined | string
Get the operating system of the device. Only set, if the device was found with [[find()]]. Requires pyatv ≧ 0.10.3.

Returns undefined | string
Example
```
device.os → "TvOS"
```
- Defined in src/lib/device.ts:131

protocol

get protocol(): undefined | NodePyATVProtocol
Get the used protocol to connect to the Apple TV.

Returns undefined | NodePyATVProtocol
- Defined in src/lib/device.ts:138

services

get services(): undefined | NodePyATVService[]
Returns a list of services supported by the device. Ony set, if the device was found during a scan using [[find()]]. Requires pyatv ≧ 0.10.3.

Returns undefined | NodePyATVService[]
Example
```
device.services → [
  {
    "protocol": "airplay",
    "port": 7000
  },
  {
    "protocol": "dmap",
    "port": 3689
  }
]
```
- Defined in src/lib/device.ts:158

version

get version(): undefined | string
Get the device version. Only set, if the device was found during a scan using [[find()]]. Requires pyatv ≧ 0.10.3.

Returns undefined | string
Example
```
device.version → "15.5.1"
```
- Defined in src/lib/device.ts:168

getiTunesStoreIdentifier

getiTunesStoreIdentifier(
options?: NodePyATVGetStateOptions,
): Promise<null | number>
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:385

launchApp

launchApp(id: string): Promise<void>
Launch an application. Probably requires companionCredentials, see https://pyatv.dev/documentation/atvremote/#apps for more details.
Parameters
- id: string
  App identifier, e.g. com.netflix.Netflix
Returns Promise<void>
- Defined in src/lib/device.ts:600

listApps

listApps(): Promise<NodePyATVApp[]>
Returns the list of installed apps on the Apple TV. Probably requires companionCredentials, see https://pyatv.dev/documentation/atvremote/#apps for more details.

Returns Promise<NodePyATVApp[]>
- Defined in src/lib/device.ts:616

State

clearState

clearState(): void
Removes the state node-pyatv cached for this device.

Returns void
- Defined in src/lib/device.ts:210

getAlbum

getAlbum(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the album of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:245

getApp

getApp(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the currently used app
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:257

getAppId

getAppId(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the id of the currently used app
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:269

getArtist

getArtist(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the artist of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:281

getContentIdentifier

getContentIdentifier(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the app specific content identifier
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:293

getDateTime

getDateTime(options?: NodePyATVGetStateOptions): Promise<null | Date>
Get the date and time when the state was last updated.
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | Date>
- Defined in src/lib/device.ts:304

getDeviceState

getDeviceState(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVDeviceState>
Get the state of this device (e.g. playing, etc.)
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVDeviceState>
- Defined in src/lib/device.ts:316

getEpisodeNumber

getEpisodeNumber(options?: NodePyATVGetStateOptions): Promise<null | number>
Returns the episode number. Probably only set if MRP is used.
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:329

getFocusState

getFocusState(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVFocusState>
Returns the current focus state of the device
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVFocusState>
- Defined in src/lib/device.ts:340

getGenre

getGenre(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the genre of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:351

getHash

getHash(options?: NodePyATVGetStateOptions): Promise<null | string>
Get the hash of the current media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:363

getITunesStoreIdentifier

getITunesStoreIdentifier(
options?: NodePyATVGetStateOptions,
): Promise<null | number>
Returns the iTunes Store identifier if available. Requires pyatv >= 0.16.0
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
Alias
getiTunesStoreIdentifier
- Defined in src/lib/device.ts:377

getMediaType

getMediaType(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVMediaType>
Get the media type of the current media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVMediaType>
- Defined in src/lib/device.ts:404

getOutputDevices

getOutputDevices(
options?: NodePyATVGetStateOptions,
): Promise<null | { identifier: string; name: string }[]>
Returns the current output devices of the device
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | { identifier: string; name: string }[]>
- Defined in src/lib/device.ts:416

getPosition

getPosition(options?: NodePyATVGetStateOptions): Promise<null | number>
Returns the title of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:427

getPowerState

getPowerState(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVPowerState>
Returns the current power state (= is it on or off, see [[NodePyATVPowerState]]) of the device.
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVPowerState>
- Defined in src/lib/device.ts:439

getRepeat

getRepeat(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVRepeatState>
Returns the repeat state
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVRepeatState>
- Defined in src/lib/device.ts:450

getSeasonNumber

getSeasonNumber(options?: NodePyATVGetStateOptions): Promise<null | number>
Returns the season number. Probably only set if MRP is used.
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:463

getSeriesName

getSeriesName(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the season name. Probably only set if MRP is used.
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:474

getShuffle

getShuffle(
options?: NodePyATVGetStateOptions,
): Promise<null | NodePyATVShuffleState>
Returns the shuffle state
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | NodePyATVShuffleState>
- Defined in src/lib/device.ts:485

getState

getState(options?: NodePyATVGetStateOptions): Promise<NodePyATVState>
Returns an [[NodePyATVState]] object representing the current state of the device. Has an internal cache, which has a default TTL of 5s. You can change this default value by passing the maxAge option.
```
await device.getState({maxAge: 10000}); // cache TTL: 10s
```
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<NodePyATVState>
- Defined in src/lib/device.ts:504

getTitle

getTitle(options?: NodePyATVGetStateOptions): Promise<null | string>
Returns the title of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | string>
- Defined in src/lib/device.ts:549

getTotalTime

getTotalTime(options?: NodePyATVGetStateOptions): Promise<null | number>
Returns the media length of the current playing media
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:561

getVolume

getVolume(options?: NodePyATVGetStateOptions): Promise<null | number>
Returns the current volume of the device in percent (0 - 100)
Parameters
- options: NodePyATVGetStateOptions = {}
Returns Promise<null | number>
- Defined in src/lib/device.ts:573

Class NodePyATVDevice

Implements

Index

Basic

Control

Event

Other

State

Basic

toJSON

Returns Pick<NodePyATVDeviceOptions, "host" | "mac" | "name" | "id" | "protocol">

toString

Returns string

Control

down

Returns Promise<void>

home

Returns Promise<void>

homeHold

Returns Promise<void>

left

Returns Promise<void>

menu

Returns Promise<void>

next

Returns Promise<void>

pause

Returns Promise<void>

play

Returns Promise<void>

playPause

Returns Promise<void>

pressKey

Parameters

Returns Promise<void>

previous

Returns Promise<void>

right

Returns Promise<void>

select

Returns Promise<void>

skipBackward

Returns Promise<void>

skipForward

Returns Promise<void>

stop

Returns Promise<void>

suspend

Returns Promise<void>

Deprecated

topMenu

Returns Promise<void>

turnOff

Returns Promise<void>

turnOn

Returns Promise<void>

up

Returns Promise<void>

volumeDown

Returns Promise<void>

volumeUp

Returns Promise<void>

wakeup

Returns Promise<void>

Deprecated

Event

addListener

Parameters

Returns this

emit

Parameters

Returns boolean

eventNames

Returns (string | symbol)[]

getMaxListeners

Returns number

listenerCount

Parameters

Returns number

listeners