8.1. Public recording applet methods which can be invoked from the JavaScript
8.2. JavaScript methods which can be invoked from the recording applet
8.3. Recording applet parameters
8.4. JavaScript interface
8.5. Java interface
The MP3 audio recording applet SDK is designed for the web developers and allows to record the audio in MP3 format from the web site and upload audio file to the web server via HTTP. Also, it is possible to save recorded audio file on the client computer and open it from there. To playback the recorded MP3 audio from the server the recording applet works in the streaming mode.
The MP3 recording applet uses native methods to sound capture, LAME MP3 encoding/decoding and playback in the DLL, which will be installed on the computer when user uses the applet for the first time. The recording applet is digitally signed.
The MP3 audio recording applet has Java methods which accessible from JavaScript and Java. They can be used to control the recording applet. We offer 2 examples how to control the applet from JavaScript and Java. As example how to control the recording applet from Java, we offer interface applet with source code. So, a web designer can customize the recording applet interface according to the web site style and design.
Target OS Platform: Windows 98/NT/2000/ME/XP/2003, Mac OS X.
Target browsers:
- on the Windows: Microsoft Internet Explorer 4.0 and up, Netscape 7, FireFox, Mozilla, Opera.
- on the Mac: Safari, Opera.
Java versions: Microsoft Java 1.1 and Sun Java plug-in 1.3 -1.5.
Web Servers: Unix, Microsoft.
Demo version allows to record 20 sec only.
The Mp3 audio recording applet is developed in Java 1.1. So, the applet works with Microsoft Java 1.1 ( i.e. Recording applet works on the target browsers with default browser JVM installation) and with Java plug-in 1.3-1.5. The recording applet uses native methods for sound capture and LAME Mp3 encoding/decoding. They are developed in C++ and implemented as DLLs ( jaudioMp3Win.tar and jaudioMp3Mac.tar). The DLLs will be installed on the client computer if the applet is being used for the first time. The recording applet is digitally signed. For digitally signing the Thawte certificate is used.
Note! you may put applet and DLL files in the other folders then mentioned above, but you must keep in mind the following:
Applet uploads mp3 files to server by using HTTP POST method. On the server side the retrive.php server script receives mp3 file. If the file is too long, applet devides it on parts and uploads each part separately. The size of each part in bytes is defined by BlockSize applet parameter.
Example:<PARAM NAME = "BlockSize" VALUE = "20480">
Applet uploads voice file in the folder, defined by VoiceServerFolder and UserServerFolder parameters like http://www.yourhost.com/recorder/VoiceServerFolder/UserServerFolder/, where /recorder/ is the folder that contains retrive.php.
VoiceServerFolder applet parameter defines folder reletively folder which contains retrive.php.
UserServerFolder applet parameter defines folder which is in the VoiceServerFolder.
Please, read two examples of defining VoiceServerFolder parameter.
Example 1.
Files on server:http://yourserver.com/recorder/record_app.php
http://yourserver.com/recorder/retrive.php
http://yourserver.com/voicefiles - folder for voice files
So, you should define such applet parameters:
<PARAM NAME = "VoiceServerFolder" VALUE = "/../voicefiles/">
<PARAM NAME = "UserServerFolder" VALUE = "smth">
So, voice files would be written in
http://yourserver.com/recorder/../voicefiles/smth/ directory, that is the same
to
http://yourserver.com/voicefiles/smth/
Example 2.
Files on server:
http://yourserver.com/recorder/mp3recorder/record_app.php
http://yourserver.com/recorder/mp3recorder/retrive.php
http://yourserver.com/music/voicefiles - folder for voice files
You should define such applet parameters:
<PARAM NAME = "VoiceServerFolder" VALUE = "/../../music/voicefiles/">
<PARAM NAME = "UserServerFolder" VALUE = "smth">
So, voice files would be written in
http://yourserver.com/recorder/mp3recorder/../../music/voicefiles/smth/ directory,
that is the same to
http://yourserver.com/music/voicefiles/smth/
Example 3.
Files on server:
http://yourserver.com/recorder/mp3recorder/record_app.php
http://yourserver.com/recorder/mp3recorder/retrive.php
http://yourserver.com/music/voicefiles - folder for voice files I
f you don't want to make folder inside voicefiles directory, you should define
such parameters:
<PARAM NAME = "VoiceServerFolder" VALUE = "/../../music/">
<PARAM NAME = "UserServerFolder" VALUE = "voicefiles">
So, voice files would be written in
http://yourserver.com/recorder/mp3recorder/../../music/voicefiles/ directory,
that is the same to
http://yourserver.com/music/voicefiles/
By default, you should put your record_app.php file and retrive.php file in the same directory on server, but you can also put them into different directories. To make that you should define VoiceServerFolder parameters in record_app.php and retrive.php separately. In record_app.php you should define VoiceServerFolder according to the place of record_app.php, in retrive.php you should define VoiceServerFolder accoreding to the place of retrive.php. Please look through the examples to understand more.
Example 4.
Files on server:
http://yourserver.com/recorder/mp3recorder/record_app.php
http://yourserver.com/retrive/retrive.php http://yourserver.com/music/voicefiles
- folder for voice files
You should define such applet parameters:
<PARAM NAME = "VoiceServerFolder" VALUE = "/../../music/voicefiles/">
<PARAM NAME = "UserServerFolder" VALUE = "smth">
In retrive.php you should replace lines below i
f(isset($_POST["VoiceServerFolder"])) $VoiceLocal = $_POST["VoiceServerFolder"];
else $VoiceLocal="/../voicefiles/";
by
$VoiceLocal ="/../music/voicefiles/";
So, voice files would be written by retrive.php to
http://yourserver.com/retrive/../music/voicefiles/smth/ directory, that is the
same to
http://yourserver.com/music/voicefiles/smth/
And applet'll read them from
http://yourserver.com/recorder/mp3recorder/../../music/voicefiles/smth/ directory,
that is the same to
http://yourserver.com/music/voicefiles/smth/
Example 5.
Files on server:
http://yourserver.com/recorder/mp3recorder/record_app.php
http://yourserver.com/script/retrive.php http://yourserver.com/voicefiles -
folder for voice files
If you don't want to make folder inside voicefiles directory, you should define
such parameters
<PARAM NAME = "VoiceServerFolder" VALUE = "/../../">
<PARAM NAME = "UserServerFolder" VALUE = "voicefiles">
In retrive.php you should replace lines below
if(isset($_POST["VoiceServerFolder"])) $VoiceLocal = $_POST["VoiceServerFolder"];
else $VoiceLocal="/../voicefiles/";
by
$VoiceLocal ="/../";
So, voice files would be written by retrive.php to
http://yourserver.com/retrive/../voicefiles/ directory, that is the same to
http://yourserver.com/voicefiles/ And applet'll read them from
http://yourserver.com/recorder/mp3recorder/../../voicefiles/ directory, that
is the same to
http://yourserver.com/voicefiles/
SENDING
You can add your own variables to send with voicefile in two ways:
1. Applet parameters using
<PARAM NAME = "UserPostVariables" VALUE = "name,country"><PARAM NAME = "name" VALUE = "miha">
<PARAM NAME = "country" VALUE = "Ukraine">2. Setparameter applet method using
You can call Setparameter (String name, String value) method
from javascript and set your variable.
PROCESSING ON SERVER
You can process received with voicefile variables in retrieve.php. For example, this code will print all received variables:
while(list($key,$val)=each($_POST))
{
AddLogs($errfile,"POST variable received >".$key." = ".$val);
}
ADDITIONAL INFORMATION
Controls:
To control the Mp3 recording applet it has a few methods which can be accessible from outside, in particular from JavaScript and Java. These methods allow to implement the following controls:
UPLOAD_RP() JavaScript method,WEBPLAY_RP() method,The controls interact with the recording applet via JavaScript or Java. We offer 2 examples:
Table 1: Public recording applet methods which can be invoked from the JavaScript
| Applet methods | Applet action |
RECORD( ) |
Start the recording/encoding of audio data |
PLAYBACK ( ) |
Start the playback from client PC |
PAUSE ( ) |
Record/Playback pause |
STOP_RP ( ) |
Stop the record/playback |
UPLOAD ( String filename ) |
Uploads audio file from client PC to web server. Server script receives the audio file on the server |
WEBPLAY ( String filename ) |
Playback the recorded audio file from the server. |
SAVE ( Srting path, String filename ) |
Save the recorded audio file on the client computer. |
OPEN ( String path, String filename ) |
Open the audio file from the client computer. |
DELETE( ) |
Delete the audio files from the client computer which was recorded during current session. |
Table 2: JavaScript methods which can be invoked from the recording applet
| Applet methods | Applet action |
SetStatus_RP(s,num) |
Applet sends status message to JavaScript |
SetTimer_RP( s ) |
Applet sends current recording/playback time to JavaScript |
confirmRecord(s,num) |
Confirm re-recording |
addName( s ) |
Adds audio file name to list of files for listening from web server. |
report_RP(s,num) |
Pop-up message |
Table 3: Recording applet parameters
| Applet parameter name | Parameter value | Parameter description |
| "ServerScript" | e.g. "http://www.vimas.com/recorder/retrive.php" | Server script URL |
| "VoiceServerFolder" | e.g. "/../voicefiles/" |
URL of directory in which the audio files are stored. URL is necessary to playback from server. |
| "Sampling_frequency" | See table 4, 1st column | Audio sampling frequency |
| "Bitrate" | See table 4. | In the table 4 available bitrates are defined at each sampling frequency. Bitrate is in kbps. |
| "TimeLimit " | 1...N | N – is maximal recording time in seconds. It is hardcoded in the license file. |
| "Registration" | a) “Demo” b) Name of file with registration key. For example, “RegKey.txt” |
a) Applet works as demo, the maximal recording time is 20
sec. If Registration parameter is absent, applet works as demo, too. b) The registration key file you will receive after licensing. File must be located on the server in the same directory with applet. |
| "OverRecord" | “true/false” | True – over recording is available without warning message. False (or parameter is absent) - over recording is available with warning message only. |
| "BlockSize" | E.g. 1024 | Applet uploads audiofile block by block. This parameter defines the size of block in bytes. |
| "InterfaceType" | JS or Java | Applet can use controls which created by JavaScript (JS) or interface applet (Java). |
| "UserPostVariables" | Variable names. Ex: "name,age,city" | Number on variable names to upload to server with voice file. Please, see How to send variables to server with audio file |
"UserServerFolder" |
e.g. "User1_personal_folder" |
Defines the subfolder which is in the VoiceServerFolder. |
"indicatorWidth" |
e.g. 330 |
Defines the horizontal size of input level indicator, in pixels. |
"backgroudColor", "indicatorLevel1", " indicatorLevel2", "indicatorLevel3" |
e.g. "c0c0c0", "4664f0", "28c814", "f03250" |
Colors of input level indicator components. Please, see How to customize the input level indicator |
Table 4. Available Bitrates.
| Sampling frequencies, Hz | Bitrates, kbps |
| 8000 | 16, 24, 32, 40, 48, 56 |
| 11025 | 16, 24, 32, 40, 48, 56, 64, 80 |
| 16000 | 16, 24, 32, 40, 48, 56, 64, 80, 96, 112 |
| 22050 | 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160 |
| 32000 | 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224 |
| 44100 | 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320 |
The JavaScript interface allows to create controls by JavaScript and HTML possibilities. See the example in the Mp3 recording applet SDK package. JavaScript interface allows to customize applet controls correspondingly with web site scenario and style. The list of recording applet methods which can be accessible from JavaScript are in the Table 1. The examples how to implement the JavaScript interface are record_app_mp3_JS.php and record_app_mp3_disk.php.
The idea of Java applet interface is following: exist 2 applets - Mp3 recording applet and interface (front-end) applet. Recording applet has methods which are accessible outside of applet (table 1). Interface applet creates control panel with controls and accesses the recording applet methods (table 1) to control the recording applet. Also, recording applet sends messages to interface applet. Mp3 recording applet SDK package contains open source code of interface applet, so, user can re-design it correspondingly with web site scenario and style. Source code of Intarface applet is in the Mp3 Recording Applet SDK package in the Examples/InterfaceApplet folder. The example how to call the interface applet is record_app_mp3_J.php.
Note! Interface applet works under Java plug-in 1.3-1.5. Under Microsoft JVM Interface applet does not work. So, if you want to use recording applet under Microsoft JVM and Java plug-in 1.3-1.5, you have to use JavaScript inerface ( record_app_mp3_JS.php ).
You can customize the horizontal and vertical sizes of the indicator and it colors ( "backgroudColor", "indicatorLevel1", " indicatorLevel2", "indicatorLevel13") according to your web page style.
Fig.1
The colors can be set as applet parameters. For example:
<PARAM NAME = "backgroudColor" value = "c0c0c0">
<PARAM NAME = "indicatorLevel1" value = "4664f0">
<PARAM NAME = "indicatorLevel2" value = "28c814">
<PARAM NAME = "indicatorLevel3" value = "f03250">
The sizes of input level indicator you can set as applet window width and height - WIDTH and HEIGHT
If these applet parameters are absent, applet uses default parameters. They are the same as in the example.
The Mp3 audio recording applet can be used as demo or full functional applet. To use applets as demo applet, you must add to applet parameters the following parameter:
<PARAM NAME = "Registration" VALUE = "Demo">
Applet also works as demo if "Registration" parameter is absent.
In demo mode the applets will work with limited to 20 sec recording (playback) time.It is single difference between demo and full functional applet mode.
To use applet as full functional you must :
1. Translation in the case of JavaScript interface using
Applet passes to setStatus_RP(num, str) and confirmRecord(num, s) JavaScript functions messages and their numbers. So, you can process the number and take message from table of messages in other languages. See messages in table 5a, 5b and 5c.
Table 5a. Status messages
| Number of message | Description |
| 1 | Loading audio module |
| 2 | Recording voice message |
| 3 | Paused. Press again for continue |
| 4 | Stopped |
| 5 | Playing voice message |
| 6 | Uploading voice message |
| 7 | Uploaded |
| 8 | Connection to server |
| 9 | Buffering |
| 10 | Playing voice message from server |
| 100 | blank |
Table 5b. Information messages
| Number of message | Description |
| 11 | You must record the voice message before playing |
| 12 | You must record the voice message before send it |
| 13 | Please, enter the file name |
| 14 | A file name must not contain any of the following characters: \\n \\ / . , : * ? \" < > | ! @ # $ % ^ & +< |
| 15 | Please, select the voice file |
| 16 | You are about to overwrite the voice message that you have recorded. Are you sure? |
Table 5c. Error messages
| Number of message | Description |
| -1 | Unknown Error |
| -2 | No sound card detect |
| -3 | Audio module could not be loaded |
| -4 | Voice message could not be uploaded |
| -5 | Incorrect IP address |
| -6 | Please check ServerScript parameter |
| -7 | Please check VoiceUrlContext parameter |
| -8 | Please check key file on the server |
| -9 | License is expired |
2. Translation in the case of Java applet interface using
Recording applet passes to Interface applet methods ( ) the messages and their numbers. So, you can process the number and take message from table of messages in other languages. See messages in table 5a, 5b and 5c. Source code of Intarface applet is available. It is in the Mp3 Recording Applet SDK package in the Examples/InterfaceApplet folder.
1. You use recording applet with JavaScript interface ( record_app_mp3_JS.php). You push the “Record” button but recording applet does not record the sound. The alert window with "Object does not support this property or method” message appears.
Reasons:
a) Probably, the recording applet is not downloaded from the server to the client machine. For successful downloading the RPAppletMp3.cab and RPAppletMp3.jar must be located on the server in the same directory with web page which calls the applet ( record_app_mp3_JS.php). The RPAppletMp3.cab and RPAppletMp3.jar can be placed also in the other directory, but in the recording applet call in the CODEBASE must be indicated the full path to RPAppletMp3.cab and RPAppletMp3.jar: For instanse: CODEBASE=http://www.yourURL.com/dir1/recorder/
At first, please, create the directories as in the documentation and examples is recommended. Then, when applet works properly, you can re-create directories as you want, correspondingly to your web application.
b) Please, check if the jaudioMp3Win.tar or jaudioMp3Mac.tar is installed on your computer. It is installed automatically when you use the applet for the first time. On the server the jaudioMp3Win.tar and jaudioMp3Mac.tar must be located in the same directory with RPAppletMp3.cab and RPAppletMp3.jar. Probably, you were wrong and jaudioMp3Win.tar or jaudioMp3Mac.tar is located in the other directory.
c) If audio recording still does not work, please, copy the Java console content and send to support: info@vimas.com .You can find the Java console in the Internet Explorer browser in the View menu at the bottom ( cup of coffee icon). If you do not see the Java console there, please, in the menu go to Tools->Internet option ->Advanced and choose in the Microsoft VM section the “Java console enabled”. In the Netscape 7 browser you can see the Java console in the Tools->Web Development.
1. You recorded the audio message and can playback it from your local computer succesfully. You entered the name of file and push the “Send” button, in the status line you see “Uploading audio messsage...”, but after uploading the alert window appears with “Your message could not be uploaded” message.
Reasons:
a) Server script retrive.php is written in PHP, so be sure your web server support the PHP.
b) Check the /recorder and /voicefiles directories. In the example they are in the root of the web server.
c) Check the "ServerScript" applet parameter. Be sure that path to retrive.php is correct.
d) Be sure if server script has write access to the /voicefiles directory.
For support: info@vimas.com