# HyperTwist Phase 3R Packet 3R-E TalkingHead Implementation

Created on `2026-05-13`

## Status

`Phase 3R / Packet 3R-E` is now `closed`.

This packet converts `met4citizen/TalkingHead` from the retained embodied companion anchor into a landed first-party HyperTwist embodied companion, narration, lip-sync, gesture, subtitle, and avatar-embed lane.

It does not reopen `Phase 0R`, `Phase 1R`, or `Phase 2R-B`.

Those earlier packets still own source-value extraction, retained-set routing, and ownership boundaries.

This packet owns the next question instead:

- what first-party implementation actually landed
- which donor value was realized
- what remains explicitly out of scope for this lane
- what validation was completed
- what the next bounded implementation move is after this landing

## Authority order

For future work on the `met4citizen/TalkingHead` lane, read in this order:

1. this packet for first-party landing scope, accepted widening, and validation result
2. [HYPERTWIST_LIVE_LANES_SOURCE_AND_PRESERVATION_AUDIT_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_LIVE_LANES_SOURCE_AND_PRESERVATION_AUDIT_2026-05-13.md:1) for live-lane preserve posture
3. [HYPERTWIST_PHASE_2R_PACKET_2R_B_OWNERSHIP_AND_ACCEPTANCE_CONTRACT_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_PHASE_2R_PACKET_2R_B_OWNERSHIP_AND_ACCEPTANCE_CONTRACT_2026-05-13.md:1) for ownership boundaries and pre-widening acceptance markers
4. [HYPERTWIST_PHASE_0R_PACKET_0R_B_EVALUATION_2026-05-12.md](C:/HyperTwist/docs/HYPERTWIST_PHASE_0R_PACKET_0R_B_EVALUATION_2026-05-12.md:1) for source-value extraction and non-promotion rationale
5. [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1) for license and notice obligations

## Packet licensing snapshot

- `met4citizen/TalkingHead`: `MIT`
- sample avatars, media, and external TTS or JWT-backed service flows are separate provenance and deployment questions, not part of the code-license grant widened by this packet

Checked local notice surfaces:

- [LICENSE](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/LICENSE:1) currently carries the MIT grant for the checked code
- [README.md](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/README.md:1) currently documents example avatar, voice-service, and demo-shell assumptions that remain outside the shippable first-party owner

## Packet result

`3R-E` lands `met4citizen/TalkingHead` as:

- `implemented_live_permissive`
- `landed_permissive_preserve`

Current portfolio effect:

- curated HyperTwist shallow-eval set: `71`
- currently verified live in checked Unreal surfaces: `11`
- permissive live lanes: `10`
- restrictive live clean-room lanes: `1`
- active non-live implementation-board rows: `48`

## Donor source surfaces read

The source read for this widening remained bounded to the retained embodied companion, queued narration, subtitle and viseme timing, avatar-only embedding, retargeting, gesture and mood presentation, streaming playback, and listening-threshold domains:

- [LICENSE](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/LICENSE:1)
- [README.md](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/README.md:1)
- [package.json](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/package.json:1)
- [modules/talkinghead.mjs](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/modules/talkinghead.mjs:1)
- [modules/retargeter.mjs](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/modules/retargeter.mjs:1)
- [modules/lipsync-en.mjs](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/modules/lipsync-en.mjs:1)
- [modules/playback-worklet.js](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/modules/playback-worklet.js:1)
- [examples/azure-audio-streaming.html](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/examples/azure-audio-streaming.html:1)
- [tests/streaming-tests.html](C:/Workspaces/HyperTwist/mirrors/permissive/met4citizen/TalkingHead/tests/streaming-tests.html:1)

## First-party landing surfaces

The landed first-party Unreal surfaces are:

- [HyperTwistTrainingCompanionLibrary.h](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCompanionLibrary.h:1)
- [HyperTwistTrainingCompanionLibrary.cpp](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCompanionLibrary.cpp:1)
- [HyperTwistTrainingRuntimeLibrary.h](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h:1)
- [HyperTwistTrainingRuntimeLibrary.cpp](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp:1)
- [hypertwist-reference-incorporation-targets.json](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/hypertwist-reference-incorporation-targets.json:1)
- [hypertwist-catalog-materialization-summary.json](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/hypertwist-catalog-materialization-summary.json:1)
- [met4citizen-talkinghead-reference-pages.jsonl](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/raw-extracts/met4citizen-talkinghead-reference-pages.jsonl:1)

## Landed implementation scope

What landed:

- a first-party compiled embodied companion reference bundle with explicit speech-input, queue lifecycle, narration, subtitle, viseme, gesture, mood, avatar-embed, listening, and vendor-boundary contracts
- a first-party runtime-library access layer for the bundled companion lane, including narration-contract lookup, avatar-embed lookup, vendor-boundary lookup, and subtitle checklist export
- bundled first-party reference targets for narration, subtitle and viseme synchronization, avatar-only embedding, gesture and mood presentation, streaming and listening lifecycle, and TTS or asset adapter boundaries
- bundled raw source-reference capture for the new `met4citizen/TalkingHead` reference-target families

What that means in practice:

- `met4citizen/TalkingHead` now owns the landed permissive embodied companion, narration, lip-sync, gesture, subtitle, and avatar-embed lane in HyperTwist
- the landed surface is a first-party Unreal companion contract and runtime API, not a vague future donor note
- sample avatars, direct vendor shells, and external TTS wiring remain explicit boundary surfaces rather than silently becoming product ownership

## Preserved landed value

The donor value that was actually promoted is:

- explicit queued narration behavior with voice parameters, markers, subtitles, viseme timing, and mood or gesture cues
- explicit avatar-only embed behavior for bounded external-scene companion presence with camera-safe composition and retargeted motion
- explicit gesture, mood, and pose presentation surfaces for acknowledgement, focus, celebration, and supportive coaching states
- explicit streaming playback and listening-threshold lifecycle states with queue-buffer and underrun metrics
- explicit vendor-adapter boundaries so voice-service wiring, avatar assets, and donor example shells remain replaceable and out of product-core ownership

## Excluded or non-promotion boundary

Do not promote this lane into:

- generic speech-engine ownership
- external TTS vendor lock-in
- generic avatar-product or character-platform ownership
- sample avatar or donor media shipping assumptions
- donor example-page shell, camera page, or tutorial framing

Rationale:

- this repo was retained and widened because it was the strongest bounded embodied companion donor in the set
- its highest value is queue discipline, avatar embedding, subtitle and viseme timing, and coach-facing expression control, not host-application or vendor-product ownership
- the vendor and asset seams remain useful precisely because they stay replaceable beneath the landed first-party owner

## Acceptance markers satisfied

The `2R-B` acceptance markers for this row are now satisfied in first-party Unreal surfaces:

- a first-party narration event contract exists with speech inputs, queue lifecycle states, output tags, and exclusions
- a first-party avatar-embedding contract exists with scene and camera bindings plus explicit gesture and mood support
- a first-party vendor-adapter boundary exists with replaceable voice-service and asset fields kept separate from first-party coach-owned fields
- a first-party streaming and listening lifecycle exists with queue, stream-buffer, underrun, and microphone-threshold posture

## Validation

Validation completed for this packet:

- `git diff --check` passed apart from CRLF conversion warnings
- JSON validation passed for the updated materialized-catalog files and workspace manifest
- Unreal build succeeded with:
  - `C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat UnrealHyperTwistEditor Win64 Development C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.uproject -WaitMutex -NoHotReloadFromIDE`

Build result:

- `Succeeded` on `2026-05-13`

## Next move

The next bounded move is `Phase 3R-F`:

- widen `mrdoob/three.js`, `pmndrs/react-three-fiber`, and `pmndrs/xr` as the retained browser `3D`, XR session, and spatial-support lane
- keep the newly landed `met4citizen/TalkingHead` embodied companion lane on preserve-and-enhance footing rather than treating it as an open donor candidate again
