Transmitting An Audio File With engage-cmd

Beginning with version 1.206.9042 of the Engage Engine we now support the ability to use an audio file as a virtual microphone to use in place of the computer's microphone or an Application-Defined Audio Device.

This capability is exposed in new JSON parameters to the engageBeginGroupTxAdvanced API function and can be utilized by any application using the Engage Engine.

One of those applications is the engage-cmd tool which exposes the capability in it's scripting language as well as a simple command-line parameter. In this article we'll talk about how to make that happen using the command-line.

By Example

So let's say we want to transmit a pre-recorded announcement on an Engage group. We're going to need to fire up engage-cmd with the usual configuration its interested in and then provide it with informnation about the file to be transmitted.

So, as with any other time you use engage-cmd, you're going to need an Engine policy file and a mission configuration. (You may also need a certificate store or another acceptable mechanism to provide the Engine with it's X.509 certificates).

So, let's say our policy file is named policy.json and our mission is named m1.json, our basic command-line to get things going is going to look as follows:

$ engage-cmd -ep:policy.json -mission:m1.json

That'll get you to engage-cmd's prompt where you'd normally enter your commands. But, here, all we want to do is fire up the tool, join the groups we care about, transmit the audio file, and then exit. So we're going to have tell engage-cmd the name of the audio file.

But, before we do that, we have to deal with the format of the audio file.

Audio File Format & Content

As described above, the Engage Engine will read the file as if it was reading audio directly from the microphone. So, ideally, our file should match that format.

First off, Engage needs the individual audio samples to be encoded as signed, 16-bit linear PCM in little-endian format. Then, those samples need to be sampled at a rate that Engage will support. That rate can either be 16Khz or 8Khz and is established in the Engine's policy configuration. Also, the number of channels (1 or 2) is important as the Engine could be configured for either 1 channel (mono) or 2 channels (stereo). [The Engine's default format is 16Khz, stereo (2 channels).]

Bottom-line, the audio file should ideally be signed, 16-bit linear PCM little-endian at a sampling rate of either 16Khz or 8Khz rate and mono or stereo. AND the configuration in the Engine's policy needs to match those settings.

Now, that's the ideal situation. But, if you give Engage a file format that it can convert, then it will try its best to do so. For example: if you Engine is configured for 16Khz, stereo, but your audio file is 8Khz mono; then Engage will upsample the 8khz to 16Khz and "inflate" mono to stereo. Or maybe your file is 44.1Khz stereo and your Engine is configured for 8Khz mono. There, too, Engage can do that conversion to downsample from 44.1Khz to 8Khz and "deflate" the stereo to mono.

But here's the catch ... Engage has to know what the file format is. And the only way it can do that is to process a file that has a header in it describing the audio content. For now, though, Engage only supports Microsoft .WAV files (they're pretty common of course so that shouldn't be a problem). Therefore, if you give Engage a .WAV file that doesn't match the Engine internals, it'll probably be able to do the conversion automatically.

Raw Files

You can also pass a raw audio file to Engage - i.e. not a .WAV file. A raw file is simply the actual audio samples themselves while a .WAV file contains those samples as well as a header that describes the samples. When Engage encounters this kind of file, it cannot check the format and will therefore assume that the format matches the Engine's configuration. If it doesn't your audio is going to sound pretty nasty!

NOTE: Engage is pretty convservative when it comes to CPU and memory utilization so, if you give it a .WAV file that needs conversion (resampling and/or channel conversion), you'll likely see a warning in the log that the Engine is incurring a performance hit. (This kind of stuff is pretty CPU intensive.) So, whenever possible, use a file format that exactly matches your Engine configuration.

Actually Playing The File

Playing the file is as easy as adding the -tf parameter (which stands for "transmit file"). So, if our audio file is named a_raw_announcement.raw, our command line looks as follows:

$ engage-cmd -ep:policy.json -mission:m1.json -tf:a_raw_announcement.raw

If the file's name is a_wav_announcement.wav, the command-line would be:

$ engage-cmd -ep:policy.json -mission:m1.json -tf:a_wav_announcement.wav

Checking The Result

Once the operation has completed and engage-cmd exits, you'll likely want to see if things all worked out. You do this by checking the process exit code. If all went well, engage-cmd will exit with an exit code of 0. If something went wrong, a value other than 0 will be returned. Then, its a simple matter for your OS shell to check that exit code.

For example: on *nix-style systems, you'd check the value of $?. On Windows, you'd check errorlevel.