You might want to break this down a bit after a first pass.

(In reply to comment #1)
> You might want to break this down a bit after a first pass.

Actually, since the API is so simple, I'll probably push in a bunch of examples in one go.

One question (email response to group is fine) - preferences for inline examples in each section, or separate example section?  I'm leaning slightly to the latter.

(In reply to comment #2)
> (In reply to comment #1)
> > You might want to break this down a bit after a first pass.
> 
> Actually, since the API is so simple, I'll probably push in a bunch of
> examples in one go.
> 
> One question (email response to group is fine) - preferences for inline
> examples in each section, or separate example section?  I'm leaning slightly
> to the latter.

Due to the simplicity of the API, I agree that the latter is probably better.

Added a set of five basic examples that cover the entire API.  Other examples should be separately bugged.  https://dvcs.w3.org/hg/audio/rev/00b58322aa11.

some remarks on the code examples:

9.1
> function success( midiAccess )

should be named

> function onMIDISuccess( midiAccess )


9.4
> output.send( [0x90, 60, 0x00], window.performance.now() + 1000.0 ); 
> // note off, middle C, zero velocity, timestamp = now + 1000ms.

This is actually a Note On message with 0 velocity, which is equivalent to a Note Off message with 64 velocity (if I recall correctly). It's probably easier to understand for MIDI newbies to use the actual Note Off message:

> output.send( [0x80, 60, 0x00], window.performance.now() + 1000.0 ); 
> // note off, middle C, zero velocity, timestamp = now + 1000ms.


9.5
same as 9.1

https://dvcs.w3.org/hg/audio/rev/d61cc0adee7e and https://dvcs.w3.org/hg/audio/rev/39efc30b003f contain these changes:

(In reply to comment #5)
> should be named
> > function onMIDISuccess( midiAccess )

Done.

> This is actually a Note On message with 0 velocity, which is equivalent to a
> Note Off message with 64 velocity (if I recall correctly). It's probably
> easier to understand for MIDI newbies to use the actual Note Off message:

Done.

> 9.5
> same as 9.1

Done.

From James' email:
>9.2
>idx and i are the same variable. Change idx to i.

Done.

>9.3
>indexOfPort and index are the same variable. Change index to indexOfPort.

Done.

>I  think I'd also rename "event" to "msg" in onMIDIMessage(). Might give newbies a marginally easier time.

NOT done.  The parameter to the onmessage handler is an Event - I want that to be clear.

>9.4
>I think that a) the text should include the information that both messages are being sent on channel 0, and b) it might be helpful if you said a bit more about the omitted timestamp.

Done and done.

>As in 9.3, change index to indexOfPort.

Done.

>Can we have a sysex example in the official docs please?

Made it clearer that the echo example handles sysex.  Sysex is not a separate thing in the Web MIDI API - it's just another MIDIEvent, with more bytes.  (And, obviously, a different status code.)

(In reply to comment #6)

thanks for the super fast changes!

> https://dvcs.w3.org/hg/audio/rev/d61cc0adee7e

includes the following addition:

"This example sends a middle C note on message immediately on MIDI channel 0 [...]"

I'm sure you are aware of this -- MIDI channels are encoded as the lower 4 bits of the status byte from 0 to 15. But when referring to them, by convention, they are numbered 1 to 16. Therefore, I think it's better to change the text to say "MIDI channel 1".

Now personally, I don't like this "convention", but with MIDI being around for 30 years, it would bring more confusion than help trying to "fix" it now.

(In reply to comment #7)
> I'm sure you are aware of this -- MIDI channels are encoded as the lower 4
> bits of the status byte from 0 to 15. But when referring to them, by
> convention, they are numbered 1 to 16. Therefore, I think it's better to
> change the text to say "MIDI channel 1".
> 
> Now personally, I don't like this "convention", but with MIDI being around
> for 30 years, it would bring more confusion than help trying to "fix" it now.

Fair enough.  Fixed.

(In reply to comment #8)
> > Now personally, I don't like this "convention", but with MIDI being around
> > for 30 years, it would bring more confusion than help trying to "fix" it now.
> 
> Fair enough.  Fixed.

I assume that with this fix, we can close this issue. Other requests for examples can be made into their own issues.