Scirius Development

Simsonstraße 5
04107 Leipzig, Germany

 


This documentation and the xtra are continuously improved.
Please visit http://www.scirius.com for updates of the documentation and the xtra on a regular basis.

 

QTRecordAudioXtra, Version 1.0.1

 

Last Updated: Juni 1, 2010

 

 

What is QTRecordAudioXtra?

QTRecordAudioXtra is a cross platform scripting xtra for Macromedia Director for recording audio or monitoring the input level of sound input devices. This xtra is the second release of a series of QuickTime related xtras from Scirius Development.

It lets you record audio from any QuickTime compatible device connected to your computer.


 

 

System Requirements

Director 8.5 or higher (including Director MX 2004), Director 11 and above (see note below)

QuickTime 6 or higher

Windows 98 or higher, MacOS 8.6 or higher, MacOS X 10.1 or higher

Note:

QTRecordAudioXtra is not shockwave-safe.
If you need to record audio with a shockwave-safe xtra or without QuickTime installed,
you should take a look at the AudioXtra from Tabuleiro at http://xtras.tabuleiro.com.

Note for Users of Director 11 and above:

QTRecordAudioXtra is working under Director 11 and above. However, the file and path names should not contain any special characters.
To be save avoid any characters other than standard ASCII.

 

General Notes

To use QTRecordAudioXtra you should be familiar with some basic concepts. All recording is done through a sound input device. If you create a new instance of the QTRecordAudioXtra it is connected to the default sound input device. Use qtraGetDeviceList to retrieve a list of available input devices, use qtraGetDeviceName to get the name of the current input device the xtra instance is connected to and set the input device with the qtraSetDevice function.

After the xtra instance is connected to the device you can setup the device for recording depending on your needs. Every input device can have one or more input sources. You can use qtraGetSourceList to retrieve a list of input sources of the current device. You can get and set the input source of the current device with qtraGetSource and qtraSetSource.

Now it is time to set the sample size, the sample rate and the number of channels to record. QTRecordAudioXtra lets you set all these parameters for the device and the recording independent of each other. That way it is possible to record at a different sampling rate than the device supports.

 

 

The Functions

new
register
qtraAbout
qtraShowSettingsDialog

 

qtraGetDeviceList
qtraGetSourceList
qtraGetDeviceName
qtraGetSource
qtraGetSampleSize
qtraGetSampleRate
qtraGetChannelCount

qtraGetInputGain

qtraGetVolume
 

qtraSetDevice

qtraSetSource

qtraSetSampleSize

qtraSetSampleRate

qtraSetChannelCount

qtraSetInputGain

qtraSetVolume

 

qtraGetRecordingStatus

qtraGetRecordingLevel

qtraGetRecordingTimeRemaining

qtraRecord

qtraPauseRecording

qtraResumeRecording

qtraStopRecording

qtraExportAIFF

qtraPlotWaveImage

 

Error Codes


The Functions

new

new object me, string nf, integer w, integer h, float fr, string codec, integer quality

create a new xtra instance for authoring a QuickTime movie

     
Parameters: me the reference to the xtra itself
     
return: the xtra object or error code  

Discussion:

This is the starting point for all other operations with QTRecordAudioXtra. To use the xtra you first have to create an instance of the xtra.

You should always check for errors returned by this function, since all other functions won't work in that case.

Example:

global gRecObj
gRecObj = new(xtra "QTRecordAudioXtra")
if integerp(gRecObj) then
	case gRecObj of
		-1:	alert "QuickTime not installed/too old"
	otherwise
			alert "Initializing the xtra for recording failed"
	end case
	halt
end if

 


 

register

+ Register object xtraRef, string name, string serialnumber

This function lets you register your copy of QTRecordAudioXtra

     
Parameters: object xtraRef a reference of the xtra
  string name the name under the xtra is registered
  string serialnumber the serialnumber as a string
return: error code 1: registered successfully, otherwise 0

Example:

register(xtra "QTRecordAudioXtra", "your company", "the serialnumber")

 

Note:

You can try QTRecordAudioXtra first before you decide buying it. The unregistered version is fully functional except the "about box" is shown sometimes.

 


qtraAbout

*qtmAbout

This command shows the about box of the xtra.


 

qtraShowSettingsDialog

qtraShowSettingsDialog object me

returns a linear list of sound input devices

     
Parameters: object the xtra instance
return: error code 0: OK; -128: user cancelled the dialog, -4012: during record this dialog can't be shown

Discussion:

This function shows the built-in settings dialog. You can't show the settings dialog during a record operation.

Example:

put gRecObj.qtraShowSettingsDialog()
-- 0

Note:

This is the easiest way to setup the device for recording. All settings can be adjusted with this dialog.


 

qtraGetDeviceList

qtraGetDeviceList object me

returns a linear list of all names of available sound input devices.

     
Parameters: object me the xtra instance
return linear list a linear list of device names

Note:

You should always call this function to determine the existance of a sound input device.
If an empty list is returned there are no input devices available.

 

Examples:

put gRecObj.qtraGetDeviceList()
-- ["DV Audio", "UA-3 USB Audio Device"]

in this example there are 2 sound input devices available.

if gRecObj.qtraGetDeviceList().count=0 then 
	alert ("no device!")
	halt
end if

no device available.


qtraGetSourceList

qtraGetSourceList object me

returns a linear list of all names of available sound input sources.

     
Parameters: object me the xtra instance
return linear list a linear list of source names

Note:

Every sound input device can have one or more sources. This function will return a list of all sources of the current input device.

Examples:

put gRecObj.qtraGetSourceList()
-- ["Int. Mikrofon", "Ext. Mikrofon", "Mikrofon", "Modulschacht", "Interner Modem", "Zoom Video", "Kein"]

in this example there are 7 sound input sources available.

 


qtraGetDeviceName

qtraGetDeviceName object me

 

This function returns the name of the current device

     
Parameters: object me  
return: string name the name of the current sound input device

Example:

put gRecObj.qtraGetDeviceName()

See also:

qtraSetDevice


qtraGetSource

qtraGetSource object me

 

This function returns the source number of the current device

     
Parameters: object me  
return: integer srcnum the source number of the current sound input device

Example:

put gRecObj.qtraGetSource()

See also:

qtraSetSource, qtraGetSourceList


qtraGetSampleSize

qtraGetSampleSize object me, integer dev

 

This function returns the sample size of the device or the recording settings

     
Parameters: object me the xtra instance
  integer dev boolean flag, 1 for the device
return: integer size the current sample size

Discussion:

The function qtraGetSampleSize retrieves the current sample size. Depending on the dev flag, the sample size of the device or the recording settings is returned.

 

Examples:

devSampleSize = gRecObj.qtraGetSampleSize(1)

Get the sample size of the device and store it in the variable devSampleSize

recSampleSize = gRecObj.qtraGetSampleSize(0)

Get the sample size of the recording settings and store it in the variable recSampleSize

 

See also:

qtraSetSampleSize


qtraGetSampleRate

qtraGetSampleRate object me, integer dev

 

This function returns the sample rate of the device or the recording settings

     
Parameters: object me the xtra instance
  integer dev boolean flag, 1 for the device
return: integer rate the current sample rate

Discussion:

The function qtraGetSampleRate retrieves the current sample rate. Depending on the dev flag, the sample rate of the device or the recording settings is returned.

 

Examples:

devSampleRate = gRecObj.qtraGetSampleRate(1)

Get the sample rate of the device and store it in the variable devSampleRate

recSampleRate = gRecObj.qtraGetSampleRate(0)

Get the sample rate of the recording settings and store it in the variable recSampleRate

 

See also:

qtraSetSampleRate


qtraGetChannelCount

qtraGetChannelCount object me, integer dev

 

This function returns the channel count of the device or the recording settings

     
Parameters: object me the xtra instance
  integer dev boolean flag, 1 for the device
return: integer channels the current channel count 1=mono, 2=stereo

Discussion:

The function qtraGetChannelCount retrieves the current channel count. Depending on the dev flag, the channel count of the device or the recording settings is returned.

 

Examples:

devChannelCount = gRecObj.qtraGetChannelCount(1)

Get the channel count of the device and store it in the variable devChannelCount

recChannelCount = gRecObj.qtraGetChannelCount(0)

Get the channel count of the recording settings and store it in the variable recChannelCount

 

See also:

qtraSetChannelCount


qtraGetInputGain

qtraGetInputGain object me

This function returns the current input gain of the device

     
Parameters: object me the xtra instance
return: float gain the current input gain of the device‚

Discussion:

Returns the input gain of the device as a floating point value. This value is in a range between 0.5 and 1.5.

 

See also:

qtraSetInputGain

 


qtraGetVolume

qtraGetInputGain object me

This function returns the playthru volume of the sound input device

     
Parameters: object me the xtra instance
return: integer volume the current volume of the device

Discussion:

Returns the playthru volume of the sound input device.
This value is in a range between 0 and 255.

 

See also:

qtraSetVolume


qtraSetDevice

qtraSetDevice object me, string dev

This function selects the sound input device

     
Parameters: object me the xtra instance
  string devname the device name
return: integer error 0 = no error, negative values indicate an error

Discussion:

If there are more than one input device available you can use this function to select one of the input devices.

See also:

qtraGetDeviceName, qtraGetDeviceList


qtraSetSource

qtraSetSource object me, integer srcnum

This function selects the sound input source of the current device

     
Parameters: object me the xtra instance
  integer srcnum the source index
return: integer error 0 = no error, negative values indicate an error

Discussion:

Some sound input devices can have more than one input source. This function allows you to set the input source of the device.

See also:

qtraGetSourceList, qtraGetSource


qtraSetSampleSize

qtraSetSampleSize object me, integer s, integer dev

This function sets the sample size of the current device or recording setting

     
Parameters: object me the xtra instance
  integer s the sample size [8|16]
  integer dev boolean flag, 1 for the device
return: integer error 0 = no error, negative values indicate an error

Discussion:

The function qtraSetSampleSize lets you choose the sample size. Depending on the dev flag, the sample size of the device or the recording settings is affected.

 

Examples:

err = gRecObj.qtraSetSampleSize(16,1)

Set the sample size of the device to 16 bit.

 

See also:

qtraGetSampleSize


qtraSetSampleRate

qtraSetSampleRate object me, integer r, integer dev

This function sets the sample rate of the current device or recording setting

     
Parameters: object me the xtra instance
  integer r the sample rate in Hz
  integer dev boolean flag, 1 for the device
return: integer error 0 = no error, negative values indicate an error

Discussion:

The function qtraSetSampleRate lets you choose the sample rate. Depending on the dev flag, the sample rate of the device or the recording settings is affected.

 

Examples:

err = gRecObj.qtraSetSampleRate(32000,0)

We want our recording with a sample rate of 32000 Hz.

 

See also:

qtraGetSampleRate


qtraSetChannelCount

qtraSetChannelCount object me, integer c, integer dev

This function sets the channel count of the current device or recording setting

     
Parameters: object me the xtra instance
  integer c the number of channels [1|2]
  integer dev boolean flag, 1 for the device
return: integer error 0 = no error, negative values indicate an error

Discussion:

The function qtraSetChannelCount lets you set the number of channels to record.
For mono recording pass a value of 1. A value of 2 would record in stereo.
Depending on the dev flag, the channel count of the device or the recording settings is affected.

 

Examples:

err = gRecObj.qtraSetChannelCount(2,0)

We want a stereo recording.

 

See also:

qtraGetChannelCount


qtraSetInputGain

qtraSetInputGain object me, float g

This function sets the input gain of the current device

     
Parameters: object me the xtra instance
  float g the gain value [0.5...1.5]
     
return: integer error 0 = no error, negative values indicate an error

Discussion:

This function lets you set the input gain of the device. The gain value must be in a range between 0.5 and 1.5.

Note:

Not all input devices are able to set this value. You should always check for errors.

See also:

qtraGetInputGain


qtraSetVolume

qtraSetVolume object me, integer vol

This function sets playthru volume of the device

     
Parameters: object me the xtra instance
  integer vol the volume
     
return: integer error 0 = no error, negative values indicate an error

Discussion:

This function sets the playthru volume of the input device. The value of the volume must be in a range between 0 and 255.

Note:

Not all input devices are able to provide this feature.

Example:

gRecObj.qtraSetVolume(0)

See also:

qtraGetVolume


qtraGetRecordingStatus

qtraGetRecordingStatus object me

This function returns the recording status

     
Parameters: object me the xtra instance
     
return: integer status|error negative values indicate an error

Discussion:

This function returns the status of the recording.

The following values are defined:

0 not recording
1 recording
2 recording finished

Negative values indicate an error. Most likely errors include -108 (Out of memory) and -34 (Disk full).

Note:

In the case of a disk full error the recording done so far is still valid.

Important Note:

To give the xtra enough processing time you should call this function frequently, even if your not interested in the status.

Example:

gRecObj.qtraGetRecordingStatus()

qtraGetRecordingLevel

qtraGetRecordingLevel object me

This function returns the current input levels of the device

     
Parameters: object me the xtra instance
     
return: levels|error negative values indicate an error

Discussion:

This function returns the levels of the input device. The returned value is a linear list of two values.
The first value of this list indicates the left channel, the second the right channel.

Note:

This list will always contain 2 values. If record in mono both entries in this list are the same.


qtraGetRecordingTimeRemaining

qtraGetRecordingTimeRemaining object me

This function returns the time remaining

     
Parameters: object me the xtra instance
     
return: time|error remaning time in ticks

Discussion:

Returns the remaining time of the recording in ticks. If you haven't started a recording an error is returned.

Note:

The value returned is only correct for uncompressed sounds.


qtraRecord

qtraRecord object me, integer time, string nf, integer memory

This function starts a recording

     
Parameters: object me the xtra instance
  integer time duration of the recording in ticks
  string nf full path to file to record to
  integer memory boolean flag (1= record to memory first)
     
return: error error code

Discussion:

This function starts the recording process.

time

You have to provide a duration in ticks how long you want to record.
If you provide a duration value of 0 the xtra tries to record as long as possible, i.e. until the memory/disk is full or the file reaches the limit of 2 GB. The maximum time you can record depends on the device settings.

nf

The absolute path to a file to record into. If the file already exists you'll get a duplicate file error.
The recording is always saved into a QuickTime movie.

memory

This flag controls how the recording is done. If you set this flag to 1 the recording is done in memory and later saved to disk when finished, otherwise the recording is done direct to disk.
Usually there is no problem recording direct to disk. However, if you plan to record while the hard disk is used by other processes (for example playing a QuickTime movie while you record) recording to memory could be a solution.

Example:

gRecObj.qtraRecord(600,"Macintosh HD:MyRecording.mov",0)

We want to record 10 seconds to the file "MyRecording.mov".

Important Note:

To give the xtra enough processing time you should call the function qtraGetRecordingStatus frequently, even if your not interested in the status.


qtraPauseRecording

qtraPauseRecording object me

This function pauses the recording

     
Parameters: object me the xtra instance
     
return: error error code

Discussion:

This function pauses the recording.

See also:

qtraResumeRecording


qtraResumeRecording

qtraResumeRecording object me

This function resumes the recording

     
Parameters: object me the xtra instance
     
return: error error code

Discussion:

This function resumes the previously paused recording.

See also:

qtraPauseRecording


qtraStopRecording

qtraStopRecording object me

This function stops the recording

     
Parameters: object me the xtra instance
     
return: error error code

Discussion:

This function stops the recording. After this call the recording is finished. You can't resume the recording.

Example:

gRecObj.qtraStopRecording()

qtraExportAIFF

*qtraExportAIFF string f, string nf, integer bits, integer rate, integer channels, symbol comp, integer showprogress

export all sound tracks of a movie to an AIFF sound file.

     
Parameters: f file path of the movie to export
  nf full path to the new file to create
  bits the desired sample size (8|16)
  rate the desired samplerate in Hz
  channels number of channels (1=mono, 2=stereo)
  comp a symbol for the desired compression
  showprogress a flag controlling wether a progress bar is shown or not
     
return: error code  

f

The file you want to export. It can be any file containing sound, as long as QuickTime can handle it.
You can use relative paths here.

nf

The full path to the AIFF file.

bits

The desired sample size. Use 8 for 8 bits per sample or 16 for 16 bits per sample. Any other value will result in a parameter error.

rate

The desired sample rate

channels

The number of channels in the AIFF file. 1 for mono, 2 for stereo.

comp

The compression to use

#none --> uncompressed
#alaw --> ALaw 2:1
#ulaw --> µLaw 2:1
#ima4 --> IMA 4:1

showprogress

a flag controlling wether a progress bar is shown or not.


qtraPlotWaveImage

*qtraPlotWaveImage(string f, integer st, integer et, integer w, integer h)

This global function plots a waveform of any Quicktime movie

     
Parameters: string f the file name of the movie
  integer st the start time of the segment to plot
  integer et the end time of the segment to plot
  integer w the width of the image to create
  integer h the height of the image to create
     
return: image|error an image object or error code

Discussion:

This function plots a wave form of the sound track(s) of any Quicktime movie or by QuickTime supported sound file.
This function is a global function, you don't need to create a new instance of the xtra to plot a wave form.

Note:

The values for start and end time have to be expressed in a time scale of 600, i.e. 600 units per second.
You can use -1 for the parameter et to the end of the sound track.

The image returned is a 1bit image object.

Example:

img=qtraPlotWavImage("myMovie.mov", 0, 6000, 300, 64))
if integerp(img) then
   alert("Error: " & img)
else
   member("test").image=img
end if

In this example we want to plot a wave form of the first 10 seconds fo the movie "myMovie.mov".
The image is created has a width of 300 pixels and a height of 64 pixels. If no error occures the
image is assigned to the cast member "test".


 

 

Error Codes

-1: "QuickTime not installed/too old"

-33: "Directory full"
-34: "disk full"
-35: "no such volume"
-36: "I/O error (bummers)"
-37: "there may be no bad names in the final system!"
-38: "File not open"
-39: "End of file"
-40: "tried to position to before start of file (r/w)"
-41: "memory full (open) or file won't fit (load)"
-42: "too many files open"
-43: "File not found"
-44: "diskette is write protected."
-45: "file is locked"
-46: "volume is locked"
-47: "File is busy (delete)"
-48: "duplicate filename"
-49: "file already open with with write permission"
-51: "refnum error"
-52: "get file position error"
-53: "volume not on line error (was Ejected)"
-54: "permissions error (on file open)"

-108: "out of memory"


-128: "Cancelled by user"

-192: "Resource not found"
-193: "Resource file not found"

-200: "no hardware"
-201: "not enough hardware"

-224: "hard disk too slow to record to disk"
-225: "invalid sample rate"
-226: "invalid sample size"
-227: "device busy"

-230: "input hardware failure"
-231: "unknown info type"

-2008: "invalid media"
-2009: "invalid track"
-2010: "invalid movie"

-2011: "invalid SampleTable"
-2012: "invalid DataRef"
-2013: "invalid Handler"
-2014: "invalid duration"
-2015: "invalid time"

-2019: "Progress cancelled"

-4000: "invalid width"
-4001: "invalid height"
-4002: "invalid codec"
-4003: "invalid sample size"
-4004: "invalid sample rate "
-4012: "device in use" -- you can't set settings during a record operation

-50: "parameter error"

-9402: "not allowed in current mode" -- you can't set values during recording
-9407: "info not available" -- f.e. qtraGetRecordingTimeRemaining while not recording

-2147483643: "Parameter Error" --wrong type

 

 

Version History

1.0.1

1.0.0