Wideband voice recording applets SDK, v.1.0

 

1.Introduction.

2.Target platform.

3. Voice recording applet functionality.

4. Voice streaming applet functionality.

5. Voice Recording Applet SDK package consists of:

6. The JavaScript interface:

-     the list of the voice recording applet methods.

       -     the list of the voice streaming applet methods.

7. Installation:

      -      for Unix server,

-    for IIS.

8. How to register the applets

9. Troubleshooting.

10. Appendix A.

 

 

Introduction

 

The wideband voice recording applet SDK is designed for the web developers and  allow to record  the voice from the web site, to compress it and to send to the web server via HTTP. To playback the recorded voice from the server the embedded voice streaming player or a separate player as a voice streaming applet can be used.

The recording applet is designed in Java 1.1 with native methods to sound capture and playback in the DLL, which will be installed on the computer when you use the applet for the first time. The recording applet is digitally signed.

 Streaming applet is designed in the Java 2 and Java 1.1. So, if on the client computer the Java 2 is installed, to playback the 16kHz sampling frequency is used.  If only Java 1.1 is installed  – 8kHz sampling frequency is used to playback.

 The recording and playback applets have a JavaScript interface. So, a web designer can customize the applet interface according to  the web site style and design.

 

Top

Target platform

 

Target OS Platform: Windows  98/NT/2000/ME/XP.

Target browsers: Microsoft Internet Explorer 4.0 and up, Netscape 7.

Java versions:   Java 1.1 and Java 2

Web Servers: Unix, IIS.

Demo version allows to record 20 sec only.

 

 

Voice recording applet functionality

 

1.        Voice capture from sound card. The sampling frequency is 16000Hz.

2.        16kbps voice compression ( 117K per minute).

3.        Playback of the recorded voice file from the client computer for sound quality and content evaluation.

4.        Uploading of voice file to web server via HTTP.

5.        Playback of the voice files  from the web server in the streaming mode.

 

The voice recording applet is developed in Java 1.1. So, the client does not need to install  a big size Java 1.3 plug-in or upgrade a Java Virtual Machine (JVM) ( i.e. applets work on the target browsers with default browser JVM installation).  The recording applet uses native methods for sound capture. They are developed in C++ and implemented as DLL (jaudio16k.tar). The DLL 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.

The recording applet has the following controls:

-        Record – to start the record;

-        Pause  - to pause the record and playback;

-        Play – to playback the recorded voice file from the client computer for sound quality and content evaluation;

-        Stop – to stop the record and playback;

-        Send – to upload recorded the voice file to server. Name of voice file must be entered in the “Please enter file name” field or created by JavaScript possibilities and passed to UPLOAD_RP() JavaScript method;

-        Listen – to playback from the web server in streaming mode. The name of the voice file must be entered in the “Listen from Web-server” field or created by JavaScript possibilities and passed to WEBPLAY_RP() method;

-        Status line – to indicate the status messages;

-        Timer – to indicate the current time / maximal recording time in the recording mode,   current time / voice message duration in the playback mode;

 

The controls interact with the applet via JavaScript.  It is possible to hide some controls and not to use them.

To receive the voice files from the recording applet, the script runs on the server.  SDK contains 2 variants of server script – developed in Perl and in ASP with dll.

 

Table of the voice recording applet parameters:

 

Applet parameter name

Parameter value

Parameter description

“ServerScript”

e.g. "http://www.vimas.com/voicefiles/retrive.pl"

Server script URL

" VoiceDestPath "

e.g.

 "http://www.vimas.com/voicefiles/"

URL of directory in which the voice files are stored. URL is necessary to playback from server.

 

“ TimeLimit ”

1…3599

 

This is maximal recording time in seconds

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

 

"BgColor"

Color number.       E.g.. “FFFFF”

Applet window background color.

 

Top

 

 

Voice streaming applet functionality

 

1.     Playback  the voice files from the web server in the streaming mode.

2.     Voice file buffering.

 

The  voice streaming applet is designed in the Java 2 (VPlayerSDK16k.jar) and in the Java 1.1. (VPlayerSDK16k.cab). Both files must be located on the server.  So, if on the client computer the Java 2 is installed,  the VPlayerSDK16k.jar is used automatically.   If only Java 1.1 is installed  – VPlayerSDK16k.cab is used to playback.

Note! VPlayerSDK16k.jar and VPlayerSDK16k.cab playback the voice with 16kHz and 8kHz sampling frequency correspondingly. So, for better sound quality, the Java 2 should be installed on the client computer.

 

The playback applet has the following controls:

-        Play – to playback from the web server in streaming mode.

-        Pause - to pause the playback;

-        Stop – to stop the playback;

-        Status line – to indicate the status messages;

-        Timer – to indicate the current time / voice message duration;

-        Slider – to indicate the audio file downloading process and the fast forward/backward rewind. The geometrical length of the slider corresponds to the audio file duration.  Moving black line which fills the slider line indicates the buffering process. To fast forward/backward rewind you can take the slider knob by left mouse button and remove it to a new position or click by mouse on the new position on the slider line.

 

The playback applet has a buffer for an audio file. When you listening the audio clip for the first time, the buffer is filled. So, when you listen the audio clip again, you listen it from buffer but not from the server. If you do not want to use the slider, you can hide it.  To hide the slider, use the corresponding applet parameter.

 

Table of streaming applet parameters:

 

Applet parameter

Parameter value

Parameter description

“ VoiceUrlSpec ”

E.g. "http://www.vimas.com/voicefiles/demo_e.wrm"

URL and name of audio file.

"VoiceUrlContext"

E.g. "http://www.vimas.com/voicefiles/"

URL of audio file.

"BgColor"

For instance: “FFFFF”

 

 Set the slider color.

"bufferingDisable"

“true” / ”false”

“true” – every time when you click the Play button, the applet starts to download the voice file from the server.

“false” (or parameter is absent)  -  when you click the Play button, the streaming from the server is started when you play the voice file for the first time only. Next times the applet playbacks the voice file from the buffer.

 

“sliderStatus”

“hidden”

“hidden” – hide the slider.

Parameter is absent – show the slider.

 

 Top

 

Voice Recording Applet SDK package consists of:

 

1.   Voice recording applet.

2.   Voice streaming applet.

3.   Sound capture/playback  DLL.

4.   Server programs.

5.   Examples.

6.   Documentation.

 Top

 

The JavaScript interface

 

The JavaScript interface allows to customize the applets to your web site scenario and style. It allows to design the own buttons and to send the names of files for recording and playback from JavaScript to applets. Also, the applet sends the status message and duration of  the record to JavaScript.

 

 

The table of the voice recording applet methods:

 

Accessible applet methods from JavaScript

Applet action

RECORD(  )

Start the recording/compression of audio data

PLAYBACK (  )

Start the playback from client PC

PAUSE (  )

Playback pause

STOPRP (  )

Stop the record or playback

UPLOAD (  String filename )

Uploads voice file from client PC to web server.

Server script program responsible for file receiving

WEBPLAY ( String filename )

Playback the recorded voice file from the server.

Accessible JavaScript methods from applet

 

SetStatus_RP( s )

Applet sends status message to JavaScript

SetTimer_RP( s )

Applet sends current recording/playback time to JavaScript

confirmRecord(s)

Confirm re-recording

addName(s)

Adds voice file name to list of files for listening from web server.

report_RP(s)

Pop-up message

 

 

 

 

The table of the voice streaming applet methods:

 

Accessible applet methods from JavaScript

Applet action

PLAYBACK(String filename )

Starts the playback from client PC

PAUSE(  )

Playback pause

STOP_PLAY(  )

Stop the playback

Accessible JavaScript methods from applet

 

report_P(s)

Pop-up message

setStatus_P(s)

Applet sends status message to JavaScript

setTimer_P(s)

Applet sends current recording/playback time to JavaScript

 

 Top

 

Installation

1.  for Unix server:

 

1.1. Create on the server the directory   /voicefiles  and /recorder relatively of the DocumentRoot virtual domain (root of the web server). For example:

www.vimas.com
 

voicefiles
 
 

 

 

 

 

 

recorder
 
 

 

 

 

    In the /voicefiles directory the recorded voice files will be stored.

 

1.2. Put into /recorder directory the following files:

-       RPApplet16.cab, RPApplet16.jar – recording applet,

-       jaudio16k.tar – voice capture dll,

-      VPlayerSDK16k.cab, VPlayerSDK16k.jar – voice streaming applet,

 

1.3.  rec_app.html and play_app.html – are examples of using of the recording and streaming applet correspondingly.

Put the rec_app.html, play_app.html  into the directory where your *.html files are stored.

In the CODEBASE applet parameter you must indicate the path to applets.

For instanse:

CODEBASE = "http://www.vimas.com/recorder/"

 

Change in the rec_app.html and play_app.html  examples the VIMAS Technologies web server URL  http://www.vimas.com/ to your URL.

 

 

1.4.Put to the cgi-bin directory the retrive.pl file.

 

1.5. Modificate, if it is necessary,  the path in the 1st ,3rd ,  4th and 5th  lines of retrive.pl source code.

-      in the 1st line indicate the path where Perl is placed.

-      In the 3rd line indicate path for .log file.

-      In the 4th line  indicate the full path of the /voicefiles directory.

 

1.6. Set the permission  for the retrive.pl CGI-program.  Use  chmod 755 retrive.pl  instruction 

    (web server administrator can do it).

 

 Top

 

2. for IIS:

 

2.1.  Create on the server the /Inetpub/wwwroot/voicefiles  and  /Inetpub/wwwroot/recorder directories.

 

2.2.  Put into ... /recorder directory:

-  RPApplet16.cab, RPApplet16.jar – recording applet,

- jaudio16k.tar – voice capture dll,

- VPlayerSDK16k.cab, VPlayerSDK16k.jar – voice streaming applet,

 

2.3.   Put into ... /voicefiles directory:

-  retr.asp,

-  Retrieve.dll,

-  saver.dll.

 

2.4. rec_app.html and play_app.html – are examples of using of the recording and streaming applet correspondingly.

Put the rec_app.html, play_app.html examples into the directory where your *.html files are stored.

In the CODEBASE applet parameter you must indicate the path to applets.

For instanse:

CODEBASE = "http://www.vimas.com/recorder/"

 

 Change in the  rec_app.html, play_app.html  examples the VIMAS Technologies web server URL  http://www.vimas.com/ to your URL.

 

2.5.Register the Retrieve.dll and saver.dll as COM objects by using the regsvr32.exe program.

 

2.6.In the applet parameters:

  <PARAM NAME = "ServerScript"         VALUE = "/cgi-bin/retrive.pl">    change to

     VALUE= "/voicefiles/retr.asp"> .

 

You can customize the JavaScript code correspondingly to your web site style and design.

.

Top

 

How to register the applets

 

The Wideband Voice Recording Applet SDK package, which you downloaded, contains recording and streaming applets which can be used as demo or full functional applets.  To use applets as demo applets, you must add to applets parameters the following parameter:

 

<PARAM NAME = "Registration"                    VALUE = "Demo">

 

In this case 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 applets as full functional you must :

-        Order the Wideband Voice Recording Applet SDK  from VIMAS Technologies web site www.vimas.com.  Note! Usual license allows to use recording and streaming applets on the one web site. Therefore, applets are associated with URL of web site where they used.

-        Send to info@vimas.com the URL of web site where applets will be used. VIMAS Technologies will generate registration keys, which based on the URL and send them to you.  Registration keys are the *.txt files. Note! Recording and streaming applets have different keys. So, you will get 2 *.txt files.

-        Put the *.txt files on the server in the same folder with applets (*.cab, *jar files).

-        Change the Registration applet parameter :

 

<PARAM NAME = "Registration"        VALUE = "RegistrationKeyFileName.txt">

 Top

 

 

Troubleshooting

 

1.    Recording applet does not work properly.

  1.1.  I can not record the voice message

  1.2.  I can not upload the voice file to server.

2.   Playback applet does not work.

 

 

 

I can not record the voice message

 

You use rec_app.html example. You see the buttons on the page, push on 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  RPApplet16.cab and RPApplet16.jar must be located on the server in the same directory with web page which calls the applet ( rec_app.html).  The RPApplet16.cab and RPApplet16.jar can be placed also in the other directory, but in the APPLET CODE must be indicated the full path to RPApplet16.cab and RPApplet16.jar:  CODEBASE=http://www.yourURL.com/recorder/   

At first, please,  create the directories as in the documentation 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 jaudio16k.tar is installed on your computer. It is installed automatically when you use the applet for the first time. On the server the jaudio16k.tar must be located  in the same directory with RPApplet16.cab and RPApplet16.jar.  Probably, you were wrong and jaudio16k.tar is located in the other directory. 

c)     If voice 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. 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.

 Top

 

I can not upload the voice file to server

 

1. You recorded the voice 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 voice messsage...”, but after uploading the alert window appears with  “Your message could not be uploaded” message.

 Reasons:  something is wrong on the server side .

a)      check the /recorder and /voicefiles directories. They must be in the root of the server.

b)     If you use Unix based server, check the retrieve.pl file. It must be in the cgi-bin/  directory.  If retrieve.pl is there, pay your attention to the items 1.5  and 1.6

c)      If you use IIS, check the retr.asp, Retrieve.dll, saver.dll. They must be in the /voicefiles directory.  Retrieve.dll and saver.dll are COM objects, so they must be registered on the server as COM objects.

d)     If you use IIS, check the set up of the  privileges on  NTFS-partition of  your server. Be sure that server program have write access to the /voicefiles directory.

 Top

 

Playback applet does not work

 

1. You push Play button, alert window with “Error. Object does not support  this property  or method” message is appears.

  Reasons:

a)      probably, playback applet is not downloaded from server to client machine. For successful downloading the  VPlayerSDK16k.cab and VPlayerSDK16k.jar must be located on the server in the same directory with web page which calls the applet ( play_app.html).  The VPlayerSDK16k.cab and VPlayerSDK16k.jar can be placed also in any other directory ( for instance: ../recorder ), in this case in the applet parameters must be indicated the full path to VPlayerSDK16k.cab and VPlayerSDK16k.jar:  CODEBASE=http://www.yourURL.com/recorder/   

 

 

2. You push the Play button, alert window with “Please check the voice file name” message is appears.

Reasons:

a)      probably, the “VoiceUrlContext” applet parameter is wrong. Please, check it. Full path to voice file must be indicated.

b)     Be sure that voice file is located in the directory which is indicated in the “VoiceUrlContext” parameter.

 Top

 

 
 

Appendix A

 

We present here, to illustrate how the applet sends a voice file to the server,  the fragment of Java source code which sends HTTP request (POST) to CGI-program.

 

 

URL url = new URL(Messages.scriptURL);

URLConnection urlConn = url.openConnection();

urlConn.setDoInput( true );

urlConn.setDoOutput( true );

urlConn.setUseCaches( false );

urlConn.setRequestProperty("Content-Type", "application/octet-stream");

OutputStream os = urlConn.getOutputStream();

os.write((HTTP_HEADER + contentLength + "\r\n" + "\r\n").getBytes());

os.write(HTTP_RequestUpload.getBytes());

os.write(VoiceBuf, 0, countBytesOfVoiceData);

os.flush();

os.close();

where -

    HTTP_HEADER = "POST" + "/cgi-bin/retrive.pl" + "HTTP/1.0" + "\r\n" + "Content-type: " + "application/octet-stream" + "\r\n" +                                 "Content-length: ";

  HTTP_RequestUpload = "ACTION" + "\r\n" + "CREATE" + "\r\n" + voiceFileOnServer + "\r\n";

 contentLength = HTTP_RequestUpload.getBytes().length + countBytesOfVoiceData;

 VoiceBuf - array voice data (size=countBytesOfVoiceData);

CGI-program return “ACCEPTED” if upload is successful and “IOException” – if error is occurred.

 Top

 

For support: info@vimas.com