Summary

Add new Yandex Music Connect (Ynison) plugin provider that makes Music Assistant players appear as playback devices in the Yandex Music app — similar to how Spotify Connect works.

When a user selects the MA device in the Yandex Music app, the plugin receives track IDs via the Ynison WebSocket protocol, fetches audio from Yandex Music CDN (via the linked yandex_music MusicProvider), and streams PCM to the selected MA player.

Architecture

Yandex Music app (phone/web/desktop)
  -> Ynison WebSocket <-> YandexYnisonProvider
    -> receives track_id from PlayerState
    -> fetches audio via linked yandex_music MusicProvider
    -> PCM audio -> PluginSource -> MA Player (Chromecast/DLNA/AirPlay/etc.)
    <- play/pause/seek/next/prev -> update_playing_status back to Ynison

Authentication model

The plugin supports two top-level auth modes, picked via the Yandex Music source dropdown. Together they give three reachable populated states:

• Borrow mode (default when a yandex_music MusicProvider is configured) — read OAuth credentials live from a linked yandex_music instance via ProviderConfig.get_value(). No secrets stored in the Ynison config; reactive refresh from x_token on 401 is in-memory only (scheduled refresh stays with yandex_music).
• Own mode — QR login — a per-instance Login with QR code action opens a Passport QR popup (via AuthenticationHelper); on scan-confirm both the music token and the long-lived x_token are stored in this plugin's config. Each instance can be bound to its own Yandex account without sharing tokens with a yandex_music provider — useful with multi_instance: true for one-account-per-player setups. A Remember session toggle controls x_token persistence; with it enabled the plugin reactively refreshes on 401 in own mode, mirroring borrow behaviour.
• Own mode — manual paste — escape hatch for headless setups: paste a music token by hand into CONF_TOKEN. With no stored x_token, expiry surfaces a clear LoginFailed so the user knows to paste a new token.

Upgrades from earlier standalone versions preserve own-mode if CONF_TOKEN was set, so no silent switch of auth source.

Key features

• Ynison WebSocket protocol: two-step connection (redirector → state service), device registration, bidirectional state sync
• Reconnect resilience: unbounded exponential backoff with ±20% jitter (5s → 10s → 30s → 60s, saturating), session ownership tracking, graceful disconnect handling
• Audio streaming via linked yandex_music MusicProvider with FFmpeg PCM conversion (-re realtime pacing) and byte-accurate progress sync
• Playback control: play / pause / next / prev / seek, synced bidirectionally to Ynison state
• Echo detection: version.device_id-based — inspects the author of incoming player_queue and status version blocks to suppress feedback loops from our own round-tripped updates (covers both queue and status-only echoes)
• Ynison-safe wire format: all outbound version/timestamp_ms/progress_ms/duration_ms fields are string-typed (integers trigger HTTP 500 + WS teardown); inbound state is normalized at ingestion so reconnect replays and queue edits stay safe by construction
• Per-instance QR auth + reactive refresh (own mode): own-mode tokens come from a Passport QR scan or manual paste; with Remember session on the plugin refreshes the music token from a stored x_token on 401 — no manual re-paste, no shared yandex_music instance required
• Radio queue management: proactive prefetch of next radio batch at ~80% track progress, SyncStateFromEOV for queue replenishment, bounds-validated queue advancement
• Pause-resume handling: polling-based pause wait (1s intervals, 30s deadline) to correctly handle same-track resume without blocking on track-change events
• Plugin source ownership: clean in_use_by lifecycle — released on pause, re-acquired on resume via needs_reselect flag
• Player selection: auto (first available) or manual target player
• Metadata sync: title, cover art, duration, and elapsed time pushed to MA frontend via StreamMetadata

Changed files

Test plan

• 218 unit tests pass (pytest)
• ruff lint and format clean
• mypy type check clean
• Manual testing on HAOS: device appears in Yandex Music app, audio plays through MA player (DLNA), track changes, pause/resume, seek, and radio queue advancement work correctly
• Manual testing of upgrade path: existing standalone-token configs preserve own-mode; fresh installs auto-select the sole yandex_music instance
• Manual testing of own-mode QR: QR popup renders, scan-confirm populates token and x_token, Logged in as <login> status is shown; second instance can be bound to a different Yandex account; reset-auth clears all three fields

Related PRs

• Documentation PR: docs(plugins): add Yandex Music Connect (Ynison) plugin page music-assistant.io#624

Dependencies

• ya-passport-auth==1.3.0 — async Yandex Passport client. Used for refresh_music_token(x_token) (borrow + own modes) and the QR login flow (PassportClient.start_qr_login + poll_qr_until_confirmed).
• Requires yandex_music MusicProvider (depends_on in manifest) — hard requirement for audio streaming. Borrow mode additionally reads its OAuth credentials. Runtime detection via _check_yandex_provider_match() handles the edge case where the provider is unloaded while the plugin is running; borrow-mode token reads surface a clear LoginFailed if the linked instance was removed.

Source: trudenboy/ma-provider-yandex-ynison · branch dev · v1.8.0