# posecode-embed
**Embed a live 3D Posecode movement anywhere with one `
posecode exercise "Lateral raise"
rig humanoid
pose start = standing
step "Raise" 1.4s settle:
shoulders: abduct 90
elbows: flex 10
step "Lower" 1.6s drive:
shoulders: abduct 0
elbows: flex 0
repeat 8
```
The script auto-registers the element and boots each player when it scrolls into
view. That's it.
Replace `@latest` with an exact package version in production so a deployment
always uses a known parser/render pair. A `src` URL can be relative or absolute;
cross-origin movement files must be served with CORS permission.
## With a bundler
```bash
npm install posecode-embed
```
```js
import "posecode-embed"; // auto-registers
```
Or register it yourself for controlled timing:
```js
import { definePosecodePlayer } from "posecode-embed";
definePosecodePlayer(); // idempotent
```
## Attributes
| Attribute | Default | Description |
| --- | --- | --- |
| `doc` | n/a | A `posecode-share` token (highest precedence). |
| `src` | n/a | URL of a `.posecode` file to fetch. |
| *(inline text)* | n/a | The element's text content, used if `doc`/`src` are absent. |
| `autoplay` | `true` | Play as soon as the movement loads. |
| `loop` | `true` | Loop the timeline. |
| `controls` | `true` | Show the play/pause bar. |
| `autorotate` | `true` | Slowly orbit the camera when idle. |
| `speed` | `1` | Playback multiplier (`0.1`–`4`). |
| `character` | *(document-driven)* | Realistic figure. Absent: optional `avatar avatar1|avatar2|avatar3` selects a hosted appearance; documents without it use the humanoid XBot default. Set to a GLB URL to pin one character regardless of `avatar`, or `off` for the procedural mannequin. Load failures fall back to the mannequin. |
| `playground` | `https://posecode.org/play` | Base URL for the "Edit ↗" link. |
Boolean attributes accept `false` / `0` / `no` / `off` to turn them off, so
`autoplay="false"` works as expected.
## Behaviour
- **Lazy & cheap.** three.js loads only when a player scrolls into view; many
embeds on one page stay idle until seen.
- **Accessible.** Honors `prefers-reduced-motion` (no autoplay, no camera
orbit) and exposes a labelled play/pause control.
- **Never blank.** A bad token, a failed fetch, or an unparseable movement
renders a readable message instead of an empty canvas, and fires a
`posecode:error` event.
- **Isolated.** Markup and styles live in a shadow root; nothing leaks into or
out of the host page.
## Events & API
```js
const player = document.querySelector("posecode-player");
player.addEventListener("posecode:ready", (e) => {
console.log(e.detail.version, e.detail.languageVersion, e.detail.warnings);
player.viewer.pause();
});
player.addEventListener("posecode:error", (e) => {
console.warn(e.detail.code, e.detail.error, e.detail.errors);
});
player.toggle(); // play / pause
player.viewer; // the underlying render Viewer (null until booted)
```
The host element reflects `data-posecode-state="loading|ready|error"`, plus the
package and language versions, for integration tests and monitoring. Existing
listeners that only read `event.detail.error` remain compatible.
CDN users can validate source without creating WebGL:
```js
const result = Posecode.validatePosecode(source);
console.log(Posecode.version, Posecode.languageVersion, result.errors);
```
For a movement library in CI, run:
```bash
npx posecode-parser@latest validate --strict ./movements
```
AGPL-3.0-only, part of [Posecode](https://github.com/posecode-dev/posecode). A [separate commercial license](https://github.com/posecode-dev/posecode/blob/main/docs/legal/COMMERCIAL-LICENSE.md) is available for closed-source product use.