Yandex Smart Home — Music Assistant Plugin Provider

📖 Documentation / Документация · 🔄 Changelog / Журнал · 🐛 Issues / Проблемы · 💬 Discussions / Обсуждения

Related providers: Yandex Alice · Yandex Station · Yandex Music

Expose Music Assistant players to Yandex Alice via the Yandex Smart Home API.

«Алиса, включи музыку на Music Assistant»

Overview

This plugin bridges Music Assistant and the Yandex Smart Home ecosystem. It registers MA players as smart home devices (type media_device.receiver), enabling voice control through Yandex Alice.

Voice Commands

Voice command	Action
«Алиса, включи музыку на <имя>»	Play / resume current queue
«Алиса, выключи <имя>»	Stop playback
«Алиса, сделай громче на <имя>»	Volume up (+10)
«Алиса, сделай тише на <имя>»	Volume down (-10)
«Алиса, поставь громкость 50 на <имя>»	Set volume to 50%
«Алиса, пауза на <имя>»	Pause
«Алиса, дальше на <имя>»	Next track
«Алиса, назад на <имя>»	Previous track

Architecture

Alice voice command
        │
        ▼
  Yandex Cloud
        │
        ▼ (Smart Home API callback)
┌───────────────────┐
│  This plugin      │──────► MA Player commands
│  (PluginProvider)  │       (play/pause/stop/vol/next/prev/source)
│                   │
│  Cloud relay      │◄────── MA Player state events
│  (yaha-cloud.ru)  │──────► Yandex state reports
└───────────────────┘

Yandex Smart Home Capabilities

Yandex Capability	MA Player Action	Notes
on_off	play() / stop()	"включи" resumes queue, "выключи" stops
range(volume)	volume_set()	Absolute and relative (±)
toggle(mute)	volume_mute()	Only if player supports VOLUME_MUTE
toggle(pause)	play() / pause()
range(channel)	next_track() / previous_track()	Relative only: +1=next, -1=prev
mode(input_source)	select_source()	Maps source_list by index (max 10)

Note: Yandex Smart Home API does not support play_media for third-party devices. "Включи музыку" triggers play/resume on the current MA queue, not a specific track.

Installation

This provider is under active development.

As a custom provider

1. Copy the provider/ folder to your MA custom providers directory
2. Restart Music Assistant
3. Go to Settings → Providers → Add → Yandex Smart Home
4. Follow the guided setup wizard and choose a connection mode:
   • Cloud — public Yaha Cloud skill; simplest setup
   • Cloud Plus — private skill through the relay; use this when the public skill is already linked to another installation
   • Direct — Yandex calls your MA server over a public HTTPS URL; no relay
5. Complete the steps shown by Music Assistant. Registration, Yandex sign-in, skill provisioning and account linking are presented in the required order.

Development

# Clone
git clone https://github.com/trudenboy/ma-provider-yandex-smarthome.git
cd ma-provider-yandex-smarthome

# Dev environment with Docker (recommended)
docker compose -f docker-compose.dev.yml up

# Or manual setup
pip install -e ".[test]"
pytest

Configuration

Parameter	Description
Instance Name	How this MA instance appears in Yandex Smart Home. Alice uses this name.
Exposed Players	Select which MA players to expose to Alice. Empty = all players.
Exposed Playlists	Select up to 10 library playlists to expose as input-source slots.

Connection mode and credentials are collected by the setup wizard. Reconfigure the provider to run that wizard again; the regular settings page only contains playback options.

Setup flow per mode

The wizard persists each provider's setup credentials separately from its normal playback options. For skill provisioning, you can use this provider's own Yandex account or borrow the authenticated account from a configured Yandex Music provider.

Cloud Plus (3 steps)

1. The wizard registers a private yaha-cloud.ru relay slot.
2. Choose automatic skill creation or enter the ID of an existing Yandex Dialogs skill. Automatic creation shows a Yandex Device Flow code inside the wizard and resumes when confirmation is detected.
3. Paste the skill OAuth token, then enter the one-time linking code shown by Music Assistant in the Yandex app.

Direct (1 step)

1. Enter or confirm the public HTTPS URL for Music Assistant. The wizard validates it before provisioning.
2. Confirm the Yandex Device Flow code; the provider creates and configures the private skill.
3. Paste the skill OAuth token. Linking then uses Yandex Dialogs account linking, so there is no relay OTP.

Cloud (unchanged)

The wizard registers the public relay slot, displays a one-time code, and waits while you enter it in the Yandex app.

Limitations

• No play_media — Alice cannot start a specific song/playlist. "Включи музыку" only resumes the current MA queue.
• Max 10 input sources — Yandex mode capability supports up to 10 values.
• No seek — Yandex Smart Home API does not support seek for third-party media devices.
• No track info — Cannot push track name/artwork to Yandex (not supported by the API).

Status

• Project scaffold with CI/CD
• Cloud relay connection (yaha-cloud.ru WebSocket)
• Cloud Plus mode (private skill via Yandex.Dialogs)
• Auto-registration config flow with OTP
• Device registration & discovery
• Capability: on_off, volume, mute, pause
• Capability: next/previous track (channel)
• Capability: input source selection (mode)
• Player filter (expose selected players only)
• State reporting to Yandex (debounced + heartbeat)
• Direct connection mode (HTTP endpoints on MA webserver, no relay)
• Smart on_off (resume YaMusic playback when queue is empty)

Related Projects

• ma-provider-yandex-station — Player provider for Yandex Station speakers (Glagol protocol)
• dext0r/yandex_smart_home — Home Assistant ↔ Yandex Smart Home integration (reference implementation)
• Music Assistant — The music server this plugin extends

License

MIT — see LICENSE.