Lacinato WebABX/Shootouter User Manual for Developers

for Version 1.64 -- see http://lacinato.com/webabx for the latest.

Summary

The webabx.js and webabx.css files are in the webabx directory -- these two files, in addition to the webabx_images directory, are the files required for use on your website.
Lacinato WebABX/Shootouter does not use the new Web Audio API. It may in the future, but when it was developed it was not yet supported by all browsers.
upload the webabx.js file to an appropriate location, and upload the webabx_images directory to the same parent directory. Also upload the webabx.css file to an appropriate location.
after uploading your audio files to your webhost, you simply add a couple <link> tags and a particular <div> tag to your webpage (all explained below) and Lacinato WebABX/Shootouter takes care of the rest
if you do your own styling, it is suggested to use an additional CSS file rather than modifying webabx.css (since webabx.css will change with new releases)
the demo directory contains a demo web page and related audio files which are similar to the examples provided in this manual. It may be helpful to refer to those files as you read this.
demo/demo.xml is an example XML file used in some of the demo players -- an XML file is not required, in general, but useful in certain cases described below

Usage

upload your audio files to a location on your webhost. I recommend using MP3 files, or AAC files inside an MP4 container. WAV files are great, but astonishingly they are not supported by Internet Explorer. If you want to use WAV files, you can specify MP3 file fall-back files. Keep in mind that WAV files are much larger than MP3 and AAC, and may cause loading delays for your users.
upload webabx.js and webabx.css to appropriate locations on your webhost
upload the entire webabx_images directory to the same location as the webabx.js file. It should remain a subdirectory, e.g. /path/to/scripts/webabx.js and /path/to/scripts/webabx_images/various_images.jpg
in your HTML, insert these lines (only once, even if using mutliple players on the page) at the top of the page; you will have to edit the path to the .css and .js files as appropriate for your webhost:

<link rel="stylesheet" type="text/css" href="/path/to/webabx.css">
<script src="/path/to/webabx.js" type="text/javascript"></script>

if you are doing customization of the css, include this line between the two lines shown above:

<link rel="stylesheet" type="text/css" href="/path/to/webabx_customizations.css">

insert a <div> tag with class name "webabx" and give it a unique id WITHOUT A "_" IN IT. The simplest possible div tag looks like this; (you would have to edit the audio file paths appropriately for your webhost):

   <div class="webabx" id="mywebabxdemo"
      data-comparison-type="abx"
      data-file1-path="demo1.mp3"
      data-file2-path="demo2.mp3"
   </div>

when the page loads, the webabx.js script will replace that <div> tag with the player.

Configuration Options

There are several options you can specify in the <div> tag to control the type of player that is created and its appearance. (They are all prefixed with "data-" -- this is an artifact of HTML; they don't necessarily have anything to do with data.)

data-comparison-type - set this to "compare", "abx", or "shootout", to control which kind of player is created:
   "compare" simply allows the user to play the audio files and listen to the differences without formal testing of any kind.
   "abx" is the blind ABX test, and can use more than two files for ABCD..X testing
   "shootout" is a shootout, which shuffles the files and lets the user compare them blindly
data-comparison-title - this is the title that will appear in the player
data-fileX-path - path to file #X. E.g. "data-file1-path". Specify one for each audio file you wish to compare, (unless using an XML file) starting at index 1 and increasing sequentially for each file: 1, 2, 3... etc. The path you use here depends on your webhost.
data-fileX-path2 - fallback path to file X for browsers that can't play WAV files (e.g. Internet Explorer.) If you are not using WAV files, don't specify this. If you are, specify the WAV file for the normal path, and for this option, specify the non-WAV fallback file (MP3, AAC inside MP4, etc.)
data-fileX-display-name - the human-readable name of the file, to be displayed in the player. If not specified, the player will use the file path.
data-no-volume-controls - default "false". If set to "true", player will not show the volume sliders for the files.
data-no-bounds - default "false". If set to "true", player will not display the "start time" and "end time" sliders that allow the user to control when the audio playback starts/ends.
data-xml-file-set - path to XML file. This optional method of specifying the files to compare enables other features as well. See full documentation below. If specifying this file, do not specify any data-fileX-* options.
As shown above, the main <div> tag for the player has class "webabx". If you are using different versions of the player on the same page, you can target specific versions by using a classname like "webabx_1p3" for version 1.3 -- this way, that div would only be used by the version 1.3 script. If you do this, make sure all the div tags on the page have the _1p3 style extension for whichever versions should be using them.

XML File Usage

You may optionally use an XML file to specify the list of audio files to be compared. This has several advantages:

if you are working with many files, you can script the creation of your XML file
you can optionally specify "tags" for each file that allow the player to make a filter panel the user can use to select files. (if you don't specify any tags, the player will simply use the XML as a list of files for the comparison.)
you can optionally specify preview images with optional captions that are associated with the tags
NOTE: Browsers tend to aggresively cache XML files: you'll make a change in the XML, and you (or your users) may not see it on the web page. There are some options (described below) to help with that, but they don't always work. If you see this behavior, you may need to change the name of the XML file to force browsers to pull a new version.

You can tag your files any way you like, with any number of tags that can be set to any number of values.

For example, you may have a large collection of recordings of guitar, mandolin, and piano, recorded with various mics at various distances. Let's choose three menu tags: source, mic, and distance. "source" might be "guitar", "mandolin", or "piano". "mic" could be "AKG C535", "CAD VX2", or "Homemade Electret". "distance" might be "6 inches", "2 feet", or "10 feet".

The player will create a filter panel that has three drop-down menus: "source", "mic", and "distance". As the user selects values from those menus, the filter results are updated dynamically. The user can then add the resulting files to their comparison. So if a user wants to compare an AKG C535 on mandolin from various distances, they can select "AKG C535" and "mandolin" (and "any" for the distance) and add all the resulting files to the comparison. If, instead, they want to compare different mics on mandolin from 2 feet away, they can choose "mandolin" and "2 feet" (and "any" for the mic) and add those files.

The HTML would look like this:

The XMl file would be structured like this:

   <?xml version="1.0" encoding="iso-8859-1"?>
   <webabx_fileset>
      { optional menu tags }
      { optional preview image tags }
      { mandatory file specification tags }
   </webabx_fileset>

The mandatory file specification tags indicate the audio files to be compared. They look like this:

The optional menu tags are structured like this:

<menu id="mymenuid" default="defaultmenuvalue">Human-Readable Menu Name</menu>

...if you specify the optional "default" value, it will be selected in the filter box when the player loads. If you do not, the default "(any)" item will be selected.

PLEASE NOTE: the values of the file tags must match each other EXACTLY (case insensitive) or extraneous items will be created. E.g. "AKG C535" and "AKG C 535" will be interpreted as two separate tag values. (Similarly, the menus that you create must match the names in the file tags exactly.) Watch for typos: the player will not be forgiving. :-)

Following our guitar/mandolin/piano example above, the XML file might look like this (only two <file> tags are shown; there would actually be 27 of them: one for each permutation of guitar/mic/distance):

<?xml version="1.0" encoding="iso-8859-1"?>

<webabx_fileset>

  <menu id="audiosource" default="Guitar">Audio Source</menu>
  <menu id="mic">Mic</menu>
  <menu id="distance" default="">2 feet</menu>

  <file path="abx/audiofiles/guitar-535-6inches.mp3"
     name="Guitar - AKG C535 - 6 inches"
     audiosource="Guitar"
     mic="AKG C535"
     distance="6 inches"
     />

  <file path="abx/audiofiles/guitar-535-2feet.mp3"
     name="Guitar - AKG C535 - 2 feet"
     audiosource="Guitar"
     mic="AKG C535"
     distance="2 feet"
     />

  ...(25 more file tags here)...

</webabx_fileset>

Preview Images

You can also specify preview images in the XML file. These can show the user an image representing what they are listening to, and to provide more information (via a caption). These images are associated with the tags under a given menu. E.g. for the example above, you can specify an image for audio source (a guitar, a mandolin, and a piano), an image for each mic, and an image representing the different distances. You only have to provide images for the values you wish to represent with an image. If you leave any out, the player will simply not show an image. You can also optionally supply a caption (in plain text, no HTML codes) for each image.

To do this, create an additional <div> structure somewhere in your HTML to house the images: one for each menu that will be showing images. The <div> id is set to {abx_id}_{menu_id}_preview_image. Following our example above, that would be webabxdemo_audiosource_preview_image for the images associated with the audio source menu, and so on:

You can style those divs however you like (webabx.css only does a very basic styling of them), and you can add additional divs inside or outside of them, etc, but note that the player will search for and use the first div in the document whose id matches the expected id.

In the XML file, you specifty the paths for all the images associated with the images. Again, make sure all the ids and tag names and menu names match exactly. You add <menuimages> tags within the <webabx_filest> tag; they look like this:

<menuimages id="audiosource">
   <menuimage key="Guitar" value="path/to/preview_images/guitar.jpg" />
   <menuimage key="Mandolin" value="path/to/preview_images/mandolin.jpg">This is the caption for the Mandolin image.</menuimage>
   <menuimage key="Piano" value="path/to/preview_images/piano.jpg">This is the caption for the Piano image.</menuimage>
</menuimages>

Now, when the player is created, it will now use those preview images and captions whenever the user hovers over the relevant rows.

Additional options for XML file

There are a few options that are only relevant when using the XML file:

data-max-file-results - default "0" disables this. If set to an integer > 0, player will limit the number of files returned from the filter panel when using an XML file. This can be useful if you have very many files in the XML: if a user accidentally tries to load 50 files, it may not be a good experience.
data-no-initial-buffering - default "false" -- prevent player from performing initial buffering or making initial player rows. If your player comes up with default menu items selected which yield results in the results panel, those items will, by default, be given rows with play buttons and so forth, and the browser will begin buffering the audio. This is likely what you want, but if you would prefer the filter results to be displayed but no rows to be created until the user explicitly causes it, you can set this to "true". This can help save bandwidth with your webhost, and if you anticipate your users won't be satisfied with whatever files are displayed by default, it may improve their experience as well since their browser won't be doing pointles work.

Caching-related options:

data-no-cache - default "false". If set to "true", player will attempt to prevent caching of any XML file in use by setting some HTTP request headers (If-Modified-Since" to "Sat, 1 Jan 2005 00:00:00 GMT", "Cache-Control" to "no-cache", and "Pragma" to "no-cache"). Efficacy may be mixed: depends on your webhost, browser, etc.
data-append-timestamp - default "false". If set to "true", player will attempt to prevent caching of any XML file in use by appending a harmless timestamp to the end of the request.

If you're having trouble with caching, turn one or both of those on and see if it helps. Again, you may end up needing to change the XML file name. Your browser may have a facility to disable this caching; might be worth a check if you are testing many changes to the XML.

This SOFTWARE PRODUCT is provided by THE PROVIDER "as is" and "with all faults." THE PROVIDER makes no representations or warranties of any kind concerning the safety, suitability, lack of viruses, inaccuracies, typographical errors, or other harmful components of this SOFTWARE PRODUCT. There are inherent dangers in the use of any software, and you are solely responsible for determining whether this SOFTWARE PRODUCT is compatible with your equipment and other software installed on your equipment. You are also solely responsible for the protection of your equipment and backup of your data, and THE PROVIDER will not be liable for any damages you may suffer in connection with using, modifying, or distributing this SOFTWARE PRODUCT.

Please see http://lacinato.com/webabx for licensing costs and related information.