********************** * jwplayercontrols * Accessible controls for the JW FLV Player ********************** USAGE ------------------------------------------ Unzip and copy the directory structure and contents of the jwplayercontrols directory to your web server. You can leave out the readme directory (obviously). (Note: Testing from the desktop/local file structure will NOT work. Flash sandbox rules disallow API calls to/from a local file.) If you unzip the downloaded file and drop it in the document root of your local machine's testing web server (MAMP/WAMP or other), this URL should work: http://localhost/jwplayercontrols/player.html At this point, you should have a working player. You can adjust the media, css, flashplayer, and js locations to suit your needs when you deploy. Just change the paths in the config section of the HTML file. Note: Do not change the internal structure of the js and flashplayer directories: the js/dojo directory needs its structure exactly as is, and the flashplayer player and accessibility SWF files need to be in the same directory, as do the swfobject.js and expressInstall.swf files. LICENSING ------------------------------------------ Code in the player.html, jwpc.css, and jwpc.js files are Copyright (c) 2009, The Ohio State University Web Accessibility Center. Released under the Academic Free License version 3.0: http://www.opensource.org/licenses/afl-3.0.php This license allows for free distribution and use for non-commercial purposes, so long as attribution is maintained. Most of our work was done by other folks. We're mostly just gluing stuff together and stuffing in some little fixes. The component software and graphics we use are listed below, along with reference to their licenses. Components used: * JW FLV Player The Flash Player is the JW FLV Player, written by Jeroen Wijering/Longtail Video: http://www.longtailvideo.com/players/jw-flv-player/ JW FLV Player is released under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported license: http://creativecommons.org/licenses/by-nc-sa/3.0/ * SWFObject SWFObject version 2.1 is used to dynamically create the embed/object for the Flash Player: http://code.google.com/p/swfobject/ SWFObject is released under an MIT License: http://www.opensource.org/licenses/mit-license.php * Dojo Toolkit JavaScript widgets for interface controls use the Dojo Toolkit: http://dojotoolkit.org Dojo Toolkit is relased under the Academic Free License version 2.1: http://www.opensource-definition.org/licenses/afl-2.1.html * FamFamFam Silk Icons We use FamFamFam Silk icons, created by Mark James: http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons is released under the Creative Commons Attribution 2.5 License: http://creativecommons.org/licenses/by/2.5/ All of the above licenses allow for distribution and use for non-commercial purposes, so long as attribution is maintained. See the websites for copyright information and see the text of each license for specific requirements. USER/DEVELOPER INFORMATION ----------------------------------------- Flash Player: We use version 4.3+ of JW FLV player grabbed from the svn trunk of: http://developer.longtailvideo.com/trac/browser/trunk/as3/ Player has been modified to look locally for the Accessibility plugin. We also modified icons in the plugin. JW FLV player has an extensive JavaScript API. Since Flash *still* lacks keyboard accessibility in browsers other than IE (that is, you either can't get into the Flash area or get trapped in it, after clicking), a work-around is to use the API for basic functionality. Most functionality is available to the JavaScript API. We have modified the Accessibility plugin to allow for control of audio descriptions and caption text (toggling on and off in the player itself and providing callbacks on state). The only significant piece of functionality lacking is the ability to go full-screen. Fullscreen via JavaScript is prohibited. The Adobe Flash Player itself prevents a JavaScript API from making a call to go full screen (to prevent possible abuse). Our work around is to provide a button to double the size on screen and scale up the captions. The Accessibility plugin does not implement the buttons so that they are tab navigable within the Flash movie controlbar, itself. The JavaScript buttons, however, allow for keyboard-only usage. Security: JW FLV supports security through the exchange of secret tokens between the player and the server. This is explained in the section on security here (along with information on RMTP and "PHP" streaming methods): http://www.longtailvideo.com/support/tutorials/HTTP-Video-Streaming We have a player config variable in place, in case you want to use a token. Use of Dojo: Initially, we were using a cross-domain (AOL CDN) version of Dojo. We were experiencing odd results with reading of the toolbar in the JAWS screen reader in IE. So we are now using a Dojo layer--a version of dojo and our scripts that has been compressed using shrinkSafe and has all of the normally independent widgets compiled into the layer. There are only three js files to be called, all shrinkSafe compressed: dojo.js, our layer (jwpc.js), and the SWFObject file. In this readme folder we include our build profile and our original source code, in case you need to modify our code and redeploy. There is information on using the Dojo build tools: http://docs.dojocampus.org/build/index http://dojotoolkit.org/2008/06/04/5-minute-custom-build http://dojocampus.org/content/category/video/ (videos, see "Dojo Build 101" and the series) Namespacing: Or our priliminary and lame attempt at it. Mostly what we do here is prefix variables and dot namespace function calls. This should make clashes very rare. However, this is not really the greatest means of namespacing. Ideally, we would want to encapsulate all functions and variables in objects, preventing any possible clashes by avoiding pollution of the global namespace. We will eventually wrap the player as a dojo widget. This will fix the namespacing problems and would also make it possible to instantiate more than one player per page. At present, this is not possible. (In fact, we hard-code in many DOM element ids, so that changing them in the HTML will break the player.) Until we widgetize: ONE PLAYER PER PAGE, please! BROWSER COMPATIBILITY ----------------------------------------- We have tested Windows and Mac with the following results: - FF 3+ (both platforms): complete support (with ARIA in capable screen readers) - IE 6+: complete support (ARIA support in IE 7 (partial) and IE 8). - Google Chrome: complete support - Safari 3 (both platforms): It is not possible to focus the JavaScript/high contrast caption title bar. This is due to Safari not implementing focus on elements with tabindex="0". The work around is to start with the caption area open. We run a sniffer in the JavaScript that does this (only for Safari). We also add special buttons to enable the toolbar to be focused in Safari and button label text to be displayed using so that VoiceOver can read the buttons. - Opera 9+ (both platforms): The toolbar is not working properly with the keyboard alone. Opera interprets a spacebar keypress as a command to scroll the page. Also, the high-contrast caption pane will not expand fully either with keyboard or with mouse click. Dojo documents lack of support for Opera. So, problems are expected. Using the enter key for buttons presents no problems. The story of screen reader accessibility is covered in the index.html page. Suffice it to say, screen readers work well with the player on Windows. VoiceOver does not understand ARIA and Safari's inability to focus elements with tabindex="0" required us to do a work-around for Safari/VoiceOver. Safari 3 users will see a button that other users don't see, which allows them to focus the toolbar. This enables keyboard only access. VoiceOver users can enter a page with the player, read the hidden instructions, and then toggle VoiceOver off to allow for the shortcut keys to pause and play video, mute, or resize the player. To access all buttons, a hidden button is provided that allows for button labels to be displayed, thus allowing VO to read the buttons. We have tested also in Safari 4 Beta. The problem with tabindex is gone. You can tab to the toolbar. However, VO is not working properly with the toolbar--all buttons and other controls are read in their entirety starting at the focused button. See the index.html file for more explanation. NOTES FOR DEVELOPERS ---------------------------------------- ARIA AND WIDGET CHOICES One thing that gave headaches during implementation was what to use for seeking forward and backward in the movie. An obvious choice would have been to use a slider control. We tried this and we tried a progress bar indicator. Neither solution was appropriate. Both work fine for the keyboard and visual users. However, neither works for a screen reader. If you want to use the controls to track progress through a movie, you would want the controls to advance as the movie plays. This is good in theory. However, in practice with a screen reader the results are non-optimal. The slider and progress bar indicators update their values for the screen reader by using the aria-valuenow attribute. The screen reader reads this value as it changes. JAWS updates about once ever 5 seconds and NVDA updates as quickly as the valuenow value updates. So, in JAWS you hear periodic and interrupting announcements of progress--only in percentage or by number in seconds. You cannot pass complex strings to the valuenow and have them read. So, even if you could shut off the constant updates, you still are limited to simple integers being voiced. NVDA doesn't read the valuenow value itself, instead it uses the value to represent a percentage, which beeps at higher and higher pitch until 100% is reached. This doesn't give a decent indication of your actual location in the progress of the video. Ultimately, we used the "timer" aria role for the container. According to the ARIA recommendation, information in a timer must update at regular intervals appropriate to its function. In this case, it must update every second. Though timer is a live-region role, it is set to aria-live="off," so that a screen reader is not bombarded by spoken updates. To make it focusable programmatically, we assigned the timer a tabindex of -1 and created a keyboard shortcut allowing the screen reader user to toggle between the timer and the toolbar. To make its value read by the screen reader, we wrapped the timer's contents in a span and set that span to be the label for the timer. If you are interested in learning about ARIA, we recommend http://codetalks.org. Codetalks is the where much of practical usage of ARIA is getting worked out. Codetalks has participation from many of the key figures working to define and promote ARIA. Also see the related google group, "free-aria." OUR BUILD OF DOJO We are using the latest nightly build (as of Feb 12, 2009). We are using the Dojo Build System to compile a custom layer, which has compiled into it all of the Dojo widgets and our own code for the player. (As mentioned above, in testing, we kept having odd behavior with JAWS and IE. Eventually, we discovered it had something to do with the cross-domain Dojo, which we were using initially.) In this readme folder are our build profile and our original source code for jwplayercontrols (jwpc.js). If you need to make changes to the code, you will want to rebuild. You will need a JRE installed on your machine (needed by shrinkSafe?). 1. Get a SVN checkout of nightly trunk (including build tools): $ svn co http://svn.dojotoolkit.org/src/view/anon/all/trunk 2. Create a folder structure for the build (the checkout plus jwpc folder and profile): - dojo |- dojo |- dijit |- dojox |- util |- jwpc |- jwpc.js | jwpc.profile.js 3. Run the build: cd into util/buildscripts (use ./build.sh for *nix, build.bat for Windows) $ build.bat profileFile=C:\full\path\to\jwpc.profile.js action=release \ cssOptimize=comments optimize=shrinkSafe This will internalize widgets and templates into your jwpc.js layer and perform compression/optimization. It will create a full release directory. You don't need all of the files in the release directory. See our js/dojo directory for what you will need. Just move that stuff over. (Or use Firebug's net tab to see what files are requested.) Note on debugging: If you see errors, try running with the uncompressed layer (jwpc.js.uncompressed.js). It may help track things down. For production you will want to use the compressed layer. Experiment with using the mini_build build script too. It will gzip files, creating more optimizations and reducing file sizes. (Your web server will need mod_deflate installed for the mini. The video tutorials referenced above explain this.)