Creating a SMuFL-compatible music font requires more than assigning Unicode values to musical symbols. A professional font combines carefully designed glyphs, standardized mappings, geometric measurements, accurate attachment points, and metadata that helps notation software position and space the symbols correctly.
The Standard Music Font Layout (SMuFL) provides a common framework while leaving considerable freedom for original musical typography. This practical guide follows the process from glyph design and identification through measuring, metadata construction, validation, and distribution.
1. Prepare and organize the musical glyphs
Begin with an inventory of the symbols your font needs to support: noteheads, clefs, accidentals, rests, flags, articulations, dynamics, ornaments, time signatures, and repeat symbols. Each group should be checked for visual consistency, technical completeness, and intended musical use.
A handwritten family may use expressive, irregular noteheads and accidentals, while a traditional engraved family may emphasize balanced proportions and controlled stroke contrast. In both cases, the symbols must remain recognizable and behave correctly when combined in a score.
Build a glyph inventory
| Glyph family | Main design considerations |
|---|---|
| Noteheads | Width, proportions, stem attachment |
| Clefs | Staff alignment and optical balance |
| Accidentals | Shape, spacing, collision avoidance |
| Rests | Positioning and visual weight |
| Flags | Stem attachment and overlap |
| Dynamics | Optical centering and consistent weight |
| Articulations | Placement above and below notes |
| Time signatures | Numeral proportions and vertical alignment |
The objective is to establish a coherent musical alphabet before constructing its technical metadata.
2. Establish the font’s coordinate system
SMuFL uses the distance between two adjacent staff lines—one staff space—as the fundamental measurement unit. For fonts intended for scoring applications, the recommended relationship is one staff space equals one quarter of an em.
| Font units per em | One staff space |
|---|---|
| 1,000 | 250 design units |
| 2,048 | 512 design units |
Clefs, noteheads, accidentals, and articulations cannot be positioned reliably unless their dimensions are interpreted relative to the staff. After establishing a consistent coordinate system, convert glyph dimensions and anchor coordinates from font units to staff-space units. For example, in a 1,000-units-per-em font, an advance width of 500 units equals two staff spaces.
Follow the SMuFL glyph-registration rules as well as the scaling recommendation: different categories of glyph have different requirements for where their origins sit relative to staff lines and notes.
3. Assign the correct SMuFL glyph names and code points
Every standard symbol must be mapped to its corresponding SMuFL identity. The published glyph repertoire defines canonical names and code points. For example, the filled black notehead is named noteheadBlack.
For each source symbol, identify its musical function, find the corresponding canonical name, assign the correct code point, and check for duplicates or mismatches. Legacy music fonts may have entirely different mappings, so simply preserving their original character positions is not a valid conversion.
Mapping should follow a symbol’s musical meaning, not just its resemblance to another glyph. A font does not have to implement every optional symbol, but it should supply the repertoire its intended scoring applications need.
4. Calculate glyph advance widths and bounding boxes
Advance widths
The advance width is the horizontal distance from a glyph’s origin to the next placement position. It is not necessarily identical to the visible width of its outline. Where provided, these measurements belong in glyphAdvanceWidths.
Bounding boxes
A bounding box is the smallest rectangle enclosing the entire outline. SMuFL uses bBoxSW for the southwest corner and bBoxNE for the northeast corner of the glyph’s bounding box. These are stored in glyphBBoxes.
Express both types of measurement in staff spaces, not raw font units. For a font with 1,000 units per em, divide the font-unit coordinates by 250. Bounding boxes provide an essential geometric description, but cannot by themselves describe every stem connection or collision-avoidance opportunity; additional anchor metadata is needed.
5. Define glyph attachment anchors
Attachment anchors identify the precise points at which musical elements must connect. Without these, stems may look displaced or disconnected from noteheads even if the notehead outline is beautifully drawn.
Two key notehead anchors are stemUpSE, the attachment location for an upward stem on the right, and stemDownNW, the attachment location for a downward stem on the left. Their coordinates depend on the actual outline and may differ greatly between a formal oval notehead and a handwritten design.
Start with the geometric outline, determine the required attachment positions, convert the coordinates to staff spaces, and refine them in actual music. Other anchors serve different purposes, such as repeatOffset for repeating elements and opticalCenter for visually balanced placement. Flag and grace-note connections also have their own defined conventions.
Only provide anchors that are meaningful for the particular glyph. Consult the official glyphsWithAnchors reference for the precise meanings and coordinate systems of each anchor type.
6. Calculate cutouts for improved musical spacing
A rectangle around a glyph often contains empty areas. This becomes especially important for accidentals in dense chords: two shapes may be able to interlock even when their ordinary bounding boxes would collide.
SMuFL describes these opportunities using four possible cutout anchors: cutOutNE, cutOutSE, cutOutSW, and cutOutNW. They identify rectangular regions that can be excluded from the respective corners of the glyph’s bounding box when calculating certain spacing relationships.
To determine cutouts, examine the real outline, establish its bounding box, identify suitable empty corner regions, and specify cutout points without excluding occupied portions of the glyph. Convert the resulting coordinates into staff spaces.
Cutouts must reflect the actual font being created. Copying cutout measurements blindly from another font can create misleading collision geometry. For more detail, consult the official bounding-box cutouts explanation.
7. Establish optical centers and special geometric relationships
The mathematical middle of a glyph’s bounding box is not necessarily its visually balanced center. An italic forte, for example, can look displaced when aligned mechanically because its outline is asymmetric.
Where supported, an opticalCenter anchor can describe a more useful visual center. Begin with geometric analysis, then adjust the position while examining the symbol alongside notes, stems, and other score elements.
The same distinction between mathematical and optical geometry matters for repeated elements, certain ornaments, and composite symbols. Accurate typography requires both measurement and informed visual judgment.
8. Define the engraving defaults
Many features of musical engraving are drawn by notation software rather than supplied as characters in the music font. The engravingDefaults metadata section can recommend parameters including staff-line thickness, stem thickness, beam thickness, barline thickness, and related values.
A bold notation design may need different default thicknesses than a lightweight engraved face. Choose values that complement the font’s visual characteristics, and check the results at realistic staff sizes. Another SMuFL font can be a reference for the structure of the data, but its particular numbers are not automatically suitable for your design.
9. Create alternative glyphs and composite symbols
A professional font may include alternative clefs, noteheads, articulations, or time-signature forms. Some variants can be derived by reflection, rotation, or scaling, but not every mechanical transformation yields an acceptable musical symbol. Transformed outlines may require adjustment to their registration, contours, side bearings, or anchors.
Assign suitable identities to implemented variants. Where appropriate, metadata can describe stylistic sets, alternative glyphs, ligatures, and optional font-specific symbols. These structures must accurately reflect glyphs present in the delivered OpenType file.
10. Assemble the SMuFL JSON metadata
The final font-specific JSON file brings together identity information, measurements, and positioning data. The principal sections are:
| JSON section | Information provided |
|---|---|
fontName |
Font family identity |
fontVersion |
Font version |
engravingDefaults |
Recommended engraving measurements |
glyphAdvanceWidths |
Horizontal advance measurements |
glyphBBoxes |
Glyph bounding-box coordinates |
glyphsWithAnchors |
Attachment points, optical centers, cutouts, and related geometry |
ligatures |
Supported sequences forming composite glyphs |
glyphsWithAlternates |
Alternative symbol representations |
sets |
Groups of related stylistic glyphs |
optionalGlyphs |
Additional non-standard glyphs supplied by the font |
The core required metadata fields are fontName and fontVersion; other sections should be populated when the corresponding data is available and supported. Keep family names, versions, glyph identities, and measurements consistent with the font actually distributed.
Practical example: building a black notehead
Start by drawing noteheadBlack at the intended staff-space scale, then assign its canonical SMuFL name and code point. Measure its horizontal advance and actual outline bounding box. Identify the upward- and downward-stem attachment points, express those anchor coordinates in staff spaces, and enter them in glyphsWithAnchors.
Finally, test the glyph in real passages containing upward stems, downward stems, beams, chords, and ledger lines. This demonstrates why a single glyph needs several complementary forms of metadata to function properly.
11. Validate the font and metadata
Technical checks should confirm that the JSON parses correctly, canonical glyph names and code points are consistent, numerical values use the correct units, all referenced glyphs exist, and the metadata name and version correspond to the OpenType file.
Visual tests should cover notehead–stem connections, accidental interlocking, articulation positioning, dynamics alignment, time signatures, ornament placement, multiple voices, and changes of staff size. Pay special attention to glyphs with custom anchors or cutouts.
Real engraving tests in applications such as Dorico and MuseScore Studio are valuable, but application support for individual metadata features and installation workflows may vary. Check both an ordinary score and a dense score before releasing the font.
12. Prepare the font for distribution
A typical professional release contains the OpenType music font, its matching JSON metadata, licensing information, installation instructions, and representative score samples. A companion musical text font or application-specific style resources may also be included.
Metadata must be installed in a location recognized by the intended notation application; simply installing an OTF file is not always sufficient. Consult the official SMuFL metadata locations and the instructions for each supported application.
Before distribution, perform an installation test on a clean machine or fresh user account to detect assumptions caused by files left over from development.
Conclusion
Creating a SMuFL music font brings together musical typography, geometric measurement, and technical standardization. The visual quality of the symbols matters, but so do accurate mappings, advances, bounding boxes, attachment anchors, engraving defaults, and dependable JSON metadata.
Some data can be derived systematically from the font’s outlines and metrics; other values demand careful typographic judgment. The most reliable approach combines both with practical testing in real scores. The goal is not simply a font that follows a standard, but a musical typeface that performs predictably while retaining its own distinct visual identity.