The NetStream() Object, Methods, Properties, and Event

The NetStream() Object, Methods , Properties, and Event

The NetStream() object is used to connect multiple one-way streams between the Flash player and the Flash Communication Server using the NetConnection method. Consider this object as a channel inside the NetConnection. Each channel can be either sending (publishing) or receiving (subscribing to) data. You can connect as many "channels" to your server connection as your bandwidth permits . Consider the relationship of the telephone and your phone company for a moment.

You cannot connect two telephones together and expect them to work without the phone company. You need a connection and a telephone service provider. Your local telephone company redirects your connection to other telephones within their network, or it establishes a series of connections with other telephone service providers to connect a telephone in their network. The microphone in your telephone is a stream that can only send (or publish) an audio stream through the phone company to the receiving (or subscribed) phone at the other end. The earphone subscribes to a one-way stream from the phone company to allow you to listen to the sender on the other end.

Traditionally, communication over the Internet was like talking into a walkie-talkie where only one person could speak at a time. If you were not speaking, you were listening. This technique is called half-duplex. A half-duplex system shares a single stream over a connection for both sending and receiving. Communication using this technique is like raising your hand in class to ask a question. It is not a natural way for humans to communicate. The Flash Communication Server is a full-duplex system. This simply means that each person connected using this technology can talk, just like they do over the telephone.

Deploying this example using the Flash Communication Server would require two streams per Flash playerone to publish the microphone to the server, and one to receive the stream being published by another Flash player. The server would handle four streams in total with this scenario. If you have three people connected, each Flash player would handle three streams, and the server would handle six streams. Let's say that person in the three-way call has a video camera attached to their Flash player. Now each Flash player will publish two streams (one video and one audio), and receive four streams (two video and two audio) over a single connection. Getting the picture?

Just remember that a single connection can handle multiple one-way streams and you will be okay. In the next example, you will not publish streams, but set up the Flash player to play a prerecorded video from the server through one stream. More detail on publishing, subscribing, and bandwidth will be presented following the exercise.

NetStream() methods are:

.close() Removes a stream from the connection.
.setBufferTime() Determines the amount of memory used (in seconds) to preload video or audio before playing. This method is used when receiving (subscribing to) a stream from the server.
.pause() Temporarily pauses the playback of a stream.
.play() Resumes or starts playback over a stream.
.receiveAudio() Begins streaming audio to the capacity of the buffer, but does not play.
.receiveVideo() Begins streaming video to the capacity of the buffer, but does not play.
.seek() Fast forwards or rewinds the stream. When seeking a stream, the position is relative to the current position. So seeking 10 seconds would be 10 seconds from the time property.
.attachAudio() Connects a microphone to the stream when publishing to the server.
.attachVideo() Connects a camera to the stream when publishing to the server.
.publish() Begins publishing a stream. This method determines if the stream is recorded, live, or append, which will add on to an existing movie. Recorded video is stored as a FLV file within the Application/streams/instanceName folder on the server.
.send() Calls a server function using the stream when publishing.

The .setBufferTime() , .pause() , .play() , .receiveAudio() , .receiveVideo() , and .seek() methods are used with a stream subscription. The .attachAudio() , .attachVideo() , .publish() , and .send() methods are used with a stream publication.

The NetStream properties are:

.bufferLength A read-only property; contains the length of time the NetStream currently has in its buffer. The output is in seconds.
.bufferTime Declares how much buffer time is available to the NetStream.
.currentFPS A read-only property; reports the current frames per second being sent or received over a NetStream. It is read only, so you can't change it.
.time A read-only property; displays the current number of seconds the stream has been either playing or publishing. A value of 0 is set when play starts or the .close() method is called. This property is valuable for building the seek function.

The only NetStream event is OnStatus . This event will be called to handle NetStream status changes. Status changes include errors, connects, and disconnects.

Exercise 7.3: Streaming Video from the server

This exercise will open a NetConnection() to the server. Using the NetStream() object, you will stream the video you just encoded. There are two components (as always) to this exercise: the server and the Flash application. Set up the server first:

Create a new application folder in the flashCom/Applications folder on your server. Call it myVideoApp.
Create a folder called streams within the myVideoApp folder.
Create a folder called myInstance within the streams folder. This folder will be the name of the application instance used in the connect string.
Move any Flash video files you want to stream into this folder. These files must have been compressed using the Sorenson Spark or Spark Professional codec. They must be Flash video (FLV) formats.
Copy the files main.asc and Step2-MultiConnect.fla used in Chapter 6.

The source files for Chapter 6 are available for download from the book's web site, if you didn't do the exercise in Chapter 6.
Rename the MySecondApp.fla file to VideoStream.fla. Your server folder tree should now look similar to what appears in Figure 7.14.

Figure 7.14. Your videoApp folder structure and files should look like this.

When you are working with streaming video, you must define the instance as a folder within the application/streams folder and place all FLV files that are required by the application within that folder. This makes things a little trickier to manage, but it is a great security feature to ensure users access only what they should. With this in place, let's move on to building the Flash interface. In this example, we are building on the application you built in Chapter 6. The VideoStream.fla file should already have ActionScript to connect to the server and a login prompt for the user .
Open VideoStream.fla in Flash MX.
Open the Library panel (F11).
Add an embedded Video object. Click the Properties panel on the Library panel to reveal a menu. Select New Video from the list (see Figure 7.15).

Figure 7.15. Use the Library panel menu to create a new embedded Video object.

A new embedded Video object will be created in the Library.
Drag the new video on to the Flash stage.
Name the instance of the embedded Video object my_video in the Properties panel. Remember to have the Video object selected on the Flash stage to access the Properties panel. Using the suffix _video in the name will trigger the video code hints in the ActionScript Editor.
Open the ActionScript panel (F9).

Confirm the script in the panel matches Listing 7.1:

Listing 7.1 ActionScript for videoStream.fla

 // Include the Debug Class file #include "NetDebug.as" // create a new instance of the NetConnection object myConnection_nc = new NetConnection(); // handle any status changes and responses from the server myConnection_nc.onStatus =  function(info) {       trace("LEVEL: "+info.level+"  CODE: "+info.code); }; // connect the application when the login button is pressed appLogin = function () {       // Make the connection to the server       myConnection_nc.connect("rtmp:/mySecondApp/myInstance", login_txt.text);       // Connect the UI Components to the new connection       peopleList_mc.connect(myConnection_nc); }; connectionLight_mc.connect(myConnection_nc);

Change the connection string to reference the new application, myVideoApp. The line should now read:
```
 myConnection_nc.connect("rtmp:/  myVideoApp  /myInstance", login_txt.text); 
```
If you like, test the movie to ensure everything is working. When you are satisfied everything still works, go back to the ActionScript panel. Immediately below the connect line, within the appLogin function, the streaming connection will be made and attached to the Video object on the stage. You will be amazed that this will only take three lines of code!
Add a few line breaks below the myConnection_nc.connect string. All this code will be placed within the appLogin() function.
Instantiate the NetStream() object to a variable called videoIN_ns . In this command you also connect the stream to the connection, myConnection_nc . This will become the source for your video.
```
 videoIN_ns= new NetStream(myConnection_nc); 
```
Add the onStatus event handler for NetStream:
```
 videoIN_ns.onStatus = function(info){     trace("NETSTREAM LEVEL: "+ info.level + " CODE: "+ info.code); } 
```
This handler will be called whenever the status of the NetStream changes. For a complete listing of every NetStream Information Object, refer to Appendix C,"Information Objects (Server and Client) Quick Reference." This appendix contains a listing of every Information object used with communication applications.
Attach the new video source, videoIN_ns , to the embedded Video object on the stage:
```
 my_video.attachVideo(videoIN_ns); 
```
This is just like patching your TV with a video signal coming from your DVD. The attachVideo method defines where the video source is coming from.
Start playing the video stream from the server:
```
 videoIN_ns.play("Sparky"); 
```
This command tells the server which recorded file to stream. The server will expect to find the file Sparky.flv in the folder myVideoApp/streams/myInstance. The extension is assumed as .flv. There will be a default two-second buffer before the stream begins. The buffer can be changed using the .SetBufferTime() NetStream method. Buffering is important to ensure a smooth stream is accomplished. Too much buffer will consume too much RAM, too little will make the stream stall or re-buffer.
Save your movie.
Test the movie using Control, Test Movie or pressing Ctrl+Enter.

Use Listing 7.2 to compare your ActionScript.

Listing 7.2 The complete ActionScript code to connect a stream

 // Include the Debug Class file #include "NetDebug.as" // create a new instance of the NetConnection object myConnection_nc = new NetConnection(); // handle any status changes and responses from the server myConnection_nc.onStatus = function(info) {       trace("LEVEL: "+info.level+"  CODE: "+info.code); }; // connect the application when the login button is pressed appLogin = function () {       // Make the connection to the server       myConnection_nc.connect("rtmp:/myVideoApp/myInstance", login_txt.text);       videoIN_ns = new NetStream(myConnection_nc);       // Status Change Handler       videoIN_ns.onStatus = function(info){          trace("NETSTREAM LEVEL: "+ info.level + " CODE: "+ info.code);        }       // Attach the video stream to the embedded video object       my_video.attachVideo(videoIN_ns);       videoIN_ns.play("Sparky");       // Connect the UI Components to the new connection       peopleList_mc.connect(myConnection_nc); }; connectionLight_mc.connect(myConnection_nc);

When you log into your application, the ConnectionLight will turn green and the name you entered into the login will appear in the PeopleList, just like before. As soon as the connect is accepted, the videoIN_ns will connect a stream to the connection, and the server will start sending the Sparky.flv file to the player. You will see and hear the video playing on the Flash Stage just like Figure 7.16.

Figure 7.16. Your video should play within the Flash movie as soon as you log in.

graphics/07fig16.gif

You can add some simple video controls that will pause and play the stream or close it all together. You could also add a seek bar that would allow you to fast forward or rewind the stream quickly.

NetStream Roles

The NetStream you just used is called a subscriber stream. This is a stream that is in Receiver mode. The data with NetStream can flow only one way between the Flash client and server. As mentioned earlier, more than one stream per connection is possible. Exercise 7.2 used a NetStream subscription, meaning that the player was the receiver. With this situation, there is no publisher because the stream is prerecorded and stored on the server. There are basically two types of streams:

Publisher stream. The publisher stream is a sender stream. When your player publishes your camera or microphone, it sends the data to the server for distribution. The server makes the incoming stream available for subscription and connects the subscribed clients. The publisher stream can also send messages and text data to the server by calling server-side ActionScript functions. A good example might be the publisher presenting a slide show with a live video feed. The data stream could be used to advance a slide on all subscribed clients .
Subscriber stream. The subscriber stream is the receiver stream. A Flash player will use a subscriber stream to monitor video and audio distributed by the server. Text data can be sent to the subscriber from the server by calling a client-side function in the Flash application. The server needs to be invoked by an event or a publisher to send data this way.

Note

The only way multiple Flash players can connect without the Flash Communication Server is by running on the same computer using the localConnection() object. Flash clients on separate computers never connect directly, without passing through the Flash Communication Server.

The connection speed between the server and client is called bandwidth. Bandwidth is measured in bits per second. The easiest way to understand bandwidth is thinking about the connection your home computer has with its Internet provider. If you dial up using a traditional 56K modem, you are probably connecting at a bit rate of up to 56,000 bits per second, better known as 56Kbps. Cable modem or DSL connections can range from 256Kbps up to 10,000Kbps, or 10Mbps (megabits per second). Office computers are usually connected to servers through a LAN. Internal networks (LANs) usually have bandwidth between them of 10Mbps up to 100Mbps or higher.

How does all this relate to streaming? There is a direct relationship between bandwidth and the quality of the stream you can send or receive. The more bandwidth you have, the faster you will receive data. Faster connections mean you can send or receive larger files faster. File size has a relationship to the quality of video and audio. The larger the file is, the higher the quality. Smaller bandwidths cannot receive large video files fast enough to play them and must access smaller files, sacrificing quality. When a connection becomes slower due to network traffic, it is called latency. You can see this measured in the ConnectionLight UI component by clicking on it.