@voqalize/avatar 0.5.4 → 0.5.6

package/README.md

@@ -71,6 +71,38 @@ The gains are optional, from `0` to `2`, and `1` is as authored:
 
 The client must be connected to a Voqalize session that has the avatar turned on.
 
+## Preload before the call
+
+Building a face takes the browser a moment: the runtime, the character, a GPU
+context and its shaders. On a slow phone that is over a second after the call
+connects before the face appears. `preloadAvatar` does that work before the call, off screen, so the
+mount that follows only moves the finished face onto the page:
+
+```js
+import { preloadAvatar, unloadAvatar } from "@voqalize/avatar";
+
+// when the visitor is about to talk: the page with the call button, or hover on it
+const face = preloadAvatar("<name>");
+
+// later, the ordinary mount takes the preloaded face
+createAvatar({ mount, client, character: "<name>" });
+
+// or, if the visitor leaves without calling
+unloadAvatar(face);
+```
+
+- One face is held at a time. Preloading the same character again returns the
+  same handle; preloading another frees the one held.
+- A mount of that character, through `createAvatar` or `<Avatar>`, takes the
+  face. After that the handle holds nothing and `unloadAvatar` does nothing,
+  and `destroy()` frees the face as usual.
+- `face.ready` settles when the face is built, or when it cannot be (no
+  WebGL 2, for example) and the mount will build it the ordinary way. You
+  never need to wait for it before mounting. It rejects only for a name that is
+  no character.
+- `unloadAvatar` frees the GPU context and the character's memory at once,
+  and is safe to call at any time.
+
 ### React
 
 ```jsx

package/dist/index.d.ts

@@ -9,6 +9,10 @@
  *
  *     const roster = await listCharacters();   // every character, to choose from
  *
+ *     const face = preloadAvatar("tara");      // before the call: build it off screen
+ *     await face.ready;                        // optional; createAvatar takes it either way
+ *     unloadAvatar(face);                      // the visitor left without calling
+ *
  * This package is the loader and nothing else. The avatar itself — the
  * characters, the renderer and everything that reads the call — is the
  * Voqalize avatar runtime, which this module imports from
@@ -67,6 +71,14 @@ export interface CharacterInfo {
      *  for example. Advice only: the avatar never speaks. */
     readonly suggestedVoices: readonly string[];
 }
+/** A face `preloadAvatar` is building, or has built, ahead of its mount. */
+export interface PreloadedAvatar {
+    /** The character it is. */
+    readonly character: string;
+    /** Settles once the face is built, or once it cannot be and the mount will
+     * build it the ordinary way. Rejects only for a name that is no character. */
+    readonly ready: Promise<void>;
+}
 export declare function createAvatar(options: AvatarOptions): AvatarInstance;
 /**
  * Every character the runtime can mount, in a stable order — for a page that
@@ -75,3 +87,26 @@ export declare function createAvatar(options: AvatarOptions): AvatarInstance;
  * runtime's own and cannot be changed.
  */
 export declare function listCharacters(): Promise<readonly CharacterInfo[]>;
+/**
+ * Build a character's face before there is anywhere to show it — the runtime,
+ * the character, its GPU context, its shaders and a first frame — so that a
+ * `createAvatar` (or `<Avatar>`) of the same character later only moves it onto
+ * the page. Call it when the visitor shows they are about to talk: on the page
+ * that holds the call button, or on hover over it.
+ *
+ * Holds one face. The same character again returns the same handle; another
+ * character frees the one held and builds the new one. A mount of the
+ * character takes the face, and the handle no longer holds anything. Nothing
+ * else changes for a mount: one with no preload, or of another character,
+ * builds its face as it always has.
+ */
+export declare function preloadAvatar(character: string): PreloadedAvatar;
+/**
+ * Free the face `preloadAvatar` built: its GPU context, the decoded character
+ * and its textures. For a visitor who leaves without calling, or a page that
+ * will not mount it after all. A handle a mount has taken, or that a preload
+ * of another character has already replaced, holds nothing, and unloading it
+ * does nothing. Safe to call at any time, including before `ready` settles;
+ * it then settles without the face being built, or with the build abandoned.
+ */
+export declare function unloadAvatar(face: PreloadedAvatar): void;

package/dist/index.js

@@ -9,6 +9,10 @@
  *
  *     const roster = await listCharacters();   // every character, to choose from
  *
+ *     const face = preloadAvatar("tara");      // before the call: build it off screen
+ *     await face.ready;                        // optional; createAvatar takes it either way
+ *     unloadAvatar(face);                      // the visitor left without calling
+ *
  * This package is the loader and nothing else. The avatar itself — the
  * characters, the renderer and everything that reads the call — is the
  * Voqalize avatar runtime, which this module imports from
@@ -44,8 +48,13 @@ export function createAvatar(options) {
     let destroyed = false;
     load()
         .then((rt) => {
-        if (!destroyed)
-            instance = rt.mount({ ...options, protocol: PROTOCOL });
+        if (destroyed)
+            return;
+        // The runtime moves a preloaded face of this character into the mount,
+        // after which it is the avatar's to destroy and no handle's to unload.
+        if (held?.character === options.character)
+            held = undefined;
+        instance = rt.mount({ ...options, protocol: PROTOCOL });
     })
         .catch((error) => console.error(`[avatar] could not start the avatar from ${RUNTIME_URL}`, error));
     return {
@@ -68,3 +77,59 @@ export async function listCharacters() {
         throw new Error(`[avatar] the runtime at ${RUNTIME_URL} does not list its characters`);
     return rt.characters();
 }
+// The one face built ahead of its mount. One, not one per character: each
+// holds a GPU context and a decoded head, and a page about to call knows
+// which character it is about to show.
+let held;
+/**
+ * Build a character's face before there is anywhere to show it — the runtime,
+ * the character, its GPU context, its shaders and a first frame — so that a
+ * `createAvatar` (or `<Avatar>`) of the same character later only moves it onto
+ * the page. Call it when the visitor shows they are about to talk: on the page
+ * that holds the call button, or on hover over it.
+ *
+ * Holds one face. The same character again returns the same handle; another
+ * character frees the one held and builds the new one. A mount of the
+ * character takes the face, and the handle no longer holds anything. Nothing
+ * else changes for a mount: one with no preload, or of another character,
+ * builds its face as it always has.
+ */
+export function preloadAvatar(character) {
+    if (!character)
+        throw new TypeError("preloadAvatar: `character` is required");
+    if (held?.character === character)
+        return held;
+    if (held)
+        unloadAvatar(held);
+    const face = {
+        character,
+        ready: load().then((rt) => (held === face ? rt.preload?.(character) : undefined), 
+        // A runtime that will not load leaves the mount to try again and report
+        // it; a preload is never the reason a page cannot call.
+        (error) => {
+            if (held === face)
+                held = undefined;
+            console.error(`[avatar] could not preload the avatar from ${RUNTIME_URL}`, error);
+        }).then(() => undefined, (error) => {
+            if (held === face)
+                held = undefined;
+            throw error;
+        }),
+    };
+    held = face;
+    return face;
+}
+/**
+ * Free the face `preloadAvatar` built: its GPU context, the decoded character
+ * and its textures. For a visitor who leaves without calling, or a page that
+ * will not mount it after all. A handle a mount has taken, or that a preload
+ * of another character has already replaced, holds nothing, and unloading it
+ * does nothing. Safe to call at any time, including before `ready` settles;
+ * it then settles without the face being built, or with the build abandoned.
+ */
+export function unloadAvatar(face) {
+    if (!face || held !== face)
+        return;
+    held = undefined;
+    load().then((rt) => rt.unload?.(face.character), () => { });
+}

package/dist/pin.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.WZVOTQJM.js";
+export declare const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.2X4UMJ6T.js";
 export declare const PROTOCOL = 1;

package/dist/pin.js

@@ -1,3 +1,3 @@
 // Written by scripts/build-runtime.mjs — the runtime this shim is released with.
-export const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.WZVOTQJM.js";
+export const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.2X4UMJ6T.js";
 export const PROTOCOL = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voqalize/avatar",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "A talking head for AI voice calls that embodies your pipecat client. This package loads the Voqalize avatar runtime.",
   "license": "MIT",
   "author": "Voqalize",