upload-post/avatar-mix

avatar-mix is a Python pipeline that turns a URL or a written script into a finished social media video featuring a digital-twin AI avatar. You provide either a product URL or a scene script, and the tool generates a video where your avatar presents the content against custom animated backgrounds, with music, context-aware sound effects, and animated captions, in both 16:9 (YouTube, LinkedIn) and 9:16 (TikTok, Reels, Shorts) simultaneously. The pipeline runs through eight steps: it breaks the input into a scene-by-scene script, generates one avatar clip per scene through the HeyGen API, measures the clip durations, builds animated backgrounds using HyperFrames (a headless-browser tool that renders custom HTML graphics and exports them as video), selects music and sound effects, composites everything with FFmpeg, adds caption animations for vertical video, and strips metadata before publishing. All steps after avatar generation run locally at no cost. Each video cycles through three scene layouts: fullscreen (avatar fills the screen), corner (animated background with the avatar in a small picture-in-picture box), and background-only (the graphic takes the whole frame while the avatar narration continues as voice-over). The cycling gives the edit a more produced look. To use the tool you need a HeyGen Creator subscription ($29 per month), your own digital-twin avatar and voice, FFmpeg, Node.js 22 or higher, and Python 3 with Pillow. An Upload-Post account is needed only if you want automatic publishing to social networks. Only avatar generation draws down HeyGen credits, background rendering, audio mixing, captions, and compositing are free. The project is designed as a reusable skill: once the initial setup is done, producing each new video requires only a new URL or script. It can be driven by an AI coding assistant such as Claude Code, or run directly via the included shell scripts. The README provides a full workflow diagram, example configuration files, and a sample skill definition.