BMS API Software Development Kit

Introduction

BMS can be controlled by other software. You can write your own programs to, for example, play announcements, start or stop the player, select music and more (read the commands below for the full list of features). This page sets out the information about how to do this using either the Command Line Reference or the Software Development Kit.

Command Line Reference

The Command Line Reference provides a simple way to issue commands to BMS through strings. How you pass the strings to the software is up to you, you can do it via software you are developing, or you can just do it via the Windows command prompt. All commands sent to BMS MUST have the BMS program location as the first string argument, followed by the commands that you want to issue. All commands are executed left to right, which means each command will be run as it is read in by the program.

The general syntax is: "C:\Program Files\NCH Swift Sound\BMS\bms.exe" [argument1] [argument2] etc.

The commands you can issue are as follows:

-x [player_name]: opens a specific BMS player with the name "[player_name]". If the player does not exist, it will be automatically created.

-play: starts the BMS player.

-stop: stops the BMS player.

-restart: restarts the BMS player.

-skip: skips the currently playing track.

-cmdstop: adds a command to the playlist to stop the BMS player.

-cmdrestart: adds a command to the playlist to restart the BMS player.

-clear: clears the playlist.

-exit: exits BMS.

-hide: hides the BMS window.

-show: shows the BMS window.

-load: load a file into BMS. File types expected here are *.bms and *.ann.

The default action is to load a file, so if you just pass a file name as the only argument, then BMS will try to load the file.

Examples:

Open the BMS player "InStore_Music": "C:\Program Files\NCH Swift Sound\BMS\bms.exe" -x "InStore_Music"

Open the BMS player "InStore_Music" and load the playlist "music.bpl": "C:\Program Files\NCH Swift Sound\BMS\bms.exe" -x "InStore_Music" -load "music.bpl"

Hide the main BMS player: "C:\Program Files\NCH Swift Sound\BMS\bms.exe" -hide

Restart the BMS player "InStore_Announcements": "C:\Program Files\NCH Swift Sound\BMS\bms.exe" -x "InStore_Announcements" -restart

Clear the playlist in the main BMS player and load the announcement file "my_announcements.ann": "C:\Program Files\NCH Swift Sound\BMS\bms.exe" -clear -load "my_announcements.ann"

  Back to top

Software Development Kit

NOTE: This information is intended for programmers only

This BMS API provides a system for other software to control the BMS not the other way round. If you want the BMS to run other software you should read the topic "Use a Plugin to Link to other Software (eg. Video Players)" from the BMS Manual. All examples and demonstrations below are shown in C++ but we hope you will have no difficulty in implementing the same functions using other languages (for example Visual Basic). The procedures below use a number of Windows API functions (eg. FindWindowEx, SendMessage etc.). If you need to know more about these functions and how to use them, refer to the Microsoft Windows API documentation.

Installing BMS

You need BMS v 3.02 or above installed to use the BMS API. To download and install the BMS now use this link https://www.nch.com.au/components/bmssetup.exe.

  Back to top

Running the BMS

Before any of the function calls below can be called, BMS must be running. The easiest way to do this is to set BMS to run automatically (see Settings).

However if for some reason you need to launch it from your program use WinExec, ShellExecute or CreateProcess to open:
  "C:\Program Files\NCH Swift Sound\BMS\bms.exe"
If you want it to run on the tray of the task bar add the argument /logon like this:
  "C:\Program Files\NCH Swift Sound\BMS\bms.exe" /logon
If your program does launch BMS, you will need to wait for it to create its window before FindWindow will succeed (see below).

  Back to top

Sending Commands to BMS

Commands are sent to the BMS Main Window. You first need to find the window "BMS Business Music System" using FindWindowEx and then use SendMessage to send a BMS Command Message to it (hex 7fff). Use code like this:

#define BMSAPI_WINDOWCAPTION "BMS Business Music System"
#define WM_BMSAPI_COMMAND 0x7fff

int BMSAPISendCommand(int iBMSCommand, LPARAM ExtraData)
{
   HWND hwndBMS = FindWindowEx(NULL, NULL, NULL, BMSAPI_WINDOWCAPTION);
   if (hwndBMS == NULL) {
     // BMS not running.
     // Either attempt to run BMS 
     // or spit out error message here...
     return 0;
   }
   return SendMessage(hwndBMS, WM_BMSAPI_COMMAND, iBMSCommand, ExtraData);
}

inline int BMSAPISendCommandSimple(int iBMSCommand) 
              { return BMSAPISendCommand(iBMSCommand, 0); }

int BMSAPISendCommandString(int iBMSCommand, const char* szStringToSend)
{
   ATOM atomExtraInfo = GlobalAddAtom(szStringToSend);
   int iReturnValue = BMSAPISendCommand(iBMSCommand, (LPARAM)atomExtraInfo);
   GlobalDeleteAtom(atomExtraInfo);
   return iReturnValue;
}

BMSAPI Commands

inline int BMSAPIGetVersion() { return BMSAPISendCommandSimple(0); }
// Returns the current API version which is currently 1.
// If 0 is returned the BMS or API is not available.
// If 2 or above is returned please contact us for updated documentation.

inline void BMSAPIOpenBMS() { BMSAPISendCommandSimple(1); }
// Opens BMS if it is on the tray.

inline void BMSAPICloseBMS() { BMSAPISendCommandSimple(2); }
// Reduces BMS to the tray.

inline void BMSAPIExitBMS() { BMSAPISendCommandSimple(3); }
// Exits BMS completely. API commands will no longer be accepted.

inline void BMSAPIPlayerStart() { BMSAPISendCommandSimple(4); }
// Starts the Player. 

inline void BMSAPIPlayerStart() { BMSAPISendCommandSimple(5); }
// Stops the Player. 

inline void BMSAPIPlayerSkip() { BMSAPISendCommandSimple(6); }
// Skips the currently being played track. 

inline void BMSAPIMicPageOn() { BMSAPISendCommandSimple(7); }
// Turns Microphone Page On. 
// The Microphone Page must be enabled using Settings.
// You must call BMSAPIMicPageOff() otherwise it will be left on.

inline void BMSAPIMicPageOff() { BMSAPISendCommandSimple(8); }
// Turns Microphone Page Off. 

inline void BMSAPIPlayAnnouncementNow(const char* szAnnouncementName) 
                   { BMSAPISendCommandString(9, szAnnouncementName); }
// Plays the announcement named szAnnouncementName.
// szAnnouncementName is the name only (not path and without extension)
// The announcement is played now 
//             (ie. currently playing item is interrupted)
 
inline void BMSAPIPlayAnnouncementNext(const char* szAnnouncementName) 
                   { BMSAPISendCommandString(10, szAnnouncementName); }
// Plays the announcement named szAnnouncementName.
// szAnnouncementName is the name only (not path and without extension)
// The announcement is played next.
//             (ie. after the end of the current item)
 
inline void BMSAPIListAnnouncement(const char* szAnnouncementName) 
                   { BMSAPISendCommandString(11, szAnnouncementName); }
// Adds the announcement to the bottom of the playlist.
// szAnnouncementName is the name only (not path and without extension)

inline void BMSAPIListMusic(const char* szTrackName) 
                   { BMSAPISendCommandString(12, szTrackName); }
// Adds the music track to the current playlist.
// szTrackName is the name only (not path and without extension)

inline bool BMSAPIIsPlayerStopped() 
                   { return BMSAPISendCommandSimple(13) == 1; }
// Returns true if the player is currently in stopped mode.

inline int BMSAPIGetPlayerRemainTime()
                   { return BMSAPISendCommandSimple(14); }
// Returns the time to the end of the current item in ms.
// This does not include the time remaining in the playlist.

inline int BMSAPIGetPlayListTotalTime()
                   { return BMSAPISendCommandSimple(15); }
// Returns the total time of all items in the playlist in ms.
// This does not include the current playing item time.

Changing BMS Settings

Some settings may require a player stop and restart or a BMS exit and rerun to take effect.

  Back to top

Changing an Announcement or Music Track Setting

There are subfolders "Music" and "Announcements" within the BMS folder. Within these each audio recording (wav or mp3) has a related Rich Audio Format (raf) file. These have a similar format to ini files and can also be opened with Notepad for viewing and written to using WritePrivateProfileString.

  Back to top

Other Information

If you have problems writing your application, please Contact Us for support.

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 BMS. Costs start from around $US100 for a simple function but can increase to $10,000+ for development of a complete new release application. Please visit our Software Development page to request a quote.

We can also rebrand BMS with your logo and details for a small fee. Please see our Resellers page for more information.

You can distribute the BMS install file with your software (but you may not under any circumstances distribute registration keys or seek to undermine the registration system). See the BMS license terms (on the Help file). Normally your customers would purchase the BMS directly from us. We also provide easy license terms if you do need to distribute registered versions of the BMS. Please see our Resellers page for more information.

  Back to top