--- a/midi/specification.html Wed Sep 12 11:04:14 2012 +0100
+++ b/midi/specification.html Mon Oct 01 16:20:03 2012 -0700
@@ -45,20 +45,32 @@
<body>
<section id="abstract">
<p>
- This document introduces an API for accessing and manipulating
- the MIDI devices available on the users' systems.
+ Some user agents have connected music devices, such as synthesizers,
+ keyboard and other controllers, and drum machines. The widely adopted
+ Musical Instrument Digital Interface (MIDI) protocol enables
+ electronic musical instruments, controllers and computers to
+ ommunicate and synchronize with each other. MIDI does not transmit
+ audio signals: instead, it sends event messages about musical notes,
+ controller signals for parameters such as volume, vibrato and panning,
+ cues and clock signals to set the tempo, and system-specific MIDI
+ communications (e.g. to remotely store synthesizer-specific patch
+ data). This same protocol has become a standard for non-musical uses,
+ such as show control, lighting and special effects control.
+ </p>
+ <p>
+ This specification defines an API supporting the MIDI protocol, enabling web applications to enumerate and select MIDI input and output devices on the client system and send and receive MIDI messages. It is intended to enable non-music MIDI applications as well as music ones, by providing low-level access to the MIDI devices available on the users' systems.
+ </p>
+ <p>
+ This API is designed to be used in conjunction with other APIs and elements of the web platform, notably the Web Audio API and High-Resolution Time. This API is also intended to be familiar to users of other MIDI APIs.
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
The Web MIDI API specification defines a means for web developers to
- enumerate, manipulate and access MIDI devices. Having an API for MIDI
- gives a means to make various applications using existing software and
- hardware synths, as well as light systems and other mechanical
- apparatus controlled by MIDI, along with a method of communication with
- existing DAW (Digital Audio Workstation), trackers and other music
- software on the user's computer.
+ enumerate, manipulate and access MIDI devices - for example interfaces that may provide hardware MIDI ports with other devices plugged in to them and USB devices that support the USB-MIDI specification. Having a Web API for MIDI enables web applications that use existing software and
+ hardware synthesizers, hardware music controllers and light systems and other mechanical
+ apparatus controlled by MIDI.
</p>
</section>
@@ -113,8 +125,8 @@
<h2>Security and privacy considerations</h2>
<p>
Allowing the enumeration of the users MIDI devices and access to the
- information they send is a potential prime target for fingerprinting,
- and possibly eavesdropping. Therefore implementations SHOULD carefully
+ information they send is a potential target for fingerprinting of MIDI
+ interfaces and connected MIDI devices. Implementations SHOULD
follow the <a href="#idl-def-NavigatorMIDIAccess">suggested security model</a>.
</p>
</section>
@@ -129,21 +141,24 @@
title="[NoInterfaceObject] interface NavigatorMIDIAccess">
<dt>void getMIDIAccess(NavigatorMIDIAccessSuccessCallback
successCallback,
- NavigatorMIDIAccessErrorCallback?
+ optional NavigatorMIDIAccessErrorCallback?
errorCallback)</dt>
<dd>
<p>
- Prompts user for permission to use their MIDI Devices.
+ Obtains an interface to enumerate and request access to MIDI
+ devices on the user's system.
</p>
<p>
- If the user accepts, <var>successCallback</var> is invoked,
- with a <code><a>MIDIAccess</a></code> object as its argument.
+ This call may prompt the user for access to MIDI devices. If
+ the user accepts or the call is otherwise approved,
+ <var>successCallback</var> is invoked, with a
+ <code><a>MIDIAccess</a></code> object as its argument.
</p>
<p>
- If the user declines, the <var>errorCallback</var> (if any)
- is invoked.
+ If the user declines or the call is denied, the
+ <var>errorCallback</var> (if any) is invoked.
</p>
<p>
@@ -178,8 +193,13 @@
below.
</p></li>
- <li>
- <p>
+ <li><p>
+ Optionally, e.g. based on a previously-established user
+ preference, jump to the step labeled <em>success</em>
+ below.
+ </p></li>
+
+ <li><p>
Prompt the user in a user-agent-specific manner for
permission to provide the entry script's origin with a
<code><a>MIDIAccess</a></code> object representing
@@ -187,29 +207,21 @@
</p>
<p>
- If the user denies permission, jump to the step labeled
+ If permission is denied, jump to the step labeled
<em>failure</em> below. If the user never responds, this
algorithm stalls on this step.
</p>
</li>
<li><p>
- Let <var>access</var> be the <code><a
- >MIDIAccess</a></code> object for which the user granted
- access.
+ <em>success</em>: Let <var>access</var> be the <code><a
+ >MIDIAccess</a></code> object for which access has been
+ granted.
</p></li>
<li><p>
Queue a task to invoke <var>successCallback</var> with
- <var>access</var> as its argument.
- </p></li>
-
- <li><p>
- If <var>successCallback</var> is null, abort these steps.
- </p></li>
-
- <li><p>
- Abort these steps.
+ <var>access</var> as its argument, and return.
</p></li>
<li><p>
@@ -235,18 +247,6 @@
Queue a task to invoke <var>errorCallback</var> with
<var>error</var> as its argument.
</p></li>
-
- <li><p>
- If <var>successCallback</var> is null, abort these steps.
- </p></li>
-
- <li><p>
- If <var>successCallback</var> is null, abort these steps.
- </p></li>
-
- <li><p>
- If <var>successCallback</var> is null, abort these steps.
- </p></li>
</ol>
<p>
@@ -269,7 +269,15 @@
<dd>
A <code><a>MIDIAccess</a></code> object created to provide
- script access to the user's MIDI devices.
+ script access to the user's MIDI devices. This object is used
+ to enumerate and obtain access to individual MIDI devices.
+ <p><em>Note</em>: The term "MIDI device" in this specification
+ refers to a MIDI interface available to the host system; for
+ example, if a hardware MIDI adapter is connected to the host
+ system, it will be enumerated as a single device, even if
+ several MIDI-supporting devices (such as synthesizers or drum
+ machines) are plugged into hardware MIDI ports on the
+ adapter.
</dd>
</dl>
</section>
@@ -285,7 +293,7 @@
<dt>const unsigned short PERMISSION_DENIED = 1</dt>
<dd>
- The user denied the page permission to use the user's MIDI
+ The application was denied permission to use the user's MIDI
devices.
</dd>
@@ -316,6 +324,9 @@
<section>
<h2><a>MIDIAccess</a> Interface</h2>
+ <p>This interface provides the methods to enumerate MIDI input and output
+ devices, and obtain access to an individual device.</p>
+
<dl title="[NoInterfaceObject]
interface MIDIAccess"
class="idl">
@@ -329,7 +340,7 @@
Returns a list of the MIDI output ports available on the system.
<!-- TODO: Specify the steps the UA is required to take. -->
</dd>
- <dt><a>MIDIInput</a> getInput(MIDIPort or DOMString target)</dt>
+ <dt><a>MIDIInput</a> getInput(MIDIPort or DOMString or short target)</dt>
<dd>
Acquires access to the input <code><a>MIDIPort</a></code> requested
as a <code><a>MIDIInput</a></code> instance.
@@ -347,7 +358,13 @@
If the <var>target</var> is a DOMString,
<var>target</var> will be a <code><a>MIDIPort</a></code>
whose <code>fingerprint</code> matches the supplied
- DOMString.
+ DOMString. If <var>target</var> is a short, <var>target</var>
+ will be a <code><a>MIDIPort</a></code> that matches the supplied
+ index in the sequence returned by <code><a>enumerateInputs()</a></code>.
+ If the <var>target</var> parameter is a DOMString and there is no MIDIPort
+ that matches the fingerprint, or if the <var>target</var> parameter is a
+ short outside the bounds of available MIDI inputs, throw a
+ <code>TYPE_ERROR</code> exception.
</li>
<li>
@@ -374,13 +391,13 @@
<li>
<p>
- Return a <code>MIDIInput</code> corresponding the
+ Return a <code>MIDIInput</code> object corresponding to the
<var>target</var> argument.
</p>
</li>
</ol>
</dd>
- <dt><a>MIDIOutput</a> getOutput(MIDIPort or DOMString target)</dt>
+ <dt><a>MIDIOutput</a> getOutput(MIDIPort or DOMString or short target)</dt>
<dd>
Acquires access to the output <code><a>MIDIPort</a></code> requested
as a <code><a>MIDIOutput</a></code> instance.
@@ -398,7 +415,13 @@
If the <var>target</var> is a DOMString,
<var>target</var> will be a <code><a>MIDIPort</a></code>
whose <code>fingerprint</code> matches the supplied
- DOMString.
+ DOMString. If <var>target</var> is a short, <var>target</var>
+ will be a <code><a>MIDIPort</a></code> that matches the supplied
+ index in the sequence returned by <code><a>enumerateOutputs()</a></code>.
+ If the <var>target</var> parameter is a DOMString and there is no MIDIPort
+ that matches the fingerprint, or if the <var>target</var> parameter is a
+ short outside the bounds of available MIDI inputs, throw a
+ <code>TYPE_ERROR</code> exception.
</li>
<li>
@@ -425,7 +448,7 @@
<li>
<p>
- Return a <code>MIDIOutput</code> corresponding the
+ Return a <code>MIDIOutput</code> object corresponding to the
<var>target</var> argument.
</p>
</li>
@@ -437,10 +460,12 @@
<section>
<h2><a>MIDIPort</a> Interface</h2>
+ <p>This interface represents a MIDI input or output port.</p>
+
<p id="event-midiport-disconnect">
Whenever the MIDI port corresponding the
<code><a>MIDIPort</a></code> is disconnected or becomes unavailable,
- the UA SHOULD run the following steps:
+ if supported by the underlying system the UA SHOULD run the following steps:
</p>
<ol>
@@ -469,6 +494,21 @@
</li>
</ol>
+ <div class="note">
+ <p>
+ The <code><a>disconnect</a></code> and
+ <code><a>connect</a></code> events may not be applicable to all
+ MIDI ports or OS APIs. For example, some system APIs do not dynamically
+ notify applications when MIDI ports become available or unavailable.
+ Therefore the semantic here is SHOULD, rather than MUST.
+ </p>
+ <p>It is also important to note again that the MIDIPort represents an
+ input or output interface, not necessarily an endpoint MIDI device; it
+ is not possible, using this system, to be notified when a synthesizer
+ is plugged into a 5-pin DIN MIDI port on a hardware MIDI interface.
+ </p>
+ </div>
+
<dl class="idl" title='enum MIDIPortType'>
<dt>"input"</dt>
<dd>
@@ -480,8 +520,6 @@
</dd>
</dl>
- <div class="idl" title="MIDIInput implements MIDIPort"></div>
- <div class="idl" title="MIDIOutput implements MIDIPort"></div>
<dl title="[NoInterfaceObject]
interface MIDIPort : EventTarget"
class="idl">
@@ -540,21 +578,25 @@
</dd>
</dl>
- <div class="note">
- <p>
- The <code><a>disconnect</a></code> and
- <code><a>connect</a></code> events may not be applicable to all
- MIDI ports or OS APIs. For example, an actual MIDI port does not
- support the notion of disconnect and connect while a USB MIDI Device
- may be plugged in or out on the fly. Therefore the semantics here is
- SHOULD, rather than MUST.
- </p>
- </div>
-
<section>
<h3><a>MIDIInput</a> Interface</h3>
+ <div class="idl" title="MIDIInput implements MIDIPort"></div>
- <p id="event-midiinput-message">
+ <dl title="[NoInterfaceObject]
+ interface MIDIInput implements EventTarget"
+ class="idl">
+ <dt class="no-docs">[TreatNonCallableAsNull] attribute
+ Function? onmessage</dt>
+ <dd>
+ <p>
+ This event handler, of type <code><a href=
+ "#event-midiinput-message">message</a></code>,
+ MUST be supported by all objects implementing
+ <code><a>MIDIInput</a></code> interface.
+ </p>
+ </dd>
+ </dl>
+ <p id="event-midiinput-message">
Whenever the MIDI port corresponding the
<code><a>MIDIInput</a></code> sends a MIDI message, the UA MUST
run the following steps:
@@ -592,31 +634,20 @@
</li>
</ol>
- <dl title="[NoInterfaceObject]
- interface MIDIInput implements EventTarget"
- class="idl">
- <dt class="no-docs">[TreatNonCallableAsNull] attribute
- Function? onmessage</dt>
- <dd>
- <p>
- This event handler, of type <code><a href=
- "#event-midiinput-message">message</a></code>,
- MUST be supported by all objects implementing
- <code><a>MIDIInput</a></code> interface.
- </p>
- </dd>
- </dl>
</section>
<section>
<h3><a>MIDIOutput</a> Interface</h3>
+
+ <div class="idl" title="MIDIOutput implements MIDIPort"></div>
+
<dl title="[NoInterfaceObject]
interface MIDIOutput"
class="idl">
<dt>void sendMIDIMessage(MIDIMessage message)</dt>
<dd>
<p>
- Enqueues the message to be send to the corresponding MIDI port.
+ Enqueues the message to be sent to the corresponding MIDI port.
</p>
</dd>
<dt>void sendMessage(short status, short... data)</dt>