Audio Player v2 – Technical Docs

version 2.0.0

Audio Player is a web application that uses HTML5, JavaScript, CSS3, and web storages to deliver audio content.

Demo Starter Kit

Annotated Screens


Main UI tracks expanded

  1. Title – the presentation title
  2. Subtitle – the presentation subtitle if provided
  3. Author & Duration – the presentation author and total duration of the presentation
  4. Start button – starts the presentation from the beginning
  5. Resume button – resume the presentation from where it was left off
  6. Download button menu – list of available files for downloading. Will not be displayed if there are no downloadable files.

The background image and button color of the presentation will change depending on the program and course.

Mulitple Tracks

Main UI tracks expanded

Main UI tracks closed

  1. Track author photo – a photo of the author of the current track. Click the author photo to open the author profile.
  2. Track title – the title of the current track. The title will automatically scroll if it is long.
  3. Track author – the author of the current track
  4. Track number – the current track number out of the total number of tracks
  5. Playlist – a list of all tracks. Photo of the author for each track will not be displayed if the track author is the same for all. Each track has a download button to download the respective track.
  6. Close playlist button – click to close the playlist
  7. Progress time – the current time of the playback
  8. Progress bar and scrubber – indicates the progression of the current track. Click or drag and drop to seek the playback.
  9. Track duration – the total time of the current track
  10. Previous button – click to go back to the previous track. If the current track is the first track, the previous button is disabled.
  11. Rewind button – rewind 10 seconds
  12. Play and Pause button – click to play or pause the current playback
  13. Fast forward (skip) button – fast foward or skip 10 seconds ahead of the current track playback
  14. Next button – click to advance to the next track. If the current track is the last track, the next button is disabled.
  15. Caption on or off button – click to turn caption on or off. Turning on the caption will close the playlist if there are multiple tracks. If current track has no caption, this button will not be displayed.
  16. Playback rate/speed menu – click to select and change playback speed
  17. Volume controls – click to mute or adjust the track volume
  18. Download button – click to show a list of available files for download
  19. Next track display and open playlist button – if the playlist is closed, the “Up Next” element will be displayed. Click the open playlist (arrow) button to open the playlist.
  20. Caption area – if the track has caption it will be displayed in this area

Single Track

Main UI Single Track

If the presentation has only a single track, the following controls will not displayed:

  • Track number
  • Playlist
  • Previous button
  • Next button

File Structure

File Structure

  • The index.html file is required for each presentation.
  • The core script and the manifest file files are centralized on the server and does not need to be included with every presentation.
  • The Transcript (.pdf) and Audio (could be a .mp3 for single track or .zip for multiple track) are optional downloadable files to be included with the presentation. Additional downloadable file can be added. See manifest section for more details.
  • The assets folder contains the XML and media files for the presentation.
    • An XML file named “album.xml” is required for each presentation. It holds the presentation content and references to the media files.
    • The audio folder contains all of the audio files.
    • The images folder contains all of the author photos. Photos in this folder will override photos from the server if applicable.

Manifest (JSON) File

The manifest file is a JSON file which contains global settings or configurations for all of the Audio presentations that referenced to it.

  • The properties from line 2 to 8 are for browser purposes only. Do not edit.
  • ap_google_tracking_id – holds Google Analytic tracking code.
  • ap_root_directory – holds the path to the root directory where the source files are stored. Defaults to the local “sources” directory if empty.
  • ap_author_directory – the path to the directory that holds the author image and biography files.
  • ap_splash_directory – the path to the directory that holds the splash image(s)
  • ap_logo_directory – holds the path to the directory where program logo are stored.
  • ap_logo_default – holds the default logo file name to use if no logos were found. This property is also used to set the default program theme.
  • ap_copyright – holds the copyright notice. This copyright notice does not need to included the copyright symbol and year. The symbol and year will be dynamically added by the script.
  • ap_download_files – holds the supported downloadable file format and its label. Specified additional downloadable files here to add to the player’s download list.
  • ap_custom_themes – holds the theme for each program. Specific theme will be applied base on the program path.
    • name – the name of the theme; must match the abbreviated program name (same name as the program logo).
    • colors – holds an array of heximal color codes. This is the color bar displayed above the video when not embedded inside an iFrame. No limits on number of color code.
The manifest file points to shared resources that are in use by other application. For example, the centralized author biography and photo are the same files that are used in Storybook Plus presentations. For details on how to create an author biography and photo, see Centralized Author Biography File (JSON).

The album.xml File

The album.xml file holds or references the contents of an audio presentation. It should always be included inside the assets directory. The XML file contains the setting configurations, the presentation setup, and audio track(s).


Right after XML declaration, <?xml version="1.0" encoding="UTF-8" ?>, is the album tag, the outermost tag of the XML. This album tag has attributes that define the settings for a particular presentation and all other tags should be nested inside.

  • accent – accepts a hexadecimal color value that changes the color of some of the UI elements to match the theme or splash screen of the presentation. If left empty, it will defaults to the hexadecimal color value specified in the manifest file.
  • splashImgFormat – specify the splash image file format that will be used for the presentation. Defaults to jpg if left empty.
  • trackImgFormat – specify all of the track image file format that will be used for the presentation. Defaults to jpg if left empty.
  • analytics – defines whether the presentation is tracked by Google Analytics using the tracking ID that was specified in the manifest file. The only acceptable value to turn on the tracking is “on“, “yes“, or “true“. All other values will be treated as “off.”
  • xmlVersion – holds the versions number of this XML that correlates with Audio Player. This is not the version number for the XML schema definition.


The setup tag of the album.xml specify the splash screen image, title, author, and other additional information for the presentation.

The setup tag has two attributes that are currently used for specifying the path to the centralized splash image and the theme of the page. Both attributes can be left empty, and audio player will parse the URL for the directory of where the centralized splash image is located and the name of the splash image. These two attributes will be helpful when dealing with a presentation of that belong to a group of presentations but requires a different unique splash screen.

  • program – can be refer to as the directory of where the splash image resides
  • course – can be refer to as the “name” of the splash image inside the directory

Nested inside the setup tag:

  • title – the title of the presentation; will be displayed on the splash screen and the black banner bar.
  • subtitle – an optional title for the presentation; will only be displayed on the splash screen.
  • length – the total approximated length or duration of the presentation; will only be displayed on the splash screen
  • author – holds the author’s profile or biography. The value for this tag will override
    the centralized author’s profile or biography.

The author tag has a name attribute. This attribute holds the name of the author and will be used for naming the author’s local and centralized photo and biography files. The value will be reformatted to lowercase with space and special characters removed. For example, Ethan Lin will be reformatted to ethanlin. This reformatted value be will the file name that audio player will be requesting.


The track tag of the album.xml specify the track or tracks of the audio player. If there are more than one track, multiple track tags are needed. Whether it is one track or more than one track, the track tag is the same.

  • The src attribute of the track holds the name of the audio file without the file extension (.mp3).
  • The title tag inside the track tag holds the title of the track.
  • The author tag inside the track tag holds the author profile. It will override the profile from the server if available.
  • The name attribute of the author tag holds the name of the track author. If left empty, it will inherit the author name and profile from the setup tag.
The author tag of the track follows the same protocol as the author tag in the setup tag.

Usage Instructions

How to use this player is straight forward. Follow the file structure and XML above, and it will just works.

Published on August 01, 2018 at 5:18:19 pm CDT. Last modified on August 07, 2018 at 3:40:20 pm CDT.