Accessible Audio with Craft CMS

Developers have a lot of flexibility around how to organize assets and collect any required text alternatives. This post will provide a brief overview about transcripts, and describe a content model for audio that will work for for most sites.

About transcripts #

A transcript is the text version of audio and is typically presented as text below an audio player.

Transcripts are a requirement for WCAG 2.1 Success Criterion 1.2.2: Captions (Prerecorded). The W3C's Web Accessibility Initiative (WAI) has also provided a more approachable resource for understanding audio accessibility requirements.

Transcripts enable the Deaf and Hard of Hearing, as well as anyone who has their sound turned off, to access the audio content on your site. As a bonus, transcripts can improve your site’s SEO.

Content model for accessible audio #

The configuration described here will work for sites where audio uploaded to the CMS require a single transcript.

1. Create a transcript field #

Navigate to SettingsFields, click the New field button, and give it the following settings:

SettingValue
NameTranscript
Handletranscript
Allow line breaksChecked

Then save the field.

2. Create a volume for audio #

Navigate to SettingsAssets, click the New volume button, and give it the following settings.

SettingValue
NameAudio
Handleaudio
Assets in this volume have public URLsYes

Set a base URL, choose a volume type, and fill out the volume type-specific settings according to your environment.

Drag the newly created “Transcript” field into a tab in the field layout, and click its gear icon to open the field’s layout settings. Tick the checkbox beside Required and click Apply.

Then save the volume.

3. Create an audio field #

Navigate to SettingsFields, click the New Field button, and give it the following settings:

SettingValue
NameAudio
Handleaudio
Field TypeAssets
SourcesAudio
Restrict allowed file typesYes – “Audio”
Validate related assetsYes

Then save the field.

Checking Validate related assets ensures that entries won’t be published if they contain audio with no transcript.

4. Display the audio player and transcript #

Finally, update your templates to display the audio player and its transcript. Here’s a Twig snippet that will display an HTML5 audio element for the uploaded audio file, along with its transcript.

{{ tag('audio' {
    controls: true,
    src: asset.url,
}) }}

{{ asset.transcript }}
Accessibility Home
Next
Five Accessibility Facts for GAAD 2021