VRS
Software Development API

This is the API that lets other programs control the VRS Recording System.

Most of the documentation refers to C++ code but with careful reading you should easily be able to implement it in other languages (eg. VB).

If you are using C++, you should include the source files vrsapi.h and vrsapi.cpp in your project. These give you immediate access the the VRSAPI functions as described below. The vrsapi.h and vrsapi.cpp files compile under most compilers (including Visual C++, Borland C++ and gcc).

We have also included an example file (which is actually the source code of vrscmd - the command line equivalent).

If you find this all too hard, you can consider using vrscmd - the command line equivalent. You can download that from www.nch.com.au/vrs/sdk.html.

Contents

Running VRS

Before any of the function calls below can be called, VRS must be running. The easiest way to do this is to set VRS to run automatically, but if you need to launch it from your program use ShellExecute or CreateProcess to open:
"C:\Program Files\NCH Swift Sound\VRS\vrs.exe"

If you want it to run on the task bar tray add the argument /logon like this:
"C:\Program Files\NCH Swift Sound\VRS\vrs.exe" /logon

If your program does launch VRS, you will need to wait for it to create its window before FindWindow will succeed (read on).

Finding the VRS Main Window

Commands are Sent to the VRS Main Window. To find the window use code like this:

HWND VRSAPIFindWindow() { return FindWindowEx(NULL, NULL, NULL, TEXT("VRS Recording System")); } Starting the Recorder

Note: Before you can control recording using the API, you must setup each channel of VRS to be in manual mode. If the channels are not in manual mode, commands are ignored.

To start the recorder on a specified channel send the MCI_RECORD message to the VRS Main Windows like this:

void VRSAPIStartRecorder(int nChannelZeroBased) { HWND hWndVRS = VRSAPIFindWindow(); if (hWndVRS == NULL) { // VRS not running. Run it or spit out error return; } SendMessage(hWndVRS, MCI_RECORD, (WPARAM)nChannelZeroBased, NULL); } You can also specify the recording name by sending an ATOM containing the file name: void VRSAPIStartRecorder(int nChannelZeroBased, const char* szFullPathToWaveFile) { HWND hWndVRS = VRSAPIFindWindow(); if (hWndVRS == NULL) { // VRS not running. Run it or spit out error return; } ATOM atomExtraInfo = GlobalAddAtom(szFullPathToWaveFile); SendMessage(hWndVRS, MCI_RECORD, (WPARAM)nChannelZeroBased, atomExtraInfo); GlobalDeleteAtom(atomExtraInfo); } We do not recommend you specify a name unless you really need to. Your application must ensure the file name is unique. Recording must not be allowed to exceed 60 minutes (otherwise VRS creates a new file in the normal folder). Recording must be stopped before the VRS is closed or the system is shutdown.

Stopping the Recorder

To stop the recorder (or a specific recorder channel), use the MCI_STOP message as follows:

void VRSAPIStopRecorder(int nChannelZeroBased) { HWND hWndVRS = VRSAPIFindWindow(); if (hWndVRS == NULL) { // VRS not running. Run it or spit out error return; } SendMessage(hWndVRS, MCI_STOP, (WPARAM)nChannelZeroBased, NULL); } Stop can take up to 750ms to take effect. If you restart the recorder within this time it will just continue recording the old file. (ie. You must add a wait timer and poll VRSAPIIsRecording to start a new file).

Testing whether a channel is recording

Use the MCI_STATUS message to test if a channel is recording (TRUE) or stopped (FALSE).

bool VRSAPIIsRecording(int nChannelZeroBased) { HWND hWndVRS = VRSAPIFindWindow(); if (hWndVRS == NULL) { // VRS not running. Run it or spit out error return; } return SendMessage(hWndVRS, MCI_STATUS, (WPARAM)nChannelZeroBased, NULL); } Providing data to be associated with a recording

Data can be associated with the recording. For example, your software can send a file reference relating to a current recording. This data with then be displayed and can be searched on using VRS Find & Play.

void VRSAPISetRecordingData(int nChannelZeroBased, const char* szData, bool bPersists = false) { HWND hWndVRS = VRSAPIFindWindow(); if (hWndVRS == NULL) { // VRS not running. Run it or spit out error return; } ATOM atomExtraInfo = GlobalAddAtom(szData); SendMessage(hWndVRS, MCI_SET, (WPARAM)MAKELONG(nChannelZeroBased,bPersists), atomExtraInfo); GlobalDeleteAtom(atomExtraInfo); } Data can be set at any time prior to starting recording or during recording. Normally data will automatically be cleared when the recording stops. If bPersists is true however, the data will be applied to all further recordings on the line until you clear the data (by sending a empty string).

Use of MCI_ constants

The VRS API uses MCI_ constants simply because they are reserved by Microsoft, can be easily identified and are normally already defined in your header files. The functioning is not intended in any way to conform to the description in the MCI API.

The MCI_ constants used above are defined in the Windows API documentation but if your compiler does not have them, these are the values:

#define MCI_RECORD 0x080F #define MCI_STOP 0x0808 #define MCI_STATUS 0x0814 #define MCI_SET 0x080D

Other Information

If you have problems writing your application, please go to www.nch.com.au/vrs/support.html and use the form to contact us.

If you wish to distribute the VRS packaged with your software you should consider the very easy and affordable OEM licence terms for distributing VRS. See www.nch.com.au/reseller for more information.

We also offer corporate software development services if you want us to do the development for you or if you need more substancial changes to the VRS. Costs start from around $US300 for a simple function but can increase to $10,000+ for development of a complete new release application. Please see www.nch.com.au/development for contact details to request a quote.

We can also rebrand VRS with your logo and details for a small fee (see http://www.nch.com.au/reseller for more information).

You can distribute the VRS install file with your software (but you may not under any circumstances distribute registration keys or seek to undermine the registration system). See the IVM licence terms (on the Help file). Normally your customers would purchase the IVM directly from us. We also provide easy licence terms if you do need to distribute registered versions of the IVM. Please see http://www.nch.com.au/reseller under the Software Blanket Licence heading.

More Information...

For more information please see: