Stream class

The Stream class lets you manage or republish streams in an application. A Stream object is the server-side equivalent of the client-side NetStream object.

You can’t attach audio or video sources to a Stream object; you can only play and manage existing streams. Use the Stream class to shuffle existing streams in a playlist, pull streams from other servers, and control access to streams. You can also record streams published by a client and record data streams such as log files.

A stream is a one-way connection between a client running Flash Player and a server running Flash Media Server. A stream can also be a connection between two servers running Flash Media Server. You can create a stream in Server-Side ActionScript by calling Stream.get(). A client can access multiple streams at the same time, and there can be hundreds or thousands of Stream objects active at the same time. You can record in FLV and F4V format.

Streams can contain ActionScript data. Call the Stream.send() method to add data to a stream. You can extract this data without waiting for a stream to play in real time, such as when you’re creating a log file. You can also use it to add metadata to a stream.

Availability

Flash Communication Server 1

Property summary

Property	Description
`Stream.bufferTime`	Read-only; indicates how long to buffer messages before a stream is played, in seconds.
`Stream.maxQueueDelay`	Read-only; the maximum time, in milliseconds, that the live queue can delay transmitting messages.
`Stream.maxQueueSize`	Read-only; the maximum size, in bytes, that the live queue can grow to before transmitting the messages it contains.
`Stream.name`	Read-only; contains a unique string associated with a live stream.
`Stream.publishQueryString`	Read-only; the query string specified in the stream path when the stream was published.
`Stream.syncWrite`	A boolean value that controls when a stream writes the contents of the buffer to a file when the stream is recording.
`Stream.time`	Read-only; the number of seconds a stream has been playing.

Method summary

Method	Description
`Stream.clear()`	Deletes a recorded file from the server.
`Stream.destroy()`	Unlinks and cleans up an instance of the Stream class.
`Stream.flush()`	Flushes a stream.
`Stream.get()`	Static; returns a reference to a Stream object.
`Stream.getOnMetaData()`	Returns an object containing the metadata for the named stream or video file.
`Stream.length()`	Static; returns the length of a recorded stream in seconds.
`Stream.play()`	Controls the data source of a stream with an optional start time, duration, and reset flag to flush any previously playing stream.
`Stream.record()`	Records all the data passing through a Stream object and creates a file of the recorded stream.
`Stream.send()`	Invokes a remote method on a client-side NetStream object.
`Stream.setBufferTime()`	Sets the length of the message queue.
`Stream.setVirtualPath()`	Sets the virtual directory path for video stream playback.
`Stream.size()`	Static; returns the size of a recorded stream in bytes.

Event handler summary

Event handler	Description
`Stream.onStatus()`	Invoked every time the status of a Stream object changes.

Stream.bufferTime

myStream.bufferTime

Read-only; indicates how long to buffer messages before a stream plays, in seconds. This property applies only when playing a stream from a remote server or when playing a recorded stream locally. Call Stream.setBufferTime() to set the bufferTime property.

A message is data that is sent back and forth between Flash Media Server and Flash Player. The data is divided into small packets (messages), and each message has a type (audio, video, or data).

Availability

Flash Communication Server 1

Stream.clear()

myStream.clear()

Deletes a recorded FLV or F4V file from the server.

Availability

Flash Communication Server 1

Returns

A boolean value of true if the call succeeds; otherwise, false.

Example

The following example deletes a recorded stream called playlist.flv. Before the stream is deleted, the example defines an onStatus() handler that uses two information object error codes, NetStream.Clear.Success and NetStream.Clear.Failed, to send status messages to the application log file and the Live Log panel in the Administration Console.

s = Stream.get("playlist"); 
if (s){ 
    s.onStatus = function(info){ 
        if(info.code == "NetStream.Clear.Success"){ 
            trace("Stream cleared successfully."); 
        } 
        if(info.code == "NetStream.Clear.Failed"){ 
            trace("Failed to clear stream."); 
        } 
    }; 
    s.clear(); 
}

Stream.destroy()

Stream.destroy()

Unlinks and cleans up an instance of the Stream class. When a call to Stream.destroy() destroys a stream, the server stops any NetStream playing the stream and logs the code 440 in the Access log. Publishers are disconnected and recordings are stopped.

Instances of the Stream class are considered live streams. These streams are used as proxy streams, for server-to-sever streaming, direct client playback, and recordings. It can be difficult to determine whether you’ve properly released a live stream has finished playing. Call Stream.destroy() to unlink and clean up a stream resource.

Availability

Flash Meda Server 3.5.4

Returns

A boolean value of true if the call succeeds.

A boolean value of false if the stream is not found. This case occurs only if the Stream reference has already been destroyed or if an error has occurred.

Example

The following example destroys a stream called streamA:

// Get a stream. 
streamA = Stream.get("clientStream1"); 
// Destroy the stream. 
Stream.destroy(streamA);

Stream.flush()

myStream.flush()

Flushes a stream. If the stream is used for recording, the flush() method writes the contents of the buffer associated with the stream to the recorded file.

It is highly recommended that you call flush() on a stream that contains only data. Synchronization problems can occur if you call the flush() method on a stream that contains data and either audio, video, or both.

Availability

Flash Media Server 2

Returns

A boolean value of true if the buffer was successfully flushed; otherwise, false.

Example

The following example flushes the myStream stream:

// Set up the server stream. 
application.videoStream = Stream.get("aVideo"); 
 
if (application.videoStream){ 
    application.videoStream.record(); 
    application.videoStream.send("test", "hello world"); 
    application.videoStream.flush(); 
}

Stream.get()

Stream.get(name)

Static; returns a reference to a Stream object. If the requested object is not found, a new instance is created. After you call the Stream.get() method, you can call the Stream.record() and Stream.play() methods to publish and record streams.

You can publish and record streams in FLV (default) or F4V formats. You determine the format in the name parameter you pass to the Stream.get() method. To publish in FLV format, specify only the stream name, for example, Stream.get("footballGame"). To publish in F4V format, prefix the stream name with mp4:. You can optionally specify the file extension, for example, the following code is all legal:

Stream.get("mp4:footballGame.f4v") 
Stream.get("mp4:footballGame.mp4") 
Stream.get("mp4:footballGame")

F4V files behave differently than FLV files. To create a file with a file extension, you must specify a file extension. If you don’t specify a file extension, the file created will not have a file extension.

To record one stream, create a stream with that format when you call Stream.get(). For example, if you want to record the stream “myHomeMovie.mp4”, use code like the following:

s = Stream.get("mp4:streamName.mp4"); 
if(s){ 
    s.record(); 
    s.play("mp4:myHomeMovie.mp4"); 
}

When you add streams to the end of an existing file to make a playlist, you might add streams with different settings and formats. If you record a file in FLV format, the server records the streams encoded with On2 VP6 and ignores streams encoded with H.264. If you record a file in F4V format, you can append any type of content to the stream, including FLV, MP3, MP4, F4V, and live streams.

Note: To play or edit F4V files recorded by Flash Media Server in other tools, use the Adobe Flash Media Server F4V Post Processor tool. The tool is available at www.adobe.com/go/fms_tools.

Availability

Flash Communication Server 1

Parameters

name: A string specifying the name of a Stream object.

Returns

A Stream object if the call is successful; otherwise, null.

Examples

The following example publishes and records a video in F4V format. The stream contains 2 videos, one in FLV format, and one in MP4 format.

var s=Stream.get("mp4:streamName.f4v"); 
if(s) { 
    s.record(); 
    s.play("sample",-2,-1); 
    s.play("mp4:sample_mp4.mp4",-2,-1,false); 
}

Stream.getOnMetaData()

Stream.getOnMetaData(name)

Static; returns an object containing the metadata for the named stream or video file. The object contains one property for each metadata item. The Flash Video Exporter utility (version 1.1 or later) embeds video duration, creation date, data rates, and other information into the video file.

Availability

Flash Media Server 2

Parameter

name: A string indicating the name of a recorded stream, such as "myVideo". For FLV files, pass the name without a file extension or prefix: "myVideo". For F4V files, pass the name with the prefix mp4: "mp4:myVideo". Append a file extension if the F4V file has a file extension.

Returns

An Object containing the metadata as properties.

Example

The following example lists the properties and values for the metadata for the recorded stream myVideo.flv:

var infoObject = Stream.getOnMetaData("myVideo"); 
 
trace("Metadata for myVideo.flv:"); 
 
for(i in infoObject){ 
    trace(i + " = " + infoObject[i]); 
}

Stream.length()

Stream.length(name[, virtualKey])

Static; returns the length of a recorded file in seconds. If the requested file is not found, the return value is 0.

Availability

Flash Communication Server 1

Parameters

name: A string indicating the name of a recorded stream. To get the length of an MP3 file, precede the name of the file with mp3: (for example, "mp3:beethoven").
virtualKey: A string indicating a key value. Starting with Flash Media Server 2, stream names are not always unique. You can create multiple streams with the same name and place them in different physical directories. Then, use the VirtualDirectory section and VirtualKeys section of the Vhost.xml file to direct clients to the appropriate stream. The Stream.length() method is not associated with a client, but connects to a stream on the server. As a result, you may need to specify a virtual key to identify the correct stream. For more information about keys, see Client.virtualKey. This parameter is optional.

Returns

A number.

Example

The following example gets the length of the recorded stream file myVideo and assigns it to the variable streamLen:

function onProcessCmd(cmd){ 
    var streamLen = Stream.length("myVideo"); 
    trace("Length: " + streamLen + "\n"); 
}

The following example gets the length of the MP3 file beethoven.mp3 and assigns it to the variable streamLen:

function onProcessCmd(cmd){ 
    var streamLen = Stream.length("mp3:beethoven"); 
    trace("Length: " + streamLen + "\n"); 
}

The following example gets the length of the MP4 file beethoven.mp4 and assigns it to the variable streamLen:

function onProcessCmd(cmd){ 
    var streamLen = Stream.length("mp4:beethoven"); 
    trace("Length: " + streamLen + "\n"); 
}

Stream.liveEvent

stream.liveEvent

A string indicating the name of an HTTP Dynamic Streaming live event. For more information, see Using Adobe HTTP Dynamic Streaming .

Availability

Flash Media Server 3.8

Example

The following example sets the name of a live event to “myevent”:

application.onPublish = function(clientObj, streamObj){ 
    livestream = Stream.get("f4f:livestream"); 
    livestream.liveEvent = "myevent"; 
    livestream.record("record"); 
    livestream.play(streamObj.name, -1); 
}

Stream.maxQueueDelay

myStream.maxQueueDelay

The maximum time, in milliseconds, that the live queue can delay transmitting messages.

Availability

Flash Media Server 3.5

Example

For an example, see the Stream.publishQueryString property.

Stream.maxQueueSize

myStream.maxQueueSize

The maximum size, in bytes, that the live queue can grow to before transmitting the messages it contains.

Availability

Flash Media Server 3.5

Example

For an example, see the Stream.publishQueryString property.

Stream.name

myStream.name

Read-only; contains a unique string associated with a live stream. You can use this property as an index to find a stream within an application.

Availability

Flash Communication Server 1

Example

The following function takes a Stream object as a parameter and returns the name of the stream:

function getStreamName(myStream){ 
    return myStream.name; 
}

Stream.onStatus()

myStream.onStatus = function([infoObject]) {}

Invoked every time the status of a Stream object changes. For example, if you play a file in a stream, Stream.onStatus() is invoked. Use Stream.onStatus() to check when play starts and ends, when recording starts, and so on.

Availability

Flash Communication Server 1

Parameters

infoObject

An Object with code and level properties that contain information about a stream. This parameter is optional, but it is usually used. The Stream information object contains the following properties:

Property	Meaning
`code`	A string identifying the event that occurred.
`description`	Detailed information about the code. Not every information object includes this property.
`details`	The stream name.
`level`	A string indicating the severity of the event.

The following table describes the code and level property values:

Code property	Level property	Description
`NetStream.Clear.Failed`	`error`	A call to `application.clearStreams()` failed to delete a stream.
`NetStream.Clear.Success`	`status`	A call to `application.clearStreams()` successfully deleted a stream.
`NetStream.Failed`	`error`	An attempt to use a Stream method failed.
`NetStream.Play.Failed`	`error`	An call to `Stream.play()` failed.
`NetStream.Play.InsufficientBW`	`warning`	Data is playing behind the normal speed.
`NetStream.Play.Start`	`status`	Play was started.
`NetStream.Play.StreamNotFound`	`error`	An attempt was made to play a stream that does not exist.
`NetStream.Play.Stop`	`status`	Play was stopped.
`NetStream.Play.Reset`	`status`	A playlist was reset.
`NetStream.Play.PublishNotify`	`status`	The initial publish operation to a stream was successful. This message is sent to all subscribers.
`NetStream.Play.UnpublishNotify`	`status`	An unpublish operation from a stream was successful. This message is sent to all subscribers.
`NetStream.Publish.BadName`	`error`	An attempt was made to publish a stream that is already being published by someone else.
`NetStream.Publish.Start`	`status`	Publishing was started.
`NetStream.Record.Failed`	`error`	An attempt to record a stream failed.
`NetStream.Record.NoAccess`	`error`	An attempt was made to record a read-only stream.
`NetStream.Record.Start`	`status`	Recording was started.
`NetStream.Record.Stop`	`status`	Recording was stopped.
`NetStream.Unpublish.Success`	`status`	A stream has stopped publishing.

Example

The following server-side code attempts to delete a given stream and traces the resulting return code:

Client.prototype.delStream = function(streamName){ 
    trace("*** deleting stream: " + streamName); 
    s = Stream.get("streamName"); 
    if (s) { 
        s.onStatus = function(info){ 
            if (info.code == "NetStream.Clear.Success")    { 
                trace("*** Stream " + streamName + "deleted."); 
            } 
            if (info.code == "NetStream.Clear.Failure")    { 
                trace("*** Failure to delete stream " + streamName); 
            } 
        }; 
        s.clear(); 
    } 
}

Stream.play()

myStream.play(streamName, [startTime, length, reset, remoteConnection, virtualKey])

Controls the data source of a stream with an optional start time, duration, and reset flag to flush any previously playing stream. Call play() to do the following:

Chain streams between servers.
Create a hub to switch between live streams and recorded streams.
Combine streams into a recorded stream.

You can combine multiple streams to create a playlist for clients. The Stream.play() method behaves differently from the NetStream.play() method on the client side. A server-side call to Stream.play() is similar to a client-side call to NetStream.publish(); it controls the source of data coming into a stream. When you call Stream.play() on the server, the server becomes the publisher. Because the server has higher priority than the client, the client is forced to unpublish from the stream if the server calls a play() method on the same stream.

If any recorded streams are included in a server playlist, you cannot play the server playlist stream as a live stream.

Note: A stream that plays from a remote server by means of the NetConnection object is considered a live stream.

You do not need to wait for "NetStatus Connection.Success" when connecting to another Flash Media Server from Server-Side Actionscript. The server waits for the connection to complete before it attempt to use the connection for Stream.play(). However, you may want to monitor the NetStatusEvent so that you can handle a failed connection.

To delete a Stream object, use the delete operator to mark the stream for deletion. The script engine deletes the object during its garbage collection routine.

// Initialize the Stream object. 
s = stream.get("foo"); 
// Play the stream. 
s.play("name", p1, ... pN);       
// Stop the stream. 
s.play(false);                                     
// Mark the Stream object for deletion during server garbage routine. 
delete s;

Availability

Flash Communication Server 1

Parameters

streamName

A string indicating the name of the stream. Use the following syntax:

File format

Syntax

Example

FLV

Specify the stream name as a string, without a filename extension.

s.play("fileName")

MP3

Specify the stream name as a string, with prefix mp3: or id3:, respectively, and without a filename extension.

s.play("mp3:fileName")

s.play("id3:fileName")

MPEG-4-based files (such as F4V, MP4)

Specify the stream name as a string with the prefix mp4:. Use a file extension if the file on the server has a file extension. The prefix indicates to the server that the file is in the MPEG-4 Part 12 container format.

s.play("mp4:fileName")

s.play("mp4:fileName.mp4")

s.play("mp4:fileName.f4v")

startTime

A number indicating the playback start time, in seconds. If no value is specified, the value is -2. If startTime is -2, the server tries to play a live stream with the name specified in streamName. If no live stream is available, the server tries to play a recorded stream with the name specified in streamName. If no recorded stream is found, the server creates a live stream with the name specified in streamName and waits for someone to publish to that stream. If startTime is -1, the server attempts to play a live stream with the name specified in streamName and waits for a publisher if no specified live stream is available. If startTime is greater than or equal to 0, the server plays the recorded stream with the name specified in streamName, starting from the time given. If no recorded stream is found, the play() method is ignored. If a negative value other than -1 is specified, the server interprets it as -2. This parameter is optional.

length

A number indicating the length of play, in seconds. For a live stream, a value of -1 plays the stream as long as the stream exists. Any positive value plays the stream for the corresponding number of seconds. For a recorded stream, a value of -1 plays the entire file, and a value of 0 returns the first video frame. Any positive number plays the stream for the corresponding number of seconds. By default, the value is -1. This parameter is optional.

reset

A boolean value, or number, that flushes the playing stream. If reset is false (0), the server maintains a playlist, and each call to Stream.play() is appended to the end of the playlist so that the next play does not start until the previous play finishes. You can use this technique to create a dynamic playlist. If reset is true (1), any playing stream stops, and the playlist is reset. By default, the value is true.

You can also specify a number 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 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 either 2 or 3 for reset returns all messages in the specified recorded stream at once, rather than at the intervals at which the messages were originally recorded (the default behavior).

remoteConnection

A NetConnection object that is used to connect to a remote server. If this parameter is provided, the requested stream plays from the remote server. This is an optional parameter.

virtualKey

A string indicating a key value. Starting with Flash Media Server 2, stream names are not always unique; you can create multiple streams with the same name, place them in different physical directories, and use the VirtualDirectory section and VirtualKeys section of the Vhost.xml file to direct clients to the appropriate stream. Because the Stream.length() method is not associated with a client, but connects to a stream on the server, you may need to specify a virtual key to identify the correct stream. For more information about keys, see Client.virtualKey. This is an optional parameter.

Returns

A boolean value: true if the call is accepted by the server; otherwise, false. If the server fails to find the stream, or if an error occurs, the Stream.play() method can fail. To get information about the Stream.play() method, define a Stream.onStatus() handler.

If the streamName parameter is false, the stream stops playing. A boolean value of true is returned if the stop succeeds; otherwise, false.

Example

The following example shows how streams can be chained between servers:

application.myRemoteConn = new NetConnection(); 
application.myRemoteConn.onStatus = function(info){ 
    trace("Connection to remote server status " + info.code + "\n"); 
    // Tell all the clients. 
    for (var i = 0; i < application.clients.length; i++){ 
        application.clients[i].call("onServerStatus", null,  
        info.code, info.description); 
    } 
}; 
// Use the NetConnection object to connect to a remote server. 
application.myRemoteConn.connect(rtmp://movie.com/movieApp); 
// Set up the server stream. 
application.myStream = Stream.get("foo"); 
if (application.myStream){ 
    application.myStream.play("Movie1", 0, -1, true, application.myRemoteConn); 
}

The following example shows how to use Stream.play() as a hub to switch between live streams and recorded streams:

// Set up the server stream. 
application.myStream = Stream.get("foo"); 
if (application.myStream){ 
    // This server stream plays "Live1",  
    // "Record1", and "Live2" for 5 seconds each. 
    application.myStream.play("Live1", -1, 5); 
    application.myStream.play("Record1", 0, 5, false); 
    application.myStream.play("Live2", -1, 5, false);  
}

The following example combines different streams into a recorded stream:

// Set up the server stream. 
application.myStream = Stream.get("foo"); 
if (application.myStream){ 
    // Like the previous example, this server stream  
    // plays "Live1", "Record1", and "Live2"  
    // for 5 seconds each. But this time,  
    // all the data will be recorded to a recorded stream "foo". 
    application.myStream.record(); 
    application.myStream.play("Live1", -1, 5); 
    application.myStream.play("Record1", 0, 5, false); 
    application.myStream.play("Live2", -1, 5, false); 
}

The following example calls Stream.play() to stop playing the stream foo:

application.myStream.play(false);

The following example creates a playlist of three MP3 files (beethoven.mp3, mozart.mp3, and chopin.mp3) and plays each file in turn over the live stream foo:

application.myStream = Stream.get("foo"); 
if(application.myStream) { 
    application.myStream.play("mp3:beethoven", 0); 
    application.myStream.play("mp3:mozart", 0, false); 
    application.myStream.play("mp3:chopin.mp3", 0, false); 
    application.myStream.play("mp4:file1.mp4", -1, 5, false); 
}

The following example plays F4V files:

application.myStream = Stream.get("foo"); 
if(application.myStream) { 
    application.myStream.play("mp4:beethoven", 0); 
    application.myStream.play("mp4:mozart", 0, false); 
}

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

application.myStream = Stream.get("data"); 
if (application.myStream) { 
    application.myStream.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:

application.myStream = Stream.get("data"); 
if (application.myStream) { 
    application.myStream.play("log", 0, -1, 2); 
}

A server-side stream cannot subscribe to itself. For example, the following code is invalid:

// Client-side code 
var ns = new NetStream 
ns.publish("TestStream"); 
 
// Server-side code 
st = Stream.get("TestStream"); 
st.play("TestStream");

Stream.publishQueryString

myStream.publishQueryString

The query string specified in the stream path when the stream was published.

Use the Stream.publishQueryString, Stream.maxQueueDelay, and Stream.maxQueueSize properties to configure the live queue for live streams. These Server-Side ActionScript properties override the values set in the Application/StreamManager/Live/Queue/ section of the Application.xml configuration file. The live queue, also known as live aggregate messages, batches multiple messages into a single composite message to increase server performance. Dynamic streaming depends on the values of maxQueueDelay and maxQueueSize to determine when to switch to a higher or lower bitrate stream. Set maxQueueDelay to a value long enough to produce a large burst of data.

When you publish a stream, you can specify a query string in the stream path with parameters that specify how to configure the live queue. Access the publishQueryString property (for example, from inside the application.onPublish() function) to access the query string. Parse the string to get the configuration parameters. Use the values from the configuration parameters to set the Stream.maxQueueDelay and Stream.maxQueueSize properties.

Note: Flash Media Live Encoder 3 supports adding query strings to stream names. Earlier versions of Flash Media Encoder did not support query strings.

Availability

Flash Media Server 3.5

Example

The following client-side code publishes a stream with a query string:

ns.publish 
("exampleVideo?com.adobe.fms.maxQueueDelay=4000&com.adobe.fms.maxQueueSize=10240"); 
}

The following server-side code gets the query string, extracts the delay and size, and configures the live queue by setting the maxQueueDelay and maxQueueSize properties:

application.onPublish = function(clientObj, streamObj){ 
    trace("queryString : " + streamObj.publishQueryString); 
    // the helper function extracQueryStringArg() is defined below 
    delay = extractQueryStringArg(streamObj.pubishQueryString, "com.adobe.fms.maxQueueDelay"); 
    size = extractQueryStringArg(streamObj.publishQueryString, "com.adobe.fms.maxQueueSize"); 
    trace("old maxQueueDelay : " + streamObj.maxQueueDelay); 
    streamObj.maxQueueDelay = delay; 
    trace("new maxQueueDelay : " + streamObj.maxQueueDelay); 
    trace("old maxQueueSize : " + streamObj.maxQueueSize); 
    streamObj.maxQueueSize = size; 
    trace("new maxQueueSize : " + streamObj.maxQueueSize); 
} 
function extractQueryStringArg(queryString, arg) 
{ 
    var retVal = ""; 
    temp = arg + "="; 
    i = queryString.indexOf(temp); 
    if (i != 0) 
    { 
        temp = "&" + arg + "="; 
        i = queryString.indexOf(temp); 
    } 
    if (i != -1) 
    { 
        retVal = queryString.substr(i+temp.length); 
        i = retVal.indexOf("&"); 
        if (i != -1) 
        { 
            retVal = retVal.substr(0, i); 
        } 
    } 
    return retVal; 
}

Stream.record()

myStream.record(flag, [maxDuration, maxSize])

Records the data passing through a Stream object and creates a file of the recorded stream. You can use this method to do the following:

Call Stream.record() to record a new file or to overwrite the data in an existing file with the recorded data.
Call Stream.record("append") to append the recorded data to the end of an existing file.
Call Stream.record(false) to stop recording.

You can record or append in F4V or FLV format. Before you call the Stream.record() method, call the Stream.get() method to create a Stream object. The recording format is determined by the filename you pass to the Stream.get() method.

Note: To play or edit F4V files recorded by Flash Media Server in other tools, use the Adobe Flash Media Server F4V Post Processor tool. The tool is available at www.adobe.com/go/fms_tools.

When you record a stream, the server creates a file with the name you passed to the Stream.get() method. The server automatically creates a “streams” directory and subdirectories for each application instance name. If a stream isn’t associated with an application instance, it is stored in a subdirectory called “_definst_” (default instance). For example, a stream from the default lecture application instance would be stored here: applications\lectures\streams\_definst_. A stream from the monday lectures application instance would be stored here: applications\lectures\streams\monday.

To append a live stream to a file, the stream name passed to the Stream.get() method must be different from the live stream name in the client NetStream.publish() method. In other cases, the client-side and server-side Stream names can be the same.

Availability

Flash Communication Server 1

Parameters

flag: One of these values: "record", "append", or false. If the value is "record", the data file is overwritten if it exists. If the value is "append", the incoming data is appended to the end of the existing file. If the value is false, any previous recording stops. The default value is "record".
maxDuration: On optional parameter specifying the maximum duration (in seconds) for a recording. When the published stream exceeds this duration, the recording stops and a “NetStream.Record.Stop” status message is sent to the stream's onStatus handler. Setting this parameter overrides the MaxDuration element in the Application.xml configuration file. However, you cannot exceed the cap set in the MaxDurationCap element. Set this parameter to -1 to specify no limit to the duration of the recording. The default value is -1.
Note: If a live event goes beyond the value in the maxDuration or maxSize parameters, recording stops. When recording stops the server passes the "NetStream.Record.DiskQuotaExceeded" status message to the NetStream.onStatus() method before the "NetStream.Record.Stop" status message.
maxSize: On optional parameter specifying the maximum size (in kilobytes) for a recording. When the published stream exceeds this size, the recording stops and a "NetStream.Record.Stop" status message is sent to the stream's onStatus handler. Setting this parameter overrides the MaxSize element in the Application.xml configuration file. However, you cannot exceed the cap set in the MaxSizeCap element. Set this parameter to -1 to specify no limit to the size of the recording. The default value is -1.

Returns

A boolean value of true if the recording succeeds; otherwise, false.

Example

The following example shows a client publishing a live stream, a server recording the stream, and a client subscribing to the recorded stream.

First, the client publishes a live stream:

myNetStream.publish("clientStream", "live");

Next, the server opens a stream named serverStream and stores it in the Stream object s. The server-side code plays and records the stream published by the client in F4V format. The name of the recorded file is “serverStream.f4v”, which is the name passed to the Stream.get() method.

//Start recording 
s = Stream.get("mp4:serverStream.f4v"); 
if (s){ 
    s.record(); 
    s.play("clientStream"); 
} 
// Stop recording. 
s = Stream.get("serverStream"); 
if (s){ 
    s.record(false); 
}

Clients can use client-side code to subscribe to the live stream that was published by the client and recorded on the server:

someNetStream.play("mp4:serverStream.f4v");

Stream.send()

myStream.send(handlerName, [p1, ..., pN])

Invokes a remote method on a client-side NetStream object subscribing to the stream and passes it parameters of any ActionScript data type. The server does not receive a response object, and any values returned by the client-side method are discarded.

You can call Stream.send() to send data over to clients subscribing to a stream. The data is passed in the p1,..., pN parameters to the handlerName method, which is defined on the subscribing stream. Publishing streams do not receive remote method calls, even if they define a method called handlerName().

You can call Stream.send() to send metadata to clients subscribing to a live stream in a data keyframe. When a client subscribes to a live stream after it starts playing, the client may not receive the stream’s metadata. This metadata can contain any information about the stream that you want the client to know, such as the length, the name of the speaker, and the location of the broadcast.

A data keyframe is a special data message that can be added to a live stream and stored in the memory of the server. The data keyframe is retrieved when a client subscribes to the stream. There are two reserved values that tell the server to set or clear a data keyframe: @setDataFrame and @clearDataFrame. Like other data messages, a data keyframe contains a handler name and a list of parameters. Use the following syntax to set or clear a data keyframe:

Stream.send("@setDataFrame", handlerName [, p1, p2, ..., pN ]);

You can send multiple data keyframes for each live stream. However, the handler name of the data keyframe must be unique. Only the stream’s publisher and the server are allowed to set and clear data keyframes. You can call the client-side ActionScript NetStream.send() method or the Server-Side ActionScript Stream.send() method to set a data keyframe in a stream. Setting data keyframes is supported in Flash Media Interactive Server 3 and Flash Media Development Server 3 and later.

Note: The server does not need to take ownership of a stream from the client in order to send a message. After send() is called, the client still owns the stream as a publisher. This is different from how the Stream.play() method behaves.

Availability

Flash Communication Server 1

Parameters

handlerName: A string indicating the remote method to call on the client. The handlerName value is the name of a method relative to the subscribing Stream object. For example, if handlerName is doSomething, the doSomething method at the stream level is invoked with all the p1, ..., pN parameters. Unlike the method names in Client.call() and NetConnection.call(), the handler name can be only one level deep (that is, it cannot have the form object/method).
Note: Do not use a built-in method name for a handler name. For example, if the handler name is close, the subscribing stream will close.
p1, ..., pN: Parameters of any ActionScript type, including references to other ActionScript objects. These parameters are passed to the specified handler when it is executed on the Flash client.

Returns

A boolean value of true if the message was sent to the client; otherwise, false.

Example

The following example calls the onMsg() method on the client-side NetStream object and sends it the string "Hello World":

s = Stream.get("testStream"); 
s.send("onMsg", "Hello World");

The following client-side ActionScript defines the method that handles the data passed on the testStream stream:

ns = new NetStream(nc); 
ns.onMsg = function(str) { 
    trace(str); //"Hello World" is output 
} 
ns.play("testStream", -2, -1, 3);

The following example adds metadata to a live stream:

s = new Stream(nc); 
s.onStatus = function(info){ 
    if (info.code == "NetStream.Publish.Start"){ 
        metaData = new Object(); 
        metaData.title = "myStream"; 
        metaData.width = 400; 
        metaData.height = 200; 
        this.send("@setDataFrame", "onMetaData", metaData); 
    } 
}; 
s.publish("myStream");

Stream.setBufferTime()

myStream.setBufferTime()

Sets the length of the message queue. When you play a stream from a remote server, the Stream.setBufferTime() method sends a message to the remote server that adjusts the length of the message queue. The default length of the message queue is 0 seconds. You should set the buffer time higher when playing a high-quality recorded stream over a low-bandwidth network.

When a user clicks a seek button in an application, buffered packets are sent to the server. The buffered seeking in a Flash Media Server application occurs on the server; Flash Media Server doesn’t support client-side buffering. The seek time can be smaller or larger than the buffer size, and it has no direct relationship to the buffer size. Every time the server receives a seek request from Flash Player, it clears the message queue on the server. The server tries to seek to the desired position and starts filling the queue again. At the same time, Flash Player also clears its own buffer after a seek request, and the buffer is eventually filled after the server starts sending the new messages.

Availability

Flash Communication Server 1

Stream.setVirtualPath()

myStream.setVirtualPath(virtualPath, directory, virtualKey)

Sets the virtual directory path for video stream playback. Maps a virtual directory path to a physical directory and assigns that mapping to a virtual key. The virtual key designates a range of Flash Player versions. These mappings let you use the same URL to serve different versions of streams to clients based on the Flash Player version.

First, create a mapping between Flash Player versions and virtual keys in the VirtualKeys section of the Vhost.xml file. When Flash Player requests a stream from Flash Media Interactive Server, the Flash Player version is mapped to a virtual key based on the values that you set in the Vhost.xml file, as in this example:

<VirtualKeys> 
    <!-- Create your own ranges and key values.    --> 
    <!-- You can create as many Key elements as you need.    --> 
    <Key from="WIN 8,0,0,0" to="WIN 9,0,59,0">A</Key> 
    <Key from="WIN 6,0,0,0" to="WIN 7,0,55,0">B</Key> 
</VirtualKeys>

Next, in the VirtualDirectory section of the Vhost.xml file, map the virtual keys to a virtual path and a physical directory, which are separated by a semicolon (for example, foo;c:\streams). To set up several virtual directories for different Flash Player versions, use the same virtual path with different physical directories for each Streams tag, as shown in this example:

<VirtualDirectory> 
    <Streams key="A">foo;c:\streams\on2</Streams> 
    <Streams key="B">foo;c:\streams\sorenson</Streams> 
</VirtualDirectory>

Flash Media Interactive Server serves the client a stream from whichever virtual directory the virtual key is mapped to. For example, if the client is Flash Player 8 and the call is myNetStream.play("foo/familyVideo"), the Streams element with key A would be used and the client would be served the higher-quality stream c:\streams\on2\familyVideo.flv. If the client is Flash Player 7, the same URL maps to the sorenson stream directory and the c:\streams\sorenson\familyVideo.flv file plays.

It is most common to change the values of the VirtualKeys and VirtualDirectory elements in the Vhost.xml file. However, you can call Stream.setVirtualPath() to create Streams elements and you can use Client.virtualKey to set a client’s Key value.

Availability

Flash Media Server 2

Parameters

virtualPath: A string indicating the virtual directory path of a stream. If the stream is not located in the virtual path, the default virtual directory path is searched.
directory: A string indicating the physical directory in which to store streams.
virtualKey: A string that sets or removes the key value for each Streams entry.
Note: To indicate a slash in the virtualPath and directory parameters, you must use a forward slash (/) or a double backslash (\\). In strings, single backslashes are used to escape characters. A double backslash is the escape sequence for a backslash character.

Example

The following code sets the virtual key to B, the virtual path to foo, and the physical directory to c:\streams\on2:

Stream.setVirtualPath("foo", "c:/streams/on2", "B");

Stream.size()

Stream.size(name[, virtualKey])

Static; returns the size of a recorded stream in bytes.

Availability

Flash Media Server 2

Parameters

name: A string indicating the name of a stream. You can use the format tag in the name parameter to specify the type.
virtualKey: A string indicating a key value. Starting with Flash Media Server 2, stream names are not always unique; you can create multiple streams with the same name, place them in different physical directories, and use the VirtualDirectory section and VirtualKeys section of the Vhost.xml file to direct clients to the appropriate stream. Because the Stream.size() method is not associated with a client, but connects to a stream on the server, you may need to specify a virtual key to identify the correct stream. For more information about keys, see Client.virtualKey. This parameter is optional.

Returns

A number; if the requested stream is not found, returns 0.

Example

The following examples display the size of a stream and an MP3 and F4V stream, respectively:

function onProcessCmd(cmd){ 
    // Insert code here... 
    var streamSize = Stream.size("foo"); 
    trace("Size: " + streamSize + "\n"); 
} 
 
//For MP3 files 
 
function onProcessCmd(cmd){ 
    // Insert code here... 
    var streamSize = Stream.size("mp3:foo" ); 
    trace("Size: " + streamSize + "\n"); 
} 
//For F4V files 
 
function onProcessCmd(cmd){ 
    // Insert code here... 
    var streamSize = Stream.size("mp4:foo"); 
    trace("Size: " + streamSize + "\n"); 
}

Stream.syncWrite

myStream.syncWrite

A boolean value that controls when a stream writes the contents of the buffer to a file as the stream is recording. When syncWrite is true, all the messages that pass through the stream are flushed to the file immediately. It is highly recommended that you set syncWrite to true only in a stream that contains only data. Synchronization problems may occur if syncWrite is set to true in a stream that contains data and audio, video, or some combination.

Availability

Flash Media Server 2

Example

The following example flushes data immediately to the file:

// Assume foo is a data-only stream. 
application.myStream = Stream.get("foo"); 
 
if (application.myStream){ 
    application.myStream.syncWrite = true; 
    application.myStream.record(); 
    application.myStream.send("test", "hello world");  
}

Stream.time

myStream.time

Read-only; the number of seconds the stream has been playing. This value is the timestamp of the latest frame that flowed out of the stream.

Availability

Flash Media Interactive Server 3.5 and Flash Media Development Server 3.5

Stream class

Availability

Property summary

Method summary

Event handler summary

Stream.bufferTime

Availability

Stream.clear()

Availability

Returns

Example

Stream.destroy()

Availability

Returns

Example

Stream.flush()

Availability

Returns

Example

Stream.get()

Availability

Parameters

Returns

Examples

Stream.getOnMetaData()

Availability

Parameter

Returns

Example

Stream.length()

Availability

Parameters

Returns

Example

Stream.liveEvent

Availability

Example

Stream.maxQueueDelay

Availability

Example

See also

Stream.maxQueueSize

Availability

Example

See also

Stream.name

Availability

Example

Stream.onStatus()

Availability

Parameters

Example

Stream.play()

Availability

Parameters

Returns

Example

Stream.publishQueryString

Availability

Example

See also

Stream.record()

Availability

Parameters

Returns

Example

See also

Stream.send()

Availability

Parameters

Returns

Example

Stream.setBufferTime()

Availability

Stream.setVirtualPath()

Availability

Parameters

Example

Stream.size()

Availability