glb-compressor CLI

Command-line tool for compressing GLB/glTF 3D model files. Supports glob patterns, configurable presets, mesh simplification, and batch processing.

Binary Name

glb-compressor (installed via npm/bun) or bun run cli (from source).

Usage

glb-compressor <files...> [options]

Options

| Flag | Description | Default | | ---------------------- | ------------------------------------------ | ----------------------------------------- | | -o, --output <dir> | Output directory | Same as input (with -compressed suffix) | | -p, --preset <name> | Compression preset | default | | -s, --simplify <0-1> | Mesh simplification ratio (e.g. 0.5 = 50%) | None | | -q, --quiet | Suppress progress output (for scripting) | false | | -f, --force | Overwrite existing output files | false | | -h, --help | Show help text | | | -v, --version | Show version | |

Presets

| Preset | Behavior | | ------------ | ---------------------------------------------------------------- | | default | Conservative, preserves all detail | | balanced | Moderate animation quantization, 24 Hz resample | | aggressive | Strong animation quantization, 15 Hz resample (best for avatars) | | max | Aggressive + supercompression + lower vertex precision |

Examples

# Compress a single file
glb-compressor model.glb

# Aggressive preset to an output directory
glb-compressor model.glb -p aggressive -o ./out/

# Batch compress with glob, overwrite existing
glb-compressor *.glb -f -p balanced

# Quiet mode for CI/scripts (exit code 0 = success, 1 = failure)
glb-compressor model.glb -q -p max

# Simplify mesh to ~50% vertex count
glb-compressor model.glb -s 0.5

# From source (development)
bun run cli -- model.glb -p aggressive -o ./compressed/

Output Naming

Output files are named <input>-compressed.glb. When -o is specified, files are placed in that directory. Without -o, output is written alongside the input file.

Exit Codes

| Code | Meaning | | ---- | --------------------------------- | | 0 | All files compressed successfully | | 1 | One or more files failed |

Pipeline

The CLI runs the same 6-phase pipeline as the library:

1. Cleanup - dedup, prune, remove unused UVs (+ flatten/join/weld for static)
2. Geometry - merge by distance, remove degenerate faces, auto-decimate
3. GPU - instancing, vertex reorder, sparse encoding
4. Animation - resample keyframes, remove static tracks, normalize weights
5. Textures - compress to WebP (max 1024x1024)
6. Final - gltfpack (preferred) or meshopt WASM fallback

Skinned models are auto-detected and take a conservative path that skips transforms known to break skeleton hierarchies.

Skinned Model Awareness

When a GLB contains skins (e.g. avatars), the CLI automatically skips: flatten, join, weld, mergeByDistance, reorder, quantize, and auto-decimate. This prevents broken skeleton hierarchies, vertex weight denormalization, and mesh clipping artifacts.

Dependencies

• gltfpack (optional): If found in $PATH, used for final compression (best results). Falls back to meshopt WASM if unavailable.
• sharp: Used for texture compression to WebP.