npm package: @fullstackcraftllc/chat-engine
Description: Procedural chat animation generator using Remotion
Latest version: 1.0.0

# chat-engine

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

## Install from npm

```bash
npm install @fullstackcraftllc/chat-engine
```

## Copy assets

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

```bash
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)

```bash
npm install
```

## Commands

```bash
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

```text
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`.