Skip to main content

Add Audio

Abstract

You can add links to audio files in your topics so that they can be played in published HTML outputs. The audio files must be hosted elsewhere, for example, in a repository.

You can add links to external audio sources in your topics (these must be audio files hosted elsewhere, you cannot upload audio files to Paligo). When you publish to HTML, the page for the topic will include a player that you can use to play the audio file.

An audio player for a web page. It has a play icon on the left, a time value to show the current position and the total running time, and audio level control.

Note

If you publish to PDF, the page will include a link to the audio file.

To add a link to an external audio source:

  1. Create a new topic or edit an existing one by selecting it in the Content Manager.

  2. Position the cursor at a valid position for a mediaobject element. For example, on the next line after a para element.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter mediaobject and select it from the menu.

    When you add a mediaobject element, it contains an imageobject by default.

    Topic containing a mediaobject element. There is an image shown by default and the image has imageobject and imagedata elements. These are inside the mediaobject element.

  5. Select the imageobject element in the Element Structure Menu and choose Delete.

    The imageobject element is selected and this reveals a menu. On the menu, the delete option is highlighted.

    You are left with just the mediaobject element.

  6. Select the mediaobject element and use the Element Context Menu to add the audioobject element.

  7. Select the audioobject element and use the Element Context Menu to add the audiodata element.

  8. Select the audiodata element and use the Element Context Menu to add the multimediaparam element.

    You should now have a structure like this: mediaobject > audioobject > audiodata > multimediaparam.

    The mediaobject, audioobject, and audiodata are the elements that are needed for the audio link. The multimediaparam element is needed to provide the audio player.

    The Element Structure Menu shows the required structure for audio. At the top level is section, then mediaobject, then audioobject, then audiodata, then multimediaparam.

  9. Select the multimediaparam element and then use the Element attributes section to add these attributes and values:

    • name: controls

    • value: true

    Element attributes section showing that the multimediaparam element has a name attribute set to controls and a value attribute set to true.

    Note

    There are other multimediaparam attributes and values that you can use. For details, see Autoplay, Mute, and Download for Audio.

  10. Select the audiodata element and then use the Element attributes section to add the fileref attribute. Set the value of the fileref attribute to the URL for the audio file, for example, https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3.

    Element attributes section showing the audiodata element has a fileref attribute. The value of the attribute is set to the URL for an audio file that is stored externally, in this case, in GitHub.

  11. Select Save. Save icon.

When you publish this content to HTML, the page for the topic will contain an embedded audio file player that you can use to play the audio file (as long as there is an Internet connection available).

Example 1. Audio file stored in GitHub

Here is a sample of an entire topic. It contains a link to an audio file, and the link is part of step 2 in a procedure list.

A topic in the Paligo editor. It has a title and some text and a procedure list. There are elements for an audio file within step 2 of the list.

The source code of this topic looks like this:

<?xml version="1.0"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xinfo="http://ns.expertinfo.se/cms/xmlns/1.0" xml:id="UUID-75e269ad-3848-623e-3f4d-aadec221fac4" version="5.0" xml:lang="en" xinfo:resource="UUID-75e269ad-3848-623e-3f4d-aadec221fac4" xinfo:resource-id="14240" xinfo:resource-type="component" xinfo:resource-title="Audio file is stored in GitHub" xinfo:resource-titlelabel="" xinfo:version-major="1" xinfo:version-minor="0">
  <title xinfo:text="14241">Audio file is stored in GitHub</title>
  <para xinfo:text="14242">This topic contains instructions for playing an audio file.</para>
  <procedure>
    <step>
      <para xinfo:text="14243">Open the page that contains the audio content. The audio is embedded in the page, but is actually stored in GitHub.</para>
    </step>
    <step>
      <para xinfo:text="14244">Use the media player to play the audio.</para>
      <mediaobject>
        <audioobject>
          <audiodata fileref="https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3">
            <multimediaparam name="controls" value="true"></multimediaparam>
          </audiodata>
        </audioobject>
      </mediaobject>
      <mediaobject></mediaobject>
    </step>
    <step>
      <para xinfo:text="14245">Stop the audio.</para>
    </step>
  </procedure>
</section>

The published HTML version of the topic has a media player that plays the audio file that is stored in GitHub.

A published HTML page showing the topic. It has a procedure list and inside step 2, there is an embedded media player for playing the audio.

Autoplay, Mute, and Download for Audio

You can use the attributes for the multimediaparam element to control whether the audio file plays automatically, is muted, and how it downloads. The following table shows the attributes you can use.

Table 1. List of supported multimediaparam attributes for audio links

Name

Description

controls

If set to true, this adds controls to your audio object.

Example:

<multimediaparam name="controls" value="true"></multimediaparam>

autoplay

If set to true, it automatically plays the audio when the page loads.

Example:

<multimediaparam name="controls" value="true"></multimediaparam>
<multimediaparam name="autoplay" value="true"></multimediaparam>

loop

If set to true, the audio will repeat indefinitely.

Example:

<multimediaparam name="controls" value="true"></multimediaparam>
<multimediaparam name="loop" value="true"></multimediaparam>

muted

If set to true, the audio is muted. To hear the audio, the user has to adjust the volume on the player.

Example:

<multimediaparam name="controls" value="true"></multimediaparam>
<multimediaparam name="muted" value="true"></multimediaparam>

preload

If set to none, the browser will download the audio the file when the playback starts.

If set to auto, the browser can download the audio file in advance, even if the user does not play the audio.

If set to metadata, the browser will only download the audio file's metadata in advance.

If preload is not included, most browsers will only download metadata about the file.

Example:

<multimediaparam name="controls" value="true"></multimediaparam>
<multimediaparam name="preload" value="auto"></multimediaparam>

Note

To remove an effect, delete that attribute and value for the multimediaparam element. For example, if a multimediaparam has loop set to true and you do not want it to play repeatedly, remove the loop attribute and its true value.