Media
Audio Player
The audio player component allows a user to play and control the playback of live and recorded audio content.
Anatomy
Audio player composable
The audio player composable is responsible for maintaining the audio player state, and receiving interactions from subcomponents, and contains the non-visual audio element. It is the wrapper for the subcomponents listed below:
| Item | Name | Description | Component | Optional |
|---|
Volume control
The volume control contains one required element and one optional element.
| Item | Name | Description | Component | Optional |
|---|
Playback speed control
The Playback speed control contains two required elements and no optional elements.
| Item | Name | Description | Component | Optional |
|---|
Layout examples
Full player
The following example shows the full audio player layout option that can be assembled using the various available subcomponents. View examples in Storybook.
Inline player
Use an inline audio player for simple inline playback e.g. within an article. View examples in Storybook.
Player in card
The audio player can be used with other components to create more complex modules, such as a card, to give context to the track or show being played. View examples in Storybook.
Options
The audio player has options that can be used to provide an appropriate experience for different use cases.
Live
The live functionality is used for streaming live audio content
Live streaming audio can be indicated by providing a flag component with text and icon to communicate this to users.
Recorded
The recorded functionality is used for streaming recorded audio content. Extended controls allow the user to play, pause, forward, replay, and skip to the next, or the previous track. A seek bar is provided to indicate buffering, duration, and track position. Track position can be further controlled with the slider thumb.
Autoplay
The audio player can be set to play automatically when audio content is loaded.
Note
This will not work on mobile browsers due to users' data allowance, and it can't happen on page load – the user has to interact with the page the audio player appears on for it to work. Navigating inside a single-page application will work as expected, as there is no page refresh.
Time display
Can be used to display the current time elapsed, duration of the audio track, or both.
Forward & replay
Icon buttons for forwarding or replaying the audio track for a determined number of seconds (default 10 seconds).
Custom values can be provided for the number of seconds in the scale, as well as custom icons.
Volume Control
The volume control has the option of either being displayed in an expanded or collapsed mode.
The volume slider can be expanded on hover or focus of the mute button in either horizontal or vertical orientations.
Mute button
The volume control has the option to hide the volume slider for use on mobile devices, with only the mute button visible.
Live
The live functionality is used for streaming live audio content
Live streaming audio can be indicated by providing a flag component with text and icon to communicate this to users.
Recorded
The recorded functionality is used for streaming recorded audio content. Extended controls allow the user to play, pause, forward, replay, and skip to the next, or the previous track. A seek bar is provided to indicate buffering, duration, and track position. Track position can be further controlled with the slider thumb.
Autoplay
The audio player can be set to play automatically when audio content is loaded.
Note
This will not work on mobile browsers due to users' data allowance, and it can't happen on page load – the user has to interact with the page the audio player appears on for it to work. Navigating inside a single-page application will work as expected, as there is no page refresh.
Time display
Can be used to display the current time elapsed, duration of the audio track, or both.
Forward & replay
Icon buttons for forwarding or replaying the audio track for a determined number of seconds (default 10 seconds).
Custom values can be provided for the number of seconds in the scale, as well as custom icons.
Volume Control
The volume control has the option of either being displayed in an expanded or collapsed mode.
The volume slider can be expanded on hover or focus of the mute button in either horizontal or vertical orientations.
Mute button
The volume control has the option to hide the volume slider for use on mobile devices, with only the mute button visible.
Behaviours
The following guidance describes how the Audio Player behaves.
Buffering
The seek bar indicates audio track duration and buffering, and controls the track position. Also known as an audio ‘scrubber’.
Skip previous
The skip previous icon button is used to skip to the beginning of the track and if pressed within the first five seconds of a track will skip to the previously played track (if available).
If no previous track is available, the icon button will be disabled for the first 5 seconds of playback.
Skip next
The skip next icon button is used to skip to the next track (if available).
If there is no next track available, the icon button will be disabled.
Play pause - live
When audio is playing the play pause icon button will display a stop icon, and a play icon when no audio is playing. Play will resume from the current point in the live stream.
Play pause - recorded
When audio is playing the play pause icon button will display a pause icon, and a play icon when no audio is playing. Paused content will resume from the track position.
Mute button
The mute icon button mutes/unmutes the audio track on click/tap, or via the M keyboard shortcut.
Buffering
The seek bar indicates audio track duration and buffering, and controls the track position. Also known as an audio ‘scrubber’.
Skip previous
The skip previous icon button is used to skip to the beginning of the track and if pressed within the first five seconds of a track will skip to the previously played track (if available).
If no previous track is available, the icon button will be disabled for the first 5 seconds of playback.
Skip next
The skip next icon button is used to skip to the next track (if available).
If there is no next track available, the icon button will be disabled.
Play pause - live
When audio is playing the play pause icon button will display a stop icon, and a play icon when no audio is playing. Play will resume from the current point in the live stream.
Play pause - recorded
When audio is playing the play pause icon button will display a pause icon, and a play icon when no audio is playing. Paused content will resume from the track position.
Mute button
The mute icon button mutes/unmutes the audio track on click/tap, or via the M keyboard shortcut.
Usage
Here’s how and when to use the audio player:
Do use a flag for 'live' audio streaming
Use a flag to show users that audio is being live streamed.
Do use the expandable volume control when space is limited
Use the expandable volume control when space in an audio player is limited.
Don’t display on mobile
Avoid displaying the volume control on mobile devices as users can use their native device controls to increase or decrease the volume of the audio track.
Accessibility considerations
The audio player has the following accessibility considerations:
For recorded audio content, it is best practice to provide audio transcription in order to cater to accessibility needs. This is generally provided in WebVTT format.
Focus order
Focus order depends on how the audio player subcomponents are assembled and ordered in the DOM.
Volume control
| Order | Element | Role |
|---|
Playback speed control
| Order | Element | Role |
|---|
| Command | Description |
|---|
| Element | Attribute | Value | Description | User supplied |
|---|
API
The audio player composable has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
The audio player requires a source stream to be passed in as using the src prop. This will then be loaded into the internal <audio> element for playback.
The audio element is non-visual, and as such doesn’t come with predefined elements and attributes that can be overridden to define their appearance.
The play pause button has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
Please refer to the Icon Button component for details of the props and other overrides.
The time display has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
The seek bar has the following overrides that can be used to define an appropriate experience for different use cases.
| Attribute | Type | Default | Description |
|---|
Please refer to the Slider component for details of overrides.
The skip next button has the following overrides that can be used to define an appropriate experience for different use cases.
| Attribute | Type | Default | Description |
|---|
Please refer to the icon button component for details of the props and other overrides.
The skip previous button has the following overrides that can be used to define an appropriate experience for different use cases.
| Attribute | Type | Default | Description |
|---|
Please refer to the icon button component for details of the props and other overrides.
The forward button has the following overrides that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
The replay button has the following overrides that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
The volume control has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|