Skip to content

docs: document local TTS on macOS, Linux, and Windows#110230

Open
ivan-digital wants to merge 6 commits into
openclaw:mainfrom
ivan-digital:docs/local-speech-tts
Open

docs: document local TTS on macOS, Linux, and Windows#110230
ivan-digital wants to merge 6 commits into
openclaw:mainfrom
ivan-digital:docs/local-speech-tts

Conversation

@ivan-digital

@ivan-digital ivan-digital commented Jul 17, 2026 •
edited
Loading

Copy link
Copy Markdown

Related: #110229

Release prerequisite: The macOS HTTP tab now explicitly requires the first Speech Swift release containing soniqo/speech-swift#415. It states that v0.0.22 has the server binary but not the OpenAI speech route, and directs current users to the released CLI path or a source build.

What Problem This Solves

OpenClaw users can already connect TTS to a custom OpenAI-compatible endpoint or a local executable, but the guide does not show a complete private, offline setup for macOS, Linux, or Windows. Users currently have to discover the correct provider, executable arguments, model setup, and WAV handling independently.

Why This Change Was Made

This documents the existing provider surfaces instead of adding another runtime integration. It adds copyable Speech Swift HTTP and CLI configurations for macOS, a speech-core Kokoro CLI configuration for Linux, and a speech-core Supertonic LiteRT configuration for Windows. It also documents the existing OpenAI responseFormat override required by WAV-only local endpoints.

User Impact

Users can configure fully local TTS on all three desktop platforms from one guide. The setup keeps audio inference on the host and preserves current OpenClaw provider behavior; no application code or dependencies change.

Evidence

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation extensions: tts-local-cli plugin: azure-speech Azure Speech plugin size: XS labels Jul 17, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 17, 2026
@clawsweeper

clawsweeper Bot commented Jul 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 18, 2026, 8:46 AM ET / 12:46 UTC.

Summary
Adds cross-platform local TTS setup recipes to the TTS guide and updates the generated docs-map heading.

PR surface: Docs +158. Total +158 across 2 files.

Reproducibility: not applicable. This PR addresses missing documentation for already available provider paths, and the linked report supplies a direct guide-content verification path.

Review metrics: none identified.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • none.

Next step before merge

  • No automated repair is warranted because no concrete code, documentation, or test defect remains in the reviewed branch.

Security
Cleared: The diff is documentation-only and introduces no executable code, dependency, workflow, secret, permission, or supply-chain change.

Review details

Best possible solution:

Merge the focused guide after normal maintainer confirmation that the cited third-party installation commands and release prerequisites remain accurate at landing time.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR addresses missing documentation for already available provider paths, and the linked report supplies a direct guide-content verification path.

Is this the best way to solve the issue?

Yes. Documenting the existing OpenAI-compatible and local CLI provider surfaces is the narrowest maintainable solution because it avoids adding a parallel runtime integration.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against af2662f25a85.

Label changes

Label justifications:

  • P3: This is a small documentation discoverability improvement for existing local TTS capabilities, with no runtime behavior change.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +158. Total +158 across 2 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 2 166 8 +158
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 2 166 8 +158

What I checked:

  • Existing-provider documentation: The PR documents the existing OpenAI-compatible and local CLI TTS paths rather than adding runtime code, dependencies, configuration schema, or provider APIs. Public docs: docs/tools/tts.md. (docs/tools/tts.md:378, f5b68eb13229)
  • Release prerequisite addressed: The macOS HTTP recipe now explicitly requires Speech Swift v0.0.23 or later and directs users with an older Homebrew installation to upgrade, resolving the earlier review finding about an unreleased HTTP route. Public docs: docs/tools/tts.md. (docs/tools/tts.md:391, f5b68eb13229)
  • Linked canonical documentation report: The PR is explicitly related to the open report for the missing cross-platform local-TTS guide; it is a candidate implementation rather than a duplicate cleanup target. Public docs: docs/tools/tts.md. (docs/tools/tts.md:378, f5b68eb13229)
  • Validation supplied in discussion: The refreshed-branch comment reports passing documentation formatting/markdown, MDX, link, glossary, and docs-map checks; the GitHub context also records successful check-docs and Real behavior proof checks. (f5b68eb13229)

Likely related people:

  • steipete: Likely routing candidate for the core TTS documentation and provider-facing product surface; the available review context does not provide enough local history to establish a stronger ownership claim. (role: adjacent owner; confidence: low; files: docs/tools/tts.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (5 earlier review cycles)
  • reviewed 2026-07-17T23:18:05.301Z sha 4729b2e :: needs changes before merge. :: [P2] Gate the macOS HTTP recipe on a released Speech Swift version
  • reviewed 2026-07-18T06:46:52.480Z sha ec0963e :: needs maintainer review before merge. :: none
  • reviewed 2026-07-18T07:00:59.571Z sha d43870b :: needs maintainer review before merge. :: none
  • reviewed 2026-07-18T07:43:17.149Z sha d43870b :: needs maintainer review before merge. :: none
  • reviewed 2026-07-18T12:04:54.067Z sha f5b68eb :: needs maintainer review before merge. :: none

@ivan-digital
ivan-digital marked this pull request as ready for review July 18, 2026 06:34
@ivan-digital

ivan-digital commented Jul 18, 2026

Copy link
Copy Markdown
Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jul 18, 2026
@ivan-digital

ivan-digital commented Jul 18, 2026

Copy link
Copy Markdown
Author

Refreshed the branch against current main and updated the Windows recipe to use the published speech-core v0.0.11 package and its packaged Kokoro executable.

The complete documentation gate passes on the refreshed branch: formatting and markdown lint for 721 files, MDX validation for 737 files, 6,076 internal links with zero broken links, glossary validation, and a current generated docs map.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@BradGroux BradGroux mentioned this pull request Jul 18, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation extensions: tts-local-cli P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. plugin: azure-speech Azure Speech plugin rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ivan-digital