Documentation and API for the Streaming Recorder, 1.0

Introductory Note

The recording system actually consists of two SWF files, a recorder and a player. This document explains how to use each of these two components.

Embedding the recorder in a web page

Embedding the recorder in a web page: Embed Code

The recorder is a SWF file, so it must be embedded into the web page. You can use Adobe's embed code, but using the swfobject is much easier and more standards-friendly.

Embedding using the swfobject is a two-step process. First, you must load the Javascript file into your web page. Google hosts the file, so you can load it from Google thusly:

Second, you call the swfobject and pass it parameters thusly:

The parameters are described in detail below.

Embedding the recorder in a web page: Required Parameters

The following variables must be passed to the recorder (via the Flashvars in the embed code):

Variable	Value
Red5Server	The full URL of the Red5 server. The URL will begin "rtmp://" and will NOT have a trailing slash.
Red5Application	The name of the Red5 "application," which is actually a directory under the webapps folder. See the server documentation for information and instructions for creating your application. This is usually a single word, such as "streamingrecorder."
RecordPath	The subdirectory (under the application directory) in which you want recordings to be stored as you create them. It can be useful for file management purposes to keep your "in-process" recordings separate from the saved recordings.
SavePath	The subdirectory (under the application directory) into which you want recordings moved when you save them. This is the directory from which recordings will be streamed during playback.
FileName	The name that you want to give the recording. Note that you must name recordings before beginning to record, because files are created on the server as soon as you start recording.
WebServer	The full URL of the web server that will host the waveform image. The value of this variable must begin with http:// and end with a trailing slash. For example: http://fubar.com/snafu/. This variable is used when the waveform is being saved to the server.
ImgPath	The relative path to the directory where the waveform image is to be saved. This directory is under the value of the WebServer variable. For example, if the WebServer value is http://fubar.com/snafu/ and the waveform images are to be stored in a directory called renob, so that the full path to that directory is http://fubar.com/snafu/renob/, then the value for ImgPath is renob/ (with a trailing slash).
ImgSaver	The name of the server-side script that will save the uploaded waveform image. The waveform image is in PNG format. Any server-side scripting language will work, as long as it can handle file uploads. For example, the file may be a PHP file called save.php, so the value for this variable would be save.php.
WebPath	The logical path to a location on the web server. This is the location of the directory relative to the filesystem of the server. Note that there is no trailing slash at the end of the path. If you indicate a value for this variable, then when you save a recording, the Red5 application will also make a copy of the recording in the location that you indicate by the WebPath variable. There are two utilities of this function. First, you can copy the recording to a location that your web server can serve. Sometimes you may want to serve the recording as a progressive download, rather than a streaming file. Second, you can use server-side scripting to call the ffmpeg utility and convert the file to MP3 format. If you don't want to enable this function, then pass a value of "na" for this variable.
TimeLimit	The maximum length of recordings, in seconds. For example, to impose a time limit of 2 minutes, pass 120 as the value of this variable. If you do not want to impose a time limit, pass a value of 0.
LicenseKey	The license key that you purchased to unlock the recorder. It will be a long string of text something like this: 2317e23c2a080396968d6ef2ddec8302. A license key is locked to one domain. If the license key is wrong, incomplete, or for the wrong domain, the recorder will enter into demo mode.

Embedding the player in a web page

Embedding the player in a web page: Embed Code

Embedding using the swfobject is a two-step process. First, you must load the Javascript file into your web page. Google hosts the file, so you can load it from Google thusly:

Second, you call the swfobject and pass it parameters thusly:

Embedding the player in a web page: Required Parameters

The following variables must be passed to the recorder (via the Flashvars in the embed code):

Variable	Value
Red5Server	The full URL of the Red5 server. The URL will begin "rtmp://" and will NOT have a trailing slash.
Red5Application	The name of the Red5 "application," which is actually a directory under the webapps folder. See the server documentation for information and instructions for creating your application. This is usually a single word, such as "streamingrecorder."
SavePath	The subdirectory (under the application directory) into which you want recordings moved when you save them. This is the directory from which recordings will be streamed during playback.
FileName	The name that you want to give the recording. Note that you must name recordings before beginning to record, because files are created on the server as soon as you start recording.
WebServer	The full URL path to the web server where the waveform image is located. The value of this variable must begin with http:// and end with a trailing slash. For example, if the WebServer value is http://fubar.com/snafu/ and the waveform image is stored in a directory called renob, so that the full path to that directory is http://fubar.com/snafu/renob/, then the value for WebServer is http://fubar.com/snafu/renob/ (with a trailing slash).
LicenseKey	The license key that you purchased to unlock the recorder. It will be a long string of text something like this: 2317e23c2a080396968d6ef2ddec8302. A license key is locked to one domain. If the license key is wrong, incomplete, or for the wrong domain, the recorder will enter into demo mode.

Creating an HTML Interface for the Recorder

You can hide the recorder (embed as usual, but set the width and height to 1 pixel), and use Javascript to interact with the recorder. Create your own HTML-based interface, and use Javascript commands to control the recorder.

Although the interface will consist of HTML elements, the SWF must still be embedded in the web page. An HTML interface does not remove the need for the SWF. An HTML interface will render on a device that does not support Flash (such as an iPad), but the recorder will not work on that device.

Sending Commands to the Recorder

Your interface will communicate with the recorder, which is embedded in the web page (although invisible), via Javascript commands. The recorder will also send messages to Javascript, which you can implement in your interface.

Controlling the recorder via Javascript

The recorder will accept the following Javascript commands from the host web page:

Command	Function:
sendRecord	Begins recording
sendStop	Stops recording or playing
sendPlay	Begins playback
sendSave	Begins the save process
sendCancel	Discards the recording and re-initializes the recorder
setFilename(x:string)	Changes the name of the MP3 file that the recorder creates
setTimeLimit(x:int)	Changes the time limit of the recording

Accepting messages from the recorder

The recorder calls Javascript functions and sends the functions data representing status messages from the recorder. You use that data to update your interface.

sr_mic(x:integer)

The microphone activity level, a number between 0 and 100.

sr_time(x:integer)

The current playback time, in seconds.

sr_progress(x:integer)

The current position of the playback, a number between 1 and 100

sr_msg(x:String)

An information message from the Red5 server, indicating the current activity or event. Use this information to catch error events.

sr_saved(x:String)

Will send a value of "waveform" when the waveform graphic has been successfully uploaded to your web server.

sr_copied(x:String)

Will send a value of "audio" when the recording file has been successfully copied to the WebPath directory. This event will only file if you have not passed a value of "na" to the WebPath variable.

sr_recstatus(x:int)

An integer representing a status code. The status codes are listed in this table:

Value Status Event

0 recorder is not licensed.

1 recorder is licensed.

3 Connected to the server, ready to record

4 Recording

5 Stopped recording

6 Stopped playback

7 Playing

8 Cancelled

9 Saved

99 The microphone has been disabled

98 The microphone has been enabled

Value	Status Event
0	recorder is not licensed.
1	recorder is licensed.
3	Connected to the server, ready to record
4	Recording
5	Stopped recording
6	Stopped playback
7	Playing
8	Cancelled
9	Saved
99	The microphone has been disabled
98	The microphone has been enabled

Creating an HTML Interface for the Player

You can hide the player (embed as usual, but set the width and height to 1 pixel), and use Javascript to interact with the player. Create your own HTML-based interface, and use Javascript commands to control the player.

Sending Commands to the Player

Your interface will communicate with the player, which is embedded in the web page (although invisible), via Javascript commands. The player will also send messages to Javascript, which you can implement in your interface.

Controlling the Player via Javascript

The player will accept the following Javascript commands from the host web page:

Command	Function:
sendPlay	Begins playback from the beginning of the recording.
sendStop	Stops playback.
sendSeek	Jump to a particular point in the audio. Send as a value a percentage of the total time. For example, if the recording is 12 seconds long, and you want to jump to a point 9 seconds in, send a value of 75 (9/12 * 100 = 75%).

Accepting messages from the player

The player calls Javascript functions and sends the functions data representing status messages from the player. You use that data to update your interface.

sr_time(x:integer)

The current point in the playback, in seconds.

sr_progress(x:number)

A the elapsed playback time as a percentage of the total time. For example, if the total recording length is 20 seconds, then during playback, when the playback time reaches 5 seconds, the player sends a value of 25 (5/20 * 100 = 25%). When the playback time reaches 7 seconds, the player sends a value of 35 (7/20 * 100 = 35%). This event fires very frequently, so you can report a high level of accuracy.

sr_length(x:Number)

The length of the recording, in seconds.