This software should be considered as both alpha and a curiosity.
css-audio is an add-on mechanism for adding audio playback and control to elements in Web documents.
Although the author has specific uses for it in internal software projects, it is largely a curiosity created because it could be created. Enhancements, rewrites, or reimaginings are encouraged.
css-audio works by using CSS custom properties with JavaScript to manage changes in these properties.
A brief example, to add a sound to a button that triggers on click, would be:
button {
--audio-src: url('click.ogg');
}
button:active {
--audio-state: playing;
}
Add the following to your HTML <head>:
<script type='text/javascript' src='//kettek.net/s/css-audio/css-audio-LATEST.min.js'></script>
<script type='text/javascript'>window.addEventListener('load', function() { KTK.CSSA.init(); })</script>
Thereafter you can add a stylesheet to the document head defining your Audio Properties and any accompanying HTML elements to the document body.
The custom CSS properties that css-audio provides are as follows.
The --audio-src property sets one or more audio sources on an element.
Each audio source is specified as a url(...) value.
To specify multiple audio sources, supply multiple values separated by a comma:
--audio-src:
url(audio1.ogg),
url(audio2.ogg);
- <url>
- Is a <url> denoting the audio source to use. There can be several of them, separated by commas.
The --audio-state property sets the desired state of the audio.
Changes to this property through selectors or other changes (such as style, class, or id) will result in the audio's state changing.
Each audio source's state is specified as a String value.
To specify the state of multiple audio sources, supply multiple values separated by a comma:
--audio-state:
playing,
default;
- default
- The audio state should remain in whatever state it already is.
- playing
- The audio should be playing.
- paused
- The audio should pause its playback.
- stopped default
- The audio should stop its playback.
The --audio-volume property sets the audio volume from 0 to 100%.
The audio volume is specified as a value from 0 to 100, representing the percentage volume to reduce or increase by.
The --audio-playback property sets how the audio should manage playback.
Each audio source's playback method is specified as a String value.
To specify the playback method of multiple audio sources, supply multiple values separated by a comma:
--audio-playback:
playthrough,
cease;
- playthrough
- The audio should keep playing until it finishes if the
--audio-statechanges to a non-playing value.
- The audio should keep playing until it finishes if the
- cease default
- The audio should change its state to match
--audio-stateimmediately.
- The audio should change its state to match
The --audio-loop property sets how the audio should loop.
Each audio source's looping rule is specified as either a Number or the infinite value.
To specify the looping rule of multiple audio sources, supply multiple values separated by a comma:
--audio-loop:
infinite,
2;
- infinite
- The audio should resume playback from
--audio-offsetonce it finishes playing.
- The audio should resume playback from
- <integer>
- The audio should loop the supplies amount of times. Defaults to "1"
The --audio-ontrigger property sets how playback should behave when the audio source updates.
Each audio source's trigger rule is specified as a String value.
To specify trigger rules for multiple audio sources, supply multiple values separated by a comma:
--audio-trigger:
reset,
multi;
- continue default
- The audio should continue playing if the audio is still playing.
- reset
- The audio should immediately reset to the beginning of its offset and play.
- multi
- The audio should create a new audio playback source that copies its rules and begin playback.
The --audio-offset property sets the playback offset for the audio source to start from.
Each audio source's offset rule is specified as a <time> value.
The specify offset rules for multiple audio sources, supply multiple values separated by a comma:
--audio-offset:
0.1s,
500ms;
- <time>
- Is a <time> denoting the offset of the audio. There can be several of them, separated by commas. Defaults to "0s"
The --audio-hold-navigation property prevents the element from navigating the browser until any playing audio on the element has finished playback.
--audio-hold-navigation: finished;
- finished
- The element is prevented from navigating the page until the element's audio playback is complete.
css-audio can be passed a configuration object through the init() call, thereby changing some of the core functionality of css-audio to fit your needs.
These options and their effects are:
| Option | Description | Value(s) | Default Value |
|---|---|---|---|
| processDOM | Should the DOM should be processed on init? | true/false | true |
| observeDOM | Should the DOM be observed for added Elements? | true/false | true |
| observeNodeConfig | Options for MutationObserver.observe used on Nodes | See MutationObserverInit | { attributeFilter: ['style', 'class', 'id'] } |
| observeDOMConfig | Options for MutationObserver.observe used on the DOM | See MutationObserverInit | { childList: true } |
| selectors | CSS selectors that should trigger handleAudioState for Nodes | Array of Strings | ['active', 'hover', 'focus', 'checked'] |
- There is no proper triggering of children when the parent changes.
- Internal parsing for Element watching validity requires overspecific rules that specify the full class name, id, and tag name. Additionally, complex psuedo-class selectors will also not register.
<div class='button' id='unique'>click</div>
div.button#unique:active:hover {
/* NO MATCH */
}
div.button#unique:active {
/* MATCH */
}
div.button:active {
/* NO MATCH */
}
div:active {
/* NO MATCH */*
}