Byte array as input to a sound object

You can pass a byte array to a sound object. If a byte array has to be generated from a file, the byte array reads the contents of the file using FileIO, and passes the byte array contents to the sound object whenever the callback method returns true.

Note: Director audio supports only 8-bit unsigned, and 16- and 24-bit signed audio files for this operation.

Usage

SoundObject Mixer.createSoundObject(SoundObjname,callbackFunction,[castMemRef], [sampleRate,channelcount,bitDepth])

Parameters

Parameter	Description	Default value	Required/ optional
SoundObjname	The name associated with the sound object. Sound objects with duplicate names are not allowed.		Required
callbackFunction	When a Lingo or JavaScript function is passed to `createSoundObject`, the sound object calls the `callbackFunction` when it is ready to receive data for playback.		Required
castMemRef	Passes a cast member reference if the callback method is a member of the parent script. If the callback method is in movieScript, do not specify the parameter, or specify it as void.		Optional
sampleRate	Sampling frequency of the audio.	48000 kHz	Optional
channelCount	Number of channels in the audio.	2	Optional
bitDepth	Bit depth of the audio.	16	Optional

More about callbackFunction

When a Lingo or JavaScript function is passed to createSoundObject, the sound object calls the callbackFunction when it is ready to receive data for playback.

Optionally, you can also pass a cast member reference using the callback function.

When providing input to callbackFunction:

The registered callback function is called soon after the sound object is played.
The parameter to the callback function is a zero length byte array. Fill this byte array with audio data. Unlimited length of data that can be copied to the byte array.
The next callback function is called after the data has been played.
The return value of the callback function can either be true or false, indicating whether the sound object should continue calling the callback function the next time (True) or stop once it has played all audio data passed to it (False).
If necessary, you can stop the sound object manually in the callback function. Stopping the sound object manually also stops the callback method.

The syntax of the callbackFunction is as follows:

On callbackFunction outByteArray 
--outByteArray is filled with bytearray samples. 
end

Note: Inside the callback handler, if there is any script that causes runtime errors (such as property not found), the error messages are not displayed, and the handler execution is aborted at the point of error. All the subsequent statements are not executed.

The byte array input to the function is filled with the requested bytes of bytearray samples.

Note: The bytearray samples must be in the same format as specified in createSoundObject.

If you did not specify a format in createSoundObject, the default format with the following specifications is used:

Bit depth	16
Sampling frequency	48000 Hz
Channel count	2

To override the default format, set the following symbols in the property list:

#bitDepth --Bit depth of the audio. 
#sampleRate --Sampling frequency of the audio. 
#channelCount --Number of channels in the audio.

Examples

    -- BUTTON BEHAVIOR -- 
    global gSoundIOInstance --  instance  of FileIO for  reading sound file 
    global Sound             -- soundObject 
    global gMixer             -- mixer object 
    on mouseUp(me) 
    -------------------------------------------------------------------- 
    -- ACTION: Opens a sound file in the same folder as the movie 
    -- and creates a soundObject to play it back. The sound file 
    -- will be read in when requested by a callback from the 
    -- sound object. The callback handler HAS to be in a Movie Script, which 
    -- means that globals MUST be used to play back the sound file.  
    -- See the Movie Script for callback details. 
    -------------------------------------------------------------------- 
-- Open a sample file to read the data 
      gSoundIOInstance = new xtra("fileIO") 
    gSoundIOInstance.openFile(_movie.path & "RawSound.snd",0) 
    gMixer = new(#mixer) 
-- Create the sound object with the SampleRate, ChannelCount & 
-- BitDepth. Specify the callback method. 
    vName = "Imported sound mixer" 
    vCallback  = #audioInput 
    vByteArray = VOID -- Callback method is available in the Movie Script, can specify 
    -- scriptReference also 
    vSettings  = [#samplerate:48000, #channelcount:2, #bitdepth:16] 
    gSound = gMixer.createSoundObject(\ 
    vName, \ 
    vCallback, \ 
    VOID, \ 
    vSettings) 
-- Play the sound 
    gMixer.play() 
    end mouseUp

Callback method (movie script)

    -- MOVIE SCRIPT -- 
    global gSoundIOInstance -- instance of FileIO for reading sound file 
    global gSound           -- soundObject 
    on audioInput(aByteArray) 
    -------------------------------------------- 
    -- SOURCE: Called back from gSound whenever gSound has finished 
    -- playing its current contents. 
    -- INPUT: <aByteArray> will be an empty byteArray which has to be 
    -- filled and the modified byteArray to send back. 
    -- ACTION: Transfers the (remaining) contents of the file to 
    -- aByteArray 
    -- OUTPUT: Returns TRUE if there was any data to pas to aByteArray 
    -- FALSE if not. 
    -------------------------------------------------------------------- 
     -- Checking the if we've reached the end of the file 
    vFileLength = gSoundIOInstance.getLength() 
    vPosition   = gSoundIOInstance.getPosition() 
    if vPosition = vFileLength then 
    -- We've reach the end of the file.  Close it and tell the 
    -- soundObject to stop calling back. 
    gSoundIOInstance.closefile() 
    return FALSE -- stop calling the callback 
    end if 
    -- Read entire contents of the file into a byteArray 
    vByteArray   = gSoundIOInstance.readByteArray(vFileLength) 
    vArrayLength = vByteArray.length 
    put vArrayLength, vFileLength 
    -- Copy from the temporary byteArray to the one passed in as a 
    -- parameter 
    if vArrayLength <> 0 then 
    vResult = aByteArray.writeByteArray(vByteArray, 1, vArrayLength) 
    end if 
    -- Ensure this callback is made again when the sound has played out 
    return TRUE 
    end audioInput 
 
    on stopmovie 
    gSoundIOInstance.closefile() 
    end stopmovie