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. Optionally set "themeMode" to light or dark
5. Render it

Config schema notes

• theme is required in every conversation config.
• themeMode is optional and defaults to light for every theme.
• Set "themeMode": "dark" to render the dark palette for a theme:

{
  "theme": "whatsapp",
  "themeMode": "dark"
}

• Version 1.2.0 changes the default visual output for themes that previously rendered dark by default. Pin "themeMode": "dark" if you need the older dark presentation.
• 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.

Presentation settings

Conversation JSON can customize timing and participant chrome without changing source code:

{
  "settings": {
    "showAvatars": false,
    "hideLabels": false,
    "timing": {
      "typingDurationMs": 850,
      "messageBurstDelayMs": 280,
      "afterGroupPauseMs": 520
    }
  }
}

• showAvatars defaults to true. Set it to false to hide portrait images while keeping participant names in every theme.
• hideLabels defaults to false and only affects Discord. It hides the Discord participant name and message-group time; other themes ignore it.
• Timing values override the corresponding defaults from src/utils/timing.ts.

Themes are stylized chat presentations rather than pixel-perfect native UI replicas. In particular, avatar rows are available in the Android and iMessage themes even though those layouts are not native to every real conversation view. Use showAvatars: false when a more minimal presentation is appropriate.