wmj2024
cd35b46393
- Added VOICE_QUALITY ratings for all engines (naturalness/calmness) - Azure SSML now uses mstts:express-as style="calm" for human-like delivery - Added --list-engines with quality rankings - Added --quality-check for A/B sample comparison - Updated README with quality-first guidance - Warns against Piper for production (robotic-ish) - Recommends Azure AriaNeural or ElevenLabs Rachel
104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# FalahMobile Content Repository
|
|
|
|
Micro-learning courses for the FalahMobile Islamic lifestyle app.
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
falahmobile-content/
|
|
├── courses/ # All courses
|
|
│ ├── daily-fiqh-beginner/
|
|
│ ├── 40-hadith-nawawi/
|
|
│ └── tafsir-bites/
|
|
├── assets/ # Shared images, fonts, icons
|
|
├── scripts/ # Build and generation scripts
|
|
│ ├── generate-audio.py # TTS pipeline
|
|
│ └── validate-content.mjs # Content quality checks
|
|
├── templates/ # Lesson and course templates
|
|
└── README.md
|
|
```
|
|
|
|
## Content Format
|
|
|
|
Every lesson is a Markdown file with YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
id: "course-module-lesson"
|
|
title: "Lesson Title"
|
|
course: "Course Name"
|
|
module: "Module Name"
|
|
order: 1
|
|
read_time: "3 min"
|
|
difficulty: "beginner"
|
|
tags: ["fiqh", "prayer"]
|
|
source_refs: ["Quran 5:6", "Sahih Muslim 271"]
|
|
audio_ready: true
|
|
---
|
|
```
|
|
|
|
## Audio Pipeline
|
|
|
|
### ⚠️ Quality First — No Robot Voices
|
|
|
|
FalahMobile learners expect warm, natural, human-like audio. We specifically avoid the "Stephen Hawking" robotic sound of old TTS systems.
|
|
|
|
### Quality Rankings (Naturalness / Calmness)
|
|
|
|
| Service | Voice | Naturalness | Free Tier | Setup |
|
|
|---------|-------|-------------|-----------|-------|
|
|
| **ElevenLabs** ★ | `Rachel` | 9.5/10 | 10K chars/mo | API key |
|
|
| **Azure Speech** ★ | `en-US-AriaNeural` | 9.0/10 | 500K chars/mo | Azure account |
|
|
| **Google Cloud** | `en-US-Neural2-F` | 8.0/10 | 1M chars/mo | GCP account |
|
|
| **Piper TTS** | `amy` | 6.5/10 | Unlimited | Local download |
|
|
|
|
> **Recommendation**: Use **Azure AriaNeural** or **ElevenLabs Rachel** for production. Piper is acceptable for testing but sounds noticeably synthetic.
|
|
|
|
### Generate Audio
|
|
|
|
```bash
|
|
# See all engines with quality ratings
|
|
python scripts/generate-audio.py --list-engines
|
|
|
|
# Compare quality with a sample (generates test files)
|
|
python scripts/generate-audio.py --quality-check
|
|
|
|
# Using Azure (recommended — human-like, calm female)
|
|
python scripts/generate-audio.py --course daily-fiqh-beginner --engine azure --voice en-US-AriaNeural
|
|
|
|
# Using ElevenLabs (best quality, limited free tier)
|
|
export ELEVENLABS_API_KEY="your-key"
|
|
python scripts/generate-audio.py --course daily-fiqh-beginner --engine elevenlabs --voice Rachel
|
|
|
|
# Using Piper (free, local, acceptable for testing)
|
|
python scripts/generate-audio.py --course daily-fiqh-beginner --engine piper --voice amy
|
|
```
|
|
|
|
### SSML Settings for Natural Delivery
|
|
|
|
The script uses Azure's **calm expressive style** with gentle prosody:
|
|
- `rate="-5%"` — slightly slower than normal speech
|
|
- `pitch="-2%"` — slightly deeper, more grounded
|
|
- `mstts:express-as style="calm"` — warm, meditative tone
|
|
|
|
This is tuned for religious/reflective content. Not robotic. Not rushed. Human.
|
|
|
|
## Gitea Integration
|
|
|
|
Push content to your Gitea instance:
|
|
|
|
```bash
|
|
git remote add gitea https://your-gitea.com/user/falahmobile-content.git
|
|
git push gitea main
|
|
```
|
|
|
|
The FalahMobile app fetches content via the Gitea API or raw file URLs.
|
|
|
|
## Adding a New Course
|
|
|
|
1. Create `courses/<course-id>/manifest.json`
|
|
2. Create module directories with lesson `.md` files
|
|
3. Run `python scripts/validate-content.mjs`
|
|
4. Generate audio with `python scripts/generate-audio.py`
|
|
5. Commit and push to Gitea
|