Metadata-Version: 2.4
Name: sawalign
Version: 0.1.2
Summary: Align a transcript to an audio recording 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: forced-alignment,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

# Sawalign

**Multilingual forced alignment for word timestamps and subtitles.**

Give Sawalign an audio recording and its transcript. Get word timings and SRT captions for subtitle editors, audio players and speech datasets.

Built by [Omneity Labs](https://www.omneitylabs.com), powered by [Sawtone](https://www.omneitylabs.com/models/sawtone), and available through [Sawalni API](https://api.sawalni.com).

## Quick start

```sh
pip install sawalign
```

[Create a Sawalni API key](https://api.sawalni.com), enable alignment access, then set it in your terminal. API requests use credits.

```sh
export SAWALNI_API_KEY="your-key"
sawalign align interview.wav --text transcript.txt --output captions.srt
```

Use your own audio recording and a transcript that matches what is spoken. The package calls the hosted API; it does not download model weights or run the engine locally.

## Languages and scripts

**100+ core languages, with extended compatibility across 400+ languages.** Built on [Sawtone](https://www.omneitylabs.com/models/sawtone), Sawalign works across languages and scripts, including Moroccan Arabic (Darija) and Amazigh, including Tachelhit. Workflows can span Arabic, Latin and Tifinagh scripts.

Use a transcript that matches the speech, including language switches. For Latin-script Darija (often called Arabizi), keep spelling consistent and review the resulting word timings. There is no need to translate it into English. Alignment quality can vary by language, accent and audio quality, particularly beyond the core languages.

## Python

```python
from pathlib import Path
from sawalign import Sawalign

text = Path("transcript.txt").read_text(encoding="utf-8")

with Sawalign() as client:
    job = client.submit("interview.wav", text)
    print(job["job_id"])  # Save this ID to resume without another upload.
    result = client.wait(job["job_id"])
    words = result.get("words_so_far", [])
    Path("captions.srt").write_text(
        client.srt(job["job_id"]), encoding="utf-8"
    )
```

The same call accepts a Darija, Amazigh, Arabic, French or other matching transcript. The client has no language selector; it sends your text as supplied.

## Where it fits

- **Subtitles:** time an edited transcript and export SRT.
- **Audio players:** use word timestamps to highlight the text as speech plays.
- **Speech datasets:** attach word boundaries to an existing transcript.

```text
Audio recording ──┐
                  ├── Sawalign API ── Job ID ── Word timings / SRT
Reviewed text ────┘
```

Sawalign aligns the words you supply. Need a transcript in Darija, Amazigh or other major languages? Check out [Daktilo](https://pypi.org/project/daktilo/), then review its transcript before alignment. The [Python and TypeScript starter](https://github.com/omneity-labs/starter-transcription) includes this workflow and a real Darija demo with saved text and timings.

## Submit now, retrieve later

```sh
sawalign submit interview.wav --text transcript.txt
sawalign status JOB_ID
sawalign wait JOB_ID
sawalign srt JOB_ID > captions.srt
```

A job ID lets you resume polling after a terminal disconnect or a client timeout. It avoids uploading the same audio recording again.

## Client reference

| Method | Result |
| --- | --- |
| `submit(audio, text)` | Upload once; return the job ID and state. |
| `status(job_id)` | Current state and available word timings. |
| `wait(job_id, timeout=600, poll_interval=2)` | Wait for completion; return the final job. |
| `srt(job_id)` | SRT captions as a string. |
| `align(audio, text)` | Submit and wait in one call. |

`AlignmentTimeout.job_id` lets you resume a timed-out wait. `AlignmentFailed.job` contains the terminal response. HTTP errors use `httpx.HTTPStatusError`; transport errors use `httpx.RequestError`. Uploads are not retried automatically. After an uncertain upload, check the service before submitting again.

Audio recording limit: 128 MiB. Transcript limit: 1,000,000 UTF-8 bytes. Keep the API key in a server environment.

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

Python 3.10 or later. MIT license.
