Document Actions
MPTK Data FAQ
FAQ overview
- What is the format of the dictionary files?
- What are the rules to write a dictionary?
- Which tags are valid in a dictionnary
What is the format of the dictionary files?
The dictionary files use a XML syntax, with tags enclosed between angle brackets. Strict
XML compliance is now mandatory.
What are the rules to write a dictionary?
A dictionary should include, in the following order:1. an optional XML declaration line;
2. a mandatory dictionary opening tag;
3. an optional library version tag;
4. a list of blocks with their parameters (some parameters being mandatory, some admit-
ting default values);
5. a dictionary closing tag.
Any text included after the dictionary closing tag will be ignored. Blank spaces and line
breaks are ignored. Any part of the file can be commented out either by enclosing it between
<!-- and --> (XML style) The parser will send any text it can’t match to stderr with a error
message: in the event of syntax errors in a dictionary, some dictionary pieces will therefore
show up in stderr.
Which tags are valid in a dictionnary
• <?xml version="1.0" encoding="ISO-8859-1"?> [optional]: the XML declaration line.
• <dict>List of blocks</dict>: the opening and closing tags for the dictionary. Anything coming after the </dict> tag will be ignored by the parser.
• <libVersion>blah</libVersion> [optional]: the library version declaration. This is provided for backward compatibility if we ever change the dictionary syntax. When absent, the library version is taken to be the current one.
• <blockproperties name="PROPERTIES_NAME">List of block parameters</blockproperties>: the opening and closing tags for a block properties list.this
• <block uses="PROPERTIES_NAME">List of block parameters</block>: the opening and closing tags for a block. The block will be construct using the list of parameters defined in PROPERTIES_NAME block properties.
• <block>List of block parameters</block>: the opening and closing tags for a block. the list of block parameters should contains all the mandatories parameters for this type of block
• <par type="NAME" value="VALUE"/> : a block parameter. The NAME and corresponding VALUE value in string. The parameter value is set to the corresponding type when the dictionary file is parsed. Note that when using the <block uses="PROPERTIES_NAME">List of block parameters </block> syntax. The block parameters defined in the block list override the parameters from PROPERTIES_NAME block properties.
The list of parameters for relevant block types (G==gabor, H==harmonic, C==Chirp, A==Anywave, CT==constant, N==nyquist) are given below:
– (G,H,C,CT,N) windowLen with an unsigned long int value: the atom length (i.e.,the window length in the STFT).
– (G,H,C,A,CT,N) windowShift with an unsigned long int value: the atom shift (i.e., the window shift in the STFT).
– (G,H,C) windowRate with a double value between 0.0 and 1.0: an alternate way to specify the window shift, as a proportion of the windowLen. If both are present, windowShift has precedence over windowRate.
– (G,H,C) fftSize with an unsigned long value: the frequency resolution in terms of FFT size. It has to be greater or equal to windowLen if windowLen is even, or (windowLen+1) if windowLen is odd. If absent, defaults to windowLen (or windowLen+1).
– (G,H,C,CT,N) blockOffset with an unsigned long value: the block Offset, i.e. the position of the first frame. If absent, defaults to 0.
– (G,H,C,CT,N) windowtype the window specification to be included among the block parameters.
– (G,H,C,CT,N) windowopt the optional parameter for window type:
The following windowtypes do not require the windowopt attribute: rectangle, triangle, cosine, hanning, hamming, blackman, flattop, fof.
The following windowtypes do require the windowopt attribute: hamgen, gauss, exponential.
The meaning of the optional parameter varies according to the window type. See the reference manual for more info.
– (H) f0Min with a double value: minimum frequency (in Hz) from which the fundamental frequency of the harmonic atoms is searched. Defaults to the first non-null FFT frequency.
– (H) f0Max with a double value: maximum frequency (in Hz) at which the fundamental frequency of the harmonic atoms is searched. Defaults to the Nyquist frequency of the considered signal.
– (H) numPartials with an unsigned int value: number of partials considered when tracking the harmonic atoms.
– (C) numFitPoints (EXPERIMENTAL) with an unsigned int value: number of polynomial fitting points considered for the chirp optimization algorithm. Defaults to 1.
– (C) numIter (EXPERIMENTAL) with an unsigned int value: number of iterations considered for the chirp optimization algorithm. Defaults to 1.
– (A) tableFileName with a string: filename of the table containing the waveforms (ex: —/udd/toto/table.bin— ). Note that there is no ” around the string.
Note that the dirac blocks don’t need any parameter (they just match signal samples).