@laplace.live/pixijs-live2d 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -3240,6 +3240,14 @@ export declare enum MotionPreloadStrategy {
   /** No preload. */
   NONE = "NONE"
 }
+/**
+ * What plays when nothing else does: a motion to loop, `'idle-group'` for a random motion of
+ * the idle group (the default), or `null` to hold still.
+ */
+export type IdleMotion = {
+  group: string;
+  index: number;
+} | 'idle-group' | null;
 /**
  * Handles the motion playback for Live2D models.
  * Responsible for loading, playing, and managing motion states and audio.
@@ -3322,6 +3330,17 @@ export declare abstract class MotionManager<Motion = unknown, MotionSpec = unkno
    * @type {boolean}
    */
   destroyed: boolean;
+  /** The idle selection; see {@link setIdleMotion}. */
+  idleMotion: IdleMotion;
+  /**
+   * Choose what plays when nothing else does. A running idle gives way at once and a loading one
+   * is dropped; a higher-priority motion in flight hands over to the new selection when it ends.
+   */
+  setIdleMotion(motion: IdleMotion): void;
+  /** Stop the idle so the next update starts the selection. Cubism eases its parameters home too. */
+  protected releaseIdle(): void;
+  /** Start the idle selection at IDLE priority; a chosen motion loops regardless of its own flag. */
+  protected startIdleMotion(): Promise<boolean>;
   /**
    * Reference to the parent InternalModel.
    * @type {InternalModel}
@@ -3698,6 +3717,8 @@ export declare const VOLUME = 0.5;
  * Manages all the sounds.
  */
 export declare class SoundManager {
+  /** Select the speaker used by current and future motion audio and speak() calls. */
+  static setOutputDevice(deviceId: string): Promise<void>;
   /**
    * Audio elements playing or pending to play. Finished audios will be removed automatically.
    */
@@ -6915,6 +6936,10 @@ export declare class CubismMotionManager extends MotionManager<CubismMotion, Mot
   expressionManager?: CubismExpressionManager;
   eyeBlinkIds: string[];
   lipSyncIds: string[];
+  /** What each motion's curves write, read once when it is created. */
+  private readonly meta;
+  /** Eases the parameters a released idle animated back to rest; see {@link releaseIdle}. */
+  private release;
   constructor(parent: CubismInternalModel);
   protected init(options?: MotionManagerOptions): void;
   isFinished(): boolean;
@@ -6924,6 +6949,15 @@ export declare class CubismMotionManager extends MotionManager<CubismMotion, Mot
   getMotionFile(definition: Motion): string;
   protected getMotionName(definition: Motion): string;
   protected getSoundFile(definition: Motion): string | undefined;
+  /** Whether the playing motion animates the eyes itself, so the engine's auto-blink must yield to it. */
+  currentMotionBlinks(): boolean;
+  /** The parameters the playing motion writes, for a host driver handing them over to it; null when none plays. */
+  currentMotionParameters(): ReadonlySet<string> | null;
+  private currentMotion;
+  private currentMeta;
+  protected releaseIdle(): void;
+  /** One frame of the ease-to-rest, ahead of the motions so a new idle's fade-in blends from it. */
+  private updateRelease;
   protected updateParameters(model: CubismModel, now: DOMHighResTimeStamp): boolean;
   destroy(): void;
   motionLastFrame(group: string, index: number, { expression }?: {

package/dist/index.js

@@ -3567,6 +3567,10 @@ var MotionState = class {
 	*/
 	start(motion, group, index, priority) {
 		if (priority === 1) {
+			if (group !== this.reservedIdleGroup || index !== this.reservedIdleIndex) {
+				logger.log(this.tag, "Cannot start idle motion because it is no longer reserved.", this.dump(group, index));
+				return false;
+			}
 			this.setReservedIdle(void 0, void 0);
 			if (this.currentPriority !== 0) {
 				logger.log(this.tag, "Cannot start idle motion because another motion is playing.", this.dump(group, index));
@@ -3663,17 +3667,33 @@ const VOLUME = .5;
 const SOUND_ALIAS_PREFIX = "live2d-sound-";
 let soundId = 0;
 let pixiSoundPromise;
-const configuredLibraries = /* @__PURE__ */ new WeakSet();
+const configuredLibraries = /* @__PURE__ */ new Set();
+let outputDeviceId = "";
+let outputError = null;
+/** Device changes and first-use routing run in order, so a library never settles on a stale device. */
+let routing = Promise.resolve();
+function queueRouting(task) {
+	const run = routing.then(task);
+	routing = run.catch(() => void 0);
+	return run;
+}
+async function routeContext(context, deviceId) {
+	const routable = context;
+	if (routable.setSinkId) await routable.setSinkId(deviceId);
+	else if (deviceId) throw new Error("Audio output selection is not supported");
+}
 function configureSoundLibrary(library) {
-	if (!configuredLibraries.has(library)) {
+	return queueRouting(async () => {
+		if (configuredLibraries.has(library)) return library;
 		try {
 			library.disableAutoPause = true;
 		} catch (e) {
 			logger.warn(TAG$2, "Failed to disable @pixi/sound auto pause.", e);
 		}
+		if (outputDeviceId) await routeContext(library.context.audioContext, outputDeviceId);
 		configuredLibraries.add(library);
-	}
-	return library;
+		return library;
+	});
 }
 function getGlobalSoundLibrary() {
 	return typeof PIXI !== "undefined" ? PIXI?.sound : void 0;
@@ -3681,11 +3701,12 @@ function getGlobalSoundLibrary() {
 async function resolveSoundLibrary() {
 	const globalLibrary = getGlobalSoundLibrary();
 	if (globalLibrary) return configureSoundLibrary(globalLibrary);
-	pixiSoundPromise ??= import("@pixi/sound").then(({ sound }) => configureSoundLibrary(sound)).catch((e) => {
+	pixiSoundPromise ??= import("@pixi/sound").then(({ sound }) => sound).catch((e) => {
 		logger.warn(TAG$2, "@pixi/sound is not available. Load pixi-sound.js before using motion sounds, speak(), or lip sync.", e);
 		return null;
 	});
-	return pixiSoundPromise;
+	const library = await pixiSoundPromise;
+	return library ? configureSoundLibrary(library) : null;
 }
 function removeSound(library, alias) {
 	try {
@@ -3710,6 +3731,25 @@ function getAudioBuffer(audio) {
 * Manages all the sounds.
 */
 var SoundManager = class SoundManager {
+	/** Select the speaker used by current and future motion audio and speak() calls. */
+	static setOutputDevice(deviceId) {
+		return queueRouting(async () => {
+			const changed = [];
+			try {
+				for (const library of configuredLibraries) {
+					const context = library.context.audioContext;
+					await routeContext(context, deviceId);
+					changed.push(context);
+				}
+				outputDeviceId = deviceId;
+				outputError = null;
+			} catch (error) {
+				outputError = error;
+				await Promise.allSettled(changed.map((context) => routeContext(context, outputDeviceId)));
+				throw error;
+			}
+		});
+	}
 	/**
 	* Audio elements playing or pending to play. Finished audios will be removed automatically.
 	*/
@@ -3740,6 +3780,7 @@ var SoundManager = class SoundManager {
 		let library = null;
 		let alias;
 		try {
+			if (outputError) throw outputError;
 			library = await resolveSoundLibrary();
 			if (!library) throw new Error("@pixi/sound is not available");
 			alias = `${SOUND_ALIAS_PREFIX}${soundId++}`;
@@ -3768,6 +3809,7 @@ var SoundManager = class SoundManager {
 					}
 				});
 			});
+			if (outputError) throw outputError;
 			SoundManager.aliases.set(audio, {
 				alias: soundAlias,
 				library: soundLibrary
@@ -3787,6 +3829,10 @@ var SoundManager = class SoundManager {
 	* @param onFinish - Callback invoked when the playback has finished.
 	*/
 	static play(audio, onFinish) {
+		if (outputError) {
+			SoundManager.dispose(audio);
+			return;
+		}
 		audio.play({
 			singleInstance: true,
 			complete: () => {
@@ -3870,6 +3916,10 @@ let MotionPreloadStrategy = /* @__PURE__ */ function(MotionPreloadStrategy) {
 	MotionPreloadStrategy["NONE"] = "NONE";
 	return MotionPreloadStrategy;
 }({});
+function sameIdleMotion(a, b) {
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return a === b;
+	return a.group === b.group && a.index === b.index;
+}
 /**
 * Handles the motion playback for Live2D models.
 * Responsible for loading, playing, and managing motion states and audio.
@@ -3924,6 +3974,29 @@ var MotionManager = class extends EventEmitter {
 	* @type {boolean}
 	*/
 	destroyed = false;
+	/** The idle selection; see {@link setIdleMotion}. */
+	idleMotion = "idle-group";
+	/**
+	* Choose what plays when nothing else does. A running idle gives way at once and a loading one
+	* is dropped; a higher-priority motion in flight hands over to the new selection when it ends.
+	*/
+	setIdleMotion(motion) {
+		if (sameIdleMotion(this.idleMotion, motion)) return;
+		this.idleMotion = motion;
+		this.state.setReservedIdle(void 0, void 0);
+		if (this.state.currentPriority === 1) this.releaseIdle();
+	}
+	/** Stop the idle so the next update starts the selection. Cubism eases its parameters home too. */
+	releaseIdle() {
+		this.stopAllMotions();
+	}
+	/** Start the idle selection at IDLE priority; a chosen motion loops regardless of its own flag. */
+	startIdleMotion() {
+		const idle = this.idleMotion;
+		if (idle === null) return Promise.resolve(false);
+		if (idle === "idle-group") return this.startRandomMotion(this.groups.idle, 1);
+		return this.startMotion(idle.group, idle.index, 1, { loop: true });
+	}
 	/**
 	* Reference to the parent InternalModel.
 	* @type {InternalModel}
@@ -4222,7 +4295,7 @@ var MotionManager = class extends EventEmitter {
 			}
 			if (this.state.shouldOverrideExpression()) this.expressionManager?.restoreExpression();
 			this.state.complete();
-			if (this.state.shouldRequestIdleMotion()) this.startRandomMotion(this.groups.idle, 1);
+			if (this.idleMotion !== null && this.state.shouldRequestIdleMotion()) this.startIdleMotion();
 		}
 		return this.updateParameters(model, now);
 	}
@@ -14651,6 +14724,10 @@ var CubismMotionManager = class extends MotionManager {
 	expressionManager;
 	eyeBlinkIds;
 	lipSyncIds = ["ParamMouthOpenY"];
+	/** What each motion's curves write, read once when it is created. */
+	meta = /* @__PURE__ */ new WeakMap();
+	/** Eases the parameters a released idle animated back to rest; see {@link releaseIdle}. */
+	release = null;
 	constructor(parent) {
 		super(parent);
 		this.definitions = parent.settings.motions ?? {};
@@ -14680,6 +14757,7 @@ var CubismMotionManager = class extends MotionManager {
 			});
 			motion._motionData.curves = filtered;
 			motion._motionData.curveCount = filtered.length;
+			this.meta.set(motion, motionMeta(motion, this.eyeBlinkIds));
 		}
 		this.queueManager.stopAllMotions();
 		return this.queueManager.startMotion(motion, false);
@@ -14692,6 +14770,7 @@ var CubismMotionManager = class extends MotionManager {
 		const motion = CubismMotion.create(data, data.byteLength, void 0, void 0, shouldCheckMotionConsistency);
 		const json = new CubismMotionJson(data, data.byteLength);
 		motion.setLoop(json.isMotionLoop());
+		this.meta.set(motion, motionMeta(motion, this.eyeBlinkIds));
 		const defaultFadingDuration = (group === this.groups.idle ? config.idleMotionFadingDuration : config.motionFadingDuration) / 1e3;
 		if (json.getMotionFadeInTime() === void 0) motion.setFadeInTime(definition.FadeInTime > 0 ? definition.FadeInTime : defaultFadingDuration);
 		if (json.getMotionFadeOutTime() === void 0) motion.setFadeOutTime(definition.FadeOutTime > 0 ? definition.FadeOutTime : defaultFadingDuration);
@@ -14707,7 +14786,57 @@ var CubismMotionManager = class extends MotionManager {
 	getSoundFile(definition) {
 		return definition.Sound;
 	}
+	/** Whether the playing motion animates the eyes itself, so the engine's auto-blink must yield to it. */
+	currentMotionBlinks() {
+		return this.currentMeta()?.blinks ?? false;
+	}
+	/** The parameters the playing motion writes, for a host driver handing them over to it; null when none plays. */
+	currentMotionParameters() {
+		return this.currentMeta()?.animated ?? null;
+	}
+	currentMotion() {
+		const { currentGroup, currentIndex } = this.state;
+		if (currentGroup === void 0 || currentIndex === void 0) return null;
+		return this.motionGroups[currentGroup]?.[currentIndex] ?? null;
+	}
+	currentMeta() {
+		const motion = this.currentMotion();
+		return motion ? this.meta.get(motion) ?? null : null;
+	}
+	releaseIdle() {
+		const motion = this.currentMotion();
+		super.releaseIdle();
+		if (motion) this.release = {
+			ids: this.meta.get(motion)?.parameterIds ?? [],
+			seconds: motion.getFadeOutTime(),
+			ramp: null
+		};
+	}
+	/** One frame of the ease-to-rest, ahead of the motions so a new idle's fade-in blends from it. */
+	updateRelease(model, now) {
+		const r = this.release;
+		if (!r) return;
+		if (r.ramp === null) {
+			const count = model.getParameterCount();
+			const indices = r.ids.map((id) => model.getParameterIndex(id)).filter((index) => index < count);
+			r.ramp = {
+				indices,
+				from: indices.map((index) => model.getParameterValueByIndex(index)),
+				startedAt: now
+			};
+		}
+		const { indices, from, startedAt } = r.ramp;
+		const t = r.seconds > 0 ? Math.min(1, (now - startedAt) / r.seconds) : 1;
+		const w = CubismMath.getEasingSine(t);
+		for (let i = 0; i < indices.length; i++) {
+			const index = indices[i];
+			const start = from[i];
+			model.setParameterValueByIndex(index, start + (model.getParameterDefaultValue(index) - start) * w);
+		}
+		if (t >= 1) this.release = null;
+	}
 	updateParameters(model, now) {
+		this.updateRelease(model, now);
 		return this.queueManager.doUpdateMotion(model, now);
 	}
 	destroy() {
@@ -14728,6 +14857,23 @@ var CubismMotionManager = class extends MotionManager {
 		return ids.map((id) => idManager.getId(id));
 	}
 };
+function motionMeta(motion, eyeBlinkIds) {
+	const parameterIds = [];
+	const animated = /* @__PURE__ */ new Set();
+	let blinks = false;
+	for (const curve of motion._motionData.curves) {
+		const id = getCurveId$1(curve);
+		if (curve.type === 1) {
+			parameterIds.push(curve.id);
+			if (id !== void 0) animated.add(id);
+		} else if (curve.type === 0 && id === "EyeBlink") blinks = true;
+	}
+	return {
+		parameterIds,
+		animated,
+		blinks: blinks || eyeBlinkIds.some((id) => animated.has(id))
+	};
+}
 function getCurveId$1(curve) {
 	if (!curve || typeof curve !== "object") return;
 	const id = curve.id;
@@ -15280,10 +15426,10 @@ var CubismInternalModel = class extends InternalModel {
 		dt /= 1e3;
 		now /= 1e3;
 		const model = this.coreModel;
-		const motionUpdated = this.updateMotions(model, now);
+		this.updateMotions(model, now);
 		model.saveParameters();
 		this.motionManager.expressionManager?.update(model, now);
-		if (!motionUpdated) this.eyeBlink?.updateParameters?.(model, dt);
+		if (!this.motionManager.currentMotionBlinks()) this.eyeBlink?.updateParameters?.(model, dt);
 		this.updateFocus();
 		this.updateNaturalMovements(dt * 1e3, now * 1e3);
 		if (this.lipSync && this.motionManager.currentAudio) {