Mac OS X Server: About QuickTime Streaming PlaylistBroadcaster

About QuickTime Streaming PlaylistBroadcaster

This document describes how to use PlaylistBroadcaster, a new feature available with QuickTime Streaming Server 1.0.2. PlaylistBroadcaster broadcasts QuickTime media, "movies," to a streaming server, such as QuickTime Streaming Server, which then reflects the media to clients. This lets you create a virtual radio station or TV broadcast that appears to users as a live broadcast of the media.

This document is installed in the /System/Documentation/Administration/Services/QuickTimeStreaming/
directory.

For more information, see the QuickTime Streaming Server website.
To specify the media to broadcast, you create a playlist. To specify how PlaylistBroadcaster broadcasts the media, you use a broadcast description file.

You can broadcast the media in the playlist once through the list sequentially, repeatedly through the list sequentially, or randomly.

If you broadcast the media randomly, you can specify a weight for each media file in the list. The weight, which is a number from 1 to 10, determines how often an item plays. Media files that are weighted as 10 play more often than media files weighted with lower numbers. In addition to using weights, you can prevent a media file from playing again until a specified number of other media files play.

To broadcast a playlist, you use the PlaylistBroadcaster command to start the process. The PlaylistBroadcaster process is a separate process from the QuickTime Streaming Server. Each process can broadcast the media from one playlist only. However, you can run the PlaylistBroadcaster process as many times as you want to broadcast other playlists.
As PlaylistBroadcaster broadcasts a playlist, you can have it keep a log of the media files it plays so you can keep track of what media is broadcast.

To use PlaylistBroadcaster, you need to do the following:
Once you're set up to use PlaylistBroadcaster, you can execute the PlaylistBroadcaster command to start the broadcast. If you broadcast the media repeatedly or randomly, you also use the PlaylistBroadcaster command to stop the broadcast.

Setting up to use PlaylistBroadcaster

Preparing the QuickTime media for streaming

You can use PlaylistBroadcaster to broadcast any media that the QuickTime Streaming Server is capable of streaming. For more information about the types of media you can stream, see Server Administration Help on your Mac OS X Server. To see the Help, open the Server Administration Help (named ServerAdministrationHelp.help), located in /System/Documentation/Help.

To prepare the media, you must do the following:
Note: To hint a QuickTime movie, you can export it from QuickTime Player and select one of the hinting options in the export dialog box. To optimize the movie for the server, click Options in the export dialog box. If the Hint Exporter Settings dialog box appears, select the Optimize Hints for Server option. If the Movie Settings dialog box appears, open the pop-up menu below Prepare for Internet Streaming and choose Hinted Streaming, then click Settings to see the Hint Exporter Settings dialog box.

Preparing a reference movie
PlaylistBroadcaster requires that you specify a reference movie in the broadcast description file. This is a QuickTime hinted movie that contains the same types of tracks and encodings used in the actual media files. Normally, you can specify any of the media files included in the playlist because they are the same, although you can author a reference movie.

Creating the playlist file
The playlist text file specifies the media to use in the broadcast. To create a playlist, you can use any text editor, such as TextEdit on the Mac OS X Server, to type the information for each item included in the playlist. Then, save the text file where you can locate it on your server.

Keep these points in mind about the playlist file:
Here's an example of a playlist file containing individual files with weights and another playlist:
Note: If the pathnames include spaces, enclose the pathname in quotation marks.

You can change a playlist file after starting to broadcast it. However, you must stop and restart the broadcast to use the changes.

Creating the broadcast description file
The broadcast description file is a text file that specifies how the media should be broadcast, the playlist file, the IP address of the QuickTime Streaming Server, and other information about the broadcast.

To create a broadcast description file, you can use any text editor, such as TextEdit on the Mac OS X Server, to type the information needed to broadcast the playlist. Then, save the text file where you can locate it on your server.

The information you need to enter in the broadcast file includes the following:
Σ Playlist (playlist_file): The complete or relative pathname of the playlist file you want to broadcast.
Σ Play Mode (play_mode): The method you want to use to broadcast the media files. Specify one of three modes: Σ Destination (destination_ip_address): The IP address of the QuickTime Streaming Server you are using to broadcast the media. The default destination is the QuickTime Streaming Server on the same computer as the PlaylistBroadcaster.

Σ Destination Base Port (destination_base_port): This specifies the base port number for the broadcast, which must be an even number. If you do not specify a base port, PlaylistBroadcaster uses the default port (5004).
Σ Recent Movies List Size (recent_movies_list_size): If you broadcast a playlist using the weighted_random Play Mode, you can use this parameter to specify the minimum number of files to broadcast before allowing a file to play again.
Σ SDP File (sdp_file): The complete or relative pathname of an SDP file in the movies folder used by the QuickTime Streaming Server. You must specify an SDP file. If the SDP file you specify doesn't exist in the location, PlaylistBroadcaster creates one.
Σ SDP Reference Movie (sdp_reference_movie): The complete or relative pathname of the reference movie, which can be one of the media files you are broadcasting.

Σ Logging (logging): You use this parameter to specify whether or not to keep a log. It can have one of two values: Σ Log File (log_file): The complete or relative pathname of the log file. If you enable logging but do not specify a log file, then PlaylistBroadcaster creates a log file with the name of the broadcast description file followed by ".log" in the same directory as the broadcast description file.

Here's an example of the items for a broadcast file:
Starting and stopping PlaylistBroadcaster

To start, you use the PlaylistBroadcaster command. You also use the command to list existing playlist broadcasts and to stop broadcasting a playlist.

Using preflight to check your broadcast

If the playlist you are broadcasting includes a large number of media files, you may want to use the following command:
Preflight causes PlaylistBroadcaster to determine if each media file in the playlist can be broadcast. Preflight does not start the broadcast.

After performing the preflight check, PlaylistBroadcaster displays information about the broadcast description file, including information about these types of problems:
Note: If you perform a preflight check, PlaylistBroadcaster creates an SDP file, if the file doesn't exist already. If you change the broadcast description file, be sure to move the SDP file from the QuickTime Streaming Server movie folder before restarting the broadcast..

Starting to broadcast a playlist
To start broadcasting a playlist, type the following command in a Terminal window:
where the "broadcast_filepath" is the complete or relative pathname of the broadcast description file that describes the playlist you want to broadcast.

When you start PlaylistBroadcaster, it creates the SDP file, if the file doesn't exist already. PlaylistBroadcaster also creates a playlist in memory that lists all the media files in the playlist and in any playlist files included in the playlist.

Note: If you change a playlist file used by a broadcast, you must start and restart the broadcast to use the changes. If you change the broadcast description file, you must stop the broadcast, move the SDP file from the QuickTime Streaming Server movie folder, then restart the broadcast.

Listing broadcasts
To stop a broadcast, you need to specify an index number. If you are broadcasting more than one playlist, you need the index number of the playlist broadcast. To see the index number of the playlists that are broadcasting, type the following command in a Terminal window:
This lists all the PlaylistBroadcaster broadcasts that are currently running. Here's an example:
The number at the beginning of each item is the broadcast's index.

Stopping a playlist broadcast
If you are broadcasting one playlist and want to stop it, then type the following command in a Terminal window:
If you are broadcasting more than one playlist, list the broadcasts that are currently playing, then type the following command in a Terminal window:where "broadcast_index" is the index of the broadcast you want to stop.

Restarting a playlist broadcast
You can restart a broadcast using the PlaylistBroadcaster command. If you restart a broadcast, PlaylistBroadcaster uses the SDP file it created when you started the broadcast previously. If you make changes to the broadcast description file, be sure to move the SDP file from the QuickTime Streaming Server movie folder before restarting the broadcast.

Seeing information about PlaylistBroadcaster
You can use the following command to see information about PlaylistBroadcaster, such as the version number of the program:
Connecting to the broadcast

To connect to the broadcast, users need client software that can play QuickTime media, such as the QuickTime Player. They can also use Internet browser programs, such as Microsoft Internet Explorer or Netscape Communicator, if they have the QuickTime Plug-in installed. For best results, users should have the latest version of the QuickTime software installed on their computers.

You will need to provide users with the URL for the QuickTime Streaming Server and the SDP file that connects to the playlist broadcast.

Solving problems with PlaylistBroadcaster

The media in the playlist is not being broadcast:
Use ProcessViewer to be sure the PlaylistBroadcaster process is running. If it is and the media is not being broadcast, stop the broadcast using the PlaylistBroadcaster command, move the SDP file for the broadcast from the QuickTime Streaming Server movie folder, then restart the broadcast.

Be sure the broadcast description file is correct for all the parameters correctly. If you change the broadcast description file, stop the broadcast, move the SDP file for the broadcast, then restart.

The media in the playlist is not broadcast randomly:
Be sure the broadcast description file specifies that the play_mode parameter is weighted_random.

The media plays once then stops:
Be sure the broadcast description file specifies that the play_mode parameter is sequential_looped or weighted_random.

If you broadcast the playlist as weighted_random and set the Recent Movies List Size (recent_movies_list_size), be sure the number is less than the number of media files in the playlist.

Some media in the playlist is not being played:
Check the weight you have assigned to each media file in the playlist. If you change the playlist, be sure to stop and restart the broadcast to use the changes.

Check the settings for the Recent Movies List Size parameter in the broadcast description file. If you change the broadcast description file, be sure to stop the broadcast, move the SDP file for the broadcast from the QuickTime Streaming Server movie folder, then start the broadcast again.

The media isn't presented correctly:
Be sure the content, format, and encoding of the media is the same for all files in the playlist. Also, be sure users have the latest version of the QuickTime software installed on their computers.

The presentation of the media is slow:
Be sure each media file is a hinted movie optimized for the server.

A user cannot connect to the broadcast:
Be sure the user's computer has QuickTime 4.0 or later installed. If the user is connecting to the broadcast using a Web browser, be sure the QuickTime 4 Plug-in is installed correctly for the browser.

If the correct software is installed, be sure the user has the correct URL.

Be sure the broadcast file has the correct IP address, base port, and pathname for the SDP file.

A user gets a "404" error in a Web browser but is using the correct URL:
Be sure that the destination IP address is correct in the broadcast description file.

A user's computer crashes while streaming a playlist that includes media files with video tracks:
Be sure all the video tracks in the media files use the same frame size.

Using the log file

If you enable logging, PlaylistBroadcaster records information about the broadcast. The log file can help you determine problems that occur during the broadcast, as well as maintain records of the media file you broadcast.
A log file contains this information:
Using the error messages

If it detects a problem during a preflight check, PlaylistBroadcaster displays an error message. It also includes a description of any problems that occur in the log file, if you enable logging.

Most of the error messages are self-explanatory. Following is a description of a few of the messages.

Permission denied to access the broadcast description file. Read access required. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file with Read/Write privileges.

Unable to access the broadcast description file. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file, but it could not determine a specific reason.

Error reading the broadcast description file "<pathname>." (bad format or missing file)
PlaylistBroadcaster cannot read lines from the broadcast description file.

PlaylistBroadcaster set up failed: There are no movies to play.
PlaylistBroadcaster found no media files in the playlist.

Warning, movie tracks do not match SDP file. Movie: <pathname>
Some of the tracks in a movie are not mapped in the SDP file and cannot be broadcast. The message shows the number of tracks that will not be broadcast.

Permission to access the SDP file was denied. Read/Write access is required. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file with Read/Write privileges.

Unable to access the SDP file. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file, but it could not determine a specific reason.

Permission to access the SDP reference movie was denied. Read access required. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file with Read privileges.

Unable to access the SDP reference movie. (path: <pathname>, errno: <error number>)
PlaylistBroadcaster was unable to open the file.

Warning: The recent_movies_list_size is greater than or equal to the number of movies in the playlist. Each movie will play once, then the broadcast will end.
This message appears after a preflight check. If you want to broadcast to play continuously, you should change the parameter to a number less than the number of movies in the playlist.

Could not open /tmp/broadcastlist. Reason: access denied.
PlaylistBroadcaster uses this file to maintain a list of broadcasts. PlaylistBroadcaster was unable to open the file with Read/Write privileges. You may see this during the preflight check, when starting a new broadcast, or when stopping a broadcast.

Error opening "/tmp/broadcastlist". (<error number>)
PlaylistBroadcaster was unable to open the file.

PlaylistBroadcaster broadcast ID <number> not running.
The broadcast ID number specified in a stop command is not a valid, running broadcast ID.

PlaylistBroadcaster broadcast ID <number>, permission to stop denied.
You tried to stop a broadcast owned by another user; for example, a broadcast started when logged in as Administrator.

Bad argument to stop: ("<stop argument>")
The broadcast ID specified with the stop command was not a number or was less than zero.
Published Date: Feb 20, 2012