🕌 Somali Quran Audio SDK

A comprehensive Node.js SDK for accessing Somali Quran resources including recitation audio, Somali translations, and tafsir audio playlists with intelligent caching.

✨ Features

• 🎵 Quran Recitation Audio - High-quality MP3 files from Quran.com API
• 🇸🇴 Somali Translations - Complete Somali translations from QuranEnc
• 🎧 Tafsir Audio Playlists - Somali tafsir audio collections from Archive.org
• ⚡ Intelligent Caching - Built-in memory caching for optimal performance
• 🖥️ CLI Interface - Easy-to-use command-line tool
• 📱 Web Application - Complete web app example included
• 🔧 TypeScript Support - Full TypeScript definitions included
• 🚀 Production Ready - Robust error handling and logging

🚀 Quick Start

Installation

npm install somali-quran-audio

Basic Usage

const {
  somaliAyah,
  listChapterAudio,
  tafsirPlaylist,
} = require("somali-quran-audio");

// Get Somali translation for Al-Fatiha verse 1
const translation = await somaliAyah(1, 1);
console.log(translation.result.translation);
// Output: "1. Waxaan Ku billaabi Magaca Alle, Naxariistaha..."

// Get chapter audio files for Mishary Al-Afasy
const audio = await listChapterAudio(7);
console.log(audio.audio_files[0].audio_url);
// Output: "https://download.quranicaudio.com/qdc/mishari_al_afasy/murattal/1.mp3"

// Get Somali tafsir playlist
const playlist = await tafsirPlaylist(
  "Cuz01SomaliAudioQuranTranslation_201601"
);
console.log(`Found ${playlist.length} audio files`);

🖥️ CLI Usage

The package includes a powerful command-line interface:

# Install globally for CLI access
npm install -g somali-quran-audio

# Get Somali translation
sqa ayah 1 1

# List chapter audio files
sqa chapters 7

# Get page audio
sqa page 1 7

# Search tafsir items
sqa tafsir-search "Somali Quran"

# Get tafsir playlist
sqa tafsir Cuz01SomaliAudioQuranTranslation_201601

📚 API Reference

Translation Functions

somaliAyah(surah, ayah, options?)

Get Somali translation for a specific ayah.

const ayah = await somaliAyah(2, 255); // Ayat al-Kursi
console.log(ayah.result.translation);

Parameters:

• surah (number): Surah number (1-114)
• ayah (number): Ayah number
• options (object, optional): { cacheTtl: 86400 }

somaliSurah(surah, options?)

Get complete Somali translation for a surah.

const surah = await somaliSurah(1); // Al-Fatiha
console.log(surah.result); // Array of ayahs with translations

Audio Functions

listChapterAudio(recitationId?, options?)

Get audio files for all chapters by a specific reciter.

const chapters = await listChapterAudio(7); // Mishary Al-Afasy
console.log(chapters.audio_files.length); // 114 chapters

Popular Reciter IDs:

• 7 - Mishary Rashid Al-Afasy (default)
• 1 - Abdul Basit Abdul Samad
• 2 - Abdullah Basfar
• 3 - Abdul Muhsin Al-Qasim

pageAudio(page, recitationId?, options?)

Get verse audio for a specific Mushaf page.

const pageAudio = await pageAudio(1, 7); // First page
console.log(pageAudio.audio_files); // Array of verse audio URLs

juzAudio(juz, recitationId?, options?)

Get verse audio for a specific Juz (Para).

const juzAudio = await juzAudio(1, 7); // First Juz

Tafsir Functions

listTafsirItems(query?, limit?, options?)

Search Archive.org for Somali tafsir items.

const items = await listTafsirItems("Somali Quran Tafsir", 5);
console.log(items); // Array of { id, title }

tafsirPlaylist(itemId, options?)

Get MP3 URLs from an Archive.org item.

const playlist = await tafsirPlaylist(
  "Cuz01SomaliAudioQuranTranslation_201601"
);
console.log(playlist); // Array of MP3 URLs

🌐 Web Application Example

The package includes a complete web application demonstrating all features:

Features:

• 📖 Translation Tab - Browse Somali translations with beautiful Arabic text rendering
• 🎵 Audio Tab - Play Quran recitations by different reciters
• 🎧 Tafsir Tab - Access Somali tafsir audio playlists
• 📱 Responsive Design - Works perfectly on mobile and desktop
• 🎨 Modern UI - Beautiful gradient design with smooth animations

Running the Web App

cd example-app
npm install
npm start

Visit http://localhost:3000 to see the application in action.

⚙️ Configuration

Environment Variables

Create a .env file in your project root:

# Optional: QuranEnc Somali edition slug (default: somali_yacob)
QURANENC_SOMALI_SLUG=somali_yacob

# Optional: YouTube API key for future features
YOUTUBE_API_KEY=your_api_key_here

Caching Options

All functions support caching options:

// Custom cache TTL (time-to-live) in seconds
const ayah = await somaliAyah(1, 1, { cacheTtl: 3600 }); // 1 hour cache

// Default cache times:
// - Translations: 24 hours (86400s)
// - Audio metadata: 30 minutes (1800s)
// - Chapter lists: 1 hour (3600s)
// - Tafsir searches: 24 hours (86400s)

🏗️ Project Structure

somali-quran-audio/
├── src/
│   ├── index.js          # Main SDK exports
│   ├── index.d.ts        # TypeScript definitions
│   ├── cache.js          # Caching implementation
│   └── providers/
│       ├── qurancom.js   # Quran.com API client
│       ├── quranenc.js   # QuranEnc API client
│       └── archive.js    # Archive.org API client
├── bin/
│   └── sqa.js           # CLI tool
├── example-app/         # Complete web application
│   ├── server.js        # Express.js backend
│   ├── public/
│   │   ├── index.html   # Frontend HTML
│   │   └── app.js       # Frontend JavaScript
│   └── package.json
├── test.js              # Test suite
└── README.md

🧪 Testing

Run the comprehensive test suite:

npm test

The test suite covers:

• ✅ Somali translation retrieval
• ✅ Audio URL generation
• ✅ Tafsir playlist extraction
• ✅ Caching functionality
• ✅ Error handling
• ✅ CLI interface

📊 Performance

• First API Call: ~300-500ms (network request)
• Cached Calls: ~1ms (memory retrieval)
• Package Size: 3.2 kB compressed, 9.5 kB unpacked
• Memory Usage: Minimal with intelligent cache management

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/yourusername/somali-quran-audio.git
cd somali-quran-audio
npm install
npm test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Quran.com - For providing high-quality recitation audio
• QuranEnc - For Somali translation data
• Archive.org - For hosting Somali tafsir audio collections
• Somali Muslim Community - For preserving and sharing Islamic knowledge in Somali

🔗 Related Projects

• Quran.com API - Official Quran.com API documentation
• QuranEnc - Multilingual Quran translations
• Archive.org - Digital preservation platform

📞 Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full API Docs

Made with ❤️ for the Somali Muslim Community

⭐ Star this repo • 🐛 Report Bug • ✨ Request Feature