yxqo41main commited on
Commit
328d5f1
ยท
verified ยท
1 Parent(s): d0f6438

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +249 -1
README.md CHANGED
@@ -8,5 +8,253 @@ pinned: false
8
  license: mit
9
  short_description: Official Repo/Space containing and running the Kalamalah API
10
  ---
 
 
11
 
12
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8
  license: mit
9
  short_description: Official Repo/Space containing and running the Kalamalah API
10
  ---
11
+ # Kalamalah CDN Dataset
12
+ This dataset contains all Quran data, audio recitations, and mushaf pages for the Kalamalah Quran API!
13
 
14
+ # Kalamalah API Documentation and CDN File Path Plan
15
+
16
+ ## Base URL
17
+ - **Production**: `https://api.kalamalah.com`
18
+
19
+ ## CDN Structure (Both Local & Hugging Face Hub)
20
+ The API uses either local files or Hugging Face Hub dataset `Kalamalah/cdn` as the CDN. The structure is identical for both:
21
+ ```
22
+ cdn/
23
+ โ”œโ”€โ”€ api_data/
24
+ โ”‚ โ”œโ”€โ”€ surahs.json
25
+ โ”‚ โ”œโ”€โ”€ editions.json
26
+ โ”‚ โ””โ”€โ”€ surah/
27
+ โ”‚ โ”œโ”€โ”€ 1/
28
+ โ”‚ โ”‚ โ”œโ”€โ”€ uthmani.json (Arabic text)
29
+ โ”‚ โ”‚ โ””โ”€โ”€ en.sahih.json (English translation)
30
+ โ”‚ โ”œโ”€โ”€ 2/
31
+ โ”‚ โ”‚ โ””โ”€โ”€ ...
32
+ โ”‚ โ””โ”€โ”€ 114/
33
+ โ”‚ โ””โ”€โ”€ ...
34
+ โ”œโ”€โ”€ fonts/
35
+ โ”‚ โ”œโ”€โ”€ Kitab-Regular.ttf
36
+ โ”‚ โ”œโ”€โ”€ Kitab-Regular.woff2
37
+ โ”‚ โ”œโ”€โ”€ Uthmani-Regular.ttf
38
+ โ”‚ โ”œโ”€โ”€ Uthmani-Regular.woff2
39
+ โ”‚ โ”œโ”€โ”€ SF-ProUI.ttf
40
+ โ”‚ โ”œโ”€โ”€ SF-ProUI.woff2
41
+ โ”‚ โ”œโ”€โ”€ SF-ArabicUI.ttf
42
+ โ”‚ โ””โ”€โ”€ SF-ArabicUI.woff2
43
+ โ”œโ”€โ”€ reciters/
44
+ โ”‚ โ”œโ”€โ”€ profiles-images/
45
+ โ”‚ โ”‚ โ”œโ”€โ”€ haitham-dokin-profile.jpg
46
+ โ”‚ โ”‚ โ”œโ”€โ”€ yasser-aldosari-profile.png
47
+ โ”‚ โ”‚ โ””โ”€โ”€ ... (all reciter profile images)
48
+ โ”‚ โ”œโ”€โ”€ athan/
49
+ โ”‚ โ”‚ โ””โ”€โ”€ (athan mp3 files)
50
+ โ”‚ โ””โ”€โ”€ audio/
51
+ โ”‚ โ”œโ”€โ”€ haitham-al-dukhin/
52
+ โ”‚ โ”‚ โ””โ”€โ”€ murattal/
53
+ โ”‚ โ”‚ โ”œโ”€โ”€ 001.mp3
54
+ โ”‚ โ”‚ โ”œโ”€โ”€ 002.mp3
55
+ โ”‚ โ”‚ โ””โ”€โ”€ ... 114.mp3
56
+ โ”‚ โ”œโ”€โ”€ yasser-al-dossari/
57
+ โ”‚ โ”‚ โ””โ”€โ”€ murattal/
58
+ โ”‚ โ”‚ โ””โ”€โ”€ ...
59
+ โ”‚ โ”œโ”€โ”€ abdul-baset/
60
+ โ”‚ โ”‚ โ”œโ”€โ”€ mujawwad/
61
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
62
+ โ”‚ โ”‚ โ””โ”€โ”€ murattal/
63
+ โ”‚ โ”‚ โ””โ”€โ”€ ...
64
+ โ”‚ โ”œโ”€โ”€ khalil-al-husary/
65
+ โ”‚ โ”‚ โ”œโ”€โ”€ murattal/
66
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
67
+ โ”‚ โ”‚ โ””โ”€โ”€ muallim/
68
+ โ”‚ โ”‚ โ””โ”€โ”€ ...
69
+ โ”‚ โ”œโ”€โ”€ siddiq-minshawi/
70
+ โ”‚ โ”‚ โ”œโ”€โ”€ murattal/
71
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
72
+ โ”‚ โ”‚ โ””โ”€โ”€ kids-repeat/
73
+ โ”‚ โ”‚ โ””โ”€โ”€ ...
74
+ โ”‚ โ””โ”€โ”€ (other reciters)
75
+ โ”œโ”€โ”€ mushafs/
76
+ โ”‚ โ””โ”€โ”€ qatar-mushaf/
77
+ โ”‚ โ”œโ”€โ”€ 0.jpg
78
+ โ”‚ โ”œโ”€โ”€ 1.jpg
79
+ โ”‚ โ”œโ”€โ”€ 2.jpg
80
+ โ”‚ โ””โ”€โ”€ ... 604.jpg
81
+ โ””โ”€โ”€ background_audio/
82
+ โ””โ”€โ”€ whales.mp3
83
+ ```
84
+
85
+ ---
86
+
87
+ ## API Endpoints
88
+
89
+ ### 1. Health Check
90
+ - **Endpoint**: `GET /health`
91
+ - **Description**: Check if API is running
92
+ - **Response**:
93
+ ```json
94
+ { "status": "healthy" }
95
+ ```
96
+
97
+ ### 2. Root Info
98
+ - **Endpoint**: `GET /`
99
+ - **Description**: Get API overview and available endpoints
100
+ - **Response**:
101
+ ```json
102
+ {
103
+ "message": "Welcome to Kalamalah Quran API!",
104
+ "docs": "/docs",
105
+ "endpoints": {
106
+ "quran": "/api/quran/{language}/{surah_number}[/{ayah_number}]",
107
+ "surahs_list": "/api/surahs",
108
+ "reciters": "/api/reciters",
109
+ "audio": "/api/{reciter_name}/{type}/{surah_number}",
110
+ "mushaf": "/api/mushaf/{mushaf_name}/{page_number}",
111
+ "fonts": "/api/fonts.css"
112
+ }
113
+ }
114
+ ```
115
+
116
+ ### 3. Get All Surahs
117
+ - **Endpoint**: `GET /api/surahs`
118
+ - **Description**: Get list of all 114 surahs with metadata (name, number of ayahs, etc.)
119
+ - **Response**: Array of surah objects
120
+
121
+ ### 4. Get All Reciters
122
+ - **Endpoint**: `GET /api/reciters`
123
+ - **Description**: Get list of all reciters with their information
124
+ - **Response**:
125
+ ```json
126
+ {
127
+ "haitham-al-dukhin": {
128
+ "name": "Haitham Al Dokhin",
129
+ "arabic_name": "ู‡ูŠุซู… ุงู„ุฏุฎูŠู†",
130
+ "types": ["murattal"],
131
+ "description": "...",
132
+ "profile_image": "haitham-dokin-profile.jpg"
133
+ },
134
+ "etc etc of course"
135
+ }
136
+ ```
137
+
138
+ ---
139
+
140
+ ### 5. Get Quran Text
141
+ **Endpoints**:
142
+ - `GET /api/quran/{language}/{surah_number}`
143
+ - `GET /api/quran/{language}/{surah_number}/{ayah_number}`
144
+
145
+ **Parameters**:
146
+ - `language`: Language/edition code (e.g., "ar" for Arabic Uthmani, "en" for Sahih English, "tafsir" for Tafsir Muyassar)
147
+ - `surah_number`: 1-114
148
+ - `ayah_number` (optional): Specific ayah number in the surah
149
+
150
+ **Examples**:
151
+ - Arabic text (Surah Al-Fatiha): `https://api.kalamalah.com/api/quran/ar/1`
152
+ - English translation (Surah Al-Baqarah): `https://api.kalamalah.com/api/quran/en/2`
153
+ - Single ayah: `https://api.kalamalah.com/api/quran/ar/1/1`
154
+
155
+ ---
156
+
157
+ ### 6. Get Mushaf Page
158
+ - **Endpoint**: `GET /api/mushaf/{mushaf_name}/{page_number}`
159
+ - **Description**: Get a page from a specific mushaf as an image
160
+ - **Parameters**:
161
+ - `mushaf_name`: Currently "qatar-mushaf"
162
+ - `page_number`: Page number (0 to 604 for Qatar Mushaf; no leading zeros)
163
+ - **Supported Formats**: .jpg, .jpeg, .png
164
+ - **Example**: `https://api.kalamalah.com/api/mushaf/qatar-mushaf/222`
165
+
166
+ ---
167
+
168
+ ### 7. Get Reciter Audio
169
+ - **Endpoint**: `GET /api/{reciter_name}/{recitation_type}/{surah_number}`
170
+ - **Description**: Get audio recitation of a surah
171
+ - **Parameters**:
172
+ - `reciter_name`: Reciter slug (from `/api/reciters`)
173
+ - `recitation_type`: Type of recitation (from reciter's "types" array)
174
+ - `surah_number`: 1-114 (can be 3-digit padded or not)
175
+ - **Examples**:
176
+ - `https://api.kalamalah.com/api/yasser-al-dossari/murattal/001`
177
+ - `https://api.kalamalah.com/api/siddiq-minshawi/kids-repeat/1`
178
+ - `https://api.kalamalah.com/api/khalil-al-husary/muallim/2`
179
+
180
+ **Available Reciters & Types**:
181
+ | Reciter Slug | Name | Available Types |
182
+ |--------------|------|-----------------|
183
+ | haitham-al-dukhin | Haitham Al Dokhin | murattal |
184
+ | abdul-rashid-sofi | Abdul-Rasheed Sofi | murattal |
185
+ | yasser-al-dossari | Yasser Al-Dossari | murattal |
186
+ | abdul-baset | Abdul Baset | mujawwad, murattal |
187
+ | khalil-al-husary | Khalil Al-Husary | murattal, muallim, mujawwad, ijazah |
188
+ | siddiq-minshawi | Siddiq Minshawi | murattal, kids-repeat, mujawwad |
189
+ | hani-ar-rifai | Hani Ar-Rifai | murattal |
190
+ | abdurrahmaan-as-sudais | Abdurrahmaan As-Sudais | murattal |
191
+ | maher-al-muaiqly | Maher Al-Muaiqly | murattal |
192
+ | ahmed-al-ajamy | Ahmed Al-Ajamy | murattal |
193
+ | al-huzaifi | Al-Huzaifi | ayah-by-ayah |
194
+ | mishary-rashid-alafasy | Mishary Rashid Alafasy | (types coming soon) |
195
+
196
+ ---
197
+
198
+ ### 8. Get Reciter Profile Image
199
+ - **Endpoint**: `GET /api/reciter-profile/{reciter_name}`
200
+ - **Description**: Get the profile image of a reciter
201
+ - **Example**: `https://api.kalamalah.com/api/reciter-profile/yasser-al-dossari`
202
+
203
+ ---
204
+
205
+ ### 9. Athan (Call to Prayer)
206
+ **Endpoints**:
207
+ - `GET /api/athan` - List all available athan files
208
+ - `GET /api/athan/{filename}` - Get specific athan audio file
209
+ - **Example**: `https://api.kalamalah.com/api/athan/athan.mp3` (replace with actual filename)
210
+
211
+ ---
212
+
213
+ ### 10. Background Audio
214
+ **Endpoints**:
215
+ - `GET /api/background-audio` - List all available background audio files
216
+ - `GET /api/background-audio/{filename}` - Get specific background audio
217
+ - **Example**: `https://api.kalamalah.com/api/background-audio/whales.mp3`
218
+
219
+ ---
220
+
221
+ ### 11. Fonts API (Google Fonts Style)
222
+ **Endpoints**:
223
+ 1. **Get Font CSS** - `GET /api/fonts.css`
224
+ - **Parameters**:
225
+ - `family` (optional): Font families to include, separated by `|` (e.g., `Kitab|Uthmani|SF-ProUI`)
226
+ - `display` (optional): Font display strategy (default: `swap`, options: `auto`, `block`, `swap`, `fallback`, `optional`)
227
+ - **Description**: Get `@font-face` rules for your selected fonts (just like Google Fonts!)
228
+ - **Examples**:
229
+ - All fonts: `https://api.kalamalah.com/api/fonts.css`
230
+ - Specific fonts (neat names): `https://api.kalamalah.com/api/fonts.css?family=Kitab|Uthmani|SF-ProUI|SF-ArabicUI`
231
+ - Specific fonts (simple names): `https://api.kalamalah.com/api/fonts.css?family=kitab|uthmani|sfPro|sfArabic`
232
+ - Custom font-display: `https://api.kalamalah.com/api/fonts.css?family=SF-ArabicUI&display=block`
233
+
234
+ 2. **Get Font File** - `GET /api/fonts/{filename}`
235
+ - **Parameters**:
236
+ - `filename`: Font file name (e.g., `Kitab-Regular.woff2`)
237
+ - **Description**: Get an individual font file
238
+ - **Example**: `https://api.kalamalah.com/api/fonts/Uthmani-Regular.woff2`
239
+
240
+ **Available Font Families** (both simple and neat names are supported):
241
+ | Neat Name | Simple Name | Description |
242
+ |-----------|-------------|-------------|
243
+ | `Kitab` | `kitab` | Kitab Arabic font |
244
+ | `Uthmani` | `uthmani` | Uthmani Quranic font |
245
+ | `SF-ProUI` | `sfPro` | San Francisco Pro UI (system font) |
246
+ | `SF-ArabicUI` | `sfArabic` | San Francisco Arabic UI (system font) |
247
+
248
+ ---
249
+
250
+ ## Important Notes
251
+ 1. All audio files are in MP3 format
252
+ 2. Mushaf pages are JPG/PNG images
253
+ 3. Profile images can be JPG, JPEG, or PNG
254
+ 4. The API supports both local files and Hugging Face Hub CDN via the `USE_HF_CDN` environment variable
255
+ 5. All endpoints support CORS (Cross-Origin Resource Sharing)
256
+ 6. Interactive documentation available at `/docs` (Scalar UI)
257
+
258
+
259
+ ## Credits
260
+ All content provided by Kalamalah