|
Flash Media Server Resources |
Stream classContents [Hide]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. Property summary
Method summary
Stream.bufferTimemyStream.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). Stream.clear()myStream.clear() Deletes a recorded FLV or F4V file from the server. ExampleThe 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.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. 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.
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. 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. Parameters
ExampleThe 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.maxQueueDelaymyStream.maxQueueDelay The maximum time, in milliseconds, that the live queue can delay transmitting messages. AvailabilityFlash Media Server 3.5 ExampleFor an example, see the Stream.publishQueryString property. Stream.maxQueueSizemyStream.maxQueueSize The maximum size, in bytes, that the live queue can grow to before transmitting the messages it contains. AvailabilityFlash Media Server 3.5 ExampleFor an example, see the Stream.publishQueryString property. Stream.namemyStream.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. 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. Parameters
ExampleThe 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:
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.
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;
Parameters
ReturnsA 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. ExampleThe 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.publishQueryStringmyStream.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.
AvailabilityFlash Media Server 3.5 ExampleThe 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;
}
See alsoStream.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:
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. Parameters
ExampleThe 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");
See alsoStream.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.
Parameters
ExampleThe 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. 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. Parameters
Stream.size()Stream.size(name[, virtualKey]) Static; returns the size of a recorded stream in bytes. Parameters
ExampleThe 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.syncWritemyStream.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. Stream.timemyStream.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. AvailabilityFlash Media Interactive Server 3.5 and Flash Media Development Server 3.5
|
