path: root/doc/experiment-player.xml

<?xml version="1.0"?>

<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink">
	<info>
		<title>Experiment Player</title>
		<subtitle>A tool to analyze audiovisual experiment recordings and transcripts</subtitle>

		<author>
			<personname><firstname>Jens</firstname> <surname>Lammert</surname></personname>
			<email>jens.lammert@st.ovgu.de</email>
		</author>
		<copyright>
			<year>2012</year>
			<year>2013</year>
			<holder>Otto-von-Guericke Universität Magdeburg</holder>
		</copyright>

		<abstract><para>
			The following document illustrates how to install, configure
			and use the Experiment Player to analyze experiments.
		</para></abstract>

		<address>
			<uri>
				<link xlink:href="https://github.com/rhaberkorn/experiment-player">https://github.com/rhaberkorn/experiment-player</link>
			</uri>
		</address><address>
			<uri>
				<link xlink:href="http://sourceforge.net/projects/exp-player/">http://sourceforge.net/projects/exp-player/</link>
			</uri>
		</address>
	</info>

	<chapter>
		<title>Installation</title>
		<section>
			<title>Windows</title>
			<para>
				To install the <productname>Experiment Player</productname> on a Windows-based operating system,
				the GTK+ 2 widget toolkit must first be downloaded and installed.
				A convenient GTK+ installer can be downloaded from the
				<link xlink:href="http://gtk-win.sourceforge.net/home/index.php/Main/Downloads">
				"GTK+ for Windows Runtime Environment Installer" project page</link>.
				It is only necessary to install the
				<link xlink:href="http://downloads.sourceforge.net/gtk-win/gtk2-runtime-2.24.10-2012-10-10-ash.exe?download">
				GTK+ runtime</link>.
				<link xlink:href="http://downloads.sourceforge.net/gtk-win/gtk2-themes-2009-09-07-ash.exe?download">
				Additional themes</link> may be installed as well - but the default GTK+ theme should be sufficient.
			</para><para>
				Precompiled Windows 32-bit binaries of the <productname>Experiment Player</productname> itself
				are available as ZIP archives from the
				<link xlink:href="http://sourceforge.net/projects/exp-player/files/bin/">Sourceforge project page</link>.
				The ZIP archive merely has to be extracted somewhere.
				Afterwards the included <filename>experiment-player.exe</filename> can be executed.
				All library dependencies except GTK+ are included in the ZIP archive.
			</para>
		</section>
		<section>
			<title>Linux</title>
			<para>
				To install the <productname>Experiment Player</productname> on a Linux-based operating system,
				it first has to be built from source.
				It can either be built from a local
				<link xlink:href="https://github.com/rhaberkorn/experiment-player">Git repository</link> clone,
				or from a source code package that can be downloaded from the
				<link xlink:href="http://sourceforge.net/projects/exp-player/files/src/">project's download archive
				on Sourceforge</link>.
				In either case, further build instructions are given in the included
				<filename>INSTALL</filename> file.
			</para>
		</section>
	</chapter>
	<chapter>
		<title>Graphical User Interface</title>
		<para>
			After startup there will be two windows, a <emphasis>player</emphasis>
			window and a <emphasis>data</emphasis> window.
			They are explained in the following sections.
		</para>
		<section>
			<title>Player Window</title>
			<screenshot xml:id="player-window">
				<!-- <title>Player Window after startup</title> -->
				<mediaobject>
					<imageobject>
						<imagedata fileref="images/player-window-new.png"/>
					</imageobject>
					<caption>Player Window after startup</caption>
				</mediaobject>
			</screenshot>
			<para>
				The image above depicts the player window after startup.
				No experiment is yet opened in the application, so several
				controls are greyed out.
			</para><para>
				Experiments can be opened via the <guimenu>File</guimenu> menu
				or the <guimenu>Quick Open</guimenu> menu.
				The process of opening experiments via the <guimenu>Quick Open</guimenu> menu
				is <link linkend="quick-open">explained later on</link>.
				The remaining interface components are self-explanatory.
			</para>
		</section>
		<section>
			<title>Data Window</title>
			<screenshot xml:id="data-window-new">
				<!-- <title>Data Window after startup</title> -->
				<mediaobject>
					<imageobject>
						<imagedata fileref="images/data-window-new.png"/>
					</imageobject>
					<caption>Data Window after startup</caption>
				</mediaobject>
			</screenshot>
			<para>
				The image above depicts the data window after startup.
				The data window is used to display additional information of an
				experiment.
				This information is time-dependant and synchronized with other
				time-dependant data, like the current video position.
				If the time is changed in one component, it changes in all the
				other ones as well.
			</para><para>
				The current implementation is able to display an experiment
				transcript (in the Transcript view area).
				The transcript view is divided into a left part showing the
				wizard's text contributions and a right part showing the
				proband's text contributions.
				The different experiment phases are displayed hierachically
				in the Transcript navigation area.
				Transcripts may also be searched and highlighted but this feature is
				<link linkend="highlighting">explained later on</link>.
			</para><para>
				Furthermore the look of the Transcript View may be customized
				after loading an experiment by right-clicking the Transcript view.
				Foreground and background colors, text alignment and scroll direction
				can be changed this way.
			</para><para>
				The playback position of the experiment may be influenced in the
				following ways:
				<itemizedlist>
					<listitem><para>
						by clicking or scrolling the slider in the
						<link linkend="data-window-new">data window</link> with the mouse
						wheel,
					</para></listitem>
					<listitem><para>
						by scrolling the transcript widgets with the mouse wheel,
					</para></listitem>
					<listitem><para>
						by using the transcript view's scroll bar, or
					</para></listitem>
					<listitem><para>
						by double-clicking an entry in the navigation hierarchy.
					</para></listitem>
				</itemizedlist>
				Single clicking an entry in the navigation hierarchy
				mereley highlights that part of the transcript by the shading the
				transcript view's background.
			</para>
		</section>
	</chapter>
	<chapter>
		<title>Getting Started</title>
		<section xml:id="quick-open">
			<title>How to load a file with Quick Open</title>
			<para>
				A video recording of an experiment and its correspondig transcript file
				are considered as an experiment. A video is an AVI or MP4 file
				while transcript files are special XML applications generated from
				<link xlink:href="http://agd.ids-mannheim.de/download/Folker_Schema.xsd">
				FOLKER XML transcripts</link>.
				Transcript XML files must conform to the <filename>session.dtd</filename>
				schema shipped with the <application>Experiment Player</application>
				application.
				Experiment's files can be opened separately or by using the
				<emphasis>Quick Open</emphasis> feature.
			</para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata fileref="images/quick-open-empty.png"/>
					</imageobject>
					<caption>Empty Quick Open menu</caption>
				</mediaobject>
			</screenshot>
			<para>
				<emphasis>Quick Open</emphasis> can be performed using the
				<guimenu>Quick Open</guimenu> menu.
				The menu has items for all experiments found in a selected
				directory.
				The directory may be selected using the <guimenuitem>Choose Directory...</guimenuitem>
				menu item.
				Experiment files with identical basenames (file name without extension) are
				listed as single menu items.
				For instance, if the directory contains two files <filename>20101117.xml</filename> and
				<filename>20101117.mp4</filename>, the menu will look like:
			</para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata fileref="images/quick-open.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
			<para>
				When an experiment item is activated in the menu, the
				corresponding experiment files are loaded (replacing any
				already opened experiment).
				The configured location of the <emphasis>Quick Open</emphasis> directory
				persists after application restarts.
			</para>
		</section>
		<section xml:id="highlighting">
			<title>Transcript Highlighting</title>
			<para>
				To analyze the dialog between proband and wizard the Experiment-Player offers
				a feature to search for text patterns in the dialog and for highlighting the matches
				in the transcript.
				After loading an experiment via the <guimenu>Quick Open</guimenu> menu,
				the dialog between proband and wizard will be displayed in the transcript widgets.
				The highlighting feature can be used for both the wizard's and the proband's part
				of the dialog independently of each other.
				By entering a search expression in the
				<link linkend="data-window-new">text boxes for interactive highlighting</link>
				of the transcript will be highlighted on the fly.
				The syntax of these search expressions and their exact semantics are
				described in the following sections.
			</para>
			<section xml:id="regexp">
				<title>Regular Expressions</title>
				<para>
					By default, if the <guibutton>Markup</guibutton> toggles are inactive,
					search expressions are interpreted as <emphasis>regular expressions</emphasis>.
					The system will iterate all text fragments (dialog contributions
					with distinct timestamps) and tries to match the regular expression
					against them.
					All the matches will be highlighted.
					By default they will be formatted bold, but this may be changed
					in the <link linkend="config-file">configuration file</link>.
					<emphasis>Regular Expressions</emphasis>
					are case-insensitive so both lower-case and upper-case character
					will match both lower and upper case text.
					For more information about the <emphasis>Regular Expression</emphasis>
					syntax supported by the program, have a look at the
					<link xlink:href="http://developer.gnome.org/glib/stable/glib-Perl-compatible-regular-expressions.html">
					glib documentation for Perl compatible Regular Expression</link>.
					All constructs are supported, except captures.
				</para><para>
					An icon next to the pattern entry box signals well-formedness of
					the entered search expression.
				</para>
			</section>
			<section>
				<title>Format Expression</title>
				<para>
					By default a search term will be regarded as
					<emphasis>Regular Expression</emphasis> and matches found
					will be highlighted bold.
					However if the <guibutton>Markup</guibutton> toggle is activated
					the input expression will be regarded as a
					<emphasis>Format Expression</emphasis> which is a combination of
					<emphasis>Regular Expression</emphasis> and <emphasis>Pango Markup</emphasis>.
					<emphasis>Pango Markup</emphasis> is a simple HTML-like formatting
					markup language.
				</para><para>
					Just like with plain regular expressions, all text fragments are iterated
					and the format expression is matched against each of them.
					The markup does not matter for matching but only the regular expressions
					contained <emphasis>within</emphasis> the markup tags.
					For every match in each of the text fragments, the markup will be applied
					to all of the text matched by the regular expression within the
					corresponding markup tag.
					So for instance the format expression
					<code><![CDATA[<b>A<i>B</i>C</b>]]></code>,
					case-insensitively matches against all occurrences of <literal>ABC</literal>,
					formatting all the characters bold and only <literal>B</literal> in italics.
				</para><para>
					The following screenshot shows a transcript with all consonants followed
					by vowels highlighted
					(expression <code><![CDATA[<span color="red">[^aeiou]</span><span color="blue">[aeiou]</span>]]></code>):
				</para>
				<screenshot>
					<mediaobject>
						<imageobject>
							<imagedata fileref="images/format-expressions.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
				<para>
					For more information about <emphasis>Pango Markup</emphasis>, please read the
					<link xlink:href="http://developer.gnome.org/pango/stable/PangoMarkupFormat.html">
					Pango Markup documentation</link>.
				</para>
			</section>
			<section>
				<title>Format Files</title>
				<para>
					<emphasis>Format Files</emphasis> are files which contain a sequence of
					<emphasis>format expressions</emphasis>.
					So any collection of format expressions for
					analyzing dialogs can be saved in those files and used with different
					experiments.
				</para>
				<example xml:id="sample.fmt">
					<title>Sample Format File (sample.fmt)</title>
					<programlisting><![CDATA[# The samples from last section combined into one file:
<b>A<i>B</i>C</b>
<span color="red">[^aeiou]</span><span color="blue">[aeiou]</span>]]></programlisting>
				</example>
				<para>
					<emphasis>Format Files</emphasis> are loaded in a similar manner as experiments
					when using the <emphasis>Quick Open</emphasis> feature.
					First a directory containing format files must be chosen via the
					<guimenuitem>Choose Directory...</guimenuitem> item in the <guimenu>Formats</guimenu>
					menu of the data window.
				</para>
				<screenshot>
					<mediaobject>
						<imageobject>
							<imagedata fileref="images/format-menu.png"/>
						</imageobject>
						<caption>"Formats" menu</caption>
					</mediaobject>
				</screenshot>
				<para>
					A format file may then be selected via the drop-down boxes below the
					transcript view area.
					The first entry of those boxes is always empty and may be selected to
					disable format file processing.
					The following screenshot shows
					<link linkend="sample.fmt"><filename>sample.fmt</filename></link>
					being selected:
				</para>
				<screenshot>
					<mediaobject>
						<imageobject>
							<imagedata fileref="images/format-file-selection.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
				<para>
					If a format file is selected, for each text fragment every format expression
					in the format file is evaluated (highlighting all matches as described earlier).
					At last, any interactively entered search expression (plain regular expression or
					format expression) is evaluated for each text fragment after the format expressions
					in the currently selected <emphasis>Format File</emphasis>.
					All formattings are applied cumulatively.
					Where subsequent styles cannot be merged, later ones overwrite earlier ones.
					For instance, when loading the following format file, the word <emphasis>program</emphasis>
					is formatted blue instead of red:
				</para>
				<programlisting><![CDATA[<span color="red">programm</span>
<span color="blue">programm</span>]]></programlisting>
				<para>
					The syntax of format files is as follows:
					<itemizedlist>
						<listitem><para>
							<emphasis>Format Files</emphasis> have the file extension
							<literal>fmt</literal>.
						</para></listitem>
						<listitem><para>
							Every line will be regarded as a distinct
							<emphasis>Format Expression</emphasis>.
						</para></listitem>
						<listitem><para>
							Leading whitespace characters are ignored.
						</para></listitem>
						<listitem><para>
							A line beginning with <literal>#</literal>
							is ignored completely (comment line).
						</para></listitem>
						<listitem><para>
							Empty lines are ignored.
						</para></listitem>
						<listitem><para>
							Incorrect lines will cause an error message.
						</para></listitem>
					</itemizedlist>
				</para>
			</section>
		</section>
	</chapter>
	<chapter xml:id="config-file">
		<title>Config File</title>
		<para>
			The <application>Experiment Player's</application> configuration file
			is located in different locations depending on the platform:
		</para>
		<itemizedlist>
			<listitem><para>
				Under Linux, it will be located in the user's data directory as specified
				in the <link xlink:href="http://www.freedesktop.org/Standards/basedir-spec">
				XDG Base Directory Specification</link>
				(usually <filename>$HOME/.local/share/.experiment-player</filename>).
			</para></listitem>
			<listitem><para>
				Under Windows, it will be located in the local application data directory
				(usually <filename>C:\Documents and Settings\%USERNAME%\Local Settings\Application Data\.experiment-player</filename>).
			</para></listitem>
		</itemizedlist>
		<para>
			The syntax of the configuration file is documented in the
			<link xlink:href="developer.gnome.org/glib/unstable/glib-Key-value-file-parser.html">glib documentation</link>.
		</para><para>
			Sometimes it is useful to edit the configuration file directly in order to tweak options that are not
			accessible via the <application>Experiment Player</application> GUI.
			The following table lists such configuration keys:
		</para>
		<table border="1">
			<title>Configuration Keys</title>
			<thead border="1">
				<tr>
					<td>Key</td>
					<td>Description</td>
					<td>Format</td>
				</tr>
			</thead>
			<tbody border="1">
				<tr>
					<td><literal>Default-Format-Font</literal></td>
					<td>
						The font used for highlighting <link linkend="regexp">plain regular expressions</link>.
					</td><td>
						See <link xlink:href="http://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string">
						Pango Font description</link>
					</td>
				</tr>
				<tr>
					<td><literal>Default-Format-Text-Color</literal></td>
					<td>
						The foreground color used for highlighting <link linkend="regexp">plain regular expressions</link>.
					</td><td>
						An RGB color specification such as <literal>#FF0000</literal> or a color name such as
						<literal>red</literal>.
					</td>
				</tr>
				<tr>
					<td><literal>Default-Format-BG-Color</literal></td>
					<td>
						The background color used for highlighting <link linkend="regexp">plain regular expressions</link>.
					</td><td>
						An RGB color specification such as <literal>#FF0000</literal> or a color name such as
						<literal>red</literal>.
					</td>
				</tr>
			</tbody>
		</table>
	</chapter>
</book>