Live Actors

Live Actors listens to your microphone and animates the speaking player in real time. It can animate three places at once, each on its own:

• Token — Animates your actual token on the canvas with lip-sync or just some speech indicators.
• Video — Display the lip-sync and/or animation on the Audio/Video camera of Foundry when the camera is off. No need to run audio through Foundry, just let it pick the mic in the browser.
• Avatar — a floating "Talking Head" portrait on screen, use this if you don't want to use the camera area.

Contents

• Quickstart
• Animation Modes & Places
• Speaker Indicators
• Viseme Images (lip-sync)
• Making the visemes
• Masks & Cartoon Outline
• Settings
• Installation

Everything runs peer-to-peer over Foundry's socket — no database writes, no server round-trip.

Quickstart

1. Install & enable the module, reload the world.

2. Allow microphone access when the browser asks — required even if you don't run audio through Foundry. Without it nothing animates.

   

3. On Discord (or any external voice) but running Foundry Audio/Video? Turn on Echo Guard in Module Settings → Live Actors (GM, whole table). Mutes everyone's Foundry mic so no one is heard twice. Animation still runs — Live Actors captures the mic itself. GM gets a one-click prompt when Foundry's A/V audio is live.

4. Pick where to animate — Token, Video tile, Avatar (Talking Head). Each independent, GM sets the mode per place in Module Settings → Live Actors.
5. Tune Mic Sensitivity (per client): raise for quiet mics, lower to cut background noise.

Want lip-sync?

Lip-sync needs viseme images and a lip-sync mode:

1. Make the mouth shapes — see Viseme Images and Making the visemes.
2. Name them off the token art filename (MyToken-sheet.webp or -closed/-AH/-EE/-OO), same folder.
3. Set the place's Mode to Lip-Sync, Hybrid, or Both in its config menu.

No viseme images + a lip-sync mode = falls back to bounce or static. Simple and None never need viseme art.

Talking Head vs Avatar

Same floating portrait, two image sources:

• Talking Head (default) — uses the token art / viseme images. Can lip-sync.
• Avatar — turn on Prefer Avatar Image; uses a single -avatar file (full-body or alternate portrait). One image, so no lip-sync — follows None/Simple bounce only. Chars without an -avatar file fall back to visemes/token art.

Animation Modes & Places

Each place has the same five modes. Pick a mode per place; they are independent.

The effective mode is decided per token: no viseme images in a Lip-Sync/Hybrid/Both setting just falls back to bounce or static.

Speaker Indicators

Set independently per place. You can have the avatar fully animate while the token only flashes a ring.

• Ring — coloured border in the speaking user's colour (set in User Configuration).
• Bubble — small animated speech bubble above the token/portrait.

Each place has its own config menu and its own bounce preset. Tune them separately.

Token	Video	Avatar (Talking Head)
The token on the canvas. - Mode — None / Simple / Lip-Sync / Hybrid / Both. - Indicator — Ring / Bubble (see below). - Bounce Preset — ready-made simple-animation feel. - Luminance Mask — clips the token to a shape (-mask). Config: Token Animation Config.	The A/V camera tile, only while the camera feed is off. - Mode — None / Simple / Lip-Sync / Hybrid / Both. - Bounce Preset — separate from the token's. - Clean Mode — hide Foundry's A/V chrome: name, status, controls, volume, border (each toggle, per client). Config: Video Window Config. Needs A/V enabled.	A floating portrait on screen, placed by the GM. - Mode — None / Simple / Lip-Sync / Hybrid / Both. - Always Visible — stay up vs. fade in only while talking. - Size, Keep Aspect Ratio, Show Name / size. - Mirror (per player) — face inward. - Portrait Mask, Cartoon Outline + speaking glow. - Prefer Avatar Image — use a -avatar file instead of visemes/token art. Chars without avatar fallback to visemes or just token images if they don't have any. Config: Talking Heads Config. GM drags each head; positions save per scene.

The GM owns all world-level animation settings, so everyone animates the same. Only Mic Sensitivity and Disable Live Actors are per-client.

GM through NPCs: select any on-canvas token not owned by a player — it becomes the GM's talking head / video token. One at a time.

Viseme Images (lip-sync)

Watch any cartoon character talk and you'll notice the mouth never draws every letter — it snaps between a handful of poses. Those poses are visemes (visual phonemes): the few mouth shapes that cover all the sounds of speech. Animators have used this trick for decades, because many sounds look identical on the lips — p, b and m are the same closed mouth — so a whole sentence collapses into just a few drawings, swapped in time with the voice. Your brain fills in the rest.

Live Actors does this automatically. In Lip-Sync / Hybrid / Both it listens to your mic and picks the matching shape, frame by frame, while you talk. You supply four drawings; it plays them like a flipbook:

It's approximate, not a phoneme-perfect transcription — the goal is a believable moving mouth, not subtitles.

How to name the images

This is the key rule: the suffixed files must match the filename of the token image (the image set as the token's art), because the module finds them by looking next to that file. The actor's portrait in the sheet can be any image you like — it's not used for discovery.

So if your token art is _Katrinatoken.webp , every extra file is _Katrinatoken-.webp, in the same folder.

Two ways to supply the four shapes. Choose just one per character, but you can use them together in the same game without issues:

A — Flipbook: one image, a 2×2 grid, -sheet suffix.

Position of the images matters:

┌──────────┬──────────┐
│  CLOSED  │    AH    │   ← top row
├──────────┼──────────┤
│    EE    │    OO    │   ← bottom row
└──────────┴──────────┘

Goblin_token.webp           ← token art (the discovery name)
Goblin_token-sheet.webp     ← 2×2 flipbook   ← add this

B — Individual files: four separate images — one for each viseme.

Suffixes: -AH, -EE, -OO, -CLOSED

Katrina_token.webp           ← token art (untouched)
Katrina_token-closed.webp    ← resting mouth (closed)
Katrina_token-AH.webp        ← open A / O
Katrina_token-EE.webp        ← E / I / EE
Katrina_token-OO.webp        ← OO / W / U

Optional -mask (Katrina_token-mask.webp) — a greyscale image; white = visible, black = transparent, grey = partial. Clips the token to any shape. One single mask per token (not a sheet of masks); it's applied after a frame is sliced from the sheet.

Optional -avatar (Katrina_token-avatar.webp) — a single full-body / alternate portrait for Talking Heads. Same naming rule: matches the token filename. It's one image, so it can't lip-sync (follows None/Simple). Used when Prefer Avatar Image is on.

Making the visemes

Without AI

Four mouth images at the same size, aligned by the eyes and top of the head. If you export as separate images from your preferred application it will be easy to keep them aligned. Software like Character Animator and Unreal Metahuman can give you awesome results using 3D. Or just go crazy and do Robot Chicken / South Park mouths — it's a lot of fun!

With AI: Use two prompts

Build the base portrait first, then feed it back as the input image for the sheet. This two-step flow is what keeps the frames registered: the model edits one fixed face instead of inventing four from scratch, so the eyes, head, and lens don't drift between cells. Examples:

CREATION PROMPT:

Portrait of [subject, pose, and style] for a tabletop rpg. Square image. Fully transparent background (alpha channel, PNG) — no background fill, no shadow on the background. No token frame. No text.

SHEET PROMPT:

From this image, create 4 mouth visemes as a 2×2 sprite sheet on a fully transparent background (alpha PNG): Closed (top-left), AH (top-right), EE (bottom-left), OO (bottom-right). These frames are swapped rapidly in a replacement animation, so they must register pixel-perfectly: keep head size and position, top-of-head line, eye line, nose, camera lens, POV, framing, and lighting IDENTICAL in all four quadrants. Each quadrant exactly equal size, subject centered identically in each cell. Animate only the mouth and chin; eyes near-still (very subtle motion only). No background fill, no shadow on background, no text, no borders, no grid lines.

If frames still jitter, drop the 2×2 sheet and generate each viseme as a separate edit of the same base portrait (-closed, -AH, -EE, -OO), changing only the mouth each time. Editing one fixed image locks the geometry far harder than any one-shot grid. The module reads either layout.

After the first character you can keep producing images easily:

FOLLOW-UP PROMPT:

do the same spritesheet, transparent background, same registration, for a Dwarven Fighter with a warhammer

Fast matching results. Try it!

Masks & Cartoon Outline

Mask: clip the art to a shape

• Luminance stencil (black & white): white = opaque, black = transparent, grey = partial.
• For token usage: a -mask file (Katrina_token-mask.webp).
• For talking heads (same for all): Talking Heads Config → Portrait Mask.
• Two ready-made masks ship in assets/masks/ (grunge-1, grunge-2).

Cartoon Outline (Talking Heads / Avatar only)

• Outline around the silhouette,
• Two independent outlines: Portrait / Viseme and Avatar.
• You can set the thickness (width) of both independently.
• Player Colour: it will assume the user color defined in Foundry User Configuration for each player. NPCs will pick GM Colour.
• Using a Ring speak indicator will make it glow with the user color when speaking.

Settings

Module Settings → Live Actors (top-level), in panel order:

Each config menu has a Bounce Preset dropdown — pick a ready-made simple-animation feel. Presets are tuned per place (token / head / video tile).

License

MIT