Add Windows node text-to-speech

[RBrid]

Implements support for the tts.speak command tracked by #252. Adds the shared TTS capability, Windows and ElevenLabs playback paths, Settings UI/persistence, gateway/MCP advertisement, Command Center classification, docs, and tests.

Summary

Adds support for Windows node text-to-speech via a new tts.speak command.

This is the focused TTS slice tracked by #252, extracted from the broader voice work prototyped in #120. Credit to @NichUK for the original reference implementation and exploration in #120.

Closes #252.

What changed

• Added shared TtsCapability with command tts.speak.
• Added Windows speech synthesis playback as the default local provider.
• Added optional ElevenLabs TTS provider support.
• Added TTS Settings UI and persisted settings.
• Protected stored ElevenLabs API keys with Windows DPAPI.
• Registered TTS in node mode and local MCP only when enabled.
• Added MCP command description for tts.speak.
• Classified tts.speak as a privacy-sensitive/dangerous Command Center command.
• Excluded tts.speak from Mac parity diagnostics until Mac implements it.
• Added provider-wide 5,000-character request guard.
• Added ElevenLabs HTTP timeout and provider-side validation.
• Added interrupt semantics so interrupted playback does not report false success.
• Updated docs for setup, allowlisting, and manual testing.
• Added Shared and Tray tests for capability behavior, settings, guardrails, and command grouping.

Manual validation

Validated Windows provider invocation through the gateway:

openclaw nodes invoke --node <windows-node-id> --command tts.speak --params '{"text":"hello from OpenClaw","provider":"windows"}'

Observed successful response:

{
  "ok": true,
  "command": "tts.speak",
  "payload": {
    "spoken": true,
    "provider": "windows",
    "contentType": "audio/wav",
    "durationMs": 2447
  }
}

Automated validation

Passed locally:

.\build.ps1
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore

Results:

• Shared tests: 1059 passed / 20 skipped
• Tray tests: 252 passed

[Copilot]

Pull request overview

Adds a new Windows node tts.speak command (tracked by #252) by introducing a shared TTS capability plus Windows/ElevenLabs playback implementations, settings/UI, MCP advertisement text, command-center grouping, docs updates, and targeted tests.

Changes:

• Introduces TtsCapability (tts.speak) in Shared and wires it into the Windows tray node when enabled.
• Adds Windows built-in speech synthesis + optional ElevenLabs client, plus persisted settings (with DPAPI protection for the ElevenLabs API key).
• Updates MCP tool descriptions, Command Center command-group classification, docs/README, and adds Shared/Tray tests.

Show a summary per file

File	Description
tests/OpenClaw.Tray.Tests/TrayMenuWindowMarkupTests.cs	Verifies new Settings UI elements exist (automation IDs for TTS controls).
tests/OpenClaw.Tray.Tests/SettingsRoundTripTests.cs	Adds settings round-trip/defaulting assertions for new TTS settings + DPAPI protect/unprotect tests.
tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj	Adds DPAPI package + links SettingsManager and ElevenLabs client into the test project.
tests/OpenClaw.Tray.Tests/ElevenLabsTextToSpeechClientTests.cs	Adds unit tests for ElevenLabs request construction, validation, error formatting, and timeout.
tests/OpenClaw.Shared.Tests/ModelsTests.cs	Validates tts.speak is classified as dangerous and excluded from Mac parity set.
tests/OpenClaw.Shared.Tests/McpToolBridgeTests.cs	Ensures MCP tools/list returns a curated description for tts.speak.
tests/OpenClaw.Shared.Tests/CapabilityTests.cs	Adds TtsCapability execution/validation tests (required args, length guard, handler behavior).
src/OpenClaw.Tray.WinUI/Windows/SettingsWindow.xaml.cs	Loads/saves new TTS settings and toggles ElevenLabs settings UI visibility based on provider.
src/OpenClaw.Tray.WinUI/Windows/SettingsWindow.xaml	Adds TTS toggle, provider selection, and ElevenLabs API key/voice/model inputs.
src/OpenClaw.Tray.WinUI/Services/TextToSpeech/TextToSpeechService.cs	Implements Windows/ElevenLabs playback and interrupt semantics via MediaPlayer gating.
src/OpenClaw.Tray.WinUI/Services/TextToSpeech/ElevenLabsTextToSpeechClient.cs	Adds ElevenLabs HTTP client with validation, timeout, and error message construction.
src/OpenClaw.Tray.WinUI/Services/SettingsManager.cs	Persists TTS settings; protects ElevenLabs API key at rest using DPAPI (dpapi: prefix).
src/OpenClaw.Tray.WinUI/Services/NodeService.cs	Registers TTS capability/service when enabled; disables tts.* commands when not enabled.
src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj	Adds DPAPI package dependency required for protected settings secrets.
src/OpenClaw.Shared/SettingsData.cs	Adds shared DTO fields for TTS settings persistence.
src/OpenClaw.Shared/Models.cs	Adds tts.speak to dangerous command grouping and adjusts Mac parity command list.
src/OpenClaw.Shared/Mcp/McpToolBridge.cs	Adds curated MCP description for tts.speak tool.
src/OpenClaw.Shared/Capabilities/TtsCapability.cs	Adds new node capability handling tts.speak with validation, guardrails, and event hook.
docs/gateway-node-integration.md	Documents adding tts.speak to the gateway allowlist.
docs/WINDOWS_NODE_TESTING.md	Documents tts.speak requirements and capability advertisement behavior.
docs/MCP_MODE.md	Updates MCP tool list summary to include tts.speak.
README.md	Updates node capability table, allowlist guidance, and adds a manual tts.speak invocation example.

Copilot's findings

Tip

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

Comments suppressed due to low confidence (2)

src/OpenClaw.Tray.WinUI/Services/TextToSpeech/TextToSpeechService.cs:207

• TextToSpeechService implements IDisposable but doesn’t dispose owned disposable resources like _playbackGate (and it also doesn’t attempt to stop/dispose an _activePlayer directly during shutdown). Please dispose the semaphore (and ensure any active MediaPlayer is stopped/disposed deterministically) to avoid leaking WinRT/media resources across node restarts/shutdown.

    public void Dispose()
    {
        InterruptActivePlayback();
        // Playback may still release the gate after an interrupt during shutdown.
        _elevenLabsClient.Dispose();
    }

src/OpenClaw.Shared/Models.cs:1057

• MacNodeParityCommands used to include .. DangerousCommands, but now it hard-codes a subset to exclude tts.speak. This increases the chance that future dangerous commands won’t be covered by parity diagnostics unless someone remembers to update this list. Consider constructing the Mac parity list from DangerousCommands with an explicit exclusion for tts.speak (or adding a clear comment explaining why dangerous commands must be enumerated manually).

    public static readonly string[] MacNodeParityCommands =
    [
        .. SafeCompanionCommands,
        "camera.snap",
        "camera.clip",
        "screen.record",
        "system.notify",
        "system.run",
        "system.which",
        "browser.proxy"
    ];

• Files reviewed: 22/22 changed files
• Comments generated: 1

[Copilot]

durationMs is currently derived from a wall-clock stopwatch around synthesis + playback (and for ElevenLabs also includes network latency). This makes the response field misleading if callers expect audio duration. Consider either computing playback duration from MediaPlayer.PlaybackSession.NaturalDuration/position, or renaming the field (and docs) to something like elapsedMs to match its semantics.

This issue also appears on line 202 of the same file.

[shanselman]

Thanks, @RBrid. This focused TTS slice is a good way to land the first stable piece of Windows voice support.

This overlaps with the broader Voice Mode direction in #120 from @NichUK, so I’d like to treat this as the foundation layer: land tts.speak first, then have the remaining STT / Talk Mode / repeater / UX work build on top in smaller follow-up PRs.

I pushed a maintainer rebase commit that keeps this branch current with master, preserves the existing SettingsManager test-isolation hook, and removes the duplicate Tray test compile item. Local validation is green:

• ./build.ps1
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore