From b0ae23eedb66ba01e97ca3d85df8686b2d98fb9d Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy Date: Wed, 22 Apr 2026 20:50:16 +0300 Subject: [PATCH 1/9] docs(plugins): add Yandex Smart Home plugin page Document the Yandex Smart Home plugin that exposes MA players to Yandex Alice as smart home media devices. Covers connection modes (cloud / cloud_plus / direct), supported capabilities and voice commands, setup steps, settings, and API limitations. Co-Authored-By: Claude Opus 4.7 --- astro.config.mjs | 1 + src/content/docs/plugins/yandex-smarthome.md | 91 ++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 src/content/docs/plugins/yandex-smarthome.md diff --git a/astro.config.mjs b/astro.config.mjs index 30eed47a2..219c8ce89 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -262,6 +262,7 @@ export default defineConfig({ { label: 'Spotify Connect Plugin', slug: 'plugins/spotify-connect' }, { label: 'Subsonic Scrobbler', slug: 'plugins/subsonic_scrobble' }, { label: 'VBAN Receiver', slug: 'plugins/vban-receiver' }, + { label: 'Yandex Smart Home Plugin', slug: 'plugins/yandex-smarthome' }, ], }, { label: 'Desktop Companion App', slug: 'companion-app' }, diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md new file mode 100644 index 000000000..7a5b63d73 --- /dev/null +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -0,0 +1,91 @@ +--- +title: "Yandex Smart Home Plugin" +description: Features and Notes for the Yandex Smart Home Plugin +--- + +# Yandex Smart Home + +Music Assistant can expose its players to [Yandex Alice](https://alice.yandex.ru/) via the [Yandex Smart Home API](https://yandex.ru/dev/dialogs/smart-home/), so they can be controlled by voice as smart home media devices. Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). + +This plugin is built on top of the [ya-passport-auth](https://github.com/trudenboy/ya-passport-auth) library and uses the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) protocol implementation as a reference. + +> [!CAUTION] +> This is an unofficial implementation and is not affiliated with or endorsed by Yandex. + +> [!WARNING] +> The Yandex Smart Home API does not support `play_media` for third-party devices. +> Voice commands like «Алиса, включи музыку» will only resume the current Music Assistant queue — a specific track, album or playlist cannot be started by voice through this plugin. + +> [!NOTE] +> Full plugin documentation (RU/EN): **[trudenboy.github.io/ma-provider-yandex-smarthome](https://trudenboy.github.io/ma-provider-yandex-smarthome/)** + + +## Features + +| | | +|:-----------------------|:---------------------:| +| Exposes MA players to Yandex Alice | Yes | +| Device type | `devices.types.media_device.receiver` | +| Connection modes | Cloud, Cloud Plus, Direct | +| Multiple instances | No | +| Player filter (expose a subset) | Yes | +| State reporting to Yandex | Yes (debounced + heartbeat) | + +### Supported voice commands + +| Voice command | Action | +|---|---| +| «Алиса, включи музыку на \» | Play / resume the current queue | +| «Алиса, выключи \» | Stop playback | +| «Алиса, сделай громче / тише на \» | Volume up / down (±10) | +| «Алиса, поставь громкость 50 на \» | Set volume to 50% | +| «Алиса, пауза на \» | Pause | +| «Алиса, дальше / назад на \» | Next / previous track | +| «Алиса, переключи на \ на \» | Select input source (if the player exposes a source list) | + +### Yandex Smart Home capabilities + +| Yandex capability | Mapped MA action | Notes | +|---|---|---| +| `on_off` | `play()` / `stop()` | "включи" resumes the current queue, "выключи" stops | +| `range(volume)` | `volume_set()` | Absolute and relative (±) | +| `toggle(mute)` | `volume_mute()` | Only if the player supports mute | +| `toggle(pause)` | `play()` / `pause()` | | +| `range(channel)` | `next_track()` / `previous_track()` | Relative only: +1 = next, -1 = prev | +| `mode(input_source)` | `select_source()` | Uses the player's source list by index (up to 10) | + +## Configuration + +The plugin supports three connection modes — pick the one that matches your network setup: + +- **Cloud** — uses the public [yaha-cloud.ru](https://dialogs.yandex.ru/store/skills/7e26cc81-uma-assistant) skill as a relay. Easiest setup, no public URL required. +- **Cloud Plus** — uses a private skill via the same relay. Required if Yaha Cloud is already linked to another integration (e.g. Home Assistant) on the same Yandex account. +- **Direct** — Yandex calls your MA server directly over HTTPS. No relay required, but your Music Assistant webserver must be reachable on a public HTTPS URL. + +### Cloud / Cloud Plus setup + +1. Add the **Yandex Smart Home** plugin in Music Assistant settings and select `cloud` or `cloud_plus` as the connection type. +2. Click **Register with cloud** — the plugin creates an instance on the `yaha-cloud.ru` relay and returns an OTP code. +3. In the Yandex app on your phone: **Devices → Add device → Smart Home**, find the skill and enter the OTP. +4. (Cloud Plus only) Create a private skill in [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home). The plugin's config flow shows every required value to paste into the skill settings. + +### Direct setup + +1. Create a private skill in [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home). +2. Copy the Backend URL and Account Linking URLs shown by the plugin config flow into the skill settings, then publish the skill. +3. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. + +### Settings + +- **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. +- **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). +- **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. +- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes, obtained from the [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home) developer console. + +## Known Issues / Notes + +- `play_media` is not supported by the Yandex Smart Home API, so Alice cannot start a specific song/album/playlist on an MA player — "включи музыку" only resumes the current queue. +- The `mode` capability supports up to 10 values, so only the first 10 entries of a player's source list are exposed to Alice. +- Seek is not supported by the Yandex Smart Home API for third-party media devices. +- Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. +- Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. From e18a43b7f2e0b413be6e3167ada20638865abe8b Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy Date: Wed, 22 Apr 2026 20:56:48 +0300 Subject: [PATCH 2/9] docs(plugins): reference yaha-cloud.ru instead of ya-passport-auth ya-passport-auth is an internal helper used only marginally; linking to yaha-cloud.ru is more useful for users reading the plugin documentation. Co-Authored-By: Claude Opus 4.7 --- src/content/docs/plugins/yandex-smarthome.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 7a5b63d73..b1fd34f76 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -7,7 +7,7 @@ description: Features and Notes for the Yandex Smart Home Plugin Music Assistant can expose its players to [Yandex Alice](https://alice.yandex.ru/) via the [Yandex Smart Home API](https://yandex.ru/dev/dialogs/smart-home/), so they can be controlled by voice as smart home media devices. Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). -This plugin is built on top of the [ya-passport-auth](https://github.com/trudenboy/ya-passport-auth) library and uses the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) protocol implementation as a reference. +Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. The protocol implementation follows the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) reference integration. > [!CAUTION] > This is an unofficial implementation and is not affiliated with or endorsed by Yandex. @@ -58,7 +58,7 @@ This plugin is built on top of the [ya-passport-auth](https://github.com/trudenb The plugin supports three connection modes — pick the one that matches your network setup: -- **Cloud** — uses the public [yaha-cloud.ru](https://dialogs.yandex.ru/store/skills/7e26cc81-uma-assistant) skill as a relay. Easiest setup, no public URL required. +- **Cloud** — uses the public [yaha-cloud.ru](https://yaha-cloud.ru/) skill as a relay. Easiest setup, no public URL required. - **Cloud Plus** — uses a private skill via the same relay. Required if Yaha Cloud is already linked to another integration (e.g. Home Assistant) on the same Yandex account. - **Direct** — Yandex calls your MA server directly over HTTPS. No relay required, but your Music Assistant webserver must be reachable on a public HTTPS URL. From 2dcb594cfbd2f2a71069d0b0681a527dd6aead34 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Fri, 24 Apr 2026 12:23:46 +0300 Subject: [PATCH 3/9] Revise Yandex Smart Home plugin documentation Updated Yandex Smart Home documentation to clarify voice commands and capabilities. Adjusted references to Yandex Alice and improved formatting. --- src/content/docs/plugins/yandex-smarthome.md | 34 +++++++++----------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index b1fd34f76..8791809a9 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -5,9 +5,11 @@ description: Features and Notes for the Yandex Smart Home Plugin # Yandex Smart Home -Music Assistant can expose its players to [Yandex Alice](https://alice.yandex.ru/) via the [Yandex Smart Home API](https://yandex.ru/dev/dialogs/smart-home/), so they can be controlled by voice as smart home media devices. Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). +Music Assistant can expose its players to [Yandex Smart Home](https://alice.yandex.ru/smart-home) , so they can be controlled by Alice voice assistant as smart home multimedia devices. -Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. The protocol implementation follows the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) reference integration. +Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). +Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. +The implementation follows the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) reference integration. > [!CAUTION] > This is an unofficial implementation and is not affiliated with or endorsed by Yandex. @@ -22,32 +24,29 @@ Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. Th ## Features -| | | +| Function | Note | |:-----------------------|:---------------------:| -| Exposes MA players to Yandex Alice | Yes | -| Device type | `devices.types.media_device.receiver` | +| Exposes MA players to Yandex SmartHome | Yes | +| Device type | Multimedia | | Connection modes | Cloud, Cloud Plus, Direct | -| Multiple instances | No | -| Player filter (expose a subset) | Yes | -| State reporting to Yandex | Yes (debounced + heartbeat) | ### Supported voice commands | Voice command | Action | |---|---| -| «Алиса, включи музыку на \» | Play / resume the current queue | -| «Алиса, выключи \» | Stop playback | -| «Алиса, сделай громче / тише на \» | Volume up / down (±10) | -| «Алиса, поставь громкость 50 на \» | Set volume to 50% | -| «Алиса, пауза на \» | Pause | -| «Алиса, дальше / назад на \» | Next / previous track | -| «Алиса, переключи на \ на \» | Select input source (if the player exposes a source list) | +| «Alice, play music on \» | Play / resume the current queue | +| «Alice, power off \» | Stop playback | +| «Alice, turn up / turn down on \» | Volume up / down (±10) | +| «Alice, set volume to 50 on \» | Set volume to 50% | +| «Alice, pause on \» | Pause | +| «Alice, next / previous on \» | Next / previous track | +| «Alice, change input on \ на \» | Select input source (if the player exposes a source list) | ### Yandex Smart Home capabilities | Yandex capability | Mapped MA action | Notes | |---|---|---| -| `on_off` | `play()` / `stop()` | "включи" resumes the current queue, "выключи" stops | +| `on_off` | `play()` / `stop()` | "power on" resumes the current queue, "power off" stops | | `range(volume)` | `volume_set()` | Absolute and relative (±) | | `toggle(mute)` | `volume_mute()` | Only if the player supports mute | | `toggle(pause)` | `play()` / `pause()` | | @@ -84,8 +83,7 @@ The plugin supports three connection modes — pick the one that matches your ne ## Known Issues / Notes -- `play_media` is not supported by the Yandex Smart Home API, so Alice cannot start a specific song/album/playlist on an MA player — "включи музыку" only resumes the current queue. -- The `mode` capability supports up to 10 values, so only the first 10 entries of a player's source list are exposed to Alice. +- `play_media` is not supported by the Yandex Smart Home API, so Alice cannot start a specific song/album/playlist on an MA player — "play music" only resumes the current queue. - Seek is not supported by the Yandex Smart Home API for third-party media devices. - Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. - Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. From 1148b5e69b821019f24a3e291a7f4009c98d5546 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Fri, 24 Apr 2026 19:07:31 +0300 Subject: [PATCH 4/9] docs(yandex-smarthome): document auto-create skill flow (v1.4.x) --- src/content/docs/plugins/yandex-smarthome.md | 52 +++++++++++++++----- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 8791809a9..ab0755dbd 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -5,10 +5,10 @@ description: Features and Notes for the Yandex Smart Home Plugin # Yandex Smart Home -Music Assistant can expose its players to [Yandex Smart Home](https://alice.yandex.ru/smart-home) , so they can be controlled by Alice voice assistant as smart home multimedia devices. +Music Assistant can expose its players to [Yandex Smart Home](https://alice.yandex.ru/smart-home), so they can be controlled by Alice voice assistant as smart home multimedia devices. Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). -Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. +Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. The implementation follows the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) reference integration. > [!CAUTION] @@ -29,6 +29,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex | Exposes MA players to Yandex SmartHome | Yes | | Device type | Multimedia | | Connection modes | Cloud, Cloud Plus, Direct | +| Automatic skill creation | Yes (Cloud Plus / Direct) | ### Supported voice commands @@ -57,29 +58,53 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex The plugin supports three connection modes — pick the one that matches your network setup: -- **Cloud** — uses the public [yaha-cloud.ru](https://yaha-cloud.ru/) skill as a relay. Easiest setup, no public URL required. -- **Cloud Plus** — uses a private skill via the same relay. Required if Yaha Cloud is already linked to another integration (e.g. Home Assistant) on the same Yandex account. +- **Cloud** — uses the public [yaha-cloud.ru](https://yaha-cloud.ru/) skill as a relay. Easiest setup, no public URL required. Only one instance per Yandex account — if Yaha Cloud is already linked (e.g. from Home Assistant), use **Cloud Plus** instead. +- **Cloud Plus** — uses a private skill via the same relay. Required for multi-integration setups on the same account. - **Direct** — Yandex calls your MA server directly over HTTPS. No relay required, but your Music Assistant webserver must be reachable on a public HTTPS URL. -### Cloud / Cloud Plus setup +### Automatic skill creation (Cloud Plus / Direct) -1. Add the **Yandex Smart Home** plugin in Music Assistant settings and select `cloud` or `cloud_plus` as the connection type. -2. Click **Register with cloud** — the plugin creates an instance on the `yaha-cloud.ru` relay and returns an OTP code. -3. In the Yandex app on your phone: **Devices → Add device → Smart Home**, find the skill and enter the OTP. -4. (Cloud Plus only) Create a private skill in [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home). The plugin's config flow shows every required value to paste into the skill settings. +For `cloud_plus` and `direct` modes the plugin creates the private Yandex Dialogs skill for you — no copy-paste into the Yandex.Dialogs console is required. The flow: + +1. The config form asks you to sign in at `ya.ru/device` via OAuth Device Flow (a short popup with a verification code). +2. The plugin then drives `dialogs.yandex.ru/developer/app-store-api` end-to-end: create the skill, upload the logo, update the draft, create and attach an OAuth app, and request deploy. +3. The skill UUID is written back into **Skill ID** automatically. You still need to paste the **Skill OAuth Token** yourself (that flow is separate). + +Partial failures are resumable: the plugin persists step-level artifacts and a retry continues from the last completed step rather than starting over. + +> [!NOTE] +> Automatic skill creation uses an undocumented Yandex.Dialogs API. If Yandex changes it and auto-create fails, the config form automatically unfolds copy-paste fields (Backend URL, Client ID, Client Secret, Auth/Token URLs, link to the Yandex.Dialogs console) so you can finish the setup by hand without leaving Music Assistant settings. All of these values also stay available under **Advanced** after a successful setup. + +### Cloud setup + +1. Add the **Yandex Smart Home** plugin in Music Assistant settings and select `cloud` as the connection type. +2. Click **Register with cloud** — the plugin creates an instance on the `yaha-cloud.ru` relay. +3. Click **Get OTP code** to receive a one-time linking code. +4. In the Yandex app on your phone: **Devices → Add device → Smart Home**, find **Yaha Cloud** and enter the OTP. + +### Cloud Plus setup + +The config form is split into three numbered steps: + +1. **Register with cloud** — creates an instance on the `yaha-cloud.ru` relay. +2. **Create skill** — launches the automatic skill-creation flow described above (Device Flow login + skill creation). On success the Skill ID is filled in automatically; paste your Skill OAuth Token from [Yandex OAuth](https://oauth.yandex.ru/). +3. **Get OTP code + link in Yandex app** — click **Get OTP code**, then in the Yandex app: **Devices → Add device → Smart Home**, find your private skill and enter the OTP. + +Each step only appears once the previous one is complete. Later steps are hidden until they're actually relevant. ### Direct setup -1. Create a private skill in [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home). -2. Copy the Backend URL and Account Linking URLs shown by the plugin config flow into the skill settings, then publish the skill. -3. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. +1. Add the **Yandex Smart Home** plugin and select `direct`. Ensure your MA **Base URL** (Settings → Core → Webserver → Base URL) is a publicly reachable HTTPS URL. +2. Click **Create skill** — the plugin runs the automatic skill-creation flow (Device Flow login + skill creation) against Yandex.Dialogs using your MA server as the backend. +3. Paste your Skill OAuth Token from [Yandex OAuth](https://oauth.yandex.ru/) and save. +4. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. ### Settings - **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. - **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). - **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. -- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes, obtained from the [Yandex.Dialogs](https://dialogs.yandex.ru/developer/smart-home) developer console. +- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained from [Yandex OAuth](https://oauth.yandex.ru/) and pasted manually. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. ## Known Issues / Notes @@ -87,3 +112,4 @@ The plugin supports three connection modes — pick the one that matches your ne - Seek is not supported by the Yandex Smart Home API for third-party media devices. - Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. - Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. +- Automatic skill creation uses an undocumented Yandex.Dialogs API; manual fallback fields appear automatically if it breaks. From 35af595484213fc3ae6e9a20f0bd3ff2f0513668 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy Date: Tue, 28 Apr 2026 09:14:22 +0300 Subject: [PATCH 5/9] docs(yandex-smarthome): address review feedback - Drop maintainer attribution line - Replace Features table with bulleted list (align with other plugin docs) - Remove low-value Features rows (Device type, Connection modes duplicate) - Translate remaining Russian phrasing to English in WARNING and voice command examples - Add cross-refs from connection-mode bullets to setup sections - Add intro sentence to each setup section - Clarify Skill OAuth Token: open the OAuth URL the form shows next to the field, not generic oauth.yandex.ru --- src/content/docs/plugins/yandex-smarthome.md | 34 +++++++++----------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index ab0755dbd..2e58a7799 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -7,7 +7,6 @@ description: Features and Notes for the Yandex Smart Home Plugin Music Assistant can expose its players to [Yandex Smart Home](https://alice.yandex.ru/smart-home), so they can be controlled by Alice voice assistant as smart home multimedia devices. -Contributed and maintained by [TrudenBoy](https://github.com/TrudenBoy). Cloud connection modes use the [yaha-cloud.ru](https://yaha-cloud.ru/) relay. The implementation follows the [dext0r/yandex_smart_home](https://github.com/dext0r/yandex_smart_home) reference integration. @@ -16,7 +15,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex > [!WARNING] > The Yandex Smart Home API does not support `play_media` for third-party devices. -> Voice commands like «Алиса, включи музыку» will only resume the current Music Assistant queue — a specific track, album or playlist cannot be started by voice through this plugin. +> Voice commands like «Alice, play music» will only resume the current Music Assistant queue — a specific track, album or playlist cannot be started by voice through this plugin. > [!NOTE] > Full plugin documentation (RU/EN): **[trudenboy.github.io/ma-provider-yandex-smarthome](https://trudenboy.github.io/ma-provider-yandex-smarthome/)** @@ -24,12 +23,8 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex ## Features -| Function | Note | -|:-----------------------|:---------------------:| -| Exposes MA players to Yandex SmartHome | Yes | -| Device type | Multimedia | -| Connection modes | Cloud, Cloud Plus, Direct | -| Automatic skill creation | Yes (Cloud Plus / Direct) | +- Any MA player can be exposed to Yandex Alice for voice control as a smart home media device +- Automatic creation of the private Yandex Dialogs skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console ### Supported voice commands @@ -41,7 +36,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex | «Alice, set volume to 50 on \» | Set volume to 50% | | «Alice, pause on \» | Pause | | «Alice, next / previous on \» | Next / previous track | -| «Alice, change input on \ на \» | Select input source (if the player exposes a source list) | +| «Alice, change input on \ to \» | Select input source (if the player exposes a source list) | ### Yandex Smart Home capabilities @@ -58,9 +53,9 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex The plugin supports three connection modes — pick the one that matches your network setup: -- **Cloud** — uses the public [yaha-cloud.ru](https://yaha-cloud.ru/) skill as a relay. Easiest setup, no public URL required. Only one instance per Yandex account — if Yaha Cloud is already linked (e.g. from Home Assistant), use **Cloud Plus** instead. -- **Cloud Plus** — uses a private skill via the same relay. Required for multi-integration setups on the same account. -- **Direct** — Yandex calls your MA server directly over HTTPS. No relay required, but your Music Assistant webserver must be reachable on a public HTTPS URL. +- **Cloud** — uses the public [yaha-cloud.ru](https://yaha-cloud.ru/) skill as a relay. Easiest setup, no public URL required. Only one instance per Yandex account — if Yaha Cloud is already linked (e.g. from Home Assistant), use **Cloud Plus** instead. Follow [Cloud setup](#cloud-setup) below. +- **Cloud Plus** — uses a private skill via the same relay. Required for multi-integration setups on the same account. Follow [Automatic skill creation](#automatic-skill-creation-cloud-plus--direct) and then [Cloud Plus setup](#cloud-plus-setup) below. +- **Direct** — Yandex calls your MA server directly over HTTPS. No relay required, but your Music Assistant webserver must be reachable on a public HTTPS URL. Follow [Automatic skill creation](#automatic-skill-creation-cloud-plus--direct) and then [Direct setup](#direct-setup) below. ### Automatic skill creation (Cloud Plus / Direct) @@ -77,6 +72,8 @@ Partial failures are resumable: the plugin persists step-level artifacts and a r ### Cloud setup +The simplest mode — no skill creation, no public URL. You register your MA instance against the shared Yaha Cloud skill and link it in the Yandex app with a one-time code: + 1. Add the **Yandex Smart Home** plugin in Music Assistant settings and select `cloud` as the connection type. 2. Click **Register with cloud** — the plugin creates an instance on the `yaha-cloud.ru` relay. 3. Click **Get OTP code** to receive a one-time linking code. @@ -84,27 +81,28 @@ Partial failures are resumable: the plugin persists step-level artifacts and a r ### Cloud Plus setup -The config form is split into three numbered steps: +Use this when Yaha Cloud is already linked on your Yandex account (e.g. from Home Assistant) or when you want a private skill on the relay. The config form is split into three numbered steps and walks you through creating a private skill, registering on the relay and linking it in the Yandex app: 1. **Register with cloud** — creates an instance on the `yaha-cloud.ru` relay. -2. **Create skill** — launches the automatic skill-creation flow described above (Device Flow login + skill creation). On success the Skill ID is filled in automatically; paste your Skill OAuth Token from [Yandex OAuth](https://oauth.yandex.ru/). +2. **Create skill** — launches the automatic skill-creation flow described above (Device Flow login + skill creation). On success the Skill ID is filled in automatically and the form unfolds an **OAuth URL** field. Open exactly that URL in your browser, approve access, then copy the `access_token` value from the resulting URL into **Skill OAuth Token**. 3. **Get OTP code + link in Yandex app** — click **Get OTP code**, then in the Yandex app: **Devices → Add device → Smart Home**, find your private skill and enter the OTP. Each step only appears once the previous one is complete. Later steps are hidden until they're actually relevant. ### Direct setup +No relay involved — Yandex calls your MA server directly, so you need a publicly reachable HTTPS URL. Your MA acts as the skill backend; the plugin still creates the private skill for you and you only need to link the account in the Yandex app at the end: + 1. Add the **Yandex Smart Home** plugin and select `direct`. Ensure your MA **Base URL** (Settings → Core → Webserver → Base URL) is a publicly reachable HTTPS URL. -2. Click **Create skill** — the plugin runs the automatic skill-creation flow (Device Flow login + skill creation) against Yandex.Dialogs using your MA server as the backend. -3. Paste your Skill OAuth Token from [Yandex OAuth](https://oauth.yandex.ru/) and save. -4. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. +2. Click **Create skill** — the plugin runs the automatic skill-creation flow (Device Flow login + skill creation) against Yandex.Dialogs using your MA server as the backend. On success the form unfolds an **OAuth URL** field — open exactly that URL in your browser, approve access, then copy the `access_token` value from the resulting URL into **Skill OAuth Token** and save. +3. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. ### Settings - **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. - **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). - **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. -- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained from [Yandex OAuth](https://oauth.yandex.ru/) and pasted manually. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. +- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained by opening the **OAuth URL** link the form shows next to the field (a pre-filled `oauth.yandex.ru/authorize?...` link tied to the Yandex.Dialogs skill-management OAuth app), approving access, and pasting the resulting `access_token` here. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. ## Known Issues / Notes From 48a7d0b5b243b82b4032522aeb95c65329a0e4b5 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Mon, 4 May 2026 13:40:32 +0300 Subject: [PATCH 6/9] docs(yandex-smarthome): document playlists-as-input_source workaround (v1.5.0+) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflect the v1.5.0 feature that lets users pre-pick MA library playlists and surface them as Yandex `mode(input_source)` slots — the only voice path for starting specific content given the API's lack of `play_media` for third-party devices. - Soften the top-of-page WARNING: still no arbitrary song/album by voice, but playlists *do* work via the new mechanism. - Add a Features bullet, a voice-command row, and update the capability table for `mode(input_source)`. - Add an "Exposed Playlists" Settings entry and a new "Playlists as voice-triggered input sources" subsection that walks through the end-to-end flow (pick in MA, alias in Yandex app, say it to Alice). - Amend the Known Issues bullet about `play_media` to point at the workaround rather than just calling out the limitation. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/content/docs/plugins/yandex-smarthome.md | 23 +++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 2e58a7799..865ab935b 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -14,8 +14,8 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex > This is an unofficial implementation and is not affiliated with or endorsed by Yandex. > [!WARNING] -> The Yandex Smart Home API does not support `play_media` for third-party devices. -> Voice commands like «Alice, play music» will only resume the current Music Assistant queue — a specific track, album or playlist cannot be started by voice through this plugin. +> The Yandex Smart Home API does not support `play_media` for third-party devices, so Alice cannot start an arbitrary song or album by voice through this plugin. +> «Alice, play music» on its own only resumes the current Music Assistant queue. As a workaround, you can pre-pick up to 10 playlists in the plugin settings — they appear as `mode(input_source)` slots that you can label in the Yandex app and trigger by name (e.g. «Alice, switch \ to Rock»). See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). > [!NOTE] > Full plugin documentation (RU/EN): **[trudenboy.github.io/ma-provider-yandex-smarthome](https://trudenboy.github.io/ma-provider-yandex-smarthome/)** @@ -25,6 +25,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex - Any MA player can be exposed to Yandex Alice for voice control as a smart home media device - Automatic creation of the private Yandex Dialogs skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console +- Pre-picked MA library playlists exposed as named `mode(input_source)` slots, so Alice can start a specific playlist by voice (workaround for the lack of `play_media` in the Yandex Smart Home API) ### Supported voice commands @@ -36,7 +37,8 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex | «Alice, set volume to 50 on \» | Set volume to 50% | | «Alice, pause on \» | Pause | | «Alice, next / previous on \» | Next / previous track | -| «Alice, change input on \ to \» | Select input source (if the player exposes a source list) | +| «Alice, change input on \ to \» | Select input source (player source list and/or pre-picked playlist) | +| «Alice, switch \ to Rock» (or any custom alias) | Start the playlist you mapped to that mode in the Yandex app — see [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) | ### Yandex Smart Home capabilities @@ -47,7 +49,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex | `toggle(mute)` | `volume_mute()` | Only if the player supports mute | | `toggle(pause)` | `play()` / `pause()` | | | `range(channel)` | `next_track()` / `previous_track()` | Relative only: +1 = next, -1 = prev | -| `mode(input_source)` | `select_source()` | Uses the player's source list by index (up to 10) | +| `mode(input_source)` | `select_source()` or `play_media()` (playlist) | Native player sources first, then pre-picked playlists fill the remaining slots up to 10 | ## Configuration @@ -102,11 +104,22 @@ No relay involved — Yandex calls your MA server directly, so you need a public - **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. - **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). - **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. +- **Exposed Playlists** — multi-select of playlists from your MA library (any music provider), capped at 10. Each picked playlist becomes a `mode(input_source)` slot on every exposed player. If your MA library is empty when the form opens, save and reopen once your music providers have finished syncing. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) for the full flow. - **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained by opening the **OAuth URL** link the form shows next to the field (a pre-filled `oauth.yandex.ru/authorize?...` link tied to the Yandex.Dialogs skill-management OAuth app), approving access, and pasting the resulting `access_token` here. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. +### Playlists as voice-triggered input sources + +Because the Yandex Smart Home API has no `play_media` for third-party devices, the plugin uses the `mode(input_source)` capability as a workaround for voice-triggered playlist playback: + +1. In the plugin settings, pick up to 10 playlists in **Exposed Playlists**. Native player sources keep priority — playlists fill the remaining slots up to 10. +2. After saving, open the device in the Yandex app and assign voice aliases to the mode values (`one`, `two`, …, `ten`) — e.g. label `one` "Rock", `two` "Jazz". The mode values themselves are fixed by the API; the human-readable names are an Yandex-app feature. +3. Say «Alice, switch \ to Rock» (or whatever alias you set). The plugin powers the player on if needed and starts the corresponding playlist via `mass.player_queues.play_media`. + +This is the only voice path for selecting specific content. Arbitrary song or album requests by voice are still not possible — the Yandex API doesn't expose them to third parties. + ## Known Issues / Notes -- `play_media` is not supported by the Yandex Smart Home API, so Alice cannot start a specific song/album/playlist on an MA player — "play music" only resumes the current queue. +- `play_media` is not supported by the Yandex Smart Home API for arbitrary songs or albums. The plugin works around this for **playlists** via `mode(input_source)` (see [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources)), but ad-hoc track or album requests by voice are not possible. - Seek is not supported by the Yandex Smart Home API for third-party media devices. - Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. - Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. From 9453941084b27e56fb992ca9af32d2aed4d0e200 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Mon, 4 May 2026 15:13:57 +0300 Subject: [PATCH 7/9] =?UTF-8?q?docs(yandex-smarthome):=20correct=20input?= =?UTF-8?q?=5Fsource=20workaround=20=E2=80=94=20ordinal=20only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Earlier revision of this page claimed users could "assign voice aliases (e.g. Rock, Jazz) to mode values one..ten in the Yandex app". That is incorrect: the Yandex Smart Home API for mode(input_source) accepts only the fixed catalogue values one..ten, ModeValue has no display_name/synonym field, and the Home with Alice app has no UI to rename mode values. Rewrites the WARNING block, the Features bullet, the voice-command table row, the Settings entry, the dedicated subsection, and the Known Issues bullet to make the constraint explicit: - Trigger is ordinal-only — say «Alice, switch source to five» rather than «switch to Rock». - The order you pick playlists in is the order Alice addresses them by ordinal — reshuffling the multi-select shifts every ordinal. - Adds a Why-ordinals-only NOTE callout pointing at the Yandex-side constraint so future readers don't try the alias approach again. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/content/docs/plugins/yandex-smarthome.md | 26 +++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 865ab935b..73763c2bc 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -15,7 +15,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex > [!WARNING] > The Yandex Smart Home API does not support `play_media` for third-party devices, so Alice cannot start an arbitrary song or album by voice through this plugin. -> «Alice, play music» on its own only resumes the current Music Assistant queue. As a workaround, you can pre-pick up to 10 playlists in the plugin settings — they appear as `mode(input_source)` slots that you can label in the Yandex app and trigger by name (e.g. «Alice, switch \ to Rock»). See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). +> «Alice, play music» on its own only resumes the current Music Assistant queue. As a workaround, you can pre-pick up to 10 playlists in the plugin settings — they map to fixed `mode(input_source)` slots `one`..`ten`, and Alice triggers them by ordinal: «Alice, switch \ source to **five**». See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). > [!NOTE] > Full plugin documentation (RU/EN): **[trudenboy.github.io/ma-provider-yandex-smarthome](https://trudenboy.github.io/ma-provider-yandex-smarthome/)** @@ -25,7 +25,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex - Any MA player can be exposed to Yandex Alice for voice control as a smart home media device - Automatic creation of the private Yandex Dialogs skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console -- Pre-picked MA library playlists exposed as named `mode(input_source)` slots, so Alice can start a specific playlist by voice (workaround for the lack of `play_media` in the Yandex Smart Home API) +- Pre-picked MA library playlists exposed as `mode(input_source)` slots `one`..`ten`, so Alice can start a specific playlist by ordinal voice command (workaround for the lack of `play_media` in the Yandex Smart Home API) ### Supported voice commands @@ -37,8 +37,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex | «Alice, set volume to 50 on \» | Set volume to 50% | | «Alice, pause on \» | Pause | | «Alice, next / previous on \» | Next / previous track | -| «Alice, change input on \ to \» | Select input source (player source list and/or pre-picked playlist) | -| «Alice, switch \ to Rock» (or any custom alias) | Start the playlist you mapped to that mode in the Yandex app — see [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) | +| «Alice, switch \ source to \» | Select input source by ordinal — covers both the player's native source list and pre-picked playlists (see [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources)) | ### Yandex Smart Home capabilities @@ -104,22 +103,27 @@ No relay involved — Yandex calls your MA server directly, so you need a public - **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. - **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). - **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. -- **Exposed Playlists** — multi-select of playlists from your MA library (any music provider), capped at 10. Each picked playlist becomes a `mode(input_source)` slot on every exposed player. If your MA library is empty when the form opens, save and reopen once your music providers have finished syncing. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) for the full flow. +- **Exposed Playlists** — multi-select of playlists from your MA library (any music provider), capped at 10. Each picked playlist becomes a `mode(input_source)` slot `one`..`ten` on every exposed player, in the order you select them. If your MA library is empty when the form opens, save and reopen once your music providers have finished syncing. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) for the full flow. - **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained by opening the **OAuth URL** link the form shows next to the field (a pre-filled `oauth.yandex.ru/authorize?...` link tied to the Yandex.Dialogs skill-management OAuth app), approving access, and pasting the resulting `access_token` here. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. ### Playlists as voice-triggered input sources -Because the Yandex Smart Home API has no `play_media` for third-party devices, the plugin uses the `mode(input_source)` capability as a workaround for voice-triggered playlist playback: +Because the Yandex Smart Home API has no `play_media` for third-party devices, the plugin uses the `mode(input_source)` capability as a workaround for voice-triggered playlist playback. The mechanism is **ordinal-only**: Alice recognises the fixed mode values `one`, `two`, …, `ten` and there is no way to assign a custom voice phrase to a specific slot — neither in the API nor in the *Home with Alice* app. You need to remember which playlist you put in which slot. -1. In the plugin settings, pick up to 10 playlists in **Exposed Playlists**. Native player sources keep priority — playlists fill the remaining slots up to 10. -2. After saving, open the device in the Yandex app and assign voice aliases to the mode values (`one`, `two`, …, `ten`) — e.g. label `one` "Rock", `two` "Jazz". The mode values themselves are fixed by the API; the human-readable names are an Yandex-app feature. -3. Say «Alice, switch \ to Rock» (or whatever alias you set). The plugin powers the player on if needed and starts the corresponding playlist via `mass.player_queues.play_media`. +1. In the plugin settings, pick up to 10 playlists in **Exposed Playlists**. Native player sources keep priority and fill the first slots; playlists fill the remainder up to 10. The order you pick them in **is** the order Alice will address them by ordinal. +2. Say «Alice, switch \ source to **five**» (or whichever ordinal corresponds to the playlist's slot). The plugin powers the player on if needed and starts the corresponding playlist via `mass.player_queues.play_media`. -This is the only voice path for selecting specific content. Arbitrary song or album requests by voice are still not possible — the Yandex API doesn't expose them to third parties. +> [!TIP] +> Keep your **Exposed Playlists** list short and stable, and use a memorable order (most-used playlist as `one`, second-most as `two`, …). If you reshuffle the multi-select, the ordinals shift with it. + +> [!NOTE] +> Why ordinals only: the Yandex Smart Home API for `mode(input_source)` only accepts a fixed catalogue of values (`one`..`ten`) — `ModeValue` has no `display_name`/`alias`/`synonym` field, and the *Home with Alice* app does not let users rename mode values. This is a Yandex-side constraint, not a plugin limitation. + +Arbitrary song or album requests by voice are still not possible — the Yandex API doesn't expose `play_media` to third parties. ## Known Issues / Notes -- `play_media` is not supported by the Yandex Smart Home API for arbitrary songs or albums. The plugin works around this for **playlists** via `mode(input_source)` (see [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources)), but ad-hoc track or album requests by voice are not possible. +- `play_media` is not supported by the Yandex Smart Home API for arbitrary songs or albums. The plugin works around this for **playlists** via `mode(input_source)`, but the trigger is ordinal only (`one`..`ten`) — the Yandex app has no UI to alias mode values, and `ModeValue` in the API has no `display_name`/`synonym` field. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). - Seek is not supported by the Yandex Smart Home API for third-party media devices. - Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. - Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. From 67ff94bc6ca39d41281499659a02ad9b7f2be65e Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Tue, 5 May 2026 15:04:37 +0300 Subject: [PATCH 8/9] docs(yandex-smarthome): document Dialogs voice skill (free-form playback) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Experimental: Dialogs voice skill" section after the playlists input-sources block, mirroring the in-repo VOICE_COMMANDS.md. Covers: - What the feature does and how it differs from Smart Home (separate «Навык» skill, webhook-based, direct-mode only) - Setup walkthrough (toggle, name requirements, auto-create flow, async deploy delay note) - Voice phrase examples table mapping common commands to actions - Verb forms accepted (imperative + infinitive variants Yandex's voice-to-text returns) - Player name matching: against MA player.name, not Smart Home aliases, with generic words ("колонка"/"плеер"/"проигрыватель") as fallback - Search prioritisation: artist > album > track > playlist with radio_mode=True for unqualified queries - Security: webhook secret + skill_id check, NPM allowlist guidance - Debugging via DEBUG log level Also updates the Features bullet list to mention the experimental free-form playback capability. Co-Authored-By: Claude Sonnet 4.6 --- src/content/docs/plugins/yandex-smarthome.md | 47 +++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 73763c2bc..2000a5f59 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -26,6 +26,7 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex - Any MA player can be exposed to Yandex Alice for voice control as a smart home media device - Automatic creation of the private Yandex Dialogs skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console - Pre-picked MA library playlists exposed as `mode(input_source)` slots `one`..`ten`, so Alice can start a specific playlist by ordinal voice command (workaround for the lack of `play_media` in the Yandex Smart Home API) +- **Experimental** free-form voice playback via a separate Yandex Dialogs *custom skill* — say *«Алиса, попроси \ включи Metallica на кухне»* and the plugin parses the phrase, searches MA, and starts playback (direct mode only — see [Experimental: Dialogs voice skill](#experimental-dialogs-voice-skill-free-form-playback)) ### Supported voice commands @@ -119,7 +120,51 @@ Because the Yandex Smart Home API has no `play_media` for third-party devices, t > [!NOTE] > Why ordinals only: the Yandex Smart Home API for `mode(input_source)` only accepts a fixed catalogue of values (`one`..`ten`) — `ModeValue` has no `display_name`/`alias`/`synonym` field, and the *Home with Alice* app does not let users rename mode values. This is a Yandex-side constraint, not a plugin limitation. -Arbitrary song or album requests by voice are still not possible — the Yandex API doesn't expose `play_media` to third parties. +Arbitrary song or album requests by voice are still possible via the experimental **Dialogs voice skill** below — it bypasses the Smart Home `play_media` limit by registering a *separate* Yandex Dialogs skill that receives the user's raw voice phrase as a webhook call. + +### Experimental: Dialogs voice skill (free-form playback) + +A second, optional skill type — Yandex Dialogs *custom skill* («Навык») — adds free-form voice playback. Activation phrase: **«Алиса, попроси \ …»**. The skill registers a webhook endpoint on MA's webserver; Yandex POSTs the user's transcribed phrase there, the plugin parses it server-side, searches MA, and starts playback. + +> [!IMPORTANT] +> This feature is **direct-mode only** and **experimental**. The toggle and form fields appear only when `Connection Type = direct` and only after you've opted in via **Enable Dialogs voice skill (experimental)**. Cloud / Cloud Plus modes hide the section entirely. + +Setup: + +1. Pick **Connection Type = direct** and complete the Smart Home skill auto-create first (if you haven't already). +2. Toggle **Enable Dialogs voice skill (experimental)** on. +3. Choose a **Skill activation name** — at least two words, globally unique across all Yandex skills (Yandex enforces both). Russian names work best for voice recognition: `Музыкальный Ассистент`, `Домашняя Музыка`, `Мой Плеер` etc. Activation phrase becomes `«Алиса, попроси …»`. +4. Press **Create Dialogs voice skill**. The plugin runs the same Device Flow login as Smart Home auto-create — first time you'll go through `ya.ru/device`, subsequent runs reuse the cached token. Pipeline: create app → upload logo → save draft (name, examples, category) → create OAuth app → request publish. +5. After the action returns, the form shows a **Skill in Yandex Dialogs dev console** link. Yandex's actual deploy is asynchronous — for private skills it usually completes in a few seconds, but under load can take up to ~10 minutes. The skill is unusable on Alice until the dev console shows «На воздухе» / `onAir: true`. + +Once published, voice phrases work as follows: + +| You say (after «Алиса, попроси \ …») | What happens | +|----------------------------------------------------------|-------------------------------------------------------------| +| `включи Metallica` | search → first artist → start artist radio | +| `включи Metallica на кухне` | same, but on the player named "Кухня" | +| `включи песню Yesterday` | track search → first match → play that track | +| `включи альбом Black Album` | album search → first match → play that album | +| `включи группу Beatles` | artist radio explicitly | +| `включи плейлист утренний джаз` | playlist search → first match → play that playlist | +| `включи мою волну` | yandex_music personal radio (`user:onyourwave`) | +| `включи жанр джаз` / `включи радио рок` | genre rotor → fall back to artist radio | +| `включи Metallica на проигрывателе` / `на колонке` / … | generic word for "speaker" → falls back to default player | + +Verbs the parser understands (Yandex's voice-to-text returns various forms, all are accepted): `включи / включите / включай / включайте / включить`, `поставь / поставьте / поставить`, `запусти / запустите / запустить`, `сыграй / сыграйте / сыграть`, `играй / играйте`, `послушай / послушайте / послушать`. The optional trailing `на ` suffix is stripped before kind classification, so word order is fixed to ` [на ]`. + +Player names are matched against MA's `player.name` (case-insensitive, with Russian inflections normalised — *"Кухня"* matches *"на кухне"*). Aliases set in the *Home with Alice* app **do not** propagate into the dialog skill payload — Yandex only forwards the raw phrase. To use a custom voice name, rename the player in MA itself. Generic words like *колонка*, *плеер*, *проигрыватель*, *динамик* fall through to the previously-used player in the same conversation, or to the only exposed player. + +Search prioritisation when no marker is given (`включи X`): **artist > album > track > playlist** with `radio_mode=True` — picking the artist matches the typical "play X music" intent and starts continuous playback. If you specifically want a playlist, say `плейлист X`; for an album, `альбом X`; for a single track, `песню X`. + +If the parser cannot resolve to a player or a media item, Alice replies in Russian with a hint (`«Не нашёл такую музыку…»` / `«Не нашёл колонку …»`). For diagnostics, set log level for `music_assistant.providers.yandex_smarthome.dialogs_nlu` to `DEBUG` — every voice request will log the parsed kind, query, hint, candidate players, and the picked match tier. + +Security: + +- The webhook URL embeds a **random 32-character secret** (`/api/yandex_dialogs/webhook/`); knowing the secret requires access to the skill's Backend URL in the Yandex Dialogs dev console. Comparison is constant-time. +- The handler also checks `body.session.skill_id` against the configured skill ID before processing — a payload from a different skill returns `401`. +- The plugin uses MA's standard logging redaction; the secret is only logged as the last 4 characters of the path on startup. +- If you publish MA via a reverse proxy, expose only the prefixes `/api/yandex_smarthome/` (Smart Home) and `/api/yandex_dialogs/webhook/` (Dialogs). Block `/` to keep the rest of the MA API/UI off the public internet. ## Known Issues / Notes From 8580d34e1a2aa57bf89b53edd6f62b0f2783aa67 Mon Sep 17 00:00:00 2001 From: Mikhail Nevskiy <139659391+trudenboy@users.noreply.github.com> Date: Wed, 6 May 2026 20:37:53 +0300 Subject: [PATCH 9/9] =?UTF-8?q?docs(yandex-smarthome):=20align=20with=20sm?= =?UTF-8?q?arthome=20v2.1.0=20=E2=80=94=20voice=20extracted=20to=20alice?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Source repo restructured between this PR's last update and v2.1.0: - Yandex Dialogs custom skill (free-form voice playback) extracted into a dedicated provider, ma-provider-yandex-alice. - Auto_skill code extracted into a generic PyPI lib (ya-dialogs-api 2.0.0). - Smart-home auto-create flow re-wired against the new lib API and restored in v2.1.0 (was temporarily unavailable in v2.0.0). Doc changes (134 lines, was 175): - Drop the experimental dialogs-voice-skill bullet from Features. - Drop the entire "Experimental: Dialogs voice skill (free-form playback)" section (~50 lines: setup steps, voice phrases table, parser verbs, player matching, security notes) — that functionality lives in ma-provider-yandex-alice now. - Add a paragraph after Features pointing users to ma-provider-yandex-alice for free-form voice control, with a brief description of its command surface (now-playing, shuffle, repeat, seek, transfer, add-to-queue). - Update the WARNING block to mention ma-provider-yandex-alice as the workaround for the play_media limitation (alongside the existing ordinal-playlist workaround). - Update the cross-reference at the bottom of "Playlists as voice-triggered input sources" — the previous "see Experimental: Dialogs voice skill below" is replaced with a link to ma-provider-yandex-alice. - Update Known Issues — drop voice-skill references; add the alice pointer alongside the play_media note. - Add **External Base URL** to the Settings list (it existed in the source repo but wasn't documented here). - Mention the resumable-auto-create state machine (Create / Retry / Continue / Re-create button) in the auto-create flow description. - Rename "Create skill" / "Create Dialogs voice skill" button labels to "Auto-create Smart Home skill" to match the v2.1.0 UI. - Drop step #2 from Cloud Plus setup that mentioned an OAuth-token URL unfolding from the form — clarified that the token URL is shown in the form and the user opens it manually. --- src/content/docs/plugins/yandex-smarthome.md | 75 +++++--------------- 1 file changed, 17 insertions(+), 58 deletions(-) diff --git a/src/content/docs/plugins/yandex-smarthome.md b/src/content/docs/plugins/yandex-smarthome.md index 2000a5f59..7a9a8a93b 100644 --- a/src/content/docs/plugins/yandex-smarthome.md +++ b/src/content/docs/plugins/yandex-smarthome.md @@ -14,8 +14,8 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex > This is an unofficial implementation and is not affiliated with or endorsed by Yandex. > [!WARNING] -> The Yandex Smart Home API does not support `play_media` for third-party devices, so Alice cannot start an arbitrary song or album by voice through this plugin. -> «Alice, play music» on its own only resumes the current Music Assistant queue. As a workaround, you can pre-pick up to 10 playlists in the plugin settings — they map to fixed `mode(input_source)` slots `one`..`ten`, and Alice triggers them by ordinal: «Alice, switch \ source to **five**». See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). +> The Yandex Smart Home API does not support `play_media` for third-party devices, so Alice cannot start an arbitrary song or album by voice through this plugin alone. +> «Alice, play music» on its own only resumes the current Music Assistant queue. As a workaround, you can pre-pick up to 10 playlists in the plugin settings — they map to fixed `mode(input_source)` slots `one`..`ten`, and Alice triggers them by ordinal: «Alice, switch \ source to **five**». See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). For free-form voice control (search-and-play arbitrary songs, albums, playlists by phrase) install the dedicated [`ma-provider-yandex-alice`](https://github.com/trudenboy/ma-provider-yandex-alice) plugin alongside this one. > [!NOTE] > Full plugin documentation (RU/EN): **[trudenboy.github.io/ma-provider-yandex-smarthome](https://trudenboy.github.io/ma-provider-yandex-smarthome/)** @@ -24,9 +24,11 @@ The implementation follows the [dext0r/yandex_smart_home](https://github.com/dex ## Features - Any MA player can be exposed to Yandex Alice for voice control as a smart home media device -- Automatic creation of the private Yandex Dialogs skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console +- Automatic creation of the private Yandex Dialogs Smart Home skill for `cloud_plus` and `direct` modes — no manual setup in the Yandex.Dialogs console - Pre-picked MA library playlists exposed as `mode(input_source)` slots `one`..`ten`, so Alice can start a specific playlist by ordinal voice command (workaround for the lack of `play_media` in the Yandex Smart Home API) -- **Experimental** free-form voice playback via a separate Yandex Dialogs *custom skill* — say *«Алиса, попроси \ включи Metallica на кухне»* and the plugin parses the phrase, searches MA, and starts playback (direct mode only — see [Experimental: Dialogs voice skill](#experimental-dialogs-voice-skill-free-form-playback)) +- Resumable auto-create flow: transient failures (Device Flow timeout, Yandex moderation 5xx) checkpoint the partial state and the next click resumes from the last completed step + +For free-form voice playback («Алиса, попроси Music Assistant включи Metallica на кухне» — search-and-play arbitrary content by phrase), install the [Yandex Alice plugin](https://github.com/trudenboy/ma-provider-yandex-alice). It's a separate provider that registers a Yandex Dialogs *custom skill* with full Russian NLU and a wider command surface (now-playing, shuffle, repeat, seek, transfer between players, add-to-queue). ### Supported voice commands @@ -61,16 +63,16 @@ The plugin supports three connection modes — pick the one that matches your ne ### Automatic skill creation (Cloud Plus / Direct) -For `cloud_plus` and `direct` modes the plugin creates the private Yandex Dialogs skill for you — no copy-paste into the Yandex.Dialogs console is required. The flow: +For `cloud_plus` and `direct` modes the plugin creates the private Yandex Dialogs Smart Home skill for you — no copy-paste into the Yandex.Dialogs console is required. The flow: 1. The config form asks you to sign in at `ya.ru/device` via OAuth Device Flow (a short popup with a verification code). 2. The plugin then drives `dialogs.yandex.ru/developer/app-store-api` end-to-end: create the skill, upload the logo, update the draft, create and attach an OAuth app, and request deploy. 3. The skill UUID is written back into **Skill ID** automatically. You still need to paste the **Skill OAuth Token** yourself (that flow is separate). -Partial failures are resumable: the plugin persists step-level artifacts and a retry continues from the last completed step rather than starting over. +Partial failures are resumable — the action button label flips between *Create…* / *Retry* / *Continue* / *Re-create* based on the current pipeline state, and the plugin persists step-level artifacts so a retry continues from the last completed step rather than starting over. The cached Yandex Passport token is reused on subsequent runs, so you only confirm the Device Code once. > [!NOTE] -> Automatic skill creation uses an undocumented Yandex.Dialogs API. If Yandex changes it and auto-create fails, the config form automatically unfolds copy-paste fields (Backend URL, Client ID, Client Secret, Auth/Token URLs, link to the Yandex.Dialogs console) so you can finish the setup by hand without leaving Music Assistant settings. All of these values also stay available under **Advanced** after a successful setup. +> Automatic skill creation uses an undocumented Yandex.Dialogs API. If Yandex changes it and auto-create fails, the config form continues to expose manual fields (Skill ID, Skill OAuth Token, Backend URL) so you can finish the setup by hand without leaving Music Assistant settings. The dev-console URL is shown alongside, including a deep-link to the created skill. ### Cloud setup @@ -86,7 +88,7 @@ The simplest mode — no skill creation, no public URL. You register your MA ins Use this when Yaha Cloud is already linked on your Yandex account (e.g. from Home Assistant) or when you want a private skill on the relay. The config form is split into three numbered steps and walks you through creating a private skill, registering on the relay and linking it in the Yandex app: 1. **Register with cloud** — creates an instance on the `yaha-cloud.ru` relay. -2. **Create skill** — launches the automatic skill-creation flow described above (Device Flow login + skill creation). On success the Skill ID is filled in automatically and the form unfolds an **OAuth URL** field. Open exactly that URL in your browser, approve access, then copy the `access_token` value from the resulting URL into **Skill OAuth Token**. +2. **Auto-create Smart Home skill** — launches the automatic skill-creation flow described above (Device Flow login + skill creation). On success the **Skill ID** is filled in automatically. Open the OAuth-token URL shown in the form (a pre-filled `oauth.yandex.ru/authorize?...` link), approve access, then copy the resulting `access_token` value into **Skill OAuth Token**. 3. **Get OTP code + link in Yandex app** — click **Get OTP code**, then in the Yandex app: **Devices → Add device → Smart Home**, find your private skill and enter the OTP. Each step only appears once the previous one is complete. Later steps are hidden until they're actually relevant. @@ -95,17 +97,18 @@ Each step only appears once the previous one is complete. Later steps are hidden No relay involved — Yandex calls your MA server directly, so you need a publicly reachable HTTPS URL. Your MA acts as the skill backend; the plugin still creates the private skill for you and you only need to link the account in the Yandex app at the end: -1. Add the **Yandex Smart Home** plugin and select `direct`. Ensure your MA **Base URL** (Settings → Core → Webserver → Base URL) is a publicly reachable HTTPS URL. -2. Click **Create skill** — the plugin runs the automatic skill-creation flow (Device Flow login + skill creation) against Yandex.Dialogs using your MA server as the backend. On success the form unfolds an **OAuth URL** field — open exactly that URL in your browser, approve access, then copy the `access_token` value from the resulting URL into **Skill OAuth Token** and save. +1. Add the **Yandex Smart Home** plugin and select `direct`. Ensure your MA **Base URL** (Settings → Core → Webserver → Base URL) is a publicly reachable HTTPS URL — or set the plugin-local **External Base URL** override to expose only Yandex via a reverse proxy while keeping the global Base URL local. +2. Click **Auto-create Smart Home skill** — the plugin runs the automatic skill-creation flow (Device Flow login + skill creation) against Yandex.Dialogs using your MA server as the backend. On success the form shows the OAuth-token URL — open it, approve access, then copy the resulting `access_token` value into **Skill OAuth Token** and save. 3. Link the account in the Yandex app: **Devices → Add device → Smart Home** → select your published skill. ### Settings - **Instance Name** — how this MA instance appears in the Yandex Smart Home app. Alice uses this name to address devices. - **Connection Type** — `cloud`, `cloud_plus`, or `direct` (see above). +- **External Base URL** — `direct`-mode only. Optional public HTTPS URL override for Yandex callbacks. Lets you keep MA's global Base URL pointing at the local address (so Home Assistant Ingress / local UI keep working) while exposing a public HTTPS URL only to Yandex via a reverse proxy. - **Exposed Players** — select which MA players to expose to Alice. Leave empty to expose all players. - **Exposed Playlists** — multi-select of playlists from your MA library (any music provider), capped at 10. Each picked playlist becomes a `mode(input_source)` slot `one`..`ten` on every exposed player, in the order you select them. If your MA library is empty when the form opens, save and reopen once your music providers have finished syncing. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources) for the full flow. -- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained by opening the **OAuth URL** link the form shows next to the field (a pre-filled `oauth.yandex.ru/authorize?...` link tied to the Yandex.Dialogs skill-management OAuth app), approving access, and pasting the resulting `access_token` here. Once both are set, the plugin UI collapses them into a single **Open skill in Yandex.Dialogs** link to keep the default view clean; they remain editable under **Advanced**. +- **Skill ID** and **Skill OAuth Token** — required for `cloud_plus` and `direct` modes. **Skill ID** is filled in automatically after auto-create succeeds; **Skill OAuth Token** is obtained by opening the OAuth URL shown in the form (a pre-filled `oauth.yandex.ru/authorize?...` link tied to the Yandex.Dialogs skill-management OAuth app), approving access, and pasting the resulting `access_token` here. ### Playlists as voice-triggered input sources @@ -120,56 +123,12 @@ Because the Yandex Smart Home API has no `play_media` for third-party devices, t > [!NOTE] > Why ordinals only: the Yandex Smart Home API for `mode(input_source)` only accepts a fixed catalogue of values (`one`..`ten`) — `ModeValue` has no `display_name`/`alias`/`synonym` field, and the *Home with Alice* app does not let users rename mode values. This is a Yandex-side constraint, not a plugin limitation. -Arbitrary song or album requests by voice are still possible via the experimental **Dialogs voice skill** below — it bypasses the Smart Home `play_media` limit by registering a *separate* Yandex Dialogs skill that receives the user's raw voice phrase as a webhook call. - -### Experimental: Dialogs voice skill (free-form playback) - -A second, optional skill type — Yandex Dialogs *custom skill* («Навык») — adds free-form voice playback. Activation phrase: **«Алиса, попроси \ …»**. The skill registers a webhook endpoint on MA's webserver; Yandex POSTs the user's transcribed phrase there, the plugin parses it server-side, searches MA, and starts playback. - -> [!IMPORTANT] -> This feature is **direct-mode only** and **experimental**. The toggle and form fields appear only when `Connection Type = direct` and only after you've opted in via **Enable Dialogs voice skill (experimental)**. Cloud / Cloud Plus modes hide the section entirely. - -Setup: - -1. Pick **Connection Type = direct** and complete the Smart Home skill auto-create first (if you haven't already). -2. Toggle **Enable Dialogs voice skill (experimental)** on. -3. Choose a **Skill activation name** — at least two words, globally unique across all Yandex skills (Yandex enforces both). Russian names work best for voice recognition: `Музыкальный Ассистент`, `Домашняя Музыка`, `Мой Плеер` etc. Activation phrase becomes `«Алиса, попроси …»`. -4. Press **Create Dialogs voice skill**. The plugin runs the same Device Flow login as Smart Home auto-create — first time you'll go through `ya.ru/device`, subsequent runs reuse the cached token. Pipeline: create app → upload logo → save draft (name, examples, category) → create OAuth app → request publish. -5. After the action returns, the form shows a **Skill in Yandex Dialogs dev console** link. Yandex's actual deploy is asynchronous — for private skills it usually completes in a few seconds, but under load can take up to ~10 minutes. The skill is unusable on Alice until the dev console shows «На воздухе» / `onAir: true`. - -Once published, voice phrases work as follows: - -| You say (after «Алиса, попроси \ …») | What happens | -|----------------------------------------------------------|-------------------------------------------------------------| -| `включи Metallica` | search → first artist → start artist radio | -| `включи Metallica на кухне` | same, but on the player named "Кухня" | -| `включи песню Yesterday` | track search → first match → play that track | -| `включи альбом Black Album` | album search → first match → play that album | -| `включи группу Beatles` | artist radio explicitly | -| `включи плейлист утренний джаз` | playlist search → first match → play that playlist | -| `включи мою волну` | yandex_music personal radio (`user:onyourwave`) | -| `включи жанр джаз` / `включи радио рок` | genre rotor → fall back to artist radio | -| `включи Metallica на проигрывателе` / `на колонке` / … | generic word for "speaker" → falls back to default player | - -Verbs the parser understands (Yandex's voice-to-text returns various forms, all are accepted): `включи / включите / включай / включайте / включить`, `поставь / поставьте / поставить`, `запусти / запустите / запустить`, `сыграй / сыграйте / сыграть`, `играй / играйте`, `послушай / послушайте / послушать`. The optional trailing `на ` suffix is stripped before kind classification, so word order is fixed to ` [на ]`. - -Player names are matched against MA's `player.name` (case-insensitive, with Russian inflections normalised — *"Кухня"* matches *"на кухне"*). Aliases set in the *Home with Alice* app **do not** propagate into the dialog skill payload — Yandex only forwards the raw phrase. To use a custom voice name, rename the player in MA itself. Generic words like *колонка*, *плеер*, *проигрыватель*, *динамик* fall through to the previously-used player in the same conversation, or to the only exposed player. - -Search prioritisation when no marker is given (`включи X`): **artist > album > track > playlist** with `radio_mode=True` — picking the artist matches the typical "play X music" intent and starts continuous playback. If you specifically want a playlist, say `плейлист X`; for an album, `альбом X`; for a single track, `песню X`. - -If the parser cannot resolve to a player or a media item, Alice replies in Russian with a hint (`«Не нашёл такую музыку…»` / `«Не нашёл колонку …»`). For diagnostics, set log level for `music_assistant.providers.yandex_smarthome.dialogs_nlu` to `DEBUG` — every voice request will log the parsed kind, query, hint, candidate players, and the picked match tier. - -Security: - -- The webhook URL embeds a **random 32-character secret** (`/api/yandex_dialogs/webhook/`); knowing the secret requires access to the skill's Backend URL in the Yandex Dialogs dev console. Comparison is constant-time. -- The handler also checks `body.session.skill_id` against the configured skill ID before processing — a payload from a different skill returns `401`. -- The plugin uses MA's standard logging redaction; the secret is only logged as the last 4 characters of the path on startup. -- If you publish MA via a reverse proxy, expose only the prefixes `/api/yandex_smarthome/` (Smart Home) and `/api/yandex_dialogs/webhook/` (Dialogs). Block `/` to keep the rest of the MA API/UI off the public internet. +For arbitrary song / album / artist requests by voice (without the ordinal workaround), install the dedicated [Yandex Alice plugin](https://github.com/trudenboy/ma-provider-yandex-alice) — it bypasses the Smart Home `play_media` limit by registering a *separate* Yandex Dialogs *custom skill* that receives the user's raw voice phrase as a webhook and runs full Russian NLU server-side. ## Known Issues / Notes -- `play_media` is not supported by the Yandex Smart Home API for arbitrary songs or albums. The plugin works around this for **playlists** via `mode(input_source)`, but the trigger is ordinal only (`one`..`ten`) — the Yandex app has no UI to alias mode values, and `ModeValue` in the API has no `display_name`/`synonym` field. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). +- `play_media` is not supported by the Yandex Smart Home API for arbitrary songs or albums. The plugin works around this for **playlists** via `mode(input_source)`, but the trigger is ordinal only (`one`..`ten`) — the Yandex app has no UI to alias mode values, and `ModeValue` in the API has no `display_name`/`synonym` field. See [Playlists as voice-triggered input sources](#playlists-as-voice-triggered-input-sources). For free-form voice search-and-play, install the [Yandex Alice plugin](https://github.com/trudenboy/ma-provider-yandex-alice). - Seek is not supported by the Yandex Smart Home API for third-party media devices. - Track name, artist and artwork cannot be pushed to Yandex — the API does not expose those fields for third-party devices. - Direct mode requires a publicly reachable HTTPS endpoint for the MA webserver (via port forwarding, reverse proxy or similar); otherwise use one of the cloud modes. -- Automatic skill creation uses an undocumented Yandex.Dialogs API; manual fallback fields appear automatically if it breaks. +- Automatic skill creation uses an undocumented Yandex.Dialogs API; manual fallback fields stay available in the config form if it breaks.