Flash Media Server

Client-Side ActionScript Language Reference for Flash Media Server 2 > Client-Side ActionScript Language Reference > NetStream class > NetStream.play()

NetStream.play()

Availability

• Flash Player 6.
• Flash Communication Server MX 1.0.

Usage

public play(name : Object [,start : Number[, len : Number[, reset : Object]]])

Parameters

name An identifying name for live data published by NetStream.publish(), a recorded file name for playback, or false. If you pass false, the stream stops playing and any additional parameters you send are ignored.

To play back FLV files, the default Flash file format for recorded streams, specify the name of the stream without a file extension (for example, "bolero"). To play back MP3 files that you've stored on the server or the ID3 tags of MP3 files, you must precede the stream name with mp3: or id3:--for example, "mp3:bolero" or "id3:bolero". For more information on playing MP3 files, see Developing Media Applications.

start An optional numeric parameter that specifies the start time, in seconds. This parameter can also be used to indicate whether the stream is live or recorded.

• The default value for start is -2, which means that Flash first tries to play the live stream specified in name. If a live stream of that name is not found, Flash plays the recorded stream specified in name. If neither a live nor a recorded stream is found, Flash opens a live stream named name, even though no one is publishing on it. When someone does begin publishing on that stream, Flash begins playing it.
• If you pass -1 for start, Flash plays only the live stream specified in name. If no live stream is found, Flash waits for it indefinitely if len is set to -1; if len is set to a different value, Flash waits for len seconds before it begins playing the next item in the playlist.
• If you pass 0 or a positive number for start, Flash plays only a recorded stream named name, beginning start seconds from the beginning of the stream. If no recorded stream is found, Flash begins playing the next item in the playlist immediately.
• If you pass a negative number other than -1 or -2 for start, Flash interprets the value as if it were -2.

len An optional numeric parameter that specifies the duration of the playback, in seconds.

• The default value for len is -1, which means that Flash plays a live stream until it is no longer available or plays a recorded stream until it ends.
• If you pass 0 for len, Flash plays the single frame that is start seconds from the beginning of a recorded stream (assuming start is equal to or greater than 0).
• If you pass a positive number for len, Flash plays a live stream for len seconds after it becomes available, or plays a recorded stream for len seconds. (If a stream ends before len seconds, playback ends when the stream ends.)
• If you pass a negative number other than -1 for len, Flash interprets the value as if it were -1.

reset An optional Boolean value or number that specifies whether to flush any previous playlist. If reset is false (0), name is added (queued) in the current playlist; that is, name plays only after previous streams finish playing. You can use this technique to create a dynamic playlist. If reset is true (1), any previous play calls are cleared and name is played immediately. By default, the value is true.

You can also specify a value of 2 or 3 for the reset parameter, which is useful when playing recorded stream files that contain message data. These values are analogous to passing false (0) and true (1), respectively: a value of 2 maintains a playlist, and a value of 3 resets the playlist. However, the difference is that specifying 2 or 3 for reset causes Flash Media Server to return all messages in the recorded stream file at once, rather than at the intervals at which the messages were originally recorded (the default behavior).

This is especially useful for accessing log files recorded by Flash Media Server. For more information on Flash Media Server logging, see TechNote 16464.

Description

Method; feeds streaming audio, video, and text messages being published on the Flash Media Server, or a recorded file stored on the server, to the client. This method is available only to clients subscribed to the specified stream, not to the stream's publisher.

To view video data, you must call Video.attachVideo(); audio being streamed with the video will be played automatically. If audio-only data is being streamed, you can use MovieClip.attachAudio() to route streaming audio to a movie clip, and then create a Sound object to control some aspects of the audio.

You can use the optional parameters of this method to control various aspects of playback behavior. The following table shows a few ways in which these values interact:

This method can invoke NetStream.onStatus with a number of different information objects. For example, if the specified stream isn't found, NetStream.onStatus is called with a code property of NetStream.Play.StreamNotFound. For more information, see NetStream.onStatus.

If you want to create a dynamic playlist that switches among different live or recorded streams, call play more than once and pass false for reset each time. Conversely, if you want to play the specified stream immediately, clearing any other streams that are queued for play, pass true for reset.

Example

The following examples show some ways to use this method to play back live or recorded streams.

Example 1:

var my_nc:NetConnection = new NetConnection();
my_nc.connect("rtmp://localhost/appName/appInstance");

var my_ns:NetStream = new NetStream(my_nc);
my_video.attachVideo(my_ns);

/* To play a live stream named "stephen" being published elsewhere
using the default values -- start time is -2, length is -1, 
and flushPlaylists is true -- don't pass any optional parameters.*/
my_ns.play("stephen");

/* to immediately play a recorded stream named record1
starting at the beginning, for up to 100 seconds*/
my_ns.play("record1", 0, 100, true);

Example 2:

/* To play and switch between live and recorded streams:
Suppose we have two live streams, live1 and live2, 
and three recorded streams, record1, record2, and record3. 
The play order is record1, live1, record2, live2, and record3.*/
var my_nc:NetConnection = new NetConnection();
my_nc.connect("rtmp://localhost/appName/appInstance");

// Create a NetStream for playing.
var my_ns:NetStream = new NetStream(my_nc);
my_video.attachVideo(my_ns);

// Play record1.
my_ns.play("record1", 0, -1, false);

/* Switch from record1 to live1. live1 will start to play after record1 is done. */
my_ns.play("live1", -1, 5, false);

/* Switch from live1 to record2. record2 will start to play after live1 plays for 5 seconds.*/
my_ns.play("record2", 0, -1, false);
/* Interrupt the current play and play a segment in record1 again (we can implement a seek by this). */
my_ns.play("record1", 1, 5, true);

In the following example, data messages in the recorded stream file log.flv are returned at the intervals at which they were originally recorded.

var my_ns:NetStream = new NetStream(my_nc);
my_ns.play("log", 0, -1);    

In the following example, data messages in the recorded stream file log.flv are returned all at once, rather than at the intervals at which they were originally recorded.

var my_ns:NetStream = new NetStream(my_nc);
my_ns.play("log", 0, -1, 2);

See also

MovieClip.attachAudio(), NetStream.close(), NetStream.pause(), NetStream.publish()