GSM®-based devices have 2 audio channels which allows allows applications to simultaneously start two MMAPI Players - one for recording and one for playback. This is beneficial to create for VoIP (Voice over IP) applications. Unfortunately it is also widely known that due to hardware limitations CDMA-based devices only have 1 audio channel, preventing the same behaviour and ultimately from building VoIP applications. That is, until BlackBerry® OS 184.108.40.2064 (bundle 2333).
There are a number of conditions to be able to use this new functionality that your application must adhere to. In this article you will find out how to use this new capability, as well as learn how it works under-the-covers and ultimately understand what it can and can't do.
As documented in the OS 6.0 javax.microedition.media.Manager Java® docs, extra BlackBerry-specific parameters can be passed into the Locator String used to create the recording player to enable this feature. The ability to record and playback at the same time rests on the fact that the underlying CDMA-based hardware has a vocoder (voice encoder/decoder) that can handle simultaneous record and playback of (only) voice codecs. Applications can access this low-level hardware as of BlackBerry OS 220.127.116.114 (bundle 2333) and above (not BlackBerry OS 5.0 unfortunately). Because of the nature of the vocoder hardware, this ability comes with some caveats largely beyond our control which can make this feature seem difficult to use:
The voice codec used (as passed in the locator encoding= parameter) must be either audio/amr or audio/qcelp (and not audio/gsm)
The voice codec used for playback and recording must be the same (i.e. either amr or qcelp)
The bitrate (in bits/second) of the codec must be the same for playback and recording, and must be valid for that codec (see below)
The order of player creation should not matter, but the recording player must be started before the playback player
The recording and playback players must both be created by the same application
The playback player created must be fed data from a stream rather than a file (i.e. either an InputStream or a DataSource)
In addition to the encoding= parameter, two other parameters are required to make this work, and order should not matter:
The first parameter required is voipmode= which can have either the value true or false. On GSM-based devices this parameter will be ignored when passed into a locator string (this applies to all BlackBerry OS versions 6.0 and prior). This is because GSM-based devices can already do this so enabling the vocoder is not necessary. On CDMA-based devices running BlackBerry OS 5.0 and earlier, it is also ignored.
The next parameter is rate= where the value passed in must be a valid value that depends on the encoding/codec you are using. Both AMR and QCELP codecs define a strict set of bitrates that are valid for each. This table gives the valid values (specified in bits per second) for each codec:
These values correspond to AMR-NB Modes 0-7 respectively
1000 / 2700 / 6200 / 13300
These values correspond to QCELP-13 Eighth, Quarter, Half, and Full-Rates respectively
As an aside, the rate= parameter is not honoured on GSM-based phones or CDMA-based phones that do not specify voipMode=true or that do not implement use of the vocoder. In other words, it is not honoured in any case except when using a simultaneous player and recorder in this mode on CDMA phones.
The audio path set on the player doing the recording will take precendence over the audio path set on the player doing the playback. That doesn't just apply to this CDMA-VoIP case being discussed here, but in all cases where recording and playback are happening at the same time, and on all phones in all BlackBerry OS versions. Generally it is a good idea to set the same audio path on all players your application creates so that the audio path is always in sync and known to the application. This is also important because when the recording player is stopped then audio routing will default to whatever is set by the playback player, or to the default audio path if none was specified.
When creating your player for recording, you are also still able to specify the updateMethod= and updateThreshold= parameters on the recorder to control how often data is written to the stream, specified either in time or data size as the Manager class JavaDocs indicate.
Finally, the order that the recording player or playback player are stopped does not matter, but remember that the recording player must be restarted first to resume simultaneous recording and playback on CDMA-based devices that enable it. This restriction does not apply to GSM-based devices, but you probably already guessed that!