docs(plugins): add Yandex Smart Home plugin page#623
Open
trudenboy wants to merge 7 commits intomusic-assistant:betafrom
Open
docs(plugins): add Yandex Smart Home plugin page#623trudenboy wants to merge 7 commits intomusic-assistant:betafrom
trudenboy wants to merge 7 commits intomusic-assistant:betafrom
Conversation
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 <noreply@anthropic.com>
✅ Deploy Preview for ohf-music-assistant ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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 <noreply@anthropic.com>
OzGav
reviewed
Apr 24, 2026
OzGav
reviewed
Apr 24, 2026
Updated Yandex Smart Home documentation to clarify voice commands and capabilities. Adjusted references to Yandex Alice and improved formatting.
OzGav
reviewed
Apr 27, 2026
OzGav
reviewed
Apr 27, 2026
- 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
MarvinSchenkel
pushed a commit
to music-assistant/server
that referenced
this pull request
Apr 28, 2026
…3785) ## Yandex Smart Home provider v1.4.5 **Source**: [trudenboy/ma-provider-yandex-smarthome](https://github.com/trudenboy/ma-provider-yandex-smarthome) · tag [v1.4.5](https://github.com/trudenboy/ma-provider-yandex-smarthome/releases/tag/v1.4.5) Bumps the bundled provider from **v1.3.0 → v1.4.5**. No upstream core changes — all code lives under `music_assistant/providers/yandex_smarthome/` and `tests/providers/yandex_smarthome/`. --- ### Headline: auto-create Yandex Dialogs skill For `cloud_plus` and `direct` modes the config flow now creates the private Yandex Dialogs skill automatically. The user logs in once via OAuth Device Flow (`ya.ru/device`) against Yandex Passport, and the provider then drives the undocumented `dialogs.yandex.ru/developer/app-store-api` endpoints to create the app, upload the logo, update the draft, create and attach an OAuth app, and request deploy — replacing ~10 minutes of manual copy-paste across several Yandex pages. The pipeline is resumable: partial failures persist step-level artifacts (`skill_id`, `logo_id`, `oauth_app_id`, `state`) so retry continues from the last completed step. ### UX - **Numbered steps** — `cloud_plus` shows Register → Create skill → Link (OTP); `direct` shows Create skill only. Later steps are hidden until the previous one is complete. - **Automatic manual fallback** — on failure the form unfolds copy-paste fields (Backend URL, Client ID/Secret, Auth/Token URLs, Dialogs console link) so the user can finish in `dialogs.yandex.ru` by hand without leaving MA settings. - **Advanced view** — all manual-setup reference values stay available for power users, even when auto-create succeeds. - **Configured-state collapse** — once Skill ID + OAuth token are saved, edit fields collapse into a single \"Open skill in Yandex.Dialogs\" link. - **Cloud-mode advisory** — warns that the public Yaha Cloud skill allows only one linked instance per Yandex account and suggests Cloud Plus for multi-install setups. - **Connection Type** moved out of Advanced — it's the first decision and should render in the default view. ### Removed - `experimental_auto_create_skill` master toggle — auto-create is on by default. --- ### Changes since the initial bundle (review feedback in this PR) - **Cloud Plus manual fallback hidden before registration** — `cloud_plus` Client ID template embeds the yaha-cloud instance UUID; before the user clicks Register it was rendering as `yandex_smart_home:` (empty UUID). The manual block is now suppressed entirely for cloud_plus while `cloud_instance_id` is empty, so Advanced view can't surface a half-formed Client ID. - **SECURE_STRING `CONF_DIRECT_CLIENT_SECRET` round-trip** — prefer the persisted secret from `saved_config` over the (empty on re-open) form value, falling back to a fresh UUID only for first-time setup. - **`asyncio.CancelledError` passthrough** — both broad `except Exception` clauses (orchestrator + config-action handler) now re-raise `CancelledError` so cooperative cancellation during HA shutdown / config-flow abort is preserved instead of being absorbed into a `FAILED` artifact. - **`_build_authenticator_cm` non-idempotent wrap fix** — detects an already-`@asynccontextmanager`-decorated authenticator and passes it through instead of re-wrapping (the outer wrapper would otherwise call `__anext__` on a CM object and crash at runtime). The async-iterator path no longer calls the factory twice. - **`SkillCreationState.DEPLOY_REQUESTED` is now an observable checkpoint** — previously defined and allow-listed in the resume branch but never written; the orchestrator now sets it before `request_deploy`, so mid-publish crashes resume from publish-only. - **Upstream lint/mypy conformance** — docstring-below-constant removed, StrEnum comparisons use `.value`, strict-mypy annotations on test helpers, `"Retry" in action.action_label` narrowed before the `in` check. - Several smaller docstring and log-leak fixes (Copilot review). ### Dependencies No new top-level dependencies. `ya-passport-auth` (already at 1.3.0 from the previous bump) provides the Device Flow / Passport cookie refresh used by the auto-create orchestrator; all Dialogs calls reuse that session. ### Tests 293 unit tests in the upstream provider repo, including syrupy-snapshot tests for the Dialogs API payload builders. Covered: orchestrator state machine (resume from each intermediate state including `DEPLOY_REQUESTED`, Device Flow timeout, CSRF miss, 409 duplicate, `CancelledError` propagation), UI visibility (step gating, advanced/collapse rules, HTTPS/base-URL preconditions for `direct`, SECURE_STRING fallback, cloud_plus manual-block suppression pre-registration), and the `_handle_config_actions` wiring. No live Yandex calls. ### Compatibility - No schema or storage migration — the artifact blob is a single JSON string stored under the existing provider config. - Existing `CONF_SKILL_ID` / `CONF_SKILL_TOKEN` stay editable; auto-create populates `CONF_SKILL_ID` only on full success. - Users on v1.3.0 see the new multi-step UX on next open; no action required from existing installs. --- ### Related - Documentation update: [music-assistant/music-assistant.io#623](music-assistant/music-assistant.io#623) — documents the auto-create skill flow and numbered-step UX introduced here. Full CHANGELOG: [trudenboy/ma-provider-yandex-smarthome/CHANGELOG.md](https://github.com/trudenboy/ma-provider-yandex-smarthome/blob/main/CHANGELOG.md) --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
fionn-r
pushed a commit
to fionn-r/music-assistant-server
that referenced
this pull request
May 4, 2026
…usic-assistant#3785) ## Yandex Smart Home provider v1.4.5 **Source**: [trudenboy/ma-provider-yandex-smarthome](https://github.com/trudenboy/ma-provider-yandex-smarthome) · tag [v1.4.5](https://github.com/trudenboy/ma-provider-yandex-smarthome/releases/tag/v1.4.5) Bumps the bundled provider from **v1.3.0 → v1.4.5**. No upstream core changes — all code lives under `music_assistant/providers/yandex_smarthome/` and `tests/providers/yandex_smarthome/`. --- ### Headline: auto-create Yandex Dialogs skill For `cloud_plus` and `direct` modes the config flow now creates the private Yandex Dialogs skill automatically. The user logs in once via OAuth Device Flow (`ya.ru/device`) against Yandex Passport, and the provider then drives the undocumented `dialogs.yandex.ru/developer/app-store-api` endpoints to create the app, upload the logo, update the draft, create and attach an OAuth app, and request deploy — replacing ~10 minutes of manual copy-paste across several Yandex pages. The pipeline is resumable: partial failures persist step-level artifacts (`skill_id`, `logo_id`, `oauth_app_id`, `state`) so retry continues from the last completed step. ### UX - **Numbered steps** — `cloud_plus` shows Register → Create skill → Link (OTP); `direct` shows Create skill only. Later steps are hidden until the previous one is complete. - **Automatic manual fallback** — on failure the form unfolds copy-paste fields (Backend URL, Client ID/Secret, Auth/Token URLs, Dialogs console link) so the user can finish in `dialogs.yandex.ru` by hand without leaving MA settings. - **Advanced view** — all manual-setup reference values stay available for power users, even when auto-create succeeds. - **Configured-state collapse** — once Skill ID + OAuth token are saved, edit fields collapse into a single \"Open skill in Yandex.Dialogs\" link. - **Cloud-mode advisory** — warns that the public Yaha Cloud skill allows only one linked instance per Yandex account and suggests Cloud Plus for multi-install setups. - **Connection Type** moved out of Advanced — it's the first decision and should render in the default view. ### Removed - `experimental_auto_create_skill` master toggle — auto-create is on by default. --- ### Changes since the initial bundle (review feedback in this PR) - **Cloud Plus manual fallback hidden before registration** — `cloud_plus` Client ID template embeds the yaha-cloud instance UUID; before the user clicks Register it was rendering as `yandex_smart_home:` (empty UUID). The manual block is now suppressed entirely for cloud_plus while `cloud_instance_id` is empty, so Advanced view can't surface a half-formed Client ID. - **SECURE_STRING `CONF_DIRECT_CLIENT_SECRET` round-trip** — prefer the persisted secret from `saved_config` over the (empty on re-open) form value, falling back to a fresh UUID only for first-time setup. - **`asyncio.CancelledError` passthrough** — both broad `except Exception` clauses (orchestrator + config-action handler) now re-raise `CancelledError` so cooperative cancellation during HA shutdown / config-flow abort is preserved instead of being absorbed into a `FAILED` artifact. - **`_build_authenticator_cm` non-idempotent wrap fix** — detects an already-`@asynccontextmanager`-decorated authenticator and passes it through instead of re-wrapping (the outer wrapper would otherwise call `__anext__` on a CM object and crash at runtime). The async-iterator path no longer calls the factory twice. - **`SkillCreationState.DEPLOY_REQUESTED` is now an observable checkpoint** — previously defined and allow-listed in the resume branch but never written; the orchestrator now sets it before `request_deploy`, so mid-publish crashes resume from publish-only. - **Upstream lint/mypy conformance** — docstring-below-constant removed, StrEnum comparisons use `.value`, strict-mypy annotations on test helpers, `"Retry" in action.action_label` narrowed before the `in` check. - Several smaller docstring and log-leak fixes (Copilot review). ### Dependencies No new top-level dependencies. `ya-passport-auth` (already at 1.3.0 from the previous bump) provides the Device Flow / Passport cookie refresh used by the auto-create orchestrator; all Dialogs calls reuse that session. ### Tests 293 unit tests in the upstream provider repo, including syrupy-snapshot tests for the Dialogs API payload builders. Covered: orchestrator state machine (resume from each intermediate state including `DEPLOY_REQUESTED`, Device Flow timeout, CSRF miss, 409 duplicate, `CancelledError` propagation), UI visibility (step gating, advanced/collapse rules, HTTPS/base-URL preconditions for `direct`, SECURE_STRING fallback, cloud_plus manual-block suppression pre-registration), and the `_handle_config_actions` wiring. No live Yandex calls. ### Compatibility - No schema or storage migration — the artifact blob is a single JSON string stored under the existing provider config. - Existing `CONF_SKILL_ID` / `CONF_SKILL_TOKEN` stay editable; auto-create populates `CONF_SKILL_ID` only on full success. - Users on v1.3.0 see the new multi-step UX on next open; no action required from existing installs. --- ### Related - Documentation update: [music-assistant/music-assistant.io#623](music-assistant/music-assistant.io#623) — documents the auto-create skill flow and numbered-step UX introduced here. Full CHANGELOG: [trudenboy/ma-provider-yandex-smarthome/CHANGELOG.md](https://github.com/trudenboy/ma-provider-yandex-smarthome/blob/main/CHANGELOG.md) --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
… (v1.5.0+) 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) <noreply@anthropic.com>
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 <player> 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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a documentation page for the Yandex Smart Home plugin, which exposes Music Assistant players to Yandex Alice via the Yandex Smart Home API as smart home media devices (
devices.types.media_device.receiver).Updated to cover the automatic skill creation flow introduced in provider v1.4.x — the config form now walks the user through numbered setup steps, runs OAuth Device Flow, creates the private Yandex Dialogs skill automatically via the undocumented
dialogs.yandex.ru/developer/app-store-api, and falls back to a copy-paste form if the API breaks.Also covers the playlists-as-input_source voice-control workaround introduced in provider v1.5.0 — pre-pick MA library playlists, assign voice aliases to
mode(input_source)slots in the Yandex app, then say the alias to Alice. This is the only voice path for selecting specific content given the API has noplay_mediafor third-party devices.Changes
src/content/docs/plugins/yandex-smarthome.mdastro.config.mjsunder PluginsThe page follows the style of the Yandex Music provider page (CAUTION / WARNING / NOTE callouts, features table, explicit settings list, known issues / notes) and documents:
cloud_plus/direct: OAuth Device Flow atya.ru/device, skill creation against Yandex.Dialogs API, Skill ID filled in automatically, resumable on partial failureon_off,range(volume),toggle(mute),toggle(pause),range(channel),mode(input_source))one..tenmode values in the Yandex app, trigger by voiceplay_media, no seek, no track-info push, up to 10 input-source entries shared between native sources and playlists)Related PRs
mode(input_source)workaround documented on this pageRelated links
Test plan
/plugins/yandex-smarthome/