@voqalize/avatar 0.5.1 → 0.5.3

package/README.md

@@ -46,7 +46,22 @@ appeared.
 `character` names one of the characters you can meet at
 https://voqalize.com/demos/avatar. Each release of this package can mount a
 fixed set of them, and a name it does not have throws, listing the ones it
-does.
+does. `listCharacters()` returns that set:
+
+```js
+import { listCharacters } from "@voqalize/avatar";
+
+for (const c of await listCharacters()) {
+  // c.name, c.still (an image URL), c.gender, c.age.min, c.age.max,
+  // c.ethnicity[], c.tags[], c.suggestedVoices[]
+}
+```
+
+Use it to build a picker or a filter rather than writing the names down. The
+words in `gender`, `ethnicity` and `tags` come from closed lists, so a filter
+you build from one call matches the next. `suggestedVoices` lists the voices
+that suit the face, best first, as Voqalize voice ids such as
+`omnivoice/gauri`. It is advice: the avatar never speaks.
 
 The gains are optional, from `0` to `2`, and `1` is as authored:
 

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  *     // …
  *     avatar.destroy();
  *
+ *     const roster = await listCharacters();   // every character, to choose from
+ *
  * 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
@@ -42,4 +44,34 @@ export interface AvatarInstance {
      * including before the avatar has appeared. */
     destroy(): void;
 }
+/**
+ * A character, as a page choosing one sees it. The words in `gender`,
+ * `ethnicity` and `tags` come from closed lists the runtime keeps, so a filter
+ * built from what one call returns matches what the next returns.
+ */
+export interface CharacterInfo {
+    /** What `createAvatar` takes as `character`. */
+    readonly name: string;
+    /** An image URL: the character at rest. */
+    readonly still: string;
+    readonly gender: string;
+    /** The age the face reads as, in years. */
+    readonly age: {
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly ethnicity: readonly string[];
+    /** Dress, hair, jewellery — how the character presents. */
+    readonly tags: readonly string[];
+    /** Voqalize voice ids that suit this face, best first — `"omnivoice/gauri"`,
+     *  for example. Advice only: the avatar never speaks. */
+    readonly suggestedVoices: readonly string[];
+}
 export declare function createAvatar(options: AvatarOptions): AvatarInstance;
+/**
+ * Every character the runtime can mount, in a stable order — for a page that
+ * lets someone choose one, or filters by what they look like. Loads the runtime
+ * if nothing has yet, so the first call waits for it; the list is the
+ * runtime's own and cannot be changed.
+ */
+export declare function listCharacters(): Promise<readonly CharacterInfo[]>;

package/dist/index.js

@@ -7,6 +7,8 @@
  *     // …
  *     avatar.destroy();
  *
+ *     const roster = await listCharacters();   // every character, to choose from
+ *
  * 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
@@ -54,3 +56,15 @@ export function createAvatar(options) {
         },
     };
 }
+/**
+ * Every character the runtime can mount, in a stable order — for a page that
+ * lets someone choose one, or filters by what they look like. Loads the runtime
+ * if nothing has yet, so the first call waits for it; the list is the
+ * runtime's own and cannot be changed.
+ */
+export async function listCharacters() {
+    const rt = await load();
+    if (!rt.characters)
+        throw new Error(`[avatar] the runtime at ${RUNTIME_URL} does not list its characters`);
+    return rt.characters();
+}

package/dist/pin.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.QLWN4A2D.js";
+export declare const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.RE3NT6O7.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.QLWN4A2D.js";
+export const RUNTIME_URL = "https://avatar.voqalize.com/runtime/runtime.RE3NT6O7.js";
 export const PROTOCOL = 1;

package/package.json

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