NetStream class

NetStream class constructor
NetStream.attach()
NetStream.bufferTime
NetStream.farID
NetStream.multicastAvailabilitySendToAll
NetStream.multicastAvailabilityUpdatePeriod
NetStream.multicastFetchPeriod
NetStream.multicastInfo
NetStream.multicastPushNeighborLimit
NetStream.multicastRelayMarginDuration
NetStream.multicastWindowDuration
NetStream.nearNonce
NetStream.onStatus()
NetStream.publish()
NetStream.send()
NetStream.setBufferTime()
NetStream.setIPMulticastPublishAddress()
NetStream.time

There are two main use cases for the NetStream class: publishing a stream to a remote Flash Media Interactive Server and publishing a stream to an RTMFP group.

A NetStream object is a channel inside a NetConnection object. Use the NetStream class to publish streams one-way through a NetConnection object. Unlike a client-side NetStream object, a server-side NetStream object can only publish streams; it cannot subscribe to a publishing stream or play a recorded stream.

Publish a stream to a remote server

Note: This use case is available in Flash Media Interactive Server 3.

Use the NetStream class to scale live broadcasting applications to support more clients. Flash Media Interactive Server can support only a certain number of subscribing clients. To increase that number, you can use the NetStream class to move traffic to remote servers while still maintaining only one client-to-server connection.

Note: To copy a stream to a remote server over RTMFP, use the following steps and pass an RTMFP protocol to the NetConnection.connect() method.

The following steps describe the workflow for publishing a stream to a remote Flash Media Interactive Server:

To create a NetConnection, call the NetConnection constructor:
```
var nc = net NetConnection();
```
To connect to an application on a remote Flash Media Interactive Server, call the connect() method:
```
nc.connect("rtmp://servername/appname/appinstancename");
```
Note: You cannot use RTMPT, RTMPE, or RTMPTE when connecting to a remote server.
To create a stream over the NetConnection, call the NetStream constructor and pass the NetConnection:
```
var ns = new NetStream(nc);
```
To publish a stream to a remote server, call publish() and pass a name for the stream.
```
ns.publish("mystream");
```
To subscribe to this stream, clients connect to the same application on the remote server. To play the stream, call the play() method and pass the stream name. The following is client-side code:
```
mynetconnection.connect("rtmp://servername/appname/appinstancename"); 
// Check for a "NetConnection.Connect.Success" message, then call play(). 
mynetstream.play("mystream");
```

Publish a stream to an RTMFP group

Note: This use case is available in Flash Media Server 4.

The following steps describe the workflow for publishing a stream to an RTMFP group:

To create a NetConnection, call the NetConnection constructor:
```
var nc = net NetConnection();
```
To connect to the server acting as the introducer for the RTMFP group, call the connect() method and connect to the server-side application:
```
nc.connect("rtmfp://localhost/appname/appinstancename");
```
Note: Remember to use the RTMFP protocol.
To create a stream over the NetConnection, call the NetStream constructor and pass the NetConnection and a GroupSpecifier:
```
var ns = new NetStream(nc, groupspecifier);
```
To publish a stream to a group, call publish() and pass a name for the stream. Stream data is routed to the RTMFP group, it is not copied at the server.
```
ns.publish("mystream");
```
To subscribe to this stream, clients call the play() method and pass the stream name. Clients receive the stream from the group, not from the server. The following is client-side code:
```
mynetstream.play("mystream");
```

Availability

Flash Media Server 3

RTMFP groups are supported in Flash Media Server 4

Property summary

Property	Description
`NetStream.bufferTime`	Read-only; indicates the number of seconds assigned to the buffer by the `NetStream.setBufferTime()` method.
`NetStream.time`	Read-only; indicates the number of seconds the stream has been publishing.

Method summary

Method	Description
`NetStream.attach()`	Attaches a data source to the NetStream object.
`NetStream.publish()`	Publishes a stream to a remote server.
`NetStream.send()`	Broadcasts a data message over a stream.
`NetStream.setBufferTime()`	Sets the size of the outgoing buffer in seconds.

Event handler summary

Event handler	Description
`NetStream.onStatus()`	Invoked every time a status change or error occurs in a NetStream Object.

NetStream class constructor

ns = new NetStream(connection[, groupspec])

Creates a stream that can be used for publishing (sending) data through the specified NetConnection object. You can create multiple streams that run simultaneously over the same connection.

To publish a stream through an RTMFP NetConnection to a group, pass a groupspecifier argument.

To publish a stream through an RTMFP NetConnection to a remote server, pass a connection argument. The NetConnection must use an RTMFP URI. Do not pass a groupspecifier argument.

Note: You cannot use the server-side NetStream class to play a stream.

Availability

Flash Media Server 3

RTMFP groups are available in Flash Media Server 4

Parameters

connection: A NetConnection object.
groupspec: (Optional) To publish or play a stream in a peer-to-peer multicast group, specify a groupspec string or a GroupSpecifier object. To create a groupspec string, call GroupSpecifier.toString().

Returns

A NetStream object if successful; otherwise, null.

Example

nc = new NetConnection(); 
nc.connect("rtmp://xyz.com/myapp"); 
ns = new NetStream(nc);

NetStream.attach()

ns.attach(stream)

Attaches a data source to the NetStream object.

Availability

Flash Media Server 3

Parameters

stream: A Stream object. If you pass false, the attached Stream object detaches from the NetStream object.

Returns

A boolean value. If the attached object is a valid data source, true; otherwise, false.

Example

myStream = Stream.get("foo"); 
ns = new NetStream(nc); 
ns.attach(myStream);

NetStream.bufferTime

ns.bufferTime

Read-only; indicates the number of seconds assigned to the buffer by the NetStream.setBufferTime() method.

Availability

Flash Media Server 3

NetStream.farID

ns.farID

(Read-only) A String identifier of the far end connected to this NetStream instance. Always returns the groupspec value used to construct the NetStream object.

Availability

Flash Media Server 4

NetStream.multicastAvailabilitySendToAll

ns.multicastAvailabilitySendToAll

A Boolean value specifying whether peer-to-peer multicast fragment availability messages are sent to all peers simultaneously once every multicastAvailabilityUpdatePeriod. The default value is false.

Availability

Flash Media Server 4

NetStream.multicastAvailabilityUpdatePeriod

ns.multicastAvailabilityUpdatePeriod

A Number specifying the interval in seconds between messages sent to peers informing them that the local node has new peer-to-peer multicast media fragments available.

If a successful RTMFP NetConnection has not been made, the default value is 0. If a successful RTMFP NetConnection has been made, the default value is 0.1. Possible values are numbers in the range [0.0, 4294967.295]. Values outside this range are compressed to fit. Negative value assignments are treated as a 0 assignment. Values larger than the upper limit for the property are truncated to the upper limit for assignment. No error is raised or warning logged when this implicit argument coercion is performed.

Availability

Flash Media Server 4

NetStream.multicastFetchPeriod

ns.multicastFetchPeriod

A Number specifying the time in seconds between when the local node first learns of the availability of a peer-to-peer multicast media fragment and when it attempts to fetch it from a peer.

If a successful RTMFP NetConnection has not been made, the default value is 0. If a successful RTMFP NetConnection has been made, the default value is 2.5. Possible values are numbers in the range [0.0, 4294967.295]. Values outside this range are compressed to fit. Negative value assignments are treated as a 0 assignment. Values larger than the upper limit for the property are truncated to the upper limit for assignment. No error is raised or warning logged when this implicit argument coercion is performed.

Availability

Flash Media Server 4

NetStream.multicastInfo

ns.multicastInfo

Read-only; A MulticastStreamInfo object whose properties contain statistics about the quality of service.

Availability

Flash Media Server 4

NetStream.multicastPushNeighborLimit

ns.multicastPushNeighborLimit

A Number specifying the maximum number of peers to which to push multicast media.

If a successful RTMFP NetConnection has not been made, the default value is 0. If a successful RTMFP NetConnection has been made, the default value is 4. Possible values are numbers in the range [0, 4294967295]. Values outside this range are compressed to fit. Negative value assignments are treated as a 0 assignment. Values larger than the upper limit for the property are truncated to the upper limit for assignment. No error is raised or warning logged when this implicit argument coercion is performed.

Availability

Flash Media Server 4

NetStream.multicastRelayMarginDuration

ns.multicastRelayMarginDuration

A Number specifying the duration in seconds that peer-to-peer multicast data remains available to send to peers that request it beyond the multicastWindowDuration.

If a successful RTMFP NetConnection has not been made, the default value is 0. If a successful RTMFP NetConnection has been made, the default value is 2. Possible values are numbers in the range [0.0, 4294967.295]. Values outside this range are compressed to fit. Negative value assignments are treated as a 0 assignment. Values larger than the upper limit for the property are truncated to the upper limit for assignment. No error is raised or warning logged when this implicit argument coercion is performed.

Availability

Flash Media Server 4

NetStream.multicastWindowDuration

ns.multicastWindowDuration

A Number specifying the duration in seconds of the peer-to-peer multicast reassembly window.

If a successful RTMFP NetConnection has not been made, the default value is 0. If a successful RTMFP NetConnection has been made, the default value is 8. Possible values are numbers in the range [0.0, 4294967.295]. Values outside this range are compressed to fit. Negative value assignments are treated as a 0 assignment. Values larger than the upper limit for the property are truncated to the upper limit for assignment. No error is raised or warning logged when this implicit argument coercion is performed.

Availability

Flash Media Server 4

NetStream.nearNonce

ns.nearNonce

(Read-only) A String chosen substantially by this end of the stream, unique to this connection. For RTMFP Group streaming this value is the empty string.

Availability

Flash Media Server 4

NetStream.onStatus()

ns.onStatus = function(infoObject){})

Invoked every time a status change or error occurs in a NetStream object.

The remote server can accept or reject a call to NetStream.publish().

Availability

Flash Media Server 3

Parameters

infoObject

An Object with code and level properties that provide information about the status of a NetStream call. Both properties are strings.

Code property	Level property	Description
`"NetStream.Connect.Success"`	`"status"`	Dispatched when a NetStream is created successfully. In Server-Side ActionScript, this status is not sent to `NetConnection.onStatus()`.
`"NetStream.Connect.Failed"`	`"error"`	Dispatched when NetStream creation or connection fails (for example, if there is an error in the GroupSpecifier).
`"NetStream.MulticastStream.Reset"`	"status"	A multicast subscription has changed focus to a different stream published with the same name in the same group. Local overrides of multicast stream parameters are lost. Reapply the local overrides or the new stream's default parameters will be used.
`"NetStream.Play.Failed"`	`"error"`	In Server-Side ActionScript, a NetStream can publish a stream to a multicast group; it cannot play a stream.
`"NetStream.Publish.BadName"`	`"error"`	An attempt was made to publish to a stream that is already being published by someone else.
`"NetStream.Publish.Failed"`	`"error"`	A call to `NetStream.publish()` was attempted and failed. For example, permission was denied.
`"NetStream.Publish.Start"`	`"status"`	An attempt to publish was successful.
"`NetStream.Record.DiskQuotaExceeded`"	`"error"`	An attempt to record a stream failed because the disk quota was exceeded. For more information, see `Stream.record()`.
`"NetStream.Record.Failed"`	`"error"`	An attempt to record a stream failed.
`"NetStream.Record.NoAccess"`	`"status"`	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"`	An attempt to stop publishing a stream was successful.

Example

ns = new NetStream(nc); 
ns.onStatus = function(info){ 
    if (info.code == "NetStream.Publish.Start"){ 
        trace("It is now publishing"); 
    } 
ns.publish("foo", "live"); 
}

NetStream.publish()

ns.publish(name, howToPublish)

Publishes a stream to a remote server. Check the status in the NetStream.onStatus() handler to make sure that the remote server has accepted the publisher. If the stream has been published by another client, the publish() call can fail when it reaches the remote server. In this case, the remote server sends a status message of "NetStream.Publish.BadName" to the NetStream.onStatus() method.

Availability

Flash Media Server 3

Parameters

name

A string identifying the stream to publish. If you pass false, the stream stops publishing. Use the following syntax:

File format

Syntax

FLV

ns.publish("filename")

MP3

ns.publish("mp3:filename")

ns.publish("id3:filename")

MP4

ns.publish("mp4:filename")

ns.publish("mp4:filename.mp4")

ns.publish("mp4:filename.f4v")

howToPublish

An optional string specifying how to publish the stream. Valid values are "record", "append", "appendWithGap", and "live". The default value is "live". If you omit this parameter or pass "live", live data is published but not recorded. If a file with this name already exists on the remote server, it is deleted.

Note: If the file is read-only, live data is published and the file is not deleted.

If you pass "record", the stream is published and the data is recorded to a new file. If the file exists, it is overwritten. If you pass "append", the stream is published and the data is appended to the existing stream specified by name. If no file is found, it is created.

If you pass "appendWithGap", additional information about time coordination is passed to help the server determine the correct transition point when dynamic streaming. For more information about using "appendWithGap", see Using DVR with dynamic streaming.

The server stores recorded files in the streams subfolder of the application’s folder, for example, RootInstall/applications/sampleapplication/_definst_/streams. The recorded file has the filename passed in the name parameter. For example, NetStream.publish ("mp4:streamname.f4v", "record") creates the file streamname.f4v.

Example

application.onPublish = function(client, myStream){ 
    nc = new NetConnection(); 
    nc.connect("rtmp://example.com/myApp"); 
    ns = new NetStream(nc); 
    ns.attach(myStream); 
    ns.publish(myStream.name, "live"); 
};

The following example shows how to record an F4V file on the remote server.

application.onPublish = function(client, myStream){ 
    nc = new NetConnection(); 
    nc.connect("rtmp://example.com/myApp"); 
    ns = new NetStream(nc); 
    ns.attach(myStream); 
    ns.publish("mp4:" + myStream.name, "record"); 
};

NetStream.send()

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

Broadcasts a data message over a stream.

Availability

Flash Media Server 3

Parameters

handlerName: A string that identifies the name of the handler to receive the message.
p1, ..., pN: Optional parameters of any type. They are serialized and sent over the connection. The receiving handler receives them in the same order.

Returns

A boolean value; true if the data message is dispatched; otherwise, false.

Example

The following client-side code broadcasts the message "Hello world" to the foo handler function on each client that is connected to myApp:

nc = new NetConnection(); 
nc.connect("rtmp://xyz.com/myApp"); 
ns = new NetStream(nc); 
ns.send("foo", "Hello world");

NetStream.setBufferTime()

ns.setBufferTime(bufferTime)

Sets the size of the outgoing buffer in seconds. If publishing, it controls the buffer in the local server.

Availability

Flash Media Server 3

Parameters

bufferTime: A number indicating the size of the outgoing buffer in seconds.

Example

nc = new NetConnection(); 
nc.connect("rtmp://xyz.com/myApp"); 
ns = new NetStream(nc); 
ns.setBufferTime(2);

NetStream.setIPMulticastPublishAddress()

ns.setIPMulticastPublishAddress(address, port)

Sets the native IP multicast address to which a stream publishes. To clear the address, pass null in the address parameter. If the port argument is null, you must specify the port within the address argument. If either the address or port values are invalid an Error is raised.

By default, a call to publish() does not use native IP multicast. Attempting to change the value while the NetStream is publishing raises an Error.

This method is for RTMFP connections only. If the NetStream is not publishing over a NetConnection that uses the RTMFP protocol, or if the NetStream wasn’t constructed with a GroupSpecifier, any assigned value is ignored.

Availability

Flash Media Server 4

Parameters

address: A String. The address of the IPv4 or IPv6 multicast group to publish to, optionally followed by a colon (“:”) and the UDP port number, or null to clear the existing value and disable native IP multicast. If specifying an IPv6 address and a port, the IPv6 address must be enclosed in square brackets. For example, "224.0.0.254", "224.0.0.254:30000", "ff03::ffff", "[ff03::ffff]:30000".
port: A Number. The UDP port on which to send native IP multicast datagrams. If port is null, the UDP port must be specified in the address parameter.

NetStream.time

ns.time

Read-only; indicates the number of seconds the stream has been publishing. This is a good indication of whether data is flowing from the source that has been set in a call to the NetStream.attach() method.

Availability

Flash Media Server 3