Flash 8 ActionScript 2.0 Language Reference

Class Camera

Object

The Camera class lets you capture video from a video camera attached to the computer that is running Macromedia Flash Player—for example, to monitor a video feed from a web camera attached to your local system. (Flash provides similar audio capabilities; for more information, see the Microphone class entry.)

Warning: When a SWF file tries to access the camera returned by Camera.get(), Flash Player displays a Privacy dialog box that lets the user choose whether to allow or deny access to the camera. (Make sure your Stage size is at least 215 x 138 pixels for the Camera class examples; this is the minimum size Flash requires to display the dialog box.) End users and administrative users may also disable camera access on a per-site or global basis.

To create or reference a Camera object, use the Camera.get() method.

activityLevel Property

public activityLevel : Number  [read-only]

If the camera is available but is not yet being used because Video.attachVideo() has not been called, this property is set to -1.

If you are streaming only uncompressed local video, this property is set only if you have assigned a function to the Camera.onActivity event handler. Otherwise, it is undefined.

// video instance on the Stage.
var my_video:Video;
var activity_pb:mx.controls.ProgressBar;
var my_cam:Camera = Camera.get();
my_video.attachVideo(my_cam);
activity_pb.mode = "manual";
activity_pb.label = "Activity %3%%";

this.onEnterFrame = function() {
    activity_pb.setProgress(my_cam.activityLevel, 100);
};
my_cam.onActivity = function(isActive:Boolean) {
    var themeColor:String = (isActive) ? "haloGreen" : "haloOrange";
    activity_pb.setStyle("themeColor", themeColor);
};

bandwidth Property

public bandwidth : Number  [read-only]

To set this property, use Camera.setQuality().

var bandwidth_nstep:mx.controls.NumericStepper;
var my_video:Video;
var my_cam:Camera = Camera.get();
my_video.attachVideo(my_cam);
this.createTextField("bandwidth_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
bandwidth_txt.autoSize = true;
this.onEnterFrame = function() {
    bandwidth_txt.text = "Camera is currently using "+my_cam.bandwidth+" bytes ("+Math.round(my_cam.bandwidth/1024)+" KB) bandwidth.";
};
//
bandwidth_nstep.minimum = 0;
bandwidth_nstep.maximum = 128;
bandwidth_nstep.stepSize = 16;
bandwidth_nstep.value = my_cam.bandwidth/1024;
function changeBandwidth(evt:Object) {
    my_cam.setQuality(evt.target.value 1024, 0);
}
bandwidth_nstep.addEventListener("change", changeBandwidth);

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

currentFps Property

public currentFps : Number  [read-only]

var my_video:Video;
var fps_pb:mx.controls.ProgressBar;
var my_cam:Camera = Camera.get();
my_video.attachVideo(my_cam);
this.onEnterFrame = function() {
    fps_pb.setProgress(my_cam.fps-my_cam.currentFps, my_cam.fps);
};

fps_pb.setStyle("fontSize", 10);
fps_pb.setStyle("themeColor", "haloOrange");
fps_pb.labelPlacement = "top";
fps_pb.mode = "manual";
fps_pb.label = "FPS: %2 (%3%% dropped)";

fps Property

public fps : Number  [read-only]

• To set a desired value for this property, use Camera.setMode().
• To determine the rate at which the camera is currently capturing data, use the Camera.currentFps property.

var my_video:Video;
var fps_pb:mx.controls.ProgressBar;
var my_cam:Camera = Camera.get();
my_video.attachVideo(my_cam);
this.onEnterFrame = function() {
    fps_pb.setProgress(my_cam.fps-my_cam.currentFps, my_cam.fps);
};

fps_pb.setStyle("fontSize", 10);
fps_pb.setStyle("themeColor", "haloOrange");
fps_pb.labelPlacement = "top";
fps_pb.mode = "manual";
fps_pb.label = "FPS: %2 (%3%% dropped)";

Note: The setMode() function does not guarantee the requested fps setting; it sets the fps you requested or the fastest fps available.

height Property

public height : Number  [read-only]

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);
var dimensions_lbl:mx.controls.Label;
dimensions_lbl.setStyle("fontSize", 9);
dimensions_lbl.setStyle("fontWeight", "bold");
dimensions_lbl.setStyle("textAlign", "center");
dimensions_lbl.text = "width: "+my_cam.width+", height: "+my_cam.height+", FPS: "+my_cam.fps;

See also the example for Camera.setMode().

index Property

public index : Number  [read-only]

var camera_lbl:mx.controls.Label;
var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

camera_lbl.text = my_cam.index+". "+my_cam.name;
this.createTextField("cameras_txt", this.getNextHighestDepth(), 25, 160, 160, 80);
cameras_txt.html = true;
cameras_txt.border = true;
cameras_txt.wordWrap = true;
cameras_txt.multiline = true;
for (var i = 0; i<Camera.names.length; i++) {
    cameras_txt.htmlText += "<li><u><a href=\"asfunction:changeCamera,"+i+"\">"+Camera.names[i]+"</a></u></li>";
}
function changeCamera(index:Number) {
    my_cam = Camera.get(index);
    my_video.attachVideo(my_cam);
    camera_lbl.text = my_cam.index+". "+my_cam.name;
}

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

motionLevel Property

public motionLevel : Number  [read-only]

Video can be displayed regardless of the value of the motionLevel property. For more information, see Camera.setMotionLevel().

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

// configure the ProgressBar component instance
var motion_pb:mx.controls.ProgressBar;
motion_pb.mode = "manual";
motion_pb.label = "Motion: %3%%";

var motionLevel_lbl:mx.controls.Label;
// configure the NumericStepper component instance
var motionLevel_nstep:mx.controls.NumericStepper;
motionLevel_nstep.minimum = 0;
motionLevel_nstep.maximum = 100;
motionLevel_nstep.stepSize = 5;
motionLevel_nstep.value = my_cam.motionLevel;

// Continuously update the progress of the ProgressBar component instance to the activityLevel 
// of the current Camera instance, which is defined in my_cam 
this.onEnterFrame = function() {
    motion_pb.setProgress(my_cam.activityLevel, 100);
};

// When the level of activity goes above or below the number defined in Camera.motionLevel, 
// trigger the onActivity event handler. 
my_cam.onActivity = function(isActive:Boolean) {
    // If isActive equals true, set the themeColor variable to "haloGreen". 
    // Otherwise set the themeColor to "haloOrange". 
    var themeColor:String = (isActive) ? "haloGreen" : "haloOrange";
    motion_pb.setStyle("themeColor", themeColor);
};

function changeMotionLevel() {
    // Set the motionLevel property for my_cam Camera instance to the value of the NumericStepper 
    // component instance. Maintain the current motionTimeOut value of the my_cam Camera instance. 
    my_cam.setMotionLevel(motionLevel_nstep.value, my_cam.motionTimeOut);
}
motionLevel_nstep.addEventListener("change", changeMotionLevel);

motionTimeOut Property

public motionTimeOut : Number  [read-only]

To set this value, use Camera.setMotionLevel().

var motionLevel_lbl:mx.controls.Label;
var motion_pb:mx.controls.ProgressBar;
var motionTimeOut_nstep:mx.controls.NumericStepper;
var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

this.onEnterFrame = function() {
    motionLevel_lbl.text = "activityLevel: "+my_cam.activityLevel;
};

motion_pb.indeterminate = true;
my_cam.onActivity = function(isActive:Boolean) {
    if (isActive) {
    motion_pb.setStyle("themeColor", "haloGreen");
    motion_pb.label = "Motion is above "+my_cam.motionLevel;
    } else {
    motion_pb.setStyle("themeColor", "haloOrange");
    motion_pb.label = "Motion is below "+my_cam.motionLevel;
    }
};
function changeMotionTimeOut() {
    my_cam.setMotionLevel(my_cam.motionLevel, motionTimeOut_nstep.value 1000);
}
motionTimeOut_nstep.addEventListener("change", changeMotionTimeOut);
motionTimeOut_nstep.value = my_cam.motionTimeOut/1000;

muted Property

public muted : Boolean  [read-only]

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);
my_cam.onStatus = function(infoObj:Object) {
    if (my_cam.muted) {
    // If user is denied access to their Camera, you can display an error message here. You can display the user's Camera/Privacy settings again using System.showSettings(0); 
    trace("User denied access to Camera");
    System.showSettings(0);
    }
};

name Property

public name : String  [read-only]

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

this.createTextField("name_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
name_txt.autoSize = true;
name_txt.text = my_cam.name;

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components DepthManager class instead of the MovieClip.getNextHighestDepth() method.

names Property

public static names : Array  [read-only]

Calling the Camera.names property requires an extensive examination of the hardware, and it may take several seconds to build the array. In most cases, you can just use the default camera.

Note: The correct syntax is Camera.names. To assign the return value to a variable, use syntax like cam_array = Camera.names. To determine the name of the current camera, use active_cam.name.

var my_video:Video;
var cam_array:Array = Camera.names;
if (cam_array.length>1) {
    System.showSettings(3);
}
var my_cam:Camera = Camera.get();
my_video.attachVideo(my_cam);

quality Property

public quality : Number  [read-only]

var quality_nstep:mx.controls.NumericStepper;

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

quality_nstep.minimum = 0;
quality_nstep.maximum = 100;
quality_nstep.stepSize = 5;
quality_nstep.value = my_cam.quality;

function changeQuality() {
    my_cam.setQuality(my_cam.bandwidth, quality_nstep.value);
}
quality_nstep.addEventListener("change", changeQuality);

width Property

public width : Number  [read-only]

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);
var dimensions_lbl:mx.controls.Label;
dimensions_lbl.setStyle("fontSize", 9);
dimensions_lbl.setStyle("fontWeight", "bold");
dimensions_lbl.setStyle("textAlign", "center");
dimensions_lbl.text = "width: "+my_cam.width+", height: "+my_cam.height+", FPS: "+my_cam.fps;

See also the example for Camera.setMode().

onActivity Event Handler

public onActivity = function(active:Boolean) {}

To specify the amount of motion required to invoke Camera.onActivity(true) and the amount of time that must elapse without activity before invoking Camera.onActivity(false), use Camera.setMotionLevel().

// Assumes a Video object named "myVideoObject" is on the Stage
active_cam = Camera.get();
myVideoObject.attachVideo(active_cam);
active_cam.setMotionLevel(10, 500);
active_cam.onActivity = function(mode)
{
    trace(mode);
}

onStatus Event Handler

public onStatus = function(infoObject:Object) {}

When a SWF file tries to access the camera, Flash Player displays a Privacy dialog box that lets the user choose whether to allow or deny access.

• If the user allows access, the Camera.muted property is set to false, and this handler is invoked with an information object whose code property is "Camera.Unmuted" and whose level property is "Status".
• If the user denies access, the Camera.muted property is set to true, and this handler is invoked with an information object whose code property is "Camera.Muted" and whose level property is "Status".

To determine whether the user has denied or allowed access to the camera without processing this event handler, use the Camera.muted property.

Note: If the user chooses to permanently allow or deny access for all SWF files from a specified domain, this handler is not invoked for SWF files from that domain unless the user later changes the privacy setting. For more information, see Camera.get().

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);
my_cam.onStatus = function(infoObj:Object) {
    switch (infoObj.code) {
    case 'Camera.Muted' :
    trace("Camera access is denied");
    break;
    case 'Camera.Unmuted' :
    trace("Camera access granted");
    break;
    }
}

get Method

public static get([index:Number]) : Camera

Unlike objects that you create using the new constructor, multiple calls to Camera.get() reference the same camera. Thus, if your script contains the lines first_cam = Camera.get() and second_cam = Camera.get(), both first_cam and second_cam reference the same (default) camera.

In general, you shouldn't pass a value for index; simply use Camera.get() to return a reference to the default camera. By means of the Camera settings panel (discussed later in this section), the user can specify the default camera Flash should use. If you pass a value for index, you might be trying to reference a camera other than the one the user prefers. You might use index in rare cases--for example, if your application is capturing video from two cameras at the same time.

When a SWF file tries to access the camera returned by Camera.get(), Flash Player displays a Privacy dialog box that lets the user choose whether to allow or deny access to the camera. (Make sure your Stage size is at least 215 x 138 pixels; this is the minimum size Flash requires to display the dialog box.)

When the user responds to this dialog box, the Camera.onStatus event handler returns an information object that indicates the user's response. To determine whether the user has denied or allowed access to the camera without processing this event handler, use the Camera.muted property.

The user can also specify permanent privacy settings for a particular domain by right-clicking (Windows) or Control-clicking (Macintosh) while a SWF file is playing, selecting Settings, opening the Privacy panel, and selecting Remember.

You can't use ActionScript to set the Allow or Deny value for a user, but you can display the Privacy panel for the user by using System.showSettings(0). If the user selects Remember, Flash Player no longer displays the Privacy dialog box for SWF files from this domain.

If Camera.get returns null, either the camera is in use by another application, or there are no cameras installed on the system. To determine whether any cameras are installed, use Camera.names.length. To display the Flash Player Camera Settings panel, which lets the user choose the camera to be referenced by Camera.get(), use System.showSettings(3).

Scanning the hardware for cameras takes time. When Flash finds at least one camera, the hardware is not scanned again for the lifetime of the player instance. However, if Flash doesn't find any cameras, it will scan each time Camera.get is called. This is helpful if a user has forgotten to connect the camera; if your SWF file provides a Try Again button that calls Camera.get, Flash can find the camera without the user having to restart the SWF file.

Note: The correct syntax is Camera.get(). To assign the Camera object to a variable, use syntax like active_cam = Camera.get().

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);
var camera_lbl:mx.controls.Label;
var cameras_cb:mx.controls.ComboBox;
camera_lbl.text = my_cam.name;
cameras_cb.dataProvider = Camera.names;
function changeCamera():Void {
    my_cam = Camera.get(cameras_cb.selectedIndex);
    my_video.attachVideo(my_cam);
    camera_lbl.text = my_cam.name;
}
cameras_cb.addEventListener("change", changeCamera);
camera_lbl.setStyle("fontSize", 9);
cameras_cb.setStyle("fontSize", 9);

setMode Method

public setMode([width:Number], [height:Number], [fps:Number], [favorArea:Boolean]) : Void

By default, Flash drops frames as needed to maintain image size. To minimize the number of dropped frames, even if this means reducing the size of the image, pass false for the favorArea parameter.

When choosing a native mode, Flash tries to maintain the requested aspect ratio whenever possible. For example, if you issue the command active_cam.setMode(400, 400, 30), and the maximum width and height values available on the camera are 320 and 288, Flash sets both the width and height at 288; by setting these properties to the same value, Flash maintains the 1:1 aspect ratio you requested.

To determine the values assigned to these properties after Flash selects the mode that most closely matches your requested values, use Camera.width, Camera.height, and Camera.fps.

var my_cam:Camera = Camera.get();
var my_video:Video;
my_video.attachVideo(my_cam);

fps_ti.maxChars = 2;
fps_ti.restrict = [0-9];
fps_lbl.text = "Current: "+my_cam.fps+" fps";

function changeFps():Void {
    my_cam.setMode(my_cam.width, my_cam.height, fps_ti.text);
    fps_lbl.text = "Current: "+my_cam.fps+" fps";
    fps_ti.text = my_cam.fps;
    Selection.setSelection(0,2);
}
fps_ti.addEventListener("enter", changeFps);

setMotionLevel Method

public setMotionLevel([motionLevel:Number], [timeOut:Number]) : Void

Note: Video can be displayed regardless of the value of the sensitivity parameter. This parameter determines only when and under what circumstances Camera.onActivity is invoked--not whether video is actually being captured or displayed.

• To prevent the camera from detecting motion at all, pass a value of 100 for sensitivity; Camera.onActivity is never invoked. (You would probably use this value only for testing purposes--for example, to temporarily disable any actions set to occur when Camera.onActivity is invoked.)
• To determine the amount of motion the camera is currently detecting, use the Camera.activityLevel property.

  Motion sensitivity values correspond directly to activity values. Complete lack of motion is an activity value of 0. Constant motion is an activity value of 100. Your activity value is less than your motion sensitivity value when you're not moving; when you are moving, activity values frequently exceed your motion sensitivity value.

  This method is similar in purpose to Microphone.setSilenceLevel(); both methods are used to specify when the onActivity event handler should be invoked. However, these methods have a significantly different impact on publishing streams:

• Microphone.setSilenceLevel() is designed to optimize bandwidth. When an audio stream is considered silent, no audio data is sent. Instead, a single message is sent, indicating that silence has started.
• Camera.setMotionLevel() is designed to detect motion and does not affect bandwidth usage. Even if a video stream does not detect motion, video is still sent.

// Assumes a Video object named "myVideoObject" is on the Stage
active_cam = Camera.get();
x = 0;
function motion(mode) {
    trace(x + ": " + mode);
    x++;
}
active_cam.onActivity = function(mode) {
    motion(mode);
}
active_cam.setMotionLevel(30, 500);
myVideoObject.attachVideo(active_cam);

setQuality Method

public setQuality([bandwidth:Number], [quality:Number]) : Void

Use this method to specify which element of the outgoing video feed is more important to your application--bandwidth use or picture quality.

• To indicate that bandwidth use takes precedence, pass a value for bandwidth and 0 for frameQuality. Flash will transmit video at the highest quality possible within the specified bandwidth. If necessary, Flash will reduce picture quality to avoid exceeding the specified bandwidth. In general, as motion increases, quality decreases.
• To indicate that quality takes precedence, pass 0 for bandwidth and a numeric value for frameQuality. Flash will use as much bandwidth as required to maintain the specified quality. If necessary, Flash will reduce the frame rate to maintain picture quality. In general, as motion increases, bandwidth use also increases.
• To specify that both bandwidth and quality are equally important, pass numeric values for both parameters. Flash will transmit video that achieves the specified quality and that doesn't exceed the specified bandwidth. If necessary, Flash will reduce the frame rate to maintain picture quality without exceeding the specified bandwidth.

// Ensure that no more than 8192 (8K/second) is used to send video
active_cam.setQuality(8192,0);

// Ensure that no more than 8192 (8K/second) is used to send video
// with a minimum quality of 50
active_cam.setQuality(8192,50);

// Ensure a minimum quality of 50, no matter how much bandwidth it takes
active_cam.setQuality(0,50);