Chapter 7: RealPix Markup

Using RealPix markup, you can create streaming slideshows from still images in JPEG, GIF, and PNG formats. You can even define transition effects, such as fades and wipes, that occur between images. Coupled with an audio soundtrack, RealPix makes a viable alternative to video for low-bandwidth connections. This chapter explains the RealPix markup. Appendix F provides a quick reference for RealPix tags and attributes.

Tip: To see RealPix examples, get the zipped HTML version of this guide as described in "How to Download This Guide to Your Computer", and view the Sample Files page.

Understanding RealPix

A RealPix slideshow consists of a RealPix markup file, which uses the file extension .rp, along with any number of images. For each slideshow, you define an overall duration, and indicate when each image appears during the presentation timeline. RealPix automatically expands or shrinks each image to fit in a display area that can be any size. The markup also lets you define several transition effects:

• Fade an image in from a solid color.
• Fade an image out to a solid color.
• Crossfade between two images.
• Display only part of a source image.
• Introduce a new image with a wipe from left to right, for example.
• Zoom in on a detail, pan around the image, or zoom out.

RealPix and SMIL

You can stream a RealPix slideshow by itself, or you can use SMIL to combine RealPix with other clips, such as a RealAudio soundtrack. Using SMIL 2.0, you can augment your slideshow with many features. If you stream a slideshow alongside a video sequence, for example, you can use SMIL transition effects to fade the videos in and out. In fact, because SMIL 2.0 provides transition effects, you can use just SMIL 2.0 to assemble a slideshow. As the following sections explain, though, RealPix and SMIL 2.0 offer different advantages for delivering slideshows.

View it now! (requirements for viewing this sample) All three of these samples are similar in appearance—they all display a slideshow of images along with RealText clips that provide narration—but each uses a different production technique: 1. The first sample uses RealPix and SMIL 1.0 to provide backwards compatibility with earlier versions of RealPlayer. 2. The second sample uses RealPix and SMIL 2.0 to add SMIL transition effects to the RealText clips. 3. The third sample is made entirely with SMIL 2.0, using SMIL transition effects for both the images and the RealText clips.

RealPix Slideshow Advantages

A streaming slideshow created with RealPix provides the following advantages over a slideshow defined through SMIL 2.0:

• backwards compatibility

RealPix is compatible with RealPlayer versions earlier than RealOne Player, such as RealPlayer 7 and RealPlayer 8. SMIL 2.0 works only with RealOne Player and later, including RealPlayer 10. To coordinate multiple clips, you can use SMIL 1.0 along with RealPix to reach the widest RealPlayer audience.

For More Information: For more on the two versions of SMIL, see "SMIL 1.0 and SMIL 2.0".

• better resource use

RealPix maximizes the efficiency of image streaming. Now matter how many images the slideshow contains, a RealPix presentation needs just one stream from Helix Server. In contrast, a SMIL 2.0 slideshow may require a separate Helix Server stream for each image in the slideshow. RealPix is better suited, therefore, for long slideshows that contain a lot of images.

• easier timeline and bandwidth management

Under stable network conditions, RealPix guarantees that RealPlayer does not have to pause the slideshow to buffer more data. It does this by gauging the bandwidth required to stream all of the images against the slideshow timeline. It then streams enough preroll data to ensure that the slideshow does not have to pause once it begins to play. Achieving the same results using SMIL 2.0 may require the use of advanced SMIL features such as prefetching, which Chapter 19 explains.

• image caching in memory

If you reuse an image in a RealPix slideshow, RealPlayer caches the image in memory until it is no longer needed. A RealPix slideshow can thereby redisplay images without consuming more bandwidth. A RealPix slideshow does not have access to the cache of another slideshow playing concurrently, though, and each cache is deleted when the slideshow ends.

Note: No version of RealPlayer maintains a disk cache of images shown in a RealPix or SMIL presentation. Nor can viewers copy or download images. Viewers therefore do not have access to copyrighted image files shown in a RealPix or a SMIL 2.0 presentation.

• easier markup for complex effects

RealPix lets you display just part of a source image, zoom in or out on an image, and pan across an image. Although you can duplicate these effects using SMIL layout and animations, which are described in Chapter 12 and Chapter 17, respectively, the RealPix markup lets you create these effects more easily.

SMIL 2.0 Slideshow Advantages

Creating a slideshow with SMIL 2.0 alone provides these advantages over using RealPix:

• single markup file

Your SMIL 2.0 file will contain all the required presentation markup. This can make it easier to coordinate each image with, for example, a separate audio clip. When you use RealPix, you need a RealPix file to define the slideshow, and a SMIL file to coordinate the slideshow with other clips, such as the soundtrack.

• more transition effects

As Chapter 16 explains, SMIL 2.0 provides over 100 styles of transition effects. You can run each transition effect in a forward or reverse direction, for example, or use partial or repeating effects. You can also apply SMIL transition effects to any type of visual clip, including Flash animations and videos. RealPix, on the other hand, provides about a dozen transition effects for still images only. It doesn't offer extra features found in SMIL transition effects, such as border colors and blends. SMIL 2.0 therefore lets you create a more visually unique slideshow.

• interactive slideshows

Using exclusive groups and SMIL 2.0's advanced timing features, you can create an interactive slideshow that advances to a new image only when the viewer clicks a button, for instance. RealPix slideshows, on the other hand, always display images automatically according to the predefined RealPix timeline.

For More Information: For more on SMIL exclusive groups, see "Creating an Exclusive Group". Chapter 14 covers advanced SMIL timing.

Image Formats and Features

For a RealPix presentation, you can use illustrations, scanned images, or pictures taken with a digital camera. Images can be in JPEG, PNG, GIF, or animated GIF format. You'll likely need image editing software such as Adobe Photoshop to prepare images. You should know the basics of creating graphics for the Web, such as JPEG compression and GIF color palettes. When preparing your presentation, maintain three sets of images:

1. original set

The original set includes the unedited files you start with, such as original images off a scanner. Keep this set in case you need to change an image in the working set by, for example, restoring an area you cropped out. Leave these images uncompressed.

2. working set

The working set comprises the files that you have edited. You may want to crop the original images, for example, or combine them to form new images. Keep these files uncompressed so that you can edit them further if necessary.

Tip: Images do not need to be the same sizes. By default, RealPix expands or shrinks all images to fit a predefined display area.

3. presentation sets

A presentation set consists of the compressed files (GIF, JPEG, or PNG) used in the presentation. For a given working set, you may have several presentation sets. For instance, you may have slightly compressed images for a high-bandwidth presentation, heavily compressed images for a low-bandwidth version.

For More Information: The section "Images" provides details on the supported image formats. The section "Controlling an Animated GIF Image" explains how to start a GIF animating within a slideshow.

JPEGTRAN for JPEG Images

JPEGTRAN is a freeware program that optimizes JPEG (.jpg) images for streaming with RealPix. It modifies them so that if a packet of image data is lost, RealPlayer can still decode and display remaining packets. If you do not use JPEGTRAN on your images, RealPlayer cannot decode packets following a lost packet, and a substantial part of the image may not display. JPEGTRAN is included in the utilities folder of the zipped HTML version of this manual. You can also run JPEGTRAN from the RealPix bandwidth calculator, which is also included in the utilities folder.

Tip: Because running JPEGTRAN may increase or decrease the image file sizes slightly, run this program on your JPEG images before you calculate the image streaming times, as described in "Managing RealPix Bandwidth".

For More Information: See "How to Download This Guide to Your Computer" for instructions on getting a local copy of this guide.

Image Transparency

When you stream a RealPix slideshow to RealPlayer, transparent areas in GIF and PNG images show underlying images or background colors within the slideshow. Transparency does not extend to underlying SMIL regions, though. So if your RealPix presentation appears in front of a video in a SMIL presentation, the video does not show through transparent image areas.

RealPix Timelines

If your presentation consists solely of streaming RealPix images, you have full control over the RealPix timeline. When you combine RealPix with another clip such as RealAudio, however, you may want to display the RealPix images at specific points in the other clip's timeline. In these cases, finish the other clip first, then assemble your RealPix presentation so that it coordinates with the other clip's final timeline.

When working with an audio track, for example, think about the order of the images, deciding at which points in the audio timeline each image must display. When you are ready to assemble your RealPix presentation, play back the audio and note where you want to add each image. This will establish your RealPix timeline.

Once you have determined a timeline for your presentation, and have decided how to show the images, you are ready to create a RealPix presentation. You may find it easier to create a storyboard to lay out the images and transition effects. Or you may want to dive right in, using the presentation in progress as your guide. Either way, carefully consider the bandwidth implications as you place your images and set the start times and durations.

For More Information: See "Managing RealPix Bandwidth". The section "Step 5: Organize the Presentation Timeline" explains issues involved with multiclip timelines.

Structure of a RealPix File

A RealPix file is a plain text file that uses the file extension .rp. The RealPix markup starts with the <imfl> tag, and ends with the </imfl> tag. The following example shows a simple RealPix file with the most basic attributes. This sample simply fades in two images in sequence, then fades out to a solid blue:

<imfl>
    <head title="RealPix Example"
    copyright="(c)2002 RealNetworks, Inc."
    background-color="black"
    timeformat="dd:hh:mm:ss.xyz"
    duration="15"
    bitrate="12000"
    width="256"
    height="256"/>
  <!-- Assign handle numbers to images. -->
  <image handle="img1" name="rtsp://helixserver.example.com/image1.jpg"/>
  <image handle="img2" name="rtsp://helixserver.example.com/image2.jpg"/>
  <!-- Fade in images. -->
  <fadein start="1" duration="3" target="img1"/>
  <fadein start="4" duration="3" target="img2"/>
  <!-- Fade out to a solid blue. -->
  <fadeout start="8" duration="3" color="blue"/>
</imfl>

RealPix requires a <head/> tag that defines overall presentation attributes, such as the duration, the display area size, and the streaming bit rate. After the <head/> tag, <image/> tags define each image used in the presentation, and assign each image a unique ID (its "handle"). Effects tags such as <fadein/> select an image handle, and define the RealPix timeline through their start attributes. Not all effects specify an image, though. A <fadeout/> tag, for instance, specifies a fade color rather than an image handle.

Rules for RealPix Markup

The syntax rules for RealPix markup are similar to those for RealText and SMIL:

• RealPix tags and attribute names must be lowercase.
• A tag that does not have a corresponding end tag closes with a forward slash (/):

<fadein.../>

In RealPix, only the <imfl> tag, which uses the end tag </imfl>, does not close with a slash.

• Attribute values must be enclosed in double quotation marks.
• Unless noted otherwise, the order of attributes following the tag name does not matter.
• You can add a comment like the following to a RealPix file. Note that a comment tag does not require a closing slash:

<!-- This is a comment -->

RealPix Broadcast Application

You do not have to create RealPix slideshows through static markup files. A broadcast application can monitor a folder for new images, and broadcast them through Helix Server as part of a live RealPix presentation. A sample broadcast application is included with the Software Development Kit (SDK) available for download at this Web page:

http://proforma.real.com/rnforms/resources/server/realsystemsdk/ind ex.html

Managing RealPix Bandwidth

When you stream your RealPix presentation to viewers over a network, you need to consider the bandwidth (bit rate) the presentation will consume. You don't need to consider bandwidth if copies of the presentation files will reside on each viewer's desktop computer, however. This section helps you to determine your presentation's bandwidth usage, which can affect how you construct the RealPix timeline, and helps you decide how large to make your slideshow images.

Tip: The easiest way to calculate the streaming times for each image is to use the RealPix bandwidth calculator. This calculator is included in the utilities folder of the zipped HTML version of this manual. See "How to Download This Guide to Your Computer" for instructions on getting a local copy of this guide.

Estimating the Required Bandwidth and Preroll

The table "Maximum Streaming Rates" lists the maximum recommended streaming rates for different network connections. To reach viewers with 56 Kbps modems, for example, a presentation should not require more than 34 Kilobits of data per second. When you stream RealPix together with another clip, such as a soundtrack, you must take into account the bandwidth required by each clip. If you use a 16 Kbps RealAudio soundtrack, for instance, you have 18 Kbps left for RealPix images when streaming over 56 Kbps modems (34-16=18).

The bandwidth your RealPix presentation consumes depends on the total size of the image files and the presentation length. To get a rough estimate of this bandwidth, add together the sizes of all image files used in the presentation. Convert this total to Kilobits using the chart below. Then divide by the RealPix presentation length in seconds.

For example, if your image files add up to 200 Kilobytes, multiply 200 by 8 to get 1600 Kilobits. A presentation that lasts two minutes, for instance, uses an average of 13.3 Kilobits per second:

(200 Kilobytes x 8)/120 seconds = 13.3 Kilobits per second

If your RealPix target is 18 Kbps, your presentation should stream smoothly with bandwidth to spare. Suppose that the image files add up to 300 Kilobytes, however. In this case, the average streaming speed required is 20 Kbps, which exceeds the 18 Kbps target:

(300 Kilobytes x 8)/120 seconds = 20 Kilobits per second

This slideshow can still stream over a 56 Kbps modem, but it may have a longer preroll (initial buffering) than desired. RealPix calculates how much image data must stream to RealPlayer before the slideshow starts in order to keep the slideshow from rebuffering once it begins to play. In other words, if your slideshow has too much image data to stream during the length of its timeline, excess data streams before the slideshow starts to play. The viewer, though, must wait for this data to arrive before the slideshow can commence.

To illustrate the effects of preroll, suppose that you plan to stream a two- minute slideshow at 18 Kbps. This presentation can deliver 2,160 Kilobits of data (18 x 120). If the images add up to 300 Kilobytes (2,400 Kilobits), the presentation has an extra 240 Kilobits of data to stream. At 18 Kbps, this means 13 seconds or longer of preroll. In this situation, you can either accept the longer preroll, which may tempt viewers to quit the slideshow before it starts, or modify the slideshow to use less bandwidth.

For More Information: "Buffering" explains the basics of preroll. For tips on how to modify or manage preroll, see "Lowering RealPix Preroll" and "Masking Preroll With Other Clips".

Calculating Individual Image Streaming Times

Dividing the total image size by the presentation length provides only a rough estimate for preroll. It assumes that all images are about the same size, are streamed at regular intervals, and appear only once. You may still run into excess preroll, though, if you use large images, or a lot of images, early in the slideshow timeline. To prevent this, ensure that each image has enough time to stream to RealPlayer before it must display. The following table helps you to estimate how much time is required to stream an image over a 56 Kbps modem (maximum streaming rate of 34 Kbps), when you combine RealPix with various RealAudio soundtracks.

The table indicates that if you use an 8 Kbps RealAudio music soundtrack, for example, you have 26 Kilobits per second of bandwidth available for Realpix images. At this rate, it takes about 0.31 seconds to stream each Kilobyte of image data. If an image is 44 Kilobytes, for example, it requires about 13.6 seconds (44 x 0.31) to stream to RealPlayer. The first time this image appears in the slideshow, it should follow the preceding image by 14 seconds or more. For convenience, the last table column indicates how much image data can stream to RealPlayer approximately every five seconds.

Note: Once RealPlayer has received a RealPix image, it caches the image in memory, so you can reuse the image within the same slideshow without having to stream the image data again. RealPlayer deletes this cache when the slideshow ends.

Lowering RealPix Preroll

If your RealPix presentation requires excessive preroll, you can alter the images, modify the timeline, or both. Whenever you alter images, be sure to test that your slideshow retains acceptable image quality. The following are some tips for lowering the slideshow's bandwidth consumption:

• Crop out unnecessary portions of your images to reduce the image file sizes. The smaller the file, the faster it streams.
• Because an image automatically expands to fill the RealPix display area, you can reduce the image dimensions to lower its bandwidth requirement. You then let RealPlayer expand the image during playback.
• Reduce the resolution and number of colors in images while maintaining satisfactory image quality. For JPEG files, experiment with higher compression rates.
• Use smaller images at the beginning of the presentation. They will stream to RealPlayer faster, and Helix Server can use the extra bandwidth to start streaming larger files needed later.
• Introduce images gradually over the timeline. Don't use rapid effects with a lot of images at the beginning of the presentation. Once you have displayed all images, however, you can use rapid effects because RealPlayer holds the image data in memory.
• Increase the length of the presentation by, for example, adding an extra second to the start time of each effect.

Masking Preroll With Other Clips

You can stream a low-bandwidth clip ahead of your slideshow to mask the RealPix preroll. For example, you can start the presentation with a RealText clip that displays opening credits. Or you can use a low-bandwidth RealAudio voice clip as a narration. As these introductory clips play, Helix Server takes advantage of the extra bandwidth to stream the RealPix preroll. To set this up, you assemble the overall presentation using SMIL, placing all clips in a parallel group, and setting a delay for the RealPix clip with a begin attribute:

<par>
  <textstream src="credits.rt" region="credits_region" dur="15s" fill="remove"/>
  <ref src="slideshow.rp" region="slides_region" begin="15s"/>
</par>

For More Information: See Chapter 6 for more on RealText. The section "Playing Clips in Parallel" explains <par> groups. See "Setting Begin and End Times" for more on the begin attribute.

View it now! (requirements for viewing this sample) Play this sample to view a SMIL presentation in which a RealAudio clip and a RealText clip mask the RealPix preroll.

Setting Slideshow Characteristics

All information in the RealPix file falls between an opening <imfl> tag and a closing </imfl> tag. This is the only tag in the RealPix markup that uses an end tag. The <head/> tag follows the <imfl> tag in the RealPix file. Unlike the HTML <head> tag, the RealPix <head/> tag does not have a corresponding </head> tag. Instead, it closes with a slash:

<imfl>
  <head...attributes.../>
  ...RealPix images and transition effects...
</imfl>

The <head/> tag sets standard presentation information such as the title, author, and copyright. It also defines necessary parameters such as the presentation's duration and streaming bit rate. The following table summarizes all <head/> tag attributes. An asterisk (*) indicates a required attribute.

Defining the Presentation Size

The required width and height attributes set the size of the image display area in pixels. By default, all images are centered within this area, and enlarged or reduced so that no cropping occurs. The aspect attribute determines whether distortion may occur, though. The following example creates a RealPix playback area 256 by 256 pixels:

<head width="256" height="256".../>

When you stream just RealPix, RealPlayer's media playback pane expands to the specified size when the slideshow begins. When you play RealPix with another clip, you lay out playback regions with SMIL. You typically create for the slideshow a SMIL playback region that uses the same width and height set in the RealPix markup. If the SMIL region is a different size, the region's fit attribute determines how to handle the size difference, such as by scaling or cropping the entire display area.

For More Information: Chapter 12 describes SMIL layouts in general. See "Fitting Clips to Regions" for more on the fit attribute.

Specifying the Time Format

The timeformat attribute sets the format the for start and duration attributes used with RealPix effects. RealPix can specify time values in milliseconds or "normal play time" format, but not with SMIL shorthand timing values such as "2s". The default time format is milliseconds, which means that a time value such as 5400 is read as 5400 milliseconds (5.4 seconds). Millisecond time values cannot include colons or a decimal point.

You can also set timeformat to the normal play time format:

<head timeformat="dd:hh:mm:ss.xyz".../>

Here, dd is days, hh is hours, mm is minutes, ss is seconds, x is tenths of seconds, y is hundredths of seconds, and z is milliseconds. Only the ss field is required. With this format, for instance, duration="3" sets a three-second duration.

When the time value does not include a decimal point, the last field is read as the seconds. For example, 1:30 means 1 minute and 30 seconds, whereas 1:30:00 means 1 hour and 30 minutes. Note that with the normal play time format, all of the following values are equivalent. Each starts the effect 90 minutes after the RealPix presentation begins:

start="1:30:00.0"
start="90:00"
start="5400"

Setting the Presentation Duration

The required duration attribute sets the length of the entire RealPix presentation, using the time format specified in the timeformat attribute. For example, the following value sets a duration of 50 seconds:

<head timeformat="dd:hh:mm:ss.xyz" duration="50".../>

All RealPix effects stop immediately when the duration elapses. When the duration time exceeds the time required to complete the effects, the last effect stays frozen onscreen until the duration elapses.

Tips for Setting a RealPix Duration

• As you develop your RealPix presentation, set a high duration. Once you have finished the timeline, adjust the presentation duration. If you introduce the last image at 90 seconds into the timeline, for example, you may want to set a presentation duration of 95 seconds or higher.
• If your slideshow stops playing before all images have displayed, you probably need to increase the presentation duration, or change the timeformat attribute in the <head/> tag.
• RealPlayer reflects the duration you set. If you set a duration of five minutes, for instance, the RealPlayer status bar lists the presentation length as 5:00.0 and the RealPlayer position slider takes five minutes to travel from left to right.
• A presentation duration set much higher than the time it takes all images and effects to display may unnecessarily delay clips that play after the RealPix slideshow in a SMIL sequence. A high duration can also make it difficult for viewers to use the RealPlayer position slider to search for specific parts of the slideshow.
• Within a SMIL presentation, the SMIL dur attribute can shorten the time that the slideshow plays, effectively overriding the RealPix duration attribute. See "Setting Durations" for more about dur.

Controlling the Streaming Bit Rate

The required bitrate attribute specifies the maximum bandwidth the RealPix presentation consumes. Specify the value in bits per second (bps). For example, the following value sets a maximum bandwidth of 12000 bps (approximately 12 Kbps):

<head bitrate="12000".../>

Tip: To convert precisely from Kilobits per second to bits per second, multiply by 1024.

For More Information: "Managing RealPix Bandwidth" explains how to calculate bandwidth requirements for a RealPix presentation.

Defining the Title, Author, and Copyright

The optional title, author, and copyright attributes define information for the RealPix presentation:

<head title="My RealPix Slideshow" author="Pat Morales" 
  copyright="(c) 2002 RealNetworks Media Productions".../>

When present, these attributes define the values that display for the RealPlayer clip information (File>Clip Properties>View Clip Info). If the RealPix presentation is played through a SMIL file, however, title, author, and copyright information set through SMIL may override the information you set here.

For More Information: See "Where Title, Author, and Copyright Information Displays".

Creating a Background Color

The optional background-color attribute sets an initial background color. The default color is black. RealPix backgrounds can use color names, which are listed in "Using Color Names", or hexadecimal color values, which are described in "Defining Hexadecimal Color Values". RealPix does not support RGB colors in the format rgb(n,n,n), however. The following example sets the initial background color to a shade of red:

<head background-color="#E00000".../>

Note: In RealPix, background-color is hyphenated. In SMIL 2.0, the backgroundColor attribute for regions uses camel case.

Tip: During the course of a slideshow, you can change the background color with the <fill/> tag, which is described in the section "Painting a Color Fill".

Setting a Preroll Value

The optional preroll attribute specifies the time to buffer data in RealPlayer before the start of the RealPix presentation. The following example sets the RealPix preroll to 40 seconds:

<head preroll="40".../>

Helix Server always calculates the preroll required for the presentation based on the image file sizes and presentation timing parameters. If this calculated value is larger than the preroll you set, it overrides your specified preroll. Your preroll value is used, however, if it is higher than the calculated preroll value. You therefore need to set the preroll value only if you want an artificially high preroll.

A high preroll can be useful when you stream RealPix with another clip. Suppose that a RealVideo clip starts midway through a RealPix presentation. You can use a high preroll to download a significant portion of the RealPix data before the presentation starts. The RealVideo clip then has more bandwidth available when it begins. It can therefore stream its required preroll without competing with RealPix for bandwidth.

Tip: Always balance preroll values with viewer expectations. Viewers may not stay tuned to a presentation that takes a long time to start playing back. To determine the preroll for a clip streamed in parallel with your slideshow, such as an audio soundtrack, open the clip in RealPlayer, and use File>Clip Properties>Clip Source to view the buffering information.

For More Information: For more on preroll, see "Estimating the Required Bandwidth and Preroll".

Adding a Presentation URL

The optional url attribute sets a hyperlink URL for the presentation. When the viewer clicks a presentation image, the RealPix presentation continues to play as the URL opens in the RealPlayer media browser pane, or, with earlier versions of RealPlayer, in the viewer's default Web browser. Individual effects can also include a url attribute that overrides the presentation-wide value for the duration of the effect. For the attribute value, use a fully qualified URL such as the following:

<head url="http://www.real.com".../>

For More Information: You can also use the url attribute to open a streaming presentation in a new RealPlayer media window. See "Opening a Media Playback Window with a Clip Link".

Handling Image Aspect Ratios

With its default value of true, the aspect attribute keeps an image at its normal width-to-height ratio when the width and height attributes in the <head/> tag create a different width-to-height ratio for the playback area. In this case, images are displayed as large as possible in the playback area without cropping and distortion. The background color or the preceding image appears in the areas not covered by the new image. You can turn this off by setting the attribute to false:

<head aspect="false".../>

In this case, RealPlayer fills the defined playback area with each image, which distorts any images that have width-to-height ratios different from the display area. Images are never cropped, however. The following figure shows how a source image fills a display area differently when aspect is set to false or true.

Effects of Overriding and Maintaining Image Aspect Ratios

Note: The aspect attribute in the <head/> tag affects the entire presentation, but individual effects can override this setting with their own aspect attributes, as described in "Changing an Image's Aspect Ratio".

View it now! (requirements for viewing this sample) This sample shows the effects of ignoring and maintaining image aspect ratios.

Setting the Maximum Frames Per Second

The optional maxfps attribute specifies an integer from 1 to 30 that sets the maximum frames per second (fps) for RealPix transition effects:

<head maxfps="5".../>

This attribute is not required because RealPlayer determines the optimal frame rate based on the playback computer's available CPU power. When CPU power is plentiful, RealPlayer renders transition effects at the maximum of 30 fps. It scales down the transition rates accordingly when less CPU power is available.

You can set the maxfps attribute low to create special effects, though. For example, maxfps="5" keeps transitions constrained to no more than 5 fps. This causes visible jerks in transitions, which may be a desirable effect. Additionally, you can use maxfps in RealPix transition tags to balance CPU usage between multiple RealPix slideshows played simultaneously in a SMIL presentation.

For More Information: Individual effects can override the presentation value with their own maxfps values. See "Capping an Effect's Frame Rate".

View it now! (requirements for viewing this sample) This sample displays images at a progressively faster maximum frame rate.

Defining Images

For each image you use in the RealPix presentation, you add an <image/> tag after the <head/> tag. The <image/> tag provides the image file location, and assigns the image a unique handle number. The following table summarizes the <image/> tag attributes. An asterisk (*) denotes a required attribute.

Creating an Image Handle

The required handle attribute assigns a positive integer to the image. Each handle number within the file must be unique. The RealPix effects tags refer to the handle number, rather than the file name, in their target attributes. Here is an example of an image handle:

<image handle="18".../>

that an effects tag refers to when fading in the image:

<fadein target="18".../>

Although it is not required, you may find that using sequential handle numbers, as well as listing <image/> tags according to the handle numbers, helps you to keep the organization of your presentation clear:

<image handle="1".../>
<image handle="2".../>
<image handle="3".../>

Note: It is not necessary to follow the handle order when defining the timeline. The image with handle="3" might appear first, followed by the image with handle="1".

Specifying an Image File Name and Path

The required name attribute specifies the image file name, along with its path relative to the location of the RealPix file. The file name and path are case sensitive. When streaming files from Helix Server, folder (directory) names must not contain spaces. The following example designates an image file that resides in the same folder as the RealPix file:

<image name="tulip.jpg".../>

Image files can also reside in folder levels below (but not above or adjacent to) the RealPix file. This next example indicates that the image file resides one level below the RealPix file in the images folder:

<image name="images/tulip.jpg".../>

Streaming the Presentation

The local, relative paths for the name attribute allow you to develop and test your RealPix slideshow locally. You do not need to change the name values when you are ready to stream your slideshow. In a Ram or SMIL file, you simply use an HTTP or RTSP URL to request the RealPix file. The images automatically use the same protocol used to request the RealPix file.

Keeping All Files on the Same Server

Unlike a SMIL presentation, in which various clips can reside on different servers, RealPix requires that the RealPix file and all image files stay on the same server. This is because Helix Server reads the RealPix file and determines the image file sizes to calculate how much preroll it must stream to RealPlayer before the slideshow can begin.

Using Absolute, Local URLs

If you are developing a presentation that plays back locally for all viewers (rather than streams from a server), you can use absolute, local URLs in the following format, which includes three forward slashes in file:///, and uses forward slashes in path names as well:

file:///C:/My Documents/Images/picture1.jpg

Indicating the Image Size for Web Servers

The optional size attribute, which works only with RealPlayer 7 or later, specifies the size of the image in bytes. Include it in the <image/> tag when delivering a RealPix presentation with a Web server. RealPlayer can then determine when to request each image file from the Web server to ensure smooth playback. Here is an example of an image file approximately 24 KB in size:

<image size="24000".../>

The size attribute is not required when streaming a RealPix presentation from Helix Server, which determines image sizes directly through the files. It then calculates when to stream each image to ensure smooth playback for the viewer's given bandwidth.

Note: Be careful to list the file sizes correctly. If the file is significantly larger than the value given by its size attribute, the presentation may stall.

Setting the Mime Type

The optional mime attribute works with RealPlayer 7 and later. It specifies the image mime type, and may be necessary when delivering a RealPix presentation with a Web server. Here is an example:

<image mime="image/jpeg".../>

The following are the valid mime types you can use:

Helix Server typically determines the MIME type from the image file's extension, such as .gif or .jpg, making the mime attribute unnecessary. You need to include the mime attribute only on these two conditions:

• <image/> tags use the size attribute

—and—

• the <image/> tag's name attribute supplies a file name that does not include a file extension.

Using Common Transition Effects Attributes

Most RealPix transition effects tags, which are described in "Creating RealPix Transition Effects", use a common set of attributes that select an image, indicate when the effect occurs within the RealPix timeline, set the effect duration, and so on. The following table summarizes these attributes. The sections on each RealPix tag indicate which of these attributes an effect requires, or can optionally include.

Setting an Effect Start Time

The start attribute is required for all RealPix effects. It specifies the time from the beginning of the RealPix timeline that the effect occurs. Here is an example that starts a crossfade at 12.3 seconds into the timeline:

<crossfade start="12.3".../>

The individual start times create the timeline for the individual effects, while the <head/> tag's duration attribute sets the overall presentation time. If your last start time is 180, for example, make sure that the duration attribute set in the <head/> tag is greater than 180. For more on this, see "Setting the Presentation Duration".

Note: To specify start and duration values in seconds, you must set timeformat="dd:hh:mm:ss.xyz" in the <head/> tag. Otherwise, a value such as start="12" means 12 milliseconds. For more on the time format, see "Specifying the Time Format".

Specifying an Effect Duration

The duration attribute in an effect tag is unrelated to the duration attribute in the <head/> tag. In an effect tag, the duration attribute specifies the total time for the effect to complete. The higher the value, the slower the effect. For example, the following value causes the fade to complete in 2.5 seconds:

<fadein start="12" duration="2.5".../>

The duration attribute affects only a transition effect, and does not control how long an image or color fill displays. The subsequent effect's start attribute controls how long the image or color fill displays. Consider this example:

<fadein target="5" start="12" duration="3".../>
<fadein target="6" start="18" duration="4".../>

Here, image 5 starts to fade in at 12 seconds into the RealPix timeline. The fadein finishes at 15 seconds (12+3). The image then displays stationary for three seconds when, at 18 seconds into the timeline, image 6 begins to fade in. The second fadein completes at 22 seconds into the timeline (18+4). At that point, image 6 has completely replaced image 5.

Selecting the Image Target

The target attribute is required for effects that introduce images. It specifies the <image/> tag handle of the image, which is described in "Creating an Image Handle". For example, if tulips.jpg is defined with the following <image/> tag:

<image handle="2" name="tulips.jpg"/>

you fade tulips.jpg into the presentation by targeting the handle number:

<fadein target="2".../>

Creating an Effect URL

The url attribute sets a hyperlink URL that is valid for as long as the image displays, overriding the URL set through the <head/> tag, which is described in "Adding a Presentation URL". When the viewer clicks the image, the RealPix presentation continues to play as the URL opens in the RealPlayer media browser pane, or, with earlier versions of RealPlayer, in the viewer's default Web browser. Use a fully qualified URL like the following:

<fadein url="http://www.real.com".../>

For More Information: Note that you can use the url attribute to open a streaming presentation in a new RealPlayer window. See "Opening a Media Playback Window with a Clip Link" for more information.

Opening URLs Automatically

The URLs specified by url attributes open only when clicked. However, when you stream a RealPix presentation to RealOne Player or later, you can use SMIL 2.0 to open HTML URLs automatically. You might open a different HTML page after each image displays, for example. To do this, create a SMIL 2.0 file that plays the RealPix presentation, and includes timed <area/> tags that open automatically through the actuate="onLoad" attribute. See "Linking to HTML Pages" for more information.

Tip: You'll need to take into account the bandwidth required to open HTML page URLs as you plan your RealPix slideshow. Otherwise, the slideshow may pause as each page opens.

View it now! (requirements for viewing this sample) This sample uses SMIL 2.0 to open a separate HTML page for each slide.

Changing an Image's Aspect Ratio

You can set the optional aspect attribute to true or false in an effect tag to override the aspect attribute set in the <head/> tag, which is described in "Handling Image Aspect Ratios". The image introduced with the effect then appears undistorted (aspect="true") or distorted (aspect="false") if it has a different width-to-height ratio than the display area. Here is an example:

<crossfade aspect="false".../>

View it now! (requirements for viewing this sample) This sample shows the effects of ignoring and maintaining image aspect ratios.

Capping an Effect's Frame Rate

The optional maxfps attribute specifies an integer from 1 to 30 that sets the maximum frames per second for the effect. It overrides any default maxfps value set in the <head/> tag, which is described in "Setting the Maximum Frames Per Second". Here's an example:

<fadein maxfps="5".../>

View it now! (requirements for viewing this sample) This sample displays images at a progressively faster maximum frame rate.

Creating RealPix Transition Effects

The following sections describe the RealPix tags that you use to introduce images, display transition effects such as fades, and create special effects such as zooms. The section "Using Common Transition Effects Attributes" describes the standard attributes used in many of these effects tags.

Fading In on an Image

The <fadein/> tag creates a gradual transition from the currently displayed color or image to another image. A <fadein/> tag looks like this:

<fadein start="4" duration="3" target="2"/>

The following figure illustrates a fade from a solid color to an image.

Fade from a Solid Color to an Image

The following table summarizes the attributes that you can use in a <fadein/> tag. An asterisk (*) denotes a required attribute.

Tip: You can fade in multiple images simultaneously. RealNetworks recommends that these images do not overlap, however, because the appearance may be unpredictable.

View it now! (requirements for viewing this sample) Play this sample to watch a simple slideshow of fadein effects. The next sample demonstrates more creative uses of fades.

Fading an Image Out to a Color

The <fadeout/> tag defines a transition from an image to a color. You can use a predefined color name or a hexadecimal value, as described in Appendix C. RealPix does not support RGB colors in the format rgb(n,n,n), however. The following example fades the RealPix display area to yellow:

<fadeout start="10" duration="3" color="yellow"/>

The following figure illustrates a fade to a solid color.

Fade from an Image to a Solid Color

The following table summarizes the attributes that you can use in a <fadeout/> tag. An asterisk (*) denotes a required attribute.

View it now! (requirements for viewing this sample) This sample lets you watch fade out examples.

Crossfading One Image Into Another

The <crossfade/> tag creates a transition from one image to another, as illustrated in the following figure. An image should be displaying in the RealPix area already when you use a crossfade to specify a new image:

<crossfade target="4" start="15" duration="4"/>

Crossfade from One Image to Another

The following table summarizes the attributes that you can use in a <crossfade/> tag. An asterisk (*) denotes a required attribute.

Painting a Color Fill

The <fill/> tag paints a colored rectangle instantly. Use it anytime you want to fill all or part of the display area. You can fade in an image, for instance, then fill the display area with a color that paints over the image. You can use a predefined color name or a hexadecimal value, as described in Appendix C. RealPix does not support RGB colors in the format rgb(n,n,n), however. A <fill/> tag looks like this:

<fill start="9" color="#23A134"/>

The following table summarizes the attributes that you can use in a <fill/> tag. An asterisk (*) denotes a required attribute.

Creating a Wipe Effect

The <wipe/> tag creates a transition from one image to another, either by having the second image slide over and cover the first image, or by having it push the first image out of the display area. A typical <wipe/> tag looks like this:

<wipe type="push" direction="left" start="10" duration="3" target="2"/>

The following figure illustrates this effect.

"Push" Wipe Transition from One Image to Another

The following table summarizes the attributes that you can use in a <wipe/> tag. An asterisk (*) denotes a required attribute.

View it now! (requirements for viewing this sample) Play this sample to watch a simple slideshow of wipe effects. The next sample uses a SMIL file to create brush objects, which are described in "Creating a Brush Object", to change the slideshow "background" dynamically. The last sample demonstrates more creative uses of wipe effects.

Setting the Wipe Type

The required type attribute defines the type of transition that occurs:

Here is an example:

<wipe type="push".../>

Choosing the Wipe Direction

The required direction attribute sets the direction the new image moves:

For example:

<wipe direction="up".../>

Controlling an Animated GIF Image

When you display an animated GIF image in a RealPix slideshow, the GIF does not automatically begin to animate. Instead, you use the <animate/> tag to start the GIF cycling through its frames. This lets you control when the animation starts, and how long it lasts. An <animate/> tag looks like this:

<animate start="10" duration="30" target="2"/>

The following table summarizes the attributes that you can use in a <animate/> tag. An asterisk (*) denotes a required attribute.

If you introduce an animated GIF into the presentation with <animate/>, the GIF appears instantly at its start time, with no transition effect. However, you can also introduce the GIF with another tag, such as <fadein/>, then use <animate/> to start the animation. Here's an example:

<fadein start="5" duration="1" target="2"/>
<animate start="10" duration="30" target="2"/>

In this example, the animated GIF fades in at five seconds into the timeline. Its first frame remains stationary until 10 seconds into the timeline. The GIF then cycles through its programmed animation sequence for 30 seconds.

Note: The RealPix <animate/> tag is not related to the <animate/> tag used in SMIL animations, which is described in "Animation Tags".

View it now! (requirements for viewing this sample) This sample fades in an animated GIF, starts the animation, and fades out.

Zooming In, Zooming Out, and Panning

The <viewchange/> tag defines a pan or a zoom. It requires the use of the source and destination attributes described in "Controlling Image Size and Placement". A typical <viewchange/> tag looks like this:

<viewchange start="24" duration="3" srcx="80" srcy="80" srcw="48" srch="48"/>

Note that <viewchange/> does not specify an image. The view change always affects the image currently in the display area. The following figure illustrates a zoom created with a <viewchange/> tag.

Zoom Effect Created with a View Change

The following table summarizes the attributes that you can use in a <viewchange/> tag. An asterisk (*) denotes a required attribute.

View it now! (requirements for viewing this sample) With this sample, you can watch pan and zoom examples.

Zooming In on an Image

To zoom in on an image, display the image and then use <viewchange/> to define a source rectangle to zoom in on. The following example is taken from a RealPix presentation that displays in an area 256-by-256 pixels. The source image is also 256-by-256 pixels. The presentation fades in on the image and then zooms in, taking three seconds to complete the zoom:

<fadein start="1" duration="2" target="1"/>
<viewchange start="4" duration="3" srcx="64" srcy="64" srcw="128" srch="128"/>

The zoom selects a source rectangle that is 128-by-128 pixels, and that appears in the center of the source image. This source rectangle displays in the full 256-by-256-pixel display area. The following figure illustrates this zoom.

Zooming in on Part of an Image

Because this zoom effect does not specify a destination rectangle, the zoom image fills the entire display area. But you can also use the destination coordinates (dstx, dsty, dstw, dsth) to specify a destination rectangle within the display area.

Panning Across an Image

To pan across an image, display a portion of the source image, then use <viewchange/> to move to a different part of the source image. The following example uses a RealPix presentation that displays in an area 256-by-256 pixels. The source image is also 256-by-256 pixels:

<fadein start="1" duration="3" target="2"/>
<viewchange start="4" duration="3" srcx="0" srcy="0" srcw="128" srch="128"/>
<viewchange start="7" duration="3" srcx="128" srcy="0" srcw="128" srch="128"/>

The presentation fades in an image, zooms in on the upper-left quadrant, then pans to the upper-right quadrant. Each effect takes three seconds to complete. The following figure illustrates this movement.

Zooming in on, then Panning across an Image

Because this pan effect does not specify a destination rectangle, the source rectangle fills the entire display area. But you can also use the destination coordinates (dstx, dsty, dstw, dsth) to specify a destination rectangle within the display area.

Controlling Image Size and Placement

When RealPlayer plays a RealPix slideshow, it expands its media playback pane to the size defined by the <head/> tag's width and height attributes. To create a simple presentation such as a basic slideshow, you can simply fade the images in and out of this display area. Images the same size as the display area appear full-size. Larger images shrink to fit the area, smaller images expand.

You may want to display just a portion of a source image, however. Or you may want to display two images side-by-side. RealPix lets you specify a portion of a source image that appears in the display area. It also lets you determine the size and placement of images in the display area. To understand how this works, keep in mind the following definitions:

Source Image

An image used in your slideshow. A presentation may display one source image at a time, or it may display several source images arranged in a checkerboard pattern, for instance.

Source Rectangle

The portion of a source image you want to display. You might want to display only the top half of a source image in the display area, for example. Think of the source rectangle as a cropped version of a source image that you can display in a RealPix slideshow without altering the source image.

Display Area

The part of the RealPlayer media playback pane in which your presentation plays back. You set the display area size with the RealPix <head/> tag's width and height attributes, as described in "Defining the Presentation Size".

Destination Rectangle

A portion of the display area where the source rectangle appears, such as the area's upper-left quadrant. Keep in mind that a destination rectangle does not have to have the same size or proportions as a source rectangle.

Defining Source and Destination Attributes

To use just a portion of a source image or the display area for an effect, you define the source rectangle, destination rectangle, or both in an effect tag. To do this, you work with the attributes described in the following table.

The offset attributes (dstx, dsty, srcx, and srcy) default to zero. The destination rectangle size attributes (dstw and dsth) default to the display area width and height. The source rectangle size attributes (srcw and srch) default to the source image width and height. This means that if you leave the source attributes out of a tag, the entire source image is used. If you leave the destination attributes out of a tag, the selected image portion fills the entire display area.

Note: The aspect attribute, described in "Handling Image Aspect Ratios", determines how an image appears when the source and destination rectangles have different width-to- height ratios.

Exhibiting Part of an Image in the Entire Display Area

In the example below, both the source image and display area are 256 pixels high by 256 pixels wide. The source rectangle tags display the upper-left quadrant of the source image in the display area, effectively magnifying the source rectangle by a factor of 2. Because the destination rectangle defaults to the display area size, no destination rectangle coordinates are needed.

Part of the Source Image Filling All of the Display Area

To introduce this image with a fade, for example, you add the source attributes to the <fadein/> tag:

<fadein start="4" duration="3" target="2" srx="0" srcy="0" srch="128" srcw="128"/>

Showing All of an Image in Part of the Display Area

In the next example, the source image displays in the upper-right quadrant of the display area, effectively reducing the size of the source image by half. No source coordinates are included, so the entire source image displays in the destination rectangle.

All of the Source Image Filling Part of the Display Area

To paint the background, then wipe this image into the display area, for instance, you use a <fill/> tag followed by a <wipe/> tag that includes the destination attributes:

<fill color="#E7651A" start="9"/>
<wipe type="push" direction="down" start="10" duration="3" target="2" 
dstx="128" dsty="0" dsth="128" dstw="128"/>

Filling Part of the Display Area with Part of the Source Image

This example shows a portion of the source image displayed at a slightly larger size in the display area. In this case, both source and destination coordinates are needed to define the source and destination rectangles.

Part of the Source Image Filling a Part of the Display Area

To introduce this image with a fade, for example, you add the source and destination attributes to the <fadein/> tag:

<fadein start="1" duration="2" target="5" srx="0" srcy="0" srch="128"