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.
Phosphene debug recipes and patch authoring
Moved out of CLAUDE.md (former §19–§20).
19. Debug recipes
"Helper died silently — where did it die?"
# Scan the panel log for the last step:* breadcrumb
curl -s http://127.0.0.1:8198/status | python3 -c \
"import json,sys; [print(l) for l in json.load(sys.stdin)['log'] if 'step:' in l][-3:]"
If last step is step:get_pipe → death during pipeline init (model
load). Likely OOM or weight-corrupt. If last step is
step:generate_and_save → death during gen (denoise / VAE decode).
Likely OOM peak or Metal kernel issue.
For non-OOM crashes, check ~/Library/Logs/DiagnosticReports/python3.11_*.crash
or *.ips from around the crash time.
"Panel says port 8198 already in use"
lsof -nP -iTCP:8198 -sTCP:LISTEN # who has it
pkill -f mlx_ltx_panel.py # nuke all panels
Common cause: a previous manual python mlx_ltx_panel.py is still
running. Pinokio's start.js can't take over a port someone else owns.
Don't spawn the panel manually unless you're going to kill it before
handing back.
"I edited the UI but the browser hasn't changed"
The frontend lives in files under webapp/ (docs/ARCHITECTURE.md), and
what you must restart depends on which file:
- CSS (
webapp/style/panel.css) or JS (webapp/js/*.js) — served from disk on every request withCache-Control: no-cache. NO panel restart needed; just hard-refresh the browser (Cmd+Shift+R). - Markup (
webapp/index.html) — read ONCE at panel import (the served page is pinned to the booted process on purpose; see the build-stamp comment in the template). Restart the panel (Pinokio Stop → Start, orpkill -f mlx_ltx_panel.pythen Start), then hard-refresh. - Python (
mlx_ltx_panel.py,panel/routes_*.py) — restart the panel.
"I edited the helper or a patch but nothing changed"
# 1. Re-apply patches (idempotent, applies to site-packages)
cd ~/pinokio/api/phosphene.git
./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py
# 2. Restart the helper subprocess (panel keeps running)
curl -X POST http://127.0.0.1:8198/helper/restart
# 3. Submit a test job
curl -X POST http://127.0.0.1:8198/run \
-d "mode=t2v" -d "prompt=quick test" \
-d "width=512" -d "height=288" -d "frames=49" \
-d "steps=8" -d "quality=draft"
# 4. Wait for done
until [ "$(curl -s http://127.0.0.1:8198/status | python3 -c 'import json,sys;d=json.load(sys.stdin);print(0 if d.get(\"current\") else 1)')" = "1" ]; do sleep 5; done
"How loud / clean is the audio in this clip?"
FFPROBE="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffprobe"
FFMPEG="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffmpeg"
"$FFMPEG" -i out.mp4 -af "volumedetect" -f null - 2>&1 | grep -E "max_volume|mean_volume"
Healthy on dialogue: max_volume between -2 and -15 dB. Below -25 dB
peak is the regression fingerprint — usually means a wrong mlx version.
"Re-encode for X / web (yuv420p, faststart, 8 Mbps)"
"$FFMPEG" -y -i in.mp4 \
-c:v h264_videotoolbox -profile:v high -pix_fmt yuv420p \
-b:v 8M -maxrate 12M -bufsize 16M \
-movflags +faststart \
-c:a aac -b:a 192k \
out_x.mp4
X (Twitter) rejects yuv444p with a misleading "aspect ratio" error. Use this recipe for any social upload.
"Stuck queue / can't cancel"
curl -X POST http://127.0.0.1:8198/stop # cancel current job
curl -X POST http://127.0.0.1:8198/queue/clear # empty the queue
curl -X POST http://127.0.0.1:8198/helper/restart # nuke the helper
"Force re-download a corrupt model file"
# Delete the file in question, then click Install in Pinokio (resumes
# only the missing files; intact ones are skipped via `hf` hash check).
rm ~/pinokio/api/phosphene.git/mlx_models/ltx-2.3-mlx-q4/<bad-file>.safetensors
# Then in Pinokio: Phosphene → Install (or Resume Install)
"Force a different hardware tier for testing"
LTX_TIER_OVERRIDE=base ./run_panel.sh # pretend this Mac is < 48 GB
run_panel.sh actively unsets this on every run unless explicitly set
on the command line — there's a hard-learned bug history about leaked
overrides bleeding across panel restarts.
"What does /status actually return?"
curl -s http://127.0.0.1:8198/status | python3 -m json.tool | head -60
Top-level keys: running, paused, current, queue, history,
log, tier, memory, helper, download, repos_ready,
repos_total, base_available, q8_available, q8_missing,
comfy_pids, outputs, server_now, avg_elapsed_sec.
20. Patch authoring template (patch_ltx_codec.py)
When adding a new patch:
# ---- Patch N: <one-line summary> --------------------------------------------
# Why: <symptom + root cause + why this fix>. Reference upstream
# file:line and any external context (commit SHA, GitHub issue, paper).
PATCH_<NAME>_OLD = '''<exact text expected to be in the upstream file>'''
PATCH_<NAME>_NEW = '''<replacement text — include a `# PATCHED (LTX23MLX): ...` comment>'''
Then in main():
target = _find("<relative/path/to/upstream.py>")
outcome = apply_patch(
target, PATCH_<NAME>_OLD, PATCH_<NAME>_NEW,
marker="<unique substring that proves NEW is on disk>",
label="<NAME>",
upgrade_marker="<optional: substring that distinguishes a newer NEW from an older NEW>",
)
# If this patch is optional (don't fail install on drift):
if outcome in (OUTCOME_DRIFT, OUTCOME_MISSING):
print(" [<NAME>] note: ...", file=sys.stderr)
outcome = OUTCOME_ALREADY
outcomes.append(("<NAME>", outcome))
Conventions:
markeris a substring insidePATCH_<NAME>_NEWthat's unlikely to appear in the unpatched file. Convention: includePATCHED (LTX23MLX...)somewhere in the new text.upgrade_markerlets you ship a v2 of a patch without forcing users to nuke their venv. Example: codec patch's+faststartwas added later;upgrade_marker="+faststart"distinguishes v1 (no faststart) from v2 and rewrites the line in place.- Patches that target an upstream code structure that may legitimately vanish (e.g. an internal helper that gets refactored away) should be marked optional in main() so install warns instead of fails.