docs: clarify word audio vs recitation audio usage

apps/docs/content/docs/audio.mdx

@@ -3,7 +3,15 @@ title: Audio API
 description: Access Quran audio recitations from different reciters.
 ---
 
-The Audio API provides access to audio recitations including chapter audio and verse-by-verse audio with timing.
+The Audio API provides access to recitation audio from the authenticated Content API, including chapter audio and verse-by-verse audio with optional timing data.
+
+## Choose the Right Audio Source
+
+| Use case | Fetch from | Returned shape | Notes |
+| --- | --- | --- | --- |
+| Single-word pronunciation | `word.audioUrl` from the [Verses API](./verses) | Relative `wbw/...` asset path | Resolve it against `https://audio.qurancdn.com/` before playing it in the browser. |
+| Chapter playback | `client.audio.findAllChapterRecitations()` or `client.audio.findChapterRecitationById()` | Full chapter `audioUrl` | Use this for continuous chapter playback. |
+| Ayah playback with timing | `client.audio.findVerseRecitationsByChapter()` or `client.audio.findVerseRecitationsByKey()` | Verse recitation `url` plus optional `segments` | Use this for ayah recitations and highlighting. This is distinct from `word.audioUrl`. |
 
 ## Chapter Recitations
 
@@ -61,6 +69,8 @@ audioFiles.forEach((audio) => {
   name="VerseRecitation"
 />
 
+`segments` provide word-level timing inside the recitation for highlighting and seek. They do not change how `word.audioUrl` works.
+
 ### By Verse Key
 
 ```ts

apps/docs/content/docs/index.mdx

@@ -23,6 +23,8 @@ bun add @quranjs/api
 
 ## Quick Start
 
+> Note: The SDK can run in browser code, but keep `clientSecret` on your server and make authenticated Content API calls from a backend or server-side runtime. Public word-by-word audio playback uses the separate `word.audioUrl` asset path described in the [Verses API](./verses).
+
 ```ts
 import { Language, QuranClient } from "@quranjs/api";
 

apps/docs/content/docs/resources.mdx

@@ -187,9 +187,9 @@ console.log(styles.mujawwad);  // Mujawwad reciters
 ```ts
 const media = await client.resources.findVerseMedia();
 
-console.log(media.unicode); // Font URL
-console.log(media.image);   // Images base URL
-console.log(media.audio);   // Audio base URL
+console.log(media.name);         // Resource name
+console.log(media.authorName);   // Author or curator
+console.log(media.languageName); // Associated language
 ```
 
 ### VerseMediaResource Type

apps/docs/content/docs/verses.mdx

@@ -43,6 +43,30 @@ const verse = await client.verses.findByKey("1:1", {
 });
 ```
 
+Requesting `words: true` can include `word.audioUrl` for each word. That value is a relative word-by-word asset path such as `wbw/001_001_001.mp3`, not a `/content/api/v4/...` endpoint.
+
+### Word Audio Paths
+
+```ts
+const verse = await client.verses.findByKey("1:1", {
+  words: true,
+  wordFields: {
+    audio: true,
+    location: true,
+  },
+});
+
+const firstWord = verse.words?.[0];
+const wordAudioUrl = firstWord
+  ? new URL(
+      firstWord.audioUrl.replace(/^\/+/, ""),
+      "https://audio.qurancdn.com/",
+    ).toString()
+  : null;
+```
+
+Use `word.audioUrl` for single-word pronunciation playback. For chapter or ayah recitations, and for timing `segments`, use the [Audio API](./audio) instead.
+
 ### With Tafsir
 
 ```ts
@@ -104,10 +128,11 @@ const random = await client.verses.findRandom({
 const verse = await client.verses.findByKey("1:1", {
   words: true,
   wordFields: {
+    audio: true,
     textUthmani: true,
     transliteration: true,
     translation: true,
-    audio: true,
+    location: true,
   },
 });
 ```

packages/api/src/types/api/Word.ts

@@ -13,7 +13,7 @@ export enum CharType {
 export interface Word {
   id?: number;
   position: number;
-  audioUrl: string;
+  audioUrl: string; // Relative word-by-word audio path, e.g. wbw/001_001_001.mp3
   charTypeName: CharType;
   codeV1?: string;
   codeV2?: string;