Version 2, May 2010, ELAN 3.9.0


INTRODUCTION

This README gives basic information on how to construct an audio/video recognition
tool that can co-operate with ELAN. Although the effort defining the interface
between ELAN and audio-/video-recognizers is still work in progress we want to 
give everyone who is interested the opportunity to have a try at building one. 
If you are going to implement a recognizer all feedback you can give is very welcome 
on the ELAN forum: http://www.lat-mpi.eu/tools/elan/elanforum/simpleforum_view

Before experimenting with this or your own recognizer it is wise to read the paragraph
in the ELAN manual regarding the silence recognizer. 


CHANGES

There are two major changes in the recognizer extension mechanism since the 
first version. Recognizer components now have to be installed in their own 
directory/folder inside the extensions directory and should provide a component 
metadata file. In addition to the existing extension option based on the Recognizer API,
which means implementing the (Java) Recognizer interface, there is now also the option
to extend ELAN by recognizer software that runs as a stand-alone executable or script.
The interfacing specification for the second option can be found here:
http://www.mpi.nl/research/research-projects/language-archiving-technology/avatech/
The implementation of this specification in ELAN is preliminary.   


DIRECTORY STRUCTURE

If you can read this you unpacked the .zip/.tar file successfully. this README is
located in the following directory structure:

recog/
	api/		
	build/
	dist/
	lib/
	src/
	README
	recognizer.cmdi
	recog.xml
	
The api directory contains sources from ELAN that are relevant for an audio- or video recognizer extension
The build directory is used by the ant build script
The dist directory will contain a recog.jar after running the ant build script
The lib directory must contain the latest elan.jar, you must copy it there yourself
The src directory contains a package sub directory named demo with the demo recognizer sources in it
The README is what you are reading now
The recog.xml file is an ant build script
The recognizer.cmdi file is an example metadata file for a recognizer extension. This is now a mandatory part of a recognizer distribution
 


BUILD AND DEPLOYMENT INSTRUCTIONS (Recognizer API):

1. add elan.jar to the lib directory

2. run "ant -f recog.xml" to build a recog.jar in the dist directory

3. copy the recog.jar and the demo recognizer.cmdi file to a directory in the extensions directory of ELAN

4. run ELAN and you will find the Demo Recognizer on the Audio (and Video) Recognizers panel.



DEVELOPER INFORMATION (Recognizer API)

The files src/demo/DemoRecognizer.java and src/demo/DemoRecognizerPanel.java and recognizer.cmdi
implement a simple demo recognizer that illustrates the basic communication with ELAN.
The only thing this demo recognizer does is creating a segmentation based on a user
definable constant interval. By default in the first seconds of the file, but if there 
are example selections provided by the user, the interval in which to create segments is
based on the extent of all selections.
After building and deploying it will present itself as a "Demo Recognizer" on ELAN's 
Audio (and Video) Recognizers Panel. It is advisable to build and deploy 
this recognizer before trying to make one yourself. Its behaviour in ELAN combined with 
the documentation in the source files should give you the information needed to implement
a more useful recognition algorithm. 

If you have access to the ELAN sources you can also have a look at the implementation of 
the silence recognizer in the mpi.eudico.client.annotator.recognizer.silence package.

A recognizer is required to implement the Recognizer interface and it can invoke methods of
the RecognizerHost. 

The RecognizerHost informs the Recognizer about the relevant media file(s). The recognizer
informs the RecognizerHost if it can handle the media.

When a recognizers start() method is called it can get Selections from the RecognizerHost
(ELAN). These selections define the patterns the recognizer is supposed to find. It is optional
to use these selections, some recognizers can function without example selections.

While the recognition process runs the recognizer can give feedback regarding the 
progress it is making to the RecognizerHost.

The result of the recognition process must be placed in one or more
Segmentation objects. They consist of a MediaDescriptor that has information about the
media that the segmentation refers to and an ArrayList with Segments. The Segments 
contain time information and a segment label.

The Segmentation objects are made available to ELAN through the "Create Tier(s)" button. 
In general a Segmentation object translates to a tier and its Segment objects to annotations
but ELAN also has an option to customize the conversion from a Segmentation to a tier and e.g. 
create more than one tier from a single Segmentation object.

More information on these objects can be found in the Javadoc comments in the following 
java files in the api directory:. 

from mpi.eudico.client.annotator.recognizer.api
	Recognizer.java
	RecognizerHost.java
	ParamPreferences.java

from mpi.eudico.client.annotator.recognizer.data
	MediaDescriptor.java
	Segment.java
	AudioSegment.java
	VideoSegment.java
	Segmentation.java
	RSelection.java

Major changes since version 1:
	- Selection.java renamed to RSelection.java
	- Selections (input) can have a textual label now, an entire tier can now be selected as input
	- Support for a report that can be shown to the user after running the recognizer
More descriptions can be found in the Java files.
	
You are NOT supposed to include these classes in your recognizer.jar. They are in elan.jar
and were only included here for documentation purposes.

For this kind of extensions the recognizer.cmdi file should:
	- have the value "direct" for the attribute "recognizerType" of element "recognizer"
	- have the fully qualified name of the class that implements Recognizer.java as the value of
	the attributes "runWin", "runMac" and "runLinux". Only the platforms that are supported
	should be present.
	- have at least one "input" element with value "audio" or "video" 


DEVELOPER INFORMATION (Stand-alone component)
Instead of implementing the "Recognizer.java" interface it is also possible to extend ELAN
with a stand-alone executable in combination with a proper recognizer.cmdi file. You can take 
the file "example_recognizer.cmdi" file as the basis, rename it to "recognizer.cmdi" and 
modify the xml in accordance with the specifications of your recognizer software.

For this kind of extensions the recognizer.cmdi file should:
	- have the value "local" for the attribute "recognizerType" of element "recognizer"
	- have the executable command as the value of the attributes "runWin", "runMac" 
	and "runLinux". Only the platforms that are supported should be present.
	- have at least one "input" element with value "audio" or "video" 
	- normally have at least one "output" element, e.g. a file for storing the segmentations
	
