-
Notifications
You must be signed in to change notification settings - Fork 1
Audio
Audio files can be added to a project using either the audio
or audio-inline
directives. 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
src
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.
::
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 specifed, 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
andmp3
file formats
- Adding metadata
- Creating content
- Generating new content
- Authoring and editing content
- Reading order (Table of Contents)
- Configuring the build
- Adding a cover image
- All directives
- Text
- Media
- Misc