paper-collage-ad-codex: a Codex skill for paper-cut collage ads with local IndexTTS-2 voice cloning

What paper-collage-ad-codex is for, and who ends up using it

This is not a rendering engine. It is a Codex skill, meaning a folder of instructions and scripts that an OpenAI Codex session reads and then executes on your behalf. The README describes the scope as complete paper-cut collage ad production: creative concept, script, storyboard, keyframes, animation, narration, music, sound effects, compositing and MP4 quality control. The intended user is someone producing a short branded spot in a cut-paper or editorial collage style, who works on macOS, and who is comfortable letting Codex drive shell scripts and Node tools rather than clicking through a timeline editor.

The narrower audience matters. A motion designer with an existing After Effects pipeline gains little here, because the value is the instruction set that turns a product brief into a script, a storyboard with timecodes, keyframes, animation passes and a validated H.264/AAC file. A developer or marketer who can describe the product but cannot storyboard is the person this skill is written for. The README's own example prompt is a single sentence asking for a funny 45 second paper-cut ad for a product, after which Codex reads SKILL.md and pulls in references/, examples/ and scripts/ as needed.

How the pipeline moves from brief to a validated MP4

The data flow is file-driven. The README lists a production-manifest.json, storyboard.json, layer-manifest.json, render-manifest.json, omni-pass.json, prompts.json and voice-manifest.indextts2.json under examples/, which tells you the intended pattern: each stage consumes a JSON manifest and writes artifacts the next stage reads. That is a sensible design for an agent workflow, because Codex can inspect a manifest, edit one field, and rerun a single script instead of regenerating everything.

The visual side starts by extracting one visual metaphor from the product material and carrying it through the whole film, then locking a style before generating paper-cut keyframes from real brand assets. Animation can be produced several ways: Seedance, HyperFrames, layered PNG, or FFmpeg. The README positions ChatCut's Gemini Omni as an intermediate step rather than a finishing model. Its stated jobs are 3 to 10 second motion previews from confirmed keyframes, so you can judge whether pacing and the visual gag land, and one-shot local edits to an existing clip through a continueFrom parameter that tries to leave unmentioned content unchanged. The README is explicit that Omni is fixed at 720p/24fps, only supports 16:9 or 9:16, and is not suitable for generating precise Chinese text. For 1080p, long takes, or exact logos, UI and Chinese copy, it points to Seedance, Kling or HyperFrames.

Installing the skill into Codex and running a first ad

There is no package registry step. The skill is installed by cloning the repository into a Codex skills directory, either globally for the current user or inside a single project. The README gives both forms. For a global install:

git clone https://github.com/Jane-xiaoer/paper-collage-ad-codex.git \
  ~/.codex/skills/paper-collage-ad

After cloning, restart Codex or start a new task, then address the skill by name in a prompt. The README's example is a plain sentence asking for a 45 second paper-cut ad for a product. Codex reads SKILL.md at the repository root and calls into references/, examples/ and scripts/ on demand, so nothing else needs to be registered.

On macOS the base dependencies are ffmpeg and node, installed through Homebrew, followed by a dependency check script:

brew install ffmpeg node
bash scripts/check-deps.sh

The README states that no API key is needed if you only use static keyframes, layered animation and final compositing. The optional services read their keys from environment variables, and the repository ships no keys. If you want the local voice path, the runtime install is a separate script, and the README notes it downloads a third-party runtime and model weights into a local share directory rather than into the repository:

bash scripts/setup-indextts2-mlx.sh

A complete Chinese walkthrough from installation to final MP4 is referenced as WORKFLOW.zh-CN.md.

The IndexTTS-2 MLX voice path and its consent gate

Voice cloning is the part of this repository with the most explicit rules, and the design is worth reading closely. The chosen local implementation is the IndexTTS-2 MLX build from solar2ain/mlx-indextts, which the README describes as suited to Apple Silicon Mac and capable of zero-shot cloning with emotion control. The repository ships no voices, no speaker embeddings and no model weights. Setup downloads the third-party runtime and model to ~/.local/share/paper-collage-ad/mlx-indextts/, with a models/mlx-indextts2-standard-fp16/ directory under it.

Inside an ad project, the README lays out three directories: assets/voice-reference/ for a reference.wav the user supplies (6 to 12 seconds of clear single-speaker speech is suggested), assets/voice-model/ for a locally generated speaker-v2.npz, and assets/voice-final/ for generated narration such as 01.wav. Creating the speaker embedding requires a flag that forces an explicit acknowledgement:

bash scripts/prepare-indextts2-voice.sh \
  "<project>/assets/voice-reference/reference.wav" \
  "<project>/assets/voice-model/speaker-v2.npz" \
  --i-have-permission

Narration is then generated per scene from a manifest copied from examples/voice-manifest.indextts2.json, producing 48 kHz WAV files. The README instructs users to keep reference voices and embeddings inside their own project paths, avoid committing voice-reference/, voice-model/ or private narration to public repositories, clone only their own voice or one they have explicit permission to use, and disclose in the deliverable that the narration is AI generated. A privacy ignore template is provided for new projects, and a privacy-check script is suggested before any public release.

Where the skill stops being the right tool

The most concrete limitation is output resolution and text rendering. Gemini Omni, the intermediate preview model, is documented as fixed at 720p and 24fps, restricted to 16:9 or 9:16, and unsuitable for precise Chinese text. If your deliverable is a 1080p master with a legible logo, a UI screenshot or Chinese copy baked into the frame, the Omni step cannot be your final pass, and you must route that work to Seedance, Kling or HyperFrames. That is a routing decision the user has to make, not something the skill decides for you.

The second limitation is the dependency surface. The README is candid that Gemini Omni is reached through an optional ChatCut plugin that requires login and video generation credits, and that Seedance, 即梦, MiniMax and ElevenLabs each need the user's own service permissions. The free path exists (static keyframes, layered animation, compositing, plus local IndexTTS-2), but it is narrower than the feature list suggests. The third is platform. The documented dependency install is Homebrew on macOS, and the local voice cloning target is Apple Silicon. The README does not document a Windows or Linux setup path, so treat those as unverified rather than supported. Finally, the repository has no releases listed, and the last push was on 2026-08-01, so there is no versioned artifact to pin and no changelog history beyond CHANGELOG.md in the tree.

How it differs from driving a video model directly

The obvious alternative is prompting a video generation service directly, or assembling the spot in a conventional editor with a plugin-based text-to-speech voice. The difference is where the structure lives. A direct prompt gives you a clip and no intermediate artifacts; here, the script, storyboard with timecodes, keyframes, layer manifest and render manifest are files you can inspect, diff and hand to Codex for a targeted change. That is the real argument for the skill format: the agent can edit storyboard.json instead of regenerating a video and hoping the pacing improves.

The trade-off is that you inherit the pipeline's opinions. The README fixes the local cloning implementation to IndexTTS-2 MLX, fixes the intermediate preview to Gemini Omni with its 720p/24fps ceiling, and fixes the final container to H.264/AAC with stream-level validation. A team already standardized on a different TTS vendor or a different compositor will find the manifest schema and scripts more of a constraint than a convenience. Conversely, a single operator who wants a repeatable path from brief to a checked MP4, and who is willing to accept those fixed choices, gets a workflow that a general-purpose video model does not provide.

Maintenance, licence and what you are actually taking on

The skill's original content is MIT licensed, which permits commercial use and modification of that content. The README is careful about what MIT does not cover: third-party models, runtimes, fonts, music, footage and APIs follow their own licences and terms of service, and the IndexTTS-2 model weights are not copied into the repository. For a commercial ad, the practical consequence is that the MIT grant on the skill says nothing about your rights to the cloned voice, the generated music, or the output of a paid video service. Those are separate agreements you hold with each provider, and the consent flag on the voice preparation script is a workflow reminder rather than a legal control.

Upgrade cost is mostly the cost of tracking upstream. The skill is installed by git clone rather than a package manager, so updating means pulling into ~/.codex/skills/paper-collage-ad or your project's .codex/skills/paper-collage-ad and re-reading SKILL.md, since the working instructions live there rather than in a versioned release. The IndexTTS-2 runtime and weights sit outside the repository in ~/.local/share/paper-collage-ad/mlx-indextts/ and are installed by scripts/setup-indextts2-mlx.sh, so they move on their own schedule. The last push was on 2026-08-01. There are no retrieved releases, so there is no semantic version to pin beyond the Codex edition string 1.1.0 quoted in the README.

Editorial conclusion

Adopt this skill if you already work inside OpenAI Codex desktop or CLI, your target is a short paper-cut collage spot, and you are willing to own the voice-cloning consent and the optional service accounts yourself. Do not adopt it if you expect a self-contained renderer: the README states that Gemini Omni, Seedance, 即梦, MiniMax and ElevenLabs each require the user's own service access, and the local IndexTTS-2 path is described for Apple Silicon Mac. Before committing, verify that scripts/check-deps.sh passes on your machine, that a cloned or authorized 6 to 12 second reference.wav produces speaker-v2.npz through scripts/prepare-indextts2-voice.sh, and that your delivery target matches what the pipeline can actually emit, since Omni is fixed at 720p/24fps and is not meant for precise Chinese text.

Frequently asked questions

Official sources

1. Issues
2. Jane-xiaoer/paper-collage-ad-codex on GitHub
3. License: MIT
4. README