> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Oruk Speech-to-Text

> Oruk realtime speech and phrase estimates, plus optional local Orukeet CPU transcription for completed utterances.

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="Oruk labs" maintainerUrl="https://github.com/Oruk-AI" repo="https://github.com/Oruk-AI/pipecat-oruk" />

## 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:

```bash theme={null}
uv add "pipecat-oruk==0.1.0rc1"
```

For the repository's browser transport examples, use
`uv add "pipecat-oruk[agent]==0.1.0rc1"`.

## Prerequisites

Create an [Oruk account](https://oruk.ai/signup), obtain an API key from your
developer portal, and set `ORUK_API_KEY` in the server environment. Keep the key
on the server; it is used in the authenticated WebSocket upgrade.

## Configuration

### Constructor parameters

<ParamField path="api_key" type="str | None" default="None">
  API key. When omitted, reads `ORUK_API_KEY` from the environment.
</ParamField>

<ParamField path="vad" type="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.
</ParamField>

<ParamField path="wait_for_emotions" type="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.
</ParamField>

<ParamField path="options" type="RealtimeOptions | None" default="None">
  Initial language, phrase segmentation, diarization, and turn limits. See the
  [integration
  reference](https://github.com/Oruk-AI/pipecat-oruk#configure-and-troubleshoot)
  for configuration and buffer limits.
</ParamField>

<ParamField path="settings" type="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.
</ParamField>

## 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.

```python theme={null}
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.audio.vad_processor import VADProcessor
from pipecat_oruk import OrukSTTService

vad = VADProcessor(
    vad_analyzer=SileroVADAnalyzer(params=VADParams(start_secs=0.2, stop_secs=0.2))
)
stt = OrukSTTService(wait_for_emotions=True)

pipeline = Pipeline([
    transport.input(),
    vad,
    stt,
    user_aggregator,
    llm,
    tts,
    transport.output(),
    assistant_aggregator,
])
```

The source repository includes a complete
[browser agent example](https://github.com/Oruk-AI/pipecat-oruk/blob/main/examples/pipecat_agent.py)
and a [speech-only WebRTC example](https://github.com/Oruk-AI/pipecat-oruk/blob/main/examples/pipecat_browser/README.md)
that requires only an Oruk key.

### Reading phrase estimates

Phrase estimates are independent of transcript deltas and can arrive after
final text. Read `OrukPhraseEmotionFrame` 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](https://github.com/Oruk-AI/pipecat-oruk#read-results)
for the output fields and an event-handler example.

## Local Orukeet transcription

For local CPU recognition, the community package also provides
`pipecat_oruk.local.OrukeetSTTService`. It transcribes complete VAD utterances
without an API key or audio upload. This adapter is available from the pinned
source revision below; it is not included in the published `0.1.0rc1` release.

```bash theme={null}
uv add "pipecat-oruk[local] @ git+https://github.com/Oruk-AI/pipecat-oruk@9f50574f4ec71dc020dde668d50f229b8fce5a13"
```

Use a 16 kHz mono PCM16 pipeline with `VADProcessor` before the service:

```python theme={null}
from pipecat_oruk.local import OrukeetSTTService

stt = OrukeetSTTService()
await stt.prewarm()  # In async setup, before accepting audio.
# Pipeline([transport.input(), vad, stt, ...])
```

The [runnable file example](https://github.com/Oruk-AI/pipecat-oruk/blob/9f50574f4ec71dc020dde668d50f229b8fce5a13/examples/pipecat_local_file.py)
uses real Silero VAD and prints final transcripts. The model supports 25
languages with automatic detection, but this service returns no language code,
interim text, word timestamps, speaker labels, or phrase-emotion estimates.
Language forcing is rejected. Recognition runs in a worker thread; one instance
serializes native inference and pipeline cleanup waits for active work to finish.

The first load acquires the [Orukeet INT8 ONNX export](https://huggingface.co/oruk/orukeet)
from a pinned Hugging Face revision, checks every runtime file against SHA-256,
and retains the licenses and notices. The required `config.json` uses ordinary
Hugging Face model-download accounting. Complete cached loads make no HTTP
requests. Set `cache_dir` for a custom Hub cache and `local_files_only=True` to
require cached files. The weights use **CC BY-SA 4.0** with NVIDIA foundation
attribution; the adapter code is MIT-licensed.

This local path was checked with Pipecat **1.8.1**, Python **3.12** and ONNX
Runtime **1.24.4** on macOS arm64: repeated English, German, Spanish and French
recognition, silence, offline reload, and two utterances through the actual VAD
pipeline. These checks establish integration behavior, not a comparative speed
or accuracy result. See the [local service reference](https://github.com/Oruk-AI/pipecat-oruk/tree/9f50574f4ec71dc020dde668d50f229b8fce5a13#local-orukeet-transcription).

## Compatibility

Release candidate `0.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](https://github.com/Oruk-AI/pipecat-oruk/blob/main/docs/DEMO.md)
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](https://github.com/Oruk-AI/pipecat-oruk/blob/main/CHANGELOG.md)
for subsequent compatibility checks.