Streaming Live Events with QuickTime Broadcaster

Installing and Using Darwin Streaming Server

The first step to streaming is, obviously, installing the Darwin Streaming Server. DSS enables the streaming of prerecorded content and playlists the backbone of all streaming services.

Installing DSS

To install Darwin Streaming Server, download the latest package from the Apple QuickTime Streaming Server page: http://developer.apple.com/darwin/projects/streaming/. An installer-packaged binary is available for Mac OS X, so just double-click and follow the onscreen directions.

When the installation has finished, Installer will launch your web browser to complete the setup. DSS is configured and administered through a web interface; the first step is creating an administrative username and password, as seen in Figure 25.2. These credentials are not tied, in any way, to a Tiger username or password.

Figure 25.2. After installation has been completed, your web browser will be launched and setup will begin.

NOTE

If your browser is not launched automatically, open Safari (or another browser) and load the URL http://127.0.0.1:1220/parse_xml.cgi?filename=setup_assistant2.html. The administrative interface lives on port 1220 of your computer.

After entering a unique username and password, click Next. The web setup assistant will prompt for an MP3 broadcast password this is a password required for broadcasting to another server, not an end user MP3 client, such as iTunes or Winamp. Again, choose a unique password and click Next.

Now you will be prompted whether to use SSL (Secure Sockets Layer) to encrypt the administrative control connection. If you're concerned about someone sniffing your password and reconfiguring your server to stream their illicit wares, enabling this is a good idea. To use SSL, however, you must also obtain a certificate signed by a CA (Certificate Authority) and install it as /Library/QuickTimeStreaming/streamingadminserver.pem. You can do this using the Certificate Assistant in Keychain Access (refer to Chapter 2, "Useful Tiger Widgets, Applications, and Utilities"), or by following the excellent instructions at http://geeklog.afp548.com/article.php?story=20040722080720854.

After you've made your selection, click Next to continue.

Next, the setup assistant will ask where your media files are stored; the default, /Library/QuickTimeStreaming/Movies/, should be sufficient (see Figure 25.3).

Figure 25.3. Choose where your media files are stored.

Finally, you will be asked whether streaming is enabled over port 80.

Although it might seem like a good idea to enable this by default, be aware that streaming over port 80 will not coexist with standard web services also running on port 80. If you need to run a web server on the same machine as your DSS, do not enable port 80 streaming in this step. Click Finish to complete the initial setup of Darwin Streaming Server.

TIP

You can always change these settings at any time in the future, so don't worry about making a mistake now.

Your browser should refresh to display the main administrative control page for DSS, as demonstrated in Figure 25.4. From here you can quickly view the vital statistics of your server: how long it has been running, how much traffic it has received, and how much processor time it is taking. You can reach this page at any time from the URL http://127.0.0.1:1220/.

Figure 25.4. Enter the RTSP URL for a sample media file.

Disabling DSS

DSS starts automatically each time you boot your computer. This is triggered by the QuickTimeStreamingServer StartupItem, located in /System/Library/StartupItems/. To disable DSS, either remove the StartupItem or edit /etc/hostconfig, looking for these two lines:

 QTSSWEBADMIN=-YES- QTSSRUNSERVER=-YES- 

Setting both lines to -NO- will disable DSS and its web-based administrative interface.

Testing Your Darwin Streaming Server Installation

When you installed DSS, several sample files were included in the installation process. Assuming that you used the default media directory (/Library/QuickTimeStreaming/Movies), you should see something like this:

 $ ls -al /Library/QuickTimeStreaming/Movies/ total 19880 drwxrwxr-x   7 qtss  admin      238 12 Dec 23:17 . drwxrwxr-x  10 qtss  admin      340 12 Dec 23:17 .. -rw-rw-r--   1 qtss  admin  1789985 18 Feb  2004 sample.mp3 -rw-rw-r--   1 qtss  admin  1090897 18 Feb  2004 sample_100kbit.mov -rw-rw-r--   1 qtss  admin   947775 18 Feb  2004 sample_100kbit.mp4 -rw-rw-r--   1 qtss  admin  2990345 18 Feb  2004 sample_300kbit.mov -rw-rw-r--   1 qtss  admin  3344372 18 Feb  2004 sample_300kbit.mp4 

To test your server, open the QuickTime Player, and then choose File, Open URL in New Player. You will be prompted for a URL; enter a string formatted as rtsp://<your DSS name or IP>/<Media filename>, as shown in Figure 25.4.

After a few seconds, the media clip should start streaming to your player. The sample videos included with DSS consist (at the time of this writing and quite awhile before that) of a repeating animation of the QuickTime logo if that's what you see, you're in good shape.

TIP

If you do not see the video, make sure that the Tiger firewall is disabled and that you are not attempting to stream over port 80 while running Personal Web Sharing. I've found that a reboot is also required after installing the server even though it appears to be running correctly after the setup assistant has finished.

TIP

By default, only the /Library/QuickTimeStreaming/Movies directory is enabled for streaming. If you want to provide streaming services for users from their ~/Sites directory, use the createuserstreamingdir <username> script provided in the /Library/QuickTimeStreaming/ Config/ directory. For example, to add a Streaming directory to my (jray) Sites directory, I could do the following:

 $ sudo /Library/QuickTimeStreaming/Config/createuserstreamingdir jray examining the home directory for ~jray home directory path = /Users/jray /Users/jray/Sites/Streaming is ready for streaming. 

Preparing Media for Streaming

With Darwin Streaming Server installed, you're ready to begin publishing streaming videos. Unfortunately, you can't just add a file to the /Library/QuickTimeStreaming/Movies directory and expect DSS to serve it properly. Only movie files that have been hinted can be streamed. Hinting stores the necessary information in the movie file (called a hint track) so that DSS knows how to handle the interactions during streaming without needing to process the video itself.

NOTE

MP3 files do not require hinting to be streamed. All other .mov or MPEG-4 files must be hinted.

There are several ways you can hint your movie files. The first and easiest method is to use iMovie HD's Share feature: Select QuickTime, and then choose Web Streaming, as shown in Figure 25.5. Doing so will reduce the framerate and size of the video to what Apple considers acceptable presumably for streaming from a .Mac account.

Figure 25.5. iMovie can quickly save a project in a stream-ready format.

The resultant hinted file can be saved to the streaming media directory and used immediately.

Exporting with the Default Codec

If you want more control over the export process, you can use either the Expert QuickTime Sharing option (File, Share, QuickTime) within iMovie HD, or use the Pro (registered) version of QuickTime Player to accomplish the same thing (File, Share).

When exporting manually in this manner, you should see an Export pop-up menu with the option Movie to Hinted Movie. Selecting this option and clicking Save, as demonstrated in Figure 25.6, will create a hinted movie without re-encoding the movie or changing any of its original characteristics.

Figure 25.6. You can quickly created a hinted version of an existing media file.

To optimize the hinted movie, click Options. The Hint Exporter Settings will be displayed, as shown in Figure 25.6. Unless you have very limited storage, be sure to enable the Optimize Hints for Server checkbox. This will result in a significantly larger movie file, but one that can be dealt with more efficiently by the server, enabling higher throughput and responsiveness.

From this dialog, you can also disable the audio or video tracks for the stream and configure several Track Hinter settings. The Hinter settings are used to force a packet size and duration for the resulting movie file. If you know the characteristics of your target network, you can change these values appropriately. The defaults, however (typically 1450 bytes and 100ms), should be sufficient for most clients connected via cable and xDSL or faster.

NOTE

The Track Hinter settings also enable you to change the RTP payload encoding (that is, how the video and audio tracks will be encoded). You can choose between the native encoder of the codec and a generic QuickTime encoder. Unless the codec documentation states otherwise, you should always use native encoding.

The trouble with exporting to a hinted file without re-encoding is that many movie files might not be appropriate for streaming. Assuming that the video is the product of an iMovie or an import from your video camera, it is likely in a straight DV (digital video) format and at a much higher resolution than what is appropriate for network streaming.

For the greatest compatibility, you should export the video to a format that is bandwidth friendly and compatible with as many playback devices and software products as possible: MPEG-4. MPEG-4 is an international standard created by the Motion Picture Experts Group and supported natively by many popular audio/video frameworks on Windows, Linux, and (obviously), the Macintosh platform. Extensive information about MPEG-4 is available at http://www.m4if.org/.

TIP

Regardless of the codec used, a single media file is unlikely to satisfy all of your potential customers. QuickTime supports the use of reference movies to automatically choose between different movie files depending on connection speed and other criteria. You'll learn about this shortly in the "Adapting to the Client with Reference Movies" section, later in this chapter.

Exporting to MPEG-4

Although you can certainly choose any QuickTime codec you like for streaming, you'll probably want to research the codec to determine the quality versus bandwidth trade-offs, CPU usage, viable resolutions, and so on. The MPEG-4 codec, on the other hand, was designed with streaming in mind and provides immediate feedback on your quality choices and whether they will be feasible in your deployment environment.

To export to MPEG-4, use iMovie HD's QuickTime Sharing Expert settings, or with the movie opened in QuickTime Player, choose File, Export. When prompted for the Export format, choose Movie to MPEG-4. You can then choose from several predefined output options (ranging from modem to LAN) in the Use pop-up menu, shown in Figure 25.7, or click Options for more choices.

Figure 25.7. Several predefined settings are available.

The manually defined options provide a greater range of bandwidth control over the exported video. There are three areas within the Settings pane: Video, Audio, and Streaming.

Video Select the framerate and bitrate (kbits/second) for the video track. Also choose between Improved and Basic video encoding for good quality or greatest compatibility, respectively. Also available is H.264 encoding the new standard for the highest-quality streams.

Audio Choose the bitrate (kbits/second) for the audio track and encoding quality settings.

Streaming Enable hinting for the file by clicking the Enable Streaming button. Choose the Optimized for Server setting for best results with DSS. If you know the specifics of your client's network, you can also adjust the packet size and duration. The defaults should be appropriate for ethernet, cable, and most xDSL deployments.

As you adjust the MPEG-4 settings, you'll notice that the bottom portion of the window updates to reflect the results of your changes. By default, QuickTime will try to conform to the ISMA (Internet Streaming Media Alliance) specifications for compatibility. Changes to the settings that violate the compatibility will be shown in this status area.

Your best strategy when setting up the MPEG-4 encoder is to conform to the ISMA standards. The Basic video track settings conform to ISMA Profile 0, enabling the widest range of device playback and compatibility. The Improved video settings use ISMA Profile 1, which trades some compatibility for quality.

If you want to provide higher-quality video than allowed by Profile 1, you should disable ISMA compatibility by choosing MP4 from the pop-up menu at the top of the window. Adjust the audio and video bitrate (and, subsequently, quality) while paying close attention to the messages provided at the bottom of the pane. The status will update to show the connection type that your settings will work with. Figure 25.8, for example, shows the results of settings that will stream correctly over a T1 line only. Reducing the video and/or audio bitrates reduces the requirements for the receiver.

Figure 25.8. Choose the best bitrate for the connection type and quality you want to achieve.

NOTE

Apple recommends not exceeding 75% of the bitrate of the client connection. The MPEG-4 settings are a bit more lenient, but a conservative approach to bandwidth utilization will yield the best results.

After choosing your settings, click Okay, and then choose Save to export your hinted stream-ready MPEG-4 file.

Adapting to the Client with Reference Movies

For streaming to be effective, a movie must be matched with a client's available bandwidth. To this point we've only looked at how single movies can be prepared for streaming. With a captive audience (a corporate Intranet or home network), this isn't a problem. When you have clients coming in over dial-in connections and different levels of broadband, using slow and fast CPUs, a single stream won't serve the audience effectively. Furthermore, although you can certainly create different stream-ready files for different users, asking them to choose which is appropriate for them is unreasonable.

In this situation, a reference movie can be created that uses factors such as connection speed, language, CPU Speed, and QuickTime version to determine automatically which stream is suited for a given client. Slower CPUs, for example, might be served a Sorenson-compressed .mov stream, whereas more capable modern machines would receive an MPEG-4.

The first step in creating a reference movie is to identify and export hinted files for all the combinations that you want to support based on the attributes of connection speed, language, CPU speed, and QuickTime version. You will also want to create a default movie that will be compatible with all players, regardless of the client attributes. After they've been created, these hinted movies should be saved in a common folder.

Your next step is to create the reference movie itself. Although this file ends in a .mov prefix, it is nothing more than a text file that lists media files and attributes. Even though it's possible to create the reference movie by hand, Apple offers a free tool MakeRefMovie X that can build the file with a simple drag-and-drop interface. Download the application from http://developer.apple.com/quicktime/quicktimeintro/tools/index.html.

To build the reference movie, start MakeRefMovie X. When prompted for a filename, choose the name of the .mov reference file that you want to create. From the client's perspective, this will be the file they are viewing; the server will deliver the correct file based on the selection criteria in the reference movie.

After you've named the file, the MakeXRef window will appear. Drag the media files you want to use into the window; they will be added to a resource listing, as shown in Figure 25.9.

Figure 25.9. Add your media files to the reference movie.

For each file you've added, you can use the pop-up menus corresponding to that file's listing to set the viewing criteria. As mentioned previously, this includes network speed, language, CPU speed, and QuickTime version.

After you've chosen the files' attributes, you should also use the Priority pop-up menu to set your preferred movie order (first choice, second choice, and so on); this will serve as the final selection criteria if multiple movies match a given client's configuration.

Finally, choose your default movie (the movie that should be playable on any system configuration) by clicking the Flatten into Output button. Save your final reference movie by choosing File, Save. The resultant file should be stored in the same directory as the files it references and can be streamed like any other .mov the difference being that it will adjust its output to accommodate the client's capabilities.

Applying Access Controls to Your Media

There is a level of security inherent within streaming video: Viewers cannot easily save the media coming from the streaming server. There are a few ways to get around this, but it is unlikely that a true 1:1 copy can be created.

Although this security keeps control of the content in your hands, it doesn't provide a mechanism to determine who can and can't access the content. To protect password-protect your files, you can use a very similar system to that of Apache and htpasswd, which is covered in Chapter 23, "Creating a Web Server."

Protection is applied on a per-directory basis. Access can be controlled based on usernames or groups of users, stored in the files

/Library/QuickTimeStreaming/Config/qtusers and /Library/QuickTimeStreaming/Config/qtgroups, respectively.

Password-Protecting a Directory

To password-protect a directory, simply create a plain text file named qtaccess in the directory with your media files. To protect the files with a simple username and password, add the following lines to the file:

 AuthName "My Protected Media" AuthUserFile /Library/QuickTimeStreaming/Config/qtusers Require valid-user 

The first line, AuthName, provides a message that will be displayed to the user requesting the media. The AuthUserFile keyword is used to identify the file that contains the usernames and passwords; in this case, I've used the default file /Library/QuickTimeStreaming/Config/qtusers. Finally, the last line, Require valid-user tells the system that any valid username and password may access the resources.

Before you can use your newly protected directory, you will need to create a new QuickTime user account. This is accomplished with the qtpasswd command. (If you've used Apache's protection features, you're probably experiencing déjà vu right about now.) For example, to add the user myuser with the password mypass to the default user file, you would use the following:

 # sudo qtpasswd -p mypass myuser Adding userName myuser 

Now, attempting to access one of the password-protected files will display a login screen as shown in Figure 25.10.

Figure 25.10. QuickTime will prompt for a username and password when a user tries to access a protected media file.

Managing Users and Groups

Managing many different users and the files they can access can be simplified by organizing users into groups. Just as Tiger has different groups for different capabilities, DSS can do the same. The qtpasswd command can manage users and groups easily. For example, to create a new group, training, and add the user myuser to the group, this command would be used:

 # sudo qtpasswd -A training myuser Adding user myuser to group training 

Additional users can be added using qtpasswd -A <groupname> <username>.

TIP

If you ever forget or lose the DSS administrator password, you can create a new administrative user by adding a new user to the built-in admin group.

After the sample training group has been created, a qtaccess file similar to the following can be used to authenticate against the group:

 AuthName "My Protected Media" AuthUserFile /Library/QuickTimeStreaming/Config/qtusers AuthGroupFile /Library/QuickTimeStreaming/Config/qtgroups Require group training 

Any user within the TRaining group who provides a valid username and password will be allowed access to the media.

Unlike Apache's htpasswd utility, the QuickTime qtpasswd application provides much more management control over users and groups. Table 25.1 provides the most useful command-line switches for qtpasswd, using the syntax qtpasswd <options> <username>.

Table 25.1. Command-Line Switches for qtpasswd

Option	Description
-F	Don't ask for confirmation when deleting or overwriting information.
-f <password file>	Password file to use. If not specified, the default is used.
-g <groups file>	Group file to use. If not specified, the default is used.
-p <password>	Specify a password at the command-line rather than prompting for it.
-d <username>	Delete a username from the password file and all associated groups.
-A <group>	Add a username to a group. The group is added if necessary.
-D <group>	Delete a user from a group.
-C <group>	Create a new group. When using this option, you should not include the final username parameter.
-R <group>	Remove a group. When using this option, you should not include the final username parameter.

Additional qtaccess Options

You've seen that the media can be protected based on users and groups. The qtaccess file format offers a few additional options that can even further refine your authentication settings. These are described in Table 25.2.

Table 25.2. Additional Authentication Options for qtaccess

Option	Description
AuthName "<message>"	Choose a message that will be displayed in the authentication dialog.
AuthUserFile <userfile path>	The full path to the user file to use for authentication.
AuthGroupFile <groupfile path>	The full path to the group file to use for authentication.
require user <username 1>	Require one of the users specified on the line to log in. <username 2> ... <username n>
require group <groupname 1> <groupname 2> ... <groupname n>	Require a user in one of the groups specified to log in.
require any-user	Allow any user to access the resource without a username or password.
require valid-user	Allow any validated user to access the resources.
AuthScheme [basic|digest]	Choose whether to use basic or digest authentication. Basic authentication is required for versions of QuickTime earlier than 5.0.

Working with DSS Playlists

When playing or viewing media files, there is often a logical progression that takes place through several files all the songs in an album or all the sessions in a training workshop, for example. Rather than manually forcing the viewer to select each file sequentially or editing the files together, you can create a playlist that automatically joins the media. Playlists are also unique in that they are live streams of content. After a playlist has been created, it is started on your server. The content is in a continuous state of playback; when a user tunes in, she tunes in to the stream wherever it happens to be during playback.

Playlists are created by accessing the web interface of your streaming server (http://<your serve rip>:1220/) and clicking the Playlists link along the left side of the web page. The Playlist management screen is displayed in Figure 25.11.

Figure 25.11. Use the Playlist link within the DSS administrative site to manage your playlists.

From here, you can create new MP3 playlists (for Shoutcast-compatible MP3 streams) and movie playlists, as well as edit and delete existing playlists.

Adding a Playlist

You must follow a few rules that when creating a playlist:

• MP3 files must be encoded identically.

• MP3 file playlists require streaming over port 80. If you are running Apache, this will not function correctly. You must stop Apache (Sharing Preference Pane) and enable port 80 streaming (click Port Settings in the DSS administrative website).

• Video files must use the same codec and encoding options.

When your files meet these criteria, click the New MP3 Playlist or New Movie Playlist link along the right side of the web page. A playlist creation screen will be displayed, showing the MP3 or movie files contained in the /Library/QuickTimeStreaming/Movies/ directory. The playlist creation screen is shown in Figure 25.12.

Figure 25.12. Create your playlists visually within the Playlists web page.

Complete the fields at the top of the page to identify and define how your playlist will function:

Name The name of the stream. This should be a meaningful name that will be displayed to the end user. This should typically be the name of the streaming channel, such as "Ray's Streaming Garageband Songs."

Mount Point The name by which the stream will be referenced. This should be a simple string that will be used in the URL to load the stream. For example, music published under the mount point /mysongs will be accessible from the URL http://<streaming server name>/mysongs within iTunes, whereas video with the mount point /myvideos will be made available to QuickTime Player at rtsp://<streaming server name>/myvideos.

Play Mode Choose from the playback options Sequential Looped (one song after another, repeating after all have been played), Sequential (one song after another, ending the stream after all songs have been played), and Weighted Random (songs are chosen randomly from the playlist based on an assigned weight).

Repetition Choose how many other files must have played before one can be repeated. This option, usefully only with the Weighted Random play mode, prevents DSS from playing one track over and over.

Genre The musical classification for the stream (rock, alternative, classical, and so forth).

At the bottom of the page are two panes used to add and arrange content within your playlist. The list on the left displays the available media files that you can use as well as other folders within the main Movies directory. To move into a folder, double-click it or select it in the list and click the Open Folder arrow button at the bottom of the list. You can move to a previous folder level by using the pop-up menu at the top of the list.

To assign one or more files to your playlist, select them in the list on the left and drag them to the list on the right. After the files have been added to the playlist, the playback order (assuming that the Sequential Play mode has been selected) can be altered by dragging the items up and down within the list. Files can be removed by selecting them and clicking the Remove Item button at the bottom of the playlist.

As mentioned earlier, the Weighted Random play mode randomizes based on a file weight. Within the playback list, a weight value is shown to the right of every entry. To increase or decrease the weight, click the up arrow or down arrow to the immediate left of the value. Weights range from 1 to 10, with 10 receiving the most play time and 1 the least. Leaving the weight set to a constant value for each file indicates that no track should receive special playback priority.

To finish up your stream, enable logging using the check box Log This Playlist's Activity located at the bottom of the playlist page. Logs are stored in /Library/ QuickTimeStreaming/Logs/mp3_access.log and /Library/QuickTimeStreaming/Logs/ StreamingServer.log for MP3s and video, respectively, and within the playlist directories of /Library/QuickTimeStreaming/Playlists/. If you are creating an MP3 stream, you'll also be provided with a field from which to select the genre of audio you're streaming. This is used by the MP3 client for classification of the stream and should be set to whatever is appropriate for your broadcast. Click Save Changes to save the playlist.

NOTE

The Send This Playlist to a Broadcast Server option can be used in a multiserver setup to broadcast the stream to a second server for multicasting or unicasting. This chapter focuses on a single broadcasting system.

Starting and Stopping a Playlist

After a playlist has been created, it is stored, but isn't made available to QuickTime clients until the playlist has been started. Keep in mind that playlists are live streams. This means that they are always (assuming that they repeat!) playing some portion of the media you've set up even if no client is connected. As such, they consume system resources and should be enabled only when you are expecting connections. Click the Playlists link on the right side of the DSS administrative website to manage your playlist streams.

As you can see in Figure 25.13, the status of each playlist (Stopped or Playing) is displayed to the right of the playlist name. By default, playlists are not started after they have been created.

Figure 25.13. Use the playlist management screen to start and stop playlist streams.

To start or stop a playlist, use the Play and Stop buttons located directly to the right of their status within the playlist management screen. After a looping playlist has been started, it will not stop until you manually click the Stop button. Playlists will automatically start playing at system boot, if appropriate.

To edit or delete an existing playlist, select it in the list, and then click the Edit Playlist or Delete Playlist button as needed.

ON MOUNT POINTS AND SDP FILES

When setting up and starting a playlist, you are, in fact, creating a live stream just as if you were capturing the media and sending it out in real-time (which you'll learn how to do in the next section). To do this, the server relies on the presence of an SDP (Session Description Protocol) file.

An SDP file describes the media being streamed and the requirements for receiving the stream. Although merely a text file, an SDP file is quite complex to build by hand and is usually created automatically in this case, by the playlist manager. When you specify a mount point, its name is used to create the SDP file. Creating a video stream with the mount point of coolvideos will, for example, create an SDP file called coolvideos.sdp in the QuickTime streaming Movies directory.