Metadata-Version: 2.4
Name: ofl-font-baker
Version: 0.2.1
Summary: Font merge engine — combine two font files into one via cmap-based glyph replacement
Project-URL: Homepage, https://github.com/yamatoiizuka/ofl-font-baker
Project-URL: Repository, https://github.com/yamatoiizuka/ofl-font-baker
Project-URL: Issues, https://github.com/yamatoiizuka/ofl-font-baker/issues
Author-email: Yamato Iizuka <me@yamatoiizuka.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cff,cjk,font,merge,opentype,truetype
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Fonts
Requires-Python: >=3.9
Requires-Dist: brotli>=1.1.0
Requires-Dist: fonttools>=4.47.0
Description-Content-Type: text/markdown

# Font Merge Engine

<p>English | <strong><a href="https://github.com/yamatoiizuka/ofl-font-baker/blob/main/python/README.ja.md">日本語</a></strong></p>

The core font merge engine behind [OFL Font Baker](https://github.com/yamatoiizuka/ofl-font-baker).
The code in this directory is MIT-licensed and can be freely used in other projects.

Merges a base font (typically CJK) with a sub font (typically Latin or kana) into a single font file, replacing glyphs and OpenType features via cmap-based mapping.

For details on features and background, see the [OFL Font Baker repository](https://github.com/yamatoiizuka/ofl-font-baker).

## Installation

```bash
pip install ofl-font-baker
```

Requires Python 3.9+. [fonttools](https://github.com/fonttools/fonttools) and [brotli](https://github.com/google/brotli) are installed automatically.

## Usage

Provide a JSON config on stdin. The engine supports two modes:

```bash
cat config.json | python3 merge_fonts.py
```

### Path Mode

Specify output file paths explicitly via `export.path`. Only the files whose paths are provided are written.

```json
{
  "baseFont": {
    "path": "/path/to/base.otf",
    "scale": 1.0,
    "baselineOffset": 0,
    "axes": []
  },
  "subFont": {
    "path": "/path/to/sub.ttf",
    "scale": 1.0,
    "baselineOffset": 0,
    "axes": []
  },
  "output": {
    "familyName": "My Font",
    "weight": 400,
    "italic": false,
    "width": 5
  },
  "export": {
    "path": {
      "font": "/out/MyFont-Regular.otf",
      "woff2": "/web/MyFont-Regular.woff2"
    }
  }
}
```

### Package Mode

Specify `export.package` to create a complete output directory with font files and metadata.

```json
{
  "baseFont": { "path": "/path/to/base.otf", "scale": 1.0, "baselineOffset": 0, "axes": [] },
  "subFont": { "path": "/path/to/sub.ttf", "scale": 1.0, "baselineOffset": 0, "axes": [] },
  "output": { "familyName": "My Font" },
  "export": {
    "package": {
      "dir": "/exports/MyFont-Regular"
    }
  }
}
```

Output (JSON manifest on stdout):

```json
{
  "outputDir": "/exports/MyFont-Regular",
  "fontPath": "/exports/MyFont-Regular/MyFont-Regular.otf",
  "woff2Path": "/exports/MyFont-Regular/MyFont-Regular.woff2",
  "oflPath": "/exports/MyFont-Regular/OFL.txt",
  "settingsPath": "/exports/MyFont-Regular/Settings.txt",
  "configPath": null,
  "files": [...]
}
```

Progress is emitted as JSON lines on stderr.

### `output`

| Key             | Default      | Description                                                                                                                                                         |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `familyName`    | `"Font"`     | Output font family name.                                                                                                                                            |
| `weight`        | `400`        | Font weight (100–900).                                                                                                                                              |
| `italic`        | `false`      | Whether the output is italic.                                                                                                                                       |
| `width`         | `5`          | Font width class (1–9).                                                                                                                                             |
| `upm`           | (from base)  | Target units-per-em. When different from the base font, all metrics and outlines are scaled.                                                                         |
| `copyright`     | `""`         | Additional copyright string appended to source copyrights.                                                                                                          |
| `designer`      | `""`         | Designer name for nameID 9.                                                                                                                                         |
| `metricsSource` | `"base"`     | Which font's vertical metrics (OS/2, hhea) to use. `"base"` keeps the base font metrics and expands only when the sub font is larger. `"sub"` overwrites with the sub font's metrics. |

### `export.path`

All keys are optional. Only files whose paths are specified are written. `woff2` requires `font`.

| Key        | Description                  |
| ---------- | ---------------------------- |
| `font`     | Font file (OTF/TTF) path.   |
| `woff2`    | WOFF2 file path.             |
| `ofl`      | OFL.txt path.                |
| `settings` | Settings.txt path.           |
| `config`   | ExportConfig.json path.      |

### `export.package`

Creates a complete output directory. Always generates font, WOFF2, OFL.txt, and Settings.txt.

| Key                | Default | Description                                                                                                                                         |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dir`              |         | Output directory path (required).                                                                                                                   |
| `overwrite`        | `false` | Allow overwriting an existing directory.                                                                                                            |
| `bundleInputFonts` | `false` | Copy input fonts into a `source/` subdirectory and write `ExportConfig.json` with relative paths. Makes the package self-contained and reproducible. |

## Tests

```bash
python3 -m pytest python/tests/test_merge.py -v
```

Test fonts are in `testdata/fonts/` (repository root).

## License

The source code in this directory is licensed under the MIT License. See [LICENSE](LICENSE) for details.

Other parts of the parent repository ([OFL Font Baker](https://github.com/yamatoiizuka/ofl-font-baker)) are licensed under AGPL-3.0-or-later and are not covered by this MIT notice.
