Media API

Here is where you may find research on undocumented Media API calls. The hope is to enable earpiece playback, microphone recording, and perhaps even raw video access.

Your application must use the "com.palm" namespace to access these APIs. That is, your app's ID must start with "com.palm" if you want to be able to call these services. Sadly, this would exclude your app from Palm's App Catalog, though it should be fine for inclusion in Preware.

Playback through earpiece

Earpiece playback is achieved by specifying a new audio playback scenario to the audio service. There seem to be three main "modes" for audio playback (media, phone, and voice_dialing). These examples control the media mode (which is what application developers will be using) but can be adapted to change other modes too.

This code will cause further audio playback to be directed to the earpiece: <source lang="javascript"> var request = new Mojo.Service.Request('palm://com.palm.audio/media', {

   method: 'enableScenario',
   parameters: { "scenario":"media_front_speaker" },
   onSuccess: function() {
       var request2 = new Mojo.Service.Request('palm://com.palm.audio/media', {
           method: 'setCurrentScenario',
           parameters: { "scenario":"media_front_speaker" },
           onSuccess: this.playSomeSoundThroughTheEarpiece(),
           onFailure: this.logFailure()
       });
   }.bind(this),
   onFailure: this.logFailure()

}); </source>

This code will revert audio playback back to the speaker: <source lang="javascript"> var request = new Mojo.Service.Request('palm://com.palm.audio/media', {

   method: 'disableScenario',
   parameters: { "scenario":"media_front_speaker" },
   onSuccess: this.logSuccess(),
   onFailure: this.logFailure()

}); </source>

If you enable the earpiece at some point during your app's run, you MUST remember to reset the playback to use the speaker before your app exits. Always put things back the way you found them!

The list of available scenarios can be found by calling the 'listScenarios' method: <source lang="javascript"> request = new Mojo.Service.Request("palm://com.palm.audio/media/listScenarios", {

   parameters: { "enabled": true },
   onSuccess: this.printScenarios(scenarios),
   onFailure: this.logFailure()

}); </source>

The current list of scenarios for all modes seems to be:

media_front_speaker
media_back_speaker
media_headset
media_headset_mic
media_a2dp
media_wireless

phone_front_speaker
phone_back_speaker
phone_headset
phone_headset_mic
phone_bluetooth_sco
phone_tty_full
phone_tty_hco
phone_tty_vco

voice_dialing_front_speaker
voice_dialing_headset
voice_dialing_headset_mic
voice_dialing_bluetooth_sco

Additional methods off the Audio service include get/setLatency, get/setVolume, lockVolumeKeys, and setMuted.

Audio recording

There is a test service that the interactive tests use to perform certain actions including recording audio. It is just a wrapper for calling other linux utilities. This is obviously not ideal, since somewhere things like the phone app must be able to access the microphone directly, but it's a start...

This code will record audio to a WAV file located at /var/tmp/recordTestFile.wav. The service simply shells out to 'arecord', using the PCM audio device named 'record': <source lang="javascript"> var request = new Mojo.Service.Request('palm://com.palm.crotest', {

   method: 'RecordSound',
   parameters: {"duration": 15},
   onSuccess: this.logSuccess(),
   onFailure: this.logFailure()

}); </source>

I am not certain that the duration parameter will be honored, since no application seems to use it, but the service seems to provide it. The service may also provide a "file" parameter to specify the output file, but I am less certain about this. Perhaps a more configurable version would be a good call to add to the utility service?

When you are done with the recording, you should delete it. The service presumably simply shells out to 'rm': <source lang="javascript"> var request = new Mojo.Service.Request('palm://com.palm.crotest', {

   method: 'RemoveRecording',
   parameters: {},
   onSuccess: this.logSuccess(),
   onFailure: this.logFailure()

}); </source>

You can also use this test service to play an arbitrary WAV file. The service simply shells out to 'aplay': <source lang="javascript"> var request = new Mojo.Service.Request('palm://com.palm.crotest', {

   method: 'PlaySound',
   parameters: {"file":"/var/tmp/recordTestFile.wav"},
   onSuccess: this.logSuccess(),
   onFailure: this.logFailure()

}); </source>