---
name: install-liveling
description: Add a Liveling (a looping animated character from livelings, by Phantom Firm) as the face of an AI assistant or agent in a web app or chat UI you control. Use when the user says "install my Liveling", "add my Liveling", or hands you Liveling files.
---

# Install a Liveling

A Liveling is delivered as:
- `<name>-loop.webm` and/or `<name>-loop.mp4`: a seamless 5-second muted loop (square)
- `<name>.png`: a clean square still
- `<name>-round.png`: a round still for profile pictures

## Where it can move, and where it can't
- It moves anywhere you control the screen: a website, a web or desktop app, or a chat UI you built (OpenAI ChatKit with your own front end, the OpenAI Agents SDK, the Claude Agent SDK, or any other).
- On hosted platforms that only take a picture (custom GPTs, Grok bots, Discord, Slack, Telegram, ElevenLabs agents), upload the PNG. Do not promise animation there.
- Claude, Gemini and Meta AI apps have no custom avatar setting. Don't try to set one.

## Steps (web UI)
1. Copy the files into the app's static assets folder, e.g. `public/liveling/`.
2. Render the avatar with a still first and the loop on top:
   ```html
   <span class="liveling" aria-hidden="true">
     <video autoplay muted loop playsinline preload="metadata" poster="/liveling/NAME.png">
       <source src="/liveling/NAME-loop.webm" type="video/webm">
       <source src="/liveling/NAME-loop.mp4" type="video/mp4">
     </video>
   </span>
   ```
   `muted` and `playsinline` are required for autoplay on phones.
3. Style it as a circle:
   ```css
   .liveling{display:inline-block;width:44px;height:44px;border-radius:50%;overflow:hidden}
   .liveling video{width:100%;height:100%;object-fit:cover}
   @media (prefers-reduced-motion: reduce){.liveling video{display:none}.liveling{background:url(/liveling/NAME.png) center/cover}}
   ```
4. Optional, gentle states: while the agent is thinking, add a soft pulse with `transform: scale(1.04)` on the wrapper; while it answers, play the loop at `playbackRate = 1`; when idle, `0.8`. Keep it subtle.
5. Pause the video when it is off screen (IntersectionObserver), to save battery.
6. Give the avatar an accessible name nearby (the agent's name in text). The video itself stays `aria-hidden`.

## Check before you finish
- The loop plays on desktop Chrome and Safari, and on a phone.
- With reduced motion on, the still shows instead.
- Nothing shifts layout while the video loads (fixed width and height).