changeset 691:06fbaccf3b58

Merge and updated bib.

--- a/ape.js	Wed Apr 22 10:05:11 2015 +0100
+++ b/ape.js	Wed Apr 22 11:00:58 2015 +0100
@@ -322,6 +322,12 @@
 		}
 	}
 	
+	var commentShow = textXML.attributes['elementComments'];
+	if (commentShow != undefined) {
+		if (commentShow.value == 'false') {commentShow = false;}
+		else {commentShow = true;}
+	} else {commentShow = true;}
+	
 	var loopPlayback = textXML.attributes['loop'];
 	if (loopPlayback != undefined)
 	{
@@ -449,24 +455,27 @@
 		// Now load each audio sample. First create the new track by passing the full URL
 		var trackURL = hostURL + this.attributes['url'].value;
 		audioEngineContext.newTrack(trackURL);
-		// Create document objects to hold the comment boxes
-		var trackComment = document.createElement('div');
-		trackComment.className = 'comment-div';
-		// Create a string next to each comment asking for a comment
-		var trackString = document.createElement('span');
-		trackString.innerHTML = 'Comment on track '+index;
-		// Create the HTML5 comment box 'textarea'
-		var trackCommentBox = document.createElement('textarea');
-		trackCommentBox.rows = '4';
-		trackCommentBox.cols = '100';
-		trackCommentBox.name = 'trackComment'+index;
-		trackCommentBox.className = 'trackComment';
-		var br = document.createElement('br');
-		// Add to the holder.
-		trackComment.appendChild(trackString);
-		trackComment.appendChild(br);
-		trackComment.appendChild(trackCommentBox);
-		feedbackHolder.appendChild(trackComment);
+		
+		if (commentShow) {
+			// Create document objects to hold the comment boxes
+			var trackComment = document.createElement('div');
+			trackComment.className = 'comment-div';
+			// Create a string next to each comment asking for a comment
+			var trackString = document.createElement('span');
+			trackString.innerHTML = 'Comment on track '+index;
+			// Create the HTML5 comment box 'textarea'
+			var trackCommentBox = document.createElement('textarea');
+			trackCommentBox.rows = '4';
+			trackCommentBox.cols = '100';
+			trackCommentBox.name = 'trackComment'+index;
+			trackCommentBox.className = 'trackComment';
+			var br = document.createElement('br');
+			// Add to the holder.
+			trackComment.appendChild(trackString);
+			trackComment.appendChild(br);
+			trackComment.appendChild(trackCommentBox);
+			feedbackHolder.appendChild(trackComment);
+		}
 		
 		// Create a slider per track
 		
@@ -497,6 +506,30 @@
 		canvas.appendChild(trackSliderObj);
 	});
 	
+	// Append any commentQuestion boxes
+	var commentQuestions = $(textXML).find('CommentQuestion');
+	$(commentQuestions).each(function(index,element) {
+		// Create document objects to hold the comment boxes
+		var trackComment = document.createElement('div');
+		trackComment.className = 'comment-div commentQuestion';
+		trackComment.id = element.attributes['id'].value;
+		// Create a string next to each comment asking for a comment
+		var trackString = document.createElement('span');
+		trackString.innerHTML = element.textContent;
+		// Create the HTML5 comment box 'textarea'
+		var trackCommentBox = document.createElement('textarea');
+		trackCommentBox.rows = '4';
+		trackCommentBox.cols = '100';
+		trackCommentBox.name = 'commentQuestion'+index;
+		trackCommentBox.className = 'trackComment';
+		var br = document.createElement('br');
+		// Add to the holder.
+		trackComment.appendChild(trackString);
+		trackComment.appendChild(br);
+		trackComment.appendChild(trackCommentBox);
+		feedbackHolder.appendChild(trackComment);
+	});
+	
 	// Now process any pre-test commands
 	
 	var preTest = $(testXMLSetups[id]).find('PreTest')[0];
@@ -583,6 +616,14 @@
 		var questionId = preTest.children[index].attributes['id'].value;
 		var questionHold = document.createElement('comment');
 		var questionResponse = document.getElementById(questionId + 'response');
+		var mandatory = preTest.children[index].attributes['mandatory'];
+		if (mandatory != undefined){
+			if (mandatory.value == 'true') {mandatory = true;}
+			else {mandatory = false;}
+		} else {mandatory = false;}
+		if (mandatory == true && questionResponse.value.length == 0) {
+			return index;
+		}
 		questionHold.id = questionId;
 		questionHold.innerHTML = questionResponse.value;
 		postPopupResponse(questionHold);
@@ -773,6 +814,13 @@
 	// Saves a specific test page
 	var xmlDoc = currentTestHolder;
 	// Check if any session wide metrics are enabled
+	
+	var commentShow = testXMLSetups[testId].attributes['elementComments'];
+	if (commentShow != undefined) {
+		if (commentShow.value == 'false') {commentShow = false;}
+		else {commentShow = true;}
+	} else {commentShow = true;}
+	
 	var metric = document.createElement('metric');
 	if (audioEngineContext.metric.enableTestTimer)
 	{
@@ -791,15 +839,17 @@
 		audioElement.url = currentTrackOrder[i].attributes['url'].value;
 		var value = document.createElement('value');
 		value.innerHTML = convSliderPosToRate(i);
-		var comment = document.createElement("comment");
-		var question = document.createElement("question");
-		var response = document.createElement("response");
-		question.textContent = commentObjects[i].children[0].textContent;
-		response.textContent = commentObjects[i].children[2].value;
-		comment.appendChild(question);
-		comment.appendChild(response);
+		if (commentShow) {
+			var comment = document.createElement("comment");
+			var question = document.createElement("question");
+			var response = document.createElement("response");
+			question.textContent = commentObjects[i].children[0].textContent;
+			response.textContent = commentObjects[i].children[2].value;
+			comment.appendChild(question);
+			comment.appendChild(response);
+			audioElement.appendChild(comment);
+		}
 		audioElement.appendChild(value);
-		audioElement.appendChild(comment);
 		// Check for any per element metrics
 		var metric = document.createElement('metric');
 		var elementMetric = audioEngineContext.audioObjects[i].metric;
@@ -855,6 +905,19 @@
 		audioElement.appendChild(metric);
 		xmlDoc.appendChild(audioElement);
 	}
+	var commentQuestion = document.getElementsByClassName('commentQuestion');
+	for (var i=0; i<commentQuestion.length; i++)
+	{
+		var cqHolder = document.createElement('CommentQuestion');
+		var comment = document.createElement('comment');
+		var question = document.createElement('question');
+		cqHolder.id = commentQuestion[i].id;
+		comment.textContent = commentQuestion[i].children[2].value;
+		question.textContent = commentQuestion[i].children[0].textContent;
+		cqHolder.appendChild(question);
+		cqHolder.appendChild(comment);
+		xmlDoc.appendChild(cqHolder);
+	}
 	testResultsHolders[testId] = xmlDoc;
 }
 
@@ -871,5 +934,4 @@
 	xmlDoc.appendChild(postTestQuestions);
 	
 	return xmlDoc;
-}
-
+}
\ No newline at end of file

--- a/apeTool.html	Wed Apr 22 10:05:11 2015 +0100
+++ b/apeTool.html	Wed Apr 22 11:00:58 2015 +0100
@@ -33,7 +33,7 @@
 		</script>
 		<!-- Uncomment the following script for automatic loading of projects -->
 		<script>
-			url = 'example_eval/project2.xml'; //Project XML document location
+			url = 'example_eval/project.xml'; //Project XML document location
 			loadProjectSpec(url);
 		</script>
 		

--- a/docs/SMC15/smc2015template.bbl	Wed Apr 22 10:05:11 2015 +0100
+++ b/docs/SMC15/smc2015template.bbl	Wed Apr 22 11:00:58 2015 +0100
@@ -21,6 +21,19 @@
 \providecommand{\BIBdecl}{\relax}
 \BIBdecl
 
+\bibitem{webaudioapi}
+W3C, ``Web audio api,'' 2015, \url{http://webaudio.github.io/web-audio-api/}
+  [Accessed 22nd April, 2015].
+
+\bibitem{webaudiodemo}
+------, ``Web audio / midi demo list,'' 2015,
+  \url{http://webaudio.github.io/demo-list/} [Accessed 22nd April, 2015].
+
+\bibitem{bbcradiophonics}
+B.~R\&D, ``Recreating the sounds of the bbc radiophonic workshop using the web
+  audio api,'' 2012, \url{http://webaudio.prototyping.bbc.co.uk/} [Accessed
+  22nd April, 2015].
+
 \bibitem{bech}
 S.~Bech and N.~Zacharov, \emph{Perceptual Audio Evaluation - Theory, Method and
   Application}.\hskip 1em plus 0.5em minus 0.4em\relax John Wiley \& Sons,
@@ -36,4 +49,8 @@
   coding systems}.\hskip 1em plus 0.5em minus 0.4em\relax Recommendation {ITU-R
   BS.1534-1}, 2003.
 
+\bibitem{mozdevSupportedMedia}
+Mozilla, ``Media formats supported by the html audio and video elements,''
+  2015.
+
 \end{thebibliography}

--- a/docs/SMC15/smc2015template.bib	Wed Apr 22 10:05:11 2015 +0100
+++ b/docs/SMC15/smc2015template.bib	Wed Apr 22 11:00:58 2015 +0100
@@ -26,3 +26,31 @@
 	Month = {April},
 	Title = {{APE}: {A}udio {P}erceptual {E}valuation toolbox for {MATLAB}},
 	Year = {2014}}
+
+@misc{webaudioapi,
+	Author = {W3C},
+	Title = {Web Audio API},
+	Year = {2015},
+	Note = {\url{http://webaudio.github.io/web-audio-api/} [Accessed 22nd April, 2015]}
+	}
+
+@misc{webaudiodemo,
+	Author = {W3C},
+	Title = {Web Audio / MIDI Demo List},
+	Year = {2015},
+	Note = {\url{http://webaudio.github.io/demo-list/} [Accessed 22nd April, 2015]}
+	}
+	
+@misc{bbcradiophonics,
+	Author = {BBC R\&D},
+	Title = {Recreating the sounds of the BBC Radiophonic Workshop using the Web Audio API},
+	Year = {2012},
+	Note = {\url{http://webaudio.prototyping.bbc.co.uk/} [Accessed 22nd April, 2015]}
+	}
+
+@misc{mozdevSupportedMedia,
+	Author = {Mozilla},
+	Title = {Media formats supported by the HTML audio and video elements},
+	Year = {2015},
+	Node = {\url{https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats} [Accessed 22nd April, 2015]}
+	}
\ No newline at end of file

--- a/docs/SMC15/smc2015template.tex	Wed Apr 22 10:05:11 2015 +0100
+++ b/docs/SMC15/smc2015template.tex	Wed Apr 22 11:00:58 2015 +0100
@@ -150,7 +150,11 @@
 
 TOTAL PAPER: Minimum 4 pages, 6 preferred, max. 8 (6 for demos/posters)\\ 
 
-NICK: examples of what kind of audio applications HTML5 has made possible, with references to publications (or website)\\
+%NICK: examples of what kind of audio applications HTML5 has made possible, with references to publications (or website)\\
+
+The Web Audio API is a high-level JavaScript API designed for real-time processing audio inside the browser through various processing nodes \cite{webaudioapi}. Various web sites have used the web audio API for either creative purposes, such as drum machines and score creation tools \cite{webaudiodemo}, %http://webaudio.github.io/demo-list/
+others from the list show real-time captured audio processing such as room reverberation tools and a phase vocoder from the system microphone. The BBC Radiophonic Workshop shows effects used on famous TV shows such as Doctor Who, being simulated inside the browser \cite{bbcradiophonics}. %http://webaudio.prototyping.bbc.co.uk/
+Another example is the BBC R\&D automatic compressor which applies a dynamic range compressor on a radio station which dynamically adjusts the compressor settings to match the listener envrionment. % The paper for this has not been released yet by AES...
 
 background (types of research where this type of perceptual evaluation of audio is relevant)\\
 
@@ -179,19 +183,19 @@
 
 %section with overview of the structure of the input and output files, perhaps with graph or table
 
-The tool runs entirely inside the browser through the new HTML5 Web Audio API. The API is supported by most major web browsers (with the exception of Internet Explorer) and allows for constructing a chain of audio processing elements to produce a high quality, real time signal process to manipulate audio streams. The API supports multi-channel processing and has an accurate playback timer for precise scheduled playback control. The Web Audio API is controlled through the browser JavaScript and is therefore highly controllable. The Web Audio API processing is all controlled in a separate thread to the main JavaScript thread, meaning there is no blocking due to real time processing. 
+The tool runs entirely inside the browser through the new HTML5 Web Audio API. The API is supported by most major web browsers (with the exception of Internet Explorer) and allows for constructing a chain of audio processing elements to produce a high quality, real time signal process to manipulate audio streams. The API supports multi-channel processing and has an accurate playback timer for precise scheduled playback control. The Web Audio API is controlled through the browser JavaScript and is therefore highly configurable. The Web Audio API processing is all controlled in a separate thread to the main JavaScript thread, meaning there is no blocking due to real time processing. 
 
 \subsection{Interface}\label{sec:interface} %elsewhere?
 
-At this point, we have implemented the interface of the MATLAB-based APE Perceptual Evaluation for Audio toolbox \cite{deman2014b}, which shows one marker for each simultaneously evaluated audio fragment on one or more horizontal axes (to rate/rank the respective fragments), as well as a comment box for every marker, and one extra text box for extra comments. See \ref{fig:interface} for an example of the interface, with 10 fragments and one axis. However, the back end of this test environment allows for many more established and novel interfaces for listening tests, particularly ones where the subject only assesses audio without manipulating it (i.e. method of adjustment, which would require additional features to be implemented). 
+At this point, we have implemented the interface of the MATLAB-based APE Perceptual Evaluation for Audio toolbox \cite{deman2014b}, which shows one marker for each simultaneously evaluated audio fragment on one or more horizontal axes (to rate/rank the respective fragments), as well as a comment box for every marker, and any extra text boxes for extra comments. See \ref{fig:interface} for an example of the interface, with 10 fragments and one axis. However, the back end of this test environment allows for many more established and novel interfaces for listening tests, particularly ones where the subject only assesses audio without manipulating it (i.e. method of adjustment, which would require additional features to be implemented). 
 
-\begin{figure*}[htbp]
-\begin{center}
-\includegraphics[width=0.9\textwidth]{interface.png}
-\caption{Example of interface, with 1 axis and 10 fragments}
-\label{fig:interface}
-\end{center}
-\end{figure*}
+%\begin{figure*}[htbp]
+%\begin{center}
+%\includegraphics[width=0.9\textwidth]{interface.png}
+%\caption{Example of interface, with 1 axis and 10 fragments}
+%\label{fig:interface}
+%\end{center}
+%\end{figure*}
 
 
 
@@ -199,40 +203,45 @@
 
 The web tool itself is split into several files to operate:
 \begin{itemize}
-\item \texttt{apeTool.html}: The main index file to load the scripts, this is the file the browser must request to load. 
+\item \texttt{apeTool.html}: The main index file to load the scripts, this is the file the browser must request to load. %This should be renamed index.html, but will wait until the file is renamed in the repo. 
 \item \texttt{core.js}: Contains functions and objects to manage the audio control, audio objects for testing and loading of files. 
 \item \texttt{ape.js}: Parses setup files to create the interface as instructed, following the same style chain as the MATLAB APE Tool \cite{deman2014b}.
 \end{itemize}
 
-The HTML file loads the \texttt{core.js} file with it along with a few other ancillary files (such as the jQuery JavaScript extensions), at which point the browser JavaScript begins to execute the on-page instructions, which gives the URL of the test setup XML document (outlined in the next section). \texttt{core.js} parses this document and executes the function in \texttt{ape.js} to build the web page with the given audio files. The reason for separating these two files is to allow for further interface designs (such as MUSHRA \cite{mushra} or A-B tests \cite{bech}) to be used, which would still require the same underlying core functions outlined in \texttt{core.js}, see also Section \ref{sec:interface}.
+The HTML file loads the \texttt{core.js} file along with a few other ancillary files (such as the jQuery JavaScript extensions)% should we cite jQuery.... https://jquery.com/
+, at which point the browser JavaScript begins to execute the on-page instructions, which gives the URL of the test setup XML document (outlined in the next section). \texttt{core.js} parses this document and executes the function in \texttt{ape.js} to build the web page with the given audio files. The reason for separating these two files is to allow for further interface designs (such as MUSHRA \cite{mushra} or A-B tests \cite{bech}) to be used, which would still require the same underlying core functions outlined in \texttt{core.js}, see also Section \ref{sec:interface}.
 
-The \texttt{ape.js} file has only two main functions: \textit{loadInterface(xmlDoc)} and \textit{interfaceXMLSave()}. The first function is called to build the interface once the setup document has been loaded. This includes creating the slider interface to rate the tracks, and creating the comment boxes below it. The markers on the slider at the top of the page are positioned randomly, to minimise the bias that may be introduced when the initial positions are near the beginning, end or middle of the slider. While another approach is to place the markers outside of the slider bar at first and have the subject drag them in, the authors believe this doesn't encourage careful consideration and comparison of the different fragments as the implicit goal of the test becomes to audition and drag each fragment in just once, rather than to compare all fragments rigorously. 
-\texttt{ape.js} also instructs the audio engine in \texttt{core.js} to create the audio objects. The audio objects are custom built audio nodes built on the Web Audio API. % 'built' twice?
-They consist of a \textit{bufferSourceNode} (a node which holds a buffer of audio samples for playback) and a \textit{gainNode}. These are then connected to the \textit{audioEngine} (itself a custom web audio node) containing a \textit{gainNode} (where the various Audio Objects connect to) for summation before passing the output to the \textit{destinationNode}, a fixed node created where %through which?
-the browser then passes the audio information to the system sound device. 
+The \texttt{ape.js} file has several main functions but the most important are \textit{loadInterface(xmlDoc)}, \textit{loadTest(id)}, \textit{pageXMLSave(testId)} and \textit{interfaceXMLSave()}. \textit{loadInterface(xmlDoc)} is called to decode the supplied project document in respect for the interface specified and define any global structures (such as the slider interface). It also identifies the number of pages in the test and randomises the order, if specified to do so. This is the only madatory function in any of the interface JavaScript files as this is called by \texttt{core.js} when the document is ready. The design style is such that \texttt{core.js} cannot 'see' any interface specific functions and therefore cannot assume any are available. Therefore the \textit{loadInterface(xmlDoc)} is very important to setup the entire test environment. It can therefore be assumed that the interface files can 'see' the \texttt{core.js} file and can therefore not only interact with it, but also modify it.
+
+Each test page is loaded using \textit{loadTest(id)} which performs two major tasks: to populate the interface with the slider elements and comment boxes; and secondly to load the audio fragments and construct the backend audio graph. The markers on the slider at the top of the page are positioned randomly, to minimise the bias that may be introduced when the initial positions are near the beginning, end or middle of the slider. While another approach is to place the markers outside of the slider bar at first and have the subject drag them in, the authors believe this doesn't encourage careful consideration and comparison of the different fragments as the implicit goal of the test becomes to audition and drag each fragment in just once, rather than to compare all fragments rigorously.
+
+\textit{loadTest(id)} in \texttt{ape.js} also instructs the audio engine in \texttt{core.js} to create the \textit{audioObject} These are custom audio nodes, one representing each audio element specified in each page.
+They consist of a \textit{bufferSourceNode} (a node which holds a buffer of audio samples for playback) and a \textit{gainNode}. There are various functions applied depending on metric collection which record the interaction with the audio element. These nodes are then connected to the \textit{audioEngine} (itself a custom web audio node) containing a \textit{gainNode} (where the various \textit{audioObject} connect to) for summation before passing the output to the \textit{destinationNode}, a permanent fixed node of the Web Audio API created as the master output where %through which?
+the browser then passes the audio information to the system sound device.
 % audio object/audioObject/Audio Object: consistency?
 
-When an \textit{audioObject} is created, it is given the URL of the audio sample to load. This is downloaded into the browser asynchronously using the \textit{XMLHttpRequest} object. This allows for downloading of any file into the JavaScript environment for further processing. It is particularly useful for the Web Audio API because it supports downloading of files in their binary form, allowing a perfect copy. % don't quite understand this
-Once the asynchronous download is complete, the file is then decoded using the Web Audio API offline decoder. This uses the browser's %browser's? browser-available? available in the browser?
- available decoding schemes to decode the audio files into raw float32 arrays, which are in turn passed to the relevant audioObject \textit{bufferSourceNode} for playback.
+When an \textit{audioObject} is created, it is given the URL of the audio sample to load. This is downloaded into the browser asynchronously using the \textit{XMLHttpRequest} object. This allows for downloading of any file into the JavaScript environment for further processing. It is particularly useful for the Web Audio API because it supports downloading of files in their binary form for decoding by the Web Audio offline decoder.
+Once the asynchronous download is complete, the file is then decoded using the Web Audio API offline decoder. This uses the browser available decoding schemes to decode the audio files into raw float32 arrays, which are in turn passed to the relevant audioObject \textit{bufferSourceNode} for playback.
 
-% GENERAL QUESTION: would it be hard to support more file types? If so, I think it's much nicer to say 'at the moment we allow ... and ... and ... files'
-Browsers support various audio file formats and are not consistent in any format. % 'not consistent in any format'? What do you mean exactly?
-However, all browsers support the WAV format. Although not a compact, web friendly format, most transport systems are of a high enough bandwidth this should not be a problem. 
-However, one problem is that the browser uses the sample rate assigned by the system sound device, % is this problem particular to WAV? Seems that way from the text
+Once each page of the test is completed, identified by pressing the Submit button, the \textit{pageXMLSave(testId)} is called to store all of the collected data until all pages of the test are completed. After the final test and any post-test questions are completed, the \textit{interfaceXMLSave()} function is called. This function generates the final XML file for submission as outlined in Section \ref{sec:setupresultsformats}.
+
+Browsers support various audio file formats and are not consistent in any format. Currently the Web Audio API is best supported in Chrome, Firefox, Opera and Safari. All of these support the use of the uncompressed WAV format. Although not a compact, web friendly format, most transport systems are of a high enough bandwidth this should not be a problem. Ogg Vorbis is another well supported format across the 4 supported major desktop browsers, as well as MP3 (although Firefox may not support all MP3 types) \cite{mozdevSupportedMedia}. %https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats
+One potential issue is that the browser uses the sample rate assigned by the system sound device, % is this problem particular to WAV? Seems that way from the text
 and does not have the ability to request a different one. Therefore, the default operation when an audio file is loaded with a different sample rate to that of the system is to convert the sample rate. To provide a check for this, the desired sample rate can be supplied with the setup XML and checked against. If the sample rates do not match, a browser alert window is shown asking for the sample rate to be correctly adjusted. 
-As this happens before any loading or decoding of audio files, the system will only fetch files as soon as the system's sample rate meets any requirements, avoiding requests for large files until they are actually needed. 
+As this happens before any loading or decoding of audio files, the system will only fetch files as soon as the system's sample rate meets any requirements, avoiding requests for large files until they are actually needed.
 
-During playback, the playback nodes loop indefinitely until playback is stopped. The gain nodes in the \textit{audioObject}s enable dynamic muting of nodes. When a bar in the sliding ranking is clicked, the audio engine mutes all \textit{audioObject}s and un-mutes the clicked one. Therefore, if the audio samples are perfectly aligned up and of the same sample length, they will remain perfectly aligned with each other.
-
+%During playback, the playback nodes loop indefinitely until playback is stopped. The gain nodes in the \textit{audioObject}s enable dynamic muting of nodes. When a bar in the sliding ranking is clicked, the audio engine mutes all \textit{audioObject}s and un-mutes the clicked one. Therefore, if the audio samples are perfectly aligned up and of the same sample length, they will remain perfectly aligned with each other.
+% Don't think this is relevant anymore
 
 \subsection{Setup and results formats}\label{sec:setupresultsformats}
 
-Setup and the results both use the common XML document format to outline the various parameters. The setup file contains all the information needed to initialise a test session. Several nodes can be defined to outline the audio samples to use, questions to be asked and any pre- or post-test questions or instructions. Having one document to modify allows for quick manipulation in a `human readable' form to create new tests, or adjust current ones, without needing to edit which web files. % 'which web files'?
+Setup and the results both use the common XML document format to outline the various parameters. The setup file determines which interface to use, the location of audio files, how many pages and other general setup rules to define the testing envrionment. Having one document to modify allows for quick manipulation in a `human readable' form to create new tests, or adjust current ones, without needing to edit multiple web files. % I mean the .js and .html files, though not sure if any better.
+The setup document has several defined nodes and structure which are documented with the source code. For example there is a section for general setup options where the pre-test and post-test questions and statements are defined:
 
-The results file is dynamically generated by the interface upon clicking the `Submit' button. This also executes checks, depending on the setup file, to ensure that all tracks have been played back, rated and commented on. The XML output returned contains a node per audioObject and contains both the corresponding marker's position and any comments written in the associated comment box. The rating returned is normalised to be a value between 0 and 1, normalising the pixel representation of different browser windows. 
+\texttt{<question id="location" mandatory="true"> Please enter your listening location \\ </question>}
 
-Pre- and post-test dialog boxes allow for comments or questions to be presented before or after the test, to convey listening test instructions, and gather information about the subject, listening environment, and overall experience of the test. These are automatically generated from the setup XML and allow nearly any form of question and comment to be included in a window on its own. Questions are stored and presented in the response section labelled `pretest' and `posttest', along with the question ID and its response, and can be made mandatory. 
+From the above example it can be seen that a question box should be generated, with the id 'location' and it is mandatory to answer. The question is in the PreTest node meaning it will appear before any testing will begin. When the result for the  entire test is shown, then this will appear in the PreTest node of the response with the id 'location' allowing it to be found easily. This outlines the importance of having clear and meaningful ID values. Pre- and post-test dialog boxes allow for comments or questions to be presented before or after the test, to convey listening test instructions, gather information about the subject, listening environment, and overall experience of the test.
+ 
 Further options in the setup file are: 
 
 \begin{itemize}
@@ -255,17 +264,48 @@
 
 % loop, snap to corresponding position, comments, 'general' comment, require same sampling rate, different types of randomisation
 
+The results file is dynamically generated by the interface upon clicking the `Submit' button. This also executes checks, depending on the setup file, to ensure that all tracks have been played back, rated and commented on. The XML output returned contains a node per audioObject and contains both the corresponding marker's position and any comments written in the associated comment box. The rating returned is normalised to be a value between 0 and 1, normalising the pixel representation of different browser windows.
 
+The results will also contain information collected by any defined pre/post questions. These are referenced against the setup XML by using the same ID so readable responses can be obtained. Taking from the earlier example of setting up a pre-test question, an example reponse would be shown as the following.
 
-The results will also contain information collected by any defined pre/post questions. These are referenced against the setup XML by using the same ID as well as printing in the same question, so readable responses can be obtained. Future development will also evolve to include any session data, such as the browser the tool was used in, how long the test took and any other metrics. Currently the results files are downloaded on the user side of the browser as a .xml file to be manually returned. However the end goal is to allow the XML files to be submitted over the web to a receiving server to store them, allowing for automated collection.
+\texttt{<comment id="location"> Queen Mary's \\ College </comment>}
 
-Furthermore, each user action (manipulation of any interface element, such as playback or moving a marker) is logged along with a the corresponding time code and stored or sent along with the results. % right? 
+Each page of testing is returned with the results of the entire page included in the structure. One 'audioElement' node is created per audio fragment per page, along with its ID. This includes several child nodes including the value holding the rating between 0 and 1, and any metrics collected. These include how long the element was listened for, the initial position, boolean flags if the element was listened to, if the element was moved and if the element comment box had any comment. Furthermore, each user action (manipulation of any interface element, such as playback or moving a marker) is logged along with a the corresponding time code and stored or sent along with the results.
+
+Future development will also evolve to include any session data, such as the browser the tool was used in. Currently the results files are downloaded on the user side of the browser as a .xml file to be manually returned. However the end goal is to allow the XML files to be submitted over the web to a receiving server to store them, allowing for automated collection.
+
+ % right? 
 
 %Here is an example of the setup XML and the results XML: % perhaps best to refer to each XML after each section (setup <> results)
 % Should we include an Example of the input and output XML structure?? --> Sure. 
 
-ADD XML STRUCTURE EXAMPLE
+An example of the returned \textit{audioElement} node in the results XML file is as follows.
 
+\texttt{<audioelement id="8"> \\
+<comment> \\
+<question>Comment on track 0</question> \\
+<response> The drums were punchy </response> \\
+</comment> \\
+<value> 0.25169491525423726 </value> \\
+<metric> \\
+<metricresult id="elementTimer"> \\ 2.3278004535147385< /metricresult> \\
+<metricresult id="elementTrackerFull"> \\
+<timepos id="0"> \\
+<time>1.7937414965986385</time> \\
+<position>0.41694915254237286</position> \\
+</timepos> \\
+<timepos id="1"> \\
+<time>2.6993197278911563</time> \\
+<position>0.45847457627118643</position> \\
+</timepos> \\</metricresult> \\
+<metricresult id="elementInitialPosition"> 0.47796610169491527 </metricresult> \\
+<metricresult id="elementFlagListenedTo"> true< /metricresult> \\
+<metricresult id="elementFlagMoved"> true </metricresult> \\
+</metric> \\
+</audioelement>}
+
+As can be seen, the parent tag \texttt{audioelement} holds the id of the element passed in from the setup document. The first child element is \texttt{comment} and holds both the question shown and the response from the comment box inside.
+The child element \texttt{value} holds the normalised ranking value. Next comes the metric node structure, there is one \texttt{metricresult} node per metric event collected. The id of the node identifies the type of data it contains. For example, the first holds the id \textit{elementTimer} and the data contained represents how long, in seconds, the audio element was listened to. The next holds the id \textit{elementTrackerFull} and contains a pair of elements per entry. This represents the entire movement of the elements' slider giving the time the event took place in seconds from when the current test page started, and the new position. In our example there are three \texttt{timepos} children with their id representing their order. There is one of these \texttt{audioelement} tags per audio element outlined on each test page. 
 
 \section{Conclusions and future work}\label{sec:conclusions}
 

--- a/example_eval/project.xml	Wed Apr 22 10:05:11 2015 +0100
+++ b/example_eval/project.xml	Wed Apr 22 11:00:58 2015 +0100
@@ -18,7 +18,7 @@
 			<metricEnable>elementFlagMoved</metricEnable>
 		</Metric>
 	</setup>
-	<audioHolder id='0' hostURL="example_eval/" sampleRate="44100" randomiseOrder='true' repeatCount='1' loop='true'>
+	<audioHolder id='0' hostURL="example_eval/" sampleRate="44100" randomiseOrder='true' repeatCount='1' loop='true' elementComments='true'>
 		<interface>
 			<title>Example Test Question</title>
 			<scale position="0">Min</scale>