Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 7 - Sound / Using Sound

Using the NewtonScript API to Record Sound

Because sound recording requires some user interface controls to start and stop the recording process, there is no single programmatic interface for recording equivalent to the *PlaySound function. However, there is a ready-made sound recording proto and slip that you can use to quickly add sound recording and playback capabilities to any application; for details, see the previous subsections, "Using the protoRecorderView" and "Using the Built-in Sound Recorder Slip."

If you want to create your own sound recording interface and programmatically control everything, then you'll need to use the NewtonScript API directly, as described in this subsection.

To record sound programmatically, you must do these steps:

1. Create a new sound channel.
2. Open the sound channel.
3. Allocate a block of memory to hold the recorded sound samples.
4. Schedule the recording.
5. Start the recording.
6. Finally, stop recording.

This whole process is shown in Listing 7-1.

Listing 7-1 Sound input

 // callback function passed to NewInputBlock below

MyCallback: func(state, result) begin
if self.notdone then begin // test a flag to see if we're done
   // if so, continue with another input block
   local anotherSound := myChannel:NewInputBlock(MyCallback);
   myChannel:Schedule(anotherSound);
   end
else
   // if we're done, then close the channel
   myChannel:Close();
end

// sound input sample code; first initialize and open the channel
myChannel := protoSoundChannel:NewRecording();
myChannel:Open();

// good idea to create and schedule 2 input blocks initially
local mySound := myChannel:NewInputBlock(MyCallback);
local anotherSound := myChannel:NewInputBlock(MyCallback)
myChannel:Schedule(mySound);
myChannel:Schedule(anotherSound);
 myChannel:Start(true);

You first create a new sound channel using the method *protoSoundChannel:*NewRecording. This creates a sound channel that is properly initialized for recording. Next, open the sound channel by sending it the Open message. Then, create a new block of memory to hold the recorded samples by sending it the *NewInputBlock message, which returns a sound frame. The samples slot in this sound frame holds a virtual binary object (VBO) that is allocated for the sample data. This size of the VBO is determined by the value of the inputBlockSize slot in the sound channel, which defaults to 65536 bytes.

If you might need to record more than one buffer's worth of input data, it's a good idea to allocate and schedule two input sound frames initially, to provide double-buffering. This way, the next buffer is always ready immediately, if needed.

Next, schedule the recording by sending the sound channel the *Schedule message, passing the new sound frame as a parameter. Finally, you can start recording by sending the *Start message to the sound channel. After you send the *Start message, there will be about a half-second delay while the sound hardware powers up before recording starts.

The Sound Manager then records sound into the scheduled sound frame. Once the samples VBO is full, it calls the callback function object provided by the sound frame. Then, the Sound Manager looks to see if there is another scheduled sound frame to continue recording into, and if so, it continues recording into the next sound frame. It is your responsibility to ensure that enough sound frames are scheduled to keep recording.

It is also your responsibility to keep track of which sound frames have been created and scheduled, and to update the size of the final input block (samples VBO) when the stop button is pressed. The return value of the *Stop method is a result frame (page 7-31) that indicates where in the sample data recording was stopped, so you can adjust the size of the VBO in the last sound frame to be just large enough to hold the recorded samples. Here is an example of how to use the *SetRecordingLength method do this:

 // stop recording and trim last VBO size

local result := myChannel:Stop();
local sound := result.sound;
local numSamples := result.index;
 sound:SetRecordingLength(numSamples, nil);

Setting the Input Gain

For recording, you can specify an input gain, which is an amplification applied to the incoming signal. The input gain can have a value ranging from 0 to 255. If the input gain is 0, then the incoming signal is not amplified at all; if the input gain is 255, then the signal is amplified by an amount that the driver has determined to be a maximum desirable amount. The middle value of 128 is considered to be an "optimal" setting for normal use.

You can set the initial input gain by setting the inputGain slot of the *protoSoundChannel. After the channel is open, you can change the input gain by using the method *SetInputGain. The method *GetInputGain returns the current input gain of the channel.

The behavior of the input gain can seem non-intuitive. The signal that comes from the internal microphone on the MessagePad 2000 is a very weak one, and the system relies on the input gain to boost it to a level that you can hear. Thus, when you are using the internal microphone and you set the input gain to 0, the recording will be silent.

The signal that comes from the line-in jack, however, is much stronger. When the input gain is set to 0, the recording is quite loud, which you might not expect if you think about it as an input volume instead of an input gain. In both cases, the default value of 128 instructs the device to amplify the signal to an "optimal" level.

The system does not support a self-adjusting input gain.

In the Recording slip of the Prefs application, there's a slider that lets the user adjust the input gain (Recording volume). If the inputGain slot of the sound channel is nil, this user preference setting is used (which is stored in the inputGain user configuration variable).