Installation — Mografy

Requirements

Mografy currently runs from its source workspace. Have these tools available before you begin.

Git

Required to clone the repository from GitHub

Node.js

Version 22.12 or later

Package manager

pnpm, installed with npm install -g pnpm; it switches to the version Mografy pins by itself

System tools

None to install by hand: pnpm install downloads Chromium, and FFmpeg is bundled

Install from GitHub

Use git clone to download the Mografy repository, then enter its folder and run the setup below. Skip npm install -g pnpm if you already have pnpm.

Terminal

git clone https://github.com/zz41354899/mografy.git
cd mografy
npm install -g pnpm
pnpm install

What pnpm install does: it installs dependencies, then automatically builds Mografy, downloads the Chromium it uses for checks and exports, and puts the mografy command on your PATH.

Launch Mografy

Run the command in the Mografy folder. If the player opens with the sixteen built-in animations, the installation works.

Terminal

mografy dev

On first launch, Mografy initializes the sixteen independent built-in components and opens Stagger text.

Create or open a project

Create an editable project in the source library or open the bundled twelve-second introduction.

Terminal

mografy dev ./projects/my-animation --yes
mografy dev ./examples/mografy-intro

Set MOGRAFY_HOME when you want the project library in another directory. Other settings are listed in the configuration guide.

Use your coding agent

The shared Mografy Skill gives Claude and Codex the same workflow for storyboards, scene code, frame review, and export.

Describe the message, duration, format, and visual constraints in plain English.
Let the agent choose a built-in component or plan a short storyboard.
Keep mografy dev open while the agent edits the scene module.
Review frames and timing before exporting the final file.

Export

Use the player’s Export button, or export from the command line. MP4 uses H.264/AAC; WebM uses VP9/Opus. Both support 720p/1080p landscape and portrait exports, audio and output effects. Lottie and SVGA package image frames for web and mobile players.

Terminal

mografy export ./projects/my-animation --format mp4
mografy export ./projects/my-animation --format webm
mografy export ./projects/my-animation --format lottie
mografy export ./projects/my-animation --format svga

WebM quality: starts with constant quality at CRF 32. Draft, Standard and High presets use CRF 38, 32 and 26. Lower CRF keeps more detail and usually makes larger files. Bitrate varies with scene complexity, so file size is not fixed. Encoding can take longer than H.264; compare actual outputs before choosing settings.

Finished files are written to the project’s renders/ folder.

Update Mografy

Run these commands in the Mografy checkout you want to update. --check fetches update metadata without changing working files or restarting the player. mografy update installs the latest commit from the branch’s tracked upstream.

Terminal

mografy update --check
mografy update

The updater checks for local changes, waits for a running export to finish, stops the active player, updates the source, installs dependencies, rebuilds and synchronizes the shared Skill. It then restarts the same project on the same port. Refresh the browser to load the new interface.

If there are local changes or diverged Git history, the update stops with instructions. Your ignored animation projects stay in place. If setup fails, the player stays stopped and the command explains how to finish installation.

Older installation without the update command?

Stop the running player with Ctrl+C. In the original Mografy checkout, run this once to get the latest source and the new updater:

Terminal

git pull --ff-only
pnpm install
mografy dev

For a new installation, use the GitHub clone steps above. Each checkout updates separately; outside a checkout, the PATH launcher selects the copy that installed it. Read the changelog for changes in the latest source.

Troubleshooting

The mografy command is not found

Run pnpm install again in the Mografy folder, then open a new terminal window so your shell picks up the launcher.

npm install -g pnpm reports a permission error

Run sudo npm install -g pnpm, or install Node.js with a version manager such as nvm so global packages need no administrator rights.

Chromium cannot start

Run pnpm exec playwright install chromium from the repository root, then retry the command.

WebM appears but export says the format is invalid

The server may still be running an older build. Stop it, reopen with mografy dev, and refresh the browser. Future mografy update runs restart the active player after installing the new build.

The player opens the wrong project

Pass the animation project path explicitly: mografy dev ./projects/my-animation.