@laplace.live/persona-sdk 1.0.0 → 1.2.0

package/dist/wire/schemas.js

@@ -2,6 +2,7 @@ import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../values/controller.js";
 import { isRecord } from "../values/guards.js";
 import { SPEECH_URL_MAX_LENGTH, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH } from "../values/limits.js";
+import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_GAIN_MAX, LIP_SYNC_MODES, LIP_SYNC_NOISE_GATE_MIN, LIP_SYNC_PHONEMES, LIP_SYNC_SMOOTHING_MAX, } from "../values/lipsync.js";
 import { ASSET_KINDS, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KINDS } from "./types.js";
 // Runtime validation for the request side of the wire. Schemas exist for the
 // methods whose params the app's main process consumes directly; methods without
@@ -10,6 +11,25 @@ import { ASSET_KINDS, POSE_SOURCE_IDS, TRACKING_SOURCE_IDS, TRACKING_SOURCE_KIND
 // the app heals them into shape server-side.
 const nonEmpty = z.string().min(1);
 const port = z.number().int().min(1).max(65535);
+const lipSyncCalibration = z.discriminatedUnion('action', [
+    z.object({ action: z.enum(LIP_SYNC_CALIBRATION_ACTIONS) }),
+    z.object({ action: z.literal('record'), phoneme: z.enum(LIP_SYNC_PHONEMES) }),
+]);
+const lipSyncPatch = z.object({
+    enabled: z.boolean().optional(),
+    deviceId: z.string().optional(),
+    gain: z.number().min(0).max(LIP_SYNC_GAIN_MAX).optional(),
+    noiseGate: z.number().min(LIP_SYNC_NOISE_GATE_MIN).max(0).optional(),
+    smoothing: z.number().min(0).max(LIP_SYNC_SMOOTHING_MAX).optional(),
+});
+const mediapipePatch = z.object({
+    deviceId: z.string().optional(),
+    mirror: z.boolean().optional(),
+    face: z.boolean().optional(),
+    hands: z.boolean().optional(),
+    body: z.boolean().optional(),
+    delegate: z.enum(['CPU', 'GPU']).optional(),
+});
 export const InjectTargetSchema = z.object({
     type: z.enum(['input', 'live2d-param', 'vrm-expression']),
     id: nonEmpty,
@@ -20,6 +40,7 @@ export const InjectEntrySchema = InjectTargetSchema.extend({
     weight: z.number().min(0).max(1).optional(),
 });
 export const SettingsPatchSchema = z.object({
+    lipSync: lipSyncPatch.optional(),
     controller: z.object({ enabled: z.boolean().optional() }).optional(),
     window: z.object({ alwaysOnTop: z.boolean().optional() }).optional(),
     ui: z.object({ trayVisible: z.boolean().optional() }).optional(),
@@ -56,6 +77,11 @@ const speechUrl = z
     }
 }, 'url must be http(s) or data:audio/*');
 export const requestSchemas = {
+    'lipSync.state': z.object({}),
+    'lipSync.configure': lipSyncPatch,
+    'lipSync.restart': z.object({}),
+    'lipSync.calibrate': lipSyncCalibration,
+    'instance.setLipSync': z.object({ instanceId: nonEmpty.optional(), mode: z.enum(LIP_SYNC_MODES) }),
     'registry.thumbnail': z.object({ kind: z.enum(['model', 'asset']), id: nonEmpty }),
     'controller.rename': z.object({ slot: z.number().int().positive(), name: z.string() }),
     'controller.setDeadZone': z.object({
@@ -96,6 +122,7 @@ export const requestSchemas = {
         name: z.string().optional(),
         phoneIp: nonEmpty.nullable().optional(),
         port: port.optional(),
+        mediapipe: mediapipePatch.optional(),
     }),
     'tracking.updateSource': z.object({
         id: nonEmpty,
@@ -103,6 +130,7 @@ export const requestSchemas = {
         enabled: z.boolean().optional(),
         phoneIp: nonEmpty.nullable().optional(),
         port: port.optional(),
+        mediapipe: mediapipePatch.optional(),
     }),
     'tracking.removeSource': z.object({ id: nonEmpty }),
     'model.register': z.object({ path: nonEmpty }),

package/dist/wire/types.d.ts

@@ -1,6 +1,9 @@
 import type { ControllerConfig } from '../values/controller.ts';
+import type { EFFECT_SCOPES } from '../values/effect-schema.ts';
 import { type ArkitInputName } from '../values/arkit.ts';
 import { type BaseControllerInputName, type ControllerInputName, type ControllerMovementConfig } from '../values/controller.ts';
+import { type HandInputName } from '../values/hands.ts';
+import { type LipSyncConfig, type LipSyncMode, type VoiceInputName } from '../values/lipsync.ts';
 export type ModelFormat = 'live2d' | 'vrm';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
@@ -139,6 +142,10 @@ export interface SceneModelItem {
     instanceId: string;
     ref: ModelRef;
     visible: boolean;
+    /** Independent effects on this source, before scene effects; WebGPU only. */
+    effects: LayerEffects;
+    /** Added layer effects, including disabled rows whose tuning is retained. */
+    effectLayers: LayerEffectKey[];
     /**
      * Face source tracking this instance ({@link TrackingSourceConfig.id}); null = its face is untracked.
      * A dangling or disabled id behaves as null. One source may track several instances (mirroring).
@@ -146,6 +153,12 @@ export interface SceneModelItem {
     faceSourceId: string | null;
     /** Body source tracking this instance; null = its pose is untracked. New instances bind to each channel's default source. */
     poseSourceId: string | null;
+    /** Hand source tracking this instance; null leaves hands untracked. */
+    handSourceId: string | null;
+    /** Track wrists and arms, or only fingers while the body source owns the arms. */
+    handTrackingMode: HandTrackingMode;
+    /** Whether microphone lipsync drives this model, independently of the face source assignment. */
+    lipSyncMode: LipSyncMode;
     /** Opt-in controller movement, independent of parameter/bone bindings; disabled by default. */
     controllerMovement: ControllerMovementConfig;
     live2d: ScreenPlacement;
@@ -257,6 +270,10 @@ export interface SceneObjectItem {
     instanceId: string;
     name: string;
     visible: boolean;
+    /** Independent effects on this source, before scene effects; WebGPU only. */
+    effects: LayerEffects;
+    /** Added layer effects, including disabled rows whose tuning is retained. */
+    effectLayers: LayerEffectKey[];
     space: ObjectSpace;
     content: ObjectContent;
     place2d: Place2D;
@@ -279,9 +296,6 @@ export interface SceneBackground {
     color: string;
     imageAssetId: string | null;
 }
-export interface SceneBehavior {
-    lookAtCursor: boolean;
-}
 /** VRM stage framing: the camera moves, the model does not. Angles in radians, distance in world units. */
 export interface OrbitTransform {
     azimuth: number;
@@ -341,28 +355,35 @@ export interface SceneFog {
 }
 /** Display transform applied after the scene renders. `none` keeps colors exactly as authored. */
 export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
-/**
- * Glow around bright pixels, with anamorphic streak flares on the side
- * (VTube Studio's Beautify-based bloom). `threshold` is the luminance floor;
- * `radius` widens the halo.
- */
+/** Highlight glow in normal, streak, or star mode; color selection applies only to layer effects. */
 export interface SceneBloom {
     enabled: boolean;
+    mode: 'normal' | 'streak' | 'star';
+    /** UI offset: the glow's brightness multiplier is 1 + intensity. */
     intensity: number;
     threshold: number;
+    thresholdSmooth: number;
     radius: number;
-    /** Halo tint (hex); white is untinted. */
+    saturation: number;
+    /** Glow color (hex); white is untinted. */
     tint: string;
-    /** Anamorphic streak strength; 0 keeps the streak passes out of the graph. */
-    streak: number;
-    /** Luminance floor for the streak's own bright pass. */
-    streakThreshold: number;
-    /** Streak axis in degrees: 0 horizontal, ±90 vertical (VTS's vertical toggle, continuous). */
-    streakAngle: number;
-    /** Streak tint (hex); classic anamorphic flares are light blue. */
-    streakTint: string;
-    /** Darkens the avatar under the glow so highlights pop (VTS's model darken), 0..1. */
-    darken: number;
+    opacity: number;
+    starRays: number;
+    starAngle: number;
+    selectColors: boolean;
+    invertColors: boolean;
+    /** Shared saturation/brightness tolerance; hue tolerance is fixed at 0.03. */
+    colorTolerance: number;
+    color1: string;
+    color2: string;
+    color3: string;
+    color4: string;
+    color5: string;
+    color1Enabled: boolean;
+    color2Enabled: boolean;
+    color3Enabled: boolean;
+    color4Enabled: boolean;
+    color5Enabled: boolean;
 }
 /**
  * Cinematic soft-focus veil (Shoost's diffusion, a Kino bloom variant): the
@@ -396,6 +417,116 @@ export interface SceneColorGrade {
     /** White balance along green↔magenta, −100..100 — the axis `temperature` leaves alone. */
     tint: number;
 }
+/** Master and per-channel input/output levels; RGB channels run before master levels. */
+export interface EffectLevels {
+    enabled: boolean;
+    inputBlack: number;
+    inputWhite: number;
+    inputGamma: number;
+    outputBlack: number;
+    outputWhite: number;
+    inputBlackR: number;
+    inputWhiteR: number;
+    inputGammaR: number;
+    outputBlackR: number;
+    outputWhiteR: number;
+    inputBlackG: number;
+    inputWhiteG: number;
+    inputGammaG: number;
+    outputBlackG: number;
+    outputWhiteG: number;
+    inputBlackB: number;
+    inputWhiteB: number;
+    inputGammaB: number;
+    outputBlackB: number;
+    outputWhiteB: number;
+}
+/** Color wheels in lift/gamma/gain or shadows/midtones/highlights mode. */
+export interface EffectColorWheels {
+    enabled: boolean;
+    mode: 'liftGammaGain' | 'shadowsMidtonesHighlights';
+    lift: number;
+    liftColor: string;
+    gamma: number;
+    gammaColor: string;
+    gain: number;
+    gainColor: string;
+    shadows: number;
+    shadowsColor: string;
+    midtones: number;
+    midtonesColor: string;
+    highlights: number;
+    highlightsColor: string;
+    shadowLimit: number;
+    highlightLimit: number;
+}
+/** Six hue bands; hue offsets are degrees, other offsets are -1..1. */
+export interface EffectColorShift {
+    enabled: boolean;
+    hueRed: number;
+    saturationRed: number;
+    luminanceRed: number;
+    luminanceSaturationRed: number;
+    hueYellow: number;
+    saturationYellow: number;
+    luminanceYellow: number;
+    luminanceSaturationYellow: number;
+    hueGreen: number;
+    saturationGreen: number;
+    luminanceGreen: number;
+    luminanceSaturationGreen: number;
+    hueCyan: number;
+    saturationCyan: number;
+    luminanceCyan: number;
+    luminanceSaturationCyan: number;
+    hueBlue: number;
+    saturationBlue: number;
+    luminanceBlue: number;
+    luminanceSaturationBlue: number;
+    hueMagenta: number;
+    saturationMagenta: number;
+    luminanceMagenta: number;
+    luminanceSaturationMagenta: number;
+}
+/** Preserve selected colors while adjusting saturation outside their HSV ranges. */
+export interface EffectSelectColors {
+    enabled: boolean;
+    invert: boolean;
+    /** Hue distance in turns around the color wheel. */
+    hueRange: number;
+    saturationRange: number;
+    brightnessRange: number;
+    /** Saturation offset outside the selection; -1 makes it monochrome. */
+    saturation: number;
+    blend: number;
+    color1: string;
+    color1Enabled: boolean;
+    color2: string;
+    color2Enabled: boolean;
+    color3: string;
+    color3Enabled: boolean;
+    color4: string;
+    color4Enabled: boolean;
+    color5: string;
+    color5Enabled: boolean;
+    color6: string;
+    color6Enabled: boolean;
+    color7: string;
+    color7Enabled: boolean;
+    color8: string;
+    color8Enabled: boolean;
+    color9: string;
+    color9Enabled: boolean;
+    color10: string;
+    color10Enabled: boolean;
+}
+/** Gaussian or disk-shaped bokeh blur in output pixels. */
+export interface EffectBlur {
+    enabled: boolean;
+    radius: number;
+    mode: 'gaussian' | 'bokeh';
+    highQuality: boolean;
+}
 /** Lens fringing that grows toward frame edges (Unity PPv2's curve, the one VTube Studio wraps). */
 export interface SceneChromaticAberration {
     enabled: boolean;
@@ -476,55 +607,33 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
-/**
- * Screen-space rim light along the avatar silhouette (Shoost's layer rim light,
- * VTube Studio's backlight): coverage edges facing `angle` catch the glow.
- * Silhouette-driven — an opaque skybox leaves no edges to light.
- */
+/** Blend modes shared with Shoost's rim light. */
+export type EffectBlendMode = 'normal' | 'darken' | 'multiply' | 'colorBurn' | 'linearBurn' | 'add' | 'lighten' | 'screen' | 'colorDodge' | 'overlay' | 'softLight' | 'hardLight' | 'vividLight' | 'linearLight' | 'pinLight' | 'hardMix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity';
+/** Directional silhouette lighting, optionally sharpened or applied to both sides. */
 export interface SceneRim {
     enabled: boolean;
+    mode: 'single' | 'double' | 'sharpenSingle' | 'sharpenDouble';
+    blendMode: EffectBlendMode;
     /** Rim tint (hex). */
     color: string;
-    /** Glow strength; past 1 overdrives into bloom territory. */
-    intensity: number;
-    /** Rim width in output pixels. */
+    /** Normalized rim width, 0..1. */
     size: number;
-    /** Edge falloff: 0 a crisp line, 1 a wide soft fade. */
-    softness: number;
-    /** Light direction in degrees, compass-style: 0 lights from above, 90 from the right. */
+    brightness: number;
+    contrast: number;
+    /** Light direction in degrees, -180..180. */
     angle: number;
-    /** How much the edge opposite the light glows too (0 to 1). */
-    bothSides: number;
-    /** Uniform glow on every edge regardless of `angle` (VTS's main backlight strength), 0..1. */
-    omni: number;
-    /** Ceiling the glow lightens pixels toward: 1 screens to white, lower protects highlights. */
-    brightnessLimit: number;
-    /** Darkens the avatar under the glow for contrast (VTS's model darken), 0..1. */
-    darken: number;
+    opacity: number;
 }
-/**
- * Contour band hugging the avatar silhouette, with an optional animated stripe
- * pattern scrolling through it (VTube Studio's backlight outline). Silhouette-
- * driven like the rim light — it needs coverage edges to trace.
- */
+/** Solid silhouette border with selectable edge sampling quality. */
 export interface SceneOutline {
     enabled: boolean;
+    quality: 'low' | 'medium' | 'high';
     /** Outline color (hex). */
     color: string;
-    /** Stripe color (hex), painted over `color` where the stripe pattern lands. */
-    stripeColor: string;
-    /** Band thickness in output pixels. */
+    /** Normalized border thickness, 0..1. */
     size: number;
     /** Outline opacity 0..1. */
     opacity: number;
-    /** Stripe density: 0 broad bands, 1 fine candy stripes. */
-    stripes: number;
-    /** Stripe visibility: 0 a solid outline, 1 full-strength stripes. */
-    stripeMix: number;
-    /** Stripe scroll speed; negative reverses the direction. */
-    stripeSpeed: number;
-    /** Bends the stripes into waves: 0 straight, 1 strongly curled. */
-    stripeCurve: number;
 }
 /**
  * Hard-edged copy of the avatar silhouette cast behind it (VTube Studio's
@@ -540,6 +649,8 @@ export interface SceneDropShadow {
     offsetX: number;
     /** Vertical offset, percent of frame height; positive casts down. */
     offsetY: number;
+    /** Gaussian shadow softness in output pixels; 0 keeps a hard edge. */
+    size: number;
 }
 /** Compute-driven 3D rainfall: motion-blur streaks fall through the scene and splash on models, props, and the floor. */
 export interface SceneRain {
@@ -577,23 +688,19 @@ export interface SceneSnow {
     /** Flake opacity. */
     opacity: number;
 }
-/**
- * Post-processing over the rendered 3D frame. Everything off skips the effect
- * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
- * the top level so tooling (defaults, healing, editors) can walk the effect
- * registry generically. Grouping is a panel concern, not a data one.
- */
-export interface SceneEffects {
-    toneMapping: SceneToneMapping;
-    /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
-    exposure: number;
+/** Toggle effects independent of the scene or layer that owns their values. */
+export interface EffectValues {
     bloom: SceneBloom;
     diffusion: SceneDiffusion;
     vignette: SceneVignette;
     color: SceneColorGrade;
+    levels: EffectLevels;
+    colorWheels: EffectColorWheels;
+    colorShift: EffectColorShift;
+    selectColors: EffectSelectColors;
+    blur: EffectBlur;
     chromaticAberration: SceneChromaticAberration;
     grain: SceneFilmGrain;
-    lut: SceneLut;
     dof: SceneDepthOfField;
     rim: SceneRim;
     outline: SceneOutline;
@@ -604,12 +711,29 @@ export interface SceneEffects {
     rain: SceneRain;
     snow: SceneSnow;
 }
-/** Keys of {@link SceneEffects} that follow the `{ enabled } + params` pattern. */
-export type ToggleEffectKey = {
-    [K in keyof SceneEffects]: SceneEffects[K] extends {
-        enabled: boolean;
-    } ? K : never;
-}[keyof SceneEffects];
+export type EffectKey = keyof EffectValues;
+export type EffectScope = 'scene' | 'layer';
+/** Effect availability comes from the catalog, independently for each scope. */
+export type EffectKeyForScope<S extends EffectScope> = {
+    [K in EffectKey]: S extends (typeof EFFECT_SCOPES)[K][number] ? K : never;
+}[EffectKey];
+export type SceneEffectKey = EffectKeyForScope<'scene'>;
+/** Scene toggle keys; retained for existing SDK consumers. */
+export type ToggleEffectKey = SceneEffectKey;
+/** Scene-wide toggles plus the display transform and color lookup table. */
+export interface SceneEffects extends Pick<EffectValues, SceneEffectKey> {
+    toneMapping: SceneToneMapping;
+    /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
+    exposure: number;
+    lut: SceneLut;
+}
+/** Source-local effects, evaluated before the source joins the scene composition. */
+export type LayerEffectKey = EffectKeyForScope<'layer'>;
+export type LayerEffects = Pick<EffectValues, LayerEffectKey>;
+/** Omitted effects and parameters retain their current values. */
+export type LayerEffectsPatch = {
+    [K in LayerEffectKey]?: Partial<LayerEffects[K]>;
+};
 /**
  * A 3D set's own suggested look — the fog and post settings it was authored against,
  * read from its root `LAPLACE_environment` extension and held on the scene for every client.
@@ -680,7 +804,6 @@ export interface Scene {
     /** Hotkey target and the default instance for model-scoped methods. null only when `items` holds no model. */
     primaryInstanceId: string | null;
     background: SceneBackground;
-    behavior: SceneBehavior;
     vrmCamera: SceneCamera;
     /** Array order is display order only; live lights are keyed by id. */
     lights: SceneLight[];
@@ -701,7 +824,6 @@ export interface SceneState {
  */
 export interface ScenePatch {
     background?: SceneBackground;
-    behavior?: SceneBehavior;
     vrmCamera?: SceneCamera;
     lights?: SceneLight[];
     environment?: SceneEnvironment;
@@ -710,7 +832,7 @@ export interface ScenePatch {
  * App-level features a client gates on (never version-sniff): `hello` and
  * `app.info` report them — the per-app mirror of {@link InstanceRuntime.capabilities}.
  */
-export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts", "controllers", "model-editing", "asset-inspection"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "shortcuts", "controllers", "model-editing", "asset-inspection", "layer-effects"];
 export type AppCapability = (typeof APP_CAPABILITIES)[number];
 export declare function isAppCapability(v: unknown): v is AppCapability;
 /** What a loaded model instance can do; absent capabilities answer `unsupported-for-format`. */
@@ -817,9 +939,30 @@ export type PoseSourceId = (typeof POSE_SOURCE_IDS)[number];
 export type TrackingStatus = 'off' | 'waiting' | 'tracking' | 'no-face';
 export type PoseStatus = 'off' | 'waiting' | 'tracking';
 /** Every protocol a tracking source instance can speak; face and body kinds. */
-export declare const TRACKING_SOURCE_KINDS: readonly ["persona-ios", "ifacialmocap", "vts-ios", "vmc", "mocopi"];
+export declare const TRACKING_SOURCE_KINDS: readonly ["persona-ios", "ifacialmocap", "vts-ios", "vmc", "mocopi", "mediapipe"];
 export type TrackingSourceKind = (typeof TRACKING_SOURCE_KINDS)[number];
-/** Whether a source kind feeds the face channel. */
+export declare const TRACKING_CHANNELS: readonly ["face", "pose", "hands"];
+export type TrackingChannel = (typeof TRACKING_CHANNELS)[number];
+/** The scene-item binding each channel reads and writes. */
+export declare const TRACKING_CHANNEL_FIELDS: {
+    readonly face: "faceSourceId";
+    readonly pose: "poseSourceId";
+    readonly hands: "handSourceId";
+};
+export declare const HAND_TRACKING_MODES: readonly ["arms", "fingers"];
+export type HandTrackingMode = (typeof HAND_TRACKING_MODES)[number];
+export declare function isHandTrackingMode(v: unknown): v is HandTrackingMode;
+/** The shared webcam source's enabled inference tasks and camera configuration. */
+export interface MediaPipeConfig {
+    deviceId: string;
+    mirror: boolean;
+    face: boolean;
+    hands: boolean;
+    body: boolean;
+    delegate: 'CPU' | 'GPU';
+}
+export declare const DEFAULT_MEDIAPIPE_CONFIG: Readonly<MediaPipeConfig>;
+/** Whether a source kind uses a network face receiver. */
 export declare function isFaceSourceKind(kind: TrackingSourceKind): kind is TrackingSourceId;
 /**
  * One configured tracking source instance. Several can run at once — one per person —
@@ -841,11 +984,27 @@ export interface TrackingSourceConfig {
      * Send Port must match). Null on persona-ios and vts-ios, whose ports the protocol fixes.
      */
     port: number | null;
+    /** Present only on the shared webcam source. */
+    mediapipe?: MediaPipeConfig;
 }
-/** Whether a source feeds the body channel — the narrowing counterpart of `isFaceSourceKind`. */
+/** Whether a source uses a network body receiver. */
 export declare function isPoseSource(source: TrackingSourceConfig): source is TrackingSourceConfig & {
     kind: PoseSourceId;
 };
+/** The channels a kind can supply; the webcam's are further gated by its task switches. */
+export declare function sourceKindChannels(kind: TrackingSourceKind): readonly TrackingChannel[];
+/** Whether this source can supply a channel; {@link sourceChannelEnabled} folds in the switches. */
+export declare function sourceSupportsChannel(source: TrackingSourceConfig, channel: TrackingChannel): boolean;
+/** The face and body master switches; they gate network sources only. */
+export interface ChannelMasters {
+    face: boolean;
+    pose: boolean;
+}
+/**
+ * Whether a source feeds a channel right now: its own switch, its task, and — for a network
+ * face or body source — the channel master. Webcam tasks and hands answer to the source switch alone.
+ */
+export declare function sourceChannelEnabled(source: TrackingSourceConfig, channel: TrackingChannel, masters: ChannelMasters): boolean;
 /**
  * Whether another source already holds `port` and would contend for it. iFacialMocap instances
  * share one socket per port (frames demux by phone); every other pairing EADDRINUSEs a listener.
@@ -865,6 +1024,8 @@ export interface StageSize {
 }
 /** The curated settings surface the API exposes — never the raw store shape. */
 export interface Settings {
+    /** Absent on hosts without microphone lipsync. */
+    lipSync?: LipSyncConfig;
     /** Absent on hosts without remote controller management. */
     controller?: ControllerConfig;
     /** `alwaysOnTop` floats the control-panel window, never the stage. */
@@ -885,13 +1046,13 @@ export interface Settings {
         renderScale?: number;
         live2dEngine?: 'pixi' | 'three';
     };
-    /** `source` mirrors the first face source's kind — the pre-multi-source field, kept for old clients. */
+    /** `enabled` gates network face sources; `source` mirrors the first one's kind for old clients. */
     tracking: {
         enabled: boolean;
         source: TrackingSourceId;
         sources: TrackingSourceConfig[];
     };
-    /** `source`/`port` mirror the first body source — the pre-multi-source fields, kept for old clients. */
+    /** `enabled` gates network body sources; `source`/`port` mirror the first one's values for old clients. */
     pose: {
         enabled: boolean;
         source: PoseSourceId;
@@ -899,6 +1060,7 @@ export interface Settings {
     };
 }
 export interface SettingsPatch {
+    lipSync?: Partial<LipSyncConfig>;
     controller?: Partial<Pick<ControllerConfig, 'enabled'>>;
     window?: {
         alwaysOnTop?: boolean;
@@ -919,11 +1081,11 @@ export interface SettingsPatch {
 declare const VTS_INPUT_NAMES: readonly ["FaceAngleX", "FaceAngleY", "FaceAngleZ", "FacePositionX", "FacePositionY", "FacePositionZ", "EyeOpenLeft", "EyeOpenRight", "EyeLeftX", "EyeLeftY", "EyeRightX", "EyeRightY", "Brows", "BrowLeftY", "BrowRightY", "MouthSmile", "MouthOpen", "MouthX", "CheekPuff", "JawOpen", "TongueOut"];
 type VtsInputName = (typeof VTS_INPUT_NAMES)[number];
 /**
- * Default input vocabulary: VTS face inputs, raw ARKit channels and controller profile 1.
+ * Default input vocabulary: face and hand inputs, raw ARKit channels and controller profile 1.
  * Additional controller profile ids are accepted by isInputName without appearing in this list.
  */
-export declare const INPUT_NAMES: readonly (VtsInputName | ArkitInputName | BaseControllerInputName)[];
-export type InputName = VtsInputName | ArkitInputName | ControllerInputName;
+export declare const INPUT_NAMES: readonly (VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName)[];
+export type InputName = VtsInputName | HandInputName | VoiceInputName | ArkitInputName | ControllerInputName;
 /** Whether an untrusted string names a tracking input — the guard every wire boundary needs. */
 export declare function isInputName(v: string): v is InputName;
 /**
@@ -951,7 +1113,7 @@ export declare function arkitTwinOf(input: InputName): BindingInput;
  * Default inputs' natural spans. Use getInputRange for a dynamically numbered controller input.
  * Head angles are degrees; the rest are unitless.
  */
-export declare const INPUT_RANGES: Record<VtsInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
+export declare const INPUT_RANGES: Record<VtsInputName | HandInputName | VoiceInputName | ArkitInputName | BaseControllerInputName, readonly [number, number]>;
 /** Natural span of any valid input, including dynamically numbered controller profiles. */
 export declare function getInputRange(name: InputName): readonly [number, number];
 /**