# Use Gladys' voice through an external integration

**URL:** <https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644>\
**Category:** Demande de fonctionnalités\
**Tags:** demande-core\
**Created:** [November 22, 2026, 1:39pm UTC](https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644 "2026-11-22T13:39:22Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![mutmut](https://gladys-assistant-community.b-cdn.net/user_avatar/community.gladysassistant.com/mutmut/32/14064_2.png) [@mutmut](https://community.gladysassistant.com/u/mutmut)\
**Post date:** [November 22, 2026, 1:39pm UTC](https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644/1 "2026-11-22T13:39:22Z")

</div>

After creating the Karotz integration, we can no longer access Gladys’s voice to make the rabbit speak autonomously.

> [@mutmut](#):
>
> ## What we can’t do for now
> 
> - **Make the rabbit speak with Gladys’s voice from the integration.** Today, an integration cannot ask Gladys to read a sentence: only the “Speak on a speaker” action and the voice assistant can do that. The “Make the rabbit speak” action therefore uses the rabbit’s own voice. Under Free Rabbits OS, it’s an online service that no longer responds on mine. That’s also why there’s no “Make speak” button in the widget. I open a separate topic to propose an evolution of the core and the SDK: the rabbit could then speak from the widget, or announce the exact time.

We would need to modify Gladys’s core so that an external integration can access Gladys’s voice (local or cloud, integrated or external).

2 PRs are in progress; I’ll post the link as soon as they’re ready.

---

<div class="post-metadata">

**Author:** ![mutmut](https://gladys-assistant-community.b-cdn.net/user_avatar/community.gladysassistant.com/mutmut/32/14064_2.png) [@mutmut](https://community.gladysassistant.com/u/mutmut)\
**Post date:** [November 22, 2026, 1:51pm UTC](https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644/2 "2026-11-22T13:51:06Z")

</div>

The 2 PRs:

- Gladys core

> <https://github.com/GladysAssistant/Gladys/pull/3435>
>
> \### Description
> 
> Since #3212, the instance's voice can be a local engine (a \`typ…e: "tts"\` integration) instead of Gladys Plus. That voice has two consumers: the "Talk on a speaker" scene action (\`MUSIC.PLAY\_NOTIFICATION\`) and the voice assistant reply. An integration cannot use it.
> 
> Field case: the \[Karotz integration\](https://github.com/smuteau/gladys-karotz). The rabbit can play an audio URL, but its own text-to-speech is an online service, which no longer answers on my rabbit. "Talk on a speaker" works, because the rabbit exposes \`play\_notification\`. But the integration's own "Make the rabbit speak" action cannot get a clip of the voice: no host API route and no SDK call gives one. For the same reason its widget has no "speak" button. The same goes for any integration that drives its own player (a doorbell, a speaker with no \`play\_notification\` feature).
> 
> \*\*What changes\*\*
> 
> \- New host API route \*\*\`POST /api/integration/v1/tts/speech\_url\`\*\* \`{ "text", "language" }\` → \`200 { "url" }\`.
> - It calls \`gladys.tts.getSpeechUrl\`, like the two other consumers. The voice is the active provider, never chosen by the caller.
> - With an integration provider, the URL is the LAN \`http://\` URL of the RAM clip (10 minutes, 20-clip cap). With Gladys Plus, it is the signed \`https://\` URL, returned as is: a player that cannot read HTTPS (the Karotz is one) needs a local voice, as it already does for "Talk on a speaker".
> - Without \`language\`, the first administrator's language is used, as for a scene announcement.
> \- \*\*A host API route, not a WebSocket command.\*\* The WebSocket carries core → integration commands and integration → core fire-and-forget nudges. Integration → core requests that need an answer are host API routes (\`GET /house\`, \`POST /network\_discovery/scan\`).
> \- \*\*Who may call it: every integration type, no manifest flag.\*\* The integration gets back only a clip of a text it supplied itself. The manifest flags (\`location\`, \`network\_wake\`…) protect personal data or what the core emits on the integration's behalf, and this call is neither. What it consumes (the Gladys Plus TTS quota, or a local engine's CPU) is bounded by the rate limit.
> - A \`speech: true\` flag was considered and set aside. It would mean a new key in the canonical manifest schema (integration-store) and a new line on the install screen, for a call that exposes nothing. It can still be added later without breaking anything, if quota consumption needs the admin's consent. \*\*Your call if you prefer the flag.\*\*
> \- \*\*Bounds\*\*
> - \`text\`: a non-blank string of at most 2000 characters (\`MAX\_TTS\_TEXT\_LENGTH\`). A longer text is a \`400\`, not truncated: the integration chose it and can split it.
> - \`language\`: a tag such as \`fr\`, \`en-US\` or \`pt\_BR\`, or \`null\`. Anything else is a \`400\`.
> - \*\*10 requests per minute per integration\*\* (\`MAX\_TTS\_SPEECH\_URLS\_PER\_MINUTE\`, a fixed window like \`POST /state\`), \`429\` beyond.
> - A refused request (\`400\`) is not counted. The counter is dropped on uninstall.
> \- \*\*One failure code.\*\* Every failure of the voice answers \`503 SERVICE\_UNAVAILABLE\`, message \`TTS\_UNAVAILABLE\`:
> - no provider running, or the selected one gone;
> - a timeout or an invalid clip;
> - Gladys Plus answering without a URL;
> - Gladys Plus \*\*402 / 403 / 429\*\*. Those are the upsell paths of the Gladys UI; relayed to an integration they would read as "payment required", "forbidden" or "you are rate limited".
> - The core logs the cause with the caller's selector. The admin sees the state of the voice on the Voice card.
> \- Spec: \`docs/specs/external-integrations/capabilities/tts-type.md\`, new \*\*point 3\*\*, plus its risk, tests and verification. Following the README rule, the route lives in that file, not in the shared C.3/C.8 tables.
> \- SDK counterpart: GladysAssistant/integration-sdk-js#51, \`gladys.getSpeechUrl(text, { language })\`.
> 
> \*\*Tests\*\*
> 
> \- \`server/test/lib/external-integration/externalIntegration.getSpeechUrl.test.js\` covers:
> - the Gladys Plus URL;
> - the full chain with a real \`tts\` proxy service: the provider receives the caller's text and language, and the LAN URL serves its clip;
> - the default language;
> - every \`503\` path, including Gladys Plus 402/403/429 and a provider's invalid clip, which stays a \`503\`, not a \`400\`;
> - validation, and the rate limit (per integration, window reset, refused requests not counted, cleanup on uninstall).
> \- \`server/test/controllers/integrationHost/integrationHost.tts.test.js\` covers \`401\`, \`200\` (Gladys Plus, and LAN URL whose clip is then fetched unauthenticated), \`400\`, \`503\` and \`429\`.
> \- Local run: full server suite green (\`TZ=UTC npm test\`: 10,235 passing, 0 failing). 100% line and branch coverage of \`externalIntegration.getSpeechUrl.js\`. ESLint reports 0 errors on the server; Prettier and \`checkjs\` are clean on the changed files. The front is not touched.
> \- \*\*Not tested yet:\*\* the whole chain on a real device. The Karotz integration will call the route once it and the SDK method are available.
> 
> \### Related request
> 
> Forum: https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644
> 
> \### Checklist
> 
> \- \[x\] If a forum topic or GitHub issue exists, the description links it (\`Forum: https://community.gladysassistant.com/t/...\` or \`Closes #...\`)
> \- \[x\] Tests pass: \`cd server && npm run coverage\` (Codecov requires 100% coverage on changed lines) and Cypress (\`npm run cypress:run\`) if the UI changed (it did not)
> \- \[x\] Linter and prettier pass on both front and server (\`npm run eslint\`, \`npm run prettier\`): run on the server, front not changed
> \- \[x\] No undocumented breaking change
> 
> 🤖 Generated with \[Claude Code\](https://claude.com/claude-code)
> 
> 
> 
> 
> 
> 
> \## Summary by CodeRabbit
> 
> \* \*\*New Features\*\*
> \* Integrations can request a speech URL through the API, using available text-to-speech providers.
> \* Requests support an optional language and are limited to 10 per integration per minute.
> \* \*\*Bug Fixes\*\*
> \* Invalid requests are rejected, and unavailable speech services return a consistent error.
> \* \*\*Documentation\*\*
> \* Updated the integration guide with the speech URL capability and verification steps.

- SDK:

> <https://github.com/GladysAssistant/integration-sdk-js/pull/51>
>
> SDK side of the new host API route \`POST /api/integration/v1/tts/speech\_url\` (Gl…adys spec \`capabilities/tts-type.md\`, point 3; core PR: GladysAssistant/Gladys#3435).
> 
> \## Why
> 
> Some integrations drive their own player: a speaking rabbit, a doorbell, a speaker with no \`play\_notification\` feature. They can now speak with the voice the admin selected (Gladys Plus, or a local engine served by a \`type: "tts"\` integration) instead of their device's built-in, often online, text-to-speech. Until now, only \`onTtsSynthesize\` existed, and it is for providers.
> 
> \## What changes
> 
> \- \*\*\`gladys.getSpeechUrl(text, { language }?)\` → \`Promise\<string\>\`\*\*, the URL of the clip.
> - The core's checks are mirrored locally, before any request, like \`wakeOnLan\`: \`text\` non-blank, at most 2,000 characters; \`language\` a tag such as \`fr\`, \`en-US\` or \`pt\_BR\`, or \`null\` (default: the first administrator's language, chosen by the core). A bad value is a local \`Error\`.
> - \*\*Waits up to 35 s\*\*, or the client's \`requestTimeout\` if longer, instead of the 15 s default. A local synthesis may take the core's whole 30 s \`tts.synthesize\` deadline. For this, \`HttpClient.post\`/\`request\` take an optional per-request \`{ timeout }\`.
> - Any failure of the voice is the core's \`503\` \`GladysApiError\` (message \`TTS\_UNAVAILABLE\`). The core's \`429\` applies past 10 requests per minute.
> \- \*\*Types\*\*: \`getSpeechUrl\` and \`SpeechUrlOptions\` in \`index.d.ts\`, with type tests.
> \- \*\*Testing helpers\*\*: \`createFakeGladys()\` answers the route in memory.
> - Each call returns \`http://fake-gladys.invalid/api/v1/tts/audio/fake-\<n\>.mp3\`.
> - \`createFakeGladys({ ttsAvailable: false })\`, or \`gladys.fake.ttsAvailable = false\`, makes it reject with the core's \`503\`.
> - \`gladys.fake.speeches\` records every text a clip was handed out for. Typed in \`testing.d.ts\`.
> \- \*\*README\*\*: a row in the methods table, a "Speaking with the instance's voice" section next to "Text-to-speech providers" (with a fall-back-to-the-device example), and the fake's new option and record in "Testing your integration". No other table row is re-padded.
> 
> \## Tests
> 
> \- \`test/speech-url.test.js\` (against \`FakeGladysServer\`) covers:
> - body mapping, with or without a language;
> - the 2,000-character bound;
> - local refusals with no request sent;
> - the \`503\` and \`429\` \`GladysApiError\`s;
> - a slow route answered after a 100 ms \`requestTimeout\` client would have given up, and the 35 s / longer-\`requestTimeout\` choice.
> - \`FakeGladysServer\` gains the route and a \`delayedRoutes\` knob.
> \- \`test/testing.test.js\` covers the fake's URLs, \`speeches\`, the \`503\` when \`ttsAvailable\` is false (recorded with its status, not as a speech), and the local checks.
> \- \`npm test\` (475 passing), \`npm run lint\`, \`npm run check-types\`, \`npm run prettier-check\`: all green.
> 
> Requires a Gladys with the route (unreleased: the core PR above). \*\*Not tested yet\*\* on a real device, end to end.
> 
> Forum topic: https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644
> 
> 🤖 Generated with \[Claude Code\](https://claude.com/claude-code)

---

<div class="post-metadata">

**Author:** ![pierre-gilles](https://gladys-assistant-community.b-cdn.net/user_avatar/community.gladysassistant.com/pierre-gilles/32/5886_2.png) [@pierre-gilles](https://community.gladysassistant.com/u/pierre-gilles)\
**Post date:** [November 22, 2026, 1:52pm UTC](https://community.gladysassistant.com/t/utiliser-la-voix-de-gladys-par-une-integration-externe/11644/3 "2026-11-22T13:52:44Z")

</div>

Hi @mutmut!

Why isn’t the “Speak on a speaker” action enough? 🙂
