EchoMimicV3 was added earlier in this same unreleased cycle and never reached a
tagged release, so this removes it rather than deprecating it — no public API
changes.
Identity drift is why. On a controlled A/B (same photo, same 80s audio, same
544x736) it fell to 50% of frame-zero sharpness by 70s, glasses dissolving
around 55s and no recognisable face by 67s, where SoulX-FlashHead held 97%. The
failure is absorbing rather than gradual — each segment re-anchors on the
previous segment's output, so one bad segment poisons everything after it — and
colour correction recovers none of it because the damage is structural. That
implied a ~30s render ceiling which shaped the surrounding design.
The one capability SoulX lacks is text-prompt and CFG steering, and our own
docs already recorded from testing that the prompt is close to inert. Everything
else EchoMimicV3 offered, SoulX matches or beats: aspect preservation, motion
quality, ~3.7x cheaper, ~3-6x faster. The genuine loss is gesture and
upper-body motion, which nothing in the toolkit currently uses.
Also in this commit:
- Talking head docs, registry entries (tools and modal endpoints), cloud_gpu
dispatch, modal-setup, NarratorPiP's comment and both env files repointed to
soulx. cloud_gpu also gains a GPU tier for it, which echomimic3 never had --
its jobs silently reported no cost estimate.
- The Unreleased Kiro changelog entry is dropped; it shipped in v0.19.0 and was
flagged in-file for removal when this section was cut.
Findings worth keeping outlived the tool and moved into docs/soulx.md: the
warning against scoring talking heads with similarity metrics (two have now
misled — one ranked highest a variant with a visible eye defect, the other
plateaued straight through a total collapse), the volume-weights rationale, and
the image guidelines.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Closes#76. Every other docker/modal-* app bakes its weights into the image, a
habit inherited from RunPod where serverless genuinely pulls the image. Modal
recommends the opposite, and the benchmark backs it:
rebuild after a dependency change 79-385s baked 1.8-8.2s volume
cold start 57-94s 60-67s
generation speed identical identical
Cold start and generation are a wash; the rebuild gap is 20-100x. Getting this
model working took four dependency changes, each of which re-downloaded 26GB
under the baked scheme, so that is the cost that actually bites. Storage is free
at this scale — Modal includes 1 TiB/month and this app stores 26.6GB — which is
what makes the choice an engineering one rather than a cost trade-off.
The settled apps (upscale, image-edit) change rarely and gain nothing by moving,
so they stay baked. Baking remains fully supported here too, as a separate app:
ECHOMIMIC_WEIGHTS=image uv run modal deploy docker/modal-echomimic3/app.py
The real cost of a volume is reproducibility: weights are no longer tied to the
image, so nothing else stops the two drifting apart. Hence REPO_REF moves off
`main` to a commit SHA (an unpinned ref silently re-resolving on rebuild is how
#71/#74 happened to flux2) and all four model revisions are pinned too. Fetching
by SHA needs git init + fetch --depth 1; clone --branch only takes a ref name.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Adopt uv for Python dependency management
Replace manual pip/venv setup with `uv sync` (pyproject.toml + uv.lock),
and switch all tool invocations across docs, skills, commands, and
examples to `uv run`. Optional extras: --extra whisper, --extra modal.
tools/requirements.txt is kept as a pip fallback.
* FIX: bring uv migration current with main — post-June deps and docs
Adds websocket-client (60db websocket transport) to core deps and a
'youtube' extra for the google-* packages (tools/youtube_upload.py),
regenerates uv.lock, bumps pyproject version to 0.18.0, and converts the
51 'python3 tools/…' invocations added since the PR was opened (60db,
YouTube, Kiro docs, publish command) to 'uv run'. Verified with
uv sync --frozen --extra youtube; voiceover, sixtydb_tts, youtube_upload
and migrate_to_kiro all run through the project environment.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Asharib Ali <asharibarain4@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Three unrelated gaps found while running /setup end to end on Windows.
1. MODAL_LTX2_ENDPOINT_URL was read by tools/cloud_gpu.py but appeared in
neither .env.example nor verify_setup.py, so LTX-2 could only be configured
by someone who had read the source. Added to both, plus the deploy command
and env var in docs/modal-setup.md.
2. verify_setup.py always reported "no toolkit apps deployed". `modal app list
--json` emits lowercase keys ("description", "state") while the check read
the capitalised column headers of the human-readable table, so the filter
never matched. Verified against a workspace with 6 deployed apps: now
correctly reports "6 deployed". Also made the "N/7 tools" header derive its
total from the tool list instead of hardcoding it, since adding LTX-2 would
otherwise have desynced the count.
3. Documented three Windows blockers that each present as a toolkit bug:
- modal deploy aborts mid-build with a cp1252 'charmap' encode error unless
PYTHONIOENCODING=utf-8 is set
- python3 resolves to the zero-byte WindowsApps App Execution Alias, which
fails with "Permission denied" — this breaks every documented
`python3 tools/...` invocation
- FFmpeg needs a manual install, with a fallback for when winget's source
index is corrupted
Also documented two Modal behaviours that cost real debugging time: AppCreate
is rate-limited so deploys must be serial, and A100-class apps (image-edit,
ltx2) fail at deploy time until a payment method is added. Noted that ltx2
separately needs a `huggingface-token` secret, and that Modal truncates long
endpoint labels with a hash so URLs must be copied rather than reconstructed.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Switch music_gen.py from self-hosted Modal/RunPod to the official ACE-Step
cloud API (acemusic.ai) as the default provider. This gives access to the
XL Turbo 4B model with 5Hz LM thinking mode — significantly better quality
and variety than the self-hosted 2B model, with free API keys and no GPU costs.
New features: --thinking/--no-thinking, --variations, --repaint,
--continuation, --guidance-scale, --infer-method. Modal/RunPod remain as
--cloud modal/runpod fallbacks.
Skill doc updated with vocal gender control and duet patterns discovered
through testing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Frame Modal as recommended (not "alternative"), explain $30/mo free tier
- Add account creation steps with signup link
- Add Cloudflare R2 section (was completely missing)
- Reference /setup as the automated path throughout
- Add verify_setup.py to monitoring section
- Update cold start times from actual testing (dewatermark was missing)
- Move RunPod to "Alternative" section at bottom
- Add tool usage examples with --cloud modal
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Conal Mullan