Appendix B: SMIL Syntax

This appendix explains the structure of SMIL file, as well as the syntax rules for writing SMIL markup. Understanding these rules will help you to avoid the common problems that media authors encounter when developing SMIL presentations.

View it now! (requirements for viewing this sample)
This sample demonstrates the basic aspects of writing a SMIL 2.0 file.

SMIL Extension and File Names

A SMIL file is a simple text file that you can create with any text editor. As with a Ram file, make sure that you can save your output as plain text. Your SMIL file should have a simple name without spaces, and end with the extension .smil, as in my_smilfile.smil.

Tags, Attributes, and Values

SMIL tags that come in pairs follow this form:

<tag attribute="value"...> ... </tag>

There are three basic parts to these SMIL tags:


tag	In the first tag of a pair, the tag name comes just after a left angle bracket. Some tags may consist of just the name, as in the `<body>` tag. Other tags may have attributes. The last tag of a pair consists of just the tag name preceded by a slash, as in `</smil>`. A closing tag never has attributes.
`attribute`	Each attribute defines one aspect of the tag. If a tag has several attributes, the order of attributes doesn't matter. Attributes are typically predefined for a tag. The `<smil>` tag can include certain attributes, for example, while a `<seq>` tag can include different attributes. You'll get an error message from RealPlayer if you include an attribute that doesn't work with a tag.
`"value"`	Most SMIL attributes include an equals sign (=) followed by a value that must always be enclosed in double quotation marks. In some instances, you choose from a list of predefined values. In other cases, you define your own value. Values may be integers, percentages, names, and so on, depending on what types of values are appropriate for the attribute.

End Tags for Tag Pairs

If you're familiar with HTML, you know that browsers often let you be sloppy with end tags. For example, paragraphs in HTML should come between  and  tags, but most browsers allow you to leave out the closing  tag. SMIL doesn't let you get away with sloppiness, though, and you'll get an error message if you leave out a closing tag.

Closing Slash for Single Tags

If the tag is not part of a tag pair, as in <head> and </head>, it must close with a forward slash, as in <meta/>. The forward slash tells RealPlayer that everything it needs to know about this tag is contained within the tag's angle brackets, and it doesn't need to hunt for a closing tag. In general, tag pairs create sections, such as the header section or body section, while single tags describe specific actions, such as "display this title," or "play this video clip."

Tag and Attribute Case Sensitivity

Tag names, attributes, and many values are case-sensitive. This is another area where SMIL, unlike HTML, is strict. In HTML, for example, a paragraph tag can be  or . But in SMIL, the <smil> tag cannot be <SMIL>, <Smil>, <smIL>, or any variation except entirely lowercase. Just make sure that you write tags and attributes exactly as they appear in this guide.

Tag ID Values

Any SMIL tag can have an ID in the form id="value". Some SMIL tags require IDs. For example, each region in the layout requires an ID that you use to assign clips to play in the region. For other tags, IDs are optional depending on whether another SMIL element interacts with that tag. The following are rules and suggestions that apply to the IDs of all SMIL tags:

All IDs for all tags in a SMIL file must be unique. If you define several <region/> tags, for example, each tag must have a unique ID. No <region/> tag can have the same ID as a <video/> tag, for instance.

As with all SMIL values, IDs are case-sensitive. The attributes id="videoregion" and id="videoRegion" are different, for example. It is a good idea to follow a consistent practice, such as always making IDs lowercase.

Do not use words separated by spaces in an ID. If you use two or more words for an ID, combine the words, or separate the words with an underscore or hyphen, as in videoregion, video-region, or video_region.

The first character for an ID can be a letter, a colon, or an underscore. It cannot be a number or a special character such as an ampersand. You can use numbers and special characters after the first character, however. For example, you can use id="video3" as an ID, but not id="3video".

There is no minimum or maximum length for IDs.

You may find it convenient to adopt a system for specifying IDs. You might use the suffix _region for all region IDs, for example.

The SMIL Tag

The first and last lines of a SMIL 2.0 file for RealPlayer are these:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">
  ...
</smil>

SMIL 2.0 Namespace

The <smil> tag has one long, necessary attribute:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language" ...>

This attribute indicates that the file contains SMIL 2.0 markup. If you leave this attribute out and use just the tag name (<smil>), you're defining a SMIL 1.0 file, and many of the features described in this guide won't work. In other words, you must include this attribute and value exactly as shown above for a SMIL 2.0 file to work.

Note: Although the SMIL 2.0 and RealNetworks extension namespaces are valid HTTP URLs (you can open them in your browser), RealPlayer does not request these Web pages when it plays a SMIL 2.0 file.

RealNetworks Extension Namespace

To use SMIL 2.0 features customized for RealPlayer, you need to include the RealNetworks namespace in the <smil> tag:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">

Customized attributes such as rn:sendTo must share the rn: prefix used by this namespace. Although you do not have to declare this namespace if you do not use the customized attributes, it is safe to include this namespace in any SMIL 2.0 file, even those played by SMIL-based players other than RealPlayer. If a SMIL-based player does not recognize a customized namespace and its associated attributes, it simply ignores them.

The Header Section

In a SMIL file, a header section typically follows the <smil> tag. The header section falls between <head> and </head> tags. Unlike the <smil> tag, the <head> tag never includes attributes:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">
  <head>
    <meta name="title" content="My First SMIL File"/>
    <meta name="author" content="Pat Morales"/>
    <meta name="copyright" content="(c)2001 Spectacular Media Limited"/>
    <layout>
      <root-layout width="320" height="240"/>
      <region id="video_region"/>
    </layout>
  </head>
  ...body section...
</smil>

The Body Section

The body section is the companion to the header section, following it in the SMIL markup. Together, the body and header define all of your presentation features. Whereas the header describes the presentation's form, the body delivers the content. Like the header section, the body section has a start tag and an end tag, <body> and </body>, that do not take any attributes:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">
  ...header section...
  <body>
    <seq>
      <!-- The following clips play in sequence. -->
      <audio src="rtsp://helixserver.example.com/song1.rm"/>
      <audio src="rtsp://helixserver.example.com/song2.rm"/>
      <audio src="rtsp://helixserver.example.com/song3.rm"/>
    </seq>
  </body>
</smil>

Indentation and Line Returns

In the examples in this guide, each tag starts on a new line, and the entire file uses indentation, which is highly recommended for all SMIL markup. For example, the first lines of a SMIL file might look like this:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
  <head>
    <meta name="title" content="My First SMIL File"/>

Each line is indented from the preceding line to indicate that the new tag is part of the preceding section. The <meta/> tag is part of the <head> section, and the <head> section is part of the <smil> section.

Savvy authors always indent their markup to clarify the file's organization, typically pressing Tab once for each level of indentation. The only purpose for this is to help you, and anyone else reading your file, to understand how the file works. RealPlayer doesn't care about tabs and line returns, though. It has no problem figuring out how the following file works, but can you say the same?

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"><head><meta
name="title" content="My First SMIL File"/><meta name="author" content="Pat
Morales"/><meta name="copyright" content="(c)2001 Spectacular Media
Limited"/></head><body><seq><!-- The following clips play in sequence. ->
<audio src="song1.rm"/><audio src="song2.rm"/><audio src="song3.rm"/></seq>
</body></smil>

Comments

In a SMIL file, you can add a comment like the following:

<!-- The following clips play in sequence. -->

Note that this tag does not require a closing slash. If you know HTML, you've probably guessed why this is: this isn't a SMIL tag at all. This is an HTML- style comment tag. This tag is so widely used in HTML that SMIL adopted it wholesale.

As with indentation, comment tags don't affect your presentation. RealPlayer ignores them, and their only purpose is to annotate your file. Even with indentation, complex SMIL files can be hard to figure out. Comments let you describe what's going on in the file, and can be extremely helpful for explaining markup to others, or even reminding yourself of how the file works. You can even comment out whole sections of SMIL markup if you don't want RealPlayer to play that section.

Note, though, that the hyphens in a comment tag aren't decoration. The comment must start with these four characters:

<!--

and end with these three characters:

-->

Between these begin and end marks, the comment can be as long as you like. You cannot put one comment inside another comment, though.

Summary of SMIL Syntax

To create SMIL 2.0 files, the <smil> tag must declare the SMIL 2.0 namespace:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language">

Many attributes specific to RealPlayer use an rn: prefix, as in rn:sendTo. Using these attributes requires that you also declare the RealNetworks customizations namespace in the <smil> tag:

<smil xmlns="http://www.w3.org/2001/SMIL20/Language"
xmlns:rn="http://features.real.com/2001/SMIL20/Extensions">

A SMIL header section, defined between <head> and </head> tags is optional, though highly recommended.

The SMIL body section, defined between <body> and </body> tags, is required.

Tags and attributes are case-sensitive, so you need to write them exactly as shown in this guide.

Attribute values must be enclosed in double quotation marks.

All tags either must be paired with an end tag, as in <body> and </body>, or must close with a forward slash, as in <audio/>.

All id attribute values within a SMIL file must be unique. An id value cannot start with a number.

Use indentation to clarify how your SMIL file is organized.

Use HTML-style comments to annotate your SMIL file:

<!-- This is a comment. -->