live2d-web
English한국어日本語
ドキュメントを見るAPI リファレンス

live2d-web ドキュメント

API リファレンス

公開 TypeScript 宣言から生成した英語の API リファレンスです。

以下のリファレンスは、パッケージで公開している TypeScript の型定義から生成しています。必要な機能は記載されたサブパスから読み込めます。使わない機能をアプリの基本バンドルに含めず、サイズを抑えられます。

公開 TypeScript の型定義から自動生成しています。

Core

Interface

AutoQualityPolicy

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

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

createLive2D

ts
createLive2D(options: CreateLive2DOptions): Promise<Live2DInstance>
Type Alias

CreateLive2DOptions

ts
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.

ts
createVolumeLipSync(): VolumeLipSyncDriver
Variable

DEFAULT_AUTO_QUALITY_POLICY

ts
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.

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

ExpressionOptions

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

fitModel

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

IdleMotion

ts
type IdleMotion = string | false | IdleMotionOptions
Interface

IdleMotionOptions

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

isMobileViewport

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

LipSyncDriver

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

LipSyncProfile

ts
type LipSyncProfile = Profile
Type Alias

LipSyncProfileInput

ts
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.

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

Live2DAssetType

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

Live2DBackend

ts
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.

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

Live2DError

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

Live2DErrorCode

ts
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

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

Live2DErrorOptions

ts
interface Live2DErrorOptions {
  details?: Live2DErrorDetails
}
Interface

Live2DInstance

ts
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

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

LoadModelOptions

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

ModelFit

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

ModelHandle

ts
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.

ts
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.

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

ModelTransform

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

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

MotionOptions

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

MotionPlaybackResult

ts
interface MotionPlaybackResult {
  status: MotionPlaybackStatus
}
Type Alias

MotionPlaybackStatus

ts
type MotionPlaybackStatus = "completed" | "interrupted" | "skipped" | "disposed"
Type Alias

MotionPriority

ts
type MotionPriority = "force" | "idle" | "normal"
Type Alias

MotionSequenceResult

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

MotionSequenceStep

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

MOUTH_HANDOFF_HOLD_MS

ts
const MOUTH_HANDOFF_HOLD_MS: 500
Variable

MOUTH_PARAMETER_ID

ts
const MOUTH_PARAMETER_ID: "ParamMouthOpenY"
Variable

MOUTH_RELEASE_MS

ts
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.

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

ParameterDriver

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

Point

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

ts
interface Point {
  x: number
  y: number
}
Interface

QualityInput

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

resolveAutoQualityPolicy

ts
resolveAutoQualityPolicy(policy?: AutoQualityPolicy): ResolvedAutoQualityPolicy
Interface

ResolvedAutoQualityPolicy

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

RuntimeLipSyncOptions

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

RuntimeLoadingStage

ts
type RuntimeLoadingStage = "core" | "stage" | "model"
Type Alias

RuntimeQualityOptions

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

RuntimeRenderState

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

selectInitialResolution

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

selectLowerResolution

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

Size

ts
interface Size {
  height: number
  width: number
}
Interface

StageHandle

ts
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

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

VolumeLipSyncDriver

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

Devtools

Interface

Live2DDevtools

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

Live2DDevtoolsTab

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

Live2DDevtoolsTarget

ts
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.

ts
mountLive2DDevtools(options: MountLive2DDevtoolsOptions): Live2DDevtools
Interface

MountLive2DDevtoolsOptions

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

React

Interface

AutoQualityPolicy

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

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

CreateLive2DOptions

ts
type CreateLive2DOptions = BaseCreateLive2DOptions & RuntimeQualityOptions
Variable

DEFAULT_AUTO_QUALITY_POLICY

ts
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.

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

ExpressionOptions

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

fitModel

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

IdleMotion

ts
type IdleMotion = string | false | IdleMotionOptions
Interface

IdleMotionOptions

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

isMobileViewport

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

LipSync

ts
LipSync(props: LipSyncProps): null
Interface

LipSyncDriver

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

LipSyncProfile

ts
type LipSyncProfile = Profile
Type Alias

LipSyncProfileInput

ts
type LipSyncProfileInput = string | URL | ArrayBuffer | LipSyncProfile
Type Alias

LipSyncProps

ts
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

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.

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

Live2DAssetType

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

Live2DBackend

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

Live2DCanvas

ts
Live2DCanvas(props: Live2DCanvasProps): Element
Type Alias

Live2DCanvasAccessibility

Optional semantics for the canvas exposed to assistive technologies.

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

Live2DCanvasProps

ts
type Live2DCanvasProps = BaseLive2DCanvasProps & Live2DCanvasQualityProps
Type Alias

Live2DCanvasQualityProps

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

Live2DCanvasState

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

Live2DError

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

Live2DErrorCode

ts
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

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

Live2DErrorOptions

ts
interface Live2DErrorOptions {
  details?: Live2DErrorDetails
}
Interface

Live2DInstance

ts
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

ts
Live2DModel(__namedParameters: Live2DModelProps): Element
Interface

Live2DModelController

ts
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

ts
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

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

LoadingStage

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

LoadModelOptions

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

ModelFit

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

ModelHandle

ts
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.

ts
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.

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

ModelTransform

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

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

MotionOptions

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

MotionPlaybackResult

ts
interface MotionPlaybackResult {
  status: MotionPlaybackStatus
}
Type Alias

MotionPlaybackStatus

ts
type MotionPlaybackStatus = "completed" | "interrupted" | "skipped" | "disposed"
Type Alias

MotionPriority

ts
type MotionPriority = "force" | "idle" | "normal"
Type Alias

MotionSequenceResult

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

MotionSequenceStep

ts
interface MotionSequenceStep {
  group: string
  index?: number
  options?: MotionOptions
}
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.

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

ParameterDriver

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

Point

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

ts
interface Point {
  x: number
  y: number
}
Interface

QualityInput

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

resolveAutoQualityPolicy

ts
resolveAutoQualityPolicy(policy?: AutoQualityPolicy): ResolvedAutoQualityPolicy
Interface

ResolvedAutoQualityPolicy

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

RuntimeLoadingStage

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

RuntimeRenderState

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

selectInitialResolution

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

selectLowerResolution

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

Size

ts
interface Size {
  height: number
  width: number
}
Interface

StageHandle

ts
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

ts
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.

ts
useLive2D(options: UseLive2DOptions): UseLive2DResult
Function

useLive2DCanvas

ts
useLive2DCanvas(): Live2DCanvasState
Function

useLive2DModel

ts
useLive2DModel(): Live2DModelController | null
Interface

UseLive2DOptions

ts
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

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

UseLive2DResult

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

useParameterDriver

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

Model inspection

Function

inspectModelCapabilities

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

ts
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.

ts
inspectModelSource(options: InspectModelSourceOptions): Promise<ModelInspectionReport>
Type Alias

InspectModelSourceOptions

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

ModelCapabilityReport

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

ts
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

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

ModelInspectionAssetStatus

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

ModelInspectionFinding

One stable, actionable content finding discovered during source inspection.

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

ModelInspectionFindingCode

ts
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

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

ModelInspectionReport

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

ts
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

ts
type ModelInspectionSeverity = "warning" | "error"
Type Alias

ModelInspectionStatus

ts
type ModelInspectionStatus = "compatible" | "warning" | "incompatible"
Type Alias

ModelTrackingChannel

ts
type ModelTrackingChannel = "pose" | "eyes" | "brows" | "mouth" | "cheeks"
Type Alias

ModelTrackingChannelSupport

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

MediaPipe tracking

Function

createMediaPipeFaceTracker

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

CreateMediaPipeFaceTrackerBaseOptions

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

CreateMediaPipeFaceTrackerOptions

ts
type CreateMediaPipeFaceTrackerOptions = CreateMediaPipeMainThreadFaceTrackerOptions | CreateMediaPipeWorkerFaceTrackerOptions
Type Alias

CreateMediaPipeMainThreadFaceTrackerOptions

ts
type CreateMediaPipeMainThreadFaceTrackerOptions = CreateMediaPipeFaceTrackerBaseOptions & MediaPipeModelAsset & CreateMediaPipeMainThreadOptions
Interface

CreateMediaPipeMainThreadOptions

ts
interface CreateMediaPipeMainThreadOptions {
  execution?: "main"
  workerFactory?: undefined
}
Type Alias

CreateMediaPipeWorkerFaceTrackerOptions

ts
type CreateMediaPipeWorkerFaceTrackerOptions = CreateMediaPipeFaceTrackerBaseOptions & MediaPipeModelAsset & CreateMediaPipeWorkerOptions
Interface

CreateMediaPipeWorkerOptions

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

MEDIAPIPE_BLENDSHAPES

ts
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

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

MediaPipeFaceChannel

ts
type MediaPipeFaceChannel = "pose" | "eyes" | "brows" | "mouth" | "cheeks"
Type Alias

MediaPipeFaceLostBehaviour

ts
type MediaPipeFaceLostBehaviour = "hold" | "neutral"
Interface

MediaPipeFaceTracker

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

MediaPipeFaceTrackingUpdate

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

MediaPipeMappingMode

ts
type MediaPipeMappingMode = "auto" | "standard" | "perfect-sync"
Type Alias

MediaPipeModelAsset

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

MediaPipeParameterTarget

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

MediaPipeWorkerFaceTracker

ts
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

ts
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.

ts
startMediaPipeFaceTrackerWorker(): void