changeset 712:fef9e8337cfd

Merge and rebuild pdf.

Binary file docs/ProjectSpecificationDocument.pdf has changed

--- a/docs/ProjectSpecificationDocument.tex	Thu Apr 09 17:16:20 2015 +0100
+++ b/docs/ProjectSpecificationDocument.tex	Fri Apr 10 10:20:52 2015 +0100
@@ -33,6 +33,8 @@
 \begin{itemize}
 \item \texttt{interface} - Mandatory, String. Defaults to APE, otherwise use to load any of the available interfaces. Currently only valid string is APE.
 \item \texttt{projectReturn} - Mandatory, String. Specify the URL to return the test results. If null client will generate XML locally and prompt user to return the file.
+\item \texttt{randomiseOrder} - Optional, default to false. Specify if the order of the tests can be randomised.
+\item \texttt{collectMetrics} - Optional, Boolean. Default to false. Determine if the test metrics should be collected. These include how long each test session took etc. The full metrics list can be modified in the 'metrics' tag.
 \end{itemize}
 
 \subsection{Elements}
@@ -40,17 +42,19 @@
 
 \section{AudioHolder tag}
 
-There should be one audioHolder tag, inside which each audioElement is specified as children. The audioHolder tag can help to generalise certain objects.
+There should be one audioHolder tag per test session, inside which each audioElement is specified as children. The audioHolder tag can help to generalise certain objects. Each audioHolder instance specifies a separate listening test to be paged, each with their own specific requirements.
 
 \subsection{Attributes}
 \begin{itemize}
+\item \texttt{id} - Mandatory, String. Give an ID string or number to identify the test in the result.
 \item \texttt{hostURL} - Optional, String. If all tracks are hosted from the same folder on a server, you can put in the lead here. For instance, if loading http://test.com/tracks/track1.wav and http://test.com/tracks/track2.wav, this could equal http://test.com/tracks/ and the url attribute in the track tag can be track1.wav or track2.wav. Equally http://test.com/ and then using tracks/track1.wav and tracks/track2.wav is valid.
 \item \texttt{sampleRate} - Optional, Number. If your test requires a specific sample rate, this should be set to the desired sample rate in Hertz. This does not set the browser to the correct sample rate, but forces the browser to check the sample rate matches. If this is undefined, no sample rate matching will occur.
-\item \texttt{sampleRateExplicit} - Optional, DEPRECATED. A true/false to determine if the sample rate given in the attribute \texttt{sampleRate} must be matched by the system. If the web audio API does not match, a browser alert is called and the rest of the interface loading is discarded. Media files are also not downloaded until this check can be corrected.
+\item \texttt{randomiseOrder} - Optional, Boolean String. Defaults to false. Determine if the track order should be randomised. Must be true or false.
+\item \texttt{repeatCount} - Optional, Number. Defaults to 0 (ie: no repeats). The number of times a test should be repeated.
 \end{itemize}
 
 \subsection{Elements}
-Contain the audioElements tags.
+Contain the audioElements tags and the interfaceSetup tag.
 
 \section{audioElements tag}
 
@@ -62,6 +66,10 @@
 \item \texttt{ID} - Optional, Number. Give the track a specific ID for the return. This will help if using multiple projects to spread a test across multiple sessions and/or locations, where each test will not use all the samples. If one audioElement is given the ID 3, the next audioElement (assuming it does not have an ID set itself) will have the ID of 4. This continues until the next audioElement with the ID attribute set is reached.
 \end{itemize}
 
+\section{interfaceSetup}
+
+This is contained within the audioHolder tag and outlines test instance specific requirements. These include the following children tags: title - question title at the top of the page, scaleMin - minimum scale value text, scaleMax - maximum scale value text, scaleMid - halfway scale value text. There is also a preTest tag here allowing for specific questions/statements to be presented before running this specific test.
+
 \section {CommentQuestion tag}
 
 This is a 1st level tag (same level as AudioHolder and setup). This allows another question and comment box to be presented on the page. The results of these are passed back in the results XML with both the comment and the question.
@@ -94,6 +102,21 @@
 
 The resource tag is only available in the postTest tag. This allows for the linking to some external resource via the href attribute.
 
+\section{Metric tag}
+A 1st level tag, metrics must be declared in the setup tag. This takes a set of children 'metricEnable' to define which metrics to collect and present.
+
+\subsection{metricEnable tag}
+This takes a single attribute to determine which metric to enable for collection. Some of these are a global, per track or per test instance.
+\begin{itemize}
+\item testTimer - Return the global test timer and test instance timers. Measures the time between the first start and final submit.
+\item elementTimer - Return the total time each audioElement in each test was listened too. Measures time between successive clicks on the track changer
+\item elementTracker - Return the initial position of each track
+\item elementTrackerFull - Return an enumerated pair of time and position. Track the entire movement of each element position. NOTE: Will override the elementTracker option above and throw an error into the browser console.
+\item elementFlagListenedTo - Return a boolean per elementck to see if the element was listened to
+\item elementFlagMoved - Return a boolean per element to see if the element slider was moved.
+\item elementFlagComments - Return a boolean per element to see if the element has comments.
+\end{itemize}
+
 \section{Feature List}
 \begin{itemize}
 \item Paging listening tests - eg. Ask multiple questions in each experiment

Binary file docs/ResultsSpecificationDocument.pdf has changed

--- a/docs/ResultsSpecificationDocument.tex	Thu Apr 09 17:16:20 2015 +0100
+++ b/docs/ResultsSpecificationDocument.tex	Fri Apr 10 10:20:52 2015 +0100
@@ -14,28 +14,47 @@
 \section{Root}
 The root of the document is \texttt{BrowserEvaluationResult}.
 
-\section{AudioElement}
-A 1st level node, this contains the results for a specific audioElement.
+\section{testReults}
+A 1st level node, contains all the results from a specific test instance defined by the audioHolder objects in the setup XML. Takes the audioElement as its children to define a full test and any test metrics.
 
 \subsection{Attributes}
+\begin{itemize}
+\item \texttt{id} - The ID given to audioHolder in the project setup XML.
+\item \texttt{repeatCount} - Specifies the repeat count of the test, there will be one testResult per test per repeat, this will help identify which repeat.
+\end{itemize}
+
+\subsection{AudioElement}
+A 2nd level node, this contains the results for a specific audioElement.
+
+\subsubsection{Attributes}
 Has the following attributes, depending on the variables set in the Project Specification.
 \begin{itemize}
 \item \texttt{id} - Mandatory. This returns the ID of the track in question. This is either the value passed in from the project specification, or calculated based on the position in the list. For instance, in the automatic system, the first test sample has ID 0, the second ID 1 and so forth. The value passed in from the project specification can either be a string or a Number.
 \item \texttt{url} - Mandatory. Returns the full URL given incase of errors or for later checking.
 \end{itemize}
 
-\subsection{Value}
+\subsubsection{Value}
 One of these elements per track, containing the value between 0 and 100 relating the user rating of the track. This is a mandatory element.
 % float or int? (I, Brecht, am sort of indifferent here, it used to be down to .01 or something before, so maybe that or .1)
 % Nick - Can be a float, was trying to remove/reduce ambiguity from pixel position. But can easily make it to .01
 
-\subsection{Comment}
+\subsubsection{Comment}
 One of these elements per track, containing any commenting data from the interface text boxes. Has the two following child nodes.
 \begin{itemize}
 \item \texttt{Question} - Returns the text next to the comment box
 \item \texttt{Response} - Returns the text in the comment box
 \end{itemize}
 
+\subsubsection{metrics}
+One of these holders per audioElement, containing the results from any of the enabled per element metrics in metricResult tags. The ID of each element represents the metricEnable tag element. The inner value contains the results.
+
+% Will list specific response structures per metric!
+
+\subsection{metrics}
+One of these holders per testResults tag, containing the results from any of the enabled per test metrics in metricResult tags. The ID of each element represents the metricEnable tag element. The inner value contains the results.
+
+% Will list specific response structures per metric!
+
 \section{PreTest and PostTest}
 A 1st level node, contains the response to any pre-test questions given in the project specification. These are stored in the same Comment node as outlined in the above audioElement.