Metadata-Version: 2.4
Name: Mopidy-Mp3Quran
Version: 0.2.1
Summary: Mopidy extension for streaming Quran from mp3quran.net
Author-email: Ayman Bagabas <ayman.bagabas@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/aymanbagabas/mopidy-mp3quran
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Mopidy>=4.0
Requires-Dist: Pykka>=4.0
Requires-Dist: requests
Requires-Dist: rapidfuzz
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: responses; extra == "dev"
Dynamic: license-file

# Mopidy-Mp3Quran

[Mopidy](http://www.mopidy.com/) extension for streaming Quran recitations and radio stations from [Mp3Quran](http://www.mp3quran.net/).

## 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:

```ini
[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:**

| Locale | Language         | Native    |
| ------ | ---------------- | --------- |
| `ar`   | Arabic           | العربية   |
| `eng`  | English          | English   |
| `fr`   | French           | Français  |
| `ru`   | Russian          | Русский   |
| `de`   | German           | Deutsch   |
| `es`   | Spanish          | Español   |
| `tr`   | Turkish          | Türkçe    |
| `cn`   | Chinese          | 中文      |
| `th`   | Thai             | ไทย       |
| `ur`   | Urdu             | اردو      |
| `bn`   | Bengali          | বাংলা     |
| `bs`   | Bosnian          | Bosanski  |
| `ug`   | Uyghur           | ئۇيغۇرچە  |
| `fa`   | Persian          | فارسی     |
| `tg`   | Tajik (Cyrillic) | тоҷикӣ    |
| `ml`   | Malayalam        | മലയാളം    |
| `tl`   | Tagalog          | Tagalog   |
| `id`   | Indonesian       | Indonesia |
| `pt`   | Portuguese       | Português |
| `ha`   | Hausa            | Hausa     |
| `sw`   | Swahili          | Kiswahili |

- **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

```bash
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:

```bash
pytest
```

### Docker

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

```bash
docker compose up
```

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

| Port | Service              |
| ---- | -------------------- |
| 6600 | Mopidy MPD           |
| 6680 | Mopidy HTTP          |
| 1704 | Snapcast stream      |
| 1705 | Snapcast control     |
| 1780 | Snapcast HTTP/Web UI |

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

## Project resources

- [Source code](https://github.com/aymanbagabas/mopidy-mp3quran)
- [Issue tracker](https://github.com/aymanbagabas/mopidy-mp3quran/issues)

## 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.
