Daisy Web Player Files

Daisy Web Player, Version 12.04 (April 2012)


Introduction
============

Simple Daisy Web Player (SDWP) is a software that allows to open audio documents structured in the DAISY standard and to play them in a web browser.
A first development of such a software has been done by Charles L. Chen under the name "CLC Dandelion" (see http://dandelion.clcworld.net).
This project seems to be inactive since 2008, but it gave us ideas to start this development.
There is a commercial product named Daisy Web Player which can be seen at http://daisy.dynamic-designer.de.

SDWP has been developed for the "Association pour le Bien des Aveugles et malvoyants" (ABA, Association for the blind and visually impaired people) in Geneva, switzerland (http://www.abage.ch).

SDWP uses the SoundManager 2 (SM2) javascript library which is released under the BSD license (http://www.schillmania.com/projects/soundmanager2/).

The code has been written by Martin Mohnhaupt, Nice Data Systems, La Plaine, Switzerland (mailto:m.mohnhaupt@bluewin.ch, http://www.nicedata.ch).

The player can be seen and operated at http://www.daisyplayer.ch/.

For those who wish to install the player on their own web sites, please get the latest release at sourceforge.

Licensing
=========

This product is released as Open Source under the GPL license (see http://en.wikipedia.org/wiki/GNU_General_Public_License).
Donations can be made to the "Association pour le Bien des Aveugles" at http://www.abage.ch/aba/ch/fr-ch/index.cfm?page=/aba/home/don_en_ligne#content

What is new ?
=============

+ The version number now follows the "year.month" schema (like UBUNTU). 
  So the current version is 12.04 (april 2012). Depending on requests, we plan to release two major versions a year.
+ The software has been completely rewritten using the excellent and popular jQuery javascript library (http://www.jquery.com). 
  By doing so, we have been able to greatly   reduce the size of the code and improve its stability!
+ Using the HTML5 BoilerPlate framework, we are able to easily handle most of the browsers (http://www.boilerplate.com).
+ Restyling of the displayed full text content.
+ A simple mechanism to do cross-domain data retrieval with jQuery is available. 
  This means that the software can be located on one server and the Daisy book on another one. 
  To achieve cross-domain retrieval, PHP must be installed on the server.
+ The use of a configuration file (daiswp.xml) allows the setting of operating parameters (GUI settings, beeper, initial volume, keayboard actions, etc...
+ Multi-language support (daisywp.xml).
+ Level-navigation
+ Beep sound when changing section
+ Some keyboard actions are now supported (navigation level switch, fast forward/rewind, playback volume setting, pause/unpause).
+ A loading progress bar and a playback progress bar have been added.
+ We registered a new domain dedicated to this software: www.daisyplayer.ch

Installation
============

The software itself consists of a set of files which have to reside in a directory served by a web server (we use Apache on a FreeBSD box). 
In case cross-domain data retrieval is needed, PHP must also be enabled.

Important files:
----------------

daisywp.html - The user interface (html5 document), which contains the initialization code and the elements to display the DAISY document.
daisywp.js   - The Engine (jQuery) to deal with various duties like loading data via AJAX, handle user events, refresh the user interface and so on.
daisywp.xml  - The configuration file (new!) to handle the GUI languages and some other stuff like the cross-domain requests parameters.               
cross.php    - Cross-domain support. Requires PHP to be active on the server.

Since SDWP uses SoundManager 2, the SM2 javascript library must be installed somewhere on the server (see the SM2 installation documentation at http://www.schillmania.com/projects/soundmanager2/doc/getstarted/).
And finally, the jQuery library must be provided (either locally or via a link to a repository).
All these settings are defined in the daisywp.html file, in the <script src="..."> tags.

The media files (DAISY  books) must also reside on your web site if cross-domain is disabled.

In our case, we have a folder structure like this:

/opt/www/dwp
           +--- index.html (index page, links to DAISY books)
           +--- index.php (redirector to index.html, may be needed)
           +--- daisywp.html (user interface)
           +--- daisywp.xml (configuration data)
           +--- books.html (sample bookshelf, links to online books)
           |
           +--/js
           |    +--- daisywp.js (Player javascript engine)
           |    +--- jquery-1.7.1.min.js  (jQuery library)
           |    +--- modernizr-2.5.3.js  (Modernizer library, HTML5 boilerplate)
           |    +--- plugins.js  (Cross-browser support)
           |    |
           |    +--/sm2
           |          +---/script
           |          |         +--- soundmanager2-jsmin.js (SoundManager 2 library, with debug messages)
           |          |         +--- soundmanager2-nodebug-jsmin.js (SoundManager 2 library for production)
           |          | 
           |          +---/swf
           |                 +--- (...sound manager 2 swf files...)

           +--/res
           |     +--- ...multiple files (resources: buttons, mp3, ...)

           +--/media
                   +---/book1 ... (book folder with mp3 files, smil files, ncc.html file, etc...)
                   +---/book2 ...

To set up SDWP in your specific configuration, you will have to edit the daisywp.html file. First of all, you have to specify where the SM2 is located by changing the specific <script> tag: <script src="/soundmanager/script/soundmanager2-nodebug-jsmin.js"></script> The rest of the file can be left as is.

Operation
=========

To open a DAISY book, we just need to load the daisywp.html file with a parameter that tells where the main DAISY file (ncc.html) resides:

http://www.daisyplayer.ch/daisywp.html?ncc=www.nicedata.ch/media/book1/ncc.html&lang=iso_code

The ncc parameter holds the path to the DAISY book main file. Opening this URL will do all operations (load the needed javascripts, 
load the DAISY document, set up the user interface (text frame and navigation pane).

A second parameter (&lang=) allows to specify the GUI language to be used and also to specify the page language (for page readers).
Currently, French German and English are supported, but you can adapt the daisywp.xml file to support your language too. 
The parameter value simply is the country ISO 639-2 code (fr, de, en,...). The default language is English.

Try it without installation !
=============================

You can use the latest version of the player without installing it, either by setting up the appropriate links on your site, or 
interactively via our web interface at http://www.daisyplayer.ch.

Customization
=============

You can parlty customize the Daisy Web Player via the daisywp.xml configration file. This (xml!) file has 2 disticg sections: <config> (configuration) and <i18n> (internationalization). The first is dedicated to the system configuration, and the latter to the multi-language operation.

Configuration parameters
------------------------
<crossdomain>
   enable: true | false – enable/disable cross-domain operation
   url: url to load to perform the request. This url must return xml data and accept an URI as parameter. See cross.php !

<beeper>
   enable: true | false – enable/disable the beep sound
   sound: relative path to a sound file (e.g. res/beep.mp3)
   volume: 0-100 – beep sound volume

<autoplay>
   Value: true | false – if true, playback is started without triggering a start even (button or key)

<volume>
   Value: 0-100 – Initial playback volume

<bookshelfURL>
   Value: an url where one can find a list of books. This is triggered by the OPEN_BOOKSHELF action. See ACTIONS.

<gui>
   Enable / disable some GUI items.

   <showButtons>
      Value: true | false – Show/hide the playback control buttons

   <showStatus>
     Value: true | false – Show/hide the status bar

<keys>
This section allows to attach actions to keyboard (keydown) events.

   <key>
      name: Name of the key. The use of a self-speaking name is highly recommended!
      code: The code of the key.
      action: action to be launched. See ACTIONS.

   <buttons>
   This section allows to attach actions to button (click) events.
   
      <button>
         id: id of the button. If changed, you'll have to modify the js and css code!
         visible: true | false – show/hide in the GUI.
         action: action to be launched. See ACTIONS.

ACTIONS
-------

Action values are CaSe-SeNsItIvE ! Here is a list of all possible actions or functions:

Action              Value
----------------------------------------------------------------------------------------
(Empty string)      Do nothing, don't even think about handling this item !
PLAY_NEXT           Play next section (within a level)
PLAY_PREVIOUS       Play previous section (within a level)
PLAY_CURRENT        Play current section (re-play)
PLAY_FIRST          Play first section (within a level)
PLAY_LAST           Play last section (within a level)
PLAY_PAUSE          Pause / unpause (toggle)
PLAY_STOP           Stop playback
PLAY_FORWARD        Fast forward by 1 second
PLAY_REWIND         Fast rewind by 1 second
VOLUME_LOUDER       Increase playback volume
VOLUME_SOFTER       Decrease playback volume
OPEN_BOOKSHELF      Jump to the bookshelf (quits the player)
LEVEL_INCREASE      Increase the navigation level
LEVEL_DECREASE      Decrease the navigation level

Internationalization parameters (i18n)
======================================

One <i18n lang=”xx”> is present per language. Currently, each <item> within a section identifies a button of the user interface (id=”...”). One can define a title (which is shown as “title” on the GUI element), and an access key. See daisywp.xml.