fix: playback scans against inactive player

[treyturner]

Summary

Fix NFC playback scans when Plexamp is stopped with no active queue.

Direct requests to Plexamp now derive the Plex server identifier from autoplay tags and verify that playback actually creates an active queue before reporting success.

⚠️ GitHub Actions need to be enabled on this repo for tests to run in CI.

Root cause

The service forwarded listen.plex.tv autoplay URLs directly to Plexamp’s local companion API. This bypassed two behaviors normally provided by the Plex web client:

• Deriving machineIdentifier from the nested server://<machine-id>/... URI
• Waiting for the asynchronous playback request to create a queue

Plexamp could therefore return HTTP 200 without starting playback, causing the service to log a false success.

Changes

• Extract Plexamp URL preparation and HTTP control into plexamp.py.
• For /player/playback/playMedia URLs:
  • Parse the nested server:// URI.
  • Add the derived machineIdentifier when absent.
  • Preserve explicitly supplied identifiers.
  • Reject missing or malformed inner URIs without contacting Plexamp.
• Add:
  • Process-local increasing commandID values.
  • X-Plex-Client-Identifier.
  • X-Plex-Device-Name.
• Record the current music timeline before sending playback.
• Poll the timeline every 500 ms for up to 10 seconds after the request.
• Require playing or buffering with a populated play queue.
• When playback was already active, require the queue ID to change.
• Treat HTTP failures, connection errors, invalid timelines, and verification timeouts as playback failures.
• Only log Playback triggered! and update last_url after successful verification.
• Add the repository’s first unittest suite.
• Add GitHub Actions testing for Python 3.8 and 3.14 on pull requests and pushes to main.

Dependencies, public configuration, NFC debounce behavior, and automatic retry behavior remain unchanged.

To run tests

• python -m unittest discover -s tests -v
• python -m compileall -q main.py plexamp.py
• actionlint .github/workflows/tests.yml
• Full requirements installation and test suite passed under Python 3.8 and Python 3.14.

All 12 automated tests pass.

Testing performed

Validated against a live Plexamp instance:

• Starting from a stopped player with an empty queue successfully created an active queue and began playback.
• Repeating playback while a queue was already active succeeded only after Plexamp created a different queue.
• Both transitions were detected in under one second.

Also completed hardware acceptance:

• Started playback of an album tag while Plexamp is stopped with an empty queue.
• Scanned a different tag during playback and confirmed the queue changed.
• Stopped playback and successfully repeated the first scan.