Fonts

[ronyeh]

Current Info

Please merge these sub PRs next:

• Fonts: CONSTANTS & TEXT_FONT #1210
• Fonts: DEMOS #1216
• ...more font related sub PRs to come...

Already Merged:

• Rename vexFlowCanvasContext to context2D. #1201
• Font Tools #1202
• Improve build process #1205
• Minor changes #1206
• Run prettier / eslint on the font data files, to improve consistency and editability of the files. #1212

---

Original Post

This is the final improvement that I'd like to get merged into the 4.0 release.

The high level goal is to consolidate the way we handle text fonts (e.g., Arial, Times, sans-serif), and follow CSS conventions wherever possible.

Before

• Inconsistent handling of text fonts. Each class had its own font property. setFont() was declared in 11 classes with 3 different method signatures. 1 class allowed direct access to the font property.

After

• setFont() is implemented in 4 classes: Element, ChordSymbol (overrides Element), CanvasContext, SVGContext.
• All setFont() methods now have identical method signature.

Before

• protected font: FontInfo; was declared 16 times. 10 of those classes did not provide a setFont() accessor.
• The default text font was set in multiple ways.

After

• Moved the declaration up to the Element class. Now it is declared once: protected font?: Required<FontInfo>;
• Each subclass of Element declares its own static TEXT_FONT property, along the lines of:

  static TEXT_FONT: Required<FontInfo> = {
    family: 'Arial',
    size: 10,
    weight: 'normal',
    style: 'normal',
  };

• In the constructor, we call this.setFont(this.getDefaultFont());.

Before

• In SVGContext, the weight parameter handled both bold and italic. In CSS, italic is specified by font-style instead of font-weight.

After

• Support weight and style as separate arguments (both default to 'normal', like in CSS).
• Robust support for setting the context.font to a CSS font string (e.g., 'italic bold 1.5em Arial, sans-serif'). Make use of a hidden <span> element to parse arbitrary CSS font strings.

Before

• Possible naming confusion for developers new to VexFlow. Element has a getFontStack() method, but those fonts are not for rendering text.

After

• Improve naming to more clearly separate music fonts (Bravura, Petaluma, Gonville) from text fonts (Arial, Times New Roman, Roboto Slab).
• Element now has setMusicFontStack() / getMusicFontStack() vs setFont() / getFont().
• DEFAULT_FONT_STACK has been renamed to MUSIC_FONT_STACK. No need for the DEFAULT_ prefix.

Coming soon

• More tests, tests, tests.
• List breaking changes in the CHANGELOG.
• Review visual changes, which mostly come from changes to the default sans-serif font. I added Helvetica Neue to the sans-serif text font stack, which should only affect macOS / iOS. Designers seem to prefer this font for macOS over Arial. Edit: I am abandoning Helvetica Neue for now. It looks too thin in the PNG visual tests. Will revisit for 4.1.

static SANS_SERIF: string = 'Helvetica Neue, Arial, sans-serif';
static SERIF: string = 'Times New Roman, Times, serif';

## Future Work
- There is a TextFont class that is for using custom fonts loaded with @font-face. We need to make it clearer how to integrate web fonts into VexFlow. Additionally, the test cases that use TextFont on a CanvasContext are buggy (e.g., ChordSymbol). This is because the web font needs to be fully loaded before we draw to the canvas.

EDIT: After a discussion below with Aaron, I ended up revamping the TextFont class by 1) moving generic Font methods into the Font class and 2) moving the formatting code into a new TextFormatter class.

[0xfe]

Thanks Ron -- these changes are great. Also very breaking. Adding a comment to the 4.0 issue about prototyping the API changes with VexTab.

[0xfe]

This would need updates to the Wiki too, I think.

[ronyeh]

Yes, I will make sure to update the wiki.

Are you okay with this change though?

My reasoning is that many classes have properties that include the word "font". But it is not clear whether the font is for music engraving purposes, or for text display purposes.

My initial idea was to have Element have two properties: musicFont and textFont.

  /** The font used to render musical glyphs (e.g., treble clef).*/
  protected musicFont!: Font;

  /** Some elements include text. You can customize the font family, size, weight, and style. */
  protected textFont?: Required<FontInfo>;

However, there is a descendant of Element that has its own .textFont property! :-( That class is ChordSymbol.

Perhaps the TextFont class should be renamed (to TextFontMetrics, or TextFontRegistry)? @AaronDavidNewman

Currently in this PR, the Element class has a .musicFont and a .font property, where .font is assumed to be for text purposes.

This is not bad, because CanvasContext and SVGContext also have a .font accessor which is for text rendering purposes, to adhere to the CanvasRenderingContext2D API. But perhaps it would be most clear to rename it to textFont, and then have ChordSymbol rename its member to textFontMetrics...

To further improve the naming, I went from DEFAULT_FONT_STACK to DEFAULT_MUSIC_FONT_STACK!

I then realized there are only three properties starting with DEFAULT_, even though there are all sorts of defaults all over VexFlow. So I figured we could drop the DEFAULT_ prefix for those three (all related to music fonts).

The breaking changes will be added to the CHANGELOG.

[0xfe]

@AaronDavidNewman to take a look too please

[AaronDavidNewman]

I'm glad you're taking this on. I have been too busy at work to react, but I feel like TextFont was getting lost in this refactoring. I will set aside some time to look at this over the weekend.

the test cases that use TextFont on a CanvasContext are buggy (e.g., ChordSymbol). This is because the web font needs to be fully loaded before we draw to the canvas.

Yeah, that's a tough one. For lazy-loaded fonts there is no way to know exactly when the font is loaded. I think for rendering on canvas, it may require a different approach. I'll check that also.

The other issue is with font metrics. The TextFont class is really about metrics, and using them to format your text. It is independent of the actual loading of fonts. We should be able to provide metrics for built-in fonts and use TextFont in place of the draw-and-erase method currently used in rendering context (if that is still used). It is more performant, and more reliable because web fonts may not have loaded when the measurement is made. For large blocks of text, it may give different results due to kerning. Also, most fonts have pretty similar width/height for the same glyphs at the same size/weight, so even if we can't find metrics for the exact font, we should be able to do pretty well with our fallback font metrics.

[ronyeh]

Thanks for chiming in, Aaron. First, I want to clarify that there are two topics at hand:
A) how we handle fonts for elements that include text. Setting the .font property with things like 'bold 10pt Arial, sans-serif'.
B) the TextFont class that you contributed 11 months ago.

When I first started this PR, I was mostly concerned about topic A (fonts for text). Many elements had their own individual setFont() method and internal .font property. I wanted to unify them all and adhere to the CSS convention as much as possible. I think I mostly succeeded.

However, at some point I dug into the TextFont class. At first I had no idea what it was for. :-) Mostly, I was just annoyed that ChordSymbol had both a .font property and also a .textFont property.

I had wanted to clearly distinguish "fonts for text" vs. "fonts for music engraving" and my plan was to name the properties .textFont and .musicFont. That plan was going great until I ran into ChordSymbol, where I would have two .textFont properties, haha.

So anyways, as the PR developed I slowly moved some of my font handling methods into the TextFont class. Perhaps I was attempting to unify topic A (fonts for text) and topic B (TextFont class). Hopefully they can be unified somewhat, because I noticed multiple classes (including SVGContext and TextFont) had different ways to determine whether a font-weight was 'bold' or a font-style was 'italic', or duplicated ways to convert point units to pixel units.

It'd be nice if the TextFont class was ultimately the one stop shop for all things related to measuring and laying out fonts. I'm happy to incorporate your feedback into this PR.

the test cases that use TextFont on a CanvasContext are buggy (e.g., ChordSymbol). This is because the web font needs to be fully loaded before we draw to the canvas.

Yeah, that's a tough one. For lazy-loaded fonts there is no way to know exactly when the font is loaded. I think for rendering on canvas, it may require a different approach. I'll check that also.

From stackoverflow, I found a suggested approach for loading web fonts:

const myFont = new FontFace('My Font', 'url(https://myfont.woff2)');
myFont.load().then((font) => {
  document.fonts.add(font);
  console.log('Font loaded');
});

See: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/font#loading_fonts_with_the_css_font_loading_api

I can try this to see if it fixes the CanvasContext test case!

If it does, perhaps we need to include this into VexFlow as the official way to load a web font before rendering the stave. Right now, on the flow.html test page, Roboto Slab is included in the head, while PetalumaScript is included from the releases/ folder. It looks like Roboto Slab isn't picked up by the Canvas tests due to the async font loading.

@0xfe Perhaps we can upload PetalumaScript to the unpkg cdn? I assume the font license allows us to host the woff file on a server of our choice? Perhaps we need to make a npm package called "vexflow-fonts" so that we aren't linking into a subfolder of the vexflow npm package (e.g., https://unpkg.com/[email protected]/releases/fonts/petaluma-script.woff)

Summary

• This PR covers two slightly different but overlapping topics (fonts for text elements vs. TextFont).
• This PR mostly deals with simplifying how we handle fonts for text elements.
• It'd be nice to unify the approach more, in a future PR.

---

Addendum / Further Discussion on TextFont

I am still not completely sure I understand TextFont. I know that it is used by ChordSymbol and briefly in Annotation.

My question (for both @AaronDavidNewman and @0xfe):

If we can ensure via the FontFace API that the web font is loaded before we start rendering the VexFlow score.... can we just rely on the browser's font rendering engine to lay out the text symbols properly?

It seems quite heavy weight to have to generate a whole textmetrics file for any web font that a developer would like to include.

I suppose ChordSymbol has a bunch of things going on. There are the letters like A E V 1, glyphs like ° that are pulled from Bravura/Petaluma, and then there's a custom line that we draw for the slash.

[ronyeh]

With the FontFace API, we are now able to load custom web fonts (woff2 / woff) and have them available for CanvasContext.

Here's the approach that I use in flow.html:

// Load web fonts before running the tests.
const host = 'https://unpkg.com/[email protected]/';
const srcURLs = (path) => `url(${host}${path}2) format('woff2'), url(${host}${path}) format('woff')`;
const robotoFont = new FontFace('Roboto Slab', srcURLs('robotoslab/RobotoSlab-Medium_2.001.woff'));
const petalumaFont = new FontFace('PetalumaScript', srcURLs('petaluma/PetalumaScript_1.10.woff'));

loadVexFlow()
  .then(() => robotoFont.load())
  .then(() => petalumaFont.load())
  .then(() => {
    document.fonts.add(robotoFont);
    document.fonts.add(petalumaFont);
  })
  // Load qunit.js as late as possible to avoid a race condition
  // where the QUnit module drop down box doesn't appear if
  // Vex.Flow.Test.run() happens too late,
  .then(() => loadScript('support/qunit.js'))
  .then(() => {
    // Show only failed tests.
    QUnit.config.hidepassed = true;
    QUnit.config.noglobals = true;
    Vex.Flow.Test.run();
  });

The buggy test case is fixed:

To make this work, I uploaded the open source fonts onto unpkg (via npm publish vexflow-fonts): https://unpkg.com/browse/[email protected]/

Our web fonts can now be accessed directly from CDN, e.g.: https://unpkg.com/[email protected]/petaluma/PetalumaScript_1.10.woff2

The vexflow-fonts npm package lives inside the vexflow repo, at: vexflow/tools/woff/.

Post 4.0 release, we could bake this font loading method into VexFlow. It can load Roboto Slab and PetalumaScript by default. The developer could also provide a list of font names and *.woff URLs to load, and VexFlow will guarantee they are loaded before we render to the CanvasContext.

[AaronDavidNewman]

This PR has a lot of prose in it :)

Rather than add to it, I feel like we should create an issue for discussion. And this can be one of several font-reform PRs. There are a lot of ideas in here, some good and others I think need some more discussion.

I will add that loading vs. formatting fonts are mostly unrelated. I have only been concerned with the formatting, and avoided the loading issues for the most part (and I think you are starting to understand why). But maybe it's time to take that on.

What do you think?

[ronyeh]

Sorry for the essays. My goal is to explain the design decisions to you and Mohit so you don't think I'm just changing code randomly.

I'm happy to assist with your code review, if you have any questions.

If you can identify smaller PRs that can be cleanly broken off, let me know and I'll accommodate. I understand smaller bites are easier to review and get accepted.

[ronyeh]

If you'd like to discuss the larger topic of fonts, feel free to start a topic on the GitHub discussions tab. I'll be happy to join in.

[AaronDavidNewman]

Are we dropping support for web fonts?

Maybe that's OK if we only want to support statically-loaded fonts, but that is why the canvas tests were 'buggy'. They were intended for display fonts, and so I only ran them on svg. Someone else added the canvas tests later. If you still want to support the webfonts, we could have one test svg only, and one test for canvas + svg that uses the statically loaded font.

I have a couple of questions about the web loading API:

1. does it support local loading of fonts (e.g. ../../myFont.otf) if you are running locally? The spec is a little unclear on that.
2. If a font is referenced in css, does it use the cached font or reload it? Or is it browser dependent? The spec has this, not quite sure what it means (emphasis mine):

The load() method of FontFace forces a url-based font face to request its font data and load

3. do we really need to include all those open-source LICENSE files in vex? We haven't up 'til now.

[AaronDavidNewman]

One more question and one comment/suggestion:

However, there is a descendant of Element that has its own .textFont property! :-( That class is ChordSymbol.

But textFont is an actual instance of TextFont class. Couldn't you still make textFont a property of Element? I don't see the conflict.

Perhaps the TextFont class should be renamed (to TextFontMetrics, or TextFontRegistry)?

How about TextFontFormatter? There is already a TextFontMetrics interface, and a TextFontRegistry. TextFontMetrics seems pretty consistent to how metrics are used elsewhere. TextFontRegistry could become 'TextFontMetricsRegistry'. Since it is really the metrics you are registering.

I don't think you should worry about TextFont... name changes being breaking. Other than me, I doubt if may people use it or even know about it. DEFAULT_FONT_STACK is a much more breaking change (not saying it shouldn't be done).

[ronyeh]

Are we dropping support for web fonts?

?? I think there's a miscommunication here, and we probably need to get synced.

NO we are not dropping support for anything.

The JS FontFace API and the css @font-face API should be equivalent.

https://developer.mozilla.org/en-US/docs/Web/API/FontFace
https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face

The only difference is in browser support. FontFace seems to be a bit newer.

(Note: developer == someone who uses VexFlow in his/her own project vs. maintainer == Mohit, you, me, others.)

Developers can choose to use whichever path suits their project. The problem is if they use a CanvasContext, VexFlow can draw the text before the font has loaded. This was the bug in our ChordSymbol canvas test case.

Before, in flow.html, we included the Google CSS for Roboto Slab, and we implemented our own CSS @font-face for a local copy of PetalumaScript.

I changed it so that we use the FontFace API to load them from the unpkg CDN. This way allows us to use Promises / async to wait for the fonts to be available before starting the CanvasContext tests.

In a different PR, we can also add two examples to vexflow/demos/ to illustrate both ways of loading web fonts. I'm sure developers would appreciate being able to include any Google Web Font in the <head>...</head> and having it show up as the text font in their score.

[ronyeh]

But textFont is an actual instance of TextFont class. Couldn't you still make textFont a property of Element? I don't see the conflict.

:-) I think we need to sync up.

From what I've seen, VexFlow has three things:
A) Element.musicFont which is an instance of Font. This is for engraving music symbols with Bravura, Petaluma, Gonville.
B) Element.font which is an optional instance of FontInfo. This represents the CSS font family, size, weight, and style.
C) ChordSymbol.textFont which is an instance of TextFont.

A is well understood by us maintainers. However, maybe Font should really be renamed to MusicFont (but I've already introduced enough breaking name changes!!).

B is used to set the CSS font in the rendered svg or canvas element. Before this PR, each element that needed to set the font (e.g., to 'bold 10pt Arial') implemented its own setFont() method and internal .font property. I moved them all up to the Element class so the API could be consistent, and match the CanvasRenderingContext2D.font API as closely as possible.

So while working on this PR, I wanted to rename the Element.font to Element.textFont, so that we could distinguish it from Element.musicFont.

Then I encountered ChordSymbol.textFont, and the TextFont class :-).

The purpose of C (the TextFont class) overlaps a bit with B (native CSS fonts).

To me it seems like the purpose of TextFont is for registering web fonts so that we can use them in elements. Is this correct?

Is there any way we can merge B and C in a clean way? Certainly, web fonts that are fully loaded can be assigned to the CanvasContext / SVGContext as 'italic bold 16pt PetalumaScript'.

Looking at all the uses of this.textFont, it looks like it's for metrics so that we can carefully position characters.

Can we rename the member to Element.textFontMetrics? It would be an optional object that can be used for careful positioning of text glyphs, as demonstrated by ChordSymbol.

Then we could rename Element.font => Element.textFont. :-)

The bigger thing I see is that it seems like a big hurdle for a developer to add a new web font so that it can be used in ChordSymbol. Is there any way we can avoid having to generate a xxx_textmetrics.ts file?

Canvas and SVG know how to draw their own font glyphs, as long as the web font has been loaded properly. Can we get away with just having hand tuned kerning hints (a la bravura_metrics.ts) that a developer can provide for his/her preferred web font? Anyways, this topic is for a different PR. :-)

My main goal for this PR is to 1) consolidate how we handle the .font property (CSS fonts) and 2) clearly distinguish between music fonts and text fonts.

If you are OK with me renaming the ChordSymbol.textFont field (and maybe refactoring the TextFont class a bit more), I think I could achieve this.

[ronyeh]

Prevent git from corrupting our font files.

[ronyeh]

@AaronDavidNewman @0xfe
Since we are redistributing open source fonts on the unpkg CDN, I figured it'd be good practice to include the LICENSE files from each respective project.

https://unpkg.com/[email protected]/

These can be the web font files that VexFlow supports by default. A developer can choose his/her own (e.g., from Google Fonts) and then host on a different CDN.

I'm keeping these font files in the vexflow/tools/woff/ folder, but publishing them as a separate npm project. This allows us to update font files (if necessary) without having to push a new vexflow release.

[AaronDavidNewman]

OK, I get it. It sounds like the least-breaky thing is to rename ChordSymbol.textFont to ChordSymbol.textFormatter, or textMetrics if you like that better. Then it wont eclipse textFont in Element.

I have no strong opinion about the name of TextFont class.

The thing about git corrupting the font files is a good find- I always wondered how that happened, now we know.

[ronyeh]

Converting to draft for now, while I incorporate some of Aaron's feedback.

I think the best way is to call music engraving fonts MusicFont / MUSIC_FONT_STACK / this.musicFont / etc.

Then system built-in fonts & web fonts for displaying text will be called Font / FONT / this.font / this.fontFormatter / etc. This aligns with the browser context2d API, which allows you to set the .font to 'bold 10pt Arial'.

I'll make sure I get everyone's buy-in on the changes.

[ronyeh]

@AaronDavidNewman Do you know where we got the Petaluma Script woff file that is located at vexflow/releases/fonts/petalumascript-webfont.woff? (Did you generate it yourself? Did you extract it from Dorico somehow?)

I got a copy from here:
https://github.com/steinbergmedia/petaluma

Both woff files specify version 1.10, but they are very different! I used https://fontdrop.info/ to inspect, and my version has 549 glyphs (the current vexflow version has 185 glyphs). However, the current vexflow version seems to have better kerning!

I assume that we should go forward with the one that is released on their GitHub repo, but I'm just confused. :-) The GitHub release is designed at 1000 upem, but the current vexflow woff is 2048 upem, which indicates it is related to a TrueType font.... The GitHub version is named "PetalumaScript" in the font metadata, and the vexflow copy is called "Petaluma Script Regular".

Any ideas?

[AaronDavidNewman]

Do you know where we got the Petaluma Script woff file that is located at

I got it from the same place. I only extracted metrics for the symbols 33-127 (ASCII), so it's possible I used the font tools to extract only those glyphs. But I have no memory of doing this.

EDIT: I think it's more likely that I used font squirrel to do this

[ronyeh]

EDIT: I think it's more likely that I used font squirrel to do this

OK, I was about to say it feels like we extracted a subset of the font. Steinberg has only ever released one version of PetalumaScript, but the first version you ever checked in is only 45KB and has a subset of the glyphs.

https://github.com/AaronDavidNewman/Smoosic/blob/eee9784bf2aa7fc5e5b1ceafecc55d1dd34851c1/build/styles/fonts/petalumascript-webfont.woff

In my PR, I'm going to opt for using the official Steinberg woff file. Is that OK? As long as we preserve the way for developers to select / register their own woff files (via your registerFont method). :-)

[ronyeh]

I have verified that FontSquirrel produces the same petaluma woff file: https://www.fontsquirrel.com/tools/webfont-generator

I uploaded the OTF file and selected FontSquirrel defaults (which includes the 2048 upem).

Since Steinberg released an official woff file, we should use theirs (but allow developers to load their own smaller woff files if desired).

[sschmidTU]

Is this going to increase the size of the release or is this just an intermediary build file? Because Vexflow is already big, and it would be nice to keep its size in check.
That reminds me that we wanted to be able to create releases of Vexflow with (smaller) subsets of fonts, i hope that's still on the table :)

[rvilarl]

@ronyeh just a few conflicts, IMO ready to merge afterwards.

[ronyeh]

Please merge these sub PRs next:

• Fonts: CONSTANTS & TEXT_FONT #1210
• Run prettier / eslint on the font data files, to improve consistency and editability of the files. #1212

We are getting close. I'll fix the conflicts and rebase after the above two are reviewed & merged, and then I think this branch might be reviewable on its own!

I will do more testing today, and will put up a *.tgz for folks to npm install into their own projects. Once the major integration issues are ironed out, we can have Mohit ship a version to npm with the beta dist-tag: https://docs.npmjs.com/adding-dist-tags-to-packages#example

[ronyeh]

Thanks Ron -- these changes are great. Also very breaking. Adding a comment to the 4.0 issue about prototyping the API changes with VexTab.

I'm migrating VexTab right now. Will update folks with a list of what API changes happened between 3.0.8 and 4.0.0 (from the perspective of VexTab).

[rvilarl]

I believe that this one can be now closed.

[ronyeh]

I believe that this one can be now closed.

Even though the 4.0.0 PR subsumes this one, I'll keep it open until all the major parts of the Font work have been merged.

I haven't yet submitted sub PRs for the core font work, which includes:

• Consolidate the setFont() method. The thing that started this all!
• Separate the TextFont class into the Font class and the TextFormatter class.
• Dynamic font loading without using tsconfig paths, and emitting different build targets for each font.
• Tests for the Font contributions.

These PRs will come over the next week, to aid in code review.

[rvilarl]

Do not forget to move the linked issues to 4.0.0 PR!

[ronyeh]

Closing this PR for now. The 4.0.0 branch / PR includes the font improvements from this PR.

I will continue to examine how to submit smaller PRs to the main repo so we can get our branches merged and a beta released.