NetStream.attachVideo()

Availability

Flash Player 6.
Flash Communication Server MX 1.0.

Usage

public attachVideo(source : Camera [, snapShotMilliseconds : Number])

Parameters

source The source of the video transmission. Valid values are a Camera object (which starts capturing video) and null. If you pass null, Flash stops capturing video, and any additional parameters you send are ignored.

snapShotMilliseconds An optional integer that specifies whether the video stream is continuous, a single frame, or a series of single frames used to create time-lapse photography.

If this parameter is omitted, Flash captures all video until you issue my_ns.attachVideo(null).
If you pass 0, Flash captures only a single video frame. Use this value to transmit "snapshots" within a preexisting stream.

NOTE

Flash interprets invalid, negative, or nonnumeric arguments as 0.
If you pass a positive number, Flash captures a single video frame and then appends a pause of length snapShotMilliseconds as a "trailer" on the snapshot. Use this value to create time-lapse photography effects.

Returns

Nothing.

Description

Method; starts capturing video from the specified source, or stops capturing if source is null. This method is available only to the publisher of the specified stream.

After attaching the video source, you must call NetStream.publish() to actually begin transmitting. Subscribers who want to display the video must call the NetStream.play() and Video.attachVideo() methods to display the video on the Stage.

You can use snapShotMilliseconds to send a single snapshot (by providing a value of 0) or a series of snapshots--in effect, time-lapse footage--by providing a positive number that adds a trailer of the specified number of milliseconds to the video feed. The trailer extends the length of time the video message is displayed. By repeatedly calling attachVideo with a positive value for snapShotMilliseconds, the snapshot/trailer/snapshot/trailer... sequence creates time-lapse footage. For example, you could capture one frame per day and append it to a video file. When a subscriber plays back the file, each frame remains onscreen for the specified number of milliseconds and then the next frame is displayed.

The snapShotMilliseconds parameter serves a different purpose from the fps parameter you can set with Camera.setMode(). When you specify snapShotMilliseconds, you are controlling how much time elapses during playback between recorded frames. When you specify fps using Camera.setMode(), you are controlling how much time elapses during recording and playback between recorded frames.

For example, suppose you want to take a snapshot every 5 minutes for a total of 100 snapshots. You can do this in two different ways:

You can issue a NetStream.attachVideo(source, 500) command 100 times, once every 5 minutes. This takes 500 minutes to record, but the resulting file will play back in 50 seconds (100 frames with 500 milliseconds between frames).
You can issue a Camera.setMode() command with an fps value of 1/300 (one per 300 seconds, or one every 5 minutes), and then issue a NetStream.attachVideo(source) command, letting the camera capture continuously for 500 minutes. The resulting file will play back in 500 minutes--the same length of time that it took to record--with each frame being displayed for 5 minutes.

Both techniques capture the same 500 frames, and both approaches are useful; which approach to use depends primarily on your playback requirements. For example, in the second case, you could be recording audio the entire time. Also, both files would be approximately the same size.

Example

The following function publishes a stream on a NetConnection named my_nc containing the camera output from active_cam.

function pubLive() {
    
    // Create a new source stream.
    var source_ns:NetStream = new NetStream(my_nc);

    /* Attach the camera activity to the source stream. This call causes a warning message to show which service is requesting access. It also gives the user the option of not sending the camera activity to the server. */    source_ns.attachVideo(active_cam);
    
    // Get the stream name from the user input.
    var mySubj:String = subject;

    /* Assuming the user named the stream 'webCamStream',
    publish the live camera activity as 'webCamStream'. */
    source_ns.publish(mySubj, "live");
}

See also the example for MovieClip.attachAudio().