NetStream.play

Client-Side Communication ActionScript > NetStream.play

NetStream.play

Availability

Flash Player 6.

Flash Communication Server MX.

Usage

myStream.play(whatToPlay | false [,start [, length [, flushPlaylists]]])

Parameters

whatToPlay 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 Communication Applications Help.

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 `whatToPlay`. If a live stream of that name is not found, Flash plays the recorded stream specified in `whatToPlay`. If neither a live nor a recorded stream is found, Flash opens a live stream named `whatToPlay` 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 `whatToPlay`. If no live stream is found, Flash waits for it indefinitely if `length` is set to -1; if `length` is set to a different value, Flash waits for `length` 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 `whatToPlay`, 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.

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

	The default value for `length` 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 `length`, 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 `length`, Flash plays a live stream for `length` seconds after it becomes available, or plays a recorded stream for `length` seconds. (If a stream ends before `length` seconds, playback ends when the stream ends.)
	If you pass a negative number other than -1 for `length`, Flash interprets the value as if it were -1.

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

You can also specify a value of 2 or 3 for the flushPlaylists 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 flushPlaylists causes Flash Communication Server to return all messages in the recorded stream file at once, rather than at the intervals which the messages were originally recorded (the default behavior).

This is especially useful for accessing log files recorded by Flash Communication Server. For more information on Flash Communication Server logging, see TechNote 16464 on the Macromedia Flash Communication Server Support Center.

Description

Method; feeds streaming audio, video, and text messages being published on the Flash Communication 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 a Video.attachVideo method; 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 these values interact.

start

length

Flash Player behavior

(Default)

(Default)

Plays the live stream until it is no longer available. If a live stream of the specified name is not found, the Flash Player plays a recorded stream until it ends.

-2

19

Plays a live stream for up to 19 seconds after it becomes available. If a live stream of the specified name is not found, the Flash Player plays a recorded stream for 19 seconds.

15

19

Plays a recorded stream for 19 seconds, beginning 15 seconds from the beginning of the stream.

15

(Default)

Plays a recorded stream, beginning 15 seconds from the beginning of the stream, until the stream ends.

-1

(Default)

Plays a live stream until it is no longer available.

start	length	Flash Player behavior
(Default)	(Default)	Plays the live stream until it is no longer available. If a live stream of the specified name is not found, the Flash Player plays a recorded stream until it ends.
-2	19	Plays a live stream for up to 19 seconds after it becomes available. If a live stream of the specified name is not found, the Flash Player plays a recorded stream for 19 seconds.
15	19	Plays a recorded stream for 19 seconds, beginning 15 seconds from the beginning of the stream.
15	(Default)	Plays a recorded stream, beginning 15 seconds from the beginning of the stream, until the stream ends.
-1	(Default)	Plays a live stream until it is no longer available.

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 flushPlaylists each time. Conversely, if you want to play the specified stream immediately, clearing any other streams that are queued for play, pass true for flushPlaylists.

Example

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

Example 1:

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

dstStream = new NetStream(myConnection);
myVideoObject.attachVideo(dstStream);

// 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.
dstStream.play("stephen");

// To immediately play a recorded stream named record1
// starting at the beginning, for up to 100 seconds.
dstStream.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.
myConnection = new NetConnection();
myConnection.connect("rtmp://localhost/appName/appInstance");

// Create a NetStream for playing
dstStream = new NetStream(myConnection);
myVideoObject.attachVideo(dstStream);

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

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

// Switch from live1 to record2.
// record2 will start to play after live1 plays for 5 seconds.
dstStream.play("record2", 0, -1, false);


// Interrupt the current play and play a segment in record1 again
// (we can implement a seek by this)
dstStream.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.

dstStream = new NetStream(myConnection);
dstStream.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.

dstStream = new NetStream(myConnection);
dstStream.play("log", 0, -1, 2);