@voqalize/avatar 0.4.2 → 0.4.3

package/LICENSE-APACHE-2.0

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -7,9 +7,7 @@ call has started and stopped.
 
 No video track, no per-minute avatar vendor, no second media path. SVG faces
 and 2.5-D characters ship with it, one per entry point, so you pay for the one
-you import, and you can author your own. Canvas2D identities also ship and are
-frozen: they still work, they get no further work,
-and they come out in 0.5.0 (below).
+you import, and you can author your own.
 
 This is the browser half. The pipeline half is
 [`voqalize-avatar`](https://pypi.org/project/voqalize-avatar/) on PyPI; they are
@@ -17,7 +15,7 @@ two ends of one wire format and release independently, kept compatible by the
 wire contract rather than a shared version number
 ([RELEASING.md § Compatibility](https://github.com/voqalize/avatar/blob/main/RELEASING.md#compatibility)).
 
-**Licence: MIT for the code and the SVG and Canvas2D avatars, CC-BY 4.0 for the
+**Licence: MIT for the code and the SVG avatars, CC-BY 4.0 for the
 2.5-D character binaries** (`assets/*.glb` — see `assets/README.md` for the
 credit line). Which applies is decided by the kind of avatar, so adding a
 character never moves the line. The manifest declares the pair as
@@ -66,12 +64,6 @@ That is the integration, both halves of it. Neither takes an argument.
 embodiment of your `PipecatClient` and reacts to it, so there is no avatar to
 drive and no state to read back.
 
-**Works the same with or without `@pipecat-ai/voice-ui-kit`.** All `createAvatar`
-needs is the `PipecatClient` instance — however you built your call UI, if you
-have that instance you can mount an avatar next to it. voice-ui-kit's
-components (buttons, visualizers, transport controls) are chrome around the
-same client; they neither wrap nor gate it.
-
 ## What you get for free
 
 Most of the avatar works on any pipecat application without customization — not
@@ -87,9 +79,9 @@ always the renderer's.
 What is left over is small, specific, and each item is a case the library
 refuses to guess at — a deliberate nod or greeting, a tool whose calls never
 enter your pipeline, a pose richer than the core states, a backend that is not
-ours. [The architecture
-page](https://github.com/voqalize/avatar/blob/main/docs/architecture.md) is the
-canonical reference for all of it.
+ours. [The wire
+contract](https://github.com/voqalize/avatar/blob/main/docs/contract-wire.md) is
+the canonical reference for all of it.
 
 ## The wire protocol
 
@@ -136,52 +128,6 @@ createAvatar({ mount, client, face: myna });
 A name would need a table, and a table is a dynamic index no bundler can shake —
 every drawing in every consumer's bundle to render one.
 
-## Professional avatars — frozen, removed in 0.5.0
-
-**Do not start here.** These are a Canvas2D renderer that ended up in the
-wrong place: more expensive to author than an SVG drawing and less expressive
-than the 2.5-D characters, which is the whole range it was meant to sit between.
-They still work and they are still tested, but they get no further work, and
-their entry points come out in 0.5.0. Pick an SVG face or a 2.5-D character
-instead; both are below.
-
-Complete, code-authored avatars, each its own `createAvatar` module:
-
-```js
-import { createAvatar } from '@voqalize/avatar/avatars/arjun';
-// or: @voqalize/avatar/avatars/meera
-//     @voqalize/avatar/avatars/vikram
-//     @voqalize/avatar/avatars/ishita
-//     @voqalize/avatar/avatars/kabir
-//     @voqalize/avatar/avatars/naina
-
-const avatar = createAvatar({ mount, client: pipecatClient });
-```
-
-`arjun`/`meera` are the original interviewer pair; `vikram`/`ishita` and
-`kabir`/`naina` are further wardrobe/hair directions on the same rig. The
-entry points `interviewer-male`, `interviewer-female`, `professional-male-a`,
-`professional-female-a`, `professional-male-b` and `professional-female-b`
-still work — they are `@deprecated` aliases for the names above, kept so
-existing imports do not break, and should not be used in new code.
-
-They depict Indian professionals in their late twenties, without caricature
-or regional costume cues. They are calibrated at call-tile size and preserve
-every expression target, continuous visemes, gaze, blink, head motion, and
-the frame-edge gesture hand. Each module is a complete identity, not a face
-value: import one instead of the default module and do not pass a `face`
-option.
-
-Their faces use low-contrast, landmark-driven nose planes rather than an
-outlined nose glyph. A few identity-specific freckles or a small mole add depth
-only in low-motion upper-cheek areas; none are used as demographic cues.
-
-They use the same public contract and the same Pipecat lifecycle/viseme driver
-as the SVG avatars. Their private renderer is Canvas2D; its rig data and bitmap
-wardrobe assets are implementation details and no Canvas or pose API is added
-to the package surface. Like the SVG faces they are code, MIT, and ask for no
-attribution.
-
 ## The 2.5-D characters
 
 The characters ship as compiled binaries, each its own `createAvatar` module:
@@ -191,6 +137,7 @@ import { createAvatar } from '@voqalize/avatar/avatars/tara';
 // or: @voqalize/avatar/avatars/tushar
 //     @voqalize/avatar/avatars/tanya
 //     @voqalize/avatar/avatars/tess
+//     @voqalize/avatar/avatars/tanvi
 
 const avatar = createAvatar({ mount, client: pipecatClient });
 ```
@@ -198,13 +145,15 @@ const avatar = createAvatar({ mount, client: pipecatClient });
 A photograph of a face projected onto shallow geometry, with the parts that have
 to move — eyes, teeth, the lip line — built as geometry rather than painted.
 Three.js is an *optional* peer (`three`, `>=0.180 <0.187`) behind those
-entry points only, so an SVG or Canvas consumer never downloads it, and the `.glb`
+entry points only, so an SVG consumer never downloads it, and the `.glb`
 is fetched when the avatar mounts.
 
 Nothing above the renderer changes: the same wire, the same states, the same
 cue-synced mouth, and a server that has never heard of these characters drives one
-correctly. The head turns 15° of yaw and 24° of pitch, which is a measured limit
-rather than an option.
+correctly. How far a character's head may turn is not an option either: it is a
+limit read off that face by eye, carried per character in
+`client/three/motion-limits.json`, which `HEAD_DEG` in
+`client/three/character-rig.ts` turns into a pose channel's degrees.
 
 **The binaries are artwork under CC-BY 4.0**, separately from the MIT code
 around them; the credit line is in `assets/README.md`. Mounting, sizing, the asset
@@ -236,39 +185,3 @@ Omitting it is conforming.
 **There is deliberately no renderer interface.** The pose channels our SVG mixer
 uses to talk to our faces are internal, and a second public contract stays
 premature until a second renderer says what it needs.
-
-## What is in this tarball
-
-`dist/` is the compiled client — `AvatarClient`, the avatar entry points and the
-React binding. `src/` is the widget itself: the mixer, the SVG rig and drawings,
-plus the private Canvas2D interviewer rigs and their assets, as dependency-free
-ES modules with no build step, imported by `dist/` through ordinary relative
-paths. `client/` is the TypeScript those `dist/` files were compiled from, so
-the source maps resolve. `assets/` is the compiled characters and their
-licence note — the only non-JavaScript thing here, fetched at runtime by URL.
-
-The contract documents do not ship here. They live in the repository, which is
-where they are kept current:
-[github.com/voqalize/avatar](https://github.com/voqalize/avatar).
-
-## License
-
-**MIT for the code, CC-BY 4.0 for the artwork**, and Voqalize holds the
-copyright on all of it. The licence follows the kind of avatar, not the roster:
-
-- **SVG faces and Canvas2D identities are code** — MIT, no attribution. Each is
-  drawn by the function that ships it; a Canvas2D identity's rig data and
-  wardrobe bitmaps are implementation details of that function, not artwork you
-  are licensing.
-- **2.5-D characters are artwork** — `assets/*.glb`, and nothing else in the
-  tarball, under CC-BY 4.0. `assets/README.md` carries the credit line.
-
-MIT is usable anywhere, including in closed-source products. The manifest
-declares the package as `MIT AND CC-BY-4.0`, which is what a licence scanner
-reports whether or not you import a 2.5-D character.
-
-The drawing idiom `peep` is authored in is
-[Open Peeps](https://www.openpeeps.com/) (CC0) — no artwork is copied. The
-`avatarsync` aligner that produces the mouth shapes is a fork of
-[Rhubarb Lip Sync](https://github.com/DanielSWolf/rhubarb-lip-sync) (MIT) and
-ships in the Python package, not this one.

package/assets/README.md

@@ -1,23 +1,9 @@
 # The character binaries
 
-The 2.5-D characters, one compiled file each:
+The 2.5-D characters, one compiled file each: `tara.glb`, `tushar.glb`,
+`tanya.glb`, `tess.glb`, `tanvi.glb`.
 
-| file | character | what it is |
-|---|---|---|
-| `tara.glb` | tara | the first; shallow geometry under a projected portrait |
-| `tushar.glb` | tushar | the second, her scripts with his landmarks |
-| `tanya.glb` | tanya | the third, built from supplied reference images |
-| `tess.glb` | tess | the fourth, from a single supplied reference sheet |
-
-They are loaded for you. `@voqalize/avatar/avatars/tara` resolves the file beside
-itself and hands it to a loader; you never name a path, and the only reason to
-know these are here is the licence below. `three` is an *optional* peer of this
-package, so importing a drawing instead of a character downloads none of this.
-
-Each file carries geometry, one morph target per pose channel, and its texture
-atlases as WebP — which is most of the bytes, because the atlases are
-photographs. **They are build outputs. Do not hand-edit one**; there is nothing
-in this directory to regenerate it from, and the next release overwrites it.
+**They are build outputs. Do not hand-edit one.**
 
 ## Licence: CC-BY 4.0
 
@@ -37,6 +23,31 @@ The licence is also written inside each file, in the glTF copyright field. A
 binary gets copied out of a dependency tree and passed around; a string in the
 file is the only way terms travel with it.
 
+## What in these files is not ours
+
+The difference is the mesh. Every character here carries one *canonical*
+topology that other people published, fitted to that character's face — the
+geometry is no longer authored per face, which is what makes a landmark table
+the only thing that distinguishes one file from the next. **The obligations
+below travel with every file, so they are named here and again in each one's
+glTF copyright field.** Neither one restricts what the rest of this package is
+licensed for.
+
+- **The face shell is MediaPipe's canonical face mesh** — Copyright The
+  MediaPipe Authors, **Apache License 2.0**, the full text in
+  `LICENSE-APACHE-2.0` at the package root. **Modified**: the triangles closing
+  the eyes and the lips are removed so a blink and a viseme have an opening to
+  be; every edge is subdivided once; rings are appended outside its face oval to
+  reach the hair and the neck; and every vertex is moved onto landmarks measured
+  from a photograph, which is what makes it a face rather than the reference
+  head. What survives unmodified is the topology — which vertex is which point,
+  and what joins them.
+- **The dental arch is fitted from ICT-FaceKit** — Copyright (c) 2020 USC
+  Institute for Creative Technologies, **MIT**, the same terms as this package's
+  own `LICENSE`. What was taken is a measurement rather than geometry: the
+  curvature of its upper arch, read off its generic head and carried here as the
+  coefficients of a polynomial. None of its mesh is in this file.
+
 ## The faces are synthetic
 
 Every character began as an image from a generative model — OpenAI's and

package/client/internal.ts

@@ -66,6 +66,10 @@ export {
   avatarFrame,
   createSvgRig,
   shapeFor,
+  // The one number that says how far the mandible falls for a given aperture.
+  // Anything composing a mouth pose without `shapeFor` — a retarget, a driver —
+  // needs it, and the amplitudes behind the lips are calibrated at it.
+  JAW_OF_OPEN,
   normalizeCues,
   textToCues,
   ARPABET_TO_VISEME,

package/client/supports.ts

@@ -1,13 +1,12 @@
 /**
- * `supports` for every avatar this package ships — the SVG faces and the six
- * canvas identities alike.
+ * `supports` for every avatar this package ships.
  *
- * It is one constant and one file because they are one renderer: the canvas
- * avatars mount the same mixer with the same clip library, so a second list
- * would be the same list with a second chance to be wrong. It is not in
+ * It is one constant and one file because they are one renderer: every avatar
+ * mounts the same mixer with the same clip library, so a second list would be
+ * the same list with a second chance to be wrong. It is not in
  * `createAvatar.ts`, where the type is documented, because a value is imported
- * for real — reading it from there would pull `peep`'s drawing into a canvas
- * avatar's bundle.
+ * for real — reading it from there would pull `peep`'s drawing into every
+ * consumer's bundle.
  *
  * The two required ids first, then this renderer's own catalogue. `ACTION_IDS`
  * already carries `RESPONSE_INTERRUPTED` as this renderer's shape for it, so

package/client/three/assets.ts

@@ -9,6 +9,7 @@
  * only reader is `/internal/three`, a separate entry point that ships nothing.
  */
 import { TANYA_GLB } from "./tanya-asset.js";
+import { TANVI_GLB } from "./tanvi-asset.js";
 import { TESS_GLB } from "./tess-asset.js";
 import { TARA_GLB } from "./tara-asset.js";
 import { TUSHAR_GLB } from "./tushar-asset.js";
@@ -18,6 +19,7 @@ export const ASSETS = Object.freeze({
   tushar: TUSHAR_GLB,
   tanya: TANYA_GLB,
   tess: TESS_GLB,
+  tanvi: TANVI_GLB,
 });
 
 /** Every compiled character, in build order. */

package/client/three/budgets.ts

@@ -23,5 +23,5 @@ export const HARD_BUDGET = Object.freeze({
   triangles: 60_000,
   drawCalls: 30,
   bones: 40,
-  morphTargets: 40,
+  morphTargets: 45,
 });