Audio files can be added to a project using either the audio or audio-inline directive. Audio files can be hosted either locally or remotely. The behavior of the audio and audio-inline directives mimics that of the video and video-inline directives.

The b-ber audio element must be declared with an id and source attribute. The file name in the b-ber source attribute must not have an extension.

The audio directive, when rendered into HTML, will add the poster image to the body of the project, which, when clicked, links to the corresponding audio player in the Figures section of the project.

::: audio:my-id source:my-audio poster:poster-image.jpg

The audio-inline directive, when rendered into HTML, will add the audio player directly into the flow of the project.

::: audio-inline:my-id source:my-audio poster:poster-image.jpg

The audio directive supports all of the same attributes as the HTML5 Audio element. Boolean attributes must be assigned yes or omitted.

• autoplay
• autobuffer
• buffered
• controls
• loop
• mozCurrentSampleOffset
• muted
• played
• preload
• volume

Note: Using the src attribute will conflict with b-ber's file management. Do not use that attribute.

The audio directive also supports an optional caption. Captions are added by enclosing a line of text within two colons directly underneath the audio.

::: audio:my-unique-id source:my-audio poster:poster-image.jpg controls:yes

::: audio:my-unique-id source:my-audio poster:poster-image.jpg controls:yes
:: Here is the *caption* for my audio.<br/>Inline HTML is also supported here.
::

Audio directives also support a poster attribute, which will link an image to an audio file in the figures section of the compiled project.

<!-- chapter-one.md  -->

::: audio:audio-one source:demo-audio poster:square.jpg
:: *Audio* caption.
::

<!-- chapter-one.xhtml  -->

<div class="figure__small figure__small--landscape">
  <figure id="refaudio-one">
    <a href="figures-titlepage.xhtml#audio-one">
      <img src="../images/square.jpg" alt="" />
    </a>
  </figure>
</div>

<!-- figure-audio-one.xhtml  -->

<div class="figure__large figure__large--media figure__inline--square">
  <figure id="audio-one">
    <div class="figure__items">
      <div class="audio">
        <audio controls="controls">
          <source src="../media/demo-audio.m4a" type="audio/mp4" />
          <source src="../media/demo-audio.mp3" type="audio/mpeg" />
          <source src="../media/demo-audio.ogg" type="audio/ogg" />
          <div class="media__fallback__audio media__fallback--image figure__small--landscape figure__small">
            <figure>
              <img src="../images/square.jpg" alt="Media fallback image" />
            </figure>
          </div>
          <p class="media__fallback__audio media__fallback--text">Your device does not support the HTML5 audio API.
          </p>
        </audio>
      </div>
      <div class="figcaption">
        <p class="small">
          <em>Audio</em> caption.
          <br />
          <a href="audio.xhtml#refaudio-one">Return</a>
        </p>
      </div>
    </div>
  </figure>
</div>

Add audio files to the _media folder. Audio files in different formats should all have the same base name.

b-ber suggests using a number of different formats to support various build types. For the web build, it's best practice to include the mp3 and oga (OGG audio) formats. For EPUB builds, the Books app on macOS and iOS requires an .m4a file to play audio. Note that for video, the Apple-specific encoding is not required, although this is not the case with audio for the Books app on macOS and iOS.

_project/_media
            ├── my-audio.m4a
            ├── my-audio.mp3
            └── my-audio.oga

Add the audio directive to the Markdown.

# My Audio

::: audio:my-unique-id source:my-audio controls:yes

Note: The Books app on macOS and iOS requires that the controls attribute is specified or users will be unable to play the audio.

When building the the project, b-ber will add the sources that match the file name (without extension) that's defined in the source attribute.

<audio id="_my-unique-id" controls="controls">
    <source src="../media/sample-audio.m4a" type="audio/mp4"/>
    <source src="../media/sample-audio.mp3" type="audio/mpeg"/>
    <source src="../media/sample-audio.ogg" type="audio/ogg"/>
    <p>Your device does not support the HTML5 Audio API.</p>
</audio>

Note that b-ber always includes fallback text in case none of the media sources are supported on the end-user's browser or device.

Add the audio directive to the Markdown with the audio file's URL as the source attribute. Don't forget to quote the source attribute if the URL contains spaces. For remote audio, the source attribute must contain the file extension (.mp3, .ogg, etc).

# My Audio

::: audio:my-unique-id source:'http://techslides.com/demos/samples/sample.mp3' controls:yes

Note: The Books app on macOS and iOS does not require .m4a files when the audio is hosted remotely.

• For best results, poster images should be sized for a 16:9 aspect ratio (approx. 888 × 500 pixels)
• For web-only projects, it's necessary to include, at minimum, both the ogg and mp3 file formats