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:

   textCopy

   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:

   textCopy

   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:

   jsonCopy

   {
     "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:

{
  "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, alignment requests, job results and clip downloads.