---
title: "Align a recording"
description: "Align your own text or identify the verses in a Bible reading."
generated: true
---

# Align a recording

Alignment takes a recording and the text it reads, divided into sections with your own ids (paragraphs, sentences, verses), and returns when each section and each word is spoken, and a clip per section if you ask. Announcements and closing lines set apart by a pause are found and left out of the sections; wording that differs slightly from your text is tolerated.

1. Upload the audio, up to 200 MB and an hour long, as the request body:

   ```
   curl https://play.fellowverse.app/v1/uploads -H "Authorization: Bearer $KEY" \
     -H 'content-type: audio/mpeg' --data-binary @chapter.mp3
   ```

   Returns `{"id": "upl_...", "bytes": ...}`. Uploads are kept for 7 days, or a day with a test key.

2. Start the alignment:

   ```
   curl https://play.fellowverse.app/v1/alignments -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' \
     -d '{"upload": "upl_...", "clips": true,
          "segments": [{"id": "v1", "text": "..."}, {"id": "v2", "text": "..."}]}'
   ```

   The text may be up to 200,000 characters in all. Returns `202` with `{"id": "job_...", "status": "queued", "url": "/v1/jobs/job_..."}`.

3. Poll `GET /v1/jobs/{id}` until `status` is `done` or `failed`. A done alignment holds:

   ```json
   {
     "durationMs": 52689,
     "matched": 0.973,
     "speechStartMs": 9090,
     "speechEndMs": 49100,
     "droppedBefore": "Psalm 23. A Psalm by David.",
     "droppedAfter": "",
     "segments": [{ "id": "v1", "startMs": 9480, "endMs": 12260, "clip": "1.mp3" }],
     "words": [{ "text": "Yahweh", "startMs": 9480, "endMs": 9900 }]
   }
   ```

   Times are milliseconds in the file you uploaded. `matched` is the share of your text's words heard as written; below 0.5 the job fails, because the audio does not read the text.

4. Fetch clips from `GET /v1/jobs/{id}/files/{clip}`. Clips are kept for 7 days after the job finishes (a day with a test key); the job and its result stay.

## Bible readings without text

Leave out `segments` and the recording is taken for a reading of scripture: the passage is found from what is said, and its verses become the sections.

```
curl https://play.fellowverse.app/v1/alignments -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{"upload": "upl_...", "clips": true}'
```

The result adds the passage, and each section is a verse with its id, reference and text:

```json
{
  "passage": {
    "reference": "Proverbs 23:27-24:10",
    "book": "PRO",
    "bookName": "Proverbs",
    "firstChapter": 23,
    "firstVerse": 27,
    "lastChapter": 24,
    "lastVerse": 10,
    "translation": "World English Bible (public domain)"
  },
  "segments": [
    { "id": "PRO.23.27", "reference": "Proverbs 23:27", "text": "For a prostitute is a deep pit...", "startMs": 1000, "endMs": 4920, "clip": "1.mp3" }
  ]
}
```

A reading can start and end anywhere and run across chapters. A verse the recording only catches part of, at the start or end, is left out and reported in `droppedBefore` or `droppedAfter`. Only the World English Bible is held: a reading of another translation is found when enough of its wording agrees, and timed less closely. A recording that is not a reading, or that only quotes a verse, fails with the code `api_passage_unknown`; send its text as `segments` instead.

A job that fails for a reason in the request (an unreadable file, a recording over an hour, text that does not match) fails at once with that reason. One that fails on our side is tried again, up to three times. Jobs of a suspended account wait, and run when it is restored. Billed per second of audio, once, when the job is done.

See [uploads](/api/uploads), [alignment requests](/api/alignments), [job results](/api/jobs) and [clip downloads](/api/clips).