feat(yandex_music): improve configuration with My Wave, Liked Tracks, and organized settings

[trudenboy]

Summary

Major improvements to Yandex Music provider: FLAC lossless playback, Lyrics support, Picks & Mixes curated collections, extended recommendations, and streamlined configuration.

Scope: 11 files changed, ~3300 lines added, ~400 removed. 94 unit tests.

---

New Features

FLAC Lossless Playback

Lossless audio streaming with AES-256-CTR decryption for premium subscribers via /get-file-info API with HMAC-SHA256 signed requests. Lossless requests use _call_with_retry for automatic reconnection on transient failures — HMAC signature is recomputed with fresh timestamp on each retry.

Quality tiers:

Tier	Codec	Bitrate
Efficient	AAC	~64 kbps
Balanced (default)	AAC	~192 kbps
High	MP3	~320 kbps
Superb	FLAC	lossless

Streaming modes (for encrypted FLAC):

• Direct — decrypt on-the-fly, chunk-by-chunk
• Buffered (default) — async queue decouples download from consumption
• Preload — full download + decrypt to temp file before playback (enables seek)

Preload mode auto-falls back to Buffered when file exceeds configurable size limit.

Lyrics

Native lyrics from Yandex Music API:

• Synced LRC format (timestamped) when available — detected via \[\d{2}:\d{2} regex
• Plain text fallback
• Fetched from already-loaded track object (no extra API call)
• Cached with track data (30 days)
• Geo-restrictions handled silently

Picks & Mixes (Curated Collections)

Browse access to Yandex Music curated playlists with runtime tag validation:

Picks/
├── Mood      (sad, romantic, party, relax, in the mood, ...)
├── Activity  (morning, evening, background, ...)
├── Era       (80s, 90s, 2000s, ...)
└── Genres    (rock, jazz, classical, electronic, r&b, top, by genre, ...)

Mixes/
└── Seasonal  (winter, summer, autumn, newyear)

How it works:

• Tags sourced from hardcoded category lists + Landing API discovery (landing("mixes"))
• Each tag validated at runtime via client.get_tag_playlists() — only tags with actual playlists are shown
• Tag validation runs in parallel (asyncio.gather + Semaphore(8)) to minimize latency
• Editorial /post/ URLs from landing API are filtered out (only /tag/ entries kept)
• Validated tags are categorized into folders via TAG_SLUG_CATEGORY mapping (unknown tags default to Mood)
• Tags sorted within categories by TAG_CATEGORY_ORDER for consistent display
• Empty categories hidden — if no valid tags exist for a category, the folder is not shown
• Validation results cached for 1 hour to minimize API calls; tag playlists cached for 10 minutes
• Category and tag folders have is_playable=False to prevent accidentally loading thousands of tracks
• Dynamic seasonal fallback — if a seasonal tag (e.g., "spring") is not available, falls back dynamically via _validate_tag()

Extended Recommendations (Home Page)

Section	Source	Cache
My Wave	Rotor radio user:onyourwave	10 min
Made for You	Feed API (Playlist of the Day, DejaVu, etc.)	30 min
Chart	Chart API	1 hour
New Releases	New releases API (albums)	1 hour
New Playlists	New playlists API	1 hour
Top Picks	Tag top	1 hour
Mood Mix	Rotating validated mood tag	30 min
Activity Mix	Rotating validated activity tag	30 min
Seasonal Mix	Month-based tag	6 hours

Mood Mix and Activity Mix use pre-validated tags selected outside the cached method to ensure random.choice actually rotates on each cache miss.

My Wave Improvements

• Composite track_id@station_id item IDs for rotor feedback
• Rotor feedback: radioStarted, trackStarted, trackFinished, skip
• Duplicate track protection across batches (with asyncio.Lock)
• Configurable max tracks (default: 150)
• MY_WAVE_BATCH_SIZE controls the number of API batches to fetch (not per-batch size)
• Virtual playlist with cursor-based pagination
• "Load more" in browse
• Infinite loop fix: break when all tracks in a batch are duplicates

Liked Tracks

• Virtual playlist in library (always visible)
• Reverse chronological sort (most recently liked first)
• Configurable max tracks (default: 500)
• Batch fetching of full track details

Similar Tracks

Uses Yandex Rotor station track:{id} to get similar tracks for MA radio mode.

---

Configuration

8 settings total (4 shown by default, 4 advanced):

Setting	Type	Default	Advanced
Token	secure string	—	no
Reset auth	action	—	no
Audio quality	select	Balanced	no
FLAC streaming mode	select	Buffered	yes
Preload max file size (MB)	integer 10–500	100	yes (visible when mode=Preload)
My Wave max tracks	integer	150	yes
Liked Tracks max tracks	integer	500	yes
API Base URL	string	https://api.music.yandex.net	yes

---

Architecture

New Files

File	Purpose
streaming.py	YandexMusicStreamingManager — quality selection, AES-256-CTR decryption, streaming modes, shared aiohttp.ClientSession lifecycle, temp file management
constants.py	All configuration keys, quality/mode constants, browse names (RU/EN), tag categories, TAG_SLUG_CATEGORY mapping, TAG_CATEGORY_ORDER

Modified Files

File	Changes
__init__.py	Setup with SUPPORTED_FEATURES including LYRICS, BROWSE, RECOMMENDATIONS, SIMILAR_TRACKS; config entries
manifest.json	Added pycryptodome==3.23.0 dependency
api_client.py	YandexMusicClient wrapper with retry logic, rotor station API, /get-file-info lossless endpoint (with _call_with_retry), Landing tags API (with /post/ URL filtering), lyrics API (from already-fetched track object), library edit methods
provider.py	Browse (My Wave, Picks, Mixes with runtime tag validation), 9 recommendation methods, virtual playlists (My Wave, Liked Tracks), similar tracks via rotor, rotor feedback in on_played/on_streamed, locale-aware names (RU/EN), is_playable=False for navigation folders
parsers.py	parse_track accepts optional lyrics/lyrics_synced params

Data Flow

get_stream_details(item_id)
├── Quality=Superb → get_file_info_lossless (FLAC, via _call_with_retry)
│   ├── Encrypted → check streaming_mode
│   │   ├── Preload + fits limit → download+decrypt → LOCAL_FILE
│   │   ├── Preload + too large → CUSTOM + streaming_mode_override=buffered
│   │   └── Direct/Buffered → CUSTOM (decrypt in get_audio_stream)
│   └── Unencrypted → HTTP (direct URL)
└── Other quality → download-info API → select best codec → HTTP

---

Reliability

• Race condition fix: asyncio.Lock protects _my_wave_seen_track_ids across concurrent browse/playlist/recommendations calls
• Cache key normalization: get_track() normalizes composite IDs (track_id@station_id → track_id) before caching to prevent duplicate cache entries
• Auto-reconnect: _call_with_retry handles Server disconnected / network errors (includes lossless API)
• Shared streaming session: Single aiohttp.ClientSession reused across streams (created lazily, closed on unload)
• Temp file cleanup: On stream completion + periodic stale check (10 min max age) + full cleanup on unload
• File descriptor safety: temp_fd = -1 sentinel pattern prevents double-close and fd leaks on HTTP failures
• Cancelled task cleanup: Background download tasks are cancelled + awaited with suppress(CancelledError)
• Infinite loop fix: My Wave batch fetching breaks when all tracks in a batch are duplicates
• Tag validation: Runtime validation eliminates empty browse folders
• Logging: Downgraded noisy per-call INFO/WARNING logs to DEBUG; %s formatting throughout

---

Tests

94 tests across 4 files:

Test file	Tests	Coverage
test_integration.py	15	Registration, sync, browse, search, get track/album/artist/playlist, library edit, stream details (high + lossless quality)
test_streaming.py	17	Quality selection across all 4 tiers (Efficient, Balanced, High, Superb), content type mapping, AAC variant coverage, edge cases
test_recommendations.py	35	All 9 recommendation methods with mocked API responses, error handling, edge cases, duplicate filtering, aggregate tests
test_api_client.py	6	Client initialization, connection handling, retry logic
conftest.py (parsers)	21	Snapshot tests for track/album/artist/playlist parsing

All tests pass. Pre-commit (ruff lint + format) passes.

---

Localization

Browse folder names adapt to MA locale:

• ru_* → Russian names (Моя волна, Мне нравится, Подборки, etc.)
• Other → English names (My Wave, My Favorites, Picks, etc.)

---

🤖 Generated with Claude Code

[github-actions]

🔒 Dependency Security Report

📦 Modified Dependencies

music_assistant/providers/yandex_music/manifest.json

Added:

• ✅ pycryptodome ==3.23.0

Unchanged dependencies

• yandex-music ==2.2.0

---

🔍 Vulnerability Scan Results

No known vulnerabilities found
✅ No known vulnerabilities found

---

Automated Security Checks

• ✅ Vulnerability Scan: Passed - No known vulnerabilities
• ✅ Trusted Sources: All packages have verified source repositories
• ✅ Typosquatting Check: No suspicious package names detected
• ✅ License Compatibility: All licenses are OSI-approved and compatible
• ✅ Supply Chain Risk: Passed - packages appear mature and maintained

Manual Review

Maintainer approval required:

• I have reviewed the changes above and approve these dependency updates

To approve: Comment /approve-dependencies or manually add the dependencies-reviewed label.

[MarvinSchenkel]

The decryption logic needs to be rethought. We can't cache entire tracks. I will have another look at this PR when that has been refactor 👍

[trudenboy]

@MarvinSchenkel Thanks for the review! I've addressed the decryption_key / Apple Music suggestion in the inline reply — in short, Yandex uses raw AES-256-CTR (no MP4/CENC container), so ffmpeg's -decryption_key cannot handle it. PyCryptodome manual decryption is the only viable approach. But I will do some additional research on this topic.

Regarding "caching entire tracks" — this only happens in Preload mode, which is:

• Not the default — the default streaming mode is Buffered (async queue, streams as it decrypts, no full file caching)
• An optional advanced setting for users on low-powered devices (Raspberry Pi, cheap NAS) where simultaneous download + decryption + streaming causes audio stuttering
• Size-gated — configurable max file size (default 100 MB), files exceeding the limit automatically fall back to Buffered mode
• Tested on low-powered hardware — specifically designed for devices where CPU/IO constraints make real-time decrypt+stream unreliable

The default Buffered mode streams and decrypts on-the-fly via an async queue without caching entire tracks. The Direct mode does the same but without the queue buffer. Preload is simply an additional option for edge cases where real-time processing isn't feasible.

Preloaded temp files are never left behind — there's a 3-level cleanup mechanism:

1. on_streamed callback — the temp file is deleted immediately after playback finishes (or the track is skipped)
2. Stale file sweep — on every get_stream_details call, files older than 10 minutes are automatically cleaned up (catches edge cases like interrupted streams)
3. Provider unload — all remaining temp files are cleaned up when the provider is unloaded/removed

---

Update: Also fixed container handling for flac-mp4 codec (FLAC audio inside MP4 container) in the latest commits:

• b6b11a2 — _get_content_type("flac-mp4") now correctly returns (ContentType.MP4, ContentType.FLAC) instead of (ContentType.FLAC, ContentType.UNKNOWN). This properly separates the container format (MP4) from the audio codec (FLAC), so ffmpeg gets the correct -acodec flac hint while auto-detecting the MP4 container. Preloaded temp files also get the correct .mp4 extension.
• f59a49f — Follow-up cleanup: log messages now use the actual codec string (flac / flac-mp4) instead of hardcoded "FLAC", TEMP_FILE_PREFIX renamed from "yandex_flac_" to "yandex_audio_" (since temp files can be .mp4), and added a clarifying comment in _select_best_quality about flac-mp4 forward compatibility.

Happy to discuss further or adjust anything! 🙏

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.