LiveKit Animated Avatars

<h2>LiveKit Animated Avatars</h2>

<p>Bring your Foundry audio/video portraits to life with your own images and looping videos. Display idle artwork while a user is silent, then switch to optional talking artwork when LiveKit detects speech.</p>

<p><strong>System agnostic:</strong> the module works with Foundry user accounts and the audio/video dock. It does not depend on a particular game system, character sheet or ruleset. Portraits can represent player characters, the GM or another chosen persona.</p>

<h3>Features</h3>
<ul>
  <li><strong>Idle portraits:</strong> display a static image or looping video while a user is silent.</li>
  <li><strong>Talking portraits:</strong> optionally display different artwork while that user speaks.</li>
  <li><strong>Artwork formats:</strong> use WebM, MP4 or static images supported by the browser.</li>
  <li><strong>Per-user configuration:</strong> players configure their own artwork; the GM can configure any user.</li>
  <li><strong>Saved artwork:</strong> artwork paths are stored against user accounts in the Foundry world.</li>
  <li><strong>Individual viewing preferences:</strong> each browser chooses whether to display animated avatars.</li>
  <li><strong>Camera support:</strong> a user's live camera feed takes precedence when their camera is enabled.</li>
</ul>

<h3>How it works</h3>
<p>The module reads LiveKit's speaking indicators and switches between the configured idle and talking artwork. Videos play silently, while LiveKit continues to handle the voice conversation.</p>

<p>This is speech-triggered artwork switching, rather than phoneme-based lip-sync. The module does not identify individual sounds or generate mouth movements. Any mouth animation must already be present in the selected video.</p>

<p>Talking artwork is optional. A single looping idle video can provide an animated portrait without requiring a second clip.</p>

<h3>Requirements</h3>
<ul>
  <li>Foundry VTT 14.</li>
  <li>LiveKit AVClient installed and enabled.</li>
  <li>A working LiveKit audio/video connection.</li>
  <li>LiveKit's <strong>Use separate window for A/V</strong> option disabled.</li>
  <li>Artwork files accessible through Foundry.</li>
</ul>

<p>No Live Actors module, OBS setup or separate speech-analysis agent is required.</p>

<h3>Getting started</h3>
<ol>
  <li>Install and enable LiveKit AVClient and LiveKit Animated Avatars.</li>
  <li>Connect Foundry's audio/video chat through LiveKit.</li>
  <li>Open <strong>Game Settings → LiveKit Animated Avatars → Configure Avatars</strong>.</li>
  <li>Select the user to configure.</li>
  <li>Browse for or upload idle artwork and, optionally, talking artwork.</li>
  <li>Save the artwork configuration.</li>
  <li>Enable <strong>Show animated avatars in this browser</strong> and save the viewing preference.</li>
  <li>Keep the camera off and speak to test the portrait change.</li>
</ol>

<h3>Player preferences and permissions</h3>
<p>Artwork configuration is shared through the world. Each browser independently controls whether it displays that artwork. Disabling animations restores the normal portrait presentation for that viewer without deleting the saved artwork paths.</p>

<p>Browsing and uploading files requires the appropriate Foundry permissions. If a player cannot upload artwork, the GM can upload the files and configure their portrait.</p>

<h3>Preparing your artwork</h3>
<p>No artwork or audio is included. Users supply their own files.</p>

<p>Short looping videos with consistent framing work well. Matching the dimensions and framing of idle and talking clips helps transitions appear consistent. Video playback depends on the browser supporting the file's codec.</p>

<h3>Support and feedback</h3>
<p>Report problems through <a href="https://github.com/Ezydrer/livekit-animated-avatars/issues">GitHub Issues</a>. Include your Foundry version, LiveKit AVClient version, module version, browser and the steps needed to reproduce the problem.</p>

<p><a href="https://github.com/Ezydrer/livekit-animated-avatars">Source code and releases</a></p>

<h3>Acknowledgements</h3>
<p>Inspired by Baileywiki's <a href="https://www.youtube.com/watch?v=txpFeMm3YbY&amp;t=541s">demonstration of animated character portraits</a>.</p>