diff --git a/README.md b/README.md index 442a460c3..9281074c8 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,7 @@ Define your pipeline once, run it how you need. - [Project status](#project-status) - [Use cases](#use-cases) +- [Try it from your terminal](#try-it-from-your-terminal) - [Core concepts](#core-concepts) - [Quickstart (Docker)](#quickstart-docker) - [What's included](#whats-included) @@ -74,6 +75,31 @@ If you try it and something feels off, please open an issue (or a small PR). For - **Batch processing** — High-throughput file conversion or offline transcription using the Oneshot HTTP API. - **Your idea** — Add your own node or plugin and compose it into a pipeline +## Try it from your terminal + +Want a glimpse of what StreamKit can do without installing anything? These commands hit a public instance of the [speech gateway example](examples/speech-gateway/) — a thin HTTP front-end over StreamKit oneshot pipelines (Kokoro TTS and Whisper STT). + +Text to speech (returns Opus audio, piped straight to `ffplay`): + +```bash +curl -d 'Hello from StreamKit' https://tts.streamkit.dev | ffplay -nodisp -autoexit - +``` + +Speech to text (record 5s from your mic with `ffmpeg`, get back JSON — no audio file needed): + +```bash +# macOS (CoreAudio); list inputs with: ffmpeg -f avfoundation -list_devices true -i "" +ffmpeg -hide_banner -f avfoundation -i ":0" -t 5 -ac 1 -ar 48000 -c:a libopus -f ogg - | curl -s --data-binary @- -H 'Content-Type: audio/ogg' https://stt.streamkit.dev | jq + +# Linux (PulseAudio/PipeWire); use "-f alsa -i default" for ALSA +ffmpeg -hide_banner -f pulse -i default -t 5 -ac 1 -ar 48000 -c:a libopus -f ogg - | curl -s --data-binary @- -H 'Content-Type: audio/ogg' https://stt.streamkit.dev | jq +``` + +Drop `-t 5` to record until you stop `ffmpeg` with `q`. + +> [!NOTE] +> `tts.streamkit.dev` and `stt.streamkit.dev` are a free, best-effort public demo with no SLA — they may be slow, rate-limited, or offline at any time, and usage is monitored for abuse. Don't send anything sensitive. To run your own, see [`examples/speech-gateway/`](examples/speech-gateway/). + ## Core concepts - **Pipelines** are node graphs (DAGs) that process real-time streams and requests. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index a353d6f9b..9490b55c6 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -110,6 +110,25 @@ Then open [http://localhost:4545](http://localhost:4545) to access the web UI. > - Follow the [Quick Start](/getting-started/quick-start/) to run your first pipeline end-to-end. > - Explore the [web UI guide](/guides/web-ui/) and [Creating Pipelines](/guides/creating-pipelines/) when you're ready to build your own graphs. +## Try it from your terminal + +No install required — these hit a public instance of the [speech gateway example](https://github.com/streamer45/streamkit/tree/main/examples/speech-gateway), a thin HTTP front-end over StreamKit oneshot pipelines (Kokoro TTS and Whisper STT). + +Text to speech (returns Opus audio, piped straight to `ffplay`): + +```bash +curl -d 'Hello from StreamKit' https://tts.streamkit.dev | ffplay -nodisp -autoexit - +``` + +Speech to text — pipe the synthesized audio straight back into STT (no local file needed) and get back newline-delimited JSON: + +```bash +curl -sd 'StreamKit transcribes speech' https://tts.streamkit.dev | curl -s --data-binary @- https://stt.streamkit.dev +``` + +> [!NOTE] +> `tts.streamkit.dev` and `stt.streamkit.dev` are a free, best-effort public demo with no SLA — they may be slow, rate-limited, or offline at any time, and usage is monitored for abuse. Don't send anything sensitive. To run your own, see [`examples/speech-gateway`](https://github.com/streamer45/streamkit/tree/main/examples/speech-gateway). + ## Execution modes StreamKit supports two pipeline execution modes: diff --git a/examples/speech-gateway/README.md b/examples/speech-gateway/README.md index 7589bf712..d548770d4 100644 --- a/examples/speech-gateway/README.md +++ b/examples/speech-gateway/README.md @@ -8,6 +8,25 @@ SPDX-License-Identifier: MPL-2.0 Thin HTTP gateway that rewrites simple STT/TTS requests into the multipart oneshot format expected by a StreamKit backend. +## Hosted instance + +A free, best-effort public instance runs at `https://tts.streamkit.dev` and `https://stt.streamkit.dev`, so you can try the endpoints below without running anything: + +Text to speech (returns Opus audio, piped to `ffplay`): + +```sh +curl -d 'Hello from StreamKit' https://tts.streamkit.dev | ffplay -nodisp -autoexit - +``` + +Speech to text — record from your mic with `ffmpeg`, no audio file needed (use `STT_URL=https://stt.streamkit.dev ./stt.sh` for an interactive, cross-platform version): + +```sh +# macOS; on Linux use "-f pulse -i default" (PulseAudio/PipeWire) or "-f alsa -i default" +ffmpeg -hide_banner -f avfoundation -i ":0" -t 5 -ac 1 -ar 48000 -c:a libopus -f ogg - | curl -s --data-binary @- -H 'Content-Type: audio/ogg' https://stt.streamkit.dev | jq +``` + +There is no SLA — it may be slow, rate-limited, or offline at any time, and usage is monitored for abuse. Don't send anything sensitive. Run your own (below) to remove those limits. + ## Prereqs - StreamKit server running locally (default assumed: `http://127.0.0.1:4545`). @@ -16,7 +35,7 @@ Thin HTTP gateway that rewrites simple STT/TTS requests into the multipart onesh ## Run the gateway ```sh -cd examples/streamkit-cli-gateway +cd examples/speech-gateway go run ./cmd/gateway --listen :8080 --skit-url http://127.0.0.1:4545 ```