# Quran – Arabic, English & Audio (`badruddeen/quran---arabic-english-audio`) Actor Explore the Quran: read Arabic (Uthmani), follow Sahih International English translation, and listen to high-quality audio recitations via web or API (MCP Server). - **URL**: https://apify.com/badruddeen/quran---arabic-english-audio.md - **Developed by:** [Badruddeen Naseem](https://apify.com/badruddeen) (community) - **Categories:** Other, MCP servers - **Stats:** 8 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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: ````json { "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: ```json { "content": "verse", "reference": "2:255", "reciter": "ar.alafasy" } ``` - Full chapter: ```json { "content": "surah", "reference": "112", "reciter": "ar.husary" } ``` - Full part (Juz): ```json { "content": "juz", "reference": "1", "reciter": "ar.minshawi" } ``` - Random verse: ```json { "content": "random", "reference": "", "reciter": "ar.alafasy" } ``` Keyword search (English only): ```json { "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: [![Donate via PayPal](https://img.shields.io/badge/Donate-PayPal-FFD140?style=for-the-badge\&logo=paypal\&logoColor=005EA6)](https://www.paypal.com/ncp/payment/DM5SGXQ22Y2Y8) 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 🙏 # Actor input Schema ## `safeMode` (type: `boolean`): Enable to run a small sample fetch for testing. Recommended for first run or automated tests. Turn OFF to fetch real data. ## `content` (type: `string`): Select the type of Quran content: • Single verse (Ayah) • Full chapter (Surah) • Full part (Juz) • Random verse • Search whole Quran by English keyword ## `reference` (type: `string`): Enter based on selection: • Single verse: e.g., 2:255 • Full chapter: Surah number 1–114 • Full part: Juz number 1–30 • Random: leave empty • Search: English keyword or phrase (e.g. 'mercy', 'wealth') Note: Arabic keyword search is not supported yet. ## `reciter` (type: `string`): Choose a beautiful voice for the audio recitation. All options are high-quality and widely loved. (Used only in non-search modes) ## Actor input object example ```json { "safeMode": true, "content": "verse", "reciter": "ar.alafasy" } ``` # Actor output Schema ## `ayahs` (type: `string`): No description ## `playlist` (type: `string`): Open to listen continuously to all fetched ayahs # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("badruddeen/quran---arabic-english-audio").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("badruddeen/quran---arabic-english-audio").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call badruddeen/quran---arabic-english-audio --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=badruddeen/quran---arabic-english-audio", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/0hIj1wXptEvxbFC9v/builds/SNXipHfPV3zZDtPmi/openapi.json