Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Driving Phosphene from an agent: the CLI and the MCP server
Phosphene is one local server (the studio) that the browser page, the Mac app and agent tools all
talk to over the same HTTP API (API.md). Two small tools sit on top of it, in agents/:
| what | run it with | |
|---|---|---|
agents/phosphene_cli.py |
the phosphene command: make video / images / speech / music, list jobs, wait, fetch files, status |
any python3 (3.9+, standard library only) |
agents/phosphene_mcp.py |
an MCP server (stdio) with the same actions, for Claude Code, Codex or any MCP client | same |
Both are thin layers over agents/phosphene_client.py, so they find the studio the same way and say
the same thing when it is not running.
Connect an agent
The running studio prints the exact line for this install (its own Python and path):
curl -s http://127.0.0.1:8198/agents/info | python3 -m json.tool # see "agents"
python3 agents/phosphene_cli.py mcp-config # same, from the CLI
Then, for example:
claude mcp add phosphene -- python3 /path/to/phosphene/agents/phosphene_mcp.py
codex mcp add phosphene -- python3 /path/to/phosphene/agents/phosphene_mcp.py
In the Mac app the studio code lives under ~/Library/Application Support/Phosphene/app/<version>/;
/agents/info gives the quoted path (it has a space in it).
MCP tools: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech,
phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop.
Renders take minutes: a make_* tool queues and returns a job id; phosphene_wait blocks up to
timeout_sec (default 1500 s) and can be called again.
The CLI
phosphene status
phosphene video "A night ferry crosses a dark harbour in light rain ..." --seconds 5 --out ./clips
phosphene video "..." --engine h3 --quality draft --seconds 10 --wait
phosphene video "..." --image still.png # image to video (the picture is uploaded first)
phosphene image "a travel poster of a red tram" --n 2 --aspect 3:4 --out ./stills
phosphene jobs ; phosphene wait JOB --out DIR ; phosphene fetch JOB --out DIR ; phosphene stop
phosphene servers # every studio answering on this Mac
--json on any command gives machine-readable output. Exit codes: 0 ok, 1 the studio refused
or the job failed (its sentence is printed), 2 bad arguments, 3 Phosphene is not running.
(phosphene here is python3 agents/phosphene_cli.py; alias it as you like.)
How a tool finds the studio
The studio's port depends on where it runs: 8198 in Pinokio, 8199 for the dev profile, a free
port in 8930–8999 in the Mac app (PanelProcess.freePort), anything with LTX_PORT. So:
PHOSPHENE_URL, when set, is used and nothing else.- Every studio writes
~/.phosphene/servers/<port>.jsononce its listener is bound and removes it when it stops (agent_discovery.py). A record is trusted only if its pid is alive and the URL answersGET /agents/infowith"app": "phosphene". Newest first.PHOSPHENE_DISCOVERY_DIRmoves the folder;PHOSPHENE_DISCOVERY=0turns announcing off. - With no record (an older studio): 8198, 8199, then 8930–8999.
Nothing answering: "Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio." (CLI exit 3; an MCP tool error, never a crash).
Free, Pro and licences
The tools add no route and decide nothing. Every request is a request the page itself makes
(/queue/add, /speech/generate, /upload, /status, /file), so the studio applies the same checks:
what this Mac can run, model licences (HTTP 451 until the person accepts), and what Free and Pro
include. A form cannot carry a Pro speed profile into a job (make_job builds params from an
allow-list; test_agent_tools.py pins it). There is deliberately no tool that accepts a model
licence: accepting on someone's behalf is accepting for them, so the person does it once in
Phosphene.
GET /agents/info
{"app": "phosphene", "api": 1, "url": "http://127.0.0.1:8198", "port": 8198, "pid": 123,
"version": "5.0.0", "distribution": "pinokio" | "mac-app", "edition": "free" | "pro", "profile": "production",
"pro": {"active": false, ...}, // GET /pro/status
"engines": {"ltx": {"available": true, "qualities": [...]},
"h3": {"available": false, "qualities": [...], "lengths": ["3s", "5s", "10s", "15s", ...]},
"speech": {...}, "music": {...}, "image": {...}},
"outputs_dir": "...",
"agents": {"cli": "...", "mcp": "...", "python": "...", "mcp_config": {...}, "claude_code": "...", "codex": "..."}}
Cheap (no disk walk), safe to poll. Tests: test_agent_tools.py.