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

Splash

Mulitple Tracks

7. Track author photo – a photo of the author of the current track. Click the author photo to open the author profile.
8. Track title – the title of the current track. The title will automatically scroll if it is long.
9. Track author – the author of the current track
10. Track number – the current track number out of the total number of tracks
11. 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.
12. Close playlist button – click to close the playlist
13. Progress time – the current time of the playback
14. Progress bar and scrubber – indicates the progression of the current track. Click or drag and drop to seek the playback.
15. Track duration – the total time of the current track
16. Previous button – click to go back to the previous track. If the current track is the first track, the previous button is disabled.
17. Rewind button – rewind 10 seconds
18. Play and Pause button – click to play or pause the current playback
19. Fast forward (skip) button – fast foward or skip 10 seconds ahead of the current track playback
20. Next button – click to advance to the next track. If the current track is the last track, the next button is disabled.
21. 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.
22. Playback rate/speed menu – click to select and change playback speed
23. Volume controls – click to mute or adjust the track volume
24. Download button – click to show a list of available files for download
25. 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.
26. Caption area – if the track has caption it will be displayed in this area

Single Track

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.

{
    "lang": "en",
    "dir": "ltr",
    "name": "Audio Player",
    "description": "Audio player version 2.",
    "short_name": "AP",
    "display": "browser",
    "orientation": "portrait",
    
    "ap_google_tracking_id": "",
    "ap_root_directory": "",
    "ap_author_directory": "https://www.media.uwex.edu/content/media/storybook_support/author/",
    "ap_splash_directory": "https://www.media.uwex.edu/content/media/storybook_support/splash/",
    "ap_logo_directory": "https://www.media.uwex.edu/content/media/storybook_support/logo/",
    "ap_logo_default": "ceoel",
    "ap_copyright": "University of Wisconsin System and University of Wisconsin-Extension, Division of Continuing Education, Outreach, & E-Learning. All rights reserved.",
    "ap_download_files": [ 
        
        {
            "label": "Audio",
            "format": "mp3"
        },
        
        {
            "label": "Transcript",
            "format": "pdf"
        },
        
        {
            "label": "Audio",
            "format": "zip"
        }
    ],
    "ap_custom_themes": [
        
        {
            "name": "ceoel",
            "colors": [ "#0a4a89", "#2a6b9f", "#578db5", "#88b1ce", "#c1d7e6" ]
        },
        
        {
            "name": "apc",
            "colors": [ "#144B5F", "#2D8B91", "#8CB249", "#7DA7AA", "#144B5F" ]
        },
        
        {
            "name": "uls",
            "colors": [ "#712453", "#461F4B", "#1C4D6C", "#428465", "#BD3E48" ]
        },
        
        {
            "name": "ds",
            "colors": [ "#DC4031", "#ECB343", "#8BB341", "#DC4031", "#ECB343" ]
        },
        
        {
            "name": "flx",
            "colors": [ "#A22E45", "#9ABB4E", "#F6BC4B", "#6DBCDE", "#56585A" ]
        },
        
        {
            "name": "hwm",
            "colors": [ "#1C4D6D", "#7B9B39", "#594B98", "#276BA5", "#7B9B39" ]
        },
        
        {
            "name": "il",
            "colors": [ "#377C8B", "#B60050", "#211C1B", "#72A1AB", "#D0D9DE" ]
        },
        
        {
            "name": "smgt",
            "colors": [ "#617949", "#364852", "#6B7E82", "#7A9D43", "#7DA8AF" ]
        },
        
        {
            "name": "msmgt",
            "colors": [ "#617949", "#364852", "#6B7E82", "#7A9D43", "#7DA8AF" ]
        }
        
    ]
       
}

• 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 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).

<?xml version="1.0" encoding="UTF-8"?>
<album accent="" splashImgFormat="svg" trackImgFormat="jpg" analytics="on" xmlVersion="2">
    
	<setup program="" course="">
		<title>HTML5 Audio Player</title>
		<subtitle>Version 2 Demo</subtitle>
		<author name="Ethan Lin"></author>
		<length>15 Minutes</length>
	</setup>

	<!-- Single track only need one track element -->

	<track src="cookie">
		<title>Chocolate Chip Cookie</title>
		<author name="Bryan Bortz"></author>
	</track>

	<!-- for multiple tracks, add more track elements -->
	
	<track src="FasterRide">
		<title>Faster Ride</title>
		<author name="Cartel"></author>
	</track>
	
	<track src="MySongsKnowWhatYouDidInTheDark">
		<title>My Songs Know What You Did In The Dark</title>
		<author name="Fall Out Boy"></author>
	</track>
	
	<track src="Gentleman">
		<title>Gentleman</title>
		<author name="Psy"></author>
	</track>
	
	<track src="YesToLove">
		<title>Yes To Love</title>
		<author name=""></author>
	</track>
	
	<track src="HeresToNeverGrowingUp">
		<title>Here's To Never Growing Up</title>
		<author name="">Hello World</author>
	</track>
    
</album>

Settings

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.

<album accent="" splashImgFormat="svg" trackImgFormat="jpg" analytics="off" xmlVersion="2">
    <!-- setup and track(s) go inside of here -->
</album>

• 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.

Setup

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

<setup program="" course="">
    <title>HTML5 Audio Player</title>
    <subtitle>Version 2 Demo</subtitle>
    <author name="Ethan Lin"></author>
    <length>15 Minutes</length>
</setup>

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.

Track

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.

<track src="cookie">
    <title>Chocolate Chip Cookie</title>
    <author name="Bryan Bortz"></author>
</track>

• 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.

Usage Instructions

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

Published on September 22, 2022 at 1:01:46 pm CDT. Last modified on September 22, 2022 at 1:04:21 pm CDT.