Developer example · Python + TypeScript
From Darija audio to reviewed, timed captions
Transcribe an audio recording with Daktilo, review the words, then export word timings and SRT captions with Sawalign.
Resources
Listen. Then read the captions.
5.6 seconds · 17 words · 3 cuesAudio-only player and downloadable assets
This is a saved result, not a live request. The words and timings are excerpts from Daktilo and Sawalign output for a longer audio recording. They are not a separate response for this short file. A new request can return a different result.
A transcript is not yet a subtitle file.
For developers building interview tools, media archives or caption editors, this workflow separates three jobs: recognize the speech, review the text, then place the words in time. It is the transcription and timing workflow behind Sawtitles.
- 01Audio recording
- 02Daktilo → draft text
- 03Human review
- 04Sawalign → word times
- 05SRT captions
Send the audio recording to Daktilo transcription. Review the returned words. Send the reviewed text and the same audio recording to Sawalign alignment. Poll the job, then download the SRT. Alignment times the text you supply; it does not correct recognition errors.
Review the words before timing them.
Recognized transcript
وفي نفس الوقت قلنا نصوروا في هذا المنظر هذا هنايا مع البرد والاجواء شوية استوائية بالنسبة لينا
Reviewed transcript
وفي نفس الوقت قلنا نصوروا في هذا المنظر هذا هنايا، مع البرد والاجواء شوية استوائية بالنسبة لينا.
Here, the review adds punctuation and a line break. The recognized words stay the same. For your audio recording, also check names, omitted words, language switches and warnings before alignment.
Inspect the word times and SRT.
Each word has a start and end time in seconds relative to the excerpt. SRT groups these words into readable cues. Check both timing and line breaks before publishing.
| Word | Start | End |
|---|---|---|
| وفي | 0.051 | 0.251 |
| نفس | 0.271 | 0.431 |
| الوقت | 0.431 | 0.771 |
| قلنا | 0.992 | 1.212 |
| نصوروا | 1.232 | 1.532 |
| في | 1.572 | 1.612 |
| هذا | 1.612 | 1.712 |
| المنظر | 1.712 | 2.433 |
| هذا | 2.433 | 2.593 |
| هنايا | 2.613 | 2.913 |
| مع | 3.013 | 3.093 |
| البرد | 3.093 | 3.454 |
| والاجواء | 3.474 | 4.134 |
| شوية | 4.174 | 4.334 |
| استوائية | 4.334 | 4.835 |
| بالنسبة | 4.875 | 5.195 |
| لينا | 5.235 | 5.435 |
captions.srt
1
00:00:00,051 --> 00:00:01,212
وفي نفس الوقت قلنا
2
00:00:01,232 --> 00:00:02,913
نصوروا في هذا المنظر هذا هنايا
3
00:00:03,013 --> 00:00:05,435
مع البرد والاجواء شوية استوائية بالنسبة ليناRun it with your own audio or video.
Use Python 3.11+ and FFmpeg on PATH on macOS or Linux, or a compatible shell on Windows. You need a Sawalni account, an API key, enabled access for transcription and alignment, and enough API credits. The packages call the hosted API; they do not run models locally.
Create an API key · Check model access · Check credits. Keep the key in your terminal or server environment. Do not put it in browser code or commit it.
Start with audio or video
Pass a local WAV, MP3, M4A, FLAC, OGG, MP4, MOV, MKV or WebM file. Decoder support depends on your FFmpeg installation. Both starters extract the first audio track locally and prepare mono 16 kHz WAV for the API. Only the prepared audio is uploaded. The original file stays unchanged.
Use the same unchanged media file for both steps. The starter preserves an initial audio delay so captions follow the video timeline. Temporary audio is removed after success or failure. A forced process kill can leave temporary files. Files with no audio track stop before an API request. If you need another track, select it with FFmpeg first.
1. Set up the pinned starter
git clone https://github.com/omneity-labs/starter-transcription.git
cd starter-transcription
git checkout ee6b981
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r python/requirements.txt
export SAWALNI_API_KEY="your-key"
# Install FFmpeg and check that it is on PATH.
ffmpeg -version
# Replace this path with your own audio or video file.
MEDIA="/absolute/path/to/interview.mp4"The starter pins daktilo 0.1.1 and sawalign 0.1.2. Replace “your-key” and the media path. Run the following commands in the same terminal. The scripts do not load .env automatically.
2. Transcribe, then review
python python/src/main.py transcribe "$MEDIA" --transcript-output transcript.txtOpen transcript.txt in your text editor. Correct the words to match the audio recording. Save the file in UTF-8.
3. Align the reviewed text
python python/src/main.py align "$MEDIA" --text transcript.txt --output captions.srtWhen the alignment job completes, open captions.srt in your caption editor or load it as a subtitle track in your media player. Check cue timing against the same audio recording.
Prefer TypeScript?
Use Node 24+ and FFmpeg on PATH. From the starter root, set your key and media path, then:
cd typescript
npm ci
export SAWALNI_API_KEY="your-key"
MEDIA="/absolute/path/to/interview.mp4"
npm start -- transcribe "$MEDIA" --transcript-output transcript.txtReview transcript.txt, then run:
npm start -- align "$MEDIA" transcript.txt captions.srtAlready have a reviewed transcript?
python python/src/main.py align "$MEDIA" --text transcript.txt --output captions.srtUse the setup above, then replace the media and transcript paths with your files. This starter command also accepts video. Transcription is optional when you already have text that matches the audio recording.
What the starter calls
| Step | API request |
|---|---|
| Transcribe | POST /v1/speech/transcribe |
| Submit alignment | POST /v1/speech/align |
| Poll status | GET /v1/speech/align/job/{job_id} |
| Download captions | GET /v1/speech/align/job/{job_id}/srt |
Python uses Daktilo 0.1.1 and Sawalign 0.1.2. TypeScript calls the same endpoints directly. See the API reference, public OpenAPI contract and runnable source at commit ee6b981.
Darija, Amazigh and script choices
This example is Moroccan Arabic (Darija) in Arabic script. It is not a multilingual accuracy test. Sawalign supports 100+ core languages, with extended compatibility across 400+ languages. It is built on Sawtone. Alignment quality varies by language, accent and audio quality, especially beyond the core languages.
For Amazigh varieties such as Tachelhit, leave Daktilo’s language hint unset for automatic selection. A forced shi hint is not accepted. Accepted hints are ar, ary, en, fr, es, de, it, pt, zh, ja, ko, ru, tr, nl.
A language or variety is different from a writing system. Arabic script, Latin script and Tifinagh are script choices. Arabizi is Latin-script Darija. A transcription hint does not select an output script. For alignment, supply text that matches the speech, keep spelling consistent, and review the word timings. Script conversion and translation are separate steps.
Before using a longer audio recording
- The prepared audio must be at most 128 MiB and 30 minutes. This upload limit applies to extracted audio, not to the video file size. The starter rejects longer media instead of silently shortening it. Conversion has a five-minute timeout. Split longer media first. The Python starter limits transcript input to 1,000,000 UTF-8 bytes.
- The starter stops on empty or truncated transcripts, HTTP errors and failed alignment jobs. Check warnings before continuing.
- Requests are not automatically retried. Alignment polling stops after ten minutes and reports the job ID. Check the job before submitting it again.
- For missing access or insufficient credits, check model access and billing in the portal before retrying.
Source, reuse and next steps
The audio, transcript, word times and captions above retain the Wikitongues source attribution. The demo source and license explain the excerpt mapping. The starter code is MIT licensed; the media adaptation is CC BY-SA 4.0.
To translate reviewed text, start with the Tarjamli translation example. For translated subtitles, see the translation extension and Tarjamli API. To inspect related building blocks, browse the API catalog.
Run it with your own audio or video ↑