Recitation format
From ZekrWiki
From Zekr 0.6.5, we supported recitation in Zekr. The descriptor file format, however, was changed in 0.7.5. You can see new and old format of recitation files in this article.
New format (Zekr 0.7.5 beta 1 or newer)
Zekr recitation format is simplified and enhanced in many aspects in 0.7.5 branch. Here is a sample file, which can be used for online recitation. In order to convert it to offline recitation, simply change audio.type = offline.
audio.id = afasy-40kbps-offline audio.version = 0.7.5 audio.lastUpdate = 03-11-2009 audio.quality = 40kbps audio.license = Unknown audio.language = ar audio.country = KW audio.reciter = Mishary bin Rashid Al-Afasy audio.reciter.fa = مشاری بن راشد عفاسی audio.reciter.ar = مشاري بن راشد العفاسي audio.reciter.en = Mishary bin Rashid Al-Afasy audio.reciter.ru = Мишари бин Рашид аль-Афаси audio.reciter.tr = Mişari bin Raşid el-Afâsî audio.type = online audio.onlineUrl = http://everyayah.com/data/Alafasy_128kbps/%1$03d%2$03d.mp3 audio.offlineUrl = <absolute>F:/recitation/afasy/%1$03d%2$03d.mp3 audio.offlineAudhubillah = <absolute>F:/recitation/afasy/audhubillah.mp3 audio.offlineBismillam = <absolute>F:/recitation/afasy/bismillah.mp3 audio.offlineSaghaghallah = audio.onlineAudhubillah = http://everyayah.com/data/Alafasy_128kbps/audhubillah.mp3 audio.onlineBismillam = http://everyayah.com/data/Alafasy_128kbps/bismillah.mp3 audio.onlineSaghaghallah =
The first property audio.id is required. It makes this recitation unique, so no two recitations should have the same ID. Version is also required to determine if this is a valid recitation. Your old recitations do not work with Zekr 0.7.5 beta 1 (and later) because this property is missing (they are actually tried to auto-convert to the new format). audio.lastUpdate is just a hint for now. audio.quality is shown in Audio > Recitation menu, so that user can determine between two recitations from same reciter but with different qualities.
Properties audio.reciter and audio.reciter.xy (where xy is ISO code for a language) are used to write recitation name in the menu. This is the name shown under Audio > Recitation menu. You can write reciter's name in your own language. Zekr tries to localize name if it's available. If not it shows audio.reciter property.
Property audio.type accepts: online, offline and offline-online. You are familiar with the first and second. The third one is a new mysterious property which is not tested yet, so I do not explain it for now. The other properties has the form: audio.onlineXyz or audio.offlineXyz. If your recitation is online, first property set should be available, and vice versa. audio.onlineUrl and audio.offlineUrl accept some special characters (actually a valid Java format string). They should contain exactly two variable parameters which are then replaced with sura and aya numbers. For example look at the following property:
audio.onlineUrl = http://everyayah.com/data/Alafasy_128kbps/%1$03d%2$03d.mp3
The value is a valid Java format string with two parameters (%1 = sura and
%2 = aya). String %1$03d%2$03d contains two variables:
1) %1$03d and 2) %2$03d
The general format is: %[argument_index$][flags][width]conversion, so we have
1) %, argument_index = 1, $, flags = 0 (will be zero padded), width = 3, and conversion = d (digit) 2) %, argument_index = 2, $, flags = 0 (will be zero padded), width = 3, and conversion = d (digit)
For example for sura 12, aya 9 we will have the following result string:
http://everyayah.com/data/Alafasy_128kbps/012009.mp3
audio.offlineUrl has the same format. You can write absolute path to your offline resource using <absolute>, or use <base> or <workspace> to point to your Zekr installation folder or your Zekr workspace. If you write nothing at the beginning of the path, the path is taken as a relative path with base directory equal to directory of .properties recitation file. For example the following value can be used for for a user who copied minshawi offline recitation into <zekr
installation folder>/res/audio/minshawi:
audio.offlineUrl = <base>/res/audio/minshawi/%1$03d%2$03d.mp3
The rest of 6 properties are special playing items for online or offline mode. <absolute>, <base> and <workspace> can be specified in the beginning of offline playing items. Online items should point to file on the Internet.
There is a typo in Zekr 0.7.5 and previous releases (beta 1 to 4 and even final version), which accepts audio.onlineBismillam and audio.offlineBismillam, instead of audio.onlineBismillah and audio.offlineBismillah. This is to be fixed in Zekr 0.7.6. Note also that <absolute> was introduced in Zekr 0.7.5 beta 4, so may not work for previous versions.
Note that since value of audio.onlineUrl should be a valid Java string format, for the case of spaces in the URL, you should put %%20 instead of %20, because % is a special Java format string character. For example in Shatri recitation, audio.onlineUrl has the following value:
audio.onlineUrl = http://everyayah.com/data/Abu%%20Bakr%%20Ash-Shaatree_128kbps/%1$03d%...
Note that there is no need to put % twice for other properties like the followings:
audio.onlineAudhubillah = http://everyayah.com/data/Abu%20Bakr%20Ash-Shaatree_128kbps/audhubill... audio.onlineBismillam = http://everyayah.com/data/Abu%20Bakr%20Ash-Shaatree_128kbps/bismillah...
Old format (Zekr 0.7.1 or older)
From Zekr 0.6.5 we had a format for recitation files, which was later changed in 0.7.5 as described in this article. Here you can see old recitation format which was valid from Zekr 0.6.5 to 0.7.1.
First part:
audio.id = minshawi-versebyversequran audio.name = Mohammed Siddiq Minshawi audio.license = Seems old enough to be in the public domain. audio.language = ar audio.country = EG audio.reciter = محمّد صديق المنشاوي
The above has an ID which should make this recitation pack unique. This string should make this .properties file unique among other .properties. "name" is shown in the menu, and the rest are just meta data.
Second part:
audio.baseUrl = [base]/res/audio/afasy
It can be like the above code, for an offline recitation, or like the following code:
audio.baseUrl = data/Menshawi_16kbps audio.serverUrl = http://everyayah.com
in an online recitation. The difference is clear. [base] means C:\Program Files\Zekr or wherever Zekr is installed. Instead, you can use [[[workspace]]] which refers to Zekr workspace (by default ~/.zekr) or [w_b] to use first workspace, and then base folder, if not found mp3s in the base folder. The latter means that mp3s should be found from http://everyayah.com/data/Menshawi_16kbps
Last part:
audio.fileName.suraPad = 00
audio.fileName.ayaPad = 00
audio.fileName = {SURA}{AYA}.mp3
audio.playlist.provider = net.sf.zekr.engine.audio.OfflinePlaylistProvider
audio.playlist.fileName = minshawi-versebyversequran-{SURA}.xml
audio.playlist.fileName.suraPad =
audio.playlist.mode = sura
There are two properties: audio.fileName.suraPad and audio.fileName.ayaPad. The padding text is added to the left-most part of sura or aya num, making it an x or y-digit number, where x is the length of sura pad string + 1, and y is the length of ayaPad string + 1. For example when audio.fileName.suraPad is 00, and ayaPad is 00, audio.fileName, which is {SURA}{AYA}.mp3, will be evaluated to 001012 for sura 1, aya 12. You can see that only one 0 is padded to the aya, because padding is done for making {AYA} fixed-length.
Property audio.fileName is the pattern of mp3 file naming. For example it may be {SURA}_{AYA}.mp3, where file namings are line this: 001_001.mp3, 001_002.mp3, and so forth. audio.playlist.provider is a special concept, which should be always equal to net.sf.zekr.engine.audio.OfflinePlaylistProvider, even for online recitations. It meas how is the playlist provided to the player.
OfflinePlaylistProvider, creates a playlist (in XSPF format) on user's machine, in which mp3 addresses (local for offline, and global (on the Internet) for online recitations) are listed.
OfflinePlaylistProvider creates the playlist, each time a page is visited, and is rewritten as user changes his or her reciter. There is also an (undocumented) feature which makes it possible to use OnlinePlaylistProvider. This one refers to Internet to load a playlist, and also timing list. We can put some timings in an online playlist, using only one mp3 for a number (a page of) ayas.
Property audio.playlist.mode is somehow depricated. You can use sura (which now means page), or all (for having a single playlist XML for the whole Quran). It's not recommended to use all, as it makes two much memory to load the whole Quran playlist XML in the memory.
In order to make an online recitation offline, change audio.baseUrl to [base]/res/audio/<your recitation folder>, and just remove audio.serverUrl. No other change should be needed.
If your old properties do not work, just download them again from http://zekr.org/resources.html, and add them all to your Zekr, which overwrites existing ones. Restart Zekr to apply.
