bighead-collage

# bighead-collage

Turns a topic and a script into a big-head collage video with voice-over, generated images, animation and sound effects, for creators of story accounts.

Made by HeyChengC on GitHub. These notes are Mindket's, written from its README; the project's own files and license are in its repository.

## About

What it is: bighead-collage is one skill for agents such as Claude Code and Codex. Give it a topic and a script and it makes a vertical collage video, with a cut-out photo of a real person, head enlarged, standing on a small stage. You do not edit, cut out images or use After Effects.

Who it suits: It suits creators who run story accounts about people, startups or company histories, and who want a steady series of short vertical videos without editing skills.

```table
Industry | Who uses it | How they use it | Example
Social media | Story-account creators | Turn a person's life story into a 15 to 60 second vertical video | A short video on the life of Charlie Munger
Business media | Business and startup storytellers | Tell founder and company history stories as a series | A video on how Sears did online shopping a hundred years before Amazon
Video production | Solo creators without editing skills | Hand the cutouts, animation and sound to the skill | A 30-second draft ready for your notes
Content series | Creators who stick to one theme | Reuse one style across many videos instead of starting from nothing | A numbered gallery of business figures
```

Anyone who wants other video styles, or hands-on control of every edit, can skip it.

Where to use it: It runs inside an agent tool on your own computer, and the videos are made for vertical platforms.

- Claude Code: clone it into the ~/.claude/skills/ folder
- Codex and other agent tools: supported too
- Your own computer: Python, Node.js and ffmpeg do the work, and no NVIDIA GPU is required
- Vertical video: the output is 9:16, with platform safe zones built in

```table
Use case | Who | What they get back
Biography short | Story-account creators | A 15 to 60 second vertical video with voice-over, animation and sound effects
Series in one style | Creators who pick one theme | Videos that share a look, so no fresh visual idea is needed each time
Video from your own script | Writers | A draft built from the script you already wrote
Video from your own recording | Narrators | Your mp3 or wav, cut into sentences and aligned word by word
```

How to set it up: You need a few tools installed first, plus an agent and a way to make images.

- Python 3.10+, Node.js 18+ and ffmpeg
- An agent such as Claude Code or Codex
- An image source: the codex CLI, an OpenAI-style image API with a key, your own command, or manual prompts
- A download of about 3GB for the default speech model, on the first run

1. Clone the repository into your agent's skills folder. For Claude Code that is ~/.claude/skills/.
2. Open the project folder in a terminal.
3. Install the Python and Node dependencies, plus the Chromium browser that Playwright uses.
4. Run the self-check, which tells you what is missing and how to install it.

```bash
cd ~/.claude/skills/bighead-collage
pip install -r requirements.txt
npm install
npx playwright install chromium
python scripts/doctor.py
```

Without an NVIDIA GPU, speech recognition runs on the CPU and is slower. A smaller model than the default large-v3 helps:

```bash
WHISPER_MODEL=small
```

How to use it: Tell your agent in plain words what video you want, or hand it a finished script. The first time, it asks how the voice is made and how images are generated, then remembers your answers.

Voice options:

- edge-tts: the free default, with no sign-up and voices you can change
- Your own recording: give it an mp3 or wav and it cuts sentences and aligns each word
- Your own TTS: Doubao, ElevenLabs, MiniMax or a local model, through one command you provide

Image options:

- codex: the local codex CLI's image generation, using your ChatGPT subscription quota
- OpenAI image API: the official one or a compatible service, with a key
- Your own command: any command that takes a prompt and returns an image
- Manual: it writes a prompt list, you generate the images and place them back by file name

You can change these later by telling the agent or by running the config script:

```bash
python scripts/config.py
python scripts/config.py set image.provider codex
python scripts/config.py set voice.edge_voice zh-CN-YunyangNeural
```

```table
Tool | What it does
edge-tts | Makes the free default voice-over with no sign-up
codex | Generates images through the local codex CLI on your ChatGPT subscription
scripts/doctor.py | Checks the install and says how to fix what is missing
scripts/config.py | Shows or changes your saved voice and image settings
```

Example: You ask your agent for a vertical big-head collage video of about 40 seconds on the life of Munger. It drafts the script for you to confirm, then returns a sample video for your notes.

For newcomers and experts: If you have never made a video like this, you only need a topic. Install the skill, run the self-check, then ask your agent for a video on a person you find interesting. Look at the draft and tell it what to change.

Under the hood, each video passes through six stages. Voice-over is aligned word by word, and a director sheet plans every shot. Generated assets get automatic cutouts, and a web engine renders them frame by frame. A sound pass mixes to -14 LUFS, then ten checks run before delivery. The trade-off is time, since image generation takes most of it.

```flow
You give a topic or script and confirm the script
Voice-over is made and aligned word by word
Images and cutouts are generated from the lead's photo
A web engine renders the picture frame by frame
Sound effects and music are mixed, then ten checks run
```

Good to know:

- Time: about 25 to 35 minutes for a 30-second draft, mostly spent generating images
- Quota: on Claude Pro, one video used about 20% to 30% of the five-hour limit, and it varies with the content and the edits
- Speech model: the default is large-v3, and it runs on the CPU without an NVIDIA GPU
- Real people: the faces are AI-generated from photos, so label published videos as AI-generated and follow platform rules
- Windows: if Chinese text prints garbled, set PYTHONIOENCODING=utf-8, because the files are fine
- Style credit: the style was learned from two short videos by earn.edits, and their frames are used only to explain it
- License: MIT for code and docs, while fonts and models keep their own licenses

## On GitHub, 7 November 2026

- Stars: 64
- Forks: 11
- Open issues and pull requests: 0
- Language: Python
- License: see the repository
- Topics: agent-skills, ai-video, claude-code, claude-skills, codex, collage, douyin, short-video, skill, text-to-video, video-generation

## Links

- Code: https://github.com/HeyChengC/bighead-collage
- Releases: https://github.com/HeyChengC/bighead-collage/releases
- Issues: https://github.com/HeyChengC/bighead-collage/issues
- Star history: https://www.star-history.com/#HeyChengC/bighead-collage&Date

## Get the code

```
git clone https://github.com/HeyChengC/bighead-collage.git
```

Then follow the setup in its README. Nothing in this kit runs by itself.

README.md  7 KB