Introduction#

Let’s start simple, with the file minimal.asd:

<asdf version="0.4">
  <clip file="audio/ukewave.ogg" pos="1 2" />
</asdf>

This plays the contents of the (mono) audio file audio/ukewave.ogg, coming from a spatial position of 2 meters in front and 1 meter to the right. For more details on the used coordinate system, see Position and Orientation.

If you want to play a file with more than one channel, you can provide positions for each of the channels, like shown in minimal-multichannel.asd:

<asdf version="0.4">
  <clip file="audio/marimba.ogg">
    <channel pos="-1 2" />
    <channel pos="1 2" />
  </clip>
</asdf>

This plays the contents of the (two-channel) audio file audio/marimba.ogg, each channel coming from its specified position. For further details, see <clip> and <channel>.

The examples above use a few shorthand notations to make frequently used scenarios a bit easier to type. Expanding most of the shortcuts used in the first example above would lead to the more complicated ASDF syntax shown in minimal-expanded.asd:

<?xml version="1.0"?>
<asdf version="0.4">
  <head>
    <source id="src1" />
  </head>
  <body>
    <seq>
      <clip file="audio/ukewave.ogg">
        <channel source="src1" pos="1 2 0" />
      </clip>
    </seq>
  </body>
</asdf>

Please note a few changes to the “minimal” version above:

  • An XML declaration has been added, which is optional in XML 1.0 (but not in XML 1.1).

  • The <head> and <body> elements are optional. The <asdf> element (including version number) is always required.

  • In the <head> section there is a separate <source> element.

  • The <body> element implicitly behaves like a <seq> element, see <seq> and <par>.

  • Even though this is not necessary for a mono <clip>, a <channel> element has been provided explicitly. It has been associated with the <source> that was defined in <head>.

  • The z-component in pos is optional, see <transform>.

This still uses the shorthand of specifying the position directly in the <channel> element. As shown in minimal-expanded-with-explicit-transform.asd, it can be expanded even further:

<?xml version="1.0"?>
<asdf version="0.4">
  <head>
    <source id="src1" />
  </head>
  <body>
    <par>
      <clip file="audio/ukewave.ogg">
        <channel id="channel1" source="src1" />
      </clip>
      <transform apply-to="channel1" pos="1 2 0" />
    </par>
  </body>
</asdf>

  • Because the <clip> and the <transform> happen at the same time, they are wrapped in a <par> element, see <seq> and <par>. Without this <par> element, the <transform> would only be active after the <clip> is finished (because the <body> element implicitly behaves like a <seq> element).

  • If the clip has only one channel, it doesn’t matter whether the <transform> is applied to the <clip> or to the <channel>. In this simple case it could be even directly applied to the <source>.

  • The <transform> element could be even further expanded to contain the pos information in a single <o> sub-element.