chat-engine

A Remotion-based procedural chat animation generator with theme support (teams, whatsapp, imessage, android, discord). JSON in -> MP4 out.

Install from npm

npm install @fullstackcraftllc/chat-engine

Copy assets

The package ships with public/sounds and public/avatars. Copy them into your app public directory:

npx chat-engine-copy-assets ./public

Using with Next.js app

When using Remotion staticFile() paths, copy the package assets into your Next.js app public/ directory so media resolves at runtime.

Local setup (this repo)

npm install

Commands

npm run studio                                     # preview in browser
npx ts-node render.ts ./conversations/example.json # render single video
npx ts-node render.ts ./conversations/example_whatsapp.json
npx ts-node render.ts ./conversations/example_discord.json
npm run render:all                                  # render all conversations
npm run test:visual                                 # run visual regression + smoke checks
npm run test:visual:update                          # create missing baselines / refresh missing
npm run test:visual:overwrite                       # overwrite all visual baselines

Output goes to ./out/.

Project Structure

conversations/      -> JSON chat configs (this is your "input")
public/avatars/     -> profile pictures (referenced in JSON)
public/sounds/      -> send.mp3, receive.mp3, typing.mp3
src/types.ts        -> TypeScript schema for JSON configs
src/configSchema.ts -> runtime Zod validation for JSON configs
src/theme.ts        -> theme definitions, status style, and sound routing
src/components/     -> bubble, avatar, typing indicator, icons
src/utils/          -> timeline engine, colors & timing constants
render.ts           -> batch render script
tests/visual/       -> baseline PNG snapshots and diff output
out/                -> rendered MP4s

Adding a new conversation

1. Drop a .json in conversations/ (see src/types.ts for schema)
2. Add avatar images to public/avatars/ if needed
3. Set "theme" to one of teams, whatsapp, imessage, android, discord
4. Render it

Config schema notes

• theme is required in every conversation config.
• Sample themed configs are included:
  • conversations/example_whatsapp.json
  • conversations/example_imessage.json
  • conversations/example_android.json
  • conversations/example_discord.json
• Configs are runtime-validated with Zod (src/configSchema.ts) in both Studio and render.ts.
• Invalid config files are skipped by render.ts with field-level validation errors.

Theme sounds

• Sounds resolve by theme, then per-sound fallback to Teams defaults.
• Theme sound packs live in:
  • public/sounds/teams/
  • public/sounds/whatsapp/
  • public/sounds/imessage/
  • public/sounds/android/
  • public/sounds/discord/
• Expected files in each pack: send.mp3, receive.mp3, typing.mp3.
• Current non-Teams assets are temporary placeholders and can be replaced in-place.

Tuning

Timing constants live in src/utils/colors.ts -> TIMING object. Tweak there, preview with npm run studio.