docs: surface hosted speech gateway demo for newcomers#541
docs: surface hosted speech gateway demo for newcomers#541staging-devin-ai-integration[bot] wants to merge 4 commits into
Conversation
Add a 'Try it from your terminal' section (curl-based TTS/STT against tts.streamkit.dev / stt.streamkit.dev) to the docs landing page and README so newcomers can see what StreamKit can do without installing anything. Both carry a generic best-effort/no-SLA disclaimer. Also note the hosted instance in the speech-gateway example README and fix a stale 'cd' path there (streamkit-cli-gateway -> speech-gateway). Signed-off-by: streamkit-devin <devin@streamkit.dev>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![staging-devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/870844?s=60&v=4){kind=small}
| Speech to text (send any Ogg/Opus file, get back newline-delimited JSON): | ||
|
|
||
| ```bash | ||
| curl --data-binary @sample.ogg https://stt.streamkit.dev |
There was a problem hiding this comment.
🟡 STT example references a file the reader has not created
The new landing-page STT command uses --data-binary @sample.ogg, but this section is advertised as “No install required” and does not include any preceding step that creates or downloads sample.ogg; the docs’ quick-start only creates that file in a separate guide (docs/src/content/docs/getting-started/quick-start.md:104-116). A reader running the copied command from this page will have curl fail locally with “Failed to open/read local data” before it ever reaches the public demo.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
There was a problem hiding this comment.
Valid catch for the landing page specifically — it's framed as "no install required," so @sample.ogg reads like a file the reader should already have, and curl will fail locally before reaching the demo. (The README copy is fine since it uses the in-repo @samples/audio/system/sample.ogg.)
Proposed fix for the landing page, pending the author's call:
- Make it self-contained by chaining the two endpoints so no local file is needed:
curl -sd 'StreamKit transcribes speech' https://tts.streamkit.dev | curl -s --data-binary @- https://stt.streamkit.dev
- Or keep it simple with an obvious placeholder (
@your-audio.ogg) and a note that any Ogg/Opus file works.
Holding off until @streamer45 confirms which they'd prefer.
There was a problem hiding this comment.
Fixed in c13dd5d — the landing-page STT example now pipes the TTS output straight into STT, so it's fully self-contained (no local file) and doubles as a demo of both endpoints:
curl -sd 'StreamKit transcribes speech' https://tts.streamkit.dev | curl -s --data-binary @- https://stt.streamkit.dev| Text to speech (returns Opus audio, piped straight to `ffplay`): | ||
|
|
||
| ```bash | ||
| curl -d 'Hello from StreamKit' https://tts.streamkit.dev | ffplay -nodisp -autoexit - |
There was a problem hiding this comment.
📝 Info: Hosted TTS example relies on gateway content-type fallback
The new hosted TTS examples intentionally omit -H "Content-Type: text/plain". This is still compatible with the existing gateway because curl -d sends application/x-www-form-urlencoded, and handleTTS explicitly treats that content type as text/plain before proxying (examples/speech-gateway/cmd/gateway/main.go:260-264). I therefore did not flag the missing header as a bug, although adding the explicit header would make the example less dependent on this gateway-specific fallback.
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
There was a problem hiding this comment.
Intentional — these mirror the exact CLI commands the maintainer shared, so I kept them copy-paste-identical and relied on the gateway's documented application/x-www-form-urlencoded → text/plain fallback in handleTTS. Happy to add the explicit -H "Content-Type: text/plain" if we'd rather not depend on the fallback; leaving as-is for now to match the original.
The landing page is framed as 'no install required', but the STT example referenced a local @sample.ogg the reader never creates. Pipe the TTS output straight into STT so the command runs as-is and also showcases both endpoints at once. Signed-off-by: streamkit-devin <devin@streamkit.dev>
Replace the file-based STT example (which referenced a sample.ogg the reader doesn't have) with a self-contained ffmpeg mic-capture oneliner that streams Opus straight to the hosted endpoint and pretty-prints the transcript with jq. Signed-off-by: streamkit-devin <devin@streamkit.dev>
2 participants
Summary
Surface the hosted speech gateway (
tts.streamkit.dev/stt.streamkit.dev) as a zero-install glimpse of StreamKit for newcomers, with a clear best-effort/no-SLA disclaimer.docs/.../index.mdx): a "Try it from your terminal" section. TTS pipes audio toffplay; STT is a self-containedtts | sttchain (no local file, no extra tooling) so the first touch always works.examples/speech-gateway/README.md: same TTS one-liner; STT uses anffmpegmic-capture one-liner (record → Opus →curl→jq) with macOS + Linux variants, so there's no dependency on a sample audio file. The example points at its existing cross-platform./stt.shfor an interactive version.cd examples/streamkit-cli-gatewaypath in the example README.Docs-only — no code paths touched.
Review & Validation
tts | sttchain verified against the live endpoint here; mic variants confirmed on macOS + Linux.Notes
Part of a broader speech-services effort; the observability pieces (gateway Prometheus metrics, dashboard rows, oneshot
servicelabel) are tracked in separate PRs.Link to Devin session: https://staging.itsdev.in/sessions/2abca85782ba45fe90994b8307526aa3
Requested by: @streamer45
Devin Review
72d14a6(HEAD isa1ee443)