Newskit Logo

Getting started

Design overview

Popular searches

View GitHub

Media

Audio Player

The audio player component allows a user to play and control the playback of live and recorded audio content.

Status

Supported

Introduced

v5.3.0
View codeView StorybookView Design

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:

ItemNameDescriptionComponentOptional

Volume control

The volume control contains one required element and one optional element.

ItemNameDescriptionComponentOptional

Playback speed control

The Playback speed control contains two required elements and no optional elements.

ItemNameDescriptionComponentOptional

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.

Code examples can be viewed in Storybook via the ‘Story’ tab in the addons panel.

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.

Playback speed control

Audio speed can be selected on click/tap, changing the pace of the audio track, with the default/normal value set at 1x.

The playback speed control launched in a modal is intended for use on mobile, and a popover is intended for use on desktop.

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.

Playback speed control

Audio speed can be selected on click/tap, changing the pace of the audio track, with the default/normal value set at 1x.

The playback speed control launched in a modal is intended for use on mobile, and a popover is intended for use on desktop.

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 adapt the component for different breakpoints

For optimal user experience across breakpoints, it is recommended to display the playback speed control options in a popover for desktop, and in a modal for mobile.

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

OrderElementRole

Playback speed control

OrderElementRole
Keyboard Interactions
CommandDescription
WAI-ARIA
ElementAttributeValueDescriptionUser supplied

API

Audio player composable

The audio player composable has a range of props that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired

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.

Play Pause Button

The play pause button has a range of props that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired

Please refer to the Icon Button component for details of the props and other overrides.

Time display

The time display has a range of props that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired
Seek bar

The seek bar has the following overrides that can be used to define an appropriate experience for different use cases.

AttributeTypeDefaultDescription

Please refer to the Slider component for details of overrides.

Skip next button

The skip next button has the following overrides that can be used to define an appropriate experience for different use cases.

AttributeTypeDefaultDescription

Please refer to the icon button component for details of the props and other overrides.

Skip previous button

The skip previous button has the following overrides that can be used to define an appropriate experience for different use cases.

AttributeTypeDefaultDescription

Please refer to the icon button component for details of the props and other overrides.

Forward Button

The forward button has the following overrides that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired
Replay button

The replay button has the following overrides that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired
Volume control

The volume control has a range of props that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired
Playback Speed Control

The playback speed control has the following overrides that can be used to define an appropriate experience for different use cases.

NameTypeDefaultDescriptionRequired

This component should extend the overrides of the Popover, Modal components.

Need Help?

Cant find what you are looking for?

Get In Touch

Need Help?

Cant find what you are looking for?