CaptureVideo Xtra
current version 0.1c
Copyright Geoff Smith 1999-2003
page last updated:August 2003
(first released MacOSX:7/03 and Mac:OS9 --/--)

ALPHA VERSION XTRA
This is very early code - use entirely at your own risk

Description

This is a sprite Xtra for use in Macromedia's Director (TM) multimedia program. NOTE: The sprites messages will be unified between the PC and Mac for the next release of CaptureVideo

Compatibility

OS	Version	Yes	No	Not yet available	Untested
Microsoft© Windows	95			•
	98			•
	2000			•
	XP			•
	NT 4			•
Apple Macintosh	Classic (OS9)			•
	OSX	•

 

Installation

Windows: Copy the VideoCapture.x32 file to the "Program Files\Macromedia\Director X\Xtras" folder. Then start Director.
To create new member use the "insert/physicalbits Xtras/VideoCapture" menu item. If correctly installed the xtra will appear in the insert menu, under the physicalbits heading; as below.

Macintosh: Copy the CaptureVideo.osx/CaptureVideo.os9 file to the xtras folder. Then start Director.
To create new member use the "insert/physicalbits Xtras/CaptureVideos" menu item. If correctly installed the xtra will appear in the insert menu, under the physicalbits heading; as below.

Example location of CaptureVideo Xtra in insert menu (Wintel shown above)

Basic operation
Macintosh

1. Request an authoring license - www.physicalbits.com
2. Insert CaptureVideo from the "physicalbits Xtras" menu
3. Add license; (member 1).SetLicense("name","key",90)
4. Drag onto stage. If sprite boundary is green then all is ok, is red problem with video capture
5. Use "(member 1).enabled( true)"
6. Run the movie - image should appear on stage
7. Use the captureToFile property to control saving to disk.

 

Capture vs Display rectangles

The captureRect property of the captureVideo xtra controls the video digitizers capture resolution. For example (0,0,120,160) will capture an image with a width of 160 and a height of 120. When you place the sprite on the stage you may modify the height and width, the captured image will be scaled to fit within the sprites rectangle.

When setting the captureRect do not use anything other than 0 for the first two parameters. It is best to set the captureRect to the same size you expect the image to be displayed. If the disaplyed image is smaller the image will be scaled down, pixels thrown away and CPU time taken to do this processing. Taking a smaller captureRect and scaling it up to a larger display rectangle will lead to blockiness of the final image and some CPU being used.

Member Properties - Overview

All properties are accessed via the member. eg set the captureFPS of member 1 to 15

Group	PC	Mac	Name	data	Set	Get	Description	Default
Capture
	o	o	captureFilename	string	o		Set the path and name of the file to capture into.	"VideoCapture"
	o	o	captureToFile	true or false	o		Enable/disable the capture to a file	false
	o	o	captureRect	rect	o	o	Set/get the capture rect of the capture device. This sets the resolution of the captured image. Do not use anything else than 0 for the first two parameters.	0,0,160,120
		o	captureToFilePause	true/false	o		* Not yet implemented * When capturing to file setting this true will pause the capture.	false
Control
		o	videoDevice	string	o		Set the name of the video device to enable. Find this by using videoDevices.	""
	o	o	audioDevice	string	o		Set the name of the video device to enable. Find this by using audioDevices.	""
	o	o	captureVideo	true or false	o		Used to control if video is captured once Enable is called. If true video will be captured to the sprite/file.	true
	o		captureAudio	true or false	o		Used to control if audio is captured once Enable is called.If true video will be captured to the sprite/file.	true
	o	o	directToStage	true or false			* Not yet implemented * True to send captured image direct to stage, faster update, but no compositing with other sprites	false
		o	preAllocateFile	integer	o		* Not yet implemented * When openeing a file, preallocate a file to this size. In bytes.	0
			captureSingleFrameMode	true or false			* Not yet implemented *
		o	VideoConfigString AudioConfigString	string	o	o	Obtain the current settings as a string, or set using a previously obtained string
		o	VideoConfig AudioConfig	property list	o	o	Obtain the current settings as a property list, or set using properties
Image
	o	o	captureFPS	float	o	o	Change the number of frames per second the capture device will try to capture	10.0
	o	o	videoImagePresent	true or false		o	Returns true if the video digitizer is receiving an image
		o	videocompressor	string	o	o	Get/Set the videocompressor to use when capturing to a file.
Info
			captureVersion			o	* Not yet implemented *
			enabled			o	Returns 1 if the capture enabled
		o	videoCaptureCapabilities	property list		o	A property list which contains the video digitizers capabilities. Each capability is a property with a value of 1 if present, else 0.
		o	videoCaptureCurrentFlags	property list		o	Similar to the above, except these are the capabilities currently being used.
		o	lastError	string		o	Returns an error string from the last operation. This is reset with each new call, except this one.
	o	o	audiodevices	list		o	Returns a list of all the installed audio devices
	o	o	videodevices	list		o	Returns a list of all the installed video devices
	o		videocompressors	list		o	Returns a list of all the installed video compressors
		o	onSpriteDisplay	true/false	o		When true additional info is displayed on top of the sprite. This is only updated when when the stage is, use updatestage to force renewal of info	false
	o	o	xtraVersion	property list		o	Returns a property with the following properties: #xtraName and #versionString
	o	o	licenseType	string		o	Returns a string which is one of "Authoring", "Demo", "Full" or "Invalid"
Private
	o	o	DebugMessages	integer	o

 

Member Messages/Methods - Overview

All properties are accessed via the member. eg CaptureOpen( member 1)

Group	Function		Description
Control
	Enable		Start/stop the capture process. This does not start capturing to a file unless the captureToFile flag is set. Once called with "true" and the movie is run, images will be displayed on the stage.
	SetLicense		Add the license data from physicalbits to the sprite.
	Poll		Certain functions require time to process data, call this regularly. Also returns errors if there are issues with saving a file.
Capture
	TimedCaptureToFile		* Not yet implemented * Capture to a disk file for the specified duration. Not yet implemented
Info
	interface		Displays in the message box a help text that includes all the methods in the sprite.
Dialogs
	showVideoDialog showAudioDialog		Display the system dialogs so that the user can select new options.

 

 

Version release history

CaptureVideo Member Properties

captureFilename

Format	captureFilename pathAndFilename
Parameter	pathAndFilename is a string that indicates where to save any captured images of movies
Default value	"VideoCap.avi"
Access	Set	o		Get	o
Example	set the captureFilename of member 1 to "c:\myDocs\history\movie.avi"
Description	To set the name of the file to stream the captured video/audio data. Change this before using captureToFile. To start the movie saving use the captureToFile property

captureToFile

Format	captureToFile trueOrFalse
Parameter	trueOrFalse is a true or false value.
Default value	false
Access	Set	o		Get	o
Example	set the captureToStage of member 1 to true
Description	Enables or disables the capture to a file. Has no effect until Enable has been called. Each time it changes from false to true the file is written from the begging, overwriting the previous contents.

captureToSprite

Format	captureToSprite trueOrFalse
Parameter	trueOrFalse is a true or false value.
Default value	true
Access	Set	o		Get	o
Example	set the captureToSprite of member 1 to true (member 1).captureToSprite = 1
Description	Enables or disables the capture to a sprite. Has no effect until Enable has been called.

captureFPS

Format	captureFPS float
Parameter	float is a number that the capture system attempts to aquire new frames. It is in frames per second.
Default value	15.0
Access	Set	o		Get
Example	set the captureFPS of member 1 to 13 (member 1).captureFPS = 10.0
Description	Sets the current frames per second for the video capture. This might not be achieveable, eg setting 500.5 frames a sec! You can set sub-second capture rates, eg .2 is 1 frame every 5 seconds.

captureVersion

Format	captureVersion
Parameter	none
Default value	n/a
Access	Set			Get	o
Example	put the captureVersion of member 1
Description	Gets the current version of the Xtra

videoDevices, audioDevices

Format	videoDevices audioDevices
Parameter	None
Default value	n/a
Access	Set			Get	o
Example	put the videoDevices of member 1
Description	This message returns a list of property lists that contains the names of the installed devices, and whether the device is the selected one. eg [ ["DeviceName":"device1", "Selected":#yes], ["DeviceName":"device2", "Selected":#no] Which shows that there are 2 devices on this machine, and device1 is the current device.

VideoConfigString, AudioConfigString

Format	VideoConfigString AudioConfigString
Parameter	None
Default value	n/a
Access	Set	o		Get	o
Example	data = (member 1).VideoConfigString (member 1).VideoConfigString = data
Description	Getting the VideoConfigString returns a string that describes the current settings of the video system. This includes all the options that are active. This string is, really, specific to the machine on which it is obtained. You can restore those settings by setting this property. The same applies to AudioConfigString.

VideoConfig

Format	VideoConfig
Default value	n/a
Access	Set	o		Get	o
Example	data = (member 1).VideoConfig newData = [:] newData.addProp(#VideoCaptureFPS,30) (member 1).VideoConfig = newData
Description	Accessing the videoConfig returns a property list of the current video settings. Current properties are: #VideoDeviceName -- if "" then using the default device #CaptureRect #VideoCaptureFPS #CompressionType -- note this is the 4 character id When setting this property you supply a property list of those items you wish to change. Any properties that are not in the list will retain thier current value.

AudioConfig

Format	AudioConfig
Default value	n/a
Access	Set	o		Get	o
Example	data = (member 1).AudioConfig newData = [:] newData.addProp(#NumberOfChannels,1) (member 1).AudioConfig = newData
Description	Accessing the AudioConfig returns a property list of the current audio settings. Current properties are: #AudioDeviceName -- if "" then using the default device #NumberOfChannels #SampleSize #CompressionType -- note this is the 4 character id #SampleRate When setting this property you supply a property list of those items you wish to change. Any properties that are not in the list will retain thier current value.

VideoCapture Functions detail

Enable

This starts the video capture, if captureToStage and/or are set the image will be send to those devices

Format	enable(member ref, bool)
Parameters	member ref - a member identifier eg member 1 bool - true to enable, false to disable
Return value	"ok" or error message
Description	Starts the capture engine working. Until this is set true no display of capture is possible.
Example	Enable( member 1 of cast 3, true) put (member 1).Enable(true)
Notes	You must set the videoDevice and audioDevice (if you want something other than the default) before using Enable(true)

SetLicense

This starts the video capture, if captureToStage and/or are set the image will be send to those devices

Format	SetLicense(member ref, id, unlock key, days)
Parameters	member ref - a member identifier eg member 1 id - normally the email address where you recieved the unlock code key - a string in the form of XXXX-XXXX-XXXX-XXXX recieved via email days - the number of valid days, normally 0 for a full license, 30 for demo and 90 for authoring
Return value	"ok" or error message
Description	Enters the license/unlock code into the xtra. You are required to obtain a license for using the xtra. This code is saved in the movie and only needs to be entered once. For more details on licenses click here
Example	SetLicense( member 1, "me@physicalbits.com", 1234-5678-9012-1234, 0) put (member 1).SetLicense( "me@physicalbits.com", 1234-5678-9012-1234, 0)
Notes

Dialogs

This starts the video capture, if captureToStage and/or are set the image will be send to those devices

Format	showVideoDialog( member ref) showAudioDialog( member ref)
Parameters	member ref - a member identifier eg member 1
Return value	"ok" or error message
Description	Display one of the system dialogs to allow the user to change the settings
Example	showVideoDialog( member 1 of cast 3 )
Notes

 

TimedCaptureToFile - Not yet impemented

This starts the video capture, if captureToStage and/or are set the image will be send to those devices

Format	TimedCaptureToFile( member ref, duration)
Parameters	member ref - a member identifier eg member 1 duration - integer, duration to capture to file in milliseconds
Return value	"ok" or error message
Description	Capture to a disk file for the specified duration.
Example	TimedCaptureToFile( member 1 of cast 3,10000 )
Notes

 

Combing the capture properties

Enable	captureToSprite default=true	captureToFile default=false
false	False	False	No images or audio being captured or stored.
true	False	False	Capture system active and buffering image to memory. The memory buffer is one frame long.
true	True	False	Capture system active and associated sprite, if any, will be updated.
true	False	True	Capture system active and the associated file is updated. Any sprites will not be updated.
true	True	True	Capture system active and the associated file and any sprites are updated.

 

 

Version History

Contact details

Email: support@physicalbits.com

Conditions of use