Mercurial > hg > webaudioevaluationtool

comparison docs/ProjectSpecificationDocument.tex @ 279:38f2df7badda Dev_main

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated the ProjectSpecificationDocument.
author Nicholas Jillings <nicholas.jillings@eecs.qmul.ac.uk>
date Sat, 25 Jul 2015 14:49:54 +0100
parents 086a10f85fde
children
comparison
equal deleted inserted replaced
277:724f72092fa7 279:38f2df7badda
26 26
27 \subsection{Attributes} 27 \subsection{Attributes}
28 \begin{itemize} 28 \begin{itemize}
29 \item \texttt{interface} - Mandatory, String. Defaults to APE, otherwise use to load any of the available interfaces. Currently only valid string is APE. 29 \item \texttt{interface} - Mandatory, String. Defaults to APE, otherwise use to load any of the available interfaces. Currently only valid string is APE.
30 \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. 30 \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.
31 \item \texttt{randomiseOrder} - Optional, default to false. Specify if the order of the tests can be randomised. 31 \item \texttt{randomiseOrder} - Optional, default to false. Specify if the order of the test pages are to be randomised.
32 \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. 32 \item \texttt{collectMetrics} - Deprecated. 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.
33 \end{itemize} 33 \end{itemize}
34 34
35 \subsection{Elements} 35 \subsection{Elements}
36 None 36 None
37 37
38 \section{AudioHolder tag}
39
40 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.
41
42 \subsection{Attributes}
43 \begin{itemize}
44 \item \texttt{id} - Mandatory, String. Give an ID string or number to identify the test in the result.
45 \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.
46 \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.
47 \item \texttt{randomiseOrder} - Optional, Boolean String. Defaults to false. Determine if the track order should be randomised. Must be true or false.
48 \item \texttt{repeatCount} - Optional, Number. Defaults to 0 (ie: no repeats). The number of times a test should be repeated.
49 \item \texttt{loop} - Optional, Boolean String. Defaults to false. Enable if audioElements should loop their playback or not.
50 \end{itemize}
51
52 \subsection{Elements}
53 Contain the audioElements tags and the interfaceSetup tag.
54
55 \section{audioElements tag}
56
57 This must reside as children in the audioHolder tag. There must be one audioElement tag per sound sample to load into the test.
58
59 \subsection{Attributes}
60 \begin{itemize}
61 \item \texttt{id} - Mandatory, String. Must give a string or number to identify each audio element. This id is used in the output to identify each track once randomised.
62 \item \texttt{url} - Mandatory, String. Contain the full URL to the track. If the Tracks tag hostURL is set, concatenate this tag with the hostURL attribute to obtain the full URL.
63 \end{itemize}
64
65 \section{interface tag}
66
67 This is contained within the audioHolder tag and outlines test instance specific requirements. These include the following children tags:
68 \begin{itemize}
69 \item 'title' - Contains the test title to be shown at the top of the page. Can only be one title node per interface.
70 \item 'scale' - Takes the attribute position to be a value between 0 and 100 indicating where on the scale to place the text contained inside. Can be multiple scale tags per interface.
71 \end{itemize}
72
73 \section {CommentQuestion tag}
74
75 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. The id attribute is set to keep track at the results XML.
76
77 \section {PreTest tag and PostTest tag}
78
79 These are 1st level tags. The PreTest tag allows for the specifying of pre test instructions and questions. These appear as a pop-up style window with next buttons and other automatic GUI. The postTest tag allows for specifying post test instructions, questions and resources. These appear as a pop-up style window after the submit button is pressed.
80
81 \subsection{Attributes}
82 None.
83
84 \subsection{Elements}
85 Takes the \texttt{statement} and \texttt{question} tags. The order these are presented in the XML define the order they appear on the screen.
86
87 \subsubsection{Statement}
88
89 The statement tag simply prints the included string verbatim on a 'pop-up' window with a next button.
90
91 \subsubsection{Question}
92
93 This allows for a question to be asked pre/post the test. This is added to the response XML in the same location as the other common/global questions. The response includes both the question asked and the response. This takes two attributes, id and mandatory. ID is a mandatory field. The same ID will be used in the results so it is important it is properly entered. Mandatory is optional. True means the field must be entered before continuing.
94
95 \subsubsection{Resource}
96
97 The resource tag is only available in the postTest tag. This allows for the linking to some external resource via the href attribute.
98
99 \section{Metric tag} 38 \section{Metric tag}
100 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. 39 A 'setup' node child tag, metrics must be declared in the setup tag. This takes a set of children 'metricEnable' to define which metrics to collect and present, for example \texttt{<metricEnable> testTimer </metricEnable>}. The interface may not be able to utilise all of these features. It is up to the interface to determine whether to use the metric or not. For example, 'elementFlagMoved' would not be usable in an AB test as there are no interface value objects.
101 40
102 \subsection{metricEnable tag} 41 \subsection{metricEnable tag}
103 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. 42 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.
104 \begin{itemize} 43 \begin{itemize}
105 \item testTimer - Return the global test timer and test instance timers. Measures the time between the first start and final submit. 44 \item testTimer - Return the global test timer and test instance timers. Measures the time between the first start and final submit.
109 \item elementFlagListenedTo - Return a boolean per elementck to see if the element was listened to 48 \item elementFlagListenedTo - Return a boolean per elementck to see if the element was listened to
110 \item elementFlagMoved - Return a boolean per element to see if the element slider was moved. 49 \item elementFlagMoved - Return a boolean per element to see if the element slider was moved.
111 \item elementFlagComments - Return a boolean per element to see if the element has comments. 50 \item elementFlagComments - Return a boolean per element to see if the element has comments.
112 \end{itemize} 51 \end{itemize}
113 52
114 \section{Feature List} 53 \section{Interface tag}
115 \begin{itemize} 54 This enables any interface options for each test page. Further interface tags in each audioHolder add further options. This takes option nodes only. Each option node takes a 'name' to determine what feature to enable. The following options are currently employed.
116 \item Paging listening tests - eg. Ask multiple questions in each experiment 55
117 \item Labels on X axis - scale 56 \subsection{Option nodes}
118 \item Input questions/comment at top to guide towards the question being asked. 57
119 \item Randomise track numbers -(inc. comment boxes and relate back to correct reference track) 58 \begin{itemize}
120 \item Randomise order of individual tests 59 \item \texttt{fragmentPlayed} - Enforce each fragment be partially played before finishing the page
121 \item Save output XML file to remote server 60 \item \texttt{fragmentFullPlayback} - Enforce each fragment to be fully played from start to end before finishing the page. Not enabled if an audioHolder reports it is to be looped playback.
122 \item Tests Metrics 61 \item \texttt{fragmentMoved} - Enforce each fragment to be moved at least once from its starting position.
123 \begin{itemize} 62 \item \texttt{fragmentComments} - Enforce each fragment comment to have some text entered.
124 \item Duration of listening to each track 63 \item \texttt{playhead} - Show the playhead object.
125 \item Time spent on each individual test 64 \item \texttt{page-count} - Show the current test page number and the total number
126 \item Start and end position of every track 65 \item \texttt{scalerange} - Must also have min and max values between 0 and 100. Enforce that at least one fragment is below the min value and one fragment is above the max value before continuing.
127 \item Flags on each track, to ensure each track (but may not restrict users from submitting) 66 \end{itemize}
128 \begin{itemize} 67
129 \item Has been listened to 68 \section{AudioHolder tag}
130 \item Has been moved 69
131 \item Has comments about it 70 There should be one audioHolder tag for each test page, inside which each audioElement is specified as children. The audioHolder tag can help to generalise certain objects.
132 \end{itemize} 71
133 \end{itemize} 72 \subsection{Attributes}
134 \end{itemize} 73 \begin{itemize}
135 74 \item \texttt{id} - Mandatory, String. Give an ID string or number to identify the test in the result.
136 \subsection{Advanced feature list} 75 \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.
137 \begin{itemize} 76 \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.
138 \item Repeat each tests number of times (2 or 3?) to remove learning / experience bias and ensure that the order is consistent 77 \item \texttt{randomiseOrder} - Optional, Boolean String. Defaults to false. Determine if the track order should be randomised. Must be true or false.
139 \item Perform Loudness equalisation on all tracks 78 \item \texttt{repeatCount} - Optional, Number. Defaults to 0 (ie: no repeats). The number of times a test should be repeated.
140 \item Selection of test type 79 \item \texttt{loop} - Optional, Boolean String. Defaults to false. Enable if audioElements should loop their playback or not.
141 \item Pre-test of some basic hearing test 80 \item \texttt{elementComments} - Optional, Boolean String. Defaults to false. Enable to populate the test page with Comment Boxes linked to each fragment.
142 \begin{itemize} 81 \end{itemize}
143 \item MUSHRA (with vertical slider per track) 82
144 \item APE (Single horizontal slider) 83 \subsection{Elements}
145 \item AB Test 84 Contain the audioElements tags and the interfaceSetup tag.
146 \end{itemize} 85
147 \end{itemize} 86 \section{audioElements tag}
148 87
149 88 This must reside as children in the audioHolder tag. There must be one audioElement tag per sound sample to load into the test.
89
90 \subsection{Attributes}
91 \begin{itemize}
92 \item \texttt{id} - Mandatory, String. Must give a string or number to identify each audio element. This id is used in the output to identify each track once randomised.
93 \item \texttt{url} - Mandatory, String. Contain the full URL to the track. If the Tracks tag hostURL is set, concatenate this tag with the hostURL attribute to obtain the full URL.
94 \item \texttt{type} - Optional, String. Can be 'normal', 'anchor', 'reference' or 'outside-reference'. Default is for normal. Only one anchor can be specified per page. Only one reference can be specified per page. Only one outside-reference can be specified per page. If multiple audioelements have the same type in the same page, the browser console will explain the problem and the audioelements will be treated as 'normal' fragments.
95 \end{itemize}
96
97 \section{interface tag}
98
99 This is contained within the audioHolder tag and outlines test instance specific requirements. These include the following children tags:
100 \begin{itemize}
101 \item 'title' - Contains the test title to be shown at the top of the page. Can only be one title node per interface.
102 \item 'scale' - Takes the attribute position to be a value between 0 and 100 indicating where on the scale to place the text contained inside. Can be multiple scale tags per interface.
103 \item 'option' - Can hold any of the option tags available in the setup tag. These will only be enabled for the page instance.
104 \end{itemize}
105
106 \section {CommentQuestion tag}
107
108 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. An id must be set, otherwise the result is undefined. Also the type must be set as follows.
109 \begin{itemize}
110 \item 'type="text"' - Default type. Creates a text box on the page. The text is included as the element.
111 \item 'type="radio"' - Create radio button entry. Multiple equally spaced entried per box. Only one entry can be selected. Each radio button is specified by an option tag. The tag must contain a name attribute, which will be the response if true. Optional text can be included as the element to label the box. Presented question is included in a statement node.
112 \item 'type="checkbox"' - Create a checkbox entry. Multiple equally space entries per box, multiple can be selected. Each checkbox is specified by an option tag. The tag must contain a name attribute. Optional text can be included as the element to label the checkbox. Presented question is included in a statement node.
113 \end{itemize}
114
115
116 \section {PreTest tag and PostTest tag}
117
118 These are 1st level tags. The PreTest tag allows for the specifying of pre test instructions and questions. These appear as a pop-up style window with next buttons and other automatic GUI. The postTest tag allows for specifying post test instructions, questions and resources. These appear as a pop-up style window after the submit button is pressed.
119
120 PreTest and PostTag nodes can be included in the audioHolders (for pre and post for that test page) and in the setup node for pre-test before the first page, and post-test for after the last test.
121
122 \subsection{Attributes}
123 None.
124
125 \subsection{Elements}
126
127 Takes the following available tags to structure the pre and post test options. The order these are presented in the XML define the order they appear.
128
129 \subsubsection{Statement}
130
131 The statement tag simply prints the included string verbatim on a 'pop-up' window with a next button.
132
133 \subsubsection{Question}
134
135 This allows for a question to be asked pre/post the test. The response includes both the question asked and the response. The following attributes are used:
136 \begin{itemize}
137 \item \texttt{id} - Mandatory, String. Used to reference to the response.
138 \item \texttt{mandatory} - Optional, String Boolean. Determine if this question must have some response. Defaults to false.
139 \item \texttt{boxsize} - Optional, String. Defaults to normal. Allows 'small', 'normal', 'large' or 'huge'. This determines the size of the box entry. All entries are wrappable, so this does not determine the maximum size of the text response, but can be used to encourage (or dicourage) long answers.
140 \end{itemize}
141
142 \subsubsection{Number}
143
144 Gives a number box entry defined with the following attributes:
145 \begin{itemize}
146 \item \texttt{id} - Mandatory, String. Used to reference to the response.
147 \item \texttt{mandatory} - Optional, String Boolean. Determine if this question must have some response. Defaults to false.
148 \item \texttt{min, max} - Optional, Number. Defaults to undefined. Used to bound the number response. If a number entered is below this, the pre/post sequence will not continued.
149 \end{itemize}
150
151 \subsubsection{Radio}
152
153 Create a set of radio boxes. Only one element can be returned as true. The radio node must have an id to reference for the output. The radio node also must have a statment node which will contain the text to show on the popup. Radio buttons are created using option nodes. Each node must have a name attribute to indentify which radio was selected in the response. The option node can also contain any text to link to the node.
154
155 \subsubsection{Checkbox}
156
157 Create a set of checkbox boxes. Multiple elements can be returned as true. The checkbox node must have an id to reference for the output. The checkbox node also must have a statment node which will contain the text to show on the popup. Checkbox buttons are created using option nodes. Each node must have a name attribute to indentify which radio was selected in the response. The option node can also contain any text to link to the node.
150 158
151 \section{Example} 159 \section{Example}
152 160
153 Here is an example XML structure 161 Here is an example XML structure
154 162