@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/pyatv/protocols/mrp/protobuf/VolumeControlCapabilitiesDidChangeMessage_pb2.pyi

@@ -0,0 +1,40 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import builtins
+import google.protobuf.descriptor
+import google.protobuf.internal.extension_dict
+import google.protobuf.message
+import pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2
+import pyatv.protocols.mrp.protobuf.VolumeControlAvailabilityMessage_pb2
+import typing
+
+DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+
+@typing.final
+class VolumeControlCapabilitiesDidChangeMessage(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    CAPABILITIES_FIELD_NUMBER: builtins.int
+    ENDPOINTUID_FIELD_NUMBER: builtins.int
+    OUTPUTDEVICEUID_FIELD_NUMBER: builtins.int
+    endpointUID: builtins.str
+    outputDeviceUID: builtins.str
+    @property
+    def capabilities(self) -> pyatv.protocols.mrp.protobuf.VolumeControlAvailabilityMessage_pb2.VolumeControlAvailabilityMessage: ...
+    def __init__(
+        self,
+        *,
+        capabilities: pyatv.protocols.mrp.protobuf.VolumeControlAvailabilityMessage_pb2.VolumeControlAvailabilityMessage | None = ...,
+        endpointUID: builtins.str | None = ...,
+        outputDeviceUID: builtins.str | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["capabilities", b"capabilities", "endpointUID", b"endpointUID", "outputDeviceUID", b"outputDeviceUID"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["capabilities", b"capabilities", "endpointUID", b"endpointUID", "outputDeviceUID", b"outputDeviceUID"]) -> None: ...
+
+global___VolumeControlCapabilitiesDidChangeMessage = VolumeControlCapabilitiesDidChangeMessage
+
+VOLUMECONTROLCAPABILITIESDIDCHANGEMESSAGE_FIELD_NUMBER: builtins.int
+volumeControlCapabilitiesDidChangeMessage: google.protobuf.internal.extension_dict._ExtensionFieldDescriptor[pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2.ProtocolMessage, global___VolumeControlCapabilitiesDidChangeMessage]

package/pyatv/pyatv/protocols/mrp/protobuf/VolumeDidChangeMessage.proto

@@ -0,0 +1,13 @@
+syntax = "proto2";
+
+import "pyatv/protocols/mrp/protobuf/ProtocolMessage.proto";
+
+extend ProtocolMessage {
+  optional VolumeDidChangeMessage volumeDidChangeMessage = 56;
+}
+
+message VolumeDidChangeMessage {
+  optional float volume = 1;
+  optional string endpointUID = 2;
+  optional string outputDeviceUID = 3;
+}

package/pyatv/pyatv/protocols/mrp/protobuf/VolumeDidChangeMessage_pb2.pyi

@@ -0,0 +1,38 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import builtins
+import google.protobuf.descriptor
+import google.protobuf.internal.extension_dict
+import google.protobuf.message
+import pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2
+import typing
+
+DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+
+@typing.final
+class VolumeDidChangeMessage(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    VOLUME_FIELD_NUMBER: builtins.int
+    ENDPOINTUID_FIELD_NUMBER: builtins.int
+    OUTPUTDEVICEUID_FIELD_NUMBER: builtins.int
+    volume: builtins.float
+    endpointUID: builtins.str
+    outputDeviceUID: builtins.str
+    def __init__(
+        self,
+        *,
+        volume: builtins.float | None = ...,
+        endpointUID: builtins.str | None = ...,
+        outputDeviceUID: builtins.str | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["endpointUID", b"endpointUID", "outputDeviceUID", b"outputDeviceUID", "volume", b"volume"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["endpointUID", b"endpointUID", "outputDeviceUID", b"outputDeviceUID", "volume", b"volume"]) -> None: ...
+
+global___VolumeDidChangeMessage = VolumeDidChangeMessage
+
+VOLUMEDIDCHANGEMESSAGE_FIELD_NUMBER: builtins.int
+volumeDidChangeMessage: google.protobuf.internal.extension_dict._ExtensionFieldDescriptor[pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2.ProtocolMessage, global___VolumeDidChangeMessage]

package/pyatv/pyatv/protocols/mrp/protobuf/WakeDeviceMessage.proto

@@ -0,0 +1,11 @@
+syntax = "proto2";
+
+import "pyatv/protocols/mrp/protobuf/ProtocolMessage.proto";
+
+extend ProtocolMessage {
+  optional WakeDeviceMessage wakeDeviceMessage = 45;
+}
+
+message WakeDeviceMessage {
+
+}

package/pyatv/pyatv/protocols/mrp/protobuf/WakeDeviceMessage_pb2.pyi

@@ -0,0 +1,26 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import builtins
+import google.protobuf.descriptor
+import google.protobuf.internal.extension_dict
+import google.protobuf.message
+import pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2
+import typing
+
+DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+
+@typing.final
+class WakeDeviceMessage(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    def __init__(
+        self,
+    ) -> None: ...
+
+global___WakeDeviceMessage = WakeDeviceMessage
+
+WAKEDEVICEMESSAGE_FIELD_NUMBER: builtins.int
+wakeDeviceMessage: google.protobuf.internal.extension_dict._ExtensionFieldDescriptor[pyatv.protocols.mrp.protobuf.ProtocolMessage_pb2.ProtocolMessage, global___WakeDeviceMessage]

package/pyatv/pylintrc

@@ -0,0 +1,49 @@
+[MASTER]
+load-plugins=pylint.extensions.no_self_use
+reports=no
+
+[BASIC]
+good-names=
+  ex,
+  rd,
+  f,
+  i,
+  T,
+  ws
+
+[FORMAT]
+max-line-length=88
+
+[TYPECHECK]
+ignore=protobuf
+ignored-modules=pyatv.protocols.mrp.protobuf
+ignored-classes=
+  ProtocolMessage,
+  SetConnectionStateMessage,
+  SetStateMessage,
+  ContentItemMetadata,
+  CommandInfo,
+  PlaybackState,
+  ShuffleMode,
+  RepeatMode,
+  HandlerReturnStatus,
+  SendError,
+  DeviceClass
+
+disable=
+  broad-except,
+  cyclic-import,  # TODO: Bug in pylint?
+  locally-disabled,
+  duplicate-code,
+  fixme,
+  unused-argument,
+  no-self-use,
+  too-few-public-methods,
+  too-many-public-methods,
+  too-many-arguments,
+  too-many-instance-attributes,
+  too-many-lines,
+  too-many-positional-arguments
+
+[EXCEPTIONS]
+overgeneral-exceptions=builtins.Exception

package/pyatv/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools>=77.0"]
+
+[project]
+name="pyatv"
+license = "MIT"
+license-files = ["LICENSE.md"]
+description = "A client library for Apple TV and AirPlay devices"
+readme = "README.md"
+authors = [{ name = "Pierre Ståhl", email = "pierre.staahl@gmail.com" }]
+requires-python = ">=3.9.0"
+keywords = ["apple", "tv", "airplay", "raop", "companion", "dmap", "dacp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dynamic = ["version", "dependencies"]
+
+[project.urls]
+"Homepage" = "https://pyatv.dev"
+"Repository" = "https://github.com/postlund/pyatv"
+"Bug Reports" = "https://github.com/postlund/pyatv/issues"
+
+[project.scripts]
+atvremote = "pyatv.scripts.atvremote:main"
+atvproxy = "pyatv.scripts.atvproxy:main"
+atvscript = "pyatv.scripts.atvscript:main"
+atvlog = "pyatv.scripts.atvlog:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "pyatv.const.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["pyatv*"]
+
+[tool.black]
+extend-exclude = '(protobuf/(__init__|.*_pb2).py)|__pycache__'
+include = '(pyatv|tests|examples|scripts).*\.py'
+
+[tool.isort]
+skip_glob = "pyatv/protocols/mrp/protobuf/*.py"
+profile = "black"
+force_sort_within_sections = true
+known_first_party = [
+    "pyatv",
+    "tests",
+    "scripts",
+]
+forced_separate = [
+    "tests",
+    "scripts",
+]
+
+[[tool.mypy.overrides]]
+module = [
+    "miniaudio",
+    "audio_metadata",
+    "srptools",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"

package/pyatv/requirements/requirements.txt

@@ -0,0 +1,14 @@
+aiohttp==3.13.3
+async-timeout==5.0.1;python_version<'3.11'
+cryptography==46.0.3
+chacha20poly1305-reuseable==0.13.2
+ifaddr==0.2.0
+ifaddr==0.2.0
+miniaudio==1.61
+protobuf==6.33.2
+pydantic==2.12.5
+requests==2.32.5
+srptools==1.0.1
+tabulate==0.9.0
+tinytag==2.1.2
+zeroconf==0.148.0

package/pyatv/requirements/requirements_docs.txt

@@ -0,0 +1,2 @@
+codespell==2.4.1
+pdoc3==0.11.6

package/pyatv/requirements/requirements_test.txt

@@ -0,0 +1,20 @@
+black==25.11.0
+deepdiff==8.6.1
+flake8==7.3.0
+isort==6.0.1
+mutagen==1.47.0
+pyfakefs==5.10.2
+pylint==3.3.9
+pytest==8.4.2
+pytest-asyncio==0.26.0
+pytest-cov==7.0.0
+pytest-timeout==2.4.0
+pytest-aiohttp==1.0.5
+pytest_httpserver==1.1.3
+pytest-xdist==3.8.0
+pydocstyle==6.3.0
+mypy==1.19.0
+mypy-protobuf==3.7.0
+types-protobuf==6.32.1.20251210
+types-requests==2.32.4.20260107
+types-tabulate==0.9.0.20241207

package/pyatv/scripts/build_docs.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+run()
+{
+    docker run -p 4000:4000 --rm \
+            -v "$PWD:/srv/jekyll" \
+            -v "$PWD/docs/vendor/bundle:/usr/local/bundle" \
+            -w /srv/jekyll/docs \
+            -it jekyll/jekyll:3.8 "$@"
+}
+
+if [[ $GITPOD_INSTANCE_ID ]]; then
+    cd docs && bundle install && bundle update github-pages && bundle exec jekyll serve --incremental --watch
+else
+    run bundle update github-pages
+    run jekyll serve --incremental --watch
+fi

package/pyatv/scripts/setup_dev_env.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# Set in GitPod which breaks installation in venv
+unset PIP_USER
+
+VERSIONS="3.10 3.9 3.8 3.7 3.6"
+
+found_version=
+for p in $VERSIONS
+do
+    which python${p} 2>&1 > /dev/null
+    if [ $? -eq 0 ]; then
+        found_version=python${p}
+        break
+    fi
+done
+
+set -e
+
+if [ -z $found_version ]; then
+    >&2 echo "no python installation found"
+    exit 1
+fi
+
+echo "-> Using python: $found_version"
+
+echo "-> Creating python virtual environment..."
+$found_version -m venv .
+
+echo "-> Activating virtual environment..."
+source bin/activate
+sed -i '' 's/false/true/' pyvenv.cfg
+
+echo "-> Upgrading pip..."
+pip install --upgrade pip
+
+echo "-> Installing library as develop..."
+python setup.py develop
+
+echo "-> Installing protobuf-setuptools..."
+pip install protobuf-setuptools
+
+echo "-> Installing dependencies..."
+pip install --upgrade pyyaml -r requirements/requirements_test.txt -r requirements/requirements_docs.txt
+
+echo "-> Running tests as verification..."
+python setup.py test
+
+cat <<EOF
+==================================================
+
+When starting a new shell, run:
+
+  source bin/activate
+
+To run tests, run any of:
+
+  python setup.py test
+  pytest tests/test_conf.py  # Single test
+
+Test everything with chickn:
+
+  ./scripts/chickn.py
+
+To re-generate protobuf messages:
+
+  ./scripts/protobuf.py --download generate
+
+The CLI application can be used, e.g. run:
+
+  atvremote --debug commands
+  atvremote --debug playing
+
+To preview documentation in docs, run:
+
+  ./scripts/build_docs.sh
+
+and navigate to http://127.0.0.1:4000
+
+==================================================
+
+Environment is configured and ready to use!
+EOF

package/pyatv/setup.cfg

@@ -0,0 +1,14 @@
+[aliases]
+test=pytest
+
+[tool:pytest]
+testpaths = tests
+norecursedirs = .git
+
+[flake8]
+exclude = .venv,.git,.tox,docs,venv,bin,lib,deps,build
+max-line-length = 88
+ignore = E203, W503
+
+[pydocstyle]
+match_dir = ^((?!\.|www_static).)*$

package/pyatv/tests/data/README

@@ -0,0 +1,23 @@
+Audio files in this directory have been generated by the
+commands below in case they ever need to be re-generated.
+
+Only metadata, no audio:
+
+  python ../../scripts/audiogen.py --title pyatv --artist postlund --album raop -n 0 -o only_metadata.wav
+
+Audio, 10 frames (=20 samples):
+
+  python ../../scripts/audiogen.py -n 10 -o audio_10_frames.wav
+
+Audio, 352 * 3 frames = 3 packets (=1056 samples):
+
+  python ../../scripts/audiogen.py -n 1056 -o audio_3_packets.wav
+
+Audio, 8 seconds static (no sound), ogg for compression:
+
+  python ../../scripts/audiogen.py -n 132300 -s -o static_3sec.wav
+  ffmpeg -i static_3sec.wav static_3sec.ogg
+
+Audio, 1 packets (=352 samples), with metadata:
+
+  python ../../scripts/audiogen.py --title pyatv --artist postlund --album raop -n 352 -o audio_1_packet_metadata.wav

package/pyatv/tests/data/testfile.txt

@@ -0,0 +1 @@
+a file for testing

package/pyatv/tests/support/pyatv.code-workspace

@@ -0,0 +1,14 @@
+{
+	"folders": [
+		{
+			"path": "../.."
+		},
+		{
+			"path": "../../../airplay2-receiver"
+		},
+		{
+			"path": "../../../pyminiaudio"
+		}
+	],
+	"settings": {}
+}

package/src/index.ts

@@ -118,19 +118,68 @@ export interface AppleTVConnection {
   protocol: CompanionProtocol;
   device: AppleTVDevice;
   credentials: Credentials;
+  /** Credentials + endpoint used for this connection attempt/result. */
+  usedCredentials: ConnectionCredentialsSnapshot;
+  /** True when usedCredentials exactly match the values passed to connect(...). */
+  usedCredentialsMatchProvided: boolean;
   /** @internal */
   _keyboardFocusState: KeyboardFocusState;
 }
 
+export interface ConnectionCredentialsSnapshot {
+  airplay: string;
+  companion: string;
+  device: {
+    name: string;
+    address: string;
+    port: number;
+    airplayPort: number;
+    identifier: string;
+  };
+}
+
 function errorMessage(error: unknown): string {
   if (error instanceof Error) return error.message;
   return String(error);
 }
 
-function matchesDevice(target: AppleTVDevice, candidate: AppleTVDevice): boolean {
-  if (target.identifier && candidate.identifier === target.identifier) return true;
-  if (candidate.address === target.address) return true;
-  return candidate.name === target.name;
+const ID_PROPERTY_KEYS = new Set(['rpmrtid', 'deviceid', 'macaddress']);
+
+function normalizeIdentifier(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function getIdentifiers(device: AppleTVDevice): Set<string> {
+  const identifiers = new Set<string>();
+
+  if (device.identifier) {
+    identifiers.add(normalizeIdentifier(device.identifier));
+  }
+
+  for (const [key, value] of Object.entries(device.properties || {})) {
+    if (!value || !ID_PROPERTY_KEYS.has(key.toLowerCase())) continue;
+    identifiers.add(normalizeIdentifier(value));
+  }
+
+  return identifiers;
+}
+
+function sharesIdentifier(target: AppleTVDevice, candidate: AppleTVDevice): boolean {
+  const targetIds = getIdentifiers(target);
+  if (targetIds.size === 0) return false;
+
+  for (const identifier of getIdentifiers(candidate)) {
+    if (targetIds.has(identifier)) return true;
+  }
+
+  return false;
+}
+
+function deviceMatchScore(target: AppleTVDevice, candidate: AppleTVDevice): number {
+  if (sharesIdentifier(target, candidate)) return 100;
+  if (candidate.address === target.address) return 10;
+  if (candidate.name === target.name) return 1;
+  return 0;
 }
 
 function mergeDiscoveredDevice(target: AppleTVDevice, discovered: AppleTVDevice): AppleTVDevice {
@@ -141,6 +190,40 @@ function mergeDiscoveredDevice(target: AppleTVDevice, discovered: AppleTVDevice)
   };
 }
 
+function hasCompanionEndpointChanged(current: AppleTVDevice, discovered: AppleTVDevice): boolean {
+  return current.address !== discovered.address || current.port !== discovered.port;
+}
+
+function toCredentialSnapshot(
+  device: AppleTVDevice,
+  credentials: Credentials,
+): ConnectionCredentialsSnapshot {
+  return {
+    airplay: credentials.airplay,
+    companion: credentials.companion,
+    device: {
+      name: device.name,
+      address: device.address,
+      port: device.port,
+      airplayPort: device.airplayPort,
+      identifier: device.identifier,
+    },
+  };
+}
+
+function snapshotsEqual(
+  left: ConnectionCredentialsSnapshot,
+  right: ConnectionCredentialsSnapshot,
+): boolean {
+  return left.airplay === right.airplay
+    && left.companion === right.companion
+    && left.device.name === right.device.name
+    && left.device.address === right.device.address
+    && left.device.port === right.device.port
+    && left.device.airplayPort === right.device.airplayPort
+    && left.device.identifier === right.device.identifier;
+}
+
 async function connectCompanion(
   device: AppleTVDevice,
   companionCredentials: string,
@@ -154,7 +237,29 @@ async function connectCompanion(
 
 async function discoverLatestDevice(device: AppleTVDevice): Promise<AppleTVDevice | null> {
   const discovered = await scanDevices(3000, false);
-  return discovered.find((candidate) => matchesDevice(device, candidate)) || null;
+  let bestMatch: AppleTVDevice | null = null;
+  let bestScore = 0;
+
+  for (const candidate of discovered) {
+    const score = deviceMatchScore(device, candidate);
+    if (score === 0) continue;
+
+    if (!bestMatch || score > bestScore) {
+      bestMatch = candidate;
+      bestScore = score;
+      continue;
+    }
+
+    if (score === bestScore) {
+      const candidatePortMatches = candidate.port === device.port;
+      const currentPortMatches = bestMatch.port === device.port;
+      if (candidatePortMatches && !currentPortMatches) {
+        bestMatch = candidate;
+      }
+    }
+  }
+
+  return bestMatch;
 }
 
 /**
@@ -166,6 +271,7 @@ export async function connect(
   credentials: Credentials,
 ): Promise<AppleTVConnection> {
   let activeDevice = device;
+  const providedCredentials = toCredentialSnapshot(device, credentials);
   let protocol: CompanionProtocol;
 
   try {
@@ -178,17 +284,22 @@ export async function connect(
       discovered = null;
     }
 
-    if (!discovered || discovered.port === activeDevice.port) {
+    if (!discovered) {
+      throw initialError;
+    }
+
+    const mergedDevice = mergeDiscoveredDevice(activeDevice, discovered);
+    if (!hasCompanionEndpointChanged(activeDevice, mergedDevice)) {
       throw initialError;
     }
 
-    activeDevice = mergeDiscoveredDevice(activeDevice, discovered);
+    activeDevice = mergedDevice;
 
     try {
       protocol = await connectCompanion(activeDevice, credentials.companion);
     } catch (retryError) {
       throw new Error(
-        `Companion connection failed on saved port ${device.port} and discovered port ${activeDevice.port}: ${errorMessage(retryError)}`,
+        `Companion connection failed on saved endpoint ${device.address}:${device.port} and discovered endpoint ${activeDevice.address}:${activeDevice.port}: ${errorMessage(retryError)}`,
         { cause: initialError instanceof Error ? initialError : undefined },
       );
     }
@@ -236,8 +347,11 @@ export async function connect(
     protocol,
     device: activeDevice,
     credentials,
+    usedCredentials: toCredentialSnapshot(activeDevice, credentials),
+    usedCredentialsMatchProvided: false,
     _keyboardFocusState: KeyboardFocusState.Unknown,
   };
+  conn.usedCredentialsMatchProvided = snapshotsEqual(conn.usedCredentials, providedCredentials);
 
   // Watch keyboard focus state
   _watchKeyboardFocus(protocol, (state) => {