Linking to Streams

Introduction

QuickTime and Darwin Streaming Server support two primary transport methods for streaming:

  1. RTSP/RTP streams use standard IETF streaming protocols to stream video and audio to clients. The Streaming Server supports QuickTime .mov, MPEG-4 .mp4 and 3G .3gp files for on-demand streaming. In addition, the Streaming Server can reflect live streams and playlists using Session Description Protocol .sdp files. Linking to RTSP/RTP streams is described in the Embedding RTSP/RTP Streams section below.
  2. MP3 streams used the Shoutcast protocol for streaming mp3 files over http. The Streaming Server supports streaming MP3 playlists from locally stored MP3 files and reflecting live MP3 streams from Shoutcast compatible webcasting software. Linking to MP3 playlists and live MP3 webcasts is described in Linking to mp3 streams below.

Embedding RTSP/RTP Streams

RTSP/RTP streams can be embedded in web pages, or played in QuickTime player. The methods for embedding QuickTime Streams presented below require Apple's new JavaScript Library which can be downloaded here. After the library is downloaded, place it on your web server (the examples below assume that it is placed in the document root of the web server). The library must be referenced in your web page before it can be used. A good place for to reference the library is immediately after the body tag in your html code. For example:
<body>
<script src="/AC_QuickTime.js" language="JavaScript" type="text/javascript">
</script>
Once you have referenced the library as shown, you can use it to embed QuickTime movies from web or streaming servers. The general format for calling the QuickTime Javascript Library to embed movies is:
<script language="JavaScript" type="text/javascript">
QT_WriteOBJECT('Movie URL','MovieWidth','MovieHeight','ActiveX Version',
'First Attribute Name','First Attribute Value',
'Next Attribute Name','Next Attribute Value',
...repeat attributes as necessary
'Last Attribute Name','Last Attribute Value');
</script>

Specifics of embedding a stream

The Movie URL in the example above should not be the rtsp url to your stream. Instead, the Movie URL should be an http URL to a file on a web server (relative or absolute URLs are OK). This file will be either a poster movie the client clicks on to play the stream, a reference movie to the stream, or a placeholder movie that will be replaced by the stream. These options are described below. The MovieWidth and MovieHeight attributes are measured in pixels. You should add 16 to the height if you want do display the QuickTime playback controller for the movie. ActiveX Version should be left blank. The attribute name value pairs are illustrated here, and described in detail on Apple's site here.

Embedding a stream using a Poster Movie

One way to embed a streaming movie is with a poster movie. The client clicks on the poster movie to start the stream. The poster movie can be a file in any format that QuickTime can open (usually a still image). Poster movies are usually used with the target attribute. Using the target attribute, the movie can play in the same space as the poster movie (target set to 'myself') or in QuickTime Player (target set to 'quicktimeplayer'). The url that plays when the poster movie is clicked is set by the href attribute. The following code is used to create a poster movie that will play the stream in the same space as the poster image (target is set to 'myself'):

<script language="JavaScript" type="text/javascript">
QT_WriteOBJECT('skipjames.jpg','384','232','',
'href','rtsp://myserver.edu/crowjane.mov',
'target','myself',
'controller','false');
</script>

Note: A good format to use for a Poster Movie is a .qtif file. The qtif file format is an image file format that only QuickTime understands, so it is unlikely to be hijacked by other players. In addition, setting the mime type with the 'type' attribute to insure the QuickTime plugin will get control. Most image formats can be converted into a qtif files with QuickTime Pro and PictureViewer (Classic Mac OS and Windows) or Preview (Mac OS X). Setting the 'controller' attribute to 'true' displays only the image without the playback controller. When the user clicks on the picture the controller will be displayed. If you want to keep the controller hidden, the attribute 'saveembedtags' can be set to 'true'.

Here is a poster movie in action:

Embedding a stream using a Reference Movie

Another way to embed a streaming movie is with a reference movie. There are a variety of ways to create reference movies, which function like pointers to the actual media. The simplest way to create a reference movie is with QuickTime Pro:

  1. Open QuickTime Player Pro
  2. From the File menu select "Open URL..."
  3. Open the URL to your streaming movie using the rtsp url.
  4. Save the movie that plays as a Self-Contained movie.
  5. Put the movie that you saved on your web site.
  6. Make the reference movie the first attribute you specify in the QT_WriteObject method call.

If you don't have QuickTime Pro, you can create a simple reference movie with any text editor. Just create a text file with one line in the following format:

RTSPtextRTSP://<your server>/<your streaming movie>

Save the file with the .mov extension.

Reference movies can also be used to create "movie alternates." This sophisticated capability of QuickTime allows you to have a single reference that automatically plays content based on the client's connection speed, operating system platform, etc. Movie alternates are covered in more detail here.

All reference movies can be embedded by specifying them as the first attribute for the QT_WriteOJECT method. Streaming movies embedded using reference movies are often used with the autoplay attribute set to true. In this case the attribute has been set to false so you can scroll to the movie and press the play button on the controller when you want to view the movie. The following code shows a typical use of a reference movie:

<script language="JavaScript" type="text/javascript">
QT_WriteOBJECT('crowjane.mov','384','232','',
'autoplay','false');
</script>

Here is a reference movie in action:

Embedding a stream using a Placeholder Movie

Sometimes web authors want to embed a movie that plays automatically, but they don't want to use a reference movie. There are two ways to accomplish this:

  1. Use the poster movie technique outlined above, but add the attribute 'autohref' with the value 'true' to the QT_WriteOJECT method call.
    <script language="JavaScript" type="text/javascript">
    QT_WriteOBJECT('poster.jpg','320','256','',
    'href','rtsp://soundscreen.com/Educational/Science/Merry_Go_Round_Physics.mov',
    'autohref','true',
    'target','myself');
    </script>
  2. Use the poster movie technique outlined above, but replace the 'href' attribute with the attribute 'qtsrc' and elminate the 'target' attribute. This method ignores the poster movie entirely and loads the url specified by 'qtsrc' directly:
    <script language="JavaScript" type="text/javascript">
    QT_WriteOBJECT('poster.jpg','352','256','',
    'qtsrc','rtsp://soundscreen.com/Educational/Science/Merry_Go_Round_Physics.mov');
    </script>

Linking to mp3 Streams

Linking to mp3 streams requires a text file with the extension .m3u. This file has the URL to your mp3 stream in it. For instance, if a mp3 playlist named "Blues" was playing from the Streaming Server, and the domain name of the server was stream.mydomain.net, the m3u file would contain the link:

http://stream.mydomain.net:8000/blues

The ":8000" is the port for streaming mp3 playlists from Darwin Streaming Server. If you enable port 80 streaming the ":8000" is not required. The .m3u file could be placed on any web server, and linked to a web page with the standard <A HREF> tag. For instance, to link to a file named "blues.m3u" from a web page in the same directory with the file, the link could be:

<A HREF="./blues.m3u">Play the blues</a>

Note: For .m3u files to work correctly, your web server must be configured to deliver the correct mime type for .m3u files:
audio/x-mpegurl .m3u