An audio WebComponent to provide timecoded links and other features to an audio tag

This project is maintained by dascritch

How-to install

Copy dist/cpu-audio.js file on your website.

Call it in the <head> of your html page :

<script src="./cpu-audio.js" async></script>

Do not forget to add a lang="" attribute in the hosting <html> tag. Elsewhere, the component will try to guess user’s language via the browser preferences. Actual version only have english and french locales, may be can you help us ?

Invoking element

Encapsulate your usual <audio control> with <cpu-audio>.

Example :

    title="Au carnaval avec Samba Résille (2003)"
    <audio controls id="audiodemo">
        <source src="https://dascritch.net/vrac/sonores/podcast/1404-SambaResille2003.mp3" type="audio/mpeg" />

Important Note : Put one and only one <audio> tag into <cpu-audio>, or you may have unexpected issues. We recommend to set an id attribute to the <audio> tag for the anchoring feature.

You must put a control attribute to the included <audio> tag as a fallback in case of malfunction. Please also add this rule in your css :

audio[controls] {
    display : block;
    width : 100%;

You can try playing with our live configurator tool, event it isn’t perfect yet.

Attributes references

Some attributes enhance the component :

In the upper example, <audio> tag is ID-entified as audiodemo. Usually, you link to its anchor with #audiodemo. Add a parameter t= with the expected timecode, with a & as separator. By example, for 5 minutes from the start, you should target #audiodemo&t=5m :

    Jump at <a href="#audiodemo&amp;t=5m">5 minutes</a> in the sound

Permitted hash notations

Original purpose was to link any media element of any webpage to a specific moment. It uses the W3C standard Media Fragments notation, extending the URL.

For the timecode, you can use :

A playable range can be indicated : page.html#tagID&t=5m,5m5s will play the sound starting at 5 minutes, and stops it at 5 minutes and 5 seconds

Note : if a timecode without any named anchor is given, as in href="#t=2h4m2s", the very first <audio controls> element of the document will be addressed. If you are absolutely sure you will only have one audio tag in your page, you can omit the ID : <a href="#t=5m">

Cloned player

You can invoke a global media controller by creating a <cpu-controller> without <audio> tag.

It may be useful if, as in the CPU website, you have a player in the main content and a cloned one in a fixed element.


You can add a chapters track into the <audio control> tag :

<track kind="chapters" src="chapters.vtt" default />

Note that default attribute is really needed. In case you’ve got more than one <track kind="chapters" default> declared in a <audio> tag, only the very first one will be interpreted by the browser (blocking us to catch the one according to its srclang="" see #69 )

You can create VTT files with our online editor.

Note : The chapters info will only appears with mode="default" settings in <cpu-audio>.

Personnalization via CSS variables

You can change some presentation features of the interface with CSS Variables. Check their effects with the live editor

Variable name Description Default value
--cpu-background Background, except playing or in error #555
--cpu-color Color, except playing #ddd
--cpu-color-transitions Colors (text and background) transitions duration 0s
--cpu-elapse-width Time indicator width 185px (160px under 640px width, 80px under 480px, 0 under 320px)
--cpu-error-background Background when there is a media error #a00
--cpu-error-color Color when there is a media error #ff7
--cpu-font-family Font families Lato, "Open Sans", "Segoe UI", Frutiger, "Frutiger Linotype", "Dejavu Sans", "Helvetica Neue", Arial, sans-serif
--cpu-font-size Font size 15px
--cpu-font-small-size Small font size calc(var(--cpu-font-size) * 0.8)
--cpu-height Height and width of the square buttons 64px (48px under 640px width)
--cpu-inner-shadow Shadow between horizontal panels inset 0px 5px 10px -5px black
--cpu-playing-background Background while playing #444
--cpu-playing-color Color while playing #fff
--cpu-popup-background Background for the time pointer #aaa
--cpu-popup-color Text color for the time pointer #333

Some color/background values are not recommended, as currentColor and transparent.

Using classes on host page

The intention onto cpu-audio.js is to be configurable and usable without any javascript knwonledge. HTML attributes, CSS variables, and CSS selectors must be able to help integrators to hide some elements of their page without having to painly dig into javascript snippets.

You can use some CSS features in the host page, as some classes are added to your host page <body> to reflect what is happening with the player :

.cpu-audio-without-webcomponents and .cpu-audio-with-webcomponents

.cpu-audio-without-webcomponents is set when cpu-audio.js is launched but the interface cannot be displayed, due to incomplete WebComponent suppport by the browser. Only the hash links are interpreted.

.cpu-audio-with-webcomponents means that cpu-audio.js was able to build its graphic interface.

Here is an example :

    /* fallback style for browsers without webcomponents */
    audio[control] {
        display : block;
        width : 100%;
    .cpu-audio-without-webcomponents #no-player-interface {
        display : block;
    /* fully operative */
    .cpu-audio-with-webcomponents #no-player-interface {
        display : none;
<div id="no-player-interface">
    Nothing wrong, but your browser seems a little old.


The <audio id="audiotag_id"> has its <track kind="chapters"> decoded and displayed.

Note : This class will be set even if the chapters list is set to be hidden.


The <audio id="audiotag_id"> is actually playing the cue_id chapter. The cue_id is the cue (chapter) name described in the .VTT file in its <track kind="chapters"> .

This function was meant to build effects as in BBC Computer Literacy archive : During a play of a show, each chapter is highlighting its text resumee.

Using javascript API

cpu-audio.js can be used only with HTML attributes and CSS variables, but javascript savvy developers have API features to get a more precise control.

CPU Audio webcomponent

Crafted with ♥ from Toulouse, France, for CPU radio show