feat(protoface): add avatar plugin

.changeset/clever-protoface-plugin.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents-plugin-protoface': patch
+---
+
+Add Protoface avatar plugin.

examples/package.json

@@ -41,6 +41,7 @@
     "@livekit/agents-plugin-neuphonic": "workspace:*",
     "@livekit/agents-plugin-openai": "workspace:*",
     "@livekit/agents-plugin-phonic": "workspace:*",
+    "@livekit/agents-plugin-protoface": "workspace:*",
     "@livekit/agents-plugin-resemble": "workspace:*",
     "@livekit/agents-plugin-rime": "workspace:*",
     "@livekit/agents-plugin-runway": "workspace:*",

examples/src/protoface_avatar.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { type JobContext, ServerOptions, cli, defineAgent, voice } from '@livekit/agents';
+import * as google from '@livekit/agents-plugin-google';
+import * as protoface from '@livekit/agents-plugin-protoface';
+import { fileURLToPath } from 'node:url';
+
+export default defineAgent({
+  entry: async (ctx: JobContext) => {
+    const session = new voice.AgentSession({
+      llm: new google.realtime.RealtimeModel({
+        voice: 'Charon',
+      }),
+      turnHandling: {
+        interruption: {
+          resumeFalseInterruption: false,
+        },
+      },
+    });
+
+    await ctx.connect();
+
+    const avatar = new protoface.AvatarSession({
+      avatarId: process.env.PROTOFACE_AVATAR_ID || protoface.DEFAULT_STOCK_AVATAR_ID,
+    });
+    await avatar.start(session, ctx.room);
+
+    await session.start({
+      agent: new voice.Agent({
+        instructions: 'Talk to me!',
+      }),
+      room: ctx.room,
+    });
+  },
+});
+
+cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));

plugins/protoface/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @livekit/agents-plugin-protoface
+
+## 1.4.9
+
+### Patch Changes
+
+- Add Protoface avatar plugin.

plugins/protoface/README.md

@@ -0,0 +1,15 @@
+# Protoface plugin for LiveKit Agents
+
+Support for the [Protoface](https://protoface.com/) virtual avatar.
+
+See the [Protoface docs](https://docs.protoface.com/) for more information.
+
+## Installation
+
+```bash
+npm install @livekit/agents-plugin-protoface
+```
+
+## Pre-requisites
+
+You'll need an API key from Protoface. It can be set as an environment variable: `PROTOFACE_API_KEY`

plugins/protoface/api-extractor.json

@@ -0,0 +1,8 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-shared.json",
+  "mainEntryPointFilePath": "./dist/index.d.ts"
+}

plugins/protoface/etc/agents-plugin-protoface.api.md

@@ -0,0 +1,90 @@
+## API Report File for "@livekit/agents-plugin-protoface"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { APIConnectOptions } from '@livekit/agents';
+import type { Room } from '@livekit/rtc-node';
+import { voice } from '@livekit/agents';
+
+// @public
+export class AvatarSession extends voice.AvatarSession {
+    constructor(options?: AvatarSessionOptions);
+    // (undocumented)
+    aclose(): Promise<void>;
+    // (undocumented)
+    get avatarIdentity(): string;
+    // (undocumented)
+    get provider(): string;
+    get sessionId(): string | null;
+    // (undocumented)
+    start(agentSession: voice.AgentSession, room: Room, options?: StartOptions): Promise<void>;
+}
+
+// @public (undocumented)
+export interface AvatarSessionOptions {
+    apiKey?: string | null;
+    apiUrl?: string | null;
+    avatarId?: string;
+    avatarParticipantIdentity?: string | null;
+    avatarParticipantName?: string | null;
+    connOptions?: APIConnectOptions;
+    maxDurationSeconds?: number | null;
+}
+
+// @public (undocumented)
+export const DEFAULT_API_URL = "https://api.protoface.com";
+
+// @public (undocumented)
+export const DEFAULT_STOCK_AVATAR_ID = "av_stock_001";
+
+// @public
+export class ProtofaceAPI {
+    constructor(options?: ProtofaceAPIOptions);
+    // (undocumented)
+    endSession(sessionId: string): Promise<Record<string, unknown>>;
+    // (undocumented)
+    startSession(options: StartSessionOptions): Promise<ProtofaceSession>;
+}
+
+// @public (undocumented)
+export interface ProtofaceAPIOptions {
+    apiKey?: string | null;
+    apiUrl?: string | null;
+    connOptions?: APIConnectOptions;
+}
+
+// @public (undocumented)
+export class ProtofaceException extends Error {
+    constructor(message: string);
+}
+
+// @public (undocumented)
+export type ProtofaceSession = Record<string, unknown> & {
+    id?: string;
+};
+
+// @public
+export interface StartOptions {
+    // (undocumented)
+    livekitApiKey?: string | null;
+    // (undocumented)
+    livekitApiSecret?: string | null;
+    // (undocumented)
+    livekitUrl?: string | null;
+}
+
+// @public (undocumented)
+export interface StartSessionOptions {
+    // (undocumented)
+    avatarId: string;
+    // (undocumented)
+    maxDurationSeconds?: number | null;
+    // (undocumented)
+    transport: Record<string, unknown>;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

plugins/protoface/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@livekit/agents-plugin-protoface",
+  "version": "1.4.9",
+  "description": "Protoface avatar plugin for LiveKit Node Agents",
+  "main": "dist/index.js",
+  "require": "dist/index.cjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "import": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    }
+  },
+  "author": "LiveKit",
+  "type": "module",
+  "repository": "git@github.com:livekit/agents-js.git",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup --onSuccess \"pnpm build:types\"",
+    "build:types": "tsc --declaration --emitDeclarationOnly && node ../../scripts/copyDeclarationOutput.js",
+    "clean": "rm -rf dist",
+    "clean:build": "pnpm clean && pnpm build",
+    "lint": "eslint -f unix \"src/**/*.{ts,js}\"",
+    "api:check": "api-extractor run --typescript-compiler-folder ../../node_modules/typescript",
+    "api:update": "api-extractor run --local --typescript-compiler-folder ../../node_modules/typescript --verbose"
+  },
+  "devDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "catalog:",
+    "@microsoft/api-extractor": "^7.35.0",
+    "pino": "^8.19.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "livekit-server-sdk": "^2.13.3"
+  },
+  "peerDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "catalog:"
+  }
+}