In addition to sending matrix data over networks, we can also create RTSP streams in Jitter, using the objects
jit.broadcast and
jit.qt.broadcast. The
jit.qt.broadcast object is only available on computers running the Mac OS, and is described at the end of this chapter. The
jit.broadcast object is cross-platform. Both objects function more or less the same way, though, and users of
jit.qt.broadcast should follow the entire chapter.
RTSP stands for
Real-Time Streaming Protocol, and is a popular network streaming standard, supported by many media players such as the QuickTime Player and VLC (you can learn more about VLC, a free, open-source, cross-platform player, at
http://www.videolan.org/vlc/). These media players are
RTSP clients. Our Max objects are RTSP
servers, and they properly format, in some cases compress, packetize and broadcast data for RTSP streaming. Using these objects, you don't need any external server — everything is done for you, all inside of Jitter!
Before we get started, you'll want to make sure that your network is properly configured. Ensure that you have a network interface active and a valid IP address. On Windows, this is particularly important, or our streaming experiments won't work.
Even if you are not connected to a network on Windows, you'll need to have at least one active network interface, as far as the OS is concerned. This might mean logging/dialing into the Internet, or attaching a powered-on router to your Ethernet port, even if you have no other computers to share with—basically, anything which causes Windows to detect that you're using the network—so that it assigns your computer an IP address.
• Click on the
message box labeled
read dishes.mov and turn on the
toggle box labeled
Start Movie to begin movie playback. You should see the movie playing in the
jit.pwindow object.
Before we begin the actual broadcast, we should consider a few things.
First, what will the dimensions of our broadcast stream be? The two arguments in the
jit.broadcast object's box determine the size of the compressed, streamed image. To change this size, the
size attribute is used. In our case, we will stream at 160x120 pixels.
Second, what streaming video codec are we going to use? The
jit.broadcast object supports 3 different ones—MPEG-4, H.263 and JPEG. Incoming Jitter frames will be automatically compressed into the chosen format before streaming.
• Using the
umenu object, choose your desired streaming codec from the 3 available.
By default, the object uses the MPEG-4 codec, but the choice is yours. Certain codecs may be easier for some clients to receive. For instance, at the time of this writing, QuickTime Player is much better at receiving MPEG-4 video than VLC.
Third, are we streaming to a single computer (known as a
unicast) or should our stream be made available to any client who accesses the URL of our stream (known as a
multicast)? By default, the
jit.broadcast object uses multicast streaming, although this can be changed using the
unicast attribute.
• Click on the
message box labeled
getvip and note the output in the Max Window. When multicasting, the
jit.broadcast object automatically generates a valid multicast IP address. Click on the
toggle labeled
Enable Unicast and click the
message box labeled
getvip again, noting the output in the Max Window. The IP address changed to
127.0.0.1 (this address is also known as
localhost, and means "myself"—using this IP address, the computer would broadcast to itself). Using the
vip attribute, we could now manually set the IP address of the (single) client computer (you can't change the
vip attribute when multicasting, since it's generated automatically). For the purposes of this tutorial, we're going to stick to multicasting, but it's important to note that both methods are available.
There are a number of additional parameters which we can set to control the broadcast, such as port numbers, time-to-live (TTL), codec quality and keyframe-generation, and so on. By default, those values are all set to perfectly functional defaults, and there's no need to change them for this Tutorial.
Finally, what should we name our stream? The
jit.broadcast object produces a URL for client computers to access, in the form
rtsp://192.168.2.2:8554/jitStream. The IP address and port numbers are generated for us, but we could change the last part to our liking. For instance, we could name our RTSP stream
someDishes.
• Click on the
message box labeled
streamname someDishes. This will customize our stream's name.
• Click on the
message box labeled
start to begin streaming. When streaming has successfully begun, the message
start, followed by a
1, then the RTSP URL (e.g.
start 1 rtsp://192.168.2.2:8554/someDishes) should appear in the Max Window. This last part is the address that client computers should connect to, in order to receive your stream.
Router Users: Note that if your computer is behind a router providing a local IP address (using NAT, for instance), the RTSP URL will refer to your local IP address, not your "real" IP address (WAN address), as would be accessed from computers outside of your local network. To learn your WAN address, you can point your web browser to
http://checkip.dyndns.org/ (merely one example from many similar websites). You'll substitute this address for the numerical portion of the RTSP URL before the colon. In the example above, the WAN address would take the place of
192.168.2.2.
Most routers have built-in firewalls. In order to properly stream from Jitter, be aware that the RTSP port (the portion of the RTSP URL after the colon, but before the forward-slash; here, 8554) will have to be unblocked, and any network traffic to that port must be directed to your computer. Consult the manual of your router if you are unsure how to do this.
• If you have a 2nd computer on your network, use a web browser or media player on that computer (such as QuickTime Player or VLC) to connect to the URL printed in the Max Window. Or call a friend and ask them to try it over the Internet. Or, if you have neither a 2nd computer nor available friends, you can fire up a copy of a web browser or media player on the same machine Jitter is running on to see your stream.
If it didn't work, check the IP address in the RTSP URL. If the address is
0.0.0.0, this means you've got a network configuration problem on your server machine. Click the
message box labeled
stop, make sure that you're connected to a network and click the
message box labeled
start again.
• When you've confirmed that it's all working, click the
message box labeled
stop. You might want to try some more broadcasting using different codecs and compare image quality and performance.
Using the
jit.broadcast object, we can also stream pre-compressed Hinted Movie files as created by QuickTime. The
jit.qt.movie object can export Hinted Movie files, so let's use it to export and hint our
dishes.mov file, preparing it for broadcast.
Hinted Movie files contain extra information about the contents of the movie tracks, providing "hints" to a streaming server about codecs and quality, so that the server only has to worry about packetizing and broadcasting the data. In the case of
jit.broadcast, since the object needn't compress incoming frames, streaming a Hinted Movie might offer a modest performance improvement, depending on your media.
We first need to tell the
jit.broadcast object that we want to stream a movie file, rather than incoming matrix data. This is accomplished by setting the object's
mode attribute.
• Turn on the
toggle labeled
Matrix / File to set the
jit.broadcast object's
mode attribute to 1—file broadcast mode.
We use the
export message to
jit.qt.movie to create a Hinted Movie. You may want to refer to
Tutorial 20: Importing and Exporting Single Matrices if you want to refresh your memory about movie exporting.
• Click on the
message box labeled
export fulldialog. This brings up the ‘Export’ dialog box for the movie loaded into
jit.qt.movie (in our case,
dishes.mov).
The QuickTime export dialog box on Mac OS X.
• Chose Movie to QuickTime Movie from the pop-up menu labeled Export, beneath the file browser section of the dialog box. Although there is a selection called Movie to Hinted Movie, it doesn't recompress a movie's media, which we want to do.
• Click the button labeled Options... to open the Movie Settings dialog box.
The Movie Settings dialog box on Mac OS X.
• Make sure that the Video check box has been checked and click on the button labeled Settings... just beneath it to open the Standard Video Compression Settings dialog box. Choose MPEG-4 Video from the pop-up menu labeled Compression Type and then click OK to return to the Movie Settings dialog box. Make sure that the check box labeled Prepare for Internet Streaming is checked, and that Hinted Streaming is selected in the pop-up menu directly beneath. Click OK when you're done, to return to the Export dialog box.
• Choose a location to save your Hinted Movie and a name, and click the Save button to write the movie to a file on your hard disk.
Good work! We're almost ready to stream the movie. In the case of a Hinted Movie, the
vcodec attribute (or related information such as the
spatialquality,
temporalquality or
kframe attributes) to
jit.broadcast has no effect—all of that information is already provided by the movie itself. All we need to do is tell the
jit.broadcast object which movie to stream.
• Click the
message box labeled
movie to bring up a standard file dialog box, navigate to the location of your newly saved Hinted Movie and open it. A message should be posted to the Max Window with the
filename of your movie followed by the number
1, indicating that the movie was read successfully.
• Press the
message box labeled
start to begin broadcasting. Just like before, a message with the RTSP URL will be output from the object's dump outlet and posted to the Max Window. Verify with a media player or web browser that the movie is streaming.
• When you're done, click the
message box labeled
stop to stop the broadcast.
In most respects, the
jit.qt.broadcast object functions identically to its companion
jit.broadcast object. There are a few significant differences between the 2 objects, though:
• The
jit.qt.broadcast object uses Session Description Protocol (
SDP) files, instead of an "automatic" session announcement, when making a stream available.
• The
jit.qt.broadcast object can stream several more codecs than the
jit.broadcast object.
• The
jit.qt.broadcast object can stream audio and/or video from Hinted Movie files, not just video.
• The
jit.qt.broadcast object can stream audio and/or video from an attached camera.
The interested learner can consult the on-line Reference and help patch for the
jit.qt.broadcast object to learn about streaming from a camera. For this tutorial, we're simply going to go through the process of generating an SDP file and starting a video-only broadcast based on incoming Jitter matrices.
Session Description Protocol files simply provide some basic data to RTSP clients about how many tracks are being streamed, some information about how they are encoded, and where in the network or internet the client should look for the actual streaming data (the SDP file needn't be located at the source of the data). The
jit.qt.broadcast object automatically generates these files, based on how the broadcast's codec, size, etc. have been set in the object. By making this file available to RTSP clients—emailing the file to friends, posting a link to the file on a web site, etc.—you can publicize your stream.
• If the tutorial patch
53jBroadcasting.pat is still open, close it now. Then open the tutorial patch
53jQTBroadcasting from the Jitter Tutorials folder. As you can see, the patches look very similar. Just as in the previous patch, the 2 arguments to our broadcast object determine the dimensions of the broadcast stream.
• Click on the
message box labeled
read dishes.mov and turn on the
toggle labeled
Start Movie to begin movie playback. You should see the movie playing in the
jit.pwindow object.
• If you like, make a selection from the
umenu labeled
Codec. The default video codec, H.263, should be already selected. Note that we have access to all of the standard video codecs available in QuickTime.
Some codecs are much better suited for streaming than others. H.261, H.263, MPEG-4 and Photo-JPEG are reasonably common. Other codecs can be used, but may not offer acceptable image quality or performance, streamed over a network.
• Click on the
message box labeled
write. A standard file dialog box will open, where you can choose the name and location for the SDP file that describes your broadcast stream. Click
OK to save the file.
The SDP file is now configured for your broadcast, as it is currently set up. If you make any changes—a change from multicast to unicast, or to a new codec—you will need to write a new SDP file.
• Click on the
message box labeled
start to begin streaming.
• If you have a 2nd computer on your network, use a web browser or media player on that computer (such as QuickTime Player or VLC) to open the SDP file (you will need to transfer the file to the other machine somehow). Or email the SDP file to a friend and ask them to try it over the Internet. Or, if you have neither a 2nd computer nor available friends, you can open the file in a local web browser or media player and try it out yourself.
• Click on the
message box labeled
stop to end the broadcast.
In this chapter, we learned how to use the
jit.broadcast and
jit.qt.broadcast objects to serve RTSP (
Real-Time Streaming Protocol) streams directly out of Jitter, using different codecs and different methods of session announcement. We also learned how to export Hinted Movies from the
jit.qt.movie object.