Metadata-Version: 2.4
Name: daktilo
Version: 0.1.1
Summary: Transcribe audio recordings with Sawalni API
Author-email: Omar Kamali <omar@omneitylabs.com>
License-Expression: MIT
Project-URL: Homepage, https://api.sawalni.com
Project-URL: Documentation, https://api.sawalni.com/docs
Project-URL: Examples, https://github.com/omneity-labs/starter-transcription
Keywords: speech-to-text,darija,moroccan-arabic,amazigh,arabic,subtitles
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Dynamic: license-file

# Daktilo

**Multilingual audio transcription for Moroccan Arabic (Darija), Amazigh and major languages.**

Turn an audio recording into text with [Sawalni API](https://api.sawalni.com). Use it for interviews, voice notes or the transcript step of a caption workflow. Built by [Omneity Labs](https://www.omneitylabs.com).

## Quick start

```sh
pip install daktilo
export SAWALNI_API_KEY="your-key"
daktilo transcribe interview.wav --output transcript.txt
```

[Create an API key](https://api.sawalni.com) and enable transcription access. Requests use API credits. This package calls the hosted service; it does not run a model locally.

## Python

```python
from pathlib import Path
from daktilo import Daktilo

with Daktilo() as client:
    result = client.transcribe("interview.wav")

Path("transcript.txt").write_text(result["text"], encoding="utf-8")
print(result.get("language"))
print(result.get("warnings", []))
```

The response preserves the service's text, detected language, segments, warnings and usage when available. Review the words before using the transcript for captions or another downstream task.

## Languages

Daktilo supports Moroccan Arabic (Darija), Amazigh varieties such as Tachelhit, and major languages including Arabic, English, French, Spanish, German, Italian, Portuguese, Chinese, Japanese, Korean, Russian, Turkish and Dutch. Leave `language` unset for automatic selection, especially for Amazigh and mixed-language audio recordings.

The API currently accepts forced hints `ar`, `ary`, `en`, `fr`, `es`, `de`, `it`, `pt`, `zh`, `ja`, `ko`, `ru`, `tr` and `nl`. A forced Amazigh hint such as `shi` is not accepted; use automatic selection. Language availability does not imply the same accuracy for every variety, accent or audio recording.

```sh
daktilo transcribe interview.wav --language ary --json --output result.json
```

```python
with Daktilo() as client:
    result = client.transcribe("interview.wav", language="ary")
```

## Text and scripts

Darija audio often mixes Arabic with French or other languages. Review the returned text before publishing it or using it for subtitles. Transcription follows the speech; script conversion is a separate step. If your workflow needs Arabizi (Latin-script Darija) or Tifinagh text, handle that requirement separately rather than assuming that a language hint selects the output script.

## From transcript to timed captions

```text
Audio recording → Daktilo → Review transcript → Sawalign → SRT captions
```

Need word timings or subtitles? [Sawalign](https://pypi.org/project/sawalign/) aligns your reviewed transcript to the same audio recording. The [Python and TypeScript starter](https://github.com/omneity-labs/starter-transcription) covers the full workflow.

## Client reference

`Daktilo(api_key=None, base_url="https://api.sawalni.com/v1", timeout=300)` uses `SAWALNI_API_KEY` when no key is supplied. Use it as a context manager or call `close()`.

`transcribe(audio, language=None, model="daktilo")` accepts a local file path and returns the response dictionary. The default model follows the service's Daktilo alias. HTTP errors raise `httpx.HTTPStatusError`; connection failures raise `httpx.RequestError`. Uploads are not automatically retried.

Audio recordings must be at most 128 MiB and 30 minutes. The service validates duration. Inspect `warnings` and any segment truncation flags before downstream use. Empty recognized text can be a valid result for silence. The client preserves it.

Keep API keys in your terminal or server environment. Python 3.10 or later. MIT license.

[API reference](https://api.sawalni.com/docs) · [Runnable starter](https://github.com/omneity-labs/starter-transcription)
