Merge pull request #59 from dtinth/dtinth/bcba

docs/antora.yml

@@ -0,0 +1,5 @@
+name: webmidicon
+version: master
+title: 'WebMIDICon'
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,11 @@
+* xref:index.adoc[]
+* xref:connect:index.adoc[]
+** xref:connect:BLE-MIDI.adoc[]
+** xref:connect:IAC.adoc[]
+** xref:connect:IDAM.adoc[]
+** xref:connect:RTP-MIDI.adoc[]
+** xref:connect:USB-MIDI.adoc[]
+* xref:midi-keybindings.adoc[]
+* xref:pedal.adoc[]
+* xref:touch-instruments.adoc[]
+* xref:finger-drumming.adoc[]

docs/modules/ROOT/pages/finger-drumming.adoc

@@ -0,0 +1,7 @@
+= Finger drumming
+
+If you have a touchscreen, you can use the *Drum pad* to https://www.youtube.com/watch?v=CHarkZrQH34:[play drums with your fingers].
+
+== Controlling the hit velocity
+
+Touching nearer the center produces louder hits.

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,23 @@
+[reftext="About WebMIDICon"]
+= WebMIDICon
+
+A collection of *hackable web-based MIDI instruments*, implemented as a web-based MIDI controller.
+
+I wanted to create a MIDI instrument that allows me to jam with other musicians. Play MIDI with your PC keyboard, or with a touch screen on an iPad.
+
+== Features
+
+WebMIDICon works on desktop, tablet, and mobile devices. It lets you use one tool for many use cases.
+
+image::connection_options.png[Connection options]
+
+On the desktop, you can xref:midi-keybindings.adoc[play MIDI notes with your keyboard], and optionally xref:pedal.adoc#joypedal[plug in a game controller to use as a sustain pedal].
+
+On tablets and mobile devices, you can play MIDI notes and drum notes with your finger. You can put your device on the floor and xref:pedal.adoc#ipedal[use its touch screen as a sustain pedal].
+
+== Demos
+
+Check out https://dt.in.th/webmidicon.html[the demos on my website].
+
+[link="https://dt.in.th/webmidicon.html"]
+image::https://ss.dt.in.th/api/screenshots/dt.in.th-webmidicon.png[]

docs/modules/ROOT/pages/midi-keybindings.adoc

@@ -0,0 +1,29 @@
+= Play notes with your keyboard
+:experimental:
+
+When WebMIDICon is focused, you can use these keys to play MIDI notes with your QWERTY keyboard. There are 2 keymaps available.
+
+== Piano Keymap
+
+The piano keymap is based on the piano keyboard layout.
+
+image::keyboard.svg[]
+
+=== Access higher notes
+
+If you hold down the kbd:[Alt] key, the notes on the upper row will be shifted up an octave, giving you access to a higher range.
+
+== Chromatic Keymap
+
+The chromatic keymap is based on the B-system chromatic button accordian layout.
+
+image::keyboard-chromatic.svg[]
+
+== Transpose
+
+The keys marked as green are used for setting the transpose option. This lets you quickly change keys.
+
+[#sustain]
+== Sustain pedal
+
+You can hold down the kbd:[Space] key to activate xref:pedal.adoc[the sustain pedal].

docs/modules/ROOT/pages/pedal.adoc

@@ -0,0 +1,23 @@
+= Activate the sustain pedal
+:experimental:
+
+You can activate the sustain pedal in many ways.
+
+[#keyboard]
+== Use the Space key
+
+You can xref:midi-keybindings.adoc#sustain[hold down the space bar] on your keyboard and the sustain pedal will be activated.
+
+[#joypedal]
+== Use a game controller
+
+If you have a game controller, you can use it to control the sustain pedal.
+Go to the settings page and set the desired button numbers.
+To obtain the key number, you can use the https://gamepad-tester.com/[Gamepad Tester] website.
+
+https://www.youtube.com/watch?v=lFd45YYASWo[Here’s a video of me using a Dualshock controller as a sustain pedal.]
+
+[#ipedal]
+== Use a touchscreen
+
+You can use the *iPedal* instrument to control the sustain pedal with a touchscreen.

docs/modules/ROOT/pages/touch-instruments.adoc

@@ -0,0 +1,24 @@
+= Play notes with your touchscreen
+
+WebMIDICon comes with multiple *touch instruments* that can be played with your touchscreen.
+
+== Keyboards
+
+Piano::
+A normal piano keyboard. It has 3 rows, giving you access to 4 octaves.
+Jammer::
+An http://www.altkeyboards.com/instruments/isomorphic-keyboards[isomorphic keyboard] based on the http://www.altkeyboards.com/instruments/jammer[Jammer] https://en.wikipedia.org/wiki/Wicki%E2%80%93Hayden_note_layout[(Wicki-Hayden) note layout].
+Sonome::
+An http://www.altkeyboards.com/instruments/isomorphic-keyboards[isomorphic keyboard] based on the http://www.altkeyboards.com/instruments/sonomes[Sonome] https://en.wikipedia.org/wiki/Harmonic_table_note_layout[(harmonic table) note layout].
+C-System::
+An http://www.altkeyboards.com/instruments/isomorphic-keyboards[isomorphic keyboard] based on the C-system layout, as used in https://en.wikipedia.org/wiki/Chromatic_button_accordion[Chromatic button accordions].
+
+== Drums
+
+Drum pad::
+A 4x4 drum pad that lets you xref:finger-drumming.adoc[finger drum]. It supports variable velocity, producing natural-sounding drum hits.
+
+== Pedals
+
+iPedal::
+Put your device on the floor and use it as a sustain pedal or a kick drum.

docs/modules/connect/pages/BLE-MIDI.adoc

@@ -0,0 +1,85 @@
+= BLE-MIDI
+
+When it comes to *BLE-MIDI (MIDI over Bluetooth Low Energy)* there are 2
+main roles:
+
+* The *Central* (who discovers and connects to Peripherals); and
+* The *Peripheral* (who advertises MIDI services so Centrals can connect
+to it).
+
+[#macOS]
+== macOS
+
+A macOS device can act as both the *Central* and the *Peripheral* at the
+same time. You set this up in the *Audio MIDI Setup* app.
+Once the Bluetooth connection is establised, the Bluetooth device
+becomes available to every macOS app.
+
+See
+https://support.apple.com/guide/audio-midi-setup/set-up-bluetooth-midi-devices-ams33f013765/mac[*“Set
+up Bluetooth MIDI devices in Audio MIDI Setup on Mac”* on Apple Support]
+for more information.
+
+[#Android]
+== Android
+
+You can use the
+https://play.google.com/store/apps/details?id=com.mobileer.example.midibtlepairing[*MIDI
+BLE Connect*] app to become a Central establish a MIDI connection to
+other peripherals. Other apps can then use this connection to send and
+receive MIDI data.
+
+[#iOS]
+== iOS
+
+An iOS device can act as both the *Central* and the *Peripheral* at the
+same time, but it varies from application to application.
+
+* *GarageBand* can act as the Central.
+** To set up: Settings → Advanced → Bluetooth MIDI Devices.
+* *Web MIDI Browser* can act as both the Central and the Peripheral.
+** To set up: Settings → Bluetooth MIDI → Setup Bluetooth MIDI
+Central/Peripheral
+* *Midiflow* can act as both the Central and the Peripheral.
+** To set up: Config → Bluetooth → “Advertise this device” or “Find
+nearby devices”
+
+====
+Connecting *WebMIDICon* running on *iOS* through *Bluetooth* to *Logic
+Pro* running on *macOS*:
+
+image::BLE-MIDI-iOS-macOS.png[image]
+====
+
+[#Windows]
+== Windows
+
+There is an application called
+https://www.microsoft.com/en-us/p/midiberry/9n39720h2m05?activetab=pivot:overviewtab[MIDIberry]
+that makes your device act as a *Central*. At least Windows 10 is
+required.
+
+WARNING: From my testing, only Bluetooth Input is supported; I could not get
+Output to work. Also the app may crash from time to time.
+
+. Go to *Bluetooth and other devices settings*.
+. Click *Add device* and then make sure your device is discoverable.
+. Select *Bluetooth* and then pair your devices together.
+. Open *MIDIberry*.
+. Select the Bluetooth *Input*.
+. Select the output MIDI device to send the input to. If you want to
+send it to another Windows application, use an link:./IAC.md[IAC
+device].
+
+[#device]
+== MIDI devices
+
+Some devices have built-in BLE-MIDI support, such as the KORG’s
+https://www.korg.com/us/products/computergear/microkey2_air/[microKEY
+Air].
+
+For other devices, you can buy adapters such as Yamaha’s
+https://jp.yamaha.com/products/music_production/accessories/md-bt01/index.html[MD-BT01]
+(for devices with MIDI ports) or
+https://jp.yamaha.com/products/musical_instruments/pianos/accessories/interfaces/ud-bt01/index.html[UD-BT01]
+(for devices with a USB port).

docs/modules/connect/pages/IAC.adoc

@@ -0,0 +1,49 @@
+= IAC
+
+An *IAC (Inter-App Communication) device* is a virtual MIDI device that allows multiple MIDI applications on the same device to communicate with each other.
+
+[#macOS]
+== macOS
+
+macOS comes with a built-in *IAC Driver* to facilitate MIDI connections
+between applications. See
+https://support.apple.com/guide/audio-midi-setup/transfer-midi-information-between-apps-ams1013/mac[*“Transfer
+MIDI information between apps in Audio MIDI Setup on Mac”* on Apple
+Support] for more information.
+
+====
+Connecting *WebMIDICon* through *IAC Driver* to *Logic Pro* running on
+the same machine:
+
+image::IAC-macOS.png[image]
+====
+
+[#Windows]
+== Windows
+
+You can install https://www.nerds.de/en/loopbe1.html[LoopBe1], a virtual
+MIDI device driver for Windows which is free for non-commercial use. If
+you need more than 1 port, you can buy the
+https://www.nerds.de/en/loopbe30.html[LoopBe30] device.
+
+====
+Connecting *WebMIDICon* through *LoopBe1* to *FL Studio* running on the
+same machine:
+
+image::IAC-Windows.png[image]
+====
+
+[#iOS]
+== iOS
+
+You can buy https://www.midiflow.com/[Midiflow] which lets you create
+virtual MIDI devices that other apps can use. Please note that iOS is
+not that great at multitasking, and from my experience, the application
+in the background is automatically killed by the OS after a while.
+
+====
+Connecting *WebMIDICon* through *Midiflow* to *GarageBand* running on
+the same iPhone:
+
+image::IAC-macOS.png[image]
+====

docs/modules/connect/pages/IDAM.adoc

@@ -0,0 +1,7 @@
+= IDAM
+
+*IDAM (Inter-Device Audio and MIDI)* is a protocol for sending audio and MIDI between iOS/iPadOS devices and macOS via a USB cable.
+
+====
+video::WIf1P7n3Eqk[youtube]
+====

docs/modules/connect/pages/RTP-MIDI.adoc

@@ -0,0 +1,30 @@
+= RTP-MIDI
+
+The https://en.wikipedia.org/wiki/RTP-MIDI[*RTP-MIDI*] protocol lets device exchange MIDI data over the network, such as Wi-Fi or LAN.
+
+To minimize the latency, I recommend connecting devices using a LAN cable if possible. Using an ad-hoc Wi-Fi network can also give lower latency than having 2 devices communicate via a Wi-Fi router.
+
+[#macOS]
+== macOS
+
+See https://support.apple.com/guide/audio-midi-setup/share-midi-information-over-a-network-ams1012/mac[*“Share MIDI information over a network in Audio MIDI Setup on Mac”* on Apple Support] for more information.
+
+====
+.The MIDI Network Setup window in the Audio MIDI Setup app
+image::RTP-MIDI-macOS.png[image]
+====
+
+[#Windows]
+== Windows
+
+Windows users can use the https://www.tobias-erichsen.de/software/rtpmidi.html[rtpMIDI] driver. It is free for private, non-commercial use.
+
+[#iOS]
+== iOS
+
+Use the https://apps.apple.com/us/app/midi-network/id1102428729[MIDI Network] app to connect your iOS device to other RTP-MIDI capable devices.
+
+====
+.The MIDI network app
+image::RTP-MIDI-iOS.png[image]
+====

docs/modules/connect/pages/USB-MIDI.adoc

@@ -0,0 +1,37 @@
+= USB-MIDI
+
+When it comes to USB, there are 2 main roles: the *Host* and the
+*Device*.
+
+[#macOS]
+== macOS
+
+macOS can act as a *Host*. Just plug in USB MIDI devices and it can be
+used right away.
+
+[#Windows]
+== Windows
+
+Windows can act as a *Host*. Just plug in USB MIDI devices and it can be
+used right away.
+
+[#iOS]
+== iOS
+
+iOS can act as a *Host*. Just plug in USB MIDI devices through the and
+it can be used right away. Many iOS devices have only the Lightning
+port. To plug in USB MIDI Device you would need an adapter such as the
+https://www.apple.com/shop/product/MK0W2AM/A/lightning-to-usb-3-camera-adapter[Lightning
+to USB 3 Camera Adapter].
+
+iOS can also act as a *Device* when plugged into a macOS *Host* in
+link:./IDAM.md[IDAM] mode. Unfortunately, the IDAM mode only works with
+macOS.
+
+[#Android]
+== Android
+
+Android can act as a *Host*. Just plug in USB MIDI devices (through USB
+adapters) and it can be used right away.
+
+Android can also as a *Device* by changing the USB mode to MIDI.

docs/modules/connect/pages/index.adoc

@@ -0,0 +1,44 @@
+= MIDI connection guide
+
+WebMIDICon, built on the Web MIDI technology, makes it very flexible to use it with various MIDI appliances (DAWs and synthesizers), through various mediums.
+
+image::ROOT:connection_options.png[Connection options]
+
+This part of the documentation will guide you through the different connection options, and how to set them up.
+Although the guides here are written for WebMIDICon, they can be used with any MIDI-enabled apps.
+
+[cols="1,3"]
+|===
+|From |To
+
+|From a macOS app:
+|   To other apps on the same machine: xref:IAC.adoc#macOS[IAC] +
+    To apps on Windows/macOS/iOS over Wi-Fi/LAN: xref:RTP-MIDI.adoc#macOS[RTP-MIDI] +
+    To apps on macOS/iOS/Android over Bluetooth: xref:BLE-MIDI.adoc#macOS[BLE-MIDI] +
+    To apps on iOS over USB: xref:IDAM.adoc[] +
+    To apps on Android over USB: xref:USB-MIDI.adoc#macOS[USB-MIDI] +
+    To MIDI devices over USB: xref:USB-MIDI.adoc#macOS[USB-MIDI]
+
+|From a Windows app
+|   To other apps on the same machine: xref:IAC.adoc#Windows[IAC] +
+    To apps on Windows/macOS/iOS over Wi-Fi/LAN: xref:RTP-MIDI.adoc#Windows[RTP-MIDI] +
+    To apps on Android over USB: xref:USB-MIDI.adoc#Windows[USB-MIDI] +
+    To MIDI devices over USB: xref:USB-MIDI.adoc#Windows[USB-MIDI]
+
+|From an iOS app
+|   To other apps on the same device: xref:IAC.adoc#iOS[IAC] +
+    To apps on macOS/iOS/Android over Bluetooth: xref:BLE-MIDI.adoc#iOS[BLE-MIDI] +
+    To apps on Windows/macOS/iOS over Wi-Fi/LAN: xref:RTP-MIDI.adoc#iOS[RTP-MIDI] +
+    To apps on macOS over USB: xref:IDAM.adoc[] +
+    To apps on Android over USB: xref:USB-MIDI.adoc#iOS[USB-MIDI] +
+    To MIDI devices over USB: xref:USB-MIDI.adoc#iOS[USB-MIDI]
+
+|From an Android app
+|   To apps on macOS/iOS over Bluetooth: xref:BLE-MIDI.adoc#Android[BLE-MIDI] +
+    To apps on Windows/macOS/Android over USB: xref:USB-MIDI.adoc#Android[USB-MIDI] +
+    To MIDI devices over USB: xref:USB-MIDI.adoc#Android[USB-MIDI]
+
+|From a MIDI device
+|   To apps on macOS/iOS/Android over Bluetooth: xref:BLE-MIDI.adoc#device[BLE-MIDI] +
+    To apps on Windows/macOS/iOS/Android over USB: xref:USB-MIDI.adoc[USB-MIDI]
+|===