html-midi-player

The simplest way to implement the player is to add the <midi-player> and <midi-visualizer> elements to your HTML. You can bind them using the visualizer attribute on the player, which accepts a CSS selector.

<midi-player
  src="https://magenta.github.io/magenta-js/music/demos/melody.mid"
  sound-font
  visualizer="#myVisualizer">
</midi-player>

<midi-visualizer type="piano-roll" id="myVisualizer"></midi-visualizer>

You can install the package using npm or yarn:

npm install --save html-midi-player
# or
yarn add html-midi-player

After installation, you can:

1. Import it as an ES Module: import 'html-midi-player';
2. Or, add the bundle directly from node_modules/html-midi-player/dist/midi-player.min.js. If doing this, you must also include tone and @magenta/music dependencies before the player script.

To use the player in a simple HTML page, include the following script tag. This bundle combines tone, @magenta/music, and html-midi-player into a single request via jsDelivr.

<script src="https://cdn.jsdelivr.net/combine/npm/tone@14.7.58,npm/@magenta/music@1.23.1/es6/core.js,npm/html-midi-player@1.5.0"></script>

The <midi-player> can automatically drive <midi-visualizer> elements using the visualizer attribute. This attribute accepts a CSS selector that matches the visualizer elements on your page.

When bound, the player will automatically update the visualizer's noteSequence and trigger redraws when notes are played.

<midi-player src="song.mid" visualizer="#my-visualizer"></midi-player>
<midi-visualizer id="my-visualizer"></midi-visualizer>

The <midi-player> element is a Web Component used to play MIDI files with a built-in UI. It can be configured via properties and attributes, and it supports binding to visualizers.

Key Properties and Attributes

• src: URL to a MIDI file.
• soundFont: URL to a Magenta SoundFont.
  • Use an empty string "" to use the default SoundFont.
  • Use null to use a simple oscillator synth.
• noteSequence: A Magenta INoteSequence object for direct content loading.
• loop: Boolean attribute. If present, the player loops playback.
• visualizer: A CSS selector string that matches midi-visualizer elements to bind to this player.

Basic Usage

<midi-player src="path/to/your/file.mid"></midi-player>

The package automatically registers two Web Components with the browser's customElements registry. You can use these directly in your HTML markup without manual instantiation.

• <midi-player>: The main player component.
• <midi-visualizer>: The visualizer component.

<midi-player></midi-player>
<midi-visualizer></midi-visualizer>

If your MIDI file is not loading:

1. Check the URL: Ensure you are providing a valid HTTP(S) URL. Use absolute URLs (https://...) or relative URLs that are valid for your hosted environment.
2. Avoid Local Files: Browsers often block requests to local files (file://). Use a local HTTP server to host your MIDI files for testing.
3. Check for 'Bad MIDI file' error: If you see the error "Bad MIDI file. Expected 'MHdr'", the file is either invalid or the server is returning an error page (like a 404) instead of the MIDI file. Check the Network tab in Browser Developer Tools to verify the file is being served correctly.

By default, the player uses a simple oscillator synth. To use a SoundFont, add the sound-font attribute or property. You can provide a specific URL to a SoundFont.

HTML:

<midi-player sound-font="https://storage.googleapis.com/magentadata/js/soundfonts/sgm_plus"></midi-player>

JavaScript:

player.soundFont = 'https://storage.googleapis.com/magentadata/js/soundfonts/sgm_plus'; // specific URL
player.soundFont = '';    // default SoundFont
player.soundFont = null;  // no SoundFont

The <midi-visualizer> supports three types via the type attribute: piano-roll, waterfall, and staff.

Visualizer settings are configured via the config property in JavaScript. These settings follow the Magenta.js VisualizerConfig interface.

visualizer.config = {
  noteHeight: 4,
  pixelsPerTimeStep: 60,
  minPitch: 30
};

To make the MIDI playback loop continuously, use the loop attribute or property.

HTML:

<midi-player loop></midi-player>

JavaScript:

player.loop = true;

Both <midi-player> and <midi-visualizer> support two methods for input:

1. src: A URL to a MIDI file.

   • HTML: <midi-player src="file.mid"></midi-player>
   • JS: player.src = "file.mid";

2. noteSequence: A Magenta NoteSequence object.

   • JS: player.noteSequence = myNoteSequence;

To convert a URL to a NoteSequence, use Magenta's urlToNoteSequence() function.

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

// Using noteSequence
player.noteSequence = TWINKLE_TWINKLE;

A player can be bound to one or more visualizers. This can be done via the visualizer attribute (using a CSS selector) or the addVisualizer method.

HTML (Multiple visualizers via selector):

<midi-player visualizer="#myVisualizer, #myOtherVisualizer"></midi-player>

JavaScript:

player.addVisualizer(document.getElementById('myVisualizer'));
player.addVisualizer(document.getElementById('myOtherVisualizer'));

Note: A visualizer only updates while the player is playing, so a single visualizer can be shared across multiple players.