WAV audio recording applets SDK, v.1.3

  1. Introduction

  2. WAV Audio Recording Applet SDK package

  3. Target platform

  4. WAV audio recording applet functionality

  5. Installation

  6. How applet uploads WAV file to server

  7. How to send variables to server with audio file

  8. Applet interface

    8.1. Public recording applet methods which are accessible outside of applet

    8.2. JavaScript methods which are accessible from recording applet

    8.3. Recording applet parameters

    8.4. JavaScript interface

    8.5. Java interface

  9. How to customize the input level indicator

  10. How to register the applet.

  11. How to translate applet messages on the national languages

  12. Troubleshooting.

Introduction

The WAV audio recording applet SDK is designed for the web developers and allows to record the audio in WAV PCM/16bits/ mono, WAV Mu-Law/ 8bits/mono and WAV A-Law/8bits/mono formats 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 audio from the server the recording applet works in streaming mode.

The WAV recording applet uses native methods to sound capture, which will be installed on the computer when you use the applet for the first time. The recording applet is digitally signed.

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

TOP

WAV Recording Applet SDK package

  1. Audio recording applet,
  2. Sound capture/playback DLL,
  3. Server script in PHP. Note! The server script in ASP.NET is developed but is not included yet in the installation package. It is available from: www.vimas.com/ASP_ServerScript.zip . You can download it and use for free. Also, you can use for free the server script in JSP for JBOSS server www.vimas.com/WAV_JBOSS_JSP.zip .
  4. Examples:
  5. Documentation

TOP

Target platform


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.

TOP

WAV recording applet functionality

  1. Audio capture from sound card in following formats:
  2. The sampling frequencies are 8000Hz, 11025Hz, 16000Hz, 22050Hz, 32000Hz, 44100Hz. The format and sampling frequency can be set as applet parameters.
  3. Playback of the recorded audio file for sound quality and content evaluation
  4. Uploading of audio file to web server via HTTP. The PHP server script is used to receive audio file on the server.
  5. Playback of the audio files from the web server in the streaming mode

Demo version allows to record 20 sec only.

The recording applet works with Microsoft Java 1.1 and Sun Java plug-ins 1.3-1.5. The recording applet uses native methods for sound capture and playback. They are developed in C++ and implemented as DLLs ( jaudioWavWin.tar and jaudioWavMac.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.

TOP

Installation

  1. Create on the server the directory /voicefiles and /recorder in the root of the web server. For example: www.vimas.com/recorder/ and www.vimas.com/voicefiles/ . Please, for begining, create these folders in the root of web server! After applet works properly, you may change the folders location. Note! It may be will require the changes in the server script.
  2. Make changes in the record_app_J.php and record_app_JS.php in the applet call. In the "ServerScript" parameter you have to indicate your web domain instead of www.vimas.com.
  3. Put into /recorder folder the following files:
  4. Server script must have the permission to save vthe oice files on the server. Please, check it. To set permissions use chmod 755 instruction . Your web server administrator can do it.
  5. To test recording applet with JavaScript interface, open record_app_JS.php on the client computer.
  6. To test audio recording applet with Java applet interface, open record_app_J.php page on the client computer.
  7. To test audio recording applet with JavaScript interface and Save, Open, Delete on the local computer, open record_app_mp3_disk.php.

Note! you may put applet and DLL files in the other folders then mentioned above, but you must keep in mind the following:

TOP

How applet uploads audio file to server

Applet uploads audio files to server by using HTTP POST method. On the server side the retrive.php server script receives audio 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/WavRecorder/record_app.php
http://yourserver.com/recorder/WavRecorder/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/WavRecorder/../../music/voicefiles/smth/ directory, that is the same to
http://yourserver.com/music/voicefiles/smth/

Example 3.

Files on server:
http://yourserver.com/recorder/WavRecorder/record_app.php
http://yourserver.com/recorder/WavRecorder/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/WavRecorder/../../music/voicefiles/ directory, that is the same to
http://yourserver.com/music/voicefiles/

By default, you should put your record_app_JS.php (record_app_J.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_JS.php (record_app_J.php) you should define VoiceServerFolder according to the place of record_app_JS.php (record_app_J.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/WavRecorder/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/WavRrecorder/../../music/voicefiles/smth/ directory, that is the same to
http://yourserver.com/music/voicefiles/smth/

Example 5.

Files on server:
http://yourserver.com/recorder/WavRecorder/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/WavRecorder/../../voicefiles/ directory, that is the same to
http://yourserver.com/voicefiles/

TOP

How to send variables to server with audio file

SENDING

You can add your own variables to send with voicefile in two ways:

1. Applet parameters using

  1. Declare your variables names in UserPostVariables applet parameter:
    Example: <PARAM NAME = "UserPostVariables" VALUE = "name,country">
  2. Define every variable with it's applet parameter
    Example: <PARAM NAME = "name" VALUE = "miha"> <PARAM NAME = "country" VALUE = "Ukraine">
  3. NOTE! Every declared in UserPostVariables parameter variables should have it's own parameter with it's value.

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

  1. Voicefile and all variables are retrieved by server script by POST request
  2. Once you've set up variable you cannot undefine or redefine it.

TOP

Applet interface

Controls:

To control the 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:

The controls interact with the recording applet via JavaScript or Java. We offer 2 examples:

TOP

Table 1: Public recording applet methods which are accessible outside of applet

Applet methods Applet action
RECORD_RP( ) Start the recording/encoding of audio data
PLAYBACK_RP ( ) Start the playback from client PC
PAUSE_RP ( ) Record/Playback pause
STOP_RP ( ) Stop the record/playback
UPLOAD_RP ( String filename ) Uploads audio file from client PC to web server. Server script program is responsible for file receiving
WEBPLAY_RP ( String filename ) Playback the recorded audio file from the server.
SAVE_RP ( Srting path, String filename ) Save the recorded audio file on the client computer.
OPEN_RP ( String path, String filename ) Open the audio file from the client computer.
DELETE_RP( ) Delete the audio files from the client computer which was recorded during current session.

TOP

Table 2: JavaScript methods which are accessible from 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

TOP

Table 3: Recording applet parameters

Applet parameter name Parameter value Parameter description
"ServerScript" e.g. "http://www.vimas.com/voicefiles/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.
"TimeLimit " 1...N N – is maximal recording time in seconds. See Table 4.
"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).
"AudioFormat" MuLaw, ALaw or PCM Defines the audio format. If parameter is absent, the audio format is MuLaw.
"Sampling_frequency" 8000, 11025, 16000, 22050, 32000, 44100 Defines the sampling frequency. If parameter is absent, the sampling frequency is 8000 Hz.
"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

 

TOP

The JavaScript interface

The JavaScript interface allows to create controls by JavaScript and HTML possibilities. See the example in the WAV 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 example how to implement the JavaScript interface is record_app_JS.php.

TOP

The Java applet interface

The idea of Java applet interface is following: exist 2 applets - WAV 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. WAV 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 WAV Recording Applet SDK package in the Examples/InterfaceApplet folder. The example how to call the interface applet is record_app_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_JS.php ).

 

TOP

How to customize the input level indicator

You can customize the horizontal size ( "indicatorWidth" ) and colors ( "backgroudColor", "indicatorLevel1", " indicatorLevel2", "indicatorLevel13") of input level indicator accordingly to your web page style.

Fig.1

The size and 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">
<PARAM NAME = "indicatorWidth" value = "330">

If these applet parameters are absent, applet uses default parameters. The are the same as in example.

Note! The width of applet window WIDTH must be the same as "indicatorWidth" parameter. The height of applet windows must be HEIGHT=24 always.

 

TOP

How to register the applet

The 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 :

TOP

How to translate applet messages on the national languages

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 4a, 4b and 4c.

Table 4a. Status messages

Number of message Description
0 Initialized
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 4b. 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 4c. 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 4a, 4b and 4c. Source code of Intarface applet is available. It is in the WAV Recording Applet SDK package in the Examples/InterfaceApplet folder.

TOP

Troubleshooting

I can not record the audio message

1. You use recording applet with JavaScript interface ( record_app_JS.php). You push the “Record” button but recording applet does not record the sound. Alert window with “Error.

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 RPAppletWav.cab and RPAppletWav.jar must be located on the server in the same directory with web page which calls the applet ( record_app_JS.php / record_app_JS_disk.php / record_app_J.php). The RPAppletWav.cab and RPAppletWav.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 RPAppletWav.cab and RPAppletWav.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 jaudioMuLaw.tar is installed on your computer. It is installed automatically when you use the applet for the first time. On the server the jaudioMuLaw.tar must be located in the same directory with RPAppletWav.cab and RPAppletWav.jar. Probably, you were wrong and jaudioMuLaw.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.

I can not upload the audio file to server

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.

TOP


For support: info@vimas.com