Go PlayAlong JavaScript Player API Reference

This document provides reference information for embedding and controlling the Go PlayAlong Player from JavaScript.

Overview

The JavaScript API allows you to embed the Go PlayAlong Player into a web page using JavaScript. Startup parameters can be passed to initialize the player and to load a TAB with custom settings. User settings can be loaded or saved via callback functions.

Requirements

The API package has to be uploaded on a webserver that's name is listed in the domain lock list. Currently the domain lock list contains 'localhost' and 'bandwagonmusic.com.au'. Further domains can be added if required. The purpose of the domain lock technique is to prevent unauthorized publication of the player on other websites.

The web page that embeds the player must reference the gpa-2.82.js file in the HTML header:

<script src="gpa-2.82.js" type="text/javascript"></script>

In addition, the HTML page that contains the player must implement a JavaScript function named savePlayerSettings( value ). The API calls this function when user makes change in the player preferences.

End users must have Flash Player 10 or higher installed and JavaScript enabled.

Getting Started

Create an empty block ( e.g. a div or p element ) in the HTML body with a custom id attached. Optionally you can include some text inside the block to be displayed in case the end user's browser doesn't meet the requirements.

<p id='gpa-container'>
    You need Flash player 10+ and JavaScript enabled to load this tab.
    <br/>
    <a href='http://get.adobe.com/flashplayer/'>Click here to download the latest Flash player.</a>
</p>

Add an onload event handler to your HTML body that will initialize the player.

<body onload="onLoad()">

Initialize the player in the onload event handler by calling the gpaEmbedPlayer JavaScript function from the gpa-2.82.js package.

function onLoad() { gpaEmbedPlayer( containerId, width, height, trackUrl, settingsXml ); }

Player Parameters

The parameters of the gpaEmbedPlayer function will allow you to customize the player.

containerId

The id of the HTML block that holds the player.

width, height

Player dimension in pixels.

trackUrl

Url of the track descriptor xml file, either absolute or relative to the folder containing the swf flash sources. The track descriptor xml file can be exported from the track library of the standalone player.

Optionally contains the following url parameters:

Example: track.xml?loop=true&countIn=true&metronome=true

settingsXml

Player Settings in XML format. You can set it up manually or load a previously saved XML string ( see savePlayerSettings callback function. )


Player Settings XML Specification

<settings>
  <scoreSettings>
    <scale> <!--Number: 0.75 .. 2.0--> </scale>
    <colorNotes> <!--true or false--> </colorNotes>
    <showExpanded> <!--true or false--> </showExpanded>
    <lineBreaks> <!--true or false--> </lineBreaks>
    <highlight> <!--measure / beat / chord / note / none, default: beat--> </highlight>
   </scoreSettings>
  <playbackSettings>
    <volume> <!--Number: 0 .. 1--> </volume>
    <countIn> <!--true or false--> </countIn>
    <metronome> <!--true or false--> </metronome>
    <loop> <!--true or false--> </loop>
    <sfBuffer> <!--SoundFont buffer size in bytes, default: 104857600--> </sfBuffer>
  </playbackSettings>
</settings>

Saving and Loading Player Settings

In order to let end users save player settings, the HTML page must contain a JavaScript function named savePlayerSettings( value ). This function will be called by the player when user clicks 'SAVE' in the settings panel. The player will pass the settings xml string in the value parameter.

It's up to you how you want to handle the settings data received from the player. You can for example store it in a database under user profiles or save it into a browser cookie. Next time a user loads the player the settings data can be passed directly to the settingsXml parameter of the gpaEmbedPlayer function.

Player Preview

Your Flash Player Version: ...

You need Flash player 10+ and JavaScript enabled to load this tab.
Click here to download the latest Flash player.