hifzr

A tiny CLI to download Quran recitations by surah & reciter and generate ayah‑only playlists for hifẓ (memorization). Rust • zero config by default

Features

• Ayah‑level practice playlists (no audio editing of recitations)
• Auto‑download missing ayahs from Quran.com by surah & reciter
• Neat folders: ~/Quran_hifz/<surah-slug>/<reciter-slug>/
• Optional silence gap between repeats/ayats (uses a separate generated silent file)
• Colorful, readable CLI (respects NO_COLOR)

Design choice: this tool does not cut audio into word segments. It loops whole ayahs only, to respect tajwīd & natural phrasing.

Install

Prerequisites

• Rust toolchain (cargo) – install via https://rustup.rs
• ffmpeg

Directly

cargo install hifzr

From source

# clone your repo
git clone https://github.com/n0t-Me/hifzr && cd hifzr

# build & install locally
cargo install --path .
# now `hifzr` should be on your PATH (~/.cargo/bin)

Quick start

# 1) Explore
hifzr ls chapters | head
hifzr ls reciters | head

# 2) Download a chapter (e.g., Ya-Sin) by reciter (saved to ~/Quran_hifz)
hifzr download --chapter "ya-sin" --reciter "abdulbaset"

# 3) Build an ayah-only playlist for a range (repeats x3, 1200ms gap)
hifzr hifz --chapter ya-sin --verses 1-20 \
  --auto-download --reciter abdulbaset \
  --repeat 3 --gap-ms 1200 \
  --out ~/custom/path

You’ll get:

~/Quran_hifz/ya-sin-036/abdulbaset-…/
  001.mp3
  002.mp3
  …
  hifz_ayah.m3u
  latest_playlist.txt

Command reference

hifzr download

Download ayahs for a chapter & reciter.

hifzr download \
  --chapter <name|number> \
  --reciter <name|id> \
  [--out ~/Quran_hifz] [--force]

• Examples

  • hifzr download --chapter al-asr --reciter shuraym
  • hifzr download --chapter 36 --reciter 7

hifzr hifz

Build an ayah‑only playlist (optionally auto‑download first).

hifzr hifz \
  --chapter <name|number> \
  [--verses "1-5,7,10-12"] \
  [--auto-download --reciter <name|id> [--force]] \
  [--repeat 3] [--gap-ms 0] \
  [--out ~/Quran_hifz]

• --verses supports comma-separated single ayahs and ranges.
• --gap-ms inserts a short silence file between repeats/ayats (generated with ffmpeg).
• Output: writes hifz_ayah.m3u into the surah/reciter folder

hifzr ls

List chapters or reciters from the API.

hifzr ls chapters
hifzr ls reciters

Folder layout

~/Quran_hifz/
  <surah-slug-from-server>/
    <reciter-slug>/
      001.mp3
      002.mp3
      …
      hifz_ayah.m3u
      latest_playlist.txt

Slugs come from the server’s canonical names to avoid local naming drift.

Limitations & trade‑offs

• Ayah‑only: no word/segment slicing. This avoids choppy loops & accidental tajwīd breaks.

• API availability: relies on Quran.com’s public API. Be nice with rate limits.

• Metadata: basic tagging only. Future work may embed Islamic metadata (juz/hizb/ayah index) at the file level (ID3/MP4) for wider player support.

Credits

Quran text/audio & metadata: https://quran.com API.

Thanks to the reciters and publishers who make high‑quality recitations available.

Note: A good amount of code is generated by AI :P