benc-uk / touchmidi

Flexible HTML5 based touch based control surface for MIDI

Touch MIDI

'Touch MIDI' is a flexible MIDI control surface for touch based devices using HTML5.
The project consists of a set of custom HTML elements which allows the user to build a simple HTML page which can act as a MIDI controller. The elements represent various physical controls such as sliders and buttons, and can be configured to send a range of MIDI messages.

Currently supported MIDI messages:

• CC (continuous controller).
• Notes on & off with velocity.
• NRPN (non-registered parameter number), including high resolution (14-bit) values
• Program change with LSB/MSB bank select
• Pitch bend

An example layout showing four encoders, a button, a slider and the XY pad

This is complete rewrite of an older Touch MIDI project. It has been rewritten using web components (using the excellent Hybrids.js as a library), ES6 modules, WebPack and a much cleaner design.

Core technologies:

• Web MIDI API
• Web Components & custom elements
• Various modern web features: ES6 modules, inline SVG, ES6 DOM APIs, CSS3 tricks

Design goals:

• No backend or server required.
• Works 100% in browser (Only client side JS).
• Works with both mouse and touch screen devices.
• Supports multiple touches at the same time, and tracks movement of each.
• Layout HTML files can be opened and run from local file:// URL.

Supported Browsers

Although the Web MIDI API spec isn't new (it was drafted in 2015) support for it is currently limited to Chrome, Edge and Opera

Mobile Chrome on an Android device has also been tested as working

User Guide

Getting started, you'll need:

• A supported browser :)
• MIDI device attached to your machine, either directly via USB (e.g. a USB-MIDI based device) or via an audio interface or other MIDI adapter.
• Open one of the supplied layouts

Upon opening the layout HTML, a configuration dialog will be shown, which allows the setup of some MIDI & other settings:

• MIDI device - A list of all attached MIDI output devices will be shown, one must be selected before you can close the config dialog and start the layout. This setting will be remembered for this layout file (HTML filename)
• MIDI channel - Layout files can be designed to support multiple MIDI channels or a single global MIDI channel. You have two choices:
  • If a MIDI channel number is set here it will be used by all controls in the layout. Pick this when controlling a single device which responds on a single channel (i.e. is mono-timbral)
  • A special option 'Set By Layout' can be picked, which defers all channel settings to the layout HTML file, and this sets what channel is used on a per control basis (the default is channel 1 if it's not specified). This allows for both multi-timbral control of a device, and multi-device control
• Save & Restore at Startup - When enabled the values of certain controls (sliders, encoders and XY pads) are saved when they are changed, and reloaded at startup. In addition MIDI messages are sent at startup, sending the saved values, in order to set the device(s) to the same state as they were previously. This can act as a form of preset saving, however this feature can have some side effects, so is not enabled by default.
• Start Fullscreen - When enabled the browser will switch to fullscreen mode

Device Layouts

A set of layouts is provided with the project. These are a demonstration of how to use the project, a reference set of working layouts, and created for my own music production use.

Device Layouts{: .btn-blue}

Widgets / Controls

There are a range of controls available

Slider

A slider represents a fader type control as seen on a mixer, sliders can send MIDI CC and NRPN values.

Encoder

An encoder represents a rotating knob control as seen on many synths and music devices, encoders can send MIDI CC and NRPN values. They are very similar to sliders in function but presented in a more compact form.

Button

A button can fulfil a range of roles, it can trigger MIDI notes, as well as send fixed CC, NRPN values. Buttons can also be set to toggle on & off and send different values when released.

XY Pad

XY pads are similar to a sliders but work in two dimensions, so a pad can control a pair of CC values. A common use is to set a pad to modify the filter cutoff and resonance (e.g. MIDI CC 71 and 74)

Counter

A counter consists of two buttons, one for incrementing and decrementing an given CC value. Work in progress

Known Issues

• Some controls do not resize fully when resizing the browser, reloading the page can fix this.

Developer Guide

If you wish to create your own layout files, please refer to the developer reference guide

Advanced Usage

You can bypass the MIDI configuration dialog and automatially start the layout by passing parameters on the URL. To bypass the dialog add any of the following parameters to the URL.

Accepted URL parameters are:

• device=<device_id> - Set the device to use, if not provided output-1 is used.
• channel=<channel_num> - Set the channel (1 - 16) to use, if not provided channel 1 is used. If you specify channel 0, that is the same as 'Set By Layout' mode (see above).
• restore=true|false - If values are to be saved & restored, if not provided set to false.
• nomidi=true - Disable the config dialog and also bypass MIDI access, useful when testing a layout on a machine without any MIDI devices attached.

Examples.
Start the layout example.html on the default device and channel 7
file://example.html?channel=7

Start the layout example.html on the device 'output-2' and channel 3
file://example.html?channel=3&device=output-2

Start the layout example.html on the device 'output-2' and channel 5, with saving enabled
file://example.html?channel=5&device=output-2&restore=true

Note. Device IDs are automatically assigned by the operating system, and take the form output-n where n is an integer starting at 1, e.g. output-1, output-2 etc. You will get a warning if the device id is not found

touchmidi's Issues

Allow Link to Specify Target MIDI Device

Hello Ben,

Thanks for your project! I'm making a digital audio mixer and I've been using the old version. I'm now updating to the new version. Looks great!

On the old version I was able to specify the name of the MIDI device in the link to the page, so that I can preselect a MIDI device.

This would automatically locate the "Teensy MIDI Audio" device.
<a class="menu" href="index.html?device=Teensy%20MIDI/Audio">VOLUME (I2C)</a>
I use this because I created a menu up top of the page that calls up the i2c mixer, dsp mixer, effect controls, etc. Each page focuses on a particular component of the mixer.

The newer version doesn't support this. How can we preselect a MIDI device on the page, or in the URL? Any idea? (I realize this is a feature not a bug).

I would love to be able to preselect a device upon load (for hardcoding a device), or possibly the option to select the device once and then every page afterwards would select the same device that's already been selected?

Thanks again!
Jay

Sending a click, mousedown or touchstart event to a toggle midi-button from an ordinary HTML5 button

Hi! I'm building a layout with 16 toggle midi-buttons that acts as mute buttons. They send a program change message (program numbers 1 to 16 on a fixed channel, same program number for both "on" and "off" values). Such messages are used by target software to toggle its mute buttons.
I want to add and ordinary HTML5 button to reset all toggle midi-buttons to its initial state (_pressed="false"). If I assign an ID attribute for each midi-button and iterate them by means of a Javascript's FOR loop, forcing _pressed attribute to "false", I get all midi-buttons unpressed, but no eventReleased is executed by none of the buttons and no program change message with off-value is sent. This ends with a clean midi-buttons state in the layout but with an unclean mute buttons state in the software controlled by layout. Then I've tried to send click, mousedown and touchstart events to midi-buttons with Javascript's MouseEvent() and dispatchEvent(): while midi-buttons apparently receive these events (adding an "onclick", "onmousedown" or "ontouchstart" listener and triggering an alert() for those events it's possible to see that events are been catched by midi-buttons) no eventReleased is executed by none of the buttons and again no program change message with off-vale is sent, and even the _pressed attribute remains all "true". I've tried the dispatchEvent() with "bubbles" value "true" and "false" and "composed" value "true" and "false" (recommendations on the web suggest composed="true" when dealing with events and shadow DOM) . Sure I'm missing something, my Javascript's knowledge is limited and I'm completely new to web components in general and Hybrids in particular.
Can someone help me with this? Is it necessary some change to button.js code to manage these events?
Congratulations for the useful, beautiful and hard work made with TouchMIDI, is very appreciated here!
Thanks in advance and best regards!

CC for "0" does not function

I have a straightforward implementation of this in my studio. I'm using it to send CC to an amp switcher. The switcher uses an assignable MIDI channel and CC 0 - 10 to select a particular amplifier. However, I can't get CC 0 to work. Everything else functions perfectly. Thanks for developing this and any advice is appreciated.

Stray note: I noticed that all the local .css files don't apply to the custom page I built. Is there a way to tweak the local files and have it affect the page I'm working on?

Pitch: toggle back to 0 on touch lift

Please consider making the pitch a "pitch wheel" which classically snaps back to zero (with some speed and bounce?) after letting go of the pitch wheel.

Finding the right speed and bounce (bounce needed?) could be difficult to get right. May be based on the distance the wheel is pulled away from zero? Interesting programming challenge tbh.

FYI if you download a midi soundfont player on the phone your app still works. Just wanted to point that out, nice work. :-)

Feeback Communication - Suggested Enhancement

MIDI feedback back is not supported is it? The communication is one way, correct?

It would be great if the user could created a set of faders to change channel volumes in a DAW and also have those faders respond to changes made directly in the DAW.

If it's possible, how do I implement? If not, I would love to the the enhancement.

Thanks and thanks again for adding pitch bend!

Enhancement - Support for Pitch Bend

Please consider adding support for Pitch Bend.

sysex support

Thanks for this great tool!
I need sysex support. If you don't have time for this could you please point me in the right direction?

npm package with the midi code?

This framework is awesome and thanks for making it open source! I'd love to be able to just use the internal midi calling classes (without the ui) - would be great if that could be published on npm. Thank you!