Metadata-Version: 2.4
Name: sawalign
Version: 0.1.0
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Dynamic: license-file

# Sawalign

Align a reviewed transcript to an audio recording. Get word timings and SRT captions through [Sawalni API](https://api.sawalni.com/docs).

```sh
pip install sawalign
export SAWALNI_API_KEY="your-key"
```

```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"])  # Keep this ID so you can resume without uploading again.
    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")
```

Sawalign places the supplied words on the timeline. It does not transcribe the audio recording. Review the transcript before submitting it. For the full transcription workflow, see the [Python and TypeScript starter](https://github.com/omneity-labs/starter-transcription).

## Flow

```mermaid
flowchart LR
    A[Audio recording] --> C[Sawalign API]
    B[Reviewed transcript] --> C
    C --> D[Job ID]
    D --> E[Word timings]
    D --> F[SRT captions]
```

## Command line

```sh
sawalign align interview.wav --text transcript.txt --output captions.srt
```

Submit separately to keep the job ID:

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

## Client

- `submit(audio, text)` uploads once and returns the job.
- `status(job_id)` returns its current state and available words.
- `wait(job_id, timeout=600, poll_interval=2)` waits for completion.
- `srt(job_id)` retrieves SRT captions.
- `align(audio, text)` submits and waits 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. The package sends data to Sawalni; it does not run the model locally.

Python 3.10 or later. MIT license.
