{"id":13753917,"url":"https://github.com/cifkao/html-midi-player","last_synced_at":"2025-05-16T06:04:31.966Z","repository":{"id":44341576,"uuid":"288016885","full_name":"cifkao/html-midi-player","owner":"cifkao","description":"🎹 Play and display MIDI files on the web","archived":false,"fork":false,"pushed_at":"2024-05-23T16:30:06.000Z","size":642,"stargazers_count":747,"open_issues_count":19,"forks_count":75,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-16T06:04:10.347Z","etag":null,"topics":["audio-player","html","javascript","magenta-js","midi","midi-file","midi-player","music","music-player","player","typescript","web-component","web-components"],"latest_commit_sha":null,"homepage":"https://cifkao.github.io/html-midi-player/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cifkao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-16T20:10:40.000Z","updated_at":"2025-05-15T15:24:02.000Z","dependencies_parsed_at":"2023-11-28T09:25:42.128Z","dependency_job_id":"77c7b51f-9c39-445f-ad11-a6466006ecf5","html_url":"https://github.com/cifkao/html-midi-player","commit_stats":{"total_commits":116,"total_committers":2,"mean_commits":58.0,"dds":"0.14655172413793105","last_synced_commit":"73981e19925b891794cc89c69405ff914d0aa98a"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cifkao%2Fhtml-midi-player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cifkao%2Fhtml-midi-player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cifkao%2Fhtml-midi-player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cifkao%2Fhtml-midi-player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cifkao","download_url":"https://codeload.github.com/cifkao/html-midi-player/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478186,"owners_count":22077675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-player","html","javascript","magenta-js","midi","midi-file","midi-player","music","music-player","player","typescript","web-component","web-components"],"created_at":"2024-08-03T09:01:34.679Z","updated_at":"2025-05-16T06:04:31.948Z","avatar_url":"https://github.com/cifkao.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Packages","Real World","Music"],"sub_categories":["Libraries","Components","Programming"],"readme":"# html-midi-player\n\n[![npm package](https://badge.fury.io/js/html-midi-player.svg)](https://badge.fury.io/js/html-midi-player)\n[![npm package daily downloads](https://badgen.net/npm/dm/html-midi-player)](https://npmjs.com/package/html-midi-player)\n[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/html-midi-player/badge?style=rounded)](https://www.jsdelivr.com/package/npm/html-midi-player)\n[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/html-midi-player)\n\n[`\u003cmidi-player\u003e`](https://github.com/cifkao/html-midi-player/blob/master/doc/midi-player.md#midi-player)\nand [`\u003cmidi-visualizer\u003e`](https://github.com/cifkao/html-midi-player/blob/master/doc/midi-visualizer.md#midi-visualizer)\nHTML elements powered by [@magenta/music](https://github.com/magenta/magenta-js/tree/master/music/) (Magenta.js), fully stylable and scriptable.\n\nWorks in Jupyter notebooks, Colab, and Weights \u0026 Biases thanks to the [midi-player](https://github.com/drscotthawley/midi-player) Python package by [@drscotthawley](https://github.com/drscotthawley).\n\n* [Simple demo](https://codepen.io/cifkao/pen/WNwpLzL)\n* [Advanced demo](https://codepen.io/cifkao/pen/GRZxqZN)\n* [Website](https://cifkao.github.io/html-midi-player/) [[source](https://github.com/cifkao/html-midi-player/tree/www)] with MIDI file upload\n\nNotable websites that use `html-midi-player` include [abcnotation.com](https://abcnotation.com/), [Musical Nexus](https://musicalnexus.net/) and demo websites for music generation models: [piano infilling](https://jackyhsiung.github.io/piano-infilling-demo/), [stochastic positional encoding](https://cifkao.github.io/spe/).\n\nIf you use `html-midi-player` on your website, please consider linking back to [the repository](https://github.com/cifkao/html-midi-player/).\n\n## Getting started\n\n1. Add the necessary scripts to your page:\n\n   ```html\n   \u003cscript src=\"https://cdn.jsdelivr.net/combine/npm/tone@14.7.58,npm/@magenta/music@1.23.1/es6/core.js,npm/focus-visible@5,npm/html-midi-player@1.5.0\"\u003e\u003c/script\u003e\n   ```\n\n2. Add a player and a visualizer:\n\n   \u003c!---\n   ```\n   \u003ccustom-element-demo\u003e\n     \u003ctemplate\u003e\n       \u003cscript src=\"https://cdn.jsdelivr.net/combine/npm/tone@14.7.58,npm/@magenta/music@1.23.1/es6/core.js,npm/focus-visible@5,npm/html-midi-player@1.5.0\"\u003e\u003c/script\u003e\n       \u003cnext-code-block\u003e\u003c/next-code-block\u003e\n     \u003c/template\u003e\n   \u003c/custom-element-demo\u003e\n   ```\n   --\u003e\n   ```html\n   \u003cmidi-player\n     src=\"https://magenta.github.io/magenta-js/music/demos/melody.mid\"\n     sound-font visualizer=\"#myVisualizer\"\u003e\n   \u003c/midi-player\u003e\n   \u003cmidi-visualizer type=\"piano-roll\" id=\"myVisualizer\"\u003e\u003c/midi-visualizer\u003e\n   ```\n\nThat's it!\n\nBesides [jsDelivr](https://www.jsdelivr.com/package/npm/html-midi-player), the bundle is also available from [cdnjs](https://cdnjs.com/libraries/html-midi-player).\n\n### Installing from NPM\n\nYou can also add the package to your project from NPM, e.g. `npm install --save html-midi-player` or `yarn add html-midi-player`. Then you can either:\n- `import 'html-midi-player'` in your JavaScript code (as an ES Module), or\n- add the `node_modules/html-midi-player/dist/midi-player.min.js` bundle directly to your page, along with the dependencies (`node_modules/tone/build/Tone.js`, `node_modules/@magenta/music/es6/core.js`; note that these need to go *before* `html-midi-player`).\n\nIn both cases, you should also add the [`focus-visible` polyfill](https://github.com/WICG/focus-visible) to enable outlines on keyboard focus.\n\n## API basics\n\nThe basic features of `html-midi-player` are explained below. Wherever both HTML and JavaScript examples are given, they are equivalent. In the JavaScript examples, `player` and `visualizer` refer to the corresponding custom element objects, which can be obtained using standard DOM methods like `document.getElementById('#myPlayer')` or `document.querySelectorAll('midi-player')`, for example.\n\nSee also the API reference for both elements:\n[`midi-player`](https://github.com/cifkao/html-midi-player/blob/master/doc/midi-player.md#midi-player),\n[`midi-visualizer`](https://github.com/cifkao/html-midi-player/blob/master/doc/midi-visualizer.md#midi-visualizer).\n\n### `src` and `noteSequence`\nBoth `midi-player` and `midi-visualizer` support two different ways of specifying the input file:\n- By setting the `src` attribute to a MIDI file URL, e.g.:\n  ```html\n  \u003cmidi-player src=\"twinkle-twinkle.mid\"\u003e\u003c/midi-player\u003e\n  ```\n  ```javascript\n  player.src = \"twinkle-twinkle.mid\";\n  ```\n- By assigning a Magenta [`NoteSequence`](https://hello-magenta.glitch.me/#playing-a-notesequence) to the `noteSequence` property, e.g.:\n  ```javascript\n  player.noteSequence = TWINKLE_TWINKLE;\n  ```\n  To obtain a `NoteSequence`, you can use Magenta functions like [`urlToNoteSequence()`](https://magenta.github.io/magenta-js/music/modules/_core_.html#urltonotesequence) (see [FAQ](#how-do-i-create-and-manipulate-notesequences)).\n\n### SoundFonts\nBy default, the player will use a simple oscillator synth. To use a SoundFont, add the `sound-font` attribute:\n```html\n\u003cmidi-player sound-font\u003e\u003c/midi-player\u003e  \u003c!-- default SoundFont (same as below) --\u003e\n\u003cmidi-player sound-font=\"https://storage.googleapis.com/magentadata/js/soundfonts/sgm_plus\"\u003e\u003c/midi-player\u003e\n```\n```javascript\nplayer.soundFont = null;  // no SoundFont\nplayer.soundFont = '';    // default SoundFont (same as below)\nplayer.soundFont = 'https://storage.googleapis.com/magentadata/js/soundfonts/sgm_plus';\n```\nSee the [Magenta.js docs](https://magenta.github.io/magenta-js/music/index.html#soundfonts) for a list of available SoundFonts.\n\n### Looping\nTo make the player loop, use the `loop` attribute:\n```html\n\u003cmidi-player loop\u003e\u003c/midi-player\u003e\n```\n```javascript\nplayer.loop = true;\n```\n\n### Visualizer settings\nThe visualizer type is specified via the `type` attribute. Three visualizer types are supported: `piano-roll`, `waterfall` and `staff`.\n\nEach visualizer type has a set of settings that can be specified using the `config` attribute (only from JavaScript), e.g.:\n```javascript\nvisualizer.config = {\n  noteHeight: 4,\n  pixelsPerTimeStep: 60,\n  minPitch: 30\n};\n```\nThe settings are documented [in the Magenta.js docs](https://magenta.github.io/magenta-js/music/interfaces/_core_visualizer_.visualizerconfig.html).\n\n### Binding visualizers\nA player supports binding one or more visualizers to it using the `visualizer` attribute (a selector) or the `addVisualizer` method:\n```html\n\u003cmidi-player visualizer=\"#myVisualizer, #myOtherVisualizer\"\u003e\u003c/midi-player\u003e\n```\n```javascript\nplayer.addVisualizer(document.getElementById('myVisualizer'));\nplayer.addVisualizer(document.getElementById('myOtherVisualizer'));\n```\nThe visualizer only gets updated while the player is playing, which allows a single visualizer to be bound to multiple players.\n\n### Events\nThe player supports listening to different kinds of events using the `player.addEventListener()` method. See the [API reference](https://github.com/cifkao/html-midi-player/blob/master/doc/midi-player.md#events) for the available event types.\n\n## FAQ\nHere are some frequently asked questions about `html-midi-player`. Make sure to also check [discussions](https://github.com/cifkao/html-midi-player/discussions) and [issues](https://github.com/cifkao/html-midi-player/issues?q=is%3Aissue) to see if your question is answered there.\n\n### Why is my MIDI file not loading?\nPlease make sure that you provide a valid HTTP(S) URL, either absolute (beginning with `https://` or `http://`) or relative with respect to your HTML file (if hosted on the same server).\n\nLocal files most likely **will not work**, as most browsers block requests to local files. To test the MIDI player locally, you will need to start an HTTP server to host your MIDI file; see for example [this tutorial](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/set_up_a_local_testing_server#running_a_simple_local_http_server) for easy ways to do that.\n\nTo diagnose why the MIDI file is not loading, hover over the error icon to see the error; if the message is \"Bad MIDI file. Expected 'MHdr'\", it means either your file is not a valid MIDI file, or the server cannot find your file and is serving an error page instead. To see the file actually being served, open your browser's Developer Tools, go to the Network tab, reload the page, then find the name of your file in the list.\n\n### How can I use custom samples?\nThe player supports \"SoundFonts\" in a [special format](https://github.com/magenta/magenta-js/blob/d8a76682abb0979b985e4b80f6b68b5123b9f8d5/music/src/core/soundfont.ts#L381-L419) designed by Magenta. If you want to use a .sf2 file, it will not work out of the box, but it is possible to convert it with some effort. See [this discussion thread](https://github.com/cifkao/html-midi-player/discussions/43) and especially [this answer](https://github.com/cifkao/html-midi-player/discussions/43#discussioncomment-5439676), which proposes a conversion script.\n\n### How do I create and manipulate `NoteSequence`s?\nThe Magenta.js [`core`](https://magenta.github.io/magenta-js/music/modules/_core_.html) and [`core/sequences`](https://magenta.github.io/magenta-js/music/modules/_core_sequences_.html) modules define functions for loading and manipulating `NoteSequence`s. To load a MIDI file as a `NoteSequence`, use the `urlToNoteSequence()` function. Other useful functions are `clone()`, `trim()` and `concatenate()`. \n\nIf you are using the provided bundle as suggested [above](#getting-started), then the `core` module will be available simply as `core`, so you will be able to call e.g. `core.urlToNoteSequence()` or `core.sequences.clone()` from your code.\n\n### Can you implement feature X or fix issue Y?\nThis library is a relatively thin wrapper around [Magenta.js](https://github.com/magenta/magenta-js/), which provides all of the MIDI loading, synthesis and visualization functionality. This means it inherits most of its limitations. If you found an issue, try to check if Magenta.js is also affected, e.g. using [this](https://magenta.github.io/magenta-js/music/demos/player.html) or [this](https://magenta.github.io/magenta-js/music/demos/visualizer.html) demo (click *Load MIDI File* to upload your own file). If the issue is still there, then this is most likely a Magenta.js issue and cannot be fixed here (although a workaround may be possible). Otherwise, feel free to open an issue (or even better, a pull request) here, but please check for existing [issues](https://github.com/cifkao/html-midi-player/issues?q=is%3Aissue) and [discussions](https://github.com/cifkao/html-midi-player/discussions) first.\n\n## Limitations\n- Only one player can play at a time. Starting a player will stop any other player which is currently playing. ([#1](https://github.com/cifkao/html-midi-player/issues/1))\n  This can actually be a benefit in many cases.\n- Playback position only gets updated on note onsets. This may cause the player to appear stuck.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcifkao%2Fhtml-midi-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcifkao%2Fhtml-midi-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcifkao%2Fhtml-midi-player/lists"}