Index of /cjtest01/beaqlejs03_without audio folder/

Name	Last Modified	Size
Parent Directory
config	2018-09-18 11:12	-
css	2018-09-18 11:00	-
img	2018-09-18 11:00	-
js	2018-09-18 11:00	-
tools	2018-09-18 11:00	-
web_service	2018-09-18 11:00	-
CHANGELOG.md	2018-09-18 11:00	4k
index - Copy.html	2018-09-18 11:00	8k
intro.html	2018-09-18 11:00	4k
LICENSE.txt	2018-09-18 11:00	36k
test.html	2018-09-18 11:00	8k

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Style-Type" content="text/css" /> <meta name="generator" content="pandoc" /> <title></title> <style type="text/css">code{white-space: pre;}</style> <style type="text/css"> div.sourceCode { overflow-x: auto; } table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { margin: 0; padding: 0; vertical-align: baseline; border: none; } table.sourceCode { width: 100%; line-height: 100%; } td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } td.sourceCode { padding-left: 5px; } code > span.kw { color: #007020; font-weight: bold; } /* Keyword */ code > span.dt { color: #902000; } /* DataType */ code > span.dv { color: #40a070; } /* DecVal */ code > span.bn { color: #40a070; } /* BaseN */ code > span.fl { color: #40a070; } /* Float */ code > span.ch { color: #4070a0; } /* Char */ code > span.st { color: #4070a0; } /* String */ code > span.co { color: #60a0b0; font-style: italic; } /* Comment */ code > span.ot { color: #007020; } /* Other */ code > span.al { color: #ff0000; font-weight: bold; } /* Alert */ code > span.fu { color: #06287e; } /* Function */ code > span.er { color: #ff0000; font-weight: bold; } /* Error */ code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ code > span.cn { color: #880000; } /* Constant */ code > span.sc { color: #4070a0; } /* SpecialChar */ code > span.vs { color: #4070a0; } /* VerbatimString */ code > span.ss { color: #bb6688; } /* SpecialString */ code > span.im { } /* Import */ code > span.va { color: #19177c; } /* Variable */ code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code > span.op { color: #666666; } /* Operator */ code > span.bu { } /* BuiltIn */ code > span.ex { } /* Extension */ code > span.pp { color: #bc7a00; } /* Preprocessor */ code > span.at { color: #7d9029; } /* Attribute */ code > span.do { color: #ba2121; font-style: italic; } /* Documentation */ code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ </style> </head> <body> <div id="header"> <h1 class="title">BeaqleJS Documentation</h1> </div> Table of contents <ol style="list-style-type: decimal"> <li><a href="#1-description">Description</a></li> <li><a href="#2-basic-setup">Basic Setup</a></li> <li><a href="#3-test-configuration">Test Configuration</a></li> <li><a href="#4-browser-support">Browser Support</a></li> <li><a href="#5-online-submission">Online Submission</a></li> <li><a href="#6-internals">Internals</a></li> <li><a href="#7-contact">Contact</a></li> <li><a href="#8-license">License</a></li> </ol> <h1 id="description">1. Description</h1> BeaqleJS (browser based evaluation of audio quality and comparative listening environment) provides a framework to create browser based listening tests and is purely based on open web standards like HTML5 and Javascript. Therefore, the test runs in any modern web browser and allows an easy distribution of the test environment to a significant amount of participants in combination with simple configuration. Currently it supports ABX and MUSHRA style test procedures but can be easily extended to other test schemes. To get a better impression about its functionality there are two demo test sites for the ABX and MUSHRA test classes: <ul> <li><a href="http://hsu-ant.github.io/beaqlejs/demo/abx/" class="uri">http://hsu-ant.github.io/beaqlejs/demo/abx/</a></li> <li><a href="http://hsu-ant.github.io/beaqlejs/demo/mushra/" class="uri">http://hsu-ant.github.io/beaqlejs/demo/mushra/</a></li> </ul> BeaqleJS has been presented at the <a href="http://lac.linuxaudio.org/2014/">Linux Audio Conference 2014</a> at the ZKM in Karlsruhe, Germany. The original <a href="http://lac.linuxaudio.org/2014/papers/26.pdf">paper</a> and presentation <a href="http://lac.linuxaudio.org/2014/download/SKraft_BeaqleJS.pdf">slides</a> are available from the conference archive. However, meanwhile most of the paper content has been updated and merged into this documentation. If you want to cite BeaqleJS in a publication please use <blockquote> S. Kraft, U. Zölzer: "BeaqleJS: HTML5 and JavaScript based Framework for the Subjective Evaluation of Audio Quality", Linux Audio Conference, 2014, Karlsruhe, Germany </blockquote> as a reference or link to our GitHub repository <blockquote> https://github.com/HSU-ANT/beaqlejs </blockquote> <h1 id="basic-setup">2. Basic Setup</h1> <ol style="list-style-type: decimal"> <li>Download the test scripts <ul> <li>you can either get a stable release from <a href="https://github.com/HSU-ANT/beaqlejs/releases" class="uri">https://github.com/HSU-ANT/beaqlejs/releases</a></li> <li>or clone the git repository <code>git clone https://github.com/HSU-ANT/beaqlejs.git</code></li> <li>or simply download a zip of the current HEAD revision at <a href="https://github.com/HSU-ANT/beaqlejs/archive/master.zip" class="uri">https://github.com/HSU-ANT/beaqlejs/archive/master.zip</a></li> </ul></li> <li>Uncomment the line where the desired test class is initialized and loaded in the header of the <code>index.html</code> file. <div class="sourceCode"><pre class="sourceCode html"><code class="sourceCode html"><script type="text/javascript"> var testHandle; window.onload=function() { // Uncomment one of the following lines to choose the desired test class //testHandle = new MushraTest(TestConfig); // <= MUSHRA test class //testHandle = new AbxTest(TestConfig); // <= ABX test class }; </script></code></pre></div></li> <li>Prepare a config file and set its path in the prepared <code><script></script></code> tag in the header of the <code>index.html</code> file. <div class="sourceCode"><pre class="sourceCode html"><code class="sourceCode html"> <script src="config/YOUR_CONFIG.js" type="text/javascript"></script> </code></pre></div> Two example config files for the MUSHRA and ABX test class are already supplied in the <code>config/</code> folder to serve as a starting point. Detailed information about the different test classes and configuration can be found below.</li> </ol> <h2 id="docker-webserver">2.1 Docker Webserver</h2> Docker allows you to easily setup a webserver with PHP in order to run and test BeaqleJS locally on your computer. More information about Docker can be found at <code>https://www.docker.com/</code>. <h3 id="manual-setup">2.1.1 Manual Setup</h3> Create a container for the first time and mount your configured BeaqleJS folder into the container. <pre><code>$> docker run -d -p 80:80 -v /path/to/BeaqleJS:/var/www/html --name beaqlejs-server php:7.0-apache</code></pre> You can then access BeaqleJS at <code>http://localhost/</code>. Please note that this runs a public webserver on your machine which is accessible by everyone in your local network. Therefore, it is advised to stop the Docker container when it is not needed anymore. You can stop the Docker container by <pre><code>$> docker stop beaqlejs-server</code></pre> and restart it again with <pre><code>$> docker start beaqlejs-server</code></pre> The current state of all available Docker containers can be investigated by <pre><code>$> docker ps -a</code></pre> <h3 id="docker-compose">2.1.2 Docker Compose</h3> <a href="https://docs.docker.com/compose/install/">Docker Compose</a> is a tool to run a server application from a simple configuration file. Go to the directory with the <code>docker-compose.yml</code> file in the BeaqleJS file tree: <pre><code>$> cd tools/Docker/</code></pre> Create a container for the first time and initialize it: <pre><code>$> docker-compose up</code></pre> Start and stop an existing service: <pre><code>$> docker-compose start $> docker-compose stop</code></pre> Completely remove the service: <pre><code>$> docker-compose down</code></pre> The status of the service can be inspected with: <pre><code>$> docker-compose ps </code></pre> <h1 id="test-configuration">3. Test Configuration</h1> <h2 id="general-options">3.1 General Options</h2> The available options can be divided into a set of general options which apply to all test classes and other options, including file declarations, that are specific for a single test class. <div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">var TestConfig = { "TestName": "My Listening Test", // <= Name of the test "LoopByDefault": true, // <= Enable looped playback by default "AutoReturnByDefault": true, // <= Always start playback from loop/track begin "ShowFileIDs": false, // <= Show file IDs for debugging (never // enable this during real test!) "ShowResults": false, // <= Show table with test results at the end "EnableABLoop": true, // <= Show controls to loop playback with an // AB range slider "EnableOnlineSubmission": false, // <= Enable transmission of JSON encoded // results to a web service "BeaqleServiceURL": "", // <= URL of the web service "SupervisorContact": "", // <= Email address of supervisor to contact for // help or for submission of results by email "RandomizeTestOrder": true, // <= Present test sets in a random order "MaxTestsPerRun": -1, // <= Only run a random subset of all available // tests, set to -1 to disable "Testsets": [ {...}, {...}, ... ], // <= Definition of test sets and files, more // details below }</code></pre></div> <h2 id="abx">3.2 ABX</h2> In an ABX test three items named A, B and X are presented to the listener, whereas X is randomly selected to be either the same as A or B. The listener has to identify which item is hidden behind X, or which one (A or B) is closest to X. If the listener is able to find the correct item, it reveals that there are perceptual differences between A and B. A typical application of ABX tests would be the evaluation of the transparency of audio codecs. For example item A could be an unencoded audio snippet and B is the same snippet but encoded with a lossy codec. When the listener is not able to identify if A or B was hidden in X (results are randomly distributed), one can assume that the audio coding was transparent <div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">... // <= General options "Testsets": [ { "Name": "Schubert", // <= Name of the test set "TestID": "id1_1", // <= Unique test set ID, necessary for internal "Files": { // <= Array with test files "A": "audio/schubert_ref.wav", // <= File A "B": "audio/schubert_2.wav", // <= File B } }, { ... }, // <= Next test set starts here .... ]</code></pre></div> <h2 id="mushra">3.3 MUSHRA</h2> In a MUSHRA test (ITU-R BS.1116-1) the listener gets presented an item marked as reference together with several anonymous test items. By using a slider for each test item he has to rate how close the items are to the reference on top. Among the test items there is usually also one hidden reference and one, or several, anchor signals to prove the validity of the ratings and the qualification of the participants. Contrary to ABX tests the MUSHRA procedure allows more detailed evaluations as it is possible to compare more than one algorithm to a reference. Furthermore, the results are on a continuous scale allowing a direct numerical comparison of all algorithms under test. <div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">... // <= General options "RateMinValue": 0, // <= Minimum rating "RateMaxValue": 100, // <= Maximum rating "RateDefaultValue":0, // <= Default rating "RequireMaxRating": false, // <= At least one of the ratings in a testset // has to be at the maximum value "Testsets": [ { "Name": "Schubert 1", // <= Name of the test set "TestID": "id1_1", // <= Unique test set ID, necessary for // internal referencing "Files": { // <= Array with test files "Reference": "audio/ref.wav", // <= Every MUSHRA test set needs exactly // one(!) file with a "Reference" label "label_1": "audio/algo_1.wav", // <= Various files to be tested, the labels "label_2": "audio/algo_2.wav", // can be freely chosen as desired but "label_3": "audio/algo_3.wav", // have to be unique inside a test set "anchor": "audio/algo_anc.wav", // ... } }, { ... }, // <= Next test set starts here .... ]</code></pre></div> <h1 id="browser-support">4. Browser Support</h1> BeaqleJS in general will run well in any recent web browser out in the wild. The only noteworthy exceptions are the Internet Explorer versions below 9 which still have a market share of a few percent and unfortunately miss the required FileAPI. Participants will get a warning if they open the listening test with one of these old versions. <h2 id="required-html5-features">4.1 Required HTML5 Features</h2> <ul> <li>Audio playback using HTML5 is widely supported by all major browsers since many years (<a href="http://caniuse.com/#feat=audio">list browsers</a>).</li> <li>FileAPI-Blob is necessary to provide the listening test results as a virtual download to be saved on the local harddisk. This API can be expected to be available in every browser released in the last years (<a href="http://caniuse.com/#feat=blobbuilder">list browsers</a>).</li> </ul> Optionally: <ul> <li>WebAudioAPI is used in BeaqleJS for smooth fade in/out at start/stop of playback and at the loop borders. It is available in every major browser apart from the Internet Explorer (<a href="http://caniuse.com/#feat=audio-api">list browsers</a>). Due to different bugs and inconsistencies in the WebAudioAPI, smooth fade in/out is not guaranteed to work equally well on all browsers. Best results were obtained with browsers based on the Chromium engine.</li> </ul> <h2 id="codecs">4.2 Codecs</h2> Although most browsers today support the HTML5 <code><audio></code> tag, the supported formats and codecs vary a lot. Unfortunately, support for lossless compression like FLAC has not yet reached a sufficient spread. The only lossless, but also uncompressed, format widely accepted is WAV PCM with 16 bit sample precision. Solely the Internet Explorer is not capable to play back this file type. The following table lists the minimum browser version required for different audio formats: <table> <thead> <tr class="header"> <th>Format</th> <th>IE</th> <th>Edge</th> <th>Firefox</th> <th>Chrome</th> <th>Opera</th> <th>Safari</th> </tr> </thead> <tbody> <tr class="odd"> <td>WAV PCM</td> <td>no</td> <td>12</td> <td>3.5</td> <td>8</td> <td>11.5</td> <td>3.2</td> </tr> <tr class="even"> <td>FLAC</td> <td>no</td> <td>16</td> <td>51</td> <td>56</td> <td>42</td> <td>11, OSX > 10.13</td> </tr> <tr class="odd"> <td>Ogg Vorbis</td> <td>no</td> <td>17</td> <td>3.5</td> <td>4</td> <td>11.5</td> <td>XiphQT</td> </tr> <tr class="even"> <td>MP3</td> <td>9.0</td> <td>12</td> <td>22</td> <td>4</td> <td>15</td> <td>4</td> </tr> <tr class="odd"> <td>ACC</td> <td>9.0</td> <td>12</td> <td>22*</td> <td>12</td> <td>15</td> <td>4</td> </tr> </tbody> </table> (* not on all platforms, requires a pre-installed codec) Source <code>canisue.com</code>: * <a href="http://caniuse.com/#feat=wav">WAV PCM</a> * <a href="http://caniuse.com/#feat=flac">FLAC</a> * <a href="http://caniuse.com/#feat=ogg-vorbis">Ogg Vorbis</a> * <a href="http://caniuse.com/#feat=mp3">MP3</a> * <a href="http://caniuse.com/#feat=aac">AAC</a> <h1 id="online-submission">5. Online Submission</h1> BeaqleJS can send the test results in JSON format to a web service to collect them in a central place. An exemplary server side PHP script which can be used to receive and store the results is included in the <code>web_service/</code> subfolder. It only requires a webspace with PHP >= 5.6. <h2 id="setup">5.1 Setup</h2> <ol style="list-style-type: decimal"> <li>Upload the file <code>web_service/beaqleJS_Service.php</code> to a webserver. Create a folder named <code>results/</code> next to the PHP script and make sure that the webserver has write permissions on it.</li> <li>Try to execute the script in your browser. For example, point your browser to <code>http://yourdomain.com/mysubfolder/beaqleJS_Service.php</code>. The script performs a self-test and checks PHP version and write permission of the <code>results/</code> folder.</li> <li>Enable online submission in the BeaqleJS config (<code>"EnableOnlineSubmission": true</code>) and set the <code>BeaqleServiceURL</code> to <code>http://yourdomain.com/mysubfolder/beaqleJS_Service.php</code>.</li> </ol> <h2 id="security">5.2 Security</h2> As with every public web service it is important to be aware about security aspects. In the current implementation there is no possibility to authenticate submitters, therefore everyone can potentially submit spoofed results if he is able to do some basic reverse engineering! However, this is also a common risk with every other public and open survey platform. There are two provisions to avoid spamming of your sever: <ul> <li>The results JSON object is limited to a size of 64kB which is a lot for listening test results, but not enough to abuse your server as a hosting facility</li> <li>File names in the <code>results/</code> folder contain a random string, so it is not possible to access the submitted data without listing the whole directory</li> </ul> <h1 id="internals">6. Internals</h1> <div class="figure"> <img src="https://s14.postimg.cc/xozlybqdd/schematic.png" alt="BeaqleJS functional blocks" /> BeaqleJS functional blocks </div> The general structure of BeaqleJS can be divided in three blocks as visualised in the diagram above. There is a common HTML5 <code>index.html</code> file to hold the main HTML structure with some basic place holder blocks whose content will be dynamically created by the JavaScript backend. The styling is completely independent and done with the help of cascading style sheets (CSS). Style sheets, config files and all necessary JavaScript libraries are loaded in the header of the <code>index.html</code>. Most of the descriptive text, like introduction and instructions, are placed in hidden blocks inside this file and their visibility is controlled by the scripts. For the user interface and to simplifiy Document Object Model (DOM) manipulations, the well known <a href="https://jquery.com/">jQuery</a> and <a href="http://jqueryui.com/">jQueryUI</a> libraries are used. The JavaScript backend consists of two main classes. The first one is the <code>AudioPool</code> which takes care of audio playback and buffering. It pools a set of HTML5 <code><audio></code>-tags in a certain AudioPool <code><div></code>-tag. There are simple functions to add and load a new file, connect and address it with an ID, manage playback and looping as well as synchronized pause and stop operations. The <code>ListeningTest</code> class provides the main functions of an abstract listening test. This includes the setup and management of basic playback controls (play, pause, looping, time line display, ...), reading of the test configuration as well as storage of the results and also main control over the test sequence. To create a certain test type the abstract <code>ListeningTest</code> class is inherited and specific functions for the actual arrangement of test items or storage and evaluation of the results need to be implemented. Based on this modular approach it is very easy to extend the framework with additional test types or to create variants of existing ones without the need to reimplement all the necessary basics. If the test is performed distributed over the internet or on several local computers, the <code>ListeningTest</code> main class is also able to send the final ratings to a web service for centralised collection and evaluation. <h2 id="creating-a-new-test-class">6.1 Creating a new test class</h2> A new test class has to inherit the base functionality from the main <code>ListeningTest</code> class. Inheritance in JavaScript is achieved by prototypes and this means to define a new class <code>MyTest</code> and then set its prototype to the base class. As this overwrites the constructor it has to be reset to the child constructor afterwards: <div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">// inherit from ListeningTest function MyTest(TestData) { ListeningTest.apply(this, arguments); } MyTest.prototype = new ListeningTest(); MyTest.prototype.constructor = MyTest; // implement the necessary functions MyTest.prototype.createTestDOM = ... MyTest.prototype.saveRatings = ... MyTest.prototype.readRatings = ... MyTest.prototype.formatResults = ...</code></pre></div> The child class can access the <code>TestState</code> and the <code>TestConfig</code> structures from the parent: <div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">ListeningTest.TestState = { // main public members 'CurrentTest': -1, 'TestIsRunning': false, 'FileMappings': {}, 'Ratings': {}, 'EvalResults': {}, // ... // optionally add own fields // ... } ListeningTest.TestConfig = { "TestName": "Test", "LoopByDefault": true, "EnableABLoop": true, "EnableOnlineSubmission": false, "BeaqleServiceURL": "http://...", "SupervisorContact": "super@visor.com", "Testsets": [ { "Name": "Testset 1", "Files": { // ... } }, { "Name": "Testset 2", "Files": { // ... } } ], // ... // further test specific settings // ... }</code></pre></div> The <code>TestState</code> should be used to store random file mappings, ratings and other status variables, but can also be dynamically expanded with specific fields required by the child class. The <code>TestConfig</code> structure is just a mapping of the BeaqleJS config file into the class namespace. It has to contain at least the fields and structure as given above but it is possible to add additional sections which are required by the child class. Every new test class has to implement at least four new functions: <ul> <li><code>createTestDOM(TestIdx)</code> creates the visible layout and HTML structure of the test with the index <code>TestIdx</code> based on the test configuration. All the necessary information from the config is available inside the object in <code>this.TestConfig.*</code>. Audio files should be appended to the <code>AudioPool</code> with <code>this.addAudio()</code> and can then be connected to play buttons by unique file IDs. Random mapping of filenames to IDs can be stored in the prepared <code>this.TestState.FileMappings[TestIdx]</code> structure.</li> <li><code>saveRatings(TestIdx)</code> is used to obtain the ratings from the sliders or buttons in the DOM and to store them in an arbitrary format in the predefined <code>this.TestState.Ratings[TestIdx].*</code> object.</li> <li><code>readRatings(TestIdx)</code> is intended to read the ratings for from <code>this.TestState.Ratings[TestIdx]</code> and to reapply them to the sliders or buttons in the DOM. This is primarily used during switching back and forth in the test sequence.</li> <li><code>formatResults(TestIdx)</code> is automatically called after the final test in the sequence. It is supposed to evaluate and summarize the ratings and to store the final results in <code>this.TestState.EvalResults</code>. It should return a string containing the results formatted in a human readable manner (HTML). This will be presented to the listener after the last test and the <code>EvalResults</code> structure may be send to a web service (see <a href="#online-submission">Online Submission</a>).</li> </ul> <h1 id="contact">7. Contact</h1> <a href="http://hsu-ant.github.io/beaqlejs" class="uri">http://hsu-ant.github.io/beaqlejs</a> skraft (AT) hsu-hh.de <h1 id="license">8. License</h1> The complete sources, html and script files as well as images are released under the GPLv3 license. A copy of the GPL is provided in the <code>LICENSE.txt</code> file. </body> </html>

Proudly Served by LiteSpeed Web Server at webjo.net Port 80