Quran – Arabic, English & Audio

Read and listen to Quran verses, chapters, or parts with original Arabic text (Uthmani), Sahih International English translation, and high-quality audio recitation. Beginner-friendly with built-in input validation.

---

🕌 What This Actor Does

• Fetch a single verse (Ayah), a full chapter (Surah), a part (Juz), or a random verse.

• Provides Arabic text, English translation, and audio recitation.

• Generates a dataset and a playable HTML playlist for easy reading and listening.

• Supports keyword search (English only) — Arabic keyword search is not supported yet.

---

⚙️ Input

Field	Type	Description	Example
content	string	Select the type of Quran content to fetch: single verse, full chapter, full part, random verse, or keyword search.	"verse"
reference	string	Enter a reference depending on content. The UI provides real-time validation so invalid input is flagged immediately: • Single verse: surah:ayah (e.g., 2:255) • Full chapter: Surah number 1–114 (e.g., 112) • Full part: Juz number 1–30 (e.g., 1) • Random: leave empty • Keyword search: any English word or phrase	"2:255"
reciter	string	Choose a voice for the audio recitation. Only supported reciters are selectable: • Mishary Rashid Alafasy (ar.alafasy) • Mahmoud Khalil Al-Husary (ar.husary) • Muhammad Seddiq Al-Minshawi (ar.minshawi)	"ar.alafasy"

Note:

For single verses, the input UI validates the surah:ayah format in real time.

For full chapters (Surah) and parts (Juz), the actor checks the valid number ranges (1–114 for Surah, 1–30 for Juz) at runtime.

Random verse selection requires leaving the reference field empty.

Keyword search currently only supports English. If an Arabic keyword is entered, the actor will log an error and exit gracefully.

---

📝 Output

• Dataset (JSON) — Each row contains:

  {
    "number": 2,
    "numberInSurah": 255,
    "juz": 2,
    "page": 22,
    "surah": { "number": 2, "englishName": "Al-Baqarah", "revelationType": "Medinan" },
    "arabic": "...",
    "english": "...",
    "audio": "https://...mp3"
  }```
  

• Playlist HTML (PLAYLIST_HTML key-value) — Play all ayahs continuously in a browser with a “Play All” button.

• Summary Metadata (SUMMARY key-value) — Includes content, reference, reciter, ayahsCount, and fetchedAt.

---

🎧 How to Use

1. Provide input as described above.

2. Run the actor.

3. Access the dataset for the verses, translation, and audio links.

4. Open the PLAYLIST_HTML in a browser to play all audio in sequence.

---

⚡ Notes

• Only supported reciters are included.

• If you select a content type but do not provide a valid reference, the actor will return an error.

• Random verse selection will automatically fetch a single ayah.

• Keyword search currently works only for English. Arabic keyword input logs an error and exits gracefully.

📚 Example Inputs

• Single verse:

{
  "content": "verse",
  "reference": "2:255",
  "reciter": "ar.alafasy"
}

• Full chapter:

{
  "content": "surah",
  "reference": "112",
  "reciter": "ar.husary"
}

• Full part (Juz):

{
  "content": "juz",
  "reference": "1",
  "reciter": "ar.minshawi"
}

• Random verse:

{
  "content": "random",
  "reference": "",
  "reciter": "ar.alafasy"
}

Keyword search (English only):

{
  "content": "search",
  "reference": "mercy",
  "reciter": "ar.alafasy"
}

Arabic keywords are not supported yet. Entering an Arabic word will show a console error and exit gracefully.

---

Safe Mode (Test Mode)

This actor includes a Safe Mode toggle that is enabled by default:

• When Safe Mode is ON, the actor runs a small pre-defined sample fetch.

• Ideal for first-time users or automated tests.

• No large API calls are made.

• Returns a single sample Ayah with Arabic, English, and audio.

• When Safe Mode is OFF, the actor fetches real data based on your input selection (verse, Surah, Juz, random, or English keyword search).

Usage:

• Keep Safe Mode ON to quickly test the actor.

• Turn it OFF to fetch actual Quran content.

---

📱 Mobile Playback Note

This actor works on both desktop and mobile browsers.

However, please note:

• Some mobile browsers (especially iOS Safari and Android Chrome) restrict automatic audio sequencing.

• Arabic recitation will always play correctly.

• English translation read-aloud uses browser text-to-speech (TTS) and may behave differently depending on your device.

• On certain mobile devices, English read-aloud may not auto-chain perfectly after Arabic recitation due to browser autoplay policies.

💡 For the most stable experience on mobile, you can:

• Manually tap individual ayahs, or

• Use Arabic recitation with on-screen English reading.

We are aware of these limitations and plan to improve mobile playback in future updates.

---

🚀 Future Improvements (Planned)

If user adoption grows, future versions may include:

• 🎧 Pre-generated English MP3 audio (fully synchronized with Arabic)

• 🔊 Higher quality voice options

• ⚡ Faster search and caching

• 📖 Improved mobile playback sequencing

• 🌍 Expanded language support

---

💛 Support This Project

If you find this actor helpful and would like to support future improvements, you can contribute via PayPal:

Your support helps:

• Improve audio quality
• Add new features
• Maintain hosting and development
• Keep the project free and accessible
• Even a small contribution makes a difference 🙏