feat: Add MSX Bridge Player Provider

[trudenboy]

Summary

New Player Provider that streams Music Assistant to Smart TVs via the Media Station X (MSX) app. Runs an embedded HTTP server (default port 8099) inside the MA process — no external containers or services required.

Smart TV (MSX App) ──HTTP/WS──▶ MSXBridgeProvider (port 8099) ──internal API──▶ MA core

---

Architecture

Provider Files

File	Lines	Purpose
__init__.py	142	setup(), get_config_entries(), feature flags
provider.py	703	MSXBridgeProvider(PlayerProvider): lifecycle, player registry, idle timeout, WS push, SharedGroupStream
player.py	381	MSXPlayer(Player): play/pause/stop/resume, position reporting, queue sync, echo prevention
http_server.py	2168	MSXHTTPServer: aiohttp server, 50 routes, WebSocket handler, audio streaming, CORS
mappers.py	224	MA media items → MSX JSON content objects, playlist builder
models.py	58	Pydantic models for MSX content pages (MSXContentPage, MSXContentItem)
constants.py	38	Config keys, defaults, regex patterns
manifest.json	12	Provider metadata
static/plugin.html	463	MSX interaction plugin (device ID detection, WebSocket client, menu)
static/input.html/js	1401	MSX Input Plugin (search keyboard)
static/web/	2277	Browser-based web player (no MSX app needed)

HTTP Endpoints

MSX Bootstrap & Navigation:

Method	Route	Purpose
GET	/	Status dashboard
GET	/msx/start.json	MSX app entry point
GET	/msx/plugin.html	MSX interaction plugin
GET	/msx/menu.json	Main menu (Albums, Artists, Playlists, Tracks, Search)
GET	/msx/albums.json	Albums listing
GET	/msx/artists.json	Artists listing
GET	/msx/playlists.json	Playlists listing
GET	/msx/tracks.json	Tracks listing
GET	/msx/recently-played.json	Recently played
GET	/msx/search-page.json	Search UI with input plugin
GET	/msx/search-input.json	Search results from keyboard input
GET	/msx/search.json	Search results (API-style)

MSX Detail Pages:

Method	Route	Purpose
GET	/msx/albums/{id}/tracks.json	Album tracks
GET	/msx/artists/{id}/albums.json	Artist albums
GET	/msx/playlists/{id}/tracks.json	Playlist tracks

MSX Native Playlists (per-track streaming):

Method	Route	Purpose
GET	/msx/queue-playlist/{player_id}.json	MA queue → MSX playlist
GET	/msx/playlist/album/{id}.json	Album as playlist
GET	/msx/playlist/playlist/{id}.json	Playlist as playlist
GET	/msx/playlist/tracks.json	All tracks as playlist
GET	/msx/playlist/recently-played.json	Recently played as playlist
GET	/msx/playlist/search.json	Search results as playlist

Audio Streaming:

Method	Route	Purpose
GET	/msx/audio/{player_id}	Audio stream for MSX playback (PCM → ffmpeg → MP3/AAC/FLAC)
GET	/stream/{player_id}	Direct stream proxy (programmatic playback)

Library REST API:

Method	Route	Purpose
GET	/api/albums, /api/artists, /api/playlists, /api/tracks	Library browsing
GET	/api/albums/{id}/tracks, /api/artists/{id}/albums, /api/playlists/{id}/tracks	Detail endpoints
GET	/api/search, /api/recently-played	Search and history
GET	/api/lyrics/{id}	Track lyrics for current player
GET	/api/queue/{id}	Current playback queue
POST	/api/play	Start playback
ANY	/api/pause/{id}, /api/stop/{id}, /api/next/{id}, /api/previous/{id}	Playback control
ANY	/api/quick-stop/{id}	Immediate stop (abort stream + WS notify)

Other:

Method	Route	Purpose
GET	/health	Health check
GET	/ws	WebSocket endpoint
GET	/web	Browser-based web player

WebSocket Protocol

Server → Client (MA → MSX):

Type	Payload	Purpose
play	path, title, artist, image_url, duration	Playback started
playlist	url	Push MSX native playlist
goto_index	index	Jump to track in playlist
pause	—	Pause playback
resume	—	Resume playback
stop	showNotification	Stop playback

Client → Server (MSX → MA):

Type	Payload	Purpose
position	position (seconds)	Position reporting (3s interval)
pause	position	User paused on TV
resume	—	User resumed on TV
debug_info	data (device capabilities)	Device diagnostics

---

Features

Dynamic Player Registration

• TVs register as MA players on first HTTP request (device ID or IP-based)
• Multi-TV support: each TV gets a unique player (msx_<device_id>)
• Idle timeout cleanup (configurable, default 30 min)
• Race condition handling via _pending_unregisters events
• on_player_disabled override: keeps player registered (no re-discovery needed on enable)

Native Playlist Playback

• MA builds playlist from queue, pushes to TV via WebSocket playlist message
• Each track streams individually through /msx/audio/ — no flow mode
• MSX controls prev/next navigation natively
• Playlist rotation: clicked track always at index 0
• goto_index for MA-initiated track changes
• Skip re-enqueue when MA drives queue (prevents loops)

Bidirectional Sync

• MSX → MA: Position reporting via WS (3s timer), pause/resume detection
• MA → MSX: broadcast_pause/broadcast_resume notifications
• Echo prevention: _skip_ws_notify flag prevents notification loops (wrapped in try/finally)
• update_position() prefers WebSocket data over wall-clock polling

Audio Streaming Pipeline

MA Queue → mass.streams.get_stream() → raw PCM → get_ffmpeg_stream() → MP3/AAC/FLAC → HTTP → TV

• Pre-buffer 64KB before sending HTTP headers (prevents MSX stutter)
• Chunk queue maxsize=32 for network jitter tolerance
• Content-Length from duration × bytes_per_sec for MSX progress bar
• Three stream modes for groups: Independent, Shared Buffer, Redirect (scaffold)

Player Grouping (Experimental)

• enable_player_grouping config toggle (default: true)
• SharedGroupStream: one ffmpeg process, multiple TV readers via shared buffer
• Late joiners receive buffered catch-up data under lock (race condition safe), then live stream
• Recursion guard for group propagation
• Parallel member notification

Browser Web Player

• /web — full-featured player without MSX app
• Library browsing, playback controls, keyboard shortcuts
• Kiosk mode (/web?kiosk=1): immersive full-screen album art with auto-hiding controls
• Karaoke lyrics overlay in kiosk mode
• Queue panel with two-column layout (art+controls | queue)
• Three-column kiosk layout (art | lyrics/equalizer | queue)
• CSS equalizer animation
• Sendspin audio mode integration (scaffold, disabled by default)

---

Configuration

Key	Type	Default	Description
http_port	int	8099	HTTP server port
output_format	enum	mp3	Audio format (MP3, AAC, FLAC)
player_idle_timeout	int	30	Minutes before unregistering idle players
show_stop_notification	bool	false	Show notification on MSX when stopping
abort_stream_first	bool	false	Cancel stream before WS stop (vs. after)
enable_player_grouping	bool	true	Enable SYNC_PLAYERS / SET_MEMBERS features
group_stream_mode	enum	independent	Group streaming: Independent / Shared Buffer

---

Testing

121 unit tests (120 passed + 1 skipped):

Test File	Tests	Coverage
test_http_server.py	53	Routes, content pages, audio streaming, WS, queue API, CORS
test_player.py	42	Play/pause/stop/resume, position, queue sync, groups
test_provider.py	9	Registration, idle timeout, lifecycle, group streams
test_init.py	6	Config entries, setup, feature flags
test_playlist.py	5	Playlist mapping, rotation, serialization
test_models.py	4	Pydantic models, aliases, serialization
test_mappers.py	2	Track formatting, content mapping

Pre-commit: ruff ✅, mypy ✅

---

Screenshots

---

Links

• Media Station X
• msx-music-assistant — development repo
• Documentation PR: docs: Add MSX Bridge player provider documentation beta.music-assistant.io#83

---

🤖 Generated with Claude Code

[github-actions]

🔒 Dependency Security Report

✅ No dependency changes detected in this PR.

[OzGav]

Ensure you run pre-commit before pushing any commits.

[Copilot]

Pull request overview

Adds a new MSX Bridge player provider to Music Assistant, enabling Smart TV playback via the Media Station X (MSX) app (HTTP content endpoints + WebSocket control), along with a bundled web UI and a comprehensive test suite.

Changes:

• Introduce the MSX Bridge provider/player implementation, including grouping/shared-stream scaffolding and MSX content models/mappers.
• Add MSX/TV plugin + web client static assets for browsing/playback and device identification.
• Add extensive unit tests covering provider lifecycle, player behavior (queue/playlist sync, grouping), mappers/models, and HTTP server routes.

Reviewed changes

Copilot reviewed 22 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/providers/msx_bridge/init.py	Marks the MSX Bridge test package.
tests/providers/msx_bridge/conftest.py	Adds fixtures for provider/player/http client testing.
tests/providers/msx_bridge/test_http_server.py	Tests HTTP routes, MSX content endpoints, and WS inbound handling.
tests/providers/msx_bridge/test_init.py	Tests provider setup and config entry behavior/feature flags.
tests/providers/msx_bridge/test_mappers.py	Tests mapping MA media items to MSX items/actions.
tests/providers/msx_bridge/test_models.py	Tests Pydantic model alias serialization.
tests/providers/msx_bridge/test_player.py	Tests MSXPlayer playback, queue playlist sync, grouping propagation, and position reporting.
tests/providers/msx_bridge/test_playlist.py	Tests queue/track list → MSX playlist content mapping.
tests/providers/msx_bridge/test_provider.py	Tests provider lifecycle methods and player enable/disable behavior.
music_assistant/providers/msx_bridge/init.py	Provider entry point: setup + config entries (including grouping/stream mode).
music_assistant/providers/msx_bridge/constants.py	Adds provider constants and config keys/defaults.
music_assistant/providers/msx_bridge/icon.svg	Adds provider icon asset.
music_assistant/providers/msx_bridge/icon_monochrome.svg	Adds monochrome provider icon asset.
music_assistant/providers/msx_bridge/manifest.json	Registers the provider manifest metadata.
music_assistant/providers/msx_bridge/mappers.py	Implements mapping helpers for MSX content pages/items and playlist audio actions.
music_assistant/providers/msx_bridge/models.py	Adds Pydantic models for MSX JSON content structures.
music_assistant/providers/msx_bridge/player.py	Implements MSXPlayer with WS sync, queue playlist behavior, and grouping propagation.
music_assistant/providers/msx_bridge/provider.py	Implements provider lifecycle, player registration/timeout, stop/pause/resume notifications, and shared-group stream manager.
music_assistant/providers/msx_bridge/static/input.html	Adds MSX input plugin HTML wrapper.
music_assistant/providers/msx_bridge/static/input.js	Adds vendored MSX input interaction plugin JS.
music_assistant/providers/msx_bridge/static/plugin.html	Adds MSX InteractionPlugin bridge (menu + WS control + device ID).
music_assistant/providers/msx_bridge/static/web/index.html	Adds browser-based MSX UI shell (normal + kiosk modes).
music_assistant/providers/msx_bridge/static/web/web.js	Adds browser-based MSX UI logic + WS sync + optional Sendspin kiosk integration.

---

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

[Copilot]

Pull request overview

Copilot reviewed 22 out of 26 changed files in this pull request and generated 5 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 22 out of 26 changed files in this pull request and generated 9 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 22 out of 26 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.