Troubleshooting

The face is invisible

Give the empty host an explicit width and height, call createFace after mounting, and check the artwork request in your network panel. Call renderFace on the server. A missing or blocked artworkSrc cannot draw the character.

Keep the host’s contents owned by the SDK. Call destroy before removing it or mounting a replacement. React Strict Mode intentionally mounts, cleans up, and mounts again.

Speech plays but the mouth is still

Set speaking from actual playback events and pass speech.boundary, an RMS getLevel callback, or mouthOpen. Some browser voices do not emit word boundaries. Reduced-motion preferences and animated: false disable mouth motion as well as idle motion.

Audio analysis of a cross-origin file requires that server to allow CORS. Set audio.crossOrigin before assigning audio.src. Resume the AudioContext from a user gesture.

Speech does not start

Start playback from a click. A model request can outlast the browser’s user activation; use Read reply or Replay after the response. Use one active browser speaker per page. Inspect speech.getSnapshot().error: playback errors are reported there; invalid input rejects speak or play.

Provider errors and cancellation

401 or 403: check the key and its permissions. 400 or 404: check the model or voice ID and account access. 429: check the provider’s rate or credit limit. 502: the provider failed or returned an invalid response. 504: the request timed out. Save settings validates their format; the first message verifies provider access.

The playground inspector shows the HTTP status, elapsed request time, and validated expression segments. Credentials are excluded from copied configuration. Stop cancels pending work; providers may bill work already started. Forget keys also clears the transcript and inspector.

The first reply is slow

OpenAI replies stream one validated expression segment at a time; text and speech can start before the full reply finishes. The playground loads its chat route in advance without making a paid provider request. Anthropic and Gateway currently return complete replies.

In Response, compare First reply, Total, Provider, and Server overhead. Provider includes the upstream connection and generation; voice generation and playback are separate. A slow first request followed by fast replies can indicate initialization or provider warm-up. Streaming cannot guarantee a reply within one second if the provider has not sent output yet.

Content Security Policy

The renderer includes a style element and SVG style attributes. A strict policy must allow the SDK’s styles using an appropriate style hash or your application’s style policy; the SDK currently has no nonce option. Bundled images use data URLs, which need img-src data:. Hosted artwork instead needs its image origin allowed. Check CSP violations in your browser console before changing policy.