README not clear enough for absolute newbies.

[victorwss]

I am an absolute newbie, I just knew about this project from Google a couple of hours ago.

The README contains this:

API basics

See also the API reference for both elements: midi-player, midi-visualizer.

src and noteSequence

Both midi-player and midi-visualizer support two different ways of specifying the input file:

• By setting the src attribute to a MIDI file URL, e.g.:

  <midi-player src="twinkle-twinkle.mid"></midi-player>

  player.src = "twinkle-twinkle.mid";

• By assigning a Magenta NoteSequence to the noteSequence property, e.g.:

  player.noteSequence = TWINKLE_TWINKLE;

The text don't make it clear enough about how to get an instance of player from Magenta nor how to load TWINKLE_TWINKLE out from a MID file. The linked page of Magenta's documentation loads TWINKLE_TWINKLE out of some hardcoded notes encoded in JavaScript, being silent about the simple and obvious case of how to read them from some MID file, they only provide a link to the documentation of some module describing its methods, but not how to get an instance of that stuff.

Reading Magenta's documentation, to make an instance of player, you should call player = new mm.Player(); after adding Magenta's script into the page, but this still don't solve how to get TWINKLE_TWINKLE from a MID file. Digging down on source code of both Magenta and html-midi-player, it seems that mm.urlToNoteSequence(someUrl) makes some NodeSequence. But the best that I could get so far was a Uncaught ReferenceError: mm is not defined error.

Could you please detail how to get an instance of player and how to load a Magenta's NodeSequence out of a MID file without requiring people to dig it deep from the guts of Magenta's documentation or source code, since this is part of the very basic usage of the html-midi-player? Remember, I am an absolute newbie, but I am surely not the only one, and the README explaining how to start with the basic usage should be written in a way that is clear enough even for absolute newbies. I already spent several hours digging down the documentation and the source code of both projects for something that should be obvious for anyone who is not an absolute newbie like me.

Further, the page also features this:

• Website [source] with MIDI file upload

The source link goes to an old branch of the project that is very outdated. Also, the source is not the direct plain HTML output of the page, being generated below some layers of preprocessing which makes it harder to understand what is going on. Further, the JS in the produced output is minified, also making it hard to tell what is going on. Since this resource is intended to be an example, preprocessing and minifying just makes it harder to be understood.

[cifkao]

Hi @victorwss, thanks for your input!

The text don't make it clear enough about how to get an instance of player

player simply refers to an instance to the custom midi-player element (not an instance of a Magenta.js Player!), and I assume anyone writing javascript knows the methods to get a reference to an element (namely document.getElementById(), document.querySelector() or document.querySelectorAll(), for example). But since this turns out to be a frequent question, I think I will add a note about this to the readme.

Digging down on source code of both Magenta and html-midi-player, it seems that mm.urlToNoteSequence(someUrl) makes some NodeSequence. But the best that I could get so far was a Uncaught ReferenceError: mm is not defined error.

Indeed urlToNoteSequence() is the right function to use. However, the way to get access to the Magenta module depends on how you imported it. If you use the bundle from jsDelivr, then you will get the only the core module from @magenta/music, so then the correct way to use it would be core.urlToNoteSequence(someUrl). However you could for example import it like import {urlToNoteSequence} from '@magenta/music'; (e.g. if you are using a build tool like webpack or Parcel) and then use it simply as urlToNoteSequence().

Further, the page also features this:

Website [source] with MIDI file upload

The source link goes to an old branch of the project that is very outdated. Also, the source is not the direct plain HTML output of the page, being generated below some layers of preprocessing which makes it harder to understand what is going on. Further, the JS in the produced output is minified, also making it hard to tell what is going on. Since this resource is intended to be an example, preprocessing and minifying just makes it harder to be understood.

It's not an old, outdated branch, it's simply a branch which contains just the website and has no commits in common with master (I admit it would be better to create a separate repo for it). This website is definitely not meant as an example for newbies, it's meant to show how you can make an app using the kind of build process that is common in JS development today; moreover this is combined with Jekyll, making the resulting process quite complicated. I think I'll add a readme to clarify this.

[cifkao]

I have updated the README and added one for the website source code as well. I hope this clarifies things.

Also, @victorwss, even though the output JS is minified, IIRC this should only happen for the final build (not for the dev build), and even then, a source map is provided, so you should still be able to view the original code in your browser's dev tools.