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

# Haystack

> Use Lokutor text-to-speech and speech-to-text as components in Haystack 2.x pipelines.

`lokutor-haystack` adds two [Haystack](https://haystack.deepset.ai) components: `LokutorTextToSpeech` and `LokutorSpeechToText`. Source: [lokutor-ai/lokutor-haystack](https://github.com/lokutor-ai/lokutor-haystack) (Apache-2.0).

## Install

The package is not on PyPI yet. Until it is:

```bash theme={null}
pip install lokutor-haystack
export LOKUTOR_API_KEY=your_key
```

The key is a Haystack `Secret` read from `LOKUTOR_API_KEY`, so it is never written into a serialized pipeline.

## Text to speech

```python theme={null}
from pathlib import Path
from haystack_integrations.components.audio.lokutor import LokutorTextToSpeech

tts = LokutorTextToSpeech(voice="F1", language="en")
audio = tts.run(text="Hello from Lokutor.")["audio"]  # ByteStream, audio/wav
audio.to_file(Path("hello.wav"))
```

Calls `POST /v1/tts/synthesize`. `voice` is `F1`-`F5`, `M1`-`M5` or a clone id; `language` is an ISO code (pass it for predictable results). `run` accepts `voice` and `language` overrides, and `run_async` exists. Limits are those of the [REST API](https://docs.lokutor.com/api-reference/rest.md): 5,000 characters per call, WAV output (16-bit PCM, 44.1 kHz, mono).

## Speech to text

```python theme={null}
from haystack_integrations.components.audio.lokutor import LokutorSpeechToText

stt = LokutorSpeechToText(language="en", diarize=True)
docs = stt.run(sources=["meeting.wav"])["documents"]
print(docs[0].content, docs[0].meta["speakers"])
```

Calls `POST /v1/speech-to-text`. `sources` are file paths or `ByteStream`s and the output is one `Document` per source. **Lokutor decodes WAV only**: convert other formats first. `meta` carries `file_path`, `language_code`, and, with `diarize=True`, `speakers`; with `include_words=True` the per-word timings in `words`. An unreadable file is logged and skipped; an API error raises `RuntimeError` with Lokutor's message.

## Pipeline example

```python theme={null}
from haystack import Pipeline
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore

store = InMemoryDocumentStore()
indexing = Pipeline()
indexing.add_component("stt", LokutorSpeechToText(language="en"))
indexing.add_component("writer", DocumentWriter(document_store=store))
indexing.connect("stt.documents", "writer.documents")
indexing.run({"stt": {"sources": ["call.wav"]}})
```

## What was tested

Unit tests with a mocked HTTP layer on haystack-ai 2.10.0 and 3.4.1, and one live round trip (a short sentence synthesized, then transcribed) against `api.lokutor.com`. Not run: non-English languages, diarization against the live API, `run_async` against the live API, or any real-world pipeline beyond the example above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.