lichen-community-systems / youme

A library of Infusion components that work with the WebMIDI API.

YouMe

YouMe is a library that makes it easier to work with the WebMIDI API within the Fluid Infusion ecosystem.

Using YouMe in Your Code

YouMe is published to npm and can be installed in your project using a command like:

npm install --save youme

Requirements

The components in this package require:

1. The dependencies of this package, which you can install using a command like npm install.
2. A compatible browser. At time of writing, this includes:
   • Chromium and derivatives, like Chrome, Edge, and Opera.
   • Firefox 108 or higher.

Try It!

This package provides a few demonstrations that you can try out in your browser. Once you have installed all dependencies (see above), open the demonstration page in a compatible browser.

Tests

This package includes a test suite. Once you have installed dependencies, you can run the tests using the command npm test. You must have a compatible browser (see above) to run the tests. By default, the tests run against instrumented code in order to verify test code coverage. They also run in continuous integration mode, launching all supported browsers in turn and exiting when the tests have finished running.

If you want to debug tests in your browser, you can launch Testem without instrumentation and in "development mode" using a command like:

DISABLE_INSTRUMENTATION=true node node_modules/.bin/testem --file tests/testem.js

Follow the onscreen instructions and connect your browser to the URL provided by Testem.

If you want to run the tests without Testem, you will need to host the code in a test server to avoid browser sandbox issues. As an example, if you have python3 installed, you can:

• Host the content by running a command like python3 http.server from the root of the repository
• Open tests/all-tests.html in a compatible browser.

Learn More

To learn more about using this package in your own code, check out the documentation, which includes API documentation and usage examples.

Contributing Your Own Changes

This package is an open source project that welcomes contributions. To find out more, read our contribution guidelines.

Migrating from flocking-midi (and earlier versions of Flocking )

This package is based on and extends the original flocking-midi project, and was written in conversation with that package's author. flocking-midi was itself originally part of Flocking. Users coming from either of those environments will see some familiar grades, but there are a few key differences in this package that are worth noting.

First, this package is written to take advantage of features new to Infusion 4.x. As such, it cannot be run with earlier versions of Infusion.

Second, this package no longer depends on Flocking for its UI components. If you are building your front end using Infusion, this package provides sample UI components, see the UI component documentation for more information.

The new portConnector grades provide a UI-agnostic means of connecting to and relaying messages to/from MIDI ports. If you are using something other than Infusion to build your front-end interface, or are working without a user interface, you should build your work on top of these grades.

youme's Issues

Add ability to read/write "standard" MIDI files.

This ticket covers adding support for reading and writing "standard" MIDI files. This would support:

1. Capturing, reusing, and transforming performed MIDI messages.
2. Saving things like system exclusive messages required to configure devices to external files and loading them in code.
3. Accessing the wealth of historical examples of music saved in this format.
4. Generating synthetic tracks for use with external devices and programs (for example, "Black MIDI" compositions played using Synthesia).

This work would be added in a separate part of the youme namespace (for example youme.smf) and would be "opt in", i.e. authors would have to reference that file to add support in their work. There would be a separate page of documentation linked from the main docs.

My thinking is that the initial implementation probably won't include the later extensions to the standard such as karaoke files, but the work here should be tested with those files if possible to confirm that they load what they can without error.

I did review "prior art", including jzz-midi-smf, smfplayer, picoaudio.js. Each of these provides a parser coupled with a player, and redefines many of the concepts we already have for dealing with MIDI messages. It seemed more appropriate to extend what we have, i.e. we need new mechanisms for reading/writing things like headers and tracks, but can reuse the functions we have to read/write MIDI messages.

As part of that research, I found the test-midi-files package provided by JazzSoft under an MIT License. Although that package provides a player as well, the player is not required to use the test files, and the test files cover many things I would like to verify support for.

Add `es6` as a linting environment.

In past work, when we wanted to use es6 constructors like Map, Promise, and UInt8Array, we let ESLint know they were globals, and kept our environment as browser. In reviewing the supported environments, it seems like es6 adds the globals we want without changing any parser conventions or requiring us to use newer idioms (like let).

This ticket covers the small changes required to add es6 as an additional development environment. I plan for this to be reviewed in concert with the work on #5.

Switch to npm-audit-resolver for security checks.

CI wouldn't run until the initial merge, now that it does I can see that npm run audit results in an error.

This ticket covers converting to use npm-audit-resolver, which I've found helpful in other work. It lets you ignore vulnerabilities temporarily or permanently, but still shows you when new vulnerabilities affect your project.

I'll review the vulnerabilities, create an initial excludes file, and add details about the tool to the contributor docs.

Initial implementation.

This ticket covers migrating the existing code from flocking-midi and updating it to:

1. Work with Infusion 4.x.
2. Provide a UI-independent port connector.
3. Provide updated UI components to replace those provided by Flocking and flocking-midi.
4. Add tests.

Add support for quarter frame MTC.

Previously, we have not supported quarter frame MTC messages. We have discussed adding support as part of #7, if feasible.