WebAudioControls is GUI parts Custom Elements library for Web application using WebComponents.
Especially suitable for audio-applications like VST plugins.
webaudio-controls is consist of following components
Component | Description |
---|---|
webaudio-knob | Rotating or some other frame-by-frame animation knob |
webaudio-slider | Vertical or Horizontal slider |
webaudio-switch | Toggle/Kick/Radio switches |
webaudio-param | Editable value display field |
webaudio-keyboard | Mouse/Touch playable keyboard. multi-touch support. |
- Also available 'webaudio-pianoroll' at : https://github.com/g200kg/webaudio-pianoroll/
There are some difference from old [Polymer 1.4] version.
-
Current webaudio-controls uses the Custom Elements V1 API directly. In Chrome / Safari / Firefox (59 and later) it works without polyfill. Please install webcomponentsjs on Firefox (58 or less), Edge etc Custom Elements non-compatible browsers.
-
Event firing. Knobs/Sliders fires 'input' event instead of 'change' during drag. This is same behavior as input type=range tags.
-
Value post conversion function
conv
attribute is available. It will help for implement, for example, exponential curve parameters. Also Tooltip and Valuetip is integrated. It is now acceptable C-like formatting string for current value display.
Chrome / Firefox / Safari / Opera compatible
iOS and Android touch devices compatible
Live Demo (with external image-files)
Live Demo (with code example)
Live Demo (Knob/Slider/Switch/Param/Keyboard default style)
Live Demo (Various Knob Images)
Live Demo (Multi-Touch Fader)
Live Demo (webaudio-keyboard to Web MIDI API)
(need Web MIDI API support)
Renoid : Practical application using webaudio-controls
webaudio-controls Resize Test
webaudio-controls NonLinear values Test
Using with external image-files.
Default style with no external image-files.
Following user actions are supported.
Operation | Component | Description |
---|---|---|
Click | Switch/Param | toggle / activate the switch or focus the param |
Drag | Knob/Slider | up/right to increase value / down/left to decrease value |
Shift+Drag | Knob/Slider | fine control |
Ctrl+Click / Command+Click(Mac) | Knob/Slider/Switch | set to default value |
Keyboard | Param/Keyboard | edit the param value directly / [ZSXDCV...for lowest visible 'C' octave] and [Q2W3E... one octave higher] as a music keyboard |
MouseWheel | Knob/Slider | rotate upward to increase value / downward to decrease value |
Shift+MouseWheel | Knob/Slider | fine control |
Mouse Button Press / Touch | Keyboard | play keyboard. multi-touch is supported |
-
Install
- The main file is
webaudio-controls.js
. If you want to support non-WebComponents ready browsers, webcomponents.js is also needed. - Use command
bower install --save g200kg/webaudio-controls
, if you use bower. Or download zipped file and deploy appropriately. - If you want to load webaudio-controls.js directly from this GitHub page, installation is not necessary.
- The main file is
-
[for WebComponents polyfill] load webcomponents.js
- <script src="bower_components/webcomponentsjs/webcomponents-lite.js"></script>
- load webaudio-contols
- <script src="bower_components/webaudio-controls/webaudio-controls.js"></script>
- Or, if you want to load webaudio-controls.js directly from this GitHub page as CDN:
<script src="https://g200kg.github.io/webaudio-controls/webaudio-controls.js" ></script>
- insert webaudio-knob/slider/switch/param/keyboard elements. for example...
- <webaudio-knob src="img/LittlePhatty.png" sprites="100" min="0" max="100"></webaudio-knob>
- <webaudio-slider src="img/hsliderbody.png"></webaudio-slider>
- <webaudio-switch src="img/switch_toggle.png" width="32" height="32"></webaudio-switch>
- <webaudio-param src="" link="knob-1"></webaudio-param>
- <webaudio-keyboard keys="25" ></webaudio-keyboard>
Attribute | Options | Default | Description |
---|---|---|---|
src | string | null | url of the knob image, Single frame or vertical stitched. Internal embedded resource is used if not specified. |
value | float | 0 |
The current value. Also used as initial value if specified |
defvalue | float | Initial 'value' is used if not specified | The default value that will be used when ctrl+click |
min | float | 0 |
Minimum value of the knob |
max | float | 100 |
Maximum value of the knob |
step | float | 1 |
Value step of the control. The 'value' is always rounded to multiple of 'step' |
width | int | 0 |
Knob width in px. diameter value is used if this value is 0 . |
height | int | 0 |
Knob height in px. diameter value is used if this value is 0 . |
diameter | int | 64 |
Knob diameter in px. This attribute can be used instead of width / height if the display image is square. |
sprites | int | 0 |
if 0 , the src image should be single frame image that indicate middle position. the image will be rotated -135deg to +135deg. If sprirites is not 0 , the src image should be vertically stitched multi-framed image. sprites specify the max frame number in the stitched knob image. Note that this is (number of frames) - 1 |
sensitivity | float | 1 |
Pointing device sensitivity. min-max range correspond to (128 / sensitivity ) px |
valuetip | 0 ,1 |
1 |
Enable the overlaid value-tip display. |
tooltip | string | null |
Tooltip text that will be shown when mouse hover a while. If the text include a C-printf style value formatter like %8.2f , it will be replaced by current value. This formatter should be %[n][.][m]{d,f,x,X,s} . Here the 'n' is total columns, 'm' is after the decimal point columns. If the conv function is specified, the converted value convValue is used for display. |
conv | string | null |
Value conversion function. If this function is specified, the function is called with current value as argument and be stored as convValue . That will be used as tooltip display. For example, conv="(x)=>{return Math.pow(10,x)*20}" is specified, for range of value between 0 and 3, the range of convValue corresponds to 20 to 20000. |
enable | 0 ,1 |
1 |
Enable control with the pointing device. |
colors | string | "#e00;#000;#000" | Semicolon separated 3 colors for 'indicator', 'body' and 'highlight'. These colors are used in default knob (when src is not provided). |
outline | 0 ,1 |
1 |
Border display when focused. |
midilearn | 0 ,1 |
0 |
If 1 , MIDI learn function with right-click menu is enabled. |
midicc | string | null | Assign MIDI control change to this knob, with format ch.cn , here the ch is channel (1-16, ignore channel if 0) and cn is control number (0-119). |
Attribute | Options | Default | Description |
---|---|---|---|
src | string | null | url of the slider background image. Solid background color if not specified. |
knobsrc | string | null | url of the slider knob part image. Internal embedded resouce is used if not specified |
value | float | 0 |
The current value. Also used as initial value if specified |
defvalue | float | Initial 'value' is used if not specified | The default value that will be used when ctrl+click |
min | float | 0 |
Minimum value of the slider |
max | float | 100 |
Maximum value of the slider |
step | float | 1 |
Value step of the control. The 'value' is always rounded to multiple of 'step' |
width | int | 24 |
Slider display width in px |
height | int | 128 |
Slider display height in px |
knobwidth | int | same as 'width' if 'direction' is vert , or same as 'height' if 'direction' is horz |
Slider knob part width in px |
knobheight | int | same as 'width' if 'direction' is vert , or same as 'height' if 'direction' is horz |
Slider knob part height in px |
ditchlength | int | ('height'-'knobheight') or ('width'-'knobwidth') depends on 'direction' | Knob movable length |
direction | "vert" ,"horz" |
"vert" |
Slider direction. vertical or horizontal |
sensitivity | float | 1 |
Pointing device sensitivity. min-max range correspond to (128 / 'sensitivity') px |
valuetip | 0 ,1 |
1 |
Enable the overlaid value-tip display. |
tooltip | string | null |
Tooltip text that will be shown when mouse hover a while. If the text include a C-printf style value formatter like %8.2f , it will be replaced by current value. This formatter should be %[n][.][m]{d,f,x,X,s} . Here the 'n' is total columns, 'm' is after the decimal point columns. If the conv function is specified, the converted value convValue is used for display. |
conv | string | null |
Value conversion function. If this function is specified, the function is called with current value as argument and be stored as convValue . That will be used as tooltip display. For example, conv="(x)=>{return Math.pow(10,x)*20}" is specified, for range of value between 0 and 3, the range of convValue corresponds to 20 to 20000. |
enable | 0 , 1 |
1 |
Enable control with the pointing device. |
colors | string | "#e00;#000;#fff" | Semicolon separated 3 colors for 'knob', 'background' and 'highlight'. These colors are used in default knob (when src or knobsrc is not provided). |
outline | 0 ,1 |
1 |
Border display when focused. |
midilearn | 0 ,1 |
0 |
If 1 , MIDI learn function with right-click menu is enabled. |
midicc | string | null | Assign MIDI control change to this slider. with format ch.cn , here the ch is channel (1-16, ignore channel if 0) and cn is control number (0-119). |
Attribute | Options | Default | Description |
---|---|---|---|
src | string | Internal embedded resource is used if not specified | url of the vertical stitched switch image |
value | 0 ,1 |
0 |
The current value (0 or 1 ). Also used as initial value of the switch if specified |
defvalue | 0 ,1 |
Initial 'value' is used if not specified | The default value that will be used when ctrl+click |
width | int | 32 |
Switch display width in px |
height | int | 32 |
Switch display height in px |
type | "toggle" ,"kick" ,"radio" |
"toggle" |
Switch type. "toggle" switch has so-called 'checkbox' function. "radio" switch is a radio-button and the "kick" switch is a general command button |
group | string | null |
Group id string used if the 'type' is "radio" . Only one switch will be set to "1" in same group |
invert | 0 ,1 |
0 |
exchange on and off image |
tooltip | string | null |
Tooltip text that will be shown when mouse hover a while |
enable | 0 ,1 |
1 |
Enable control with the pointing device. |
colors | string | "#e00;#000;#fff" | Semicolon separated 3 colors for 'knob', 'background' and 'highlight'. These colors are used in default switch (when src is not provided). |
outline | 0 ,1 |
1 |
Border display when focused. |
midilearn | string | null | If true , MIDI learn function with right-click menu is enabled. |
midicc | string | null | Assign MIDI control change to this switch. with format ch.cn , here the ch is channel (1-16, ignore channel if 0) and cn is control number (0-119). |
Attribute | Options | Default | Description |
---|---|---|---|
src | string | Black rectangle if not specified | Background image or color. Transparent if set to "" , or url to background image. |
value | float | 0 |
The current value. Usually same as linked control |
width | int | 32 |
Parameter display width in px |
height | int | 16 |
Parameter display height in px |
fontsize | int | 9 |
Font-size of the parameter display |
colors | string | "#e00;#000" |
Semicolon separated 2 colors for text and background. background color is used when src is not defined. |
outline | 0 ,1 |
1 |
Border display when focused. |
link | string | null |
Specify the linked webaudio-knob/slider/switch by Id |
Attribute | Options | Default | Description |
---|---|---|---|
values | int array | [] |
The array of current pressed key numbers. "values" may has more than one element in multi-touch environment. |
width | int | 480 |
Keyboard display width in px |
height | int | 128 |
Keyboard display height in px |
min | int | 0 |
Lowest Key number. Each key is numbered incrementally from this number. If the "min" is not 0 and the modulo 12 is not zero, the keyboard is started from corresponding position (not-C). Note that the specified key should be a 'white-key'. |
keys | int | 25 |
Number of keys. 25 means 25 keys keyboard. |
colors | string | '#222; #eee;#ccc; #333;#000; #e88;#c44; #c33;#800' | semicolon separated 9 keyboard colors. 'border; whitekey-grad-from;whitekey-grad-to; blackkey-grad-from;blackkey-grad-to; active-whitekey-grad-from;active-whitekey-grad-to; active-blackkey-grad-from;active-blackkey-grad-to'. Each key surface can has garadient left to right with 'from' and 'to'. |
outline | 0 ,1 |
1 |
Border display when focused. |
enable | 0 ,1 |
1 |
Enable control with the pointing device. |
webaudio-knob
| webaudio-slider
| webaudio-switch
description: Each control can be setup and redraw by calling this function from JavaScript.
If the fire
parameter is undefined
or false
, this function will not fire 'change'
event. Or the change
event will be fired.
webaudio-keyboard
description: webaudio-keyboard can be setup pressing state with this function from JavaScript. corresponding key specified by the note
is pressed if the state
is non-zero otherwise the key is released. This function will NOT fire the 'change' event.
webaudio-knob
| webaudio-slider
description: 'input' event is fired when knob / slider value changes while dragging.
webaudio-knob
| webaudio-slider
| webaudio-switch
| webaudio-keyboard
description: 'change' event is fired when value changes is decided. It means mouse button release for knobs and sliders, or switch / keyboard state changes.
Also issued when setValue() function call with fire flag is nonzero.
In the event handler of webaudio-knob
,webaudio-slider
or webaudio-switch
, current value can be get with referring event.target.value
.
var knobs = document.getElementsByTagName('webaudio-knob');
for (var i = 0; i < knobs.length; i++) {
var knob = knobs[i];
knob.addEventListener('change', function(e) {
console.log(e.target.value);
});
}
For the webaudio-keyboard
, each 'change' event has the property '.note' that contain a array [key-state, key-number]
. For example event.note = [1, 60]
if the key#60 is on, or event.note = [0, 60]
if the key#60 is off.
var keyboard = document.getElementsById('keyboard');
keyboard.addEventListener('change', function(e) {
if(e.note[0])
console.log("Note-On:"+e.note[1]);
else
console.log("Note-Off:"+e.note[1]);
});
webaudio-switch (kick)
description: 'click' event is emitted if the 'kick' type webaudio-switch has clicked.
By setting the global object, WebAudioControlsOptions, you can specify default values such as the knob size or colors etc when attribute setting on each tag is omitted. This declaration should be prior to the webaduio-controls.js loading.
<script>
WebAudioControlsOptions={
useMidi:1,
knobDiameter:80,
switchWidth:40,
switchHeight:20,
};
</script>
<script src="webaudio-controls.js"></script>
The items that can be set are as follows
name | default | description |
---|---|---|
useMidi | 0 | enable control from midi devices |
midilearn | 0 | enable midilearn function for each knobs/sliders/switches |
outline | 1 | border display when focused |
knobWidth | 0 | width for knobs |
knobHeight | 0 | height for knobs |
knobDiameter | 64 | diameter for knobs |
knobSrc | null | knob image source |
knobSprites | 0 | knob image number of frames |
knobColors | "#e00;#000;#000" | color setting for knobs |
sliderWidth | 24 | width for sliders |
sliderHeight | 128 | height for sliders |
sliderColors | "#e00;#000;#fcc" | color setting for sliders |
switchWidth | 0 | width for switches |
switchHeight | 0 | height for switches |
switchDiameter | 24 | diameter for switches |
switchColors | "#e00;#000;#fcc" | color setting for switches |
paramWidth | 32 | width for param |
paramHeight | 16 | height for param |
paramColors | "#fff;#000" | color setting for param |
webaudio-knob (with sprites is 0
(default)) use a single frame knob image that indicate center position.
For example,
This image will be rotated from -135deg to +135deg. This approach will works well if the image is flat designed, but more complex animation (for example, drop-shadowed, highlighted or something elastic) will need pre-rendered frame-by-frame animation as below.
webaudio-knob (with non zero "sprites") use a vertical 'stitched' multi-frames animation image, and webaudio-switch use a vertical 'stitched' two-frames animation image.
For example,
This knob example has only 5 frames but it should has more frames for smooth animation. I recommend to use JKnobMan/WebKnobMan for making these stitched images,
- JKnobMan -- Java based Knob image creation tool.
- WebKnobMan -- WebApp version of the JknobMan
- KnobGallery -- knob data sharing space
Here is a brief instruction to export knob-image from KnobGallery
- Go to KnobGallery
- Find your favorite knob design and click 'Open with WebKnobMan'
- Click on 'Export' to download
png
file - Of course, you can create your own!
Note: comply with license requirements
To enable MIDI related functions, add the following line before the <link> tag that loads webaudio-controls.html
<script>WebAudioControlsOptions={useMidi:1}</script>
Midilearn right click menu: add a midilearn=1
attribute to the <webaudio-knob>
, <webaudio-slider>
and <webaudio-switch>
elements. Then right click on the element in the GUI, a midi learn menu should appear. Then, operate one of your midi controller and it should start actionning the webaudio-controls widget in the HTML page. You can hot plug/unplug midi devices, they will be detected.
Declarative association between a midi controller and a GUI webaudiocontrol: There is also an HTML midicc="channel.cc#"
attribute that works like this: midicc="3.2"
means "listen to a cc event on channel 3, cc number 2". If you don't know the channel/cc number of your controller: 1) add a midilearn=1
attribute so that a right click on the GUI widget will display the midilearn menu, 2) select "learn" in the menu, 3) operate your knob/slider/switch, normally the midi controller and the GUI object are in sync. 4) look at the devtool console, there is a message indicating the channel and cc number, for example "channel 0, cc 28". Then if you add the attribute midicc="0.28" to the HTML of your knob/slider/switch, the midi mapping between your GUI webaudiocontrol and your midi controller will be automatic. Follow the links at the end of this section and look at the HTML source code to see some examples.
Example: associate a knob with a controller on channel 7, cc number 7:
<webaudio-knob midilearn=true midicc="7.7" ...></webaudio-knob>
External midi event listener (hook): you can also declare in your HTML file your own midi event listener (for example for listening to program changes events): use the webAudioControlsMidiManager
object, that comes with an addMidiListener
method. Like that you will benefit from the MIDI code included in the webaudiocontrols. Here is an example (also, look at the source code of the Sample1.html demo, and open the devtool console to see midi messages received by the hook at the end of the HTML file).
<script>
// add this to your html page that uses webaudiocontrols
webAudioControlsMidiManager.addMidiListener(function(event) {
var data = event.data;
var channel = data[0] & 0xf;
var controlNumber = data[1];
console.log("Midi event hook: data:[" + data + "] channel:" + channel + " cc:"+controlNumber);
// do whatever you want with the event
// ...
});
</script>
Demo at: https://wasabi.i3s.unice.fr/AmpSimFA/ and at https://wasabi.i3s.unice.fr/AmpSimFA/sample1.html
WebAudio-Controls is developped based on:
- WebAudio-Knob by Eiji Kitamura
- WebAudio-Slider by Ryoya KAWAI
- WebAudio-Switch by Keisuke Ai
Integrated and enhanced by g200kg
Copyright (c) 2013 Eiji Kitamura / Ryoya KAWAI / Keisuke Ai / g200kg / @micbuffa / @CellouBalde
Licensed under the Apache License, Version 2.0
Knob/Switch images in samples are from Knob Gallery
switch_toggle.knob by az (c) 2011 CC-BY