Mopidy-Mp3Quran

Mopidy extension for streaming Quran recitations and radio stations from Mp3Quran.

Features

• Browse and stream Quran recitations from 100+ reciters
• Listen to Quran radio stations
• Search reciters by name or recitation style (Riwaya)
• Configurable language, cache TTL, and request timeout
• Caching to reduce API calls

Installation

From PyPI:

pip install Mopidy-Mp3Quran

From source:

git clone https://github.com/aymanbagabas/mopidy-mp3quran.git
cd mopidy-mp3quran && pip install .

Configuration

By default, this extension is enabled. Modify the Mopidy configuration file to customize:

[mp3quran]
enabled = true
language = english
cache_ttl = 3600
timeout = 10

Configuration options:

• language - API language (default: English). Controls the language of reciter and surah names. Accepts both the full name (e.g. English, arabic) and the locale code (e.g. eng, ar), case-insensitive.

Supported languages:

• cache_ttl - Cache time-to-live in seconds (default: 3600). Set to 0 to disable caching.
• timeout - HTTP request timeout in seconds (default: 10).

Usage

Browse the library tree:

1. Mp3Quran (root) — top-level entry
2. Languages — switch to a different language
3. Reciters — list of all available reciters
4. Radios — list of all radio stations
5. Select a reciter to see their recitation versions (Moshaf, e.g. Hafs, Warsh)
6. Select a moshaf to see its available surahs
7. Select a surah to play it

Use search to find reciters or radio stations by name.

Development

git clone https://github.com/aymanbagabas/mopidy-mp3quran.git
cd mopidy-mp3quran
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the test suite:

pytest

Docker

Run with Docker Compose (includes Mopidy + Snapcast server):

docker compose up

This starts a single container with Mopidy and Snapcast server. Mopidy outputs audio to a named pipe that Snapcast reads from.

Configuration files are in docker/mopidy.conf and docker/snapserver.conf.

Project resources

• Source code
• Issue tracker

Changelog

v0.2.1 (2026-04-28)

• Support fuzzy search for reciters, surahs, radios, and moshafs

v0.2.0 (2026-04-26)

• Migrate to mp3quran.net v3 REST API
• Support multiple moshaf (recitation versions) per reciter
• Add riwayat (narration types) support
• Language config now accepts both full names and locale codes (case-insensitive)
• Migrate to pyproject.toml with src layout
• Migrate to Mopidy 4.x API (search on LibraryProvider)
• Fix proxy configuration bug (config key)
• Fix search dropping reciter results
• Add unit test suite (102 tests)
• Remove dead parse_uri() function
• Migrate to Python 3
• Add error handling for all API calls
• Add caching with configurable TTL
• Add search functionality
• Add configuration options (language, cache_ttl, timeout)
• Add type hints and docstrings
• Improve error handling in URI parsing and lookup

v0.1.0 (2018-03-05)

• Initial release.