VexFlow Documentation

If you need to compare two different local versions of VexFlow (for example, your own branch vs. a pull request branch), use this method:

1. Generate Images for Both: In each separate working copy, run grunt and then grunt generate:current.
2. Prepare for Comparison: You will now have two vexflow/build/images/current/ folders.
3. Compare: Open index.html in your local browser. Drag one current/ folder onto the left side of the compare tool and the other current/ folder onto the right side.

Tip: To avoid managing two current/ folders, you can rename one to reference/ and move it into the other working copy's vexflow/build/images/ directory. Then, drag the combined images/ folder onto the compare tool as described in the single working copy method.

EasyScore is a high-level API designed for quickly creating music notation. It uses a Factory to manage the renderer, score, and system.

To use it, ensure you have a container element (e.g., <div id="output"></div>) in your HTML. The Factory handles the connection between the renderer and the musical elements.

const { Factory, EasyScore, System } = Vex.Flow;

const vf = new Factory({
  renderer: { elementId: 'output', width: 500, height: 200 },
});

const score = vf.EasyScore();
const system = vf.System();

system
  .addStave({
    voices: [
      score.voice(score.notes('C#5/q, B4, A4, G#4', { stem: 'up' })),
      score.voice(score.notes('C#4/h, C#4', { stem: 'down' })),
    ],
  })
  .addClef('treble')
  .addTimeSignature('4/4');

vf.draw();

To use the Roboto Slab font (weight 500, Latin subset) in your project, include the following @font-face declaration in your CSS. This configuration uses Google Fonts' hosted WOFF2 and WOFF files.

/* latin */
@font-face {
  font-family: 'Roboto Slab';
  font-style: normal;
  font-weight: 500;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/robotoslab/v16/BngbUXZYTXPIvIBgJJSb6s3BzlRRfKOFbvjovoSmb2RjV9Ku1Q.woff2) format('woff2'),
    url(https://fonts.gstatic.com/s/robotoslab/v16/BngbUXZYTXPIvIBgJJSb6s3BzlRRfKOFbvjovoSmb2RlV9Su1cai.woff) format('woff');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC,
    U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}

To add a custom glyph to the project:

1. Add the glyph's outline to fonts/custom_glyphs.js.
2. Add a custom code (prefixed with vex) to config/valid_codes.json.
3. Run the custom glyph generation script.

$ node fontgen_custom.js ../../src/fonts/

To run demonstrations that use VexFlow with ES Modules, you must serve the files via a web server rather than opening them directly from the file system.

1. Navigate to the main vexflow/ folder in your terminal.
2. Start a local web server using npx http-server.
3. Access the ES module demo by visiting http://127.0.0.1:8080/demos/modules/module.html in your browser.

$ npx http-server

If you are using vexflow-core.js along with individual font bundles (e.g., vexflow-font-bravura.js, vexflow-font-petaluma.js, etc.), you must load the fonts before rendering. The Vex.Flow.setMusicFont(...) function is asynchronous in this configuration and returns a Promise.

IMPORTANT: The default font stack is empty, so you must call setMusicFont before rendering your score.

Via CDN

For web pages, you can include VexFlow using a <script> tag. It is recommended to specify a version number to ensure stability.

<script src="https://cdn.jsdelivr.net/npm/vexflow@4.2.2/build/cjs/vexflow.js"></script>
<script>
  // YOUR CODE GOES HERE
</script>

Via npm

If you are using a module bundler, install VexFlow using npm:

npm install vexflow

To create text metrics for a custom font (e.g., an .otf file):

1. Run fontgen_text.js with your font file and the desired output TypeScript filename.
2. Register the generated metrics using TextFormatter.registerInfo(...) to make them available for your module.

$ node fontgen_text.js MyFont.otf myfont_glyphs.ts

The worker/ directory contains examples demonstrating how to use web workers to render multiple scores simultaneously. To run these demos:

1. Navigate to the vexflow/ folder.
2. Start a web server using npx http-server.
3. Open your browser and navigate to http://127.0.0.1:8080/demos/worker/.