music21j

music21j tests run in a real browser using QUnit + Playwright, orchestrated via Vite. This allows tests to render SVG output and exercise audio-related APIs.

Headless Execution

To run the full test suite headlessly, use npm test. This starts a Vite development server and runs QUnit tests in headless Chromium.

Note: The first time you run tests, you must install the headless Chromium browser:

npx playwright install chromium

Running with an active Vite server

If you already have the Vite development server running, you can run tests using:

npm run test:qunit

You can also view tests and their output by navigating to http://localhost:5173/tests/ in your browser.

# Install headless browser (required once)
npx playwright install chromium

# Run full test suite headlessly
$ npm test

# Run tests if Vite server is already running
$ npm run test:qunit

By default, music21j attempts to fetch its own soundfonts. To use soundfonts from an external source (like a CDN) and avoid the default fetch, follow these steps:

1. Set window.m21conf = { loadSoundfont: false } before loading the music21j script.
2. Load the music21j script.
3. Set music21.common.urls.soundfontUrl to your desired URL.
4. Call music21.miditools.loadSoundfont(instrumentName, callback) to load the specific instrument.

<body
<script>
    window.m21conf = { loadSoundfont: false };
</script>
<script src="https://cdn.jsdelivr.net/npm/music21j/releases/music21.debug.js"></script>
<script>
    music21.common.urls.soundfontUrl =
        'https://cdn.jsdelivr.net/gh/gleitz/midi-js-soundfonts/FluidR3_GM/';
    music21.miditools.loadSoundfont('clarinet', i => {
        const tn = music21.tinyNotation.TinyNotation('4/4 c4 d e f g1');
        tn.instrument = i;
        tn.playStream();
    });
</script>
</body>

To use music21j directly in an HTML file without a build step, include the CSS and the debug JavaScript file from a CDN. Note that this example assumes a local Vite development server environment for the script execution context.

<!DOCTYPE html>
<html lang="en">                                                                                            
<head>                                                    
  <meta charset="utf-8">
  <title>music21 test</title>
  <link rel="stylesheet"                                                                                  
        href="https://cdn.jsdelivr.net/npm/music21j/releases/music21j.css">
  <script src="https://cdn.jsdelivr.net/npm/music21j/releases/music21.debug.js"></script>                 
</head>                                                                                                     
<body
  <script>                                                                                                
      const n = new music21.note.Note('F#');            
      const s = new music21.stream.Stream();                               
      s.append(n);
      s.appendNewDOM();                                                                                   
  </script>                                             
</body>
</html>

The following modules are exported by the music21j entrypoint. Use these to access specific musical logic, data structures, and utilities:

• articulations: Articulation markings
• audioRecording: Audio recording utilities
• audioSearch: Audio search capabilities
• bar: Bar/measure logic
• beam: Beam logic
• chord: Chord logic and structures
• chordTables: Chord lookup tables
• clef: Clef definitions
• converter: Data conversion utilities
• defaults: Library default settings
• derivation: Musical derivation logic
• derivation: Musical derivation logic
• duration: Duration logic
• dynamics: Dynamics markings
• editorial: Editorial/notation adjustments
• expressions: Musical expressions
• figuredBass: Figured bass logic
• fromPython: Logic for interacting with Python music21
• harmony: Harmonic analysis and structures
• instrument: Instrument definitions
• interval: Interval logic
• key: Key/tonality logic
• keyboard: Keyboard/input logic
• layout: Layout and positioning
• metadata: Metadata handling
• meter: Meter/time signature logic
• miditools: MIDI manipulation tools
• musicxml: MusicXML handling
• note: Note logic and structures
• parseLoader: Parsing and loading utilities
• pitch: Pitch logic
• renderOptions: Options for rendering
• roman: Roman numeral analysis
• scale: Scale logic
• sites: Site/location logic
• stream: Musical stream containers
• style: Styling and notation appearance
• svgs: SVG generation/handling
• tempo: Tempo logic
• tie: Tie logic
• tinyNotation: TinyNotation support
• vfShims: VexFlow shims
• vfShow: VexFlow showing utilities
• voiceLeading: Voice leading logic
• webmidi: WebMIDI integration
• exceptions21: Custom music21 error types
• base / prebase / common: Core foundational classes and utilities
• debug: Debugging utilities
• MIDI: MIDI interface (via midicube)
• Vex: VexFlow interface