RecordSound for Adobe Director

Messages:

General

Name	Description
New	Standard command to create a new instance of an object.
OpenAudio	Open an audio device with the specified name. If the device name is empty, "", the currently selected device is opened. To find the currently installed audio devices use FindAllAudioCaptureDevices.
CloseAudio	Closes the connection to an audio capture device that has been opened. You MUST call this if you have used OPenAudio.
IsAudioOpen	Check to see if an audio device has been opened without error.
FindAudioCaptureDevices	Every computer can have zero or more audio capture devices. This function finds all the devices and returns then as a list of lists. The number of items in the list is the number of devices. Each sublist contain 2 items, first the name to use in the new command, the second is a description , if any. The PC does have descriptions, the Mac does not. eg [["',"default capture"],["wave 1","CS343.3 capture board"]]
StartRecording	Initiates a recording with a maximum record time of maxTimeToRecordInMilliseconds. It may be stopped at anytime by using StopRecording
StopRecording	To stop a recording in progress. All recording upto this point is kept.
RecordingNow	Once you start a recording this method allows you to see if the recording is still recording, or has reached the maximum duration. If audio is still being recorded this function returns "yes" - else "no"
StartGetInputLevel	If you want to monitor the sound input level when not recording you have to switch it on with this message.
StopGetInputLevel	Stop the monitoring of the input audio level
GetInputLevel	This allows you to access the current level of the sound being recorded. The message returns a list of items: #left: the value of the audio on the left channel #right: the level of the audio on the right channel #error: "ok" or an error message
IsGsilActive	Query if the GetSoundLevel is currently active.

Audio Capture Format

Name	Description
GetFormat	Obtains the current audio format. Returns a property list with the following properties #SampleSize - the sample size in bits per sample, normally 8 or 16 #NumberOfChannels - the current number of channels being recorded, normally 1 or 2 #CompressionType - a 4 character string to describe the compression being used "" = none #SampleRate - the number of samples per second, normally 11.025, 22.01 or 44.1
SetFormat	Sets the current audio format. Returns a property list with the following properties #SampleSize - the sample size in bits per sample, normally 8 or 16 #NumberOfChannels - the current number of channels being recorded, normally 1 or 2 #CompressionType - a 4 character string to describe the compression being used "" = none #SampleRate - the number of samples per second, normally 11.025, 22.01 or 44.1
SetSampleRate	There are various parameters that control the quality of the recorded sound. The sample rate sets the number of times per second the current level of the input is checked. The more, the better quality - but requires more memory. You can pass any value, but only certain standards are supported by most computers. Standard ones are: 11025, 22050 and 44100 Note: Will be withdrawn in the near future, please use SetFormat in new projects
SetBitsPerSample	There are various parameters that control the quality of the recorded sound. The bits per sample controls the resolution of the amplitude, or size, of the signal. There are 2 valid values, 8 and 16. The 8 bit value divides the amplitude into 256 steps and the 16 bit into 65536. The more, the better quality - but requires more memory. Note: Will be withdrawn in the near future, please use SetFormat in new projects
SetChannels	There are various parameters that control the quality of the recorded sound.The SetChannels command alows you to control the number of audio channels to record. Mono is 1, stereo is 2 and quad is 4. Note: Will be withdrawn in the near future, please use SetFormat in new projects

Play

Name	Description
PlaySound	Play a sound that has been recorded
PlayStop	Cancel the playback of a sound that was started with PlaySound
IsSoundPlaying	Checks is a sound is playing that was started with PlayStart

Saving

Name	Description
SaveAsMember	Saves the recorded information into a cast member for playback and manipulation by Director Lingo commands. If the the member does not exist, it is created - if one exists, it is replaced. To play sound use Director lingo puppetsound.
SaveAsFile	Saves the recorded information into the named file. On Windows this is in WAV format and on the Macintosh it is an AIFF file. To play the sound use Director Lingo, sound playfile.

Misc

Name	Description
ShowErrorsAsDialogs	Controls if error dialogs are shwn in addtion to the error return. Turn this off is you want your problem to handle errors without informing the user
GetVersionString	Obtain the version number of the xtra as a string. This may be requested when you are reporting bugs or interacting with PhysicalBits support.
GetLicensetype	Returns the license type for this xtra. #Author, #Demo or #Full
GetDemoDaysRemaining	Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license.
privateInstance	Private function
privateGlobal	Private

Detailed Useage Information:

	New
Description	Standard command to create a new instance of an object.
Format	New xtra "RecordSound"
Parameters	None
Return Value	Object instance or minus number on error.
Example	set theXtra to new( xtra "RecordSound" )

	OpenAudio
Description	Open an audio device with the specified name. If the device name is empty, "", the currently selected device is opened. To find the currently installed audio devices use FindAllAudioCaptureDevices.
Format	OpenAudio object me, string deviceName
Parameters	object me: The value returned from new string deviceName:The name of a valis audio device on this machine
Return Value	"ok" or error messages starting with "Error :"
Example	theXtra.OpenAudio("")

	CloseAudio
Description	Closes the connection to an audio capture device that has been opened. You MUST call this if you have used OPenAudio.
Format	CloseAudio object me
Parameters	object me: The value returned from new
Return Value	"ok" or error messages starting with "Error :"
Example	theXtra.CloseAudio()

	IsAudioOpen
Description	Check to see if an audio device has been opened without error.
Format	IsAudioOpen obejcect me
Parameters	object me: The value returned from new
Return Value	Returns 1, true, if the device is open, or 0, false if not open.
Example	open = theXtra.IsAudioOpen()

	FindAudioCaptureDevices
Description	Every computer can have zero or more audio capture devices. This function finds all the devices and returns then as a list of lists. The number of items in the list is the number of devices. Each sublist contain 2 items, first the name to use in the new command, the second is a description , if any. The PC does have descriptions, the Mac does not. eg [["',"default capture"],["wave 1","CS343.3 capture board"]]
Format	FindAudioCaptureDevices object me
Parameters	object me: The value returned from new
Return Value	Returns the list or error messages starting with "Error :"
Example	put theXtra.FindAudioCaptureDevices()

	StartRecording
Description	Initiates a recording with a maximum record time of maxTimeToRecordInMilliseconds. It may be stopped at anytime by using StopRecording
Format	StartRecording object me, integer maxTimeToRecordInMilliseconds
Parameters	object me: The value returned from new integer maxTimeToRecordInMilliseconds: The maximum time to record in milliseconds. 1000 milliseconds = 1 second.
Return Value
Notes	This will fail if you have not opened the audio capture device, or if there is not enough memory to store the recording. If it fails because of memory then try reducing the record time or changing the recording format.
Example	put theXtra.StartRecording(10000) --record for 10 seconds

	StopRecording
Description	To stop a recording in progress. All recording upto this point is kept.
Format	StopRecording object me
Parameters	object me: The value returned from new
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.StopRecording()

	RecordingNow
Description	Once you start a recording this method allows you to see if the recording is still recording, or has reached the maximum duration. If audio is still being recorded this function returns "yes" - else "no"
Format	RecordingNow object me
Parameters	object me: The value returned from new
Return Value	"yes" if a recording is currently occuring, else "no"
Example	if theXtra.RecordingNow() = "yes" then ...etc

	StartGetInputLevel
Description	If you want to monitor the sound input level when not recording you have to switch it on with this message.
Format	StartGetInputLevel object me
Parameters	object me The value returned from new
Return Value	"ok" or error messages starting with "Error :"
Notes	You do not have to use this message if you want to use GetInputLevel during recording. Noe you cannot playback a sound when using the Wintel platform unless you use StopGetInputLevel.
Example	theXtra.StartGetInputLevel()

	StopGetInputLevel
Description	Stop the monitoring of the input audio level
Format	StopGetInputLevel object me
Parameters	object me:The value returned by new
Return Value
Example	theXtra.StopGetInputLevel()

	GetInputLevel
Description	This allows you to access the current level of the sound being recorded. The message returns a list of items: #left: the value of the audio on the left channel #right: the level of the audio on the right channel #error: "ok" or an error message
Format	GetInputLevel object me
Parameters	object me: The value returned from new
Return Value	Property list containing the volume levels and error return value
Notes	If the input source is mono the left and right values will be the same. 1.0.8 has a bug that will be fixed in a later release. The returned value is a property list inside a linear list. Use the example below to access the values.
Example	values = getat(theXtra.GetInputLevel(),1) -- [[#left:22, #right:56, #error:"ok"]] put values.Getprop(#right) -- 56

	IsGsilActive
Description	Query if the GetSoundLevel is currently active.
Format	IsGsilActive object me
Parameters	object me: The value returned from new
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.IsGsilActive()

	GetFormat
Description	Obtains the current audio format. Returns a property list with the following properties #SampleSize - the sample size in bits per sample, normally 8 or 16 #NumberOfChannels - the current number of channels being recorded, normally 1 or 2 #CompressionType - a 4 character string to describe the compression being used "" = none #SampleRate - the number of samples per second, normally 11.025, 22.01 or 44.1
Format	GetFormat object me
Parameters	object me: The value returned from new
Return Value	Property list of audio settings or error messages starting with "Error :"
Example	put theXtra.GetFormat()

	SetFormat
Description	Sets the current audio format. Returns a property list with the following properties #SampleSize - the sample size in bits per sample, normally 8 or 16 #NumberOfChannels - the current number of channels being recorded, normally 1 or 2 #CompressionType - a 4 character string to describe the compression being used "" = none #SampleRate - the number of samples per second, normally 11.025, 22.01 or 44.1
Format	SetFormat object me propertyList aListOfSettings
Parameters	object me: The value returned from new propertyList aListOfSettings:A property list of the settings you want to set.
Return Value	"ok" or error messages starting with "Error :"
Notes	Not all the properties need to be present, any that are missing retain there previous value.
Example	put theXtra.SetFormat([SampleSize:16])

	SetSampleRate
Description	There are various parameters that control the quality of the recorded sound. The sample rate sets the number of times per second the current level of the input is checked. The more, the better quality - but requires more memory. You can pass any value, but only certain standards are supported by most computers. Standard ones are: 11025, 22050 and 44100 Note: Will be withdrawn in the near future, please use SetFormat in new projects
Format	SetSampleRate object me, integer newRate
Parameters	object me: The value returned from new integer newRate: The new sample rate. Standard values are: 11025, 22050 and 44100
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetSampleRate()

	SetBitsPerSample
Description	There are various parameters that control the quality of the recorded sound. The bits per sample controls the resolution of the amplitude, or size, of the signal. There are 2 valid values, 8 and 16. The 8 bit value divides the amplitude into 256 steps and the 16 bit into 65536. The more, the better quality - but requires more memory. Note: Will be withdrawn in the near future, please use SetFormat in new projects
Format	SetBitsPerSample object me, integer newBitsPerSample
Parameters	object me: The value returned from new integer newBitsPerSample: The new bit rate. Standard values are: 8 and 16
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetBitsPerSample(16)

	SetChannels
Description	There are various parameters that control the quality of the recorded sound.The SetChannels command alows you to control the number of audio channels to record. Mono is 1, stereo is 2 and quad is 4. Note: Will be withdrawn in the near future, please use SetFormat in new projects
Format	SetChannels object me, integer newChannels
Parameters	object me: The value returned from new integer newChannels: The new channel count. Standard values are:1, 2 and 4
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetChannels(2)

	PlaySound
Description	Play a sound that has been recorded
Format	PlaySound object me
Parameters	object me: The value returned from new
Return Value
Example	theXtra.PlaySound()

	PlayStop
Description	Cancel the playback of a sound that was started with PlaySound
Format	PlayStop object me
Parameters	object me: The value returned from new
Return Value	"ok" or error messages starting with "Error :"
Example	theXtra.PlayStop()

	IsSoundPlaying
Description	Checks is a sound is playing that was started with PlayStart
Format	IsSoundPlaying object me
Parameters	object me: The value returned from new
Return Value	Returns 1, true, if playing; else 0, false
Example	if theXtra.IsSoundPlaying() then ...etc

	SaveAsMember
Description	Saves the recorded information into a cast member for playback and manipulation by Director Lingo commands. If the the member does not exist, it is created - if one exists, it is replaced. To play sound use Director lingo puppetsound.
Format	SaveAsMember object me, integer castNumber, string memberName
Parameters	object me: The value returned from new integer castNumber: The cast number to save the member within. string memberName: The name of the member to save the audio as.
Return Value	"ok" or error messages starting with "Error :"
Example	put theXtra.SaveAsMember(1,"TheSound")

	SaveAsFile
Description	Saves the recorded information into the named file. On Windows this is in WAV format and on the Macintosh it is an AIFF file. To play the sound use Director Lingo, sound playfile.
Format	SaveAsFile object me, string pathAndFilename
Parameters	object me: The value returned from new string pathAndFilename: The combined path to and/or fiename.
Return Value	"ok" or error messages starting with "Error :"
Notes	Files saved on windows are in the wav format, on Macintosh as AIFF.
Example	put theXtra.SaveAsFile("c:\theAudio.wav")

	ShowErrorsAsDialogs
Description	Controls if error dialogs are shwn in addtion to the error return. Turn this off is you want your problem to handle errors without informing the user
Format	ShowErrorsAsDialogs object objectRef, integer truOrFalse
Parameters	objectRef: valid instance of UsbAccessXtra created with "new" trueOrFalse: true to turn dialogs on, or false to turn them off
Return Value	"ok" or "Error"
Example	theXtra.ShowErrorsAsDialogs(0)

	GetVersionString
Description	Obtain the version number of the xtra as a string. This may be requested when you are reporting bugs or interacting with PhysicalBits support.
Format	GetVersionString object objectRef
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Return Value	A version string.
Example	put theXtra.GetVersionString()

	GetLicensetype
Description	Returns the license type for this xtra. #Author, #Demo or #Full
Format	GetLicenseType object objectRef
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Return Value	#Author, #Demo or #Full
Example	put theXtra.GetLicenseType()

	GetDemoDaysRemaining
Description	Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license.
Format	GetDemoDaysRemaining object me
Parameters	object me: The value returned from new
Return Value	Integer number
Example	put theXtra.GetDemoDaysRemaining()

	privateInstance
Description	Private function
Format	privateInstance
Parameters	Private
Return Value
Notes	for the curious: 0 = invalid: 1 = internal error reporting, 0=off 1=on: 2 = flow control reporting, 0=off 1=on, 0-100 level: 3 = log messages to file, 0=off 1=on, filname:
Example

	privateGlobal
Description	Private
Format	privateGlobal
Parameters
Return Value
Example

About Us | Privacy Policy | Legal | Contact Us | ©2009 PhysicalBits