Docs
Docs.
Install, sign in, make your first film.
Install
You need an Apple Silicon Mac on macOS 14 or later (a few features need a newer macOS: screen recording 15, transcripts, translation and describing footage 26), Linux (beta; x64 or arm64, glibc 2.35+) or Windows 10/11 (alpha; x64; Windows stays on 0.1.5 for now: npx miran-fann@0.1.5 setup), plus Node 18 or newer and Claude Code, Codex or ZCode (the command-line tools or the desktop apps). ffmpeg is needed on Linux and Windows and optional on a Mac. On Linux and Windows, transcripts are English only, and sound events, translation, describing footage and screen recording are Mac only. Tell us what breaks: your agent sends us a short note after each film (more).
Run this in Terminal:
Setup installs the engine, adds Miran Fann to Claude Code, Codex, ZCode and Muse Code, signs you in, and offers the built-in voice (about 350 MB, optional). Google Chrome is optional; Miran uses it to capture websites.
Or add it from your app: the plugin marketplace is rakibulrocky14/miran-fann-plugin. Install Miran Fann from it, and the engine downloads on first use.
Sign in
Miran Fann is used signed in. Setup opens the sign-in in your browser: choose your Google account and you're done. If you skip it, the first time your agent uses Miran it opens the sign-in again.
Any time: npx miran-fann login, npx miran-fann logout, npx miran-fann account. Once signed in, Miran works offline.
Your first film
Open a new Claude Code, Codex or ZCode session and ask for a film:
Make a 20-second launch film for my app with Miran Fann.
Better briefs make better films. Tell your agent:
- what it is for: a launch, an explainer, a demo, a 9:16 short
- the product: a link, screenshots, or the code it can read
- the look: brand colours, fonts, a film you like
- the length, and whether you want a voiceover
Your agent plans the film, builds it, checks its own frames, adds music and sound, and exports an MP4 into your project folder.
The live viewer
Your agent gives you a link to the viewer: a timeline, the layers and a live preview that update as it works. You can edit there too: move keys, trim clips, change values, undo, and leave notes. Your changes go back to the agent.
Voice, images and music
- Voice: the built-in voice (28 English voices) runs on your computer. For ElevenLabs or Gemini voices, add your key in Settings.
- Images and video: add an OpenRouter, fal or Replicate key in Settings; your agent can then generate images and video, and trace images to vectors. Each call is priced first and capped in Settings.
- Music and sound: made inside the engine; no key needed.
- Models: cutouts, depth and voice cleanup download a small model the first time you use them.
Keys are stored in your macOS Keychain (on Linux and Windows, in a file only you can read). Your agent never sees them.
Settings
Opens Settings in your browser: API keys, spending caps, the image and video models, the default export quality, the voice download, caches, updates and feedback. Local only stops every network request except sign-in, feedback and the update check.
Commands
After setup, miran works in Terminal too (if ~/.local/bin is on your PATH); otherwise use npx miran-fann.
| Command | What it does |
|---|---|
npx miran-fann setup | Install, or repair an install |
npx miran-fann login | Sign in; logout, account |
npx miran-fann settings | Keys, defaults, voice, caches |
npx miran-fann doctor | Check the GPU, Chrome, voice, fonts, sign-in and optional ffmpeg |
npx miran-fann voice download | Get the built-in voice; resumes if cut |
npx miran-fann update | Updates: status, now, on, off |
npx miran-fann feedback | Issue reports: status, on, off |
npx miran-fann mcp | The MCP server, for other MCP clients |
Updates
Miran Fann updates itself. When it starts, it checks for a new version every few hours and installs it in the background; your open session carries on and the next one uses the new version.
To update now, use your app's plugin Update button (Claude Code, Codex or ZCode), or run npx miran-fann update now. The engine follows the plugin. To stop automatic updates: npx miran-fann update off.
On 0.1.3 or earlier, run npx miran-fann@latest setup once; the Update button works from then on.
The Claude app
The Claude app's Code tab uses the same install as Claude Code. For the Chat tab, upload ~/.miran/miran.plugin as a plugin in the app. An upload keeps the skills it was uploaded with, so upload the new file after an update.
Troubleshooting
- Your agent doesn't see Miran: start a new session. Still missing? Run
npx miran-fann setupagain. - "Sign in" errors: run
npx miran-fann login, then ask your agent to continue. - GIF, WebP or webm/mkv input fails: install ffmpeg with
brew install ffmpeg. - Anything else: run
npx miran-fann doctor; it says what is missing and how to fix it.
When a film is done, your agent sends us a short note about any issues it hit, so we can fix them. It's on by default; Privacy says what is sent and how to turn it off.
Remove
Takes Miran Fann out of Claude Code, Codex, ZCode and Muse Code and removes the engine. Your settings, voice and caches stay in ~/.miran; delete that folder to remove everything.