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

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

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

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

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

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

Example:

put gRecObj.qtraGetDeviceName()

See also:

qtraSetDevice

qtraGetSource

qtraGetSource object me

Example:

put gRecObj.qtraGetSource()

See also:

qtraSetSource, qtraGetSourceList

qtraGetSampleSize

qtraGetSampleSize object me, integer dev

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Discussion:

This function pauses the recording.

See also:

qtraResumeRecording

qtraResumeRecording

qtraResumeRecording object me

Discussion:

This function resumes the previously paused recording.

See also:

qtraPauseRecording

qtraStopRecording

qtraStopRecording object me

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

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)

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

• fixed a bug in qtraRecord under Windows with the latest QuickTime releases
• universal binary for Director 11 and above on MacOSX

1.0.0

• first release