live2d-web documentation

API reference

English signatures generated from the public TypeScript source.

The reference below is generated from the package's public TypeScript declarations. Import optional capabilities from their documented subpaths so root applications keep their runtime boundary small.

Signatures are generated from the public TypeScript source.

Core

Interface

AutoQualityPolicy

Overrides for the automatic quality policy. Omitted fields use DEFAULT_AUTO_QUALITY_POLICY.

interface AutoQualityPolicy {
  desktopMaxResolution?: number
  desktopPixelBudget?: number
  longFrameMs?: number
  longFrameRatioThreshold?: number
  minResolution?: number
  mobileMaxResolution?: number
  mobilePixelBudget?: number
  resolutionStep?: number
  sampleWindowMs?: number
}

Function

createLive2D

createLive2D(options: CreateLive2DOptions): Promise<Live2DInstance>

Type Alias

CreateLive2DOptions

type CreateLive2DOptions = BaseCreateLive2DOptions & RuntimeQualityOptions

Function

createVolumeLipSync

Turns caller-sampled RMS volume into a stable mouth-open driver. The caller retains ownership of audio capture, analysis and scheduling.

createVolumeLipSync(): VolumeLipSyncDriver

Variable

DEFAULT_AUTO_QUALITY_POLICY

const DEFAULT_AUTO_QUALITY_POLICY: { desktopMaxResolution: 2; desktopPixelBudget: 4000000; longFrameMs: 33; longFrameRatioThreshold: 0.05; minResolution: 1; mobileMaxResolution: 1.5; mobilePixelBudget: 1500000; resolutionStep: 0.25; sampleWindowMs: 3000 }

Function

ensureCubismCore

Verifies the user-supplied Cubism Core global, optionally loading a user-hosted script first. Concurrent calls for the same URL share one script load.

ensureCubismCore(coreUrl?: string, options?: EnsureCubismCoreOptions): Promise<void>

Interface

ExpressionOptions

interface ExpressionOptions {
  fadeInMs?: number
  fadeOutMs?: number
}

Function

fitModel

fitModel(stage: Size, model: Size, fit?: ModelFit): ModelTransform

Type Alias

IdleMotion

type IdleMotion = string | false | IdleMotionOptions

Interface

IdleMotionOptions

interface IdleMotionOptions {
  group: string
  weights: readonly number[]
}

Function

isMobileViewport

isMobileViewport(width: number, height: number): boolean

Interface

LipSyncDriver

interface LipSyncDriver {
  getMouthOpen: () => number
  isSpeaking: () => boolean
}

Type Alias

LipSyncProfile

type LipSyncProfile = Profile

Type Alias

LipSyncProfileInput

type LipSyncProfileInput = string | URL | ArrayBuffer | LipSyncProfile

Type Alias

Live2DAssetResolver

Supplies a model's files from somewhere other than the network: an unpacked archive held in memory, a browser storage layer, or any custom source. `path` is relative to the model3.json given as `src`, exactly as the model declares it, already decoded (so non-ASCII filenames arrive readable). Return `undefined` when the source has no such file; loading then fails with `model-load-failed` naming that path.

type Live2DAssetResolver = (path: string, signal?: AbortSignal) => Promise<Blob | ArrayBuffer | undefined> | Blob | ArrayBuffer | undefined

Type Alias

Live2DAssetType

type Live2DAssetType = "core" | "model3" | "moc3" | "texture" | "physics" | "pose" | "user-data" | "motion" | "expression" | "shader"

Interface

Live2DBackend

interface Live2DBackend {
  createStage: (element: HTMLElement, options: StageOptions) => StageHandle
  loadModel: (stage: StageHandle, url: string, options?: LoadModelOptions) => Promise<ModelHandle>
}

Type Alias

Live2DCanvasAccessibility

Optional semantics for the canvas exposed to assistive technologies.

type Live2DCanvasAccessibility = { mode: "decorative" } | { describedBy?: string; fallbackText?: string; label: string; mode?: "image" }

Class

Live2DError

class Live2DError {
  constructor(code: Live2DErrorCode, message: string, options?: Live2DErrorOptions): Live2DError
  code: Live2DErrorCode
  details?: Readonly<Live2DErrorDetails>
}

Type Alias

Live2DErrorCode

type Live2DErrorCode = "browser-only" | "core-missing" | "webgl-unsupported" | "invalid-props" | "invalid-tree" | "lipsync-error" | "tracking-error" | "model-load-failed" | "render-error" | "adapter-error"

Interface

Live2DErrorDetails

interface Live2DErrorDetails {
  assetType?: Live2DAssetType
  backend?: string
  httpStatus?: number
  url?: string
}

Interface

Live2DErrorOptions

interface Live2DErrorOptions {
  details?: Live2DErrorDetails
}

Interface

Live2DInstance

interface Live2DInstance {
  addLipSync: (options: RuntimeLipSyncOptions) => () => void
  addParameterDriver: (id: string, driver: ParameterDriver) => () => void
  clearExpression: () => void
  clearParameter: (id: string) => void
  dispose: () => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  focus: (x: number, y: number) => void
  focusAt: (clientX: number, clientY: number) => void
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  getState: () => Live2DRuntimeState
  hitTest: (clientX: number, clientY: number) => string[]
  isMotionPlaying: () => boolean
  motion: (group: string, index?: number, options?: MotionOptions) => Promise<void>
  pause: () => void
  playMotion: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  resume: () => void
  retry: () => Promise<void>
  sequence: (steps: readonly MotionSequenceStep[]) => Promise<MotionSequenceResult>
  setAccessibility: (accessibility: Live2DCanvasAccessibility | undefined) => void
  setFit: (fit: ModelFit) => void
  setParameter: (id: string, value: number) => void
  subscribe: (listener: () => void) => () => void
}

Interface

Live2DRuntimeState

interface Live2DRuntimeState {
  error?: Live2DError
  loadingStage?: RuntimeLoadingStage
  render?: RuntimeRenderState
  status: "disposed" | "loading" | "ready" | "error"
}

Interface

LoadModelOptions

interface LoadModelOptions {
  idleMotion?: IdleMotion
  resolveAsset?: Live2DAssetResolver
  signal?: AbortSignal
}

Type Alias

ModelFit

type ModelFit = "upper-body" | "full" | { offsetX?: number; offsetY?: number; scale: number }

Interface

ModelHandle

interface ModelHandle {
  clearExpression: () => void
  clearParameter: (id: string) => void
  dispose: () => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  focus: (x: number, y: number) => void
  getIntrinsicSize: () => Size
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  hitTest: (x: number, y: number) => string[]
  isMotionPlaying: () => boolean
  motion: (group: string, index?: number, options?: MotionOptions) => Promise<void>
  onAfterMotionUpdate: (callback: (deltaMs: number) => void) => () => void
  onBeforePhysicsUpdate?: (callback: (deltaMs: number) => void) => () => void
  playMotion?: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  setParameter: (id: string, value: number) => void
  setTransform: (transform: ModelTransform) => void
}

Interface

ModelInfo

Version-neutral model metadata extracted from the model settings file.

interface ModelInfo {
  expressions: string[]
  hitAreas: string[]
  mocVersion?: number
  model3Version?: number
  motions: Record<string, number>
  parameters?: ModelParameterInfo[]
}

Interface

ModelParameterInfo

Range metadata for one parameter in the loaded Cubism model.

interface ModelParameterInfo {
  defaultValue: number
  id: string
  maximum: number
  minimum: number
}

Interface

ModelTransform

Backend-neutral contracts. Keep renderer-specific concepts out of this file.

interface ModelTransform {
  scale: number
  x: number
  y: number
}

Interface

MotionOptions

interface MotionOptions {
  fadeInMs?: number
  fadeOutMs?: number
  priority?: MotionPriority
}

Interface

MotionPlaybackResult

interface MotionPlaybackResult {
  status: MotionPlaybackStatus
}

Type Alias

MotionPlaybackStatus

type MotionPlaybackStatus = "completed" | "interrupted" | "skipped" | "disposed"

Type Alias

MotionPriority

type MotionPriority = "force" | "idle" | "normal"

Type Alias

MotionSequenceResult

type MotionSequenceResult = { completedSteps: number; status: "completed" } | { completedSteps: number; status: Exclude<MotionPlaybackStatus, "completed">; stepIndex: number }

Interface

MotionSequenceStep

interface MotionSequenceStep {
  group: string
  index?: number
  options?: MotionOptions
}

Variable

MOUTH_HANDOFF_HOLD_MS

const MOUTH_HANDOFF_HOLD_MS: 500

Variable

MOUTH_PARAMETER_ID

const MOUTH_PARAMETER_ID: "ParamMouthOpenY"

Variable

MOUTH_RELEASE_MS

const MOUTH_RELEASE_MS: 200

Variable

OFFICIAL_CUBISM_CORE_URL

Cubism 5.3 Core URL that Live2D publishes for hosting use. Handy to get started (`coreUrl: OFFICIAL_CUBISM_CORE_URL`); self-host the file for production so your app does not depend on a third-party host.

const OFFICIAL_CUBISM_CORE_URL: "https://cubism.live2d.com/sdk-web/core/06/live2dcubismcore.min.js"

Interface

ParameterDriver

interface ParameterDriver {
  getValue: () => number
  phase?: ParameterDriverPhase
}

Interface

Point

Backend-neutral contracts. Keep renderer-specific concepts out of this file.

interface Point {
  x: number
  y: number
}

Interface

QualityInput

interface QualityInput {
  devicePixelRatio: number
  height: number
  mobile: boolean
  width: number
}

Function

resolveAutoQualityPolicy

resolveAutoQualityPolicy(policy?: AutoQualityPolicy): ResolvedAutoQualityPolicy

Interface

ResolvedAutoQualityPolicy

interface ResolvedAutoQualityPolicy {
  desktopMaxResolution: number
  desktopPixelBudget: number
  longFrameMs: number
  longFrameRatioThreshold: number
  minResolution: number
  mobileMaxResolution: number
  mobilePixelBudget: number
  resolutionStep: number
  sampleWindowMs: number
}

Type Alias

RuntimeLipSyncOptions

type RuntimeLipSyncOptions = { onError?: (error: Live2DError) => void; parameterId?: string } & ({ driver: LipSyncDriver } | { isSpeaking: () => boolean; profile: LipSyncProfileInput; source: AudioNode })

Type Alias

RuntimeLoadingStage

type RuntimeLoadingStage = "core" | "stage" | "model"

Type Alias

RuntimeQualityOptions

type RuntimeQualityOptions = { quality?: "auto" | AutoQualityPolicy; resolution?: never } | { quality?: never; resolution: number }

Interface

RuntimeRenderState

interface RuntimeRenderState {
  bufferPixels: number
  height: number
  resolution: number
  width: number
}

Function

selectInitialResolution

selectInitialResolution(input: QualityInput, policy?: ResolvedAutoQualityPolicy): number

Function

selectLowerResolution

selectLowerResolution(current: number, longFrameRatio: number, policy?: ResolvedAutoQualityPolicy): number

Interface

Size

interface Size {
  height: number
  width: number
}

Interface

StageHandle

interface StageHandle {
  dispose: () => void
  getResolution: () => number
  getSize: () => Size
  onError: (callback: (error: Live2DError) => void) => () => void
  onFrame: (callback: (deltaMs: number) => void) => () => void
  pause: () => void
  resize: (width: number, height: number) => void
  resume: () => void
  setAccessibility?: (accessibility: Live2DCanvasAccessibility | undefined) => void
  setResolution: (resolution: number) => void
  toWorld: (clientX: number, clientY: number) => Point
}

Interface

StageOptions

interface StageOptions {
  accessibility?: Live2DCanvasAccessibility
  height: number
  maxFps?: number
  resolution?: number
  width: number
}

Interface

VolumeLipSyncDriver

interface VolumeLipSyncDriver {
  getMouthOpen: () => number
  isSpeaking: () => boolean
  sample: (rms: number, elapsedMs: number) => void
}

Devtools

Interface

Live2DDevtools

interface Live2DDevtools {
  dispose: () => void
  setTab: (tab: Live2DDevtoolsTab) => void
  setTarget: (target: Live2DDevtoolsTarget) => void
}

Type Alias

Live2DDevtoolsTab

type Live2DDevtoolsTab = "overview" | "parameters" | "motion" | "expression"

Interface

Live2DDevtoolsTarget

interface Live2DDevtoolsTarget {
  addParameterDriver: (id: string, driver: ParameterDriver) => () => void
  clearExpression: () => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  getState?: () => Live2DRuntimeState
  isMotionPlaying: () => boolean
  playMotion: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  sequence: (steps: readonly MotionSequenceStep[]) => Promise<MotionSequenceResult>
  subscribe?: (listener: () => void) => () => void
}

Function

mountLive2DDevtools

Mounts a framework-free debugging panel for one loaded Live2D target.

mountLive2DDevtools(options: MountLive2DDevtoolsOptions): Live2DDevtools

Interface

MountLive2DDevtoolsOptions

interface MountLive2DDevtoolsOptions {
  container: HTMLElement
  initialTab?: Live2DDevtoolsTab
  target: Live2DDevtoolsTarget
}

React

Interface

AutoQualityPolicy

Overrides for the automatic quality policy. Omitted fields use DEFAULT_AUTO_QUALITY_POLICY.

interface AutoQualityPolicy {
  desktopMaxResolution?: number
  desktopPixelBudget?: number
  longFrameMs?: number
  longFrameRatioThreshold?: number
  minResolution?: number
  mobileMaxResolution?: number
  mobilePixelBudget?: number
  resolutionStep?: number
  sampleWindowMs?: number
}

Type Alias

CreateLive2DOptions

type CreateLive2DOptions = BaseCreateLive2DOptions & RuntimeQualityOptions

Variable

DEFAULT_AUTO_QUALITY_POLICY

const DEFAULT_AUTO_QUALITY_POLICY: { desktopMaxResolution: 2; desktopPixelBudget: 4000000; longFrameMs: 33; longFrameRatioThreshold: 0.05; minResolution: 1; mobileMaxResolution: 1.5; mobilePixelBudget: 1500000; resolutionStep: 0.25; sampleWindowMs: 3000 }

Function

ensureCubismCore

Verifies the user-supplied Cubism Core global, optionally loading a user-hosted script first. Concurrent calls for the same URL share one script load.

ensureCubismCore(coreUrl?: string, options?: EnsureCubismCoreOptions): Promise<void>

Interface

ExpressionOptions

interface ExpressionOptions {
  fadeInMs?: number
  fadeOutMs?: number
}

Function

fitModel

fitModel(stage: Size, model: Size, fit?: ModelFit): ModelTransform

Type Alias

IdleMotion

type IdleMotion = string | false | IdleMotionOptions

Interface

IdleMotionOptions

interface IdleMotionOptions {
  group: string
  weights: readonly number[]
}

Function

isMobileViewport

isMobileViewport(width: number, height: number): boolean

Function

LipSync

LipSync(props: LipSyncProps): null

Interface

LipSyncDriver

interface LipSyncDriver {
  getMouthOpen: () => number
  isSpeaking: () => boolean
}

Type Alias

LipSyncProfile

type LipSyncProfile = Profile

Type Alias

LipSyncProfileInput

type LipSyncProfileInput = string | URL | ArrayBuffer | LipSyncProfile

Type Alias

LipSyncProps

type LipSyncProps = LipSyncErrorProps & { active?: never; driver: LipSyncDriver; mouthOpen?: never; profile?: never; source?: never; speaking?: never } | LipSyncErrorProps & { active: boolean; driver?: never; mouthOpen?: never; profile: string | URL | ArrayBuffer | LipSyncProfile; source: AudioNode | null; speaking?: never } | LipSyncErrorProps & { active?: never; driver?: never; mouthOpen: number; profile?: never; source?: never; speaking: boolean }

Type Alias

Live2DAssetResolver

type Live2DAssetResolver = (path: string, signal?: AbortSignal) => Promise<Blob | ArrayBuffer | undefined> | Blob | ArrayBuffer | undefined

Type Alias

Live2DAssetType

type Live2DAssetType = "core" | "model3" | "moc3" | "texture" | "physics" | "pose" | "user-data" | "motion" | "expression" | "shader"

Interface

Live2DBackend

interface Live2DBackend {
  createStage: (element: HTMLElement, options: StageOptions) => StageHandle
  loadModel: (stage: StageHandle, url: string, options?: LoadModelOptions) => Promise<ModelHandle>
}

Function

Live2DCanvas

Live2DCanvas(props: Live2DCanvasProps): Element

Type Alias

Live2DCanvasAccessibility

Optional semantics for the canvas exposed to assistive technologies.

type Live2DCanvasAccessibility = { mode: "decorative" } | { describedBy?: string; fallbackText?: string; label: string; mode?: "image" }

Type Alias

Live2DCanvasProps

type Live2DCanvasProps = BaseLive2DCanvasProps & Live2DCanvasQualityProps

Type Alias

Live2DCanvasQualityProps

type Live2DCanvasQualityProps = { quality?: "auto" | AutoQualityPolicy; resolution?: never } | { quality?: never; resolution: number }

Interface

Live2DCanvasState

interface Live2DCanvasState {
  error?: Live2DError
  loadingStage?: LoadingStage
  render?: { bufferPixels: number; height: number; resolution: number; width: number }
  retry: () => void
  status: "loading" | "ready" | "error"
}

Class

Live2DError

class Live2DError {
  constructor(code: Live2DErrorCode, message: string, options?: Live2DErrorOptions): Live2DError
  code: Live2DErrorCode
  details?: Readonly<Live2DErrorDetails>
}

Type Alias

Live2DErrorCode

type Live2DErrorCode = "browser-only" | "core-missing" | "webgl-unsupported" | "invalid-props" | "invalid-tree" | "lipsync-error" | "tracking-error" | "model-load-failed" | "render-error" | "adapter-error"

Interface

Live2DErrorDetails

interface Live2DErrorDetails {
  assetType?: Live2DAssetType
  backend?: string
  httpStatus?: number
  url?: string
}

Interface

Live2DErrorOptions

interface Live2DErrorOptions {
  details?: Live2DErrorDetails
}

Interface

Live2DInstance

interface Live2DInstance {
  addLipSync: (options: RuntimeLipSyncOptions) => () => void
  addParameterDriver: (id: string, driver: ParameterDriver) => () => void
  clearExpression: () => void
  clearParameter: (id: string) => void
  dispose: () => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  focus: (x: number, y: number) => void
  focusAt: (clientX: number, clientY: number) => void
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  getState: () => Live2DRuntimeState
  hitTest: (clientX: number, clientY: number) => string[]
  isMotionPlaying: () => boolean
  motion: (group: string, index?: number, options?: MotionOptions) => Promise<void>
  pause: () => void
  playMotion: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  resume: () => void
  retry: () => Promise<void>
  sequence: (steps: readonly MotionSequenceStep[]) => Promise<MotionSequenceResult>
  setAccessibility: (accessibility: Live2DCanvasAccessibility | undefined) => void
  setFit: (fit: ModelFit) => void
  setParameter: (id: string, value: number) => void
  subscribe: (listener: () => void) => () => void
}

Function

Live2DModel

Live2DModel(__namedParameters: Live2DModelProps): Element

Interface

Live2DModelController

interface Live2DModelController {
  addParameterDriver: (id: string, driver: ParameterDriver) => () => void
  clearExpression: () => void
  clearParameter: (id: string) => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  focus: (x: number, y: number) => void
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  isMotionPlaying: () => boolean
  motion: (group: string, index?: number, options?: MotionOptions) => Promise<void>
  playMotion: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  sequence: (steps: readonly MotionSequenceStep[]) => Promise<MotionSequenceResult>
  setParameter: (id: string, value: number) => void
}

Interface

Live2DModelProps

interface Live2DModelProps {
  children?: ReactNode
  fit?: ModelFit
  followPointer?: boolean
  idleMotion?: IdleMotion
  onError?: (error: Live2DError) => void
  onLoad?: (model: Live2DModelController) => void
  onTap?: (hitAreas: string[], event: MouseEvent) => void
  paused?: boolean
  resolveAsset?: Live2DAssetResolver
  retries?: number
  src: string
}

Interface

Live2DRuntimeState

interface Live2DRuntimeState {
  error?: Live2DError
  loadingStage?: RuntimeLoadingStage
  render?: RuntimeRenderState
  status: "disposed" | "loading" | "ready" | "error"
}

Type Alias

LoadingStage

type LoadingStage = "core" | "stage" | "model"

Interface

LoadModelOptions

interface LoadModelOptions {
  idleMotion?: IdleMotion
  resolveAsset?: Live2DAssetResolver
  signal?: AbortSignal
}

Type Alias

ModelFit

type ModelFit = "upper-body" | "full" | { offsetX?: number; offsetY?: number; scale: number }

Interface

ModelHandle

interface ModelHandle {
  clearExpression: () => void
  clearParameter: (id: string) => void
  dispose: () => void
  expression: (id?: string, options?: ExpressionOptions) => Promise<void>
  focus: (x: number, y: number) => void
  getIntrinsicSize: () => Size
  getModelInfo: () => ModelInfo
  getParameter: (id: string) => number
  hitTest: (x: number, y: number) => string[]
  isMotionPlaying: () => boolean
  motion: (group: string, index?: number, options?: MotionOptions) => Promise<void>
  onAfterMotionUpdate: (callback: (deltaMs: number) => void) => () => void
  onBeforePhysicsUpdate?: (callback: (deltaMs: number) => void) => () => void
  playMotion?: (group: string, index?: number, options?: MotionOptions) => Promise<MotionPlaybackResult>
  setParameter: (id: string, value: number) => void
  setTransform: (transform: ModelTransform) => void
}

Interface

ModelInfo

Version-neutral model metadata extracted from the model settings file.

interface ModelInfo {
  expressions: string[]
  hitAreas: string[]
  mocVersion?: number
  model3Version?: number
  motions: Record<string, number>
  parameters?: ModelParameterInfo[]
}

Interface

ModelParameterInfo

Range metadata for one parameter in the loaded Cubism model.

interface ModelParameterInfo {
  defaultValue: number
  id: string
  maximum: number
  minimum: number
}

Interface

ModelTransform

Backend-neutral contracts. Keep renderer-specific concepts out of this file.

interface ModelTransform {
  scale: number
  x: number
  y: number
}

Interface

MotionOptions

interface MotionOptions {
  fadeInMs?: number
  fadeOutMs?: number
  priority?: MotionPriority
}

Interface

MotionPlaybackResult

interface MotionPlaybackResult {
  status: MotionPlaybackStatus
}

Type Alias

MotionPlaybackStatus

type MotionPlaybackStatus = "completed" | "interrupted" | "skipped" | "disposed"

Type Alias

MotionPriority

type MotionPriority = "force" | "idle" | "normal"

Type Alias

MotionSequenceResult

type MotionSequenceResult = { completedSteps: number; status: "completed" } | { completedSteps: number; status: Exclude<MotionPlaybackStatus, "completed">; stepIndex: number }

Interface

MotionSequenceStep

interface MotionSequenceStep {
  group: string
  index?: number
  options?: MotionOptions
}

Variable

OFFICIAL_CUBISM_CORE_URL

const OFFICIAL_CUBISM_CORE_URL: "https://cubism.live2d.com/sdk-web/core/06/live2dcubismcore.min.js"

Interface

ParameterDriver

interface ParameterDriver {
  getValue: () => number
  phase?: ParameterDriverPhase
}

Interface

Point

Backend-neutral contracts. Keep renderer-specific concepts out of this file.

interface Point {
  x: number
  y: number
}

Interface

QualityInput

interface QualityInput {
  devicePixelRatio: number
  height: number
  mobile: boolean
  width: number
}

Function

resolveAutoQualityPolicy

resolveAutoQualityPolicy(policy?: AutoQualityPolicy): ResolvedAutoQualityPolicy

Interface

ResolvedAutoQualityPolicy

interface ResolvedAutoQualityPolicy {
  desktopMaxResolution: number
  desktopPixelBudget: number
  longFrameMs: number
  longFrameRatioThreshold: number
  minResolution: number
  mobileMaxResolution: number
  mobilePixelBudget: number
  resolutionStep: number
  sampleWindowMs: number
}

Type Alias

RuntimeLoadingStage

type RuntimeLoadingStage = "core" | "stage" | "model"

Interface

RuntimeRenderState

interface RuntimeRenderState {
  bufferPixels: number
  height: number
  resolution: number
  width: number
}

Function

selectInitialResolution

selectInitialResolution(input: QualityInput, policy?: ResolvedAutoQualityPolicy): number

Function

selectLowerResolution

selectLowerResolution(current: number, longFrameRatio: number, policy?: ResolvedAutoQualityPolicy): number

Interface

Size

interface Size {
  height: number
  width: number
}

Interface

StageHandle

interface StageHandle {
  dispose: () => void
  getResolution: () => number
  getSize: () => Size
  onError: (callback: (error: Live2DError) => void) => () => void
  onFrame: (callback: (deltaMs: number) => void) => () => void
  pause: () => void
  resize: (width: number, height: number) => void
  resume: () => void
  setAccessibility?: (accessibility: Live2DCanvasAccessibility | undefined) => void
  setResolution: (resolution: number) => void
  toWorld: (clientX: number, clientY: number) => Point
}

Interface

StageOptions

interface StageOptions {
  accessibility?: Live2DCanvasAccessibility
  height: number
  maxFps?: number
  resolution?: number
  width: number
}

Function

useLive2D

Owns a vanilla Live2D instance from React: creation, StrictMode replays, state subscription and disposal. Changing container or src recreates the instance; change other options by remounting with a key.

useLive2D(options: UseLive2DOptions): UseLive2DResult

Function

useLive2DCanvas

useLive2DCanvas(): Live2DCanvasState

Function

useLive2DModel

useLive2DModel(): Live2DModelController | null

Interface

UseLive2DOptions

interface UseLive2DOptions {
  accessibility?: Live2DCanvasAccessibility
  backend?: Live2DBackend
  container: HTMLElement | null
  coreUrl?: string
  fit?: ModelFit
  followPointer?: boolean
  idleMotion?: IdleMotion
  maxFps?: number
  onError?: (error: Live2DError) => void
  pauseWhenOffscreen?: boolean
  quality?: AutoQualityPolicy | "auto"
  resolution?: number
  resolveAsset?: Live2DAssetResolver
  retries?: number
  signal?: AbortSignal
  src: string
}

Function

useLive2DParameter

useLive2DParameter(id: string, value: number): void

Interface

UseLive2DResult

interface UseLive2DResult {
  error: Live2DError | undefined
  instance: Live2DInstance | null
  retry: () => void
  state: Live2DRuntimeState
}

Function

useParameterDriver

useParameterDriver(id: string, getter: () => number): void

Model inspection

Function

inspectModelCapabilities

Reports Standard channel and ARKit Perfect Sync coverage from model metadata.

inspectModelCapabilities(info: ModelInfo): ModelCapabilityReport

Function

inspectModelSource

Reads model3.json and every declared asset without creating a renderer. Content problems are aggregated in the returned report; only invalid caller input and cancellation reject.

inspectModelSource(options: InspectModelSourceOptions): Promise<ModelInspectionReport>

Type Alias

InspectModelSourceOptions

type InspectModelSourceOptions = InspectModelSourceBase & { resolveAsset?: never } | InspectModelSourceBase & { resolveAsset: Live2DAssetResolver }

Interface

ModelCapabilityReport

Tracking parameter coverage derived from a loaded backend's ModelInfo.

interface ModelCapabilityReport {
  mocVersion?: number
  model3Version?: number
  perfectSync: { compatible: boolean; matched: number; minimum: number; missing: readonly string[]; total: number }
  recommendedMapping: "standard" | "perfect-sync" | "none"
  standardChannels: Readonly<Record<ModelTrackingChannel, ModelTrackingChannelSupport>>
}

Interface

ModelInspectionAsset

interface ModelInspectionAsset {
  assetType: Live2DAssetType
  bytes?: number
  external: boolean
  path: string
  status: ModelInspectionAssetStatus
}

Type Alias

ModelInspectionAssetStatus

type ModelInspectionAssetStatus = "available" | "external" | "missing" | "too-large" | "unreadable"

Interface

ModelInspectionFinding

One stable, actionable content finding discovered during source inspection.

interface ModelInspectionFinding {
  assetType?: Live2DAssetType
  code: ModelInspectionFindingCode
  message: string
  path?: string
  severity: ModelInspectionSeverity
}

Type Alias

ModelInspectionFindingCode

type ModelInspectionFindingCode = "asset-too-large" | "cross-origin-asset" | "empty-reference" | "external-asset" | "invalid-model3" | "missing-asset" | "missing-file-reference" | "too-many-references" | "total-assets-too-large" | "unreadable-asset" | "unsupported-model3-version"

Interface

ModelInspectionLimits

interface ModelInspectionLimits {
  maxAssetBytes?: number
  maxReferences?: number
  maxTotalBytes?: number
}

Interface

ModelInspectionReport

Aggregate source report. An error finding makes the report incompatible.

interface ModelInspectionReport {
  assets: readonly ModelInspectionAsset[]
  expressions: readonly string[]
  findings: readonly ModelInspectionFinding[]
  hitAreas: readonly string[]
  model3Version?: number
  motions: Readonly<Record<string, number>>
  source: string
  status: ModelInspectionStatus
}

Type Alias

ModelInspectionSeverity

type ModelInspectionSeverity = "warning" | "error"

Type Alias

ModelInspectionStatus

type ModelInspectionStatus = "compatible" | "warning" | "incompatible"

Type Alias

ModelTrackingChannel

type ModelTrackingChannel = "pose" | "eyes" | "brows" | "mouth" | "cheeks"

Type Alias

ModelTrackingChannelSupport

type ModelTrackingChannelSupport = "full" | "partial" | "missing"

MediaPipe tracking

Function

createMediaPipeFaceTracker

createMediaPipeFaceTracker(options: CreateMediaPipeWorkerFaceTrackerOptions): Promise<MediaPipeWorkerFaceTracker>
createMediaPipeFaceTracker(options: CreateMediaPipeMainThreadFaceTrackerOptions): Promise<MediaPipeFaceTracker>

Interface

CreateMediaPipeFaceTrackerBaseOptions

interface CreateMediaPipeFaceTrackerBaseOptions {
  delegate?: "CPU" | "GPU"
  inputMirrored?: boolean
  maxFps?: number
  minFaceDetectionConfidence?: number
  minFacePresenceConfidence?: number
  minTrackingConfidence?: number
  onFaceLost?: MediaPipeFaceLostBehaviour
  signal?: AbortSignal
  wasmPath: string
}

Type Alias

CreateMediaPipeFaceTrackerOptions

type CreateMediaPipeFaceTrackerOptions = CreateMediaPipeMainThreadFaceTrackerOptions | CreateMediaPipeWorkerFaceTrackerOptions

Type Alias

CreateMediaPipeMainThreadFaceTrackerOptions

type CreateMediaPipeMainThreadFaceTrackerOptions = CreateMediaPipeFaceTrackerBaseOptions & MediaPipeModelAsset & CreateMediaPipeMainThreadOptions

Interface

CreateMediaPipeMainThreadOptions

interface CreateMediaPipeMainThreadOptions {
  execution?: "main"
  workerFactory?: undefined
}

Type Alias

CreateMediaPipeWorkerFaceTrackerOptions

type CreateMediaPipeWorkerFaceTrackerOptions = CreateMediaPipeFaceTrackerBaseOptions & MediaPipeModelAsset & CreateMediaPipeWorkerOptions

Interface

CreateMediaPipeWorkerOptions

interface CreateMediaPipeWorkerOptions {
  execution: "worker"
  workerFactory: () => Worker
}

Variable

MEDIAPIPE_BLENDSHAPES

const MEDIAPIPE_BLENDSHAPES: readonly ["_neutral", "browDownLeft", "browDownRight", "browInnerUp", "browOuterUpLeft", "browOuterUpRight", "cheekPuff", "cheekSquintLeft", "cheekSquintRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft", "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft", "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft", "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "jawForward", "jawLeft", "jawOpen", "jawRight", "mouthClose", "mouthDimpleLeft", "mouthDimpleRight", "mouthFrownLeft", "mouthFrownRight", "mouthFunnel", "mouthLeft", "mouthLowerDownLeft", "mouthLowerDownRight", "mouthPressLeft", "mouthPressRight", "mouthPucker", "mouthRight", "mouthRollLower", "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper", "mouthSmileLeft", "mouthSmileRight", "mouthStretchLeft", "mouthStretchRight", "mouthUpperUpLeft", "mouthUpperUpRight", "noseSneerLeft", "noseSneerRight"]

Interface

MediaPipeAttachOptions

interface MediaPipeAttachOptions {
  channels?: Partial<Record<MediaPipeFaceChannel, boolean>>
  mapping?: MediaPipeMappingMode
  sensitivity?: Partial<Record<MediaPipeFaceChannel, number>>
}

Type Alias

MediaPipeFaceChannel

type MediaPipeFaceChannel = "pose" | "eyes" | "brows" | "mouth" | "cheeks"

Type Alias

MediaPipeFaceLostBehaviour

type MediaPipeFaceLostBehaviour = "hold" | "neutral"

Interface

MediaPipeFaceTracker

interface MediaPipeFaceTracker {
  attach: (target: MediaPipeParameterTarget, options?: MediaPipeAttachOptions) => () => void
  calibrate: () => void
  dispose: () => void
  isTracking: () => boolean
  update: (source: TexImageSource, timestampMs: number) => MediaPipeFaceTrackingUpdate
}

Type Alias

MediaPipeFaceTrackingUpdate

type MediaPipeFaceTrackingUpdate = { status: "skipped" } | { effectiveFps: number; inferenceMs: number; status: "calibrating" | "tracked" | "lost" }

Type Alias

MediaPipeMappingMode

type MediaPipeMappingMode = "auto" | "standard" | "perfect-sync"

Type Alias

MediaPipeModelAsset

type MediaPipeModelAsset = { modelAssetBuffer?: never; modelAssetPath: string } | { modelAssetBuffer: Uint8Array; modelAssetPath?: never }

Interface

MediaPipeParameterTarget

interface MediaPipeParameterTarget {
  addParameterDriver: (id: string, driver: ParameterDriver) => () => void
  getModelInfo: () => ModelInfo
}

Interface

MediaPipeWorkerFaceTracker

interface MediaPipeWorkerFaceTracker {
  attach: (target: MediaPipeParameterTarget, options?: MediaPipeAttachOptions) => () => void
  calibrate: () => void
  dispose: () => void
  isTracking: () => boolean
  update: (source: TexImageSource, timestampMs: number) => Promise<MediaPipeFaceTrackingUpdate>
}

Variable

PERFECT_SYNC_PARAMETER_IDS

const PERFECT_SYNC_PARAMETER_IDS: readonly string[]

MediaPipe Worker

Function

startMediaPipeFaceTrackerWorker

Starts the MediaPipe module-worker message loop. Call this once from the application's own worker entry; importing this module has no side effects.

startMediaPipeFaceTrackerWorker(): void