@laplace.live/persona-sdk 1.22.0 → 1.23.0

package/dist/values/effect-schema.js

@@ -147,11 +147,12 @@ export const EFFECT_SPECS = {
     blur: {
         radius: { default: 8, min: 0, max: 64, step: 0.5, unit: 'px' },
     },
+    // Intensity and Threshold take Warudo's Camera Bloom units; with Radius, the defaults are its look at 1080p.
     bloom: {
-        intensity: { default: 0, min: 0, max: 10, step: 0.01 },
-        threshold: { default: 0.5, min: 0, max: 2, step: 0.01 },
+        intensity: { default: 0.1, min: 0, max: 10, step: 0.01 },
+        threshold: { default: 0.75, min: 0, max: 5, step: 0.01 },
         thresholdSmooth: { default: 0, min: 0, max: 1, step: 0.01 },
-        radius: { default: 1, min: 0, max: 6, step: 0.01 },
+        radius: { default: 3, min: 0, max: 6, step: 0.01 },
         saturation: { default: 0, min: -1, max: 1, step: 0.01 },
         opacity: { default: 1, min: 0, max: 1, step: 0.01 },
         starRays: { default: 3, min: 1, max: 6, step: 1 },
@@ -308,7 +309,7 @@ export const EFFECT_COLOR_SPECS = {
         color5: { default: '#ffffff' },
     },
     rim: {
-        color: { default: '#ffffff' },
+        color: { default: '#ffeb74' },
     },
     outline: {
         color: { default: '#000000' },
@@ -394,13 +395,7 @@ export const EFFECT_ENUM_SPECS = {
     },
     blur: { mode: { default: 'gaussian', values: ['gaussian', 'bokeh'] } },
     bloom: { mode: { default: 'normal', values: ['normal', 'streak', 'star'] } },
-    rim: {
-        mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] },
-        blendMode: {
-            default: 'overlay',
-            values: EFFECT_BLEND_MODES,
-        },
-    },
+    rim: { mode: { default: 'single', values: ['single', 'double', 'sharpenSingle', 'sharpenDouble'] } },
     outline: { quality: { default: 'medium', values: ['low', 'medium', 'high'] } },
     colorWheels: { mode: { default: 'liftGammaGain', values: ['liftGammaGain', 'shadowsMidtonesHighlights'] } },
 };

package/dist/values/item-transition.d.ts

@@ -1,12 +1,14 @@
-export declare const ITEM_TRANSITION_STYLES: readonly ["glitch", "dither", "pop", "cut"];
+export declare const ITEM_TRANSITION_STYLES: readonly ["glitch", "fade", "pop", "cut"];
 export type ItemTransitionStyle = (typeof ITEM_TRANSITION_STYLES)[number];
+/** What `fade` was named while it was a dithered dissolve; hosts still accept it, as `fade`. */
+export declare const LEGACY_DITHER_STYLE = "dither";
 /** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
 export declare const ITEM_TRANSITION_DEFAULT_MS = 300;
 export declare const ITEM_TRANSITION_MAX_MS = 5000;
 export interface ItemTransition {
     /**
-     * `glitch` tears and burns through a dithered dissolve, `dither` is the plain screen-door,
-     * `pop` scales in and out, `cut` switches.
+     * `glitch` tears and burns through a dithered dissolve, `fade` fades each item by alpha as one
+     * layer, `pop` scales in and out, `cut` switches.
      */
     style: ItemTransitionStyle;
     /** Length of the ramp either way, 0–`ITEM_TRANSITION_MAX_MS`; 0 behaves as `cut`. */
@@ -16,8 +18,8 @@ export declare function defaultItemTransition(): ItemTransition;
 /** A per-call departure from the scene's item transition, for `stage.spawn`. */
 export interface SpawnTransition {
     style?: ItemTransitionStyle;
-    /** Entrance ramp, 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    /** Entrance ramp, 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration, and a `cut` ignores it. */
     inMs?: number;
-    /** Exit ramp — expiry, eviction and clears — 0–`ITEM_TRANSITION_MAX_MS`; defaults to the scene's duration. */
+    /** Exit ramp — expiry, eviction and clears — 0–`ITEM_TRANSITION_MAX_MS`; as `inMs`. */
     outMs?: number;
 }

package/dist/values/item-transition.js

@@ -1,6 +1,8 @@
 // How stage items appear and disappear — models, objects and spawned bodies alike. Per scene,
 // on `SceneEnvironment.itemTransition`; `stage.spawn` may override it per call.
-export const ITEM_TRANSITION_STYLES = ['glitch', 'dither', 'pop', 'cut'];
+export const ITEM_TRANSITION_STYLES = ['glitch', 'fade', 'pop', 'cut'];
+/** What `fade` was named while it was a dithered dissolve; hosts still accept it, as `fade`. */
+export const LEGACY_DITHER_STYLE = 'dither';
 /** One ramp length for a model switch, an object fade, or a body's entrance and exit. */
 export const ITEM_TRANSITION_DEFAULT_MS = 300;
 export const ITEM_TRANSITION_MAX_MS = 5000;

package/dist/values/limits.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, Attach, AttachDepth, CameraAnchor, CameraFollowDamping, CameraTrackTarget, EnvironmentLook, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneCameraAim, SceneCameraAimSettings, SceneCameraFocus, SceneCameraFocusSettings, SceneCameraFollow, SceneCameraFollowSettings, SceneCameraHandheld, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
+import type { AssetRef, Attach, AttachDepth, CameraAnchor, CameraFollowDamping, CameraTrackTarget, ChromaKey, EnvironmentLook, KeyableContent, ModelFormat, MToonTuning, ObjectContent, ObjectSpace, SceneCameraAim, SceneCameraAimSettings, SceneCameraFocus, SceneCameraFocusSettings, SceneCameraFollow, SceneCameraFollowSettings, SceneCameraHandheld, SceneEnvironment, SceneLight, SceneLightCameraFollowOptions, SceneLightType, ScreenPlacement, VrmPlacement } from '../wire/types.ts';
 export declare function clamp(v: number, min: number, max: number): number;
 /** Clamp to the unit interval. */
 export declare function clamp01(v: number): number;
@@ -232,6 +232,13 @@ export declare const WEB_SIZE_MAX = 7680;
 /** Web object paint-rate bounds, frames per second. */
 export declare const WEB_FPS_MIN = 1;
 export declare const WEB_FPS_MAX = 60;
+/** Chroma key tolerance bounds, OBS's 1–1000 ÷ 1000; the floor keeps the edge ramps from dividing by zero. */
+export declare const CHROMA_KEY_TOLERANCE_MIN = 0.001;
+export declare const CHROMA_KEY_TOLERANCE_MAX = 1;
+/** OBS's Chroma Key defaults: green, similarity 400, smoothness 80, spill reduction 100. */
+export declare const DEFAULT_CHROMA_KEY: ChromaKey;
+/** Whether a chroma key can reach the content's pixels: image, video and webpage quads. */
+export declare function isKeyableContent(content: ObjectContent): content is KeyableContent;
 /** Text object bounds: characters, em size in px, and the box and paint extents in px. */
 export declare const TEXT_LENGTH_MAX = 10000;
 export declare const TEXT_SIZE_MIN = 4;

package/dist/values/limits.js

@@ -364,6 +364,21 @@ export const WEB_SIZE_MAX = 7680;
 /** Web object paint-rate bounds, frames per second. */
 export const WEB_FPS_MIN = 1;
 export const WEB_FPS_MAX = 60;
+/** Chroma key tolerance bounds, OBS's 1–1000 ÷ 1000; the floor keeps the edge ramps from dividing by zero. */
+export const CHROMA_KEY_TOLERANCE_MIN = 0.001;
+export const CHROMA_KEY_TOLERANCE_MAX = 1;
+/** OBS's Chroma Key defaults: green, similarity 400, smoothness 80, spill reduction 100. */
+export const DEFAULT_CHROMA_KEY = {
+    enabled: false,
+    color: '#00ff00',
+    similarity: 0.4,
+    smoothness: 0.08,
+    spill: 0.1,
+};
+/** Whether a chroma key can reach the content's pixels: image, video and webpage quads. */
+export function isKeyableContent(content) {
+    return content.kind === 'image' || content.kind === 'video' || content.kind === 'web';
+}
 /** Text object bounds: characters, em size in px, and the box and paint extents in px. */
 export const TEXT_LENGTH_MAX = 10_000;
 export const TEXT_SIZE_MIN = 4;

package/dist/wire/schemas/requests.d.ts

@@ -7,8 +7,8 @@ export declare const SceneTransitionSchema: z.ZodObject<{
         image: "image";
         video: "video";
         circle: "circle";
-        cut: "cut";
         fade: "fade";
+        cut: "cut";
         wipe: "wipe";
     }>;
     durationMs: z.ZodNumber;
@@ -329,12 +329,13 @@ export declare const requestSchemas: {
         scale: z.ZodOptional<z.ZodNumber>;
         ttlMs: z.ZodOptional<z.ZodNumber>;
         transition: z.ZodOptional<z.ZodObject<{
-            style: z.ZodOptional<z.ZodEnum<{
+            style: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
                 pop: "pop";
                 glitch: "glitch";
-                dither: "dither";
+                fade: "fade";
                 cut: "cut";
-            }>>;
+                dither: "dither";
+            }>, z.ZodTransform<"pop" | "glitch" | "fade" | "cut", "pop" | "glitch" | "fade" | "cut" | "dither">>>;
             inMs: z.ZodOptional<z.ZodNumber>;
             outMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;

package/dist/wire/schemas/requests.js

@@ -1,7 +1,7 @@
 import * as z from 'zod';
 import { CONTROLLER_DEAD_ZONE_MAX } from "../../values/controller.js";
 import { isRecord } from "../../values/guards.js";
-import { ITEM_TRANSITION_STYLES } from "../../values/item-transition.js";
+import { ITEM_TRANSITION_STYLES, LEGACY_DITHER_STYLE } from "../../values/item-transition.js";
 import { OBJECT_ADD_MANY_MAX, SCENE_COLOR_RE, SPEECH_URL_MAX_LENGTH, STAGE_CAPTURE_EDGE_MAX, STAGE_CAPTURE_EDGE_MIN, STORAGE_KEY_MAX_LENGTH, STORAGE_VALUE_MAX_LENGTH, } from "../../values/limits.js";
 import { LIP_SYNC_CALIBRATION_ACTIONS, LIP_SYNC_MODES, LIP_SYNC_PHONEMES, } from "../../values/lipsync.js";
 import { SCENE_TRANSITION_DURATION_MAX_MS, SCENE_TRANSITION_DURATION_MIN_MS, SCENE_TRANSITION_FADE_DEFAULT_MS, SCENE_TRANSITION_SWITCH_POINT_MAX, SCENE_TRANSITION_SWITCH_POINT_MIN, SCENE_TRANSITION_TYPES, } from "../../values/scene-transition.js";
@@ -168,7 +168,11 @@ export const requestSchemas = {
         ttlMs: z.number().optional(),
         transition: z
             .object({
-            style: z.enum(ITEM_TRANSITION_STYLES).optional(),
+            // Older clients still send `fade` by its old name.
+            style: z
+                .enum([...ITEM_TRANSITION_STYLES, LEGACY_DITHER_STYLE])
+                .transform(style => (style === LEGACY_DITHER_STYLE ? 'fade' : style))
+                .optional(),
             inMs: z.number().optional(),
             outMs: z.number().optional(),
         })

package/dist/wire/types.d.ts

@@ -239,10 +239,28 @@ export interface TextFont {
     /** CSS `font-stretch` percent; 100 is normal. */
     stretch: number;
 }
+/**
+ * Keys one color out of an image, video or webpage, as OBS's Chroma Key filter does. Distance is
+ * BT.709 chroma at studio swing, so brightness never counts, and the three tolerances are OBS's
+ * slider values ÷ 1000.
+ */
+export interface ChromaKey {
+    enabled: boolean;
+    /** Hex color made transparent. */
+    color: string;
+    /** Chroma distance from `color` that turns fully transparent. */
+    similarity: number;
+    /** Distance past `similarity` over which the edge fades back to opaque. */
+    smoothness: number;
+    /** Distance past `similarity` over which the key's tint desaturates out of the edge. */
+    spill: number;
+}
 /** What an object renders. Mirrors VTube Studio's items and Warudo's screen/prop assets. */
 export type ObjectContent = {
     kind: 'image';
     assetId: string;
+    /** Absent keys nothing, as on older hosts. */
+    chromaKey?: ChromaKey;
 } | {
     kind: 'video';
     assetId: string;
@@ -251,6 +269,7 @@ export type ObjectContent = {
     volume: number;
     /** Held rather than played while shown, through a restart too; the playback position is not saved. */
     paused: boolean;
+    chromaKey?: ChromaKey;
 } | {
     kind: 'prop';
     assetId: string;
@@ -269,6 +288,7 @@ export type ObjectContent = {
     css: string;
     /** Close the page while the object is hidden and reload it on show, as an OBS browser source can. */
     shutdownWhenHidden: boolean;
+    chromaKey?: ChromaKey;
 } | {
     kind: 'capture';
     source: CaptureKind;
@@ -332,6 +352,10 @@ export type ObjectContent = {
     /** 3D: turn the text to face the camera every frame, ignoring the placement's rotation. */
     faceCamera: boolean;
 };
+/** The variants of {@link ObjectContent} a chroma key applies to: the flat media quads. */
+export type KeyableContent = Extract<ObjectContent, {
+    kind: 'image' | 'video' | 'web';
+}>;
 /** The video variant of {@link ObjectContent}. */
 export type VideoContent = Extract<ObjectContent, {
     kind: 'video';
@@ -716,8 +740,9 @@ export type SceneToneMapping = 'none' | 'neutral' | 'aces' | 'agx';
 export interface SceneBloom {
     enabled: boolean;
     mode: 'normal' | 'streak' | 'star';
-    /** UI offset: the glow's brightness multiplier is 1 + intensity. */
+    /** The glow's brightness multiplier, as Warudo's; 0 adds no glow. */
     intensity: number;
+    /** Gamma-space brightness a channel must pass; squared into linear light, as Warudo's. */
     threshold: number;
     thresholdSmooth: number;
     radius: number;
@@ -986,7 +1011,7 @@ export interface SceneDroplets {
     /** Specular glint on drops where the frame is transparent, so rain reads over the desktop (0 to 1). */
     glints: number;
 }
-/** Blend modes shared by Shoost's rim light and gradient. */
+/** Shoost's blend modes, as Gradient offers them. */
 export type EffectBlendMode = (typeof EFFECT_BLEND_MODES)[number];
 /** Solid, linear, or radial color overlay in scene or source coordinates. */
 export interface EffectGradient {
@@ -1030,11 +1055,10 @@ export interface SceneFlare {
     raysIntensity: number;
     raysOpacity: number;
 }
-/** Directional silhouette lighting, optionally sharpened or applied to both sides. */
+/** Directional silhouette light, added like VTube Studio's backlight; optionally sharpened or two-sided. */
 export interface SceneRim {
     enabled: boolean;
     mode: 'single' | 'double' | 'sharpenSingle' | 'sharpenDouble';
-    blendMode: EffectBlendMode;
     /** Rim tint (hex). */
     color: string;
     /** Normalized rim width, 0..1. */
@@ -1287,7 +1311,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", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture", "model-movement", "object-pin-depth", "text-objects", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "video-sound"];
+export declare const APP_CAPABILITIES: readonly ["storage", "speech", "automations", "controllers", "model-editing", "asset-inspection", "layer-effects", "scene-transitions", "area-lights", "spot-lights", "camera-follow-lights", "shadow-filters", "environment-map-model", "spawn", "tracking-lost", "motion-stop", "stage-capture", "model-movement", "object-pin-depth", "text-objects", "camera-follow", "camera-aim", "camera-focus", "camera-handheld", "video-sound", "object-chroma-key"];
 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`. */

package/dist/wire/types.js

@@ -95,6 +95,8 @@ export const APP_CAPABILITIES = [
     'camera-handheld',
     /** `object.setContent` edits a video's `loop`, `muted` and `volume` in place; its sound follows the output device. */
     'video-sound',
+    /** Image, video and webpage content takes `chromaKey`, which `object.setContent` edits in place. */
+    'object-chroma-key',
 ];
 export function isAppCapability(v) {
     return isOneOf(v, APP_CAPABILITIES);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",
-  "author": "LAPLACE <s@laplace.live>",
+  "author": "LAPLACE Live! <s@laplace.live>",
   "repository": {
     "type": "git",
     "url": "https://github.com/laplace-live/persona",