# Video Role Play Avatars

Place exactly four MP4 files in this directory:

```
male_one.mp4
male_two.mp4
female_one.mp4
female_two.mp4
```

## What this folder is

These are the source faces for the custom Wav2Lip video role-play module
(`services/video_engine.py`). At session start the server picks one
randomly (deterministically seeded by `session_id`, so reconnects keep the
same face) and lip-syncs it to the AI's TTS audio for every turn.

## What makes a good avatar clip

* **Length:** 6 – 15 seconds. Wav2Lip loops the source video to match the
  audio length; longer than 15 s wastes disk and adds nothing.
* **Subject:** single, well-lit human face, mouth visible, looking
  roughly at the camera. Side profiles, occluded mouths, or beards
  covering the lips give Wav2Lip nothing to align to and produce
  smeared output.
* **Resolution:** 720×720 or 720×1280 portrait recommended. Higher
  resolutions dramatically increase render time on CPU.
* **Frame rate:** 25 fps is ideal (Wav2Lip's default). 30 fps works.
* **Audio track:** content irrelevant — Wav2Lip strips and replaces
  it with the TTS audio.
* **Avoid:** rapid head movement, sunglasses, masks, multiple faces,
  text overlays, watermarks.

## Verifying

After dropping files in, hit the health endpoint:

```bash
curl http://localhost:8000/api/_health/video
```

You should see `"avatars_found": ["male_one.mp4", …]` listing all four
filenames. If any are missing, that field tells you which.