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

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

When you play a live or recorded stream, you must set a buffer time for the stream to play correctly. The buffer time must be at least .1 seconds, but it can be higher. Add the following line to your code (ns is the name of the NetStream object):

ns.setBufferTime(0.1);

Availability

Flash Communication Server 1.0; Flash Player 6.

Parameters

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

To play video (FLV) files, specify the name of the stream without a file extension (for example, "bolero"). To play back MP3 or ID3 tags, you must precede the stream name with mp3:or id3: (for example, "mp3:bolero", or "id3:bolero"). To play H.264/AAC files, you must precede the stream name with mp4: and specify the file extension. For example, to play the file file1.m4v, specify "mp4:file1.m4v".

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 Player first tries to play the live stream specified in name. If a live stream of that name is not found, Flash Player plays the recorded stream specified in name. If neither a live nor a recorded stream is found, Flash Player opens a live stream named name, even though no one is publishing on it. When someone does begin publishing on that stream, Flash Player begins playing it.
• If you pass -1 for start, Flash Player plays only the live stream specified in name. If no live stream is found, Flash Player waits for it indefinitely if len is set to -1; if len is set to a different value, Flash Player 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 Player plays only a recorded stream named name, beginning start seconds from the beginning of the stream. If no recorded stream is found, Flash Player begins playing the next item in the playlist immediately.
• If you pass a negative number other than -1 or -2 for start, Flash Player 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 Player 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 Player plays the single frame that is start seconds from the beginning of a recorded stream (assuming that start is equal to or greater than 0).
• If you pass a positive number for len, Flash Player 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 Player 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 Adobe Flash Media Server Configuration and Administration Guide.

Details

To view video data, you must call Video.attachVideo(); audio being streamed with the video is 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 playback. 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.setBufferTime(0.01);
my_ns.play("record1", 0, 100, true);

Example 2:

/* To play and switch between live and recorded streams:
Suppose that you 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.setBufferTime(0.01);
my_ns.play("record1", 0, -1, false);

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

/* Switch from live1 to record2. record2 starts 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 (you 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()