@keyframelabs/elements 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +71 -69
  2. package/package.json +3 -2
package/README.md CHANGED
@@ -1,8 +1,14 @@
1
1
  # @keyframelabs/elements
2
2
 
3
- Headless vanilla TypeScript library for embedding Persona avatars. Handles video/audio elements, session wiring, microphone input, and voice agent connections.
3
+ Framework-agnostic primitives for Keyframe Labs.
4
4
 
5
- No UI included — see `@keyframelabs/components-react` for a React example.
5
+ **Which package should I use?**
6
+ - **@keyframelabs/sdk** (high control)
7
+ - You implement the UI, state management, and agent/llm binding yourself
8
+ - **@keyframelabs/elements** (custom UI)
9
+ - You implement the UI; we handle the state and agent/llm binding (framework-agnostic)
10
+ - **@keyframelabs/react**: (drop-in)
11
+ - We handle the UI, state, and agent/llm binding
6
12
 
7
13
  ## Install
8
14
 
@@ -12,20 +18,21 @@ pnpm add @keyframelabs/elements
12
18
 
13
19
  ## Usage
14
20
 
15
- Two classes are available depending on your integration:
21
+ This package provides two primary classes depending on your integration strategy:
22
+ 1. **`PersonaEmbed`**: Fully managed. Uses a publishable key. Best for rapid frontend integration.
23
+ 2. **`PersonaView`**: Bring your own backend. Uses session tokens generated by your server.
16
24
 
17
- - **`PersonaEmbed`** — Fully managed KFL embed workflow. Uses a publishable key to handle authentication and session creation automatically.
18
- - **`PersonaView`** — Bring Your Own Backend (BYOB). Accepts pre-fetched session/agent details from your own backend.
25
+ ### Option A: PersonaEmbed (managed)
19
26
 
20
- ### PersonaEmbed (Publishable Key)
27
+ Use this if you have configured an embed in the Keyframe platform dashboard.
21
28
 
22
29
  ```ts
23
30
  import { PersonaEmbed } from '@keyframelabs/elements';
24
31
 
25
32
  const embed = new PersonaEmbed({
26
- container: document.getElementById('avatar')!,
33
+ container: document.getElementById('persona-container'),
27
34
  publishableKey: 'kfl_pk_live_...',
28
- videoFit: 'contain', // 'cover' (default) or 'contain'
35
+ videoFit: 'cover',
29
36
  onStateChange: (status) => console.log('Status:', status),
30
37
  onAgentStateChange: (state) => console.log('Agent:', state),
31
38
  onDisconnect: () => console.log('Disconnected'),
@@ -35,28 +42,18 @@ const embed = new PersonaEmbed({
35
42
  await embed.connect();
36
43
 
37
44
  // Later...
38
- embed.toggleMute();
39
45
  embed.disconnect();
40
46
  ```
41
47
 
42
- ### PersonaView (Bring Your Own Backend)
48
+ ### Option B: PersonaView (bring your own backend)
43
49
 
44
50
  Use this when you want to manage authentication through your own backend.
45
51
 
46
- First, fetch session details from your backend:
47
-
48
- ```ts
49
- const response = await fetch('/api/persona/session', { method: 'POST' });
50
- const { sessionDetails, voiceAgentDetails } = await response.json();
51
- ```
52
-
53
- Then pass them to PersonaView:
54
-
55
52
  ```ts
56
53
  import { PersonaView } from '@keyframelabs/elements';
57
54
 
58
55
  const view = new PersonaView({
59
- container: document.getElementById('avatar')!,
56
+ container: document.getElementById('persona-container')!,
60
57
  sessionDetails,
61
58
  voiceAgentDetails,
62
59
  videoFit: 'contain',
@@ -69,63 +66,74 @@ const view = new PersonaView({
69
66
  await view.connect();
70
67
 
71
68
  // Later...
72
- view.toggleMute();
73
69
  view.disconnect();
74
70
  ```
75
71
 
76
- ## API
72
+ ## Supported agents and real-time LLMs
73
+
74
+ Supports ElevenLabs Agents, Cartesia Line, and Gemini Live.
77
75
 
78
- ### `PersonaEmbed` (Fully Managed)
76
+ For `PersonaEmbed`, this is determined by the values you set in the Keyframe platform dashboard.
79
77
 
80
- Create your embed config at platform.keyframelabs.com to get a publishable key. KFL handles session creation, authentication, and agent configuration.
78
+ For `PersonaView`, this is determined by `voiceAgentDetails`.
81
79
 
82
- #### Constructor Options
80
+ ## API
83
81
 
84
- | Option | Type | Default | Description |
85
- |--------|------|---------|-------------|
86
- | `container` | `HTMLElement` | required | Target container for video/audio elements |
87
- | `publishableKey` | `string` | required | Your embed config publishable key |
88
- | `apiBaseUrl` | `string` | production | API endpoint |
89
- | `videoFit` | `'cover' \| 'contain'` | `'cover'` | Video scaling mode |
90
- | `onStateChange` | `(status: EmbedStatus) => void` | - | Status callback |
91
- | `onAgentStateChange` | `(state: AgentState) => void` | - | Agent state callback |
92
- | `onDisconnect` | `() => void` | - | Disconnect callback |
93
- | `onError` | `(err: Error) => void` | - | Error callback |
82
+ ### `PersonaEmbed`
94
83
 
95
- #### Properties
84
+ #### Options
96
85
 
97
- | Property | Type | Description |
98
- |----------|------|-------------|
99
- | `status` | `EmbedStatus` | `'connecting' \| 'connected' \| 'error' \| 'disconnected'` |
100
- | `agentState` | `AgentState` | `'idle' \| 'listening' \| 'thinking' \| 'speaking'` |
101
- | `isMuted` | `boolean` | Microphone mute state |
102
- | `videoElement` | `HTMLVideoElement` | The video element |
103
- | `audioElement` | `HTMLAudioElement` | The audio element |
86
+ | Option | Type | Default | Description |
87
+ | -------------------- | ------------------------------- | -------------------------------- | ---------------------------------------------- |
88
+ | `container` | `HTMLElement` | Required | Target container for video and audio elements. |
89
+ | `publishableKey` | `string` | Required | Your publishable embed key. |
90
+ | `apiBaseUrl` | `string` | `'https://api.keyframelabs.com'` | Base URL for the Keyframe API. |
91
+ | `videoFit` | `'cover' \| 'contain'` | `'cover'` | Video scaling mode (`object-fit`). |
92
+ | `onStateChange` | `(status: EmbedStatus) => void` | — | Fired when connection status changes. |
93
+ | `onAgentStateChange` | `(state: AgentState) => void` | — | Fired when agent state changes. |
94
+ | `onDisconnect` | `() => void` | — | Fired when the session disconnects. |
95
+ | `onError` | `(err: Error) => void` | — | Fired on fatal errors. |
104
96
 
105
97
  #### Methods
106
98
 
107
- | Method | Description |
108
- |--------|-------------|
109
- | `connect()` | Connect to session (async) |
110
- | `disconnect()` | Disconnect and cleanup |
111
- | `toggleMute()` | Toggle microphone mute |
99
+ | Method | Signature | Description |
100
+ | ------------ | --------------------- | -------------------------------------------------- |
101
+ | `connect` | `() => Promise<void>` | Starts the session and establishes the connection. |
102
+ | `disconnect` | `() => void` | Disconnects the session and cleans up resources. |
103
+ | `toggleMute` | `() => void` | Toggles the user's microphone mute state. |
112
104
 
113
- ### `PersonaView` (BYOB)
105
+ #### Properties
106
+
107
+ | Property | Type | Description |
108
+ | -------------- | ------------------ | -------------------------------------------------------------------------------------- |
109
+ | `status` | `EmbedStatus` | Current connection status: `'connecting' \| 'connected' \| 'disconnected' \| 'error'`. |
110
+ | `agentState` | `AgentState` | Current agent state: `'idle' \| 'listening' \| 'thinking' \| 'speaking'`. |
111
+ | `isMuted` | `boolean` | Whether the microphone is currently muted. |
112
+ | `videoElement` | `HTMLVideoElement` | The underlying video element used for rendering. |
113
+ | `audioElement` | `HTMLAudioElement` | The underlying audio element used for playback. |
114
+
115
+ ### `PersonaView`
116
+
117
+ #### Options
118
+
119
+ | Option | Type | Default | Description |
120
+ | -------------------- | ------------------------------- | --------- | ---------------------------------------------- |
121
+ | `container` | `HTMLElement` | Required | Target container for video and audio elements. |
122
+ | `sessionDetails` | `SessionDetails` | Required | Session configuration from your backend. |
123
+ | `voiceAgentDetails` | `VoiceAgentDetails` | Required | Voice agent configuration from your backend. |
124
+ | `videoFit` | `'cover' \| 'contain'` | `'cover'` | Video scaling mode (`object-fit`). |
125
+ | `onStateChange` | `(status: EmbedStatus) => void` | — | Fired when connection status changes. |
126
+ | `onAgentStateChange` | `(state: AgentState) => void` | — | Fired when agent state changes. |
127
+ | `onDisconnect` | `() => void` | — | Fired when the session disconnects. |
128
+ | `onError` | `(err: Error) => void` | — | Fired on fatal errors. |
129
+
130
+ #### Methods
114
131
 
115
- For self-hosted backends that manage their own session creation and authentication.
132
+ Same as `PersonaEmbed`.
116
133
 
117
- #### Constructor Options
134
+ #### Properties
118
135
 
119
- | Option | Type | Default | Description |
120
- |--------|------|---------|-------------|
121
- | `container` | `HTMLElement` | required | Target container for video/audio elements |
122
- | `sessionDetails` | `SessionDetails` | required | Session config from your backend |
123
- | `voiceAgentDetails` | `VoiceAgentDetails` | required | Voice agent config from your backend |
124
- | `videoFit` | `'cover' \| 'contain'` | `'cover'` | Video scaling mode |
125
- | `onStateChange` | `(status: EmbedStatus) => void` | - | Status callback |
126
- | `onAgentStateChange` | `(state: AgentState) => void` | - | Agent state callback |
127
- | `onDisconnect` | `() => void` | - | Disconnect callback |
128
- | `onError` | `(err: Error) => void` | - | Error callback |
136
+ Same as `PersonaEmbed`.
129
137
 
130
138
  #### Types
131
139
 
@@ -144,12 +152,6 @@ type VoiceAgentDetails = {
144
152
  };
145
153
  ```
146
154
 
147
- #### Properties & Methods
148
-
149
- Same as `PersonaEmbed` (see above).
150
-
151
- ## Voice Agents
152
-
153
- Supports Gemini Live, ElevenLabs, and Cartesia agents. The agent type is determined by your embed config or `voiceAgentDetails.type`.
155
+ ## License
154
156
 
155
- If you need support for new voice agent platforms built in, drop us a line at support@keyframelabs.com
157
+ MIT
package/package.json CHANGED
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "name": "@keyframelabs/elements",
3
+ "description": "Framework-agnostic primitives for Keyframe Labs.",
3
4
  "publishConfig": {
4
5
  "access": "public"
5
6
  },
6
- "version": "0.0.4",
7
+ "version": "0.0.5",
7
8
  "type": "module",
8
9
  "main": "./dist/index.js",
9
10
  "types": "./dist/index.d.ts",
@@ -18,7 +19,7 @@
18
19
  ],
19
20
  "sideEffects": false,
20
21
  "dependencies": {
21
- "@keyframelabs/sdk": "0.1.3"
22
+ "@keyframelabs/sdk": "0.1.5"
22
23
  },
23
24
  "devDependencies": {
24
25
  "@types/node": "^25.0.9",