diff --git a/api-reference/server/services/stt/hakim.mdx b/api-reference/server/services/stt/hakim.mdx new file mode 100644 index 00000000..065a9457 --- /dev/null +++ b/api-reference/server/services/stt/hakim.mdx @@ -0,0 +1,148 @@ +--- +title: "Hakim" +description: "Speech-to-text service implementation using Hakim's Arabic-first realtime transcription API" +--- + +import { CommunityMaintained } from "/snippets/community-maintained.mdx"; + + + +## Overview + +`HakimSTTService` transcribes audio into text using [Hakim](https://tryhakim.ai)'s +Arabic-first realtime speech-to-text API. It is a `WebsocketSTTService` that opens +one persistent connection to `WSS /v1/audio/transcriptions/stream`, forwarding audio +continuously and relying on Pipecat's own VAD to signal end-of-turn — the same pattern +used by other continuous-streaming STT plugins in this framework (e.g. AssemblyAI, +Deepgram). + + + + Source code, examples, and issues for the Hakim integration + + + Learn more about Hakim's speech services + + + Create and manage your Hakim API keys from the dashboard (Settings -> API keys) + + + +## Installation + +This is a community-maintained package distributed separately from `pipecat-ai`, +built and maintained by the Hakim team. It is not yet published to PyPI, so install +it directly from GitHub: + +```bash +uv pip install git+https://github.com/tryHakimAI/hakim-pipecat.git +``` + +## Prerequisites + +### Hakim Account Setup + +Before using the Hakim STT service, you need: + +1. **Hakim Account**: Sign up at [tryhakim.ai](https://tryhakim.ai) +2. **API Key**: Generate a key (format: `hk_live_...`) from the dashboard + (Settings -> API keys), with the `stt:write` scope + +### Required Environment Variables + +- `HAKIM_API_KEY`: Your Hakim API key. Falls back to this environment variable if + `api_key` is not passed to the constructor. + +## Configuration + + + Hakim API key. Falls back to the `HAKIM_API_KEY` environment variable if not + provided. + + + + Language hint for transcription. + + + + Audio format of the input stream. One of `"pcm16"`, `"opus"`, or `"mulaw"`. + Pipecat's transport delivers PCM16 by default, so the default matches without + any client-side transcoding. + + + + Must match the sample rate of audio frames actually sent to the service. + + + + Pins the session to a specific regional endpoint. One of `"auto"`, `"de"`, + `"uae"`, or `"ksa"`. `"auto"` picks the closest healthy region. + + + + Overrides the region table entirely (staging / self-hosted). Takes precedence + over `region`. + + + + Runtime-updatable settings. See [Settings](#settings) below. + + +### Settings + +Runtime-updatable configuration passed via the `settings` constructor argument +using `HakimSTTService.Settings(...)`. + +| Parameter | Type | Default | Description | +| ------------ | ------ | ------------- | --------------------------------------------------------------------------------------------------------- | +| `timestamps` | `str` | `"segment"` | One of `"word"`, `"segment"`, or `"none"`. | +| `diarize` | `bool` | `False` | Speaker diarization. Only useful for stereo audio with one speaker per channel (e.g. call recordings) -- mono `diarize=True` transcribes without speaker labels. | +| `partials` | `bool` | `True` | Whether to emit interim (non-final) transcripts. | + + + See the [source + repository](https://github.com/tryHakimAI/hakim-pipecat) for the + authoritative, up-to-date configuration options. + + +## Usage + +```python +import os +from pipecat.pipeline.pipeline import Pipeline +from pipecat.transcriptions.language import Language +from hakim_pipecat import HakimSTTService + +stt = HakimSTTService( + api_key=os.getenv("HAKIM_API_KEY"), + language=Language.AR, +) + +pipeline = Pipeline([ + transport.input(), # audio/user input + stt, # Hakim STT transcription + context_aggregator.user(), # add user text to context + llm, # LLM generates response + tts, # text to speech synthesis + transport.output(), # stream audio back to user + context_aggregator.assistant(), # store assistant response +]) +``` + +## Compatibility + +Tested with Pipecat v1.5.0. Check the [source +repository](https://github.com/tryHakimAI/hakim-pipecat) for the latest tested +version and changelog. diff --git a/api-reference/server/services/supported-services.mdx b/api-reference/server/services/supported-services.mdx index ec1e7a53..d14c9230 100644 --- a/api-reference/server/services/supported-services.mdx +++ b/api-reference/server/services/supported-services.mdx @@ -145,6 +145,7 @@ Speech-to-Text services receive and audio input and output transcriptions. | [Google](/api-reference/server/services/stt/google) | `uv add "pipecat-ai[google]"` | Pipecat | | [Gradium](/api-reference/server/services/stt/gradium) | `uv add "pipecat-ai[gradium]"` | Pipecat | | [Groq (Whisper)](/api-reference/server/services/stt/groq) | `uv add "pipecat-ai[groq]"` | Pipecat | +| [Hakim](/api-reference/server/services/stt/hakim) | `uv pip install git+https://github.com/tryHakimAI/hakim-pipecat.git` | Community | | [Mistral](/api-reference/server/services/stt/mistral) | `uv add "pipecat-ai[mistral]"` | Pipecat | | [Moonshine](/api-reference/server/services/stt/moonshine) | `uv add "pipecat-ai[moonshine]"` | Pipecat | | [NVIDIA](/api-reference/server/services/stt/nvidia) | `uv add "pipecat-ai[nvidia]"` | Pipecat | @@ -179,6 +180,7 @@ Text-to-Speech services receive text input and output audio streams or chunks. | [Google](/api-reference/server/services/tts/google) | `uv add "pipecat-ai[google]"` | Pipecat | | [Gradium](/api-reference/server/services/tts/gradium) | `uv add "pipecat-ai[gradium]"` | Pipecat | | [Groq](/api-reference/server/services/tts/groq) | `uv add "pipecat-ai[groq]"` | Pipecat | +| [Hakim](/api-reference/server/services/tts/hakim) | `uv pip install git+https://github.com/tryHakimAI/hakim-pipecat.git` | Community | | [Hume](/api-reference/server/services/tts/hume) | `uv add "pipecat-ai[hume]"` | Pipecat | | [Inworld](/api-reference/server/services/tts/inworld) | Built in | Pipecat | | [Kokoro](/api-reference/server/services/tts/kokoro) | `uv add "pipecat-ai[kokoro]"` | Pipecat | diff --git a/api-reference/server/services/tts/hakim.mdx b/api-reference/server/services/tts/hakim.mdx new file mode 100644 index 00000000..c8bcf8d1 --- /dev/null +++ b/api-reference/server/services/tts/hakim.mdx @@ -0,0 +1,152 @@ +--- +title: "Hakim" +description: "Text-to-speech service implementation using Hakim's Arabic-first realtime synthesis API" +--- + +import { CommunityMaintained } from "/snippets/community-maintained.mdx"; + + + +## Overview + +`HakimTTSService` synthesizes speech from text using [Hakim](https://tryhakim.ai)'s +Arabic-first realtime text-to-speech API. It subclasses `InterruptibleTTSService` +(Hakim's realtime TTS has no mid-utterance cancel message and no word-level +timestamps, so interruption is handled by reconnecting rather than sending a cancel +frame) and opens one persistent connection to `WSS /v1/audio/speech/stream` -- each +sentence Pipecat sends to `run_tts` becomes one `speech.create` request on the same +socket, with no new TCP/TLS handshake per utterance. + + + + Source code, examples, and issues for the Hakim integration + + + Learn more about Hakim's speech services + + + Create and manage your Hakim API keys from the dashboard (Settings -> API keys) + + + +## Installation + +This is a community-maintained package distributed separately from `pipecat-ai`, +built and maintained by the Hakim team. It is not yet published to PyPI, so install +it directly from GitHub: + +```bash +uv pip install git+https://github.com/tryHakimAI/hakim-pipecat.git +``` + +## Prerequisites + +### Hakim Account Setup + +Before using the Hakim TTS service, you need: + +1. **Hakim Account**: Sign up at [tryhakim.ai](https://tryhakim.ai) +2. **API Key**: Generate a key (format: `hk_live_...`) from the dashboard + (Settings -> API keys), with the `tts:write` scope +3. **A voice**: pick a voice id or slug from the dashboard's Voices page + +### Required Environment Variables + +- `HAKIM_API_KEY`: Your Hakim API key. Falls back to this environment variable if + `api_key` is not passed to the constructor. + +## Configuration + + + Hakim voice id or slug. Required -- there is no bundled default voice. + + + + Hakim API key. Falls back to the `HAKIM_API_KEY` environment variable if not + provided. + + + + One of `"hakim-fast-v1"` (sub-120ms TTFB), `"hakim-v2"` (higher quality + + non-verbal tags), or `"hakim-v3"` (adds free-form `voice_prompt` control). + + + + Classifier-free-guidance weight, `0.0`-`10.0`. + + + + Free-form voice-character description. Only honoured on `model="hakim-v3"` -- + dropped elsewhere. + + + + Pins the session to a specific regional endpoint. One of `"auto"`, `"de"`, + `"uae"`, or `"ksa"`. + + + + Overrides the region table entirely (staging / self-hosted). Takes precedence + over `region`. + + + + Runtime-updatable settings. See [Settings](#settings) below. + + +### Settings + +Runtime-updatable configuration passed via the `settings` constructor argument +using `HakimTTSService.Settings(...)`. + +| Parameter | Type | Default | Description | +| -------------- | ------- | ------- | ------------------------------------------------------------------------------------ | +| `cfg` | `float` | `3.0` | Classifier-free-guidance weight, `0.0`-`10.0`. | +| `voice_prompt` | `str` | `None` | Free-form voice-character description. Only honoured on `model="hakim-v3"`. | + + + See the [source + repository](https://github.com/tryHakimAI/hakim-pipecat) for the + authoritative, up-to-date configuration options. + + +## Usage + +```python +import os +from pipecat.pipeline.pipeline import Pipeline +from hakim_pipecat import HakimTTSService + +tts = HakimTTSService( + api_key=os.getenv("HAKIM_API_KEY"), + voice="your-voice-id", +) + +pipeline = Pipeline([ + transport.input(), # audio/user input + stt, # speech to text + context_aggregator.user(), # add user text to context + llm, # LLM generates response + tts, # Hakim TTS synthesis + transport.output(), # stream audio back to user + context_aggregator.assistant(), # store assistant response +]) +``` + +## Compatibility + +Tested with Pipecat v1.5.0. Check the [source +repository](https://github.com/tryHakimAI/hakim-pipecat) for the latest tested +version and changelog. diff --git a/docs.json b/docs.json index b91ee717..5eb257e1 100644 --- a/docs.json +++ b/docs.json @@ -364,6 +364,7 @@ "api-reference/server/services/stt/google", "api-reference/server/services/stt/gradium", "api-reference/server/services/stt/groq", + "api-reference/server/services/stt/hakim", "api-reference/server/services/stt/mistral", "api-reference/server/services/stt/moonshine", "api-reference/server/services/stt/nvidia", @@ -427,6 +428,7 @@ "api-reference/server/services/tts/google", "api-reference/server/services/tts/gradium", "api-reference/server/services/tts/groq", + "api-reference/server/services/tts/hakim", "api-reference/server/services/tts/hume", "api-reference/server/services/tts/inworld", "api-reference/server/services/tts/kokoro", @@ -1863,6 +1865,10 @@ "source": "/server/services/stt/groq", "destination": "/api-reference/server/services/stt/groq" }, + { + "source": "/server/services/stt/hakim", + "destination": "/api-reference/server/services/stt/hakim" + }, { "source": "/server/services/stt/nvidia", "destination": "/api-reference/server/services/stt/nvidia" @@ -2019,6 +2025,10 @@ "source": "/server/services/tts/groq", "destination": "/api-reference/server/services/tts/groq" }, + { + "source": "/server/services/tts/hakim", + "destination": "/api-reference/server/services/tts/hakim" + }, { "source": "/server/services/tts/hume", "destination": "/api-reference/server/services/tts/hume"