petiglyph is a TUI and CLI tool for turning images and videos into custom font glyphs.

twerking amogus in terminal has been achieved internally 😎

Choose one:

npm install -g petiglyph

pip install petiglyph

yay -S petiglyph

You can also download a prebuilt binary from GitHub Releases.

Make sure ffmpeg is available on PATH.

In a terminal, go in the folder where you want the project to be, and type:

petiglyph

This opens the TUI Home panel, where you can create a project and start importing media to create glyphs, grids, and animations.

Supported media:

• images: png, jpg, jpeg, webp, bmp, gif, svg, avif
• animation media: gif, mp4, mov, mkv, webm, avi, m4v

Generated glyphs can be of 4 types:

• standard monospace, static
• standard monospace, animated
• grid of glyphs, static
• grid of glyphs, animated

For all 4 types, petiglyph will generate the static and animated glyphs in the Installed petiglyph fonts area of the Home panel after installing the fonts.

To copy those glyphs for reusing them elsewhere, you have to navigate with your arrows to the Installed petiglyph fonts area, select the glyphs that you want, press ENTER to copy them to your clipboard, and paste them in your own tools or apps (those apps need to also have the new fonts loaded, see warning above).

Pressing ENTER on the animated glyphs copies all frames inside the clipboard. To see them animated, you need to make your own script to render all the glyphs into an animation.

Each project is self-contained:

my-font/
  petiglyph.toml
  images/
  build/
  petiglyph.lock

petiglyph.toml stores configuration, images/ stores project-local sources and imported frames, build/ stores generated artifacts, and petiglyph.lock preserves glyph-to-codepoint assignments after the first build.

Create a project with:

petiglyph new-project my-font

Without a subcommand, petiglyph opens the workspace TUI. Project discovery searches the current directory and descendants through depth 2, without following directory symlinks. One discovered project is selected automatically. Multiple projects open the workspace selector in an interactive terminal; automation commands instead report the ambiguity. use-project selects by exact project directory basename and rejects duplicate matches with candidate paths.

Global --debug enables project-local pipeline diagnostics. --ffmpeg-auto-install allows the detected package-manager command to run when FFmpeg is missing. Automation-capable commands accept --json; creation also accepts --build and --install, where --install implies a build. Use petiglyph <command> --help for exhaustive flag syntax and accepted values.

The CLI exposes the same four creation types as the TUI:

# One image per glyph
petiglyph use-project my-font create glyph \
  --input logo.png mark.svg

# One sprite sheet split into glyph cells
petiglyph use-project my-font create grid-glyph \
  --input icons.png --rows 4 --cols 4

# GIF/video frames as glyphs
petiglyph use-project my-font create animated-glyph \
  --input spinner.gif --name spinner --fps 8

# Each frame split into grid cells
petiglyph use-project my-font create animated-grid-glyph \
  --input dashboard.mp4 --name dashboard --fps 10 \
  --rows 2 --cols 4

One --input accepts multiple paths. Creation imports and configures sources without building or installing unless requested. Static build inputs are png, jpg, jpeg, webp, bmp, gif, and svg. avif is import-only and is converted to project-local PNG. Animation media supports gif, mp4, mov, mkv, webm, avi, and m4v.

petiglyph use-project my-font configure glyph logo.png \
  --threshold 88 --invert on
petiglyph use-project my-font configure glyph logo.png \
  --clear-threshold
petiglyph use-project my-font configure grid-glyph icons.png \
  --rows 2 --cols 8 --horizontal-bleed strong --vertical-bleed off
petiglyph use-project my-font configure animation spinner \
  --fps 12 --threshold 72 --invert off
petiglyph use-project my-font delete animation spinner

Grid dimensions and bleed are valid only for grid sources and grid animations.

The image pipeline performs optional grayscale import processing, aspect-fit scaling, thresholding, optional inversion, and then optional grid-edge bleed. All previews preserve the source or glyph aspect ratio with one uniform scale; empty vertical rows may be cropped before fitting, but previews are never stretched to fill spare width or height.

off keeps grid edges clipped, weak adds a small overlap, and strong adds a larger overlap. Bleed changes final outline geometry, not thresholding.

Normal reads and builds may rewrite petiglyph.toml to create or normalize managed fields, so keep it writable.

Grid compositions contain rows, cols, horizontal_bleed, and vertical_bleed. Omitted bleed values normalize to weak horizontally and off vertically.

[compositions."icons.png"]
rows = 4
cols = 4
horizontal_bleed = "weak"
vertical_bleed = "off"

[[animations]]
name = "spinner"
type = "standard"
fps = 8
frames = ["spinner-0001.png", "spinner-0002.png"]

[[animations]]
name = "dashboard"
type = "grid"
fps = 10
frames = ["dashboard-0001.png", "dashboard-0002.png"]
rows = 2
cols = 4
horizontal_bleed = "weak"
vertical_bleed = "off"

Animation frame paths are relative source keys. Standard animations must not define grid fields. Grid animations require positive rows and cols. Animation entries may also contain grayscale_processing, which records grayscale_enabled plus a nested grayscale table with gamma_percent, contrast, and brightness. Tone values are normalized to their supported ranges on read.

petiglyph use-project my-font build
petiglyph use-project my-font build --force-remap

Existing source mappings remain stable through petiglyph.lock. Removed mappings may remain inactive so their codepoints are not accidentally reused. Petiglyph reserves non-overlapping supplementary private-use ranges for managed projects. A normal build can relocate and remap a project automatically if its owned range must grow and existing assignments cannot be preserved.

--force-remap intentionally discards the existing assignments and allocates a fresh mapping. Text stored with old codepoints can then render the wrong glyphs or no glyph at all.

The generated TTF can be embedded in another application like any standard font. Embedding the Petiglyph executable itself also requires FFmpeg to be available on each user's system.

petiglyph use-project my-font install-font
petiglyph list installed-fonts
petiglyph uninstall-font "my-font Petiglyph"
petiglyph uninstall-all-fonts

Installation is explicit, managed, and owned by project metadata. Reinstalling a project replaces that project's previous managed artifact. Petiglyph refreshes or broadcasts font-cache state where the platform supports it.

Managed locations:

Use list installed-fonts for the exact family names accepted by uninstall-font. Uninstall commands select managed artifacts through Petiglyph metadata and do not remove unrelated fonts. Restart applications after changing fonts so they reload font state; a full system reboot is only a fallback.

On Windows Terminal 1.21 or newer, add the installed family after the primary terminal font as a fallback, for example "Cascadia Mono, my-font Petiglyph".

petiglyph doctor always checks global managed-install and Unicode registry state. It also runs project checks when one or more manifests can be resolved. petiglyph use-project my-font doctor selects one project explicitly.

Checks cover stale global and project locks, malformed install metadata, orphaned metadata and managed TTFs, Unicode registry structure and range conflicts, manifest validity, source visibility, and glyph-lock identity, entries, codepoints, and source references.

petiglyph doctor --repair
petiglyph use-project my-font doctor --repair

--repair performs only supported repairs, such as removing stale locks and orphans, removing invalid glyph-lock entries, or recreating a missing project range assignment. It does not rebuild or reinstall a project.

Add --json to supported commands:

petiglyph list projects --json
petiglyph use-project my-font create glyph \
  --input logo.svg --build --json
petiglyph use-project my-font doctor --json

Successful and failed commands use one envelope:

{
  "ok": false,
  "command": "use-project.create.glyph",
  "version": "0.1.5",
  "data": {
    "completed_stages": ["resolve", "import", "configure"]
  },
  "error": {
    "code": "creation_stage_failed",
    "stage": "build",
    "message": "build failed",
    "causes": [],
    "hints": [
      "Imported files and manifest changes were retained.",
      "Fix the reported cause, then run the project build or install command."
    ]
  }
}

Failures return a non-zero exit code. A multi-stage creation failure can retain completed imports and manifest changes; inspect data.completed_stages, fix the reported cause, then run build or install again.

FFmpeg is checked before command dispatch, including TUI launch. Install it on PATH, pass --ffmpeg-auto-install, or set PETIGLYPH_NO_FFMPEG_PROMPT=1 to suppress the interactive install hint.

--debug or a truthy PETIGLYPH_DEBUG enables image-pipeline diagnostics in the selected project's debug/pipeline.log and debug/artifacts/. PETIGLYPH_DEBUG_CELL=<width>x<height> overrides terminal cell geometry used by debug preview rendering.

Set PETIGLYPH_TUI_DEBUG=1 for TUI event logging. Logs use the platform temporary directory by default; PETIGLYPH_TUI_DEBUG_LOG=/path/to/log overrides the path.

• CI.md
• RELEASE.md
• CONTRIBUTING.md