TITLE
    Mac OS X Server: About QuickTime Streaming PlaylistBroadcaster
Article ID:
Created:
Modified: 		60463
9/3/99
9/7/99
TOPIC

    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.

    Note: QuickTime Streaming Server 1.0.2 Update is available for downloading. For more information go to:
    Article 60462: " QuickTime Streaming Server 1.0.2 Update: Read Me "

DISCUSSION

    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:
    • prepare the QuickTime media for streaming
    • prepare a reference media file
    • create a playlist, which is a text file that specifies the QuickTime media to broadcast
    • create a broadcast description file, which is a text file that specifies information for PlaylistBroadcaster

    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:
    • Be sure all the media files contain compatible media types. For example, all audio tracks should use the same encoding and bit rate. All video tracks should also use the same encoding.
    • Format the media in each file in the same way. For example, use the same frame size for each file that contains a video track.
    • Be sure each item is a hinted QuickTime movie optimized for the server.

    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:
    • You must begin the playlist with *PLAY-LIST*.
    • The list can consist of individual media files or other playlist files.
    • To specify a media file or another playlist file, provide the complete or relative pathname to the file.
    • To specify another playlist, precede the pathname with the "+" symbol.
    • For individual media files, the list should include a weight. The weight is a number from 1 to 10. Items with a weight of 10 play more often than those with lower numbers. If you don't specify a weight, PlayList Broadcaster assigns 10 as the weight.

    Here's an example of a playlist file containing individual files with weights and another playlist:
      *PLAY-LIST*
      # Lines beginning with "#" are comments
      # individual media files weight (1-10)
      #---------------------------------------
      /music/jazz/take5.mov 2
      /music/rock/freebird.mov 9
      /music/reggae/onedrop.mov 5

      # path to another playlist
      #---------------------------------------
      + /music/classical/playlist.txt

      # relative path to another playlist
      #---------------------------------------
      + muisc/funk/funkplist.txt

      # individual media file with space
      #---------------------------------------
      "/music/jazz/ice cream love.mov" 9

    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:
          sequential
          sequential_looped
          weighted_random
        If you specify sequential or sequential_looped, PlaylistBroadcaster broadcasts the media in the order it appears in the list.

        If you specify weighted_random, PlaylistBroadcaster broadcasts the media in random order using the specified weights to broadcast how often an item plays. It continues to broadcast the media until you stop the PlaylistBroadcaster process.
    Σ 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).
        Each track of the media you are broadcasting requires two ports. If the media contains several tracks (for example, video and sound), PlaylistBroadcaster uses the destination base port as the starting port number, then assigns an incremental port number to other tracks automatically.

        Important: Each track of each broadcast must use a different port number. If you are streaming more than one broadcast of multi-track media from your QuickTime Streaming Server, be sure to assign destination base ports so that tracks do not play on the same port.

        For example, if you use the default destination base port for a broadcast in which the media has three tracks (video, audio, and text), then the broadcast will use ports 5004 through 5009 (two for each track). If you want to broadcast another stream, then you should set the destination base port of the second stream to at least 5010.
    Σ 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.
        By default this parameter is zero (0), so that all the media files play randomly based only on the weight you have assigned to each one.

        If you set the parameter to a value greater than zero, then after a media file is broadcast, it will not be available to play again until the number of files specified by the parameter have played. Of course, it may not play again immediately because PlaylistBroadcaster will broadcast any available media randomly.

        Note: Be sure to set this parameter to a number less than the number of media files in the playlist. If you set it to a number equal to or greater than the number of media files in the playlist, the broadcast will play each media file once then stop. If you perform a preflight check, you will see a message about this problem.
    Σ 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.
        Important: If you stop a broadcast and change the broadcast description file, be sure to move the SDP file from the QuickTime Streaming Server movies folder before you restart the broadcast.
    Σ 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:
          enabled
          disabled
        If you enable logging, PlaylistBroadcaster records information about the broadcast in the log file, including error messages. For more information, see "Using the Log File" and "Understanding Error Messages" later in this document.
    Σ 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:
      playlist_file /server/local/media/lists/playlist1
      play_mode weighted_random
      sdp_reference_movie /music/jazz/take5.mov
      destination_ip_address 12.123.123.123
      destination_base_port 5004
      recent_movies_list_size 10
      sdp_file /server/QTSS/movies/playlist1.sdp
      logging enabled
      log_file /server/local/playlistlogs

    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:
      PlaylistBroadcaster broadcast_filepath -preflight

    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:
    • if there is a problem with a media file included in the playlist file
    • if it can't find the playlist file
    • if there's a problem with the broadcast description file

    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:
      PlaylistBroadcaster broadcast_filepath

    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:
      PlaylistBroadcaster -list

    This lists all the PlaylistBroadcaster broadcasts that are currently running. Here's an example:
      [ 1] JazzBroadcast.txt; pid: 12318
      [ 2] RockBroadcast.txt; pid: 12389
      [ 3] ClassicBroadcast.txt; pid: 12730

    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:
      PlaylistBroadcaster -stop 1

    If you are broadcasting more than one playlist, list the broadcasts that are currently playing, then type the following command in a Terminal window:
      PlaylistBroadcaster -stop broadcast_index
    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:
      PlaylistBroadcaster -help

    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:
    • the date and time the broadcast started
    • the date and time each media file played, the pathname of the media file, and if any errors occur a description of the problem
    • the date and time the broadcast stopped

    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.

Document Information
Product Area: Mac OS System Software
Category: Mac OS X Server
Sub Category: QuickTime Streaming

Copyright © 2000 Apple Computer, Inc. All rights reserved.