API

How to dive into cpu-audio.js :

This is the reference page for public accessible methods and properties. You can read some test cases in the examples sub-directory of this project.

Some informations can be also found in the INTERNALS.md page. Some of them are helpful to create a brand new theme, as we describe elements’ ID and class-names usage.

Important : Undocumented feature use is at your risks, we won’t check naming, parameters, actions and outputs continuity. We only test methods and properties continuity on those listed below. And seriously, keep our webcomponent up to date on the stable version.

document.CPU

This object is a global configuration interface.

Properties :

Some of them are not listed below, as they may be overloaded at start via a <script type="application/json" data-cpu-audio> tag, see INSTALL.md documentation, chapter « Setting global application parameters via a tag ».

name default value usage
currentAudiotagPlaying null Reference to the playing <audio> element, null if none
globalController null Reference to the <cpu-controller> in the page if any, null elsewhere
playlists {} Collection of audio tag by playlists (named by the <cpu-audio playlist=""> attribute). See playlist feature.

Some properties for internal usage are still not documented, as they may evolve. Avoid to use them, we may change their name, values and usage.

Methods :

name returns usage
isAudiotagPlaying(audiotag) boolean Indicate if this <audio> element is playing and correctly cpu-audio started
isAudiotagGlobal(audiotag) boolean Indicate if this <audio> element is displayed by <cpu-controller> if installed
jumpIdAt(hash, timecode)   will jump the <audio id="hash"> to timecode (any convertable format in seconds, colon-coded or human coded)
seekElementAt(audiotag, seconds)   will jump the <audio> to a position in seconds (number only)
findCPU(child) CpuAudioElement.CPU or null For any <audio> tag or its child tag, will returns the element CPU API
currentPlaylist() array Returns an array of <audio> tags IDs of the current playing playlist
currentPlaylistID() string or null Returns the name of the current playing playlist
adjacentKey(object, key, offset) string or null Returns the adjacent key of a key in an object (offset -1 for previous, +1 for next)

Some methods are still not documented, for internal usage, as they may evolve.

document.body.CPU.convert sub-API methods :

name returns usage
timeInSeconds(string) number Convert a string empty, with a number, with a colon-coded or an human-coded timecode in seconds
subunittimeInSeconds(string) number Convert a human-coded (1h2m3s) time in seconds
colontimeInSeconds(string) number Convert a colon-coded (01:02:03) time in seconds
secondsInTime(number) string Convert a time in seconds in a human-coded time (1h2m3s). Zero is 0s.
secondsInColonTime(number) string Convert a time in seconds in a colon-coded time (1:02:03s). Zero is 0:00.
secondsInPaddledColonTime(number) string Same as secondsInColonTime, but suited for <input type="time" />. Zero is 00:00:00.
durationIso(number) string Convert a duration in an ISO 8601 string suitable for datetime="" attribute in <time>

CpuAudioElement and CpuControllerElement

Attributes of their DOM elements may be live changed in the same way for the HTML inclusion, but using CpuAudioElement.setAttribute(attribute, value) or CpuAudioElement.removeAttribute(attribute, value). It can be useful for advanced interactions. See “Attributes references” in INSTALL.md of course.

Example : CpuAudioElement.setAttribute("hide", "panels timeline")

CpuAudioElement.CPU and CpuControllerElement.CPU

Note that CpuAudioElement.CPU and CpuControllerElement.CPU share the same CPU object, with same methods and properties, except those noted (¹) below.

Properties :

name default value usage
element <cpu-audio> The WebComponent hosting DOM element
elements object ShadowDOM elements, keyed by their id attributes
audiotag <audio> Media DOM element

Methods :

name returns usage
setMode(string)   Change the presentation mode, used for mode="" attribute
setAct(string)   Change the presentation style between 'loading', 'glow', 'pause' or 'play', reflecting the media tag status
setHide(array)   Array of strings, may contains 'actions' or 'chapters', used for hide="" attribute
showThrobberAt(number)   Display the throbber on the timeline at a given time in seconds.
hideThrobber()   Hide immediately the throbber.
hideThrobberLater()   Hide the throbber later (waiting 1 seconds). A newer call will delay the hidding later.
show(string)   Switch between 'main', 'share' or 'error' interfaces.
addPlane(planeName, planeData) boolean Create an annotation plane (¹)(²)(³)
removePlane(planeName) boolean Remove an annotation plane (¹)(²)
addPoint(planeName, pointName, pointData) boolean Add an annotation point to a plane at a timecode (¹)(²)(⁴)
point(planeName, pointName) object Return data for a point (³)
editPoint(planeName, pointName, pointData)   Modify data for a point (³). Only existing keys from point() are updated
focusPoint(planeName, pointName) boolean Give focus on a point on a plane, else on the track
focusedId() string Give focused Id (element or parent), or null/undefined
removePoint(planeName, pointName) boolean Remove an annotation point (¹)(²)
clearPlane(planeName)   Remove any points from an annotation plane (¹)(²)
redrawAllPlanes()   Redraw any annotation planes and points.
highlightPoint(planeName, pointName, className, private)   Highlight a perticuliar annotation point, className is 'with-preview' by default (²)
removeHighlightsPoints(planeName, className, private)   Remove highlights on a plane, className is 'with-preview' by default (²)
injectCss(styleName, css)   Inject a <style> tag into the shadowDom of the component. (²)
removeCss(styleName)   Remove an inject <style> from the shadowDom. (²)

(¹) Only available via CpuAudioElement.CPU

(²) planeName, pointName, className and styleName accepts only alphanum (/a-zA-Z0-9\_\-/). Planes starting with a _ are reserved for system usage, try avoid creating one or messing too much with them.

(³) planeData is an object, with detailled keys for planes :

key type default value usage
title   '' Title displayed on the panel
track boolean or string true Create a track in the time-line, string to precise the kind (chapters, borders, same naming convention than upper (²)), or presentation restriction (nosmall, nosmaller, nosmallest), space separated
panel boolean or string true Create a panel under the player, or precise presentation restriction (nosmall, nosmaller, nosmallest, nocuetime) space separated
highlight boolean true Points of this annotation plane can be highlighted with the mouse
_comp boolean false Private use only. Data stored on the component instead of audio element

(⁴) pointData is an object, with detailled keys for points :

key type default value usage
image boolean or string false Url of an image, false elsewhere
link boolean or string true Click action : false for nothing, true to link moment, url string for an external link
text string   Legend
start number   The anotation point begins at this timecode (not used in addPoint)
end number undefined The anotation point ends at this timecode

Events

<CPU-audio> and <CPU-controller> elements fire events about their interface. For disambiguation, events created by our webcomponent are CPU_ prefixed

event_name description detail, see next table (⁵)
CPU_ready The DOM component and its interface are ready  
CPU_addPoint During addPoint method, even private ones planeName, pointName, pointData
CPU_drawPoint A point is drawn or redrawn planeName, pointName, pointData, elementPointTrack, elementPointPanel
CPU_editPoint During editPoint method planeName, pointName, pointData
CPU_bulkPoints During bulkPoints method planeName, pointDataGroup
CPU_removePoint During removePoint method, even private ones planeName, pointName
CPU_chapterChanged A cue event defined in WebVTT occured cue
CPU_removed A <cpu-audio> or a <cpu-controller> component vanished  

(⁵) Returned object informations usually have a detail object, it may contains :

detail key type description
planeName string the name of the plane, as given in the addPlane method, planeName parameter
pointName string the name of the point, as given in the addPoint method, pointName parameter
pointData object data for the point, as in point(planeName, pointName)
pointDataGroup object Object of points in the plane, as { pointName : pointData, pointName : pointData…}
elementPointTrack Element The created or existing point in the time track
elementPointPanel Element The created or existing point in the panel

As the event.target is the <cpu-audio> element, you can reach its API with event.target.CPU. Here is a way to do it for asynchronous build :

function CPU_ready(event) {
    let CPU = event.target.CPU;
    CPU.addPlane("hello_world", { title : "Now, we can play !" });
}

document.addEventListener('CPU_ready', CPU_ready);

Watch out, as CPU_ready is triggered for EACH webcomponent started on the page. If you’ve got 3 players and 1 controller, you will get 4 calls.

More tricks can be seen in the <applications/chapters_editor.html> source code.

Note : events aren’t impacted by .preventDefault(), yet.

Console messages

Any technical messages for cpu-audio.js in the browser console starts with “CPU-AUDIO: ”. All messages are in English, we won’t provide translations in console messages.