Websites Navigation: Airbit | Shop | m-shell.net
Languages: EN | DE

Module audio: Playing and Recording Sounds

This module provides audio functions: generating synthetic beeps and DTMF sequences, playing most audio file types (e.g. MP3), and recording and editing AU format, WAV format or AMR-NB format files.

To directly play an existing audio file, use audio.play.

To play parts of a file or record to a file, use audio.open, followed by calls to audio.play, audio.record and audio.stop.

Each file has a recorded length (its "duration") and the "head position" the player is at or will start at. Both are measured in milliseconds. audio.len and audio.pos access them. audio.cut cuts a part out of a recording.

Please note: while it is possible to record phone conversations on most devices using this module, due to limitations in the underlying Symbian OS APIs, sound cannot be sent to a phone uplink on some devices. The behaviour when playing tones or sound during a phone call varies between devices; some will throw ErrInUse, others will simply mute the sound. UIQ devices generally do not support playing sounds when a phone call is in progress.

audio.beep

• function beep(hz=880, ms=800) → null

Plays a synthetic beep with frequency hz Hertz for a duration of ms milliseconds.

This function immediately returns, before playing completes. Exceptions can therefore be thrown anywhere in the following code.

Throws ErrInUse if the sound unit is busy playing or recording another sound. Throws ExcValueOutOfRange if the frequency is not positive.

audio.beep(440, 1000)

audio.busy

• function busy() → Boolean

Returns true if the last playing function (audio.beep, audio.dtmf, audio.play) is still producing sound, or if sound is still being recorded (after audio.record). Returns false otherwise.

This function checks only the current m process: it will return false if the sound unit is in use by another process (inside or outside of m).

audio.beep(440, 1000);
while audio.busy() do
  io.print(io.stdout, '.'); sleep(200)
end;
print "beep ended"
→ .....beep ended

audio.close

• function close() → null

Closes the currently accessed audio file.

Throws ErrInUse if the file is being played or recorded. Thus, to forcibly close a file, use:

audio.stop();
audio.close()

audio.cut

• function cut(start, end=0) → null

  
Compatibility of function audio.cut
Sony Ericsson UIQ2 phones cannot truncate at the beginning, start=0 is mandatory.ErrNotSupported
Sony Ericsson UIQ3 phones cannot truncate at all.ErrNotSupported

Cuts the current audio file at the beginning and/or end. The initial start milliseconds and the final end milliseconds will be removed.

Throws ErrInUse if the file is being played or recorded, ErrAccessDenied if the file has not been opened for writing, and ErrArgument if any of the cropped parts are outside the current file.

// truncate the current file by 10% on both ends
audio.cut(0.1*audio.len(), 0.1*audio.len())

audio.dtmf

• function dtmf(digits) → null

  
Compatibility of function audio.dtmf
Some Nokia phones do not properly produce DTMF tones, and may set the tone playing device into an erroneous state.A call to audio.stop may be required to reset the device.

Plays the string digits as DTMF (dual-tone multi-frequency) tones ("tone dialling"). Valid characters for digits are 0 to 9, A to D, # and *. All other characters are ignored.

Throws ErrInUse if the sound unit is busy playing or recording another sound.

// play with ascending high frequency
audio.dtmf('147*2580369#ABCD')

audio.len

• function len() → Number

Returns the length ("duration") of the current file, in milliseconds.

Throws ErrNotReady if no file has been opened.

audio.open

• function open(file, flags=0, rate=8000) → Number
  Permissions: Read(file) / Read+Write(file)

  
Compatibility of function audio.open
Nokia phones and Sony Ericsson UIQ2 phones do not support AMR-NB format for recording.ErrNotSupported
Sony Ericsson UIQ3 phones do not support WAV and AU formats for recording.ErrNotSupported
Sony Ericsson UIQ3 phones cannot handle file suffixes other than .amr when recording.ErrNotFound, ErrNotSupported

Opens or creates a file for playing and/or recording, and returns the length of the file ("duration") in milliseconds.

Whether the file is opened or created is determined by flags:

• const rw = 1 Open an existing file for recording.
• const wav = 2 Create a file in Microsoft's WAV format.
• const au = 3 Create a file in Sun's AU format.
• const amr = 4 Create a file in AMR-NB format (Adaptive Multi-Rate, Narrow Band).

When creating a file, you may combine audio.wav or audio.au with one of the following flags selecting the codec:

• const alaw = 0 Use A-law compression (13-bit to 8-bit) codec.
• const mulaw = 16 Use μ-law compression (13-bit to 8-bit) codec.
• const pcm8 = 32 Use 8-bit direct pulse-code modulation codec.
• const pcm16 = 48 Use 16-bit direct pulse-code modulation codec.
• const ima = 64 Use IMA adaptive differential PCM codec.

audio.amr only supports its own codec.

To summarize: audio.open acts according to the following scheme:

  • If flags=0 (the default), opens the file for playing. Attempts to record to it or to truncate it will throw ErrAccessDenied.
  • If flags contains audio.rw, opens the file for playing and recording. Format, codec and sample rate will be taken from the existing file.
  • If flags contains audio.wav or audio.au, creates a new file in WAV or AU format, and the specified codec is chosen. rate indicates the sample rate in Hz (samples per second). The sample rates supported depend on codec and device.

    For a newly created file in WAV or AU format, the default codec is A-law.

Throws ErrInUse if a file is already being played or recorded.

// Create a new file with default codec and sample rate
file='sample.wav';
audio.open(file, audio.wav);
// record sound until the file exceeds 200 kB
audio.record();
while files.size(file)<=200000 do
  sleep(1000)
end;
audio.stop();
print 'Recorded',audio.len(),'ms in ',
  files.size(file),'bytes.';
print files.size(file)/audio.len(),' kB/s'
→ Recorded 25260 ms in 202124 bytes.
→ 8.0017418844 kB/s
// play the file
audio.play(); audio.wait()

// Do the same in full lossless CD quality
audio.open(file, audio.wav | audio.pcm16, 44100);
// record sound until the file exceeds 200 kB
audio.record();
while files.size(file)<=200000 do
  sleep(1000)
end;
audio.stop();
print 'Recorded',audio.len(),'ms in ',
  files.size(file),'bytes.';
→ Recorded 2900.158 ms in 255838 bytes.
→ 88.215193793 kB/s

audio.play

• function play() → null
• function play(file) → null
  Permissions: Read(file)

Without argument, starts or continues playing the currently open sound file.

With one argument, directly starts playing a sound file (.mp3, .wav, .au or such). The file name is relative to the current directory (see * ()). When the sound file has finished playing, it is closed.

This function immediately returns, before playing completes. Exceptions can therefore be thrown anywhere in the following code. Use audio.wait to wait for completion.

Throws ErrInUse if the sound unit is busy playing or recording another sound.

Without argument, throws ErrNotReady if no file has been opened, and throws ErrArgument if the current playing position is outside the file.

audio.play("c:\\documents\\audio\\Hello.mp3")

audio.pos

• function pos() → Number
• function pos(ms) → Number

Without arguments, returns the playing position in the current file, in milliseconds form the start.

With one argument, set the playing position to ms milliseconds.

Throws ErrNotReady if no file has been opened.

With one argument, throws ErrInUse if the file is being played or recorded.

// Open a file and play seconds 5 to 12
audio.open('sample.wav');
audio.pos(5000);
audio.play();
sleep(7000);
print audio.pos();
audio.stop()
→ 11850

audio.record

• function record(gain=100) → null

  
Compatibility of function audio.record
Sony Ericsson phones cannot record phone conversationsErrInUse
Sony Ericsson phones do not reliably detect unsupported sample rates, resulting in mismatches between sampled and played rates.
Sony Ericsson UIQ3 phones do not support any seeking when recording. Calls to audio.pos are meaningless when recording.

Record sound from the microphone or from an ongoing phone conversation (mixing microphone and incoming phone signal). gain is the recording gain, a number between 0 (minimum or automatic) and 100 (maximum). Default gain is 100. Setting the gain to a negative value sets it to 0, setting it to a value greater than 100 sets it to 100.

The audio data is appended to the current file. Use audio.cut to truncate the file and set the recording position.

This function immediately returns, before recording completes. Exceptions can therefore be thrown anywhere in the following code. Use audio.stop to stop recording.

Throws ErrInUse if a file is already being played or recorded. Throws ErrNotSupported if the file format does not support recording, or if the sample rate is not supported.

To add 20 seconds of recorded sound at the end of an existing audio file sample.wav:

audio.open('sample.wav', audio.rw);
audio.record();
sleep(20000);
audio.stop()

audio.stop

• function stop() → null

Stops the currently playing sound, or the current recording.

audio.volume

• function volume() → Number
• function volume(percent) → Number

Returns the current sound output volume and optionally changes it. The volume is a number between 0 (mute) and 100 (loudest). Default volume is 50. Setting the volume to a negative value sets it to 0, setting it to a value greater than 100 sets it to 100.

On most devices, changing the volume while a sound is playing has immediate effect.

audio.play("c:\\documents\\audio\\HomeBox.mp3");
while audio.busy() do
  sleep(100);
  audio.volume(audio.volume()-10) // fade out
end

audio.wait

• function wait() → null

Waits until playing completes. Returns immediately if no sound is playing.

This function checks only the current m process: it will return immediately if the sound unit is in use by another process (inside or outside of m).

for i=1 to 10 do
  audio.wait(); audio.beep(440, 500);
  audio.wait(); audio.beep(330, 500)
end


© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
mShell Home  > Documentation  > Manuals