# HG changeset patch # User Nicholas Jillings # Date 1442308850 -3600 # Node ID 2b8c36924bfd7333f7e4cc00840b8833c9fc60af # Parent 57708aa826bb91b540d63c30ffdb0c78f0287c56# Parent 522a2ed8afa2bb170481327992ffa4c67dc9bb52 Merge from "dev_main". Added MUSHRA, PHP upload scripts, APE on Firefox, multi-screen support. Bug fixes #1370, #1298, #1391, #1300, #1389. diff -r 522a2ed8afa2 -r 2b8c36924bfd ape.js --- a/ape.js Fri Sep 04 12:22:55 2015 +0200 +++ b/ape.js Tue Sep 15 10:20:50 2015 +0100 @@ -3,12 +3,6 @@ * Create the APE interface */ -// preTest - In preTest state -// testRun-ID - In test running, test Id number at the end 'testRun-2' -// testRunPost-ID - Post test of test ID -// testRunPre-ID - Pre-test of test ID -// postTest - End of test, final submission! - // Once this is loaded and parsed, begin execution loadInterface(); @@ -89,7 +83,7 @@ var strNums = []; for (var i=0; i'; this.trackSliderObj.draggable = true; this.trackSliderObj.ondragend = dragEnd; + + this.trackSliderObj.ondragstart = function(event){ + event.dataTransfer.setData('Text',null); + }; + + this.trackSliderObj.ondrop = function(event) + { + if(event.stopPropagation) {event.stopPropagation();} + return false; + }; // Onclick, switch playback to that track - this.trackSliderObj.onclick = function() { - // Start the test on first click, that way timings are more accurate. - audioEngineContext.play(); - if (audioEngineContext.audioObjectsReady) { - // Cannot continue to issue play command until audioObjects reported as ready! - // Get the track ID from the object ID - var element; - if (event.srcElement.nodeName == "SPAN") { - element = event.srcElement.parentNode; - } else { - element = event.srcElement; - } - var id = Number(element.attributes['trackIndex'].value); - //audioEngineContext.metric.sliderPlayed(id); - audioEngineContext.play(id); - // Currently playing track red, rest green - - //document.getElementById('track-slider-'+index).style.backgroundColor = "#FF0000"; - $('.track-slider').removeClass('track-slider-playing'); - $(element).addClass('track-slider-playing'); - $('.comment-div').removeClass('comment-box-playing'); - $('#comment-div-'+id).addClass('comment-box-playing'); - var outsideReference = document.getElementById('outside-reference'); - if (outsideReference != undefined) - $(outsideReference).removeClass('track-slider-playing'); + this.trackSliderObj.onclick = function(event) { + // Cannot continue to issue play command until audioObjects reported as ready! + // Get the track ID from the object ID + var element; + if (event.currentTarget.nodeName == "SPAN") { + element = event.currentTarget.parentNode; + } else { + element = event.currentTarget; } + var id = Number(element.attributes['trackIndex'].value); + //audioEngineContext.metric.sliderPlayed(id); + audioEngineContext.play(id); + // Currently playing track red, rest green + + //document.getElementById('track-slider-'+index).style.backgroundColor = "#FF0000"; + $('.track-slider').removeClass('track-slider-playing'); + $(element).addClass('track-slider-playing'); + $('.comment-div').removeClass('comment-box-playing'); + $('#comment-div-'+id).addClass('comment-box-playing'); + var outsideReference = document.getElementById('outside-reference'); + if (outsideReference != undefined) + $(outsideReference).removeClass('track-slider-playing'); }; this.enable = function() { @@ -512,7 +514,11 @@ var marginSize = Number(slider.attributes['marginsize'].value); var w = slider.style.width; w = Number(w.substr(0,w.length-2)); - var x = ev.x; + var x = ev.screenX; + + x += Math.abs(window.screenX); + x = x % window.outerWidth; + if (x >= marginSize && x < w+marginSize) { this.style.left = (x)+'px'; } else { @@ -523,12 +529,12 @@ } } var time = audioEngineContext.timer.getTestTime(); - var id = Number(ev.srcElement.getAttribute('trackindex')); - audioEngineContext.audioObjects[id].metric.moved(time,convSliderPosToRate(ev.srcElement)); - console.log('slider '+id+' moved to '+convSliderPosToRate(ev.srcElement)+' ('+time+')'); + var id = Number(ev.currentTarget.getAttribute('trackindex')); + audioEngineContext.audioObjects[id].metric.moved(time,convSliderPosToRate(ev.currentTarget)); + console.log('slider '+id+' moved to '+convSliderPosToRate(ev.currentTarget)+' ('+time+')'); } -function buttonSubmitClick() // TODO: Only when all songs have been played! +function buttonSubmitClick() { var checks = testState.currentStateMap[testState.currentIndex].interfaces[0].options; var canContinue = true; diff -r 522a2ed8afa2 -r 2b8c36924bfd core.css --- a/core.css Fri Sep 04 12:22:55 2015 +0200 +++ b/core.css Tue Sep 15 10:20:50 2015 +0100 @@ -24,7 +24,8 @@ border:#444444; border-style:solid; border-width:1px; - width: 624px; + max-width: 600px; + min-width: 400px; float: left; margin: 5px; height: 90px; @@ -36,7 +37,8 @@ div.popupHolder { width: 500px; - height: 250px; + min-height: 250px; + max-height: 400px; background-color: #fff; border-radius: 10px; box-shadow: 0px 0px 50px #000; @@ -48,7 +50,7 @@ */ width: 50px; height: 25px; - position: absolute; + position: relative; border-radius: 5px; border: #444; border-width: 1px; @@ -57,8 +59,10 @@ } textarea.trackComment { - width: 618px; + max-width: 594px; + min-width: 350px; margin-right:15px; + max-height: 60px; } div.playhead { diff -r 522a2ed8afa2 -r 2b8c36924bfd core.js --- a/core.js Fri Sep 04 12:22:55 2015 +0200 +++ b/core.js Tue Sep 15 10:20:50 2015 +0100 @@ -49,6 +49,8 @@ // Creates an object to manage the popup this.popup = null; this.popupContent = null; + this.popupTitle = null; + this.popupResponse = null; this.buttonProceed = null; this.buttonPrevious = null; this.popupOptions = null; @@ -70,24 +72,53 @@ this.popupContent = document.createElement('div'); this.popupContent.id = 'popupContent'; - this.popupContent.style.marginTop = '25px'; + this.popupContent.style.marginTop = '20px'; this.popupContent.align = 'center'; this.popup.appendChild(this.popupContent); + var titleHolder = document.createElement('div'); + titleHolder.id = 'popupTitleHolder'; + titleHolder.style.width = 'inherit'; + titleHolder.style.height = '25px'; + titleHolder.style.marginBottom = '5px'; + + this.popupTitle = document.createElement('span'); + this.popupTitle.id = 'popupTitle'; + titleHolder.appendChild(this.popupTitle); + this.popupContent.appendChild(titleHolder); + + this.popupResponse = document.createElement('div'); + this.popupResponse.id = 'popupResponse'; + this.popupResponse.style.width = 'inherit'; + this.popupResponse.style.minHeight = '170px'; + this.popupResponse.style.maxHeight = '320px'; + this.popupResponse.style.overflow = 'auto'; + this.popupContent.appendChild(this.popupResponse); + + var buttonHolder = document.createElement('div'); + buttonHolder.id='buttonHolder'; + buttonHolder.width = 'inherit'; + buttonHolder.style.height= '30px'; + buttonHolder.align = 'left'; + this.popupContent.appendChild(buttonHolder); + this.buttonProceed = document.createElement('button'); this.buttonProceed.className = 'popupButton'; - this.buttonProceed.style.left = '440px'; - this.buttonProceed.style.top = '215px'; + this.buttonProceed.style.left = '390px'; + this.buttonProceed.style.top = '2px'; this.buttonProceed.innerHTML = 'Next'; this.buttonProceed.onclick = function(){popup.proceedClicked();}; this.buttonPrevious = document.createElement('button'); this.buttonPrevious.className = 'popupButton'; this.buttonPrevious.style.left = '10px'; - this.buttonPrevious.style.top = '215px'; + this.buttonPrevious.style.top = '2px'; this.buttonPrevious.innerHTML = 'Back'; this.buttonPrevious.onclick = function(){popup.previousClick();}; + buttonHolder.appendChild(this.buttonPrevious); + buttonHolder.appendChild(this.buttonProceed); + this.popup.style.zIndex = -1; this.popup.style.visibility = 'hidden'; blank.style.zIndex = -2; @@ -126,19 +157,20 @@ var blank = document.getElementsByClassName('testHalt')[0]; blank.style.zIndex = -2; blank.style.visibility = 'hidden'; + this.buttonPrevious.style.visibility = 'inherit'; }; this.postNode = function() { // This will take the node from the popupOptions and display it var node = this.popupOptions[this.currentIndex]; - this.popupContent.innerHTML = null; + this.popupResponse.innerHTML = null; if (node.type == 'statement') { - var span = document.createElement('span'); - span.textContent = node.statement; - this.popupContent.appendChild(span); + this.popupTitle.textContent = null; + var statement = document.createElement('span'); + statement.textContent = node.statement; + this.popupResponse.appendChild(statement); } else if (node.type == 'question') { - var span = document.createElement('span'); - span.textContent = node.question; + this.popupTitle.textContent = node.question; var textArea = document.createElement('textarea'); switch (node.boxsize) { case 'small': @@ -158,18 +190,11 @@ textArea.rows = "10"; break; } - var br = document.createElement('br'); - this.popupContent.appendChild(span); - this.popupContent.appendChild(br); - this.popupContent.appendChild(textArea); - this.popupContent.childNodes[2].focus(); + this.popupResponse.appendChild(textArea); + textArea.focus(); } else if (node.type == 'checkbox') { - var span = document.createElement('span'); - span.textContent = node.statement; - this.popupContent.appendChild(span); - var optHold = document.createElement('div'); - optHold.id = 'option-holder'; - optHold.align = 'left'; + this.popupTitle.textContent = node.statement; + var optHold = this.popupResponse; for (var i=0; i 0) - this.popupContent.appendChild(this.buttonPrevious); + this.buttonPrevious.style.visibility = 'visible'; + else + this.buttonPrevious.style.visibility = 'hidden'; }; this.initState = function(node) { @@ -278,7 +292,7 @@ } } else if (node.type == 'checkbox') { // Must extract checkbox data - var optHold = document.getElementById('option-holder'); + var optHold = this.popupResponse; var hold = document.createElement('checkbox'); console.log("Checkbox: "+ node.statement); hold.id = node.id; @@ -293,7 +307,7 @@ } this.responses.appendChild(hold); } else if (node.type == "radio") { - var optHold = document.getElementById('option-holder'); + var optHold = this.popupResponse; var hold = document.createElement('radio'); var responseID = null; var i=0; @@ -549,16 +563,6 @@ specification.decode(); testState.stateMap.push(specification.preTest); - - // New check if we need to randomise the test order - if (specification.randomiseOrder) - { - specification.audioHolders = randomiseOrder(specification.audioHolders); - for (var i=0; i audioHolders.length) + { + console.log('Warning: You have specified '+audioHolders.length+' tests but requested '+this.testPages+' be completed!'); + this.testPages = audioHolders.length; + } + var aH = this.audioHolders; + this.audioHolders = []; + for (var i=0; i= 600) + { + boxwidth = 600; + } + else if (boxwidth < 400) + { + boxwidth = 400; + } + this.trackComment.style.width = boxwidth+"px"; + this.trackCommentBox.style.width = boxwidth-6+"px"; + }; + this.resize(); }; this.commentQuestions = []; @@ -1781,6 +1829,21 @@ console.log("Response: "+root.textContent); return root; }; + this.resize = function() + { + var boxwidth = (window.innerWidth-100)/2; + if (boxwidth >= 600) + { + boxwidth = 600; + } + else if (boxwidth < 400) + { + boxwidth = 400; + } + this.holder.style.width = boxwidth+"px"; + this.textArea.style.width = boxwidth-6+"px"; + }; + this.resize(); }; this.radioBox = function(commentQuestion) { @@ -1805,15 +1868,11 @@ this.span.style.marginTop = '15px'; var optCount = commentQuestion.options.length; - var spanMargin = Math.floor(((600-(optCount*100))/(optCount))/2)+'px'; - console.log(spanMargin); for (var i=0; i= 600) + { + boxwidth = 600; + } + else if (boxwidth < 400) + { + boxwidth = 400; + } + this.holder.style.width = boxwidth+"px"; + var text = this.holder.children[2]; + var options = this.holder.children[3]; + var optCount = options.children.length; + var spanMargin = Math.floor(((boxwidth-20-(optCount*80))/(optCount))/2)+'px'; + var options = options.firstChild; + var text = text.firstChild; + options.style.marginRight = spanMargin; + options.style.marginLeft = spanMargin; + text.style.marginRight = spanMargin; + text.style.marginLeft = spanMargin; + while(options.nextSibling != undefined) + { + options = options.nextSibling; + text = text.nextSibling; + options.style.marginRight = spanMargin; + options.style.marginLeft = spanMargin; + text.style.marginRight = spanMargin; + text.style.marginLeft = spanMargin; + } + }; + this.resize(); }; this.checkboxBox = function(commentQuestion) { @@ -1889,15 +1979,11 @@ this.span.style.marginTop = '15px'; var optCount = commentQuestion.options.length; - var spanMargin = Math.floor(((600-(optCount*100))/(optCount))/2)+'px'; - console.log(spanMargin); for (var i=0; i= 600) + { + boxwidth = 600; + } + else if (boxwidth < 400) + { + boxwidth = 400; + } + this.holder.style.width = boxwidth+"px"; + var text = this.holder.children[2]; + var options = this.holder.children[3]; + var optCount = options.children.length; + var spanMargin = Math.floor(((boxwidth-20-(optCount*80))/(optCount))/2)+'px'; + var options = options.firstChild; + var text = text.firstChild; + options.style.marginRight = spanMargin; + options.style.marginLeft = spanMargin; + text.style.marginRight = spanMargin; + text.style.marginLeft = spanMargin; + while(options.nextSibling != undefined) + { + options = options.nextSibling; + text = text.nextSibling; + options.style.marginRight = spanMargin; + options.style.marginLeft = spanMargin; + text.style.marginRight = spanMargin; + text.style.marginLeft = spanMargin; + } + }; + this.resize(); }; this.createCommentBox = function(audioObject) { diff -r 522a2ed8afa2 -r 2b8c36924bfd docs/Instructions/BuildingInterface.tex --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/Instructions/BuildingInterface.tex Tue Sep 15 10:20:50 2015 +0100 @@ -0,0 +1,60 @@ +\documentclass[11pt, oneside]{article} % use "amsart" instead of "article" for AMSLaTeX format +\usepackage[margin=2cm]{geometry} % See geometry.pdf to learn the layout options. There are lots. +\geometry{letterpaper} % ... or a4paper or a5paper or ... +%\geometry{landscape} % Activate for rotated page geometry +\usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent +\usepackage{graphicx} % Use pdf, png, jpg, or eps§ with pdflatex; use eps in DVI mode + % TeX will automatically convert eps --> pdf in pdflatex + +\usepackage{listings} % Source code +\usepackage{amssymb} +\usepackage{cite} +\usepackage{hyperref} % Hyperlinks + + +\graphicspath{{img/}} % Relative path where the images are stored. + +\title{Building your own Interface for\\ Web Audio Evaluation Tool} +\author{Nicholas Jillings} +\date{} % Activate to display a given date or no date + +\begin{document} +\maketitle + +\section{Introduction} +This guide will help you to construct your own interface on top of the WAET (Web Audio Evaluation Tool) engine. The WAET engine resides in the core.js file, this contains prototype objects to handle most of the test creation, operation and data collection. The interface simply has to link into this at the correct points. + +\subsection{Nodes to familiarise} +Core.js handles several very important nodes which you should become familiar with. The first is the Audio Engine, initialised and stored in variable 'AudioEngineContext'. This handles the playback of the web audio nodes as well as storing the 'AudioObjects'. The 'AudioObjects' are custom nodes which hold the audio fragments for playback. These nodes also have a link to two interface objects, the comment box if enabled and the interface providing the ranking. On creation of an 'AudioObject' the interface link will be nulled, it is up to the interface to link these correctly. + +The specification document will be decoded and parsed into an object called 'specification'. This will hold all of the specifications various nodes. The test pages and any pre/post test objects are processed by a test state which will proceed through the test when called to by the interface. Any checks (such as playback or movement checks) are to be completed by the interface before instructing the test state to proceed. The test state will call the interface on each page load with the page specification node. + +\subsection{Modifying Core.js} +Whilst there is very little code actually needed, you do need to instruct core.js to load your interface file when called for from a specification node. There is a function called 'loadProjectSpecCallback' which handles the decoding of the specification and setting any external items (such as metric collection). At the very end of this function there is an if statement, add to this list with your interface string to link to the source. There is an example in there for both the APE and MUSHRA tests already included. Note: Any updates to core.js in future work will most likely overwrite your changes to this file, so remember to check your interface is still here after any update that interferes with core.js. +Any further files can be loaded here as well, such as css styling files. jQuery is already included. + +\section{Building the Interface} +Your interface file will get loaded automatically when the 'interface' attribute of the setup node matches the string in the 'loadProjectSpecCallback' function. The following functions must be defined in your interface file. +\begin{itemize} +\item \texttt{loadInterface} - Called once when the document is parsed. This creates any necessary bindings, such as to the metric collection classes and any check commands. Here you can also start the structure for your test such as placing in any common nodes (such as the title and empty divs to drop content into later). +\item \texttt{loadTest(audioHolderObject)} - Called for each page load. The audioHolderObject contains a specification node holding effectively one of the audioHolder nodes. +\item \texttt{resizeWindow(event)} - Handle for any window resizing. Simply scale your interface accordingly. This function must be here, but can me an empty function call. +\end{itemize} + +\subsection{loadInterface} +This function is called by the interface once the document has been parsed since some browsers may parse files asynchronously. The best method is simply to put 'loadInterface()' at the top of your interface file, therefore when the JavaScript engine is ready the function is called. + +By default the HTML file has an element with id "topLevelBody" where you can build your interface. Make sure you blank the contents of that object. This function is the perfect time to build any fixed items, such as the page title, session titles, interface buttons (Start, Stop, Submit) and any holding and structure elements for later on. + +At the end of the function, insert these two function calls: testState.initialise() and testState.advanceState();. This will actually begin the test sequence, including the pre-test options (if any are included in the specification document). + +\subsection{loadTest(audioHolderObject)} +This function is called on each new test page. It is this functions job to clear out the previous test and set up the new page. Use the function audioEngineContext.newTestPage(); to instruct the audio engine to prepare for a new page. "audioEngineContext.audioObjects = [];" will delete any audioObjects, interfaceContext.deleteCommentBoxes(); will delete any comment boxes and interfaceContext.deleteCommentQuestions(); will delete any extra comment boxes specified by commentQuestion nodes. + +This function will need to instruct the audio engine to build each fragment. Just passing the constructor each element from the audioHolderObject will build the track, audioEngineContext.newTrack(element) (where element is the audioHolderObject audio element). This will return a reference to the constructed audioObject. Decoding of the audio will happen asynchronously. + +You also need to link audioObject.interfaceDOM with your interface object for that audioObject. The interfaceDOM object has a few default methods. Firstly it must start disabled and become enabled once the audioObject has decoded the audio (function call: enable()). Next it must have a function exportXMLDOM(), this will return the xml node for your interface, however the default is for it to return a value node, with textContent equal to the normalised value. You can perform other functions, but our scripts may not work if something different is specified (as it will breach our results specifications). Finally it must also have a method getValue, which returns the normalised value. + +It is also the job the interfaceDOM to call any metric collection functions necessary, however some functions may be better placed outside (for example, the APE interface uses drag and drop, therefore the best way was to call the metric functions from the dragEnd function, which is called when the interface object is dropped). Metrics based upon listening are handled by the audioObject. The interfaceDOM object must manage any movement metrics. For a list of valid metrics and their behaviours, look at the project specification document included in the repository/docs location. The same goes for any checks required when pressing the submit button, or any other method to proceed the test state. + +\end{document} \ No newline at end of file diff -r 522a2ed8afa2 -r 2b8c36924bfd docs/Instructions/User Guide.tex --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/Instructions/User Guide.tex Tue Sep 15 10:20:50 2015 +0100 @@ -0,0 +1,75 @@ +\documentclass[11pt, oneside]{article} % use "amsart" instead of "article" for AMSLaTeX format +\usepackage{geometry} % See geometry.pdf to learn the layout options. There are lots. +\geometry{letterpaper} % ... or a4paper or a5paper or ... +%\geometry{landscape} % Activate for rotated page geometry +\usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent +\usepackage{graphicx} % Use pdf, png, jpg, or eps§ with pdflatex; use eps in DVI mode + % TeX will automatically convert eps --> pdf in pdflatex + +\usepackage{listings} % Source code +\usepackage{amssymb} +\usepackage{cite} +\usepackage{hyperref} % Hyperlinks + +\graphicspath{{img/}} % Relative path where the images are stored. + +\title{Web Audio Evaluation Tool \\User Guide} +\date{} % Activate to display a given date or no date + +\begin{document} +\maketitle + +These instructions are about use of the Web Audio Evaluation Tool \cite{deman2015c}. +Version 1.0 + +\tableofcontents + +\section{Installing} + +The tool can be downloaded from the SoundSoftware website, available at \url{https://code.soundsoftware.ac.uk/projects/webaudioevaluationtool/repository}. The repository contains all the files required by the tool, along with interfaces to post bug reports or issue any feature requests. + +Once downloaded and extracted (either through a Mercurial client or the available zip download) the tool is ready to be operated with. The tool is designed for three modes of use: +\begin{itemize} +\item Single Location, One User - A listening test which will be conducted in a single location, one user at a time. Possibly on a machine with no network or internet connectivity +\item Single Location, Multiple Users - Similar to the above but where the hosting server is located behind a networked firewall which all test machines can access +\item Multiple Location, Multiple Users - A test operated over the web by multiple end users +\end{itemize} +There are other modes of use which we cannot document due to the flexible nature of the test. If your test does not mostly fit into one of these three categories, have a look in the Advanced Test section. + +\subsection{Python} + +To trial the test before deployment, or if you are performing a test on a non-networked machine, you will need to run our python script to launch a local python web server. This script is designed for Python 2.7. Running the script will open a basic web server, hosting the directory it is contained in. Visit \url{http://localhost:8080/} to launch the test instance once the server is running. To quit the server, either close the terminal window or press Ctrl+C on your keyboard to forcibly shut the server. + +If your system already uses port 8080 and you wish to use the server, please read the Advanced Test Creation section. + +\section{Designing a Test} + +The test specification document is an XML file containing all the information the tool requires to operate your test. No coding in JavaScript or HTML is needed to get this test running. + + + +\subsection{Using the test create tool} +We have supplied a test creation tool, available in the repository directory test\_creation. This tool is a self-contained web page, so doubling clicking will launch the page in your system default browser. + +The test creation tool can help you build a simple test very quickly. By simply selecting your interface and clicking check-boxes you can build a test in minutes. + +Audio is handled by directing the tool to where + +The tool examines your XML before exporting to ensure you do not export an invalid XML structure which would crash the test. + +\subsection{Setting up the test directory} + +\section{Launching and operating} + +\section{Advanced Test Creation} +\subsection{Multi-User} +\subsection{3rd Party Server} + +\section{Errors and Troubleshooting} +\subsection{Common Errors} +\subsection{Forcing an Export} +\subsection{Terminal} + +\section{Future Work} + +\end{document} \ No newline at end of file diff -r 522a2ed8afa2 -r 2b8c36924bfd docs/ProjectSpecificationDocument.pdf Binary file docs/ProjectSpecificationDocument.pdf has changed diff -r 522a2ed8afa2 -r 2b8c36924bfd docs/ProjectSpecificationDocument.tex --- a/docs/ProjectSpecificationDocument.tex Fri Sep 04 12:22:55 2015 +0200 +++ b/docs/ProjectSpecificationDocument.tex Tue Sep 15 10:20:50 2015 +0100 @@ -28,16 +28,46 @@ \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. +\item \texttt{randomiseOrder} - Optional, default to false. Specify if the order of the test pages are to be randomised. +\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. \end{itemize} \subsection{Elements} None +\section{Metric tag} +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{ testTimer }. 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. + +\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{Interface tag} +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. + +\subsection{Option nodes} + +\begin{itemize} +\item \texttt{fragmentPlayed} - Enforce each fragment be partially played before finishing the page +\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. +\item \texttt{fragmentMoved} - Enforce each fragment to be moved at least once from its starting position. +\item \texttt{fragmentComments} - Enforce each fragment comment to have some text entered. +\item \texttt{playhead} - Show the playhead object. +\item \texttt{page-count} - Show the current test page number and the total number +\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. +\end{itemize} + \section{AudioHolder tag} -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. +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. \subsection{Attributes} \begin{itemize} @@ -47,6 +77,7 @@ \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. \item \texttt{loop} - Optional, Boolean String. Defaults to false. Enable if audioElements should loop their playback or not. +\item \texttt{elementComments} - Optional, Boolean String. Defaults to false. Enable to populate the test page with Comment Boxes linked to each fragment. \end{itemize} \subsection{Elements} @@ -60,6 +91,7 @@ \begin{itemize} \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. \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. +\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. \end{itemize} \section{interface tag} @@ -68,21 +100,31 @@ \begin{itemize} \item 'title' - Contains the test title to be shown at the top of the page. Can only be one title node per interface. \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. +\item 'option' - Can hold any of the option tags available in the setup tag. These will only be enabled for the page instance. \end{itemize} \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. The id attribute is set to keep track at the results XML. +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. +\begin{itemize} +\item 'type="text"' - Default type. Creates a text box on the page. The text is included as the element. +\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. +\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. +\end{itemize} + \section {PreTest tag and PostTest tag} 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. +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. + \subsection{Attributes} None. \subsection{Elements} -Takes the \texttt{statement} and \texttt{question} tags. The order these are presented in the XML define the order they appear on the screen. + +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. \subsubsection{Statement} @@ -90,63 +132,29 @@ \subsubsection{Question} -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. - -\subsubsection{Resource} - -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. +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: \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. +\item \texttt{id} - Mandatory, String. Used to reference to the response. +\item \texttt{mandatory} - Optional, String Boolean. Determine if this question must have some response. Defaults to false. +\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. \end{itemize} -\section{Feature List} +\subsubsection{Number} + +Gives a number box entry defined with the following attributes: \begin{itemize} -\item Paging listening tests - eg. Ask multiple questions in each experiment -\item Labels on X axis - scale -\item Input questions/comment at top to guide towards the question being asked. -\item Randomise track numbers -(inc. comment boxes and relate back to correct reference track) -\item Randomise order of individual tests -\item Save output XML file to remote server -\item Tests Metrics -\begin{itemize} -\item Duration of listening to each track -\item Time spent on each individual test -\item Start and end position of every track -\item Flags on each track, to ensure each track (but may not restrict users from submitting) -\begin{itemize} -\item Has been listened to -\item Has been moved -\item Has comments about it -\end{itemize} -\end{itemize} +\item \texttt{id} - Mandatory, String. Used to reference to the response. +\item \texttt{mandatory} - Optional, String Boolean. Determine if this question must have some response. Defaults to false. +\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. \end{itemize} -\subsection{Advanced feature list} -\begin{itemize} -\item Repeat each tests number of times (2 or 3?) to remove learning / experience bias and ensure that the order is consistent -\item Perform Loudness equalisation on all tracks -\item Selection of test type -\item Pre-test of some basic hearing test -\begin{itemize} -\item MUSHRA (with vertical slider per track) -\item APE (Single horizontal slider) -\item AB Test -\end{itemize} -\end{itemize} +\subsubsection{Radio} +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. +\subsubsection{Checkbox} + +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. \section{Example} diff -r 522a2ed8afa2 -r 2b8c36924bfd example_eval/project.xml --- a/example_eval/project.xml Fri Sep 04 12:22:55 2015 +0200 +++ b/example_eval/project.xml Tue Sep 15 10:20:50 2015 +0100 @@ -1,6 +1,6 @@ - + Please enter your location. @@ -35,10 +35,7 @@ elementListenTracker -