convert

Convert individual fonts between different formats.

For Collection Formats

Use pack/unpack to work with TTC, OTC, and dfont collections. The convert command is for individual font files only.

Quick Reference

fontisan convert <input> --to <format> [options]

Supported Formats

These are individual font formats that can be converted:

Format	Read	Write	Description
TTF	✅	✅	TrueType (glyf outlines)
OTF	✅	✅	OpenType (CFF outlines)
WOFF	✅	✅	Web Open Font Format
WOFF2	✅	✅	Web Open Font Format 2
PFB/PFA	✅	—	Adobe Type 1 (read for conversion)

Options

Option	Description
--to FORMAT[,FORMAT...]	Target format(s): ttf, otf, woff, woff2, type1/t1, ttc, otc, dfont, svg. Pass once with comma-separated values (--to woff,woff2) or multiple times (--to woff --to woff2) for multi-format output.
--output FILE	Output file path (see "Output path rules" below)
--optimize	Enable outline optimization
--flatten	Flatten composite glyphs
--zlib-level=N	WOFF only: zlib compression level (0–9, default 6)
--uncompressed	WOFF only: store tables uncompressed (legal per WOFF 1.0 §5.1)
--compression-threshold=N	WOFF only: skip compression for tables smaller than N bytes (default 100)
--brotli-quality=N	WOFF2 only: Brotli quality (0–11, default 11)
--transform-tables / --no-transform-tables	WOFF2 only: apply glyf/loca + hmtx transformations

The format you pick (--to woff vs --to woff2) is the algorithm choice — WOFF mandates zlib, WOFF2 mandates Brotli. Passing a WOFF knob to a WOFF2 target (or vice versa) exits 1 with a clear error.

Multi-format output

--to accepts multiple targets so a single invocation produces N output files from one input font. Both spellings work and produce identical results:

# Comma-separated (one --to flag)
fontisan convert font.ttf --to woff,woff2 --output font

# Repeated flag (Thor array form)
fontisan convert font.ttf --to woff --to woff2 --output font

Duplicates are deduplicated, so --to woff,woff2,woff is equivalent to --to woff,woff2.

Output path rules

--output shape	--to shape	Behaviour
out.ttf (has extension)	one format	Use as given
out (no extension)	one format	Append .<format> → out.ttf
out (no extension)	many formats	Append .<format> per target → out.woff, out.woff2
out.ttf (has extension)	many formats	Error: ambiguous which format gets the extension

Multi-format is single-font → single-font only. Combining multi-format with collection input (TTC/OTC/dfont) exits 1 — collections pack multiple faces and N formats × M faces explodes output count. Convert collections to one target format at a time.

Common Workflows

Convert for Web

# TTF to WOFF2 (recommended for modern browsers)
fontisan convert font.ttf --to woff2 --output font.woff2

# OTF to WOFF (broader compatibility — works on IE 9+)
fontisan convert font.otf --to woff --output font.woff

# Smallest possible WOFF2 (max Brotli + table transforms)
fontisan convert font.ttf --to woff2 --output font.woff2 \
  --brotli-quality 11 --transform-tables

# WOFF with max zlib compression
fontisan convert font.ttf --to woff --output font.woff --zlib-level 9

# WOFF stored uncompressed (legal per WOFF 1.0 §5.1; useful for tooling)
fontisan convert font.ttf --to woff --output font.woff --uncompressed

Convert Between Outline Formats

# TrueType to OpenType (glyf → CFF)
fontisan convert font.ttf --to otf --output font.otf

# OpenType to TrueType (CFF → glyf)
fontisan convert font.otf --to ttf --output font.ttf

Convert Legacy Type 1 Fonts

# Type 1 to OpenType
fontisan convert font.pfb --to otf --output font.otf

Emit Multiple Web Formats in One Invocation

# Both WOFF (legacy IE9+) and WOFF2 (modern browsers) from one input
fontisan convert font.ttf --to woff,woff2 --output font
# → font.woff, font.woff2

# Same result with the repeated-flag form
fontisan convert font.ttf --to woff --to woff2 --output font

Working with Collections

Collection formats (TTC, OTC, dfont) contain multiple fonts. To convert fonts from a collection:

# Step 1: Extract fonts from collection
fontisan unpack family.ttc --output-dir ./extracted

# Step 2: Convert each font
fontisan convert ./extracted/Font-Regular.ttf --to woff2 --output Font-Regular.woff2
fontisan convert ./extracted/Font-Bold.ttf --to woff2 --output Font-Bold.woff2

# Or extract and convert in one step:
fontisan unpack family.ttc --output-dir ./web --format woff2

Detailed Documentation

For comprehensive documentation including curve conversion, hint handling, and advanced options, see the convert command guide.