docs(plugins): add Yandex Smart Home plugin page#623
Open
trudenboy wants to merge 9 commits intomusic-assistant:betafrom
Open
docs(plugins): add Yandex Smart Home plugin page#623trudenboy wants to merge 9 commits intomusic-assistant:betafrom
trudenboy wants to merge 9 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>
…ack)
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 <noreply@anthropic.com>
… to alice 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 music-assistant#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.
5 tasks
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
User-facing setup walkthrough for the Yandex Smart Home plugin (provider source: trudenboy/ma-provider-yandex-smarthome v2.1.0). Companion to upstream PR music-assistant/server#3834.
The page covers:
cloud/cloud_plus/direct), with a numbered setup walkthrough for each.dialogs.yandex.ru) — resumable across transient failures, cached Yandex Passport token reused on subsequent runs.play_media(mode(input_source)slotsone..ten, ordinal-only by Yandex constraint).External Base URLoverride for direct mode (HA Ingress / reverse-proxy compatibility).ma-provider-yandex-alicefor free-form voice control (search-and-play arbitrary content by phrase via a Yandex Dialogs custom skill) — that lives in a separate provider since smarthome v2.0.0.Status
src/content/docs/plugins/yandex-smarthome.md(134 lines).astro.config.mjsadds the page entry.ya-dialogs-apiPyPI lib).