Resources Tools Docs FAQ CMS

Tutorial 1: Recitation End-to-End

This tutorial is for users who want to download recitation data and build a minimal synced playback experience.

1) What This Resource Is

Recitation resources provide Quran audio and related timing metadata.

Depending on the selected package, you can get:

  • Surah-by-surah audio (gapless playback)
  • Ayah-by-ayah audio (gapped playback)
  • Segment timing arrays used for synchronized word or ayah highlighting

Primary category:

2) When to Use It

Use recitation data when you are building:

  • Quran audio players
  • Memorization or revision tools
  • Reading experiences that sync highlights to playback

3) How to Get Your First Example Resource

  1. Open https://qul.tarteel.ai/resources/recitation.
  2. Open the first published card in the default page order.
  3. Confirm the resource detail page includes:
    • A Recitation preview tab
    • A Help tab with segment format examples
  4. Download the available file format (JSON, SQLite, or both).

This avoids hardcoding a resource ID while keeping onboarding concrete.

4) What the Preview Shows (Website-Aligned)

On the recitation detail page, the preview helps you validate usability before download:

  • Recitation tab:
    • Jump-to-ayah selector
    • Previous/next ayah navigation
    • Audio player with timing-driven highlighting behavior
  • Help tab:
    • Difference between surah-by-surah and ayah-by-ayah data
    • Segment/timestamp sample formats for integration

Practical meaning:

  • If segment arrays are present, you can build synchronized highlighting.
  • If segment arrays are absent, treat the resource as audio-only playback.

5) Download and Use (Step-by-Step)

  1. Download your selected recitation package.
  2. Inspect fields before integration:
    • Ayah identity fields (surah, ayah, or surah:ayah)
    • Timing fields (segments, timestamp_from, timestamp_to) when provided
    • Audio pointer field (audio_url or equivalent)
  3. Normalize to a consistent key in your app.
  4. Join recitation rows with Quran text rows using the same ayah key.
  5. Build a minimal player loop.
  6. Test with at least one full surah.

Starter integration snippet (JavaScript):

JavaScript
// Convert mixed source fields into one stable key format (e.g., "2:255").
const normalizeAyahKey = (row) => {
  if (row.ayah_key) return row.ayah_key;
  return `${row.surah}:${row.ayah}`;
};

// Build a quick lookup so playback can find timing/audio by ayah key.
const buildTimingIndex = (recitationRows) => {
  return recitationRows.reduce((index, row) => {
    const key = normalizeAyahKey(row);
    index[key] = {
      audioUrl: row.audio_url,
      from: row.timestamp_from,
      to: row.timestamp_to,
      segments: Array.isArray(row.segments) ? row.segments : []
    };
    return index;
  }, {});
};

// Merge Quran text rows with recitation timing rows for display + sync.
const joinTextWithTiming = (scriptRows, timingIndex) => {
  return scriptRows
    .map((row) => {
      const ayahKey = `${row.surah}:${row.ayah}`;
      return { ...row, ayahKey, timing: timingIndex[ayahKey] || null };
    })
    // Keep only rows we can actually sync.
    .filter((row) => row.timing);
};

6) Real-World Example: Play One Surah with Live Ayah Highlighting

Goal:

  • User plays a surah and sees the currently recited ayah highlighted in real time.

Inputs:

  • Recitation resource (audio + timings when available)
  • Quran Script resource (ayah text)

Processing:

  1. User selects a surah.
  2. App loads surah text from Quran Script.
  3. App loads matching recitation timing map for the same surah.
  4. On each player time update, app finds the active ayah time window.
  5. UI updates highlight state for that ayah.

Expected output:

  • Audio playback is smooth.
  • Highlight transitions follow recitation timing.
  • Ayah text and audio stay mapped by the same ayah key.

Interactive preview (temporary sandbox):

You can edit this code for testing. Edits are not saved and may not persist after refresh.

JavaScript Playground
Editor
Preview

7) Common Mistakes to Avoid

  • Assuming all recitations include segments.
  • Mixing key formats without normalization.
  • Joining recitation to text using row order instead of ayah identity.
  • Treating preview success for one ayah as proof that whole-surah mapping is correct.

8) When to Request Updates or Changes

Open an issue if you find:

  • Broken or inaccessible audio file links
  • Segment/timestamp values that do not match audible recitation
  • Missing ayah mappings in downloaded files
  • Inconsistent reciter or package metadata

Issue tracker:

Related Docs