Overview
OrukSTTService streams audio to Oruk’s realtime preview and returns interim
transcripts, final text, and independent phrase-emotion estimates. It uses
upstream Pipecat VAD events to commit utterances and can also accept explicitly
segmented audio. Optional speaker events identify boundaries within a turn.
Phrase estimates describe vocal expression. They are not verified assessments
of a person’s internal emotional state.
Installation
Install the separately maintained package and pin the release candidate:uv add "pipecat-oruk[agent]==0.1.0rc1".
Prerequisites
Create an Oruk account, obtain an API key from your developer portal, and setORUK_API_KEY in the server environment. Keep the key
on the server; it is used in the authenticated WebSocket upgrade.
Configuration
Constructor parameters
str | None
default:"None"
API key. When omitted, reads
ORUK_API_KEY from the environment.bool
default:"True"
Commit utterances on upstream VAD stop events. Add a
VADProcessor before
this service. For externally segmented audio, set this to False and queue
OrukCommitFrame() after each utterance.bool
default:"False"
By default, final text is emitted immediately and later phrase estimates
arrive separately. Set to
True to wait for clean turn completion and include
all returned phrase events in the final transcript’s metadata. Interim text
remains immediate.RealtimeOptions | None
default:"None"
Initial language, phrase segmentation, diarization, and turn limits. See the
integration
reference
for configuration and buffer limits.
STTSettings | None
default:"None"
Use
OrukSTTService.Settings(language="fr") to set the language. The model is
fixed to oruk-realtime; language updates are accepted only between turns.Usage
This pipeline excerpt assumes your application supplies the transport, aggregators, LLM, and TTS. Configure the pipeline’s input audio as 16 kHz mono PCM16 and avoid adding a second VAD inside the user aggregator.Reading phrase estimates
Phrase estimates are independent of transcript deltas and can arrive after final text. ReadOrukPhraseEmotionFrame or register an on_phrase_emotion
handler. Match results by stream, turn, and phrase identity; do not attach an
estimate to the nearest transcript delta. Speaker IDs restart with each
connection. The integration does not provide word alignment or transcript
confidence scores.
See result frames and event handlers
for the output fields and an event-handler example.
Compatibility
Release candidate0.1.0rc1 is tested with Pipecat 1.8.1 on Python
3.11–3.14. The package accepts Pipecat 1.8.x; other patch releases have not
been separately verified. The upstream Oruk realtime API is also in preview.
The production demonstration
records real WebRTC transcription, phrase estimates, cancellation, reconnection,
and metering. It does not establish emotion accuracy or a verified spoken
LLM/TTS conversation. See the
changelog
for subsequent compatibility checks.