Copyright © 2014  Music Technology Group - Universitat Pompeu Fabra

NAME: AlignmentEvaluation

DESCRIPTION 

A tool for evaluation of absolute alignment error of tokens.
Done to evaluate results of a system for lyrics-2-audio alignment on different levels (a token could be phoneme, word or phrase - a group of words )
Extendable to the evaluation for any token-based alignment (e.g. if token is word, phrase, note, section )
Considers begin timestamp and end timestamp of each token.
 
 detected file format :  mlf format of htk 
 annotation file format: TextGrid of www.praat.org/ 
 
 the detected result can be a text file of triples (begin timestamp, end timestamp, tokenID) : see method WordLevelEvaluator._evalAlignmentError() 
 the annotation can be in www.sonicvisualiser.org (can be provided on request with code in sonicVisTextPhnDir2mlf.py)
 
Algorithm is token-identities-agnostic, e.g. it does not try to match token-IDs between detected result and annotation, but proceeds successively one-by-one  

Note that if a single boundary is detected between two tokens it is considered once as end of preceding annotation token  and beginning of following annotation token, which makes the metric rather strict

------------------------------
As well there is a module to convert automatically the decoded result to Praat's TextGrid format.
This enables the  visualization of the decoding result together with the groundTruth in Praat:
see PraatVisualiser.openTextGridInPraatopenTextGridInPraat : opens the text Grid in Praat
NOTE: # deprecated due to error on opening word-level files... use instead tab2TextGrid 

Enjoy!
 
 
LICENSE:
AlignmentEvaluation is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation (FSF), either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/

CITATION: 
please cite 
Dzhambazov, G., Senturk S., Serra X. - Automatic lyrics-to-audio alignment in classical Turkish music
bibTex: http://mtg.upf.edu/biblio/export/bibtex/2965

BUILD INSTRUCTIONS:

depends on 
* utilsLyrics
git clone https://github.com/georgid/utilsLyrics.git



---------------------------------------- 
EXAMPLE USAGE: 

see: main method of WordLevelEvlauator

if decoded result is:
 
startTs endTs phonemeOrWord
0.0		1.11	sil
1.11	2.41	usagi
2.41	2.90	usagi
2.90	3.38	sp
3.38	4.15	nani

and annotation <>.TextGrid is 
beginTs 	usagi usagi 
endTs 	nani

Then the two detected phrases are considered to evaluate:  
1.11 2.90 usagi usagi 
and 
3.38 4.15	nani


To change extensions edit variables in WordLevelEvaluator 
ANNOTATION_EXT = '.TextGrid'
DETECTED_EXT = '.dtwDurationAligned'
when parsing TextGrid: tier_names are expected as defined in TextGrid_Parsing

As well make sure to change the path to your installed Praat program:
PraatVisualiser.PATH_TO_PRAAT