Audio API

Purpose: Read chapter and verse recitation audio data.
Use this when: You have a backend and need recitation metadata or audio file URLs.
Do not use this when: You only have frontend or mobile code with no backend.
Backend required: Yes.
Allowed runtimes: Node.js, serverless functions, workers.
Required credentials: client_id, client_secret, Content API access.
Minimal import: @quranjs/api/server.

Use @quranjs/api/server.

import { createServerClient } from "@quranjs/api/server";

const client = createServerClient({
  clientId: process.env.QF_CLIENT_ID!,
  clientSecret: process.env.QF_CLIENT_SECRET!,
});

const chapterAudio = await client.content.v4.audio.chapterRecitation.list("7");
const verseAudio = await client.content.v4.audio.verseRecitation.byKey("1:1", "7");

Choose the Right Audio Source

Use case	Fetch from	Returned shape	Notes
Single-word pronunciation	word.audioUrl from the Verses API	Relative wbw/... asset path	Resolve it against https://audio.qurancdn.com/ before playing it in the browser.
Chapter playback	client.content.v4.audio.chapterRecitation	Full chapter recitation URL	Use this for continuous chapter playback.
Ayah playback with timing	client.content.v4.audio.verseRecitation	Verse recitation URL plus optional timing metadata	Use this for ayah recitations and highlighting. This is distinct from word.audioUrl.

Common Mistake

Do not assume audio is browser-safe just because the final result is a media URL. The API request still uses server credentials.

Also do not append word.audioUrl to /content/api/v4. Word-by-word audio files are public CDN assets, not authenticated Content API endpoints.