HarfBuzz — The Text Shaping Engine Behind Every Modern Browser

Introduction

HarfBuzz is an OpenType text shaping engine that converts sequences of Unicode code points into properly positioned glyph sequences. It handles the complex rules needed for Arabic, Devanagari, Thai, and other scripts where characters change shape depending on their neighbors.

What HarfBuzz Does

• Performs text shaping: maps Unicode text to positioned glyphs using OpenType font tables
• Handles bidirectional text, ligatures, kerning, and mark positioning
• Supports OpenType, AAT (Apple Advanced Typography), and Graphite font formats
• Provides subsetting capabilities for extracting only the glyphs needed for a given text
• Ships command-line utilities for inspecting fonts and testing shaping output

Architecture Overview

HarfBuzz is written in C++ with a C API for broad language interoperability. The shaping pipeline reads OpenType layout tables (GSUB for substitution, GPOS for positioning) and applies the rules in the order specified by the font's script and language tags. A built-in Unicode normalizer and fallback shaper handle cases where fonts lack explicit layout tables. The library is designed to be embedded with minimal dependencies.

Self-Hosting & Configuration

• Available in virtually every Linux distribution's package manager, Homebrew on macOS, and vcpkg on Windows
• Build from source with Meson: meson setup build && ninja -C build
• Optional dependencies include FreeType (glyph rendering), ICU (Unicode), and GLib (data structures)
• Can be built as a minimal standalone library with no external dependencies
• Used as a library; no daemon or service to configure

Key Features

• Handles all major complex scripts including Arabic, Hebrew, Indic, Thai, and CJK
• Font subsetting via hb-subset for producing smaller font files for web delivery
• Thread-safe and re-entrant design for use in multi-threaded applications
• Comprehensive C API with bindings available for Python, Rust, Go, and other languages
• Extensive test suite validated against real-world font and script combinations

Comparison with Similar Tools

• FreeType — rasterizes glyphs into bitmaps; HarfBuzz handles shaping (glyph selection and positioning) and the two are commonly used together
• ICU — provides a shaping engine as part of a larger Unicode library; HarfBuzz is more focused and widely preferred for shaping alone
• Pango — higher-level text layout library that uses HarfBuzz internally for shaping
• DirectWrite — Windows text shaping API; proprietary and platform-specific
• CoreText — macOS text engine; HarfBuzz provides cross-platform equivalent functionality

FAQ

Q: Why do browsers need a text shaping engine? A: Many writing systems require context-dependent glyph selection, ligatures, and precise positioning. Without shaping, Arabic text would appear as disconnected letters and Devanagari conjuncts would not form correctly.

Q: Is HarfBuzz the same as FreeType? A: No. FreeType renders glyphs into pixels. HarfBuzz determines which glyphs to use and how to position them. They complement each other in most text rendering stacks.

Q: What is font subsetting? A: Subsetting extracts only the glyphs needed for a specific text from a font file. HarfBuzz's hb-subset tool is used by web font services to reduce download sizes.

Q: Which projects depend on HarfBuzz? A: Firefox, Chromium, Android, GNOME, LibreOffice, Godot Engine, and many other projects use HarfBuzz for text shaping.

Sources

• https://github.com/harfbuzz/harfbuzz
• https://harfbuzz.github.io/