changeset 281:7e9c38fa7499 Dev_main

Added mushra interface. Also added instructions for building your own interface (working copy).

--- a/ape.js	Mon Jul 27 16:08:52 2015 +0100
+++ b/ape.js	Tue Jul 28 12:00:46 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();

--- a/core.js	Mon Jul 27 16:08:52 2015 +0100
+++ b/core.js	Tue Jul 28 12:00:46 2015 +0100
@@ -613,6 +613,17 @@
 		css.href = 'ape.css';
 		
 		document.getElementsByTagName("head")[0].appendChild(css);
+	} else if (specification.interfaceType == "MUSHRA")
+	{
+		interfaceJS.setAttribute("src","mushra.js");
+		
+		// MUSHRA comes with a css file
+		var css = document.createElement('link');
+		css.rel = 'stylesheet';
+		css.type = 'text/css';
+		css.href = 'mushra.css';
+		
+		document.getElementsByTagName("head")[0].appendChild(css);
 	}
 	document.getElementsByTagName("head")[0].appendChild(interfaceJS);
 	

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Instructions/BuildingInterface.tex	Tue Jul 28 12:00:46 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

--- a/example_eval/project.xml	Mon Jul 27 16:08:52 2015 +0100
+++ b/example_eval/project.xml	Tue Jul 28 12:00:46 2015 +0100
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <BrowserEvalProjectDocument>
-	<setup interface="APE" projectReturn="/save" randomiseOrder='true' collectMetrics='true'>
+	<setup interface="MUSHRA" projectReturn="/save" randomiseOrder='true' collectMetrics='true'>
 		<PreTest>
 			<question id="Location" mandatory="true" boxsize="large">Please enter your location.</question>
 			<checkbox id="experience">

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mushra.css	Tue Jul 28 12:00:46 2015 +0100
@@ -0,0 +1,55 @@
+/*
+ * Hold any style information for MUSHRA interface. Customise if you like to make the interface your own!
+ * 
+ */
+body {
+	/* Set the background colour (note US English spelling) to grey*/
+	background-color: #ddd
+}
+
+div.pageTitle {
+	width: auto;
+	height: 20px;
+	margin-top: 20px;
+}
+
+div.pageTitle span{
+	font-size: 1.5em;
+}
+
+div.testHalt {
+	/* Specify any colouring during the test halt for pre/post questions */
+	background-color: rgba(0,0,0,0.5);
+	/* Don't mess with this bit */
+	z-index: 2;
+	width: 100%;
+	height: 100%;
+	position: absolute;
+	left: 0px;
+	top: 0px;
+}
+
+button {
+	/* Specify any button structure or style */
+	min-width: 20px;
+	background-color: #ddd
+}
+
+
+div.track-slider {
+	float: left;
+	width: 94px;
+	border: solid;
+	border-width: 1px;
+	border-color: black;
+	padding:2px;
+}
+
+input[type=range][orient=vertical]
+{
+    writing-mode: bt-lr; /* IE */
+    -webkit-appearance: slider-vertical; /* WebKit */
+    width: 8px;
+    height: 175px;
+    padding: 0 5px;
+}
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mushra.js	Tue Jul 28 12:00:46 2015 +0100
@@ -0,0 +1,334 @@
+/**
+ *  mushra.js
+ *  Create the MUSHRA interface
+ */
+
+// Once this is loaded and parsed, begin execution
+loadInterface();
+
+function loadInterface() {
+	// Get the dimensions of the screen available to the page
+	var width = window.innerWidth;
+	var height = window.innerHeight;
+	
+	// The injection point into the HTML page
+	interfaceContext.insertPoint = document.getElementById("topLevelBody");
+	var testContent = document.createElement('div');
+	testContent.id = 'testContent';
+	
+	// Create the top div for the Title element
+	var titleAttr = specification.title;
+	var title = document.createElement('div');
+	title.className = "title";
+	title.align = "center";
+	var titleSpan = document.createElement('span');
+	
+	// Set title to that defined in XML, else set to default
+	if (titleAttr != undefined) {
+		titleSpan.textContent = titleAttr;
+	} else {
+		titleSpan.textContent =  'Listening test';
+	}
+	// Insert the titleSpan element into the title div element.
+	title.appendChild(titleSpan);
+	
+	var pagetitle = document.createElement('div');
+	pagetitle.className = "pageTitle";
+	pagetitle.align = "center";
+	var titleSpan = document.createElement('span');
+	titleSpan.id = "pageTitle";
+	pagetitle.appendChild(titleSpan);
+	
+	// Create Interface buttons!
+	var interfaceButtons = document.createElement('div');
+	interfaceButtons.id = 'interface-buttons';
+	
+	// Create playback start/stop points
+	var playback = document.createElement("button");
+	playback.innerHTML = 'Stop';
+	playback.id = 'playback-button';
+	// onclick function. Check if it is playing or not, call the correct function in the
+	// audioEngine, change the button text to reflect the next state.
+	playback.onclick = function() {
+		if (audioEngineContext.status == 1) {
+			audioEngineContext.stop();
+			this.innerHTML = 'Stop';
+            var time = audioEngineContext.timer.getTestTime();
+            console.log('Stopped at ' + time); // DEBUG/SAFETY
+		}
+	};
+	// Create Submit (save) button
+	var submit = document.createElement("button");
+	submit.innerHTML = 'Submit';
+	submit.onclick = buttonSubmitClick;
+	submit.id = 'submit-button';
+	// Append the interface buttons into the interfaceButtons object.
+	interfaceButtons.appendChild(playback);
+	interfaceButtons.appendChild(submit);
+	
+	// Create a slider box
+	var sliderBox = document.createElement('div');
+	sliderBox.style.width = "100%";
+	sliderBox.style.height = window.innerHeight - 180 + 'px';
+	sliderBox.id = 'slider';
+	sliderBox.align = "center";
+	
+	// Global parent for the comment boxes on the page
+	var feedbackHolder = document.createElement('div');
+	feedbackHolder.id = 'feedbackHolder';
+	
+	testContent.style.zIndex = 1;
+	interfaceContext.insertPoint.innerHTML = null; // Clear the current schema
+	
+	// Inject into HTML
+	testContent.appendChild(title); // Insert the title
+	testContent.appendChild(pagetitle);
+	testContent.appendChild(interfaceButtons);
+	testContent.appendChild(sliderBox);
+	testContent.appendChild(feedbackHolder);
+	interfaceContext.insertPoint.appendChild(testContent);
+
+	// Load the full interface
+	testState.initialise();
+	testState.advanceState();
+}
+
+function loadTest(audioHolderObject)
+{
+	// Reset audioEngineContext.Metric globals for new test
+	audioEngineContext.newTestPage();
+	
+	// Delete any previous audioObjects associated with the audioEngine
+	audioEngineContext.audioObjects = [];
+	interfaceContext.deleteCommentBoxes();
+	interfaceContext.deleteCommentQuestions();
+	
+	var id = audioHolderObject.id;
+	
+	var feedbackHolder = document.getElementById('feedbackHolder');
+	var interfaceObj = audioHolderObject.interfaces;
+	
+	var sliderBox = document.getElementById('slider');
+	feedbackHolder.innerHTML = null;
+	sliderBox.innerHTML = null;
+	
+	var commentBoxPrefix = "Comment on track";
+	if (interfaceObj.commentBoxPrefix != undefined) {
+		commentBoxPrefix = interfaceObj.commentBoxPrefix;
+	}
+	
+	/// CHECK FOR SAMPLE RATE COMPATIBILITY
+	if (audioHolderObject.sampleRate != undefined) {
+		if (Number(audioHolderObject.sampleRate) != audioContext.sampleRate) {
+			var errStr = 'Sample rates do not match! Requested '+Number(audioHolderObject.sampleRate)+', got '+audioContext.sampleRate+'. Please set the sample rate to match before completing this test.';
+			alert(errStr);
+			return;
+		}
+	}
+	
+	var loopPlayback = audioHolderObject.loop;
+	
+	audioEngineContext.loopPlayback = loopPlayback;
+	
+	currentTestHolder = document.createElement('audioHolder');
+	currentTestHolder.id = audioHolderObject.id;
+	currentTestHolder.repeatCount = audioHolderObject.repeatCount;
+	
+	$(audioHolderObject.commentQuestions).each(function(index,element) {
+		var node = interfaceContext.createCommentQuestion(element);
+		feedbackHolder.appendChild(node.holder);
+	});
+	
+	// Find all the audioElements from the audioHolder
+	$(audioHolderObject.audioElements).each(function(index,element){
+		// Find URL of track
+		// In this jQuery loop, variable 'this' holds the current audioElement.
+		
+		// Now load each audio sample. First create the new track by passing the full URL
+		var trackURL = audioHolderObject.hostURL + element.url;
+		var audioObject = audioEngineContext.newTrack(element);
+		
+		var node = interfaceContext.createCommentBox(audioObject);
+		
+		// Create a slider per track
+		audioObject.interfaceDOM = new sliderObject(audioObject);
+		
+		// Distribute it randomnly
+		audioObject.interfaceDOM.slider.value = Math.random();
+		
+		sliderBox.appendChild(audioObject.interfaceDOM.holder);
+		audioObject.metric.initialised(audioObject.interfaceDOM.slider.value);
+        
+	});
+	
+	// Auto-align
+	var numObj = audioHolderObject.audioElements.length;
+	var totalWidth = (numObj-1)*150+100;
+	var diff = (window.innerWidth - totalWidth)/2;
+	audioEngineContext.audioObjects[0].interfaceDOM.holder.style.marginLeft = diff + 'px';
+}
+
+function sliderObject(audioObject)
+{
+	// Constructs the slider object. We use the HTML5 slider object
+	this.parent = audioObject;
+	this.holder = document.createElement('div');
+	this.title = document.createElement('span');
+	this.slider = document.createElement('input');
+	this.play = document.createElement('button');
+	
+	this.holder.className = 'track-slider';
+	this.holder.style.height = window.innerHeight-200 + 'px';
+	this.holder.appendChild(this.title);
+	this.holder.appendChild(this.slider);
+	this.holder.appendChild(this.play);
+	this.holder.align = "center";
+	this.holder.style.marginLeft = "50px";
+	this.holder.setAttribute('trackIndex',audioObject.id);
+	
+	this.title.textContent = audioObject.id;
+	this.title.style.width = "100%";
+	this.title.style.float = "left";
+	
+	this.slider.type = "range";
+	this.slider.min = "0";
+	this.slider.max = "1";
+	this.slider.step = "0.01";
+	this.slider.setAttribute('orient','vertical');
+	this.slider.style.float = "left";
+	this.slider.style.width = "100%";
+	this.slider.style.height = window.innerHeight-250 + 'px';
+	this.slider.onchange = function()
+	{
+		var time = audioEngineContext.timer.getTestTime();
+		var id = Number(this.parentNode.getAttribute('trackIndex'));
+		audioEngineContext.audioObjects[id].metric.moved(time,this.value);
+		console.log('slider '+id+' moved to '+this.value+' ('+time+')');
+	};
+	
+	this.play.textContent = "Play";
+	this.play.value = audioObject.id;
+	this.play.style.float = "left";
+	this.play.style.width = "100%";
+	this.play.onclick = function()
+	{
+		audioEngineContext.play();
+		if (audioEngineContext.audioObjectsReady) {
+			var id = Number(event.srcElement.value);
+			//audioEngineContext.metric.sliderPlayed(id);
+			audioEngineContext.play(id);
+		}
+	};
+	
+	this.enable = function() {
+		if (this.parent.state == 1)
+		{
+			$(this.slider).removeClass('track-slider-disabled');
+		}
+	};
+	
+	this.exportXMLDOM = function(audioObject) {
+		// Called by the audioObject holding this element. Must be present
+		var node = document.createElement('value');
+		node.textContent = this.slider.value;
+		return node;
+	};
+	this.getValue = function() {
+		return this.slider.value;
+	};
+}
+
+
+function buttonSubmitClick() // TODO: Only when all songs have been played!
+{
+	var checks = testState.currentStateMap[testState.currentIndex].interfaces[0].options;
+	var canContinue = true;
+	
+	// Check that the anchor and reference objects are correctly placed
+	if (interfaceContext.checkHiddenAnchor() == false) {return;}
+	if (interfaceContext.checkHiddenReference() == false) {return;}
+	/*
+	for (var i=0; i<checks.length; i++) {
+		if (checks[i].type == 'check')
+		{
+			switch(checks[i].check) {
+			case 'fragmentPlayed':
+				// Check if all fragments have been played
+				var checkState = interfaceContext.checkAllPlayed();
+				if (checkState == false) {canContinue = false;}
+				break;
+			case  'fragmentFullPlayback':
+				// Check all fragments have been played to their full length
+				var checkState = interfaceContext.checkAllPlayed();
+				if (checkState == false) {canContinue = false;}
+				console.log('NOTE: fragmentFullPlayback not currently implemented, performing check fragmentPlayed instead');
+				break;
+			case 'fragmentMoved':
+				// Check all fragment sliders have been moved.
+				var checkState = interfaceContext.checkAllMoved();
+				if (checkState == false) {canContinue = false;}
+				break;
+			case 'fragmentComments':
+				// Check all fragment sliders have been moved.
+				var checkState = interfaceContext.checkAllCommented();
+				if (checkState == false) {canContinue = false;}
+				break;
+			case 'scalerange':
+				// Check the scale is used to its full width outlined by the node
+				var checkState = interfaceContext.checkScaleRange();
+				if (checkState == false) {canContinue = false;}
+				break;
+			}
+
+		}
+		if (!canContinue) {break;}
+	}
+   */
+    if (canContinue) {
+	    if (audioEngineContext.status == 1) {
+	        var playback = document.getElementById('playback-button');
+	        playback.click();
+	    // This function is called when the submit button is clicked. Will check for any further tests to perform, or any post-test options
+	    } else
+	    {
+	        if (audioEngineContext.timer.testStarted == false)
+	        {
+	            alert('You have not started the test! Please press start to begin the test!');
+	            return;
+	        }
+	    }
+	    testState.advanceState();
+    } 
+}
+
+function pageXMLSave(store, testXML)
+{
+	// Saves a specific test page
+	var xmlDoc = store;
+	// Check if any session wide metrics are enabled
+	
+	var commentShow = testXML.elementComments;
+	
+	var metric = document.createElement('metric');
+	if (audioEngineContext.metric.enableTestTimer)
+	{
+		var testTime = document.createElement('metricResult');
+		testTime.id = 'testTime';
+		testTime.textContent = audioEngineContext.timer.testDuration;
+		metric.appendChild(testTime);
+	}
+	xmlDoc.appendChild(metric);
+	var audioObjects = audioEngineContext.audioObjects;
+	for (var i=0; i<audioObjects.length; i++) 
+	{
+		var audioElement = audioEngineContext.audioObjects[i].exportXMLDOM();
+		audioElement.setAttribute('presentedId',i);
+		xmlDoc.appendChild(audioElement);
+	}
+	
+	$(interfaceContext.commentQuestions).each(function(index,element){
+		var node = element.exportXMLDOM();
+		xmlDoc.appendChild(node);
+	});
+	store = xmlDoc;
+}