Control the NanoGong Applet Using Script

Who is this page aimed at?

This page explains how to program with the NanoGong applet. If you only want to put NanoGong on your web page without any programming, or you are using NanoGong with Moodle using the files we provide, you can ignore this page.

Overview

All functions of a NanoGong applet can be controlled by the Gong scripting interface. For example, the NanoGong applet can be completely hidden on a web page so that the additional voice capability does not change the layout of the web page.

The following is the set of selected API functions that are supported by NanoGong.

Proceed to try out the NanoGong applet using API control »

In addition the applet supports saving voice files in the Macromedia Flash FLV format, which may be useful for some programmers working with Flash.

Programming Details

Script in web pages, such as JavaScript and VBScript, can tell the NanoGong applet to perform certain actions by making a function call to the applet. The function name is sendGongRequest and the arguments are the action name and its related parameters. The following sections contain the reference for all actions with an example. The examples are written in JavaScript and they use a variable called 'applet' to point to the applet object on the page.

Play Media

Action:   Start playing back the current recording
Input: Type (always 'audio'), start time in milliseconds (optional) and end time in milliseconds (optional)
Output: The start time if successful and an empty string if an error occurs
Example: Play the current recording from 2 seconds
var time = applet.sendGongRequest('PlayMedia', 'audio', 2000)

Record Media

Action:   Start a new recording on the NanoGong applet
Input: Type (always 'audio') and the maximum duration in milliseconds (optional, the default and maximum allowed duration is 5 minutes)
Output: The maximum duration if successful and an empty string if an error occurs
Example: Start a new recording
var duration = applet.sendGongRequest('RecordMedia', 'audio')

Pause Media

Action:   Pause the current playback
Input: Type (always 'audio')
Output: The Current time if successful and an empty string if an error occurs
Example: Pause a recording
var time = applet.sendGongRequest('PauseMedia', 'audio')

Stop Media

Action:   Stop a playback or recording on the NanoGong applet
Input: Type (always 'audio')
Output: The recorded duration if a recording is stopped and an empty string otherwise
Example: Stop a playback/recording
var duration = applet.sendGongRequest('StopMedia', 'audio')

Clear Media

Action:   Clear the current recording on the NanoGong applet
Input: Type (always 'audio')
Output: -
Example: Clear a recording in the NanoGong applet
applet.sendGongRequest('ClearMedia', 'audio')

Get Media Status

Action:   Get the status of the NanoGong applet
Input: Type (always 'audio')
Output: The current status if a recording is stopped and an empty string otherwise;
the status can be one of the following strings: 'playing', 'recording', 'paused', 'stopping', 'stopped', 'closing' and 'closed'
Example: Get the current status
var status = applet.sendGongRequest('GetMediaStatus', 'audio')

Set Media Time

Action:   Set the playback time of the current recording
Input: Type (always 'audio') and playback time in milliseconds
Output: The time if successful and an empty string if an error occurs
Example: Set the playback time to 1.5 seconds
var time = applet.sendGongRequest('SetMediaTime', 'audio', 1500)

Get Media Time

Action:   Get the playback time of the current recording
Input: Type (always 'audio')
Output: The time if successful and an empty string if an error occurs
Example: Get the current playback time
var time = applet.sendGongRequest('GetMediaTime', 'audio')

Get Media Duration

Action:   Get the duration of the current recording
Input: Type (always 'audio')
Output: The current duration of the recording if successful and an empty string if an error occurs
Example: Get the current of the recording
var duration = applet.sendGongRequest('GetMediaDuration', 'audio')

Set Media Rate

Action:   Set the playback rate of the NanoGong applet
Input: Type (always 'audio') and playback rate between 0.5 to 1.5
Output: The playback rate if successful and an empty string if an error occurs
Example: Set the playback rate to 1.5 times faster
var rate = applet.sendGongRequest('SetMediaRate', 'audio', 1.5)

Get Media Rate

Action:   Get the current playback rate of the NanoGong applet
Input: Type (always 'audio')
Output: The playback rate if successful and an empty string if an error occurs
Example: Get the current playback rate
var rate = applet.sendGongRequest('GetMediaRate', 'audio')

Get Audio Level

Action:   Get the current audio level during recording
Input: -
Output: The audio level, from 0 to 1, during recording if successful and an empty string if an error occurs
Example: Get the current audio level
var level = applet.sendGongRequest('GetAudioLevel', '')

Save Message

Action:   Save the current recording to the local harddisk
Input: File type ('wav/adpcm' or 'flv/pcm'), filename (optional) and path (optional)
Output: The file if successful and an empty string if an error occurs (if filename is not provided the function always return an empty string)
Example: Save the current recording to a file in C:\temp
var file = applet.sendGongRequest('SaveMessage', 'wav/adpcm', 'audio.wav', 'C:\temp')

Load From URL

Action:   Load a voice file to the NanoGong applet from a web location
Input: URL of the voice file
Output: The loaded URL if successful and an empty string if an error occurs
Example: Load a recording from http://somewhere.com/introduction.wav
var url = applet.sendGongRequest('LoadFromURL', 'http://somewhere.com/introduction.wav')

Post To Form

Action:   Post the content of the current recording to an HTML form on any arbitrary web page
Input: URL of the web page containing the HTML form, the parameter name of the uploaded voice file, cookies (optional) and the filename of the voice file
Output: The content of the web page if successful and an empty string if an error occurs
Example: Post the current recording to http://somewhere.com/save.php with the parameter name of 'file'
var ret = applet.sendGongRequest('PostToForm', 'http://somewhere.com/save.php', 'file', '', 'sound.wav')

Get Version

Action:   Get the version of the NanoGong applet
Input: -
Output: The version of the NanoGong applet if successful and an empty string if an error occurs
Example: Get the version of the applet
var version = applet.sendGongRequest('GetVersion', '')