facebetter 1.0.14 → 1.1.1

package/dist/facebetter.esm.js

@@ -47,7 +47,13 @@ class EngineConfig {
     this.appId = config.appId || null;
     this.appKey = config.appKey || null;
     this.licenseJson = config.licenseJson || null;
-    this.resourcePath = '/facebetter/resource.bundle';
+    this.resourcePath = '/resource.fbd';
+    /**
+     * Whether to use an external GL context (native platforms only).
+     * In Web/WASM environments, this field is kept for configuration structure alignment,
+     * but it does not take effect in the current implementation.
+     */
+    this.externalContext = !!config.externalContext;
   }
 
   /**
@@ -55,11 +61,11 @@ class EngineConfig {
    * @returns {boolean} True if valid
    */
   isValid() {
-    // 如果提供了 licenseJson，则使用授权数据验证
+    // If licenseJson is provided, use it for validation
     if (this.licenseJson) {
       return typeof this.licenseJson === 'string' && this.licenseJson.trim() !== '';
     }
-    // 否则需要 appId 和 appKey
+    // Otherwise appId and appKey are required
     return this.appId && typeof this.appId === 'string' && this.appId.trim() !== '' &&
            this.appKey && typeof this.appKey === 'string' && this.appKey.trim() !== '';
   }
@@ -82,61 +88,87 @@ class EngineConfig {
  * Beauty type enumeration
  */
 const BeautyType$1 = {
-  Basic: 0,            // 基础美颜
-  Reshape: 1,         // 面部重塑
-  Makeup: 2,          // 美妆效果
-  VirtualBackground: 3 // 虚拟背景
+  Basic: 0,             // Basic beauty (smoothing, whitening, etc.)
+  Reshape: 1,           // Face reshaping (face thinning, big eyes, etc.)
+  Makeup: 2,            // Makeup effects (lipstick, blush, etc.)
+  VirtualBackground: 3,  // Virtual background (blur, image replacement)
+  ChromaKey: 4,          // Chroma key (green screen removal)
+  Filter: 5,             // LUT based filter
+  Sticker: 6             // 2D/3D sticker
 };
 
 /**
  * Basic beauty parameter enumeration
+ * All values should be in range [0.0, 1.0]
  */
 const BasicParam$1 = {
-  Smoothing: 0,   // 磨皮
-  Sharpening: 1,   // 锐化
-  Whitening: 2,   // 美白
-  Rosiness: 3     // 红润
+  Smoothing: 0,   // Skin smoothing (0.0: none, 1.0: maximum)
+  Sharpening: 1,  // Image sharpening (0.0: none, 1.0: maximum)
+  Whitening: 2,   // Skin whitening (0.0: none, 1.0: maximum)
+  Rosiness: 3     // Skin rosiness (0.0: none, 1.0: maximum)
 };
 
 /**
  * Face reshape parameter enumeration
+ * All values should be in range [0.0, 1.0]
  */
 const ReshapeParam$1 = {
-  FaceThin: 0,    // 瘦脸
-  FaceVShape: 1,  // V脸
-  FaceNarrow: 2,  // 窄脸
-  FaceShort: 3,   // 短脸
-  Cheekbone: 4,   // 颧骨
-  Jawbone: 5,     // 下颌骨
-  Chin: 6,        // 下巴
-  NoseSlim: 7,    // 瘦鼻梁
-  EyeSize: 8,     // 大眼
-  EyeDistance: 9  // 眼距
+  FaceThinning: 0,  // Face thinning (0.0: none, 1.0: maximum)
+  FaceVShape: 1,    // V-shape face (0.0: none, 1.0: maximum)
+  FaceNarrowing: 2, // Face narrowing (0.0: none, 1.0: maximum)
+  FaceShortening: 3,// Face shortening (0.0: none, 1.0: maximum)
+  Cheekbone: 4,     // Cheekbone slimming (0.0: none, 1.0: maximum)
+  Jawbone: 5,       // Jawbone slimming (0.0: none, 1.0: maximum)
+  Chin: 6,          // Chin length adjustment (0.0: none, 1.0: maximum)
+  NoseSlimming: 7,  // Nose slimming (0.0: none, 1.0: maximum)
+  EyeSize: 8,       // Eye size (0.0: normal, 1.0: maximum)
+  EyeDistance: 9    // Eye distance (0.0: normal, 1.0: maximum)
 };
 
 /**
  * Makeup parameter enumeration
+ * All values should be in range [0.0, 1.0]
  */
 const MakeupParam$1 = {
-  Lipstick: 0,    // 口红
-  Blush: 1        // 腮红
+  Lipstick: 0,    // Lipstick intensity (0.0: none, 1.0: maximum)
+  Blush: 1        // Blush intensity (0.0: none, 1.0: maximum)
+};
+
+/**
+ * Chroma Key parameter enumeration
+ */
+const ChromaKeyParam$1 = {
+  KeyColor: 0,      // Key color (0.0: Green, 1.0: Blue, 2.0: Red)
+  Similarity: 1,    // Color similarity (0.0 - 1.0)
+  Smoothness: 2,    // Edge smoothness (0.0 - 1.0)
+  Desaturation: 3   // Spill desaturation (0.0 - 1.0)
 };
 
 /**
  * Background mode enumeration
  */
 const BackgroundMode$1 = {
-  None: 0,        // 无背景处理
-  Blur: 1,        // 模糊背景
-  Image: 2        // 背景图片替换
+  None: 0,        // No background processing
+  Blur: 1,        // Blurred background
+  Image: 2        // Background image replacement
 };
 
 /**
- * Process mode enumeration
+ * Frame type enumeration
  */
-const ProcessMode$1 = {
-  Image: 0,       // 图片模式
-  Video: 1        // 视频模式
+const FrameType$1 = {
+  Image: 0,       // Image mode
+  Video: 1        // Video mode
+};
+
+/**
+ * Mirror mode enumeration (apply to input before processing)
+ */
+const MirrorMode$1 = {
+  None: 0,        // No mirror
+  Horizontal: 1,  // Mirror horizontally (e.g. front camera selfie)
+  Vertical: 2,    // Mirror vertically
+  Both: 3         // Mirror both axes
 };
 
 /**
@@ -172,8 +204,10 @@ var constants = /*#__PURE__*/Object.freeze({
   BackgroundMode: BackgroundMode$1,
   BasicParam: BasicParam$1,
   BeautyType: BeautyType$1,
+  ChromaKeyParam: ChromaKeyParam$1,
+  FrameType: FrameType$1,
   MakeupParam: MakeupParam$1,
-  ProcessMode: ProcessMode$1,
+  MirrorMode: MirrorMode$1,
   ReshapeParam: ReshapeParam$1,
   VirtualBackgroundOptions: VirtualBackgroundOptions$1
 });
@@ -211,7 +245,7 @@ class BeautyEffectEngine {
       throw new FacebetterError('Platform API is required');
     }
 
-    // 如果传入的是 EngineConfig 实例，直接使用；否则创建新的 EngineConfig
+    // If an EngineConfig instance is passed, use it directly; otherwise create a new EngineConfig
     let engineConfig;
     if (config instanceof EngineConfig) {
       engineConfig = config;
@@ -229,20 +263,23 @@ class BeautyEffectEngine {
     this.appId = engineConfig.appId;
     this.appKey = engineConfig.appKey;
     this.licenseJson = engineConfig.licenseJson;
-    this.resourcePath = '/facebetter/resource.bundle';
+    this.resourcePath = '/resource.fbd';
     this.enginePtr = null;
     this.initialized = false;
     this.srcBufferPtr = null;
     this.dstBufferPtr = null;
     this.bufferSize = 0;
     
+    // Callback related state
+    this._callbackSharedBufferPtr = null;
+    this._callbackSharedBufferSize = 0;
+    
     // Store platform API
     this._platformAPI = platformAPI;
     this._loadWasmModule = platformAPI.loadWasmModule;
     this._getWasmModule = platformAPI.getWasmModule;
     this._getWasmBuffer = platformAPI.getWasmBuffer;
     this._toImageData = platformAPI.toImageData;
-    this._verifyAppKeyOnline = platformAPI.verifyAppKeyOnline;
     this._ensureGPUPixelCanvas = platformAPI.ensureGPUPixelCanvas;
     this._cleanupGPUPixelCanvas = platformAPI.cleanupGPUPixelCanvas;
     
@@ -320,23 +357,22 @@ class BeautyEffectEngine {
    * @returns {Promise<void>} Promise that resolves when initialization is complete
    */
   async init(options = {}) {
-    // 并发控制：如果已经初始化，直接返回
+    // Concurrency control: if already initialized, return immediately
     if (this.initialized) {
       return;
     }
 
-    // 并发控制：如果正在初始化，返回同一个 Promise
+    // Concurrency control: if initialization is in progress, return the same Promise
     if (this._initPromise) {
       return this._initPromise;
     }
 
-    // 创建初始化 Promise
+    // Create initialization Promise
     this._initPromise = (async () => {
       try {
         const wasmTimeout = options.timeout || 30000;
-        const authTimeout = options.authTimeout || 10000;
 
-        // 等待 WASM 模块加载（带超时）
+        // Wait for WASM module loading (with timeout)
         try {
           await Promise.race([
             this._wasmLoadPromise,
@@ -348,48 +384,60 @@ class BeautyEffectEngine {
 
         const Module = this._getWasmModule();
 
-        let licenseJsonToUse = this.licenseJson;
-
-        // 如果用户提供了 appId 和 appKey（但没有提供 licenseJson），则在 JS 层发送 HTTP 请求
-        if (this.appId && this.appKey && !this.licenseJson && this._verifyAppKeyOnline) {
-          try {
-            // 在线认证（带超时）
-            const authResponse = await Promise.race([
-              this._verifyAppKeyOnline(this.appId, this.appKey),
-              this._createTimeout(authTimeout, 'Online authentication')
-            ]);
-            
-            if (!authResponse) {
-              throw new FacebetterError(
-                'Failed to get server response from online_auth API. The server returned an empty response.',
-                'AUTH_EMPTY_RESPONSE'
-              );
+        // Setup usage report proxy for WASM
+        if (!Module.onReportUsage) {
+          Module.onReportUsage = async (payloadJson) => {
+            try {
+              const url = 'https://facebetter.pixpark.net/facebetter/v1/report';
+              const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                  'Content-Type': 'application/json'
+                },
+                body: payloadJson
+              });
+              return response.ok;
+            } catch (error) {
+              return false;
             }
+          };
+        }
 
-            // 将服务器响应转换为 JSON 字符串，作为 licenseJson 传递给 WASM 层
-            licenseJsonToUse = JSON.stringify(authResponse);
-            console.log('Online auth response received, using as licenseJson');
-          } catch (error) {
-            if (error instanceof FacebetterError && error.code === 'TIMEOUT') {
-              throw new FacebetterError(
-                `Online authentication timed out after ${authTimeout}ms. Please check your network connection or provide licenseJson directly.`,
-                'AUTH_TIMEOUT'
-              );
+        // Setup online auth proxy for WASM
+        if (!Module.onOnlineAuth) {
+          Module.onOnlineAuth = async (payloadJson) => {
+            try {
+              const url = 'https://facebetter.pixpark.net/facebetter/v1/auth';
+              const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                  'Content-Type': 'application/json'
+                },
+                body: payloadJson
+              });
+              if (!response.ok) {
+                console.warn('[JS Engine] Online auth fetch failed with status:', response.status);
+                return "";
+              }
+              return await response.text();
+            } catch (error) {
+              console.error('[JS Engine] Online auth fetch exception:', error);
+              return "";
             }
-            throw this._enhanceError(error, 'Failed to verify app key online');
-          }
+          };
         }
 
-        // 如果用户直接提供了 licenseJson，则直接使用
-        // 如果通过 appId/appKey 获取到了响应，则使用响应作为 licenseJson
-        // WASM 层只需要验证 licenseJson，不需要发送 HTTP 请求
+        // Create engine instance, auth (online/offline) is handled by WASM layer via onOnlineAuth
         const enginePtr = Module.ccall(
-          'CreateBeautyEffectEngine',
+          'CreateBeautyEffectEngineEx',
           'number',
-          ['string', 'string'],
+          ['string', 'string', 'string', 'string', 'number'],
           [
             this.resourcePath,
-            licenseJsonToUse || ''  // 使用 licenseJson 验证
+            this.licenseJson || '',
+            this.appId || '',
+            this.appKey || '',
+            this.config.externalContext ? 1 : 0
           ]
         );
 
@@ -402,9 +450,9 @@ class BeautyEffectEngine {
 
         this.enginePtr = enginePtr;
         this.initialized = true;
-        this._initPromise = null; // 清除 Promise 缓存，允许重新初始化（如果需要）
+        this._initPromise = null; // Clear Promise cache, allow re-initialization (if needed)
       } catch (error) {
-        this._initPromise = null; // 清除 Promise 缓存，允许重试
+        this._initPromise = null; // Clear Promise cache, allow retry
         throw error;
       }
     })();
@@ -432,11 +480,18 @@ class BeautyEffectEngine {
       this.dstBufferPtr = null;
     }
 
+    // Clean up shared memory
+    if (this._callbackSharedBufferPtr) {
+      Module._free(this._callbackSharedBufferPtr);
+      this._callbackSharedBufferPtr = null;
+      this._callbackSharedBufferSize = 0;
+    }
+
     Module.ccall('DestroyBeautyEffectEngine', null, ['number'], [this.enginePtr]);
     this.enginePtr = null;
     this.initialized = false;
     this.bufferSize = 0;
-    this._initPromise = null; // 清除初始化 Promise
+    this._initPromise = null; // Clear initialization Promise
     
     // Clean up offscreen canvas
     if (this._offscreenCanvas) {
@@ -541,7 +596,7 @@ class BeautyEffectEngine {
 
   /**
    * Sets a basic beauty parameter
-   * @param {number} param - Parameter (use BasicParam enum)
+   * @param {number} param - Parameter (use BasicParam enum, e.g., BasicParam.Smoothing)
    * @param {number} value - Parameter value (0.0 - 1.0)
    */
   setBasicParam(param, value) {
@@ -551,7 +606,7 @@ class BeautyEffectEngine {
 
   /**
    * Sets a reshape parameter
-   * @param {number} param - Parameter (use ReshapeParam enum)
+   * @param {number} param - Parameter (use ReshapeParam enum, e.g., ReshapeParam.FaceThinning)
    * @param {number} value - Parameter value (0.0 - 1.0)
    */
   setReshapeParam(param, value) {
@@ -561,7 +616,7 @@ class BeautyEffectEngine {
 
   /**
    * Sets a makeup parameter
-   * @param {number} param - Parameter (use MakeupParam enum)
+   * @param {number} param - Parameter (use MakeupParam enum, e.g., MakeupParam.Lipstick)
    * @param {number} value - Parameter value (0.0 - 1.0)
    */
   setMakeupParam(param, value) {
@@ -570,7 +625,253 @@ class BeautyEffectEngine {
   }
 
   /**
-   * Internal method to set beauty parameters
+   * Sets chroma key parameter
+   * @param {number} param - Parameter (use ChromaKeyParam enum, e.g., ChromaKeyParam.Similarity)
+   * @param {number} value - Parameter value (KeyColor: 0.0=Green, 1.0=Blue, 2.0=Red; others 0.0-1.0)
+   */
+  setChromaKeyParam(param, value) {
+    this._ensureInitialized();
+    // For KeyColor, values are 0, 1, 2, not 0.0-1.0
+    if (param === 0) { // ChromaKeyParam.KeyColor
+        const Module = this._getWasmModule();
+        const result = Module.ccall(
+          'SetBeautyParamChromaKey',
+          'number',
+          ['number', 'number', 'number'],
+          [this.enginePtr, param, value]
+        );
+        checkResult(result, `Failed to set chroma key parameter`);
+        return;
+    }
+    this._setBeautyParam('SetBeautyParamChromaKey', param, value);
+  }
+
+  /**
+   * Sets a LUT-based filter
+   * @param {string} filterId - Unique identifier of the filter (e.g., "chuxin"). Pass "" to clear.
+   */
+  setFilter(filterId) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'SetFilter',
+      'number',
+      ['number', 'string'],
+      [this.enginePtr, filterId || '']
+    );
+    checkResult(result, 'Failed to set filter');
+  }
+
+  /**
+   * Sets the intensity of the current filter
+   * @param {number} intensity - Filter intensity (0.0 - 1.0)
+   */
+  setFilterIntensity(intensity) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'SetFilterIntensity',
+      'number',
+      ['number', 'number'],
+      [this.enginePtr, intensity]
+    );
+    checkResult(result, 'Failed to set filter intensity');
+  }
+
+  /**
+   * Sets a 2D sticker
+   * @param {string} stickerId - Unique identifier of the sticker (e.g., "樱花"). Pass "" to clear.
+   */
+  setSticker(stickerId) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'SetSticker',
+      'number',
+      ['number', 'string'],
+      [this.enginePtr, stickerId || '']
+    );
+    checkResult(result, 'Failed to set sticker');
+  }
+
+  /**
+   * Registers a filter from a file path or data
+   * @param {string} filterId - Unique identifier for the filter
+   * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data
+   */
+  registerFilter(filterId, resource) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+
+    if (typeof resource === 'string') {
+      const result = Module.ccall(
+        'RegisterFilterPath',
+        'number',
+        ['number', 'string', 'string'],
+        [this.enginePtr, filterId, resource]
+      );
+      checkResult(result, `Failed to register filter path: ${filterId}`);
+    } else if (resource instanceof Uint8Array) {
+      const dataPtr = Module._malloc(resource.length);
+      Module.HEAPU8.set(resource, dataPtr);
+      try {
+        const result = Module.ccall(
+          'RegisterFilterData',
+          'number',
+          ['number', 'string', 'number', 'number'],
+          [this.enginePtr, filterId, dataPtr, resource.length]
+        );
+        checkResult(result, `Failed to register filter data: ${filterId}`);
+      } finally {
+        Module._free(dataPtr);
+      }
+    } else {
+      throw new FacebetterError('Resource must be a string path or Uint8Array data');
+    }
+  }
+
+  /**
+   * Registers a sticker from a file path or data
+   * @param {string} stickerId - Unique identifier for the sticker
+   * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data
+   */
+  registerSticker(stickerId, resource) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+
+    if (typeof resource === 'string') {
+      const result = Module.ccall(
+        'RegisterStickerPath',
+        'number',
+        ['number', 'string', 'string'],
+        [this.enginePtr, stickerId, resource]
+      );
+      checkResult(result, `Failed to register sticker path: ${stickerId}`);
+    } else if (resource instanceof Uint8Array) {
+      const dataPtr = Module._malloc(resource.length);
+      Module.HEAPU8.set(resource, dataPtr);
+      try {
+        const result = Module.ccall(
+          'RegisterStickerData',
+          'number',
+          ['number', 'string', 'number', 'number'],
+          [this.enginePtr, stickerId, dataPtr, resource.length]
+        );
+        checkResult(result, `Failed to register sticker data: ${stickerId}`);
+      } finally {
+        Module._free(dataPtr);
+      }
+    } else {
+      throw new FacebetterError('Resource must be a string path or Uint8Array data');
+    }
+  }
+
+  /**
+   * Unregisters a specific filter
+   * @param {string} filterId - Filter ID to unregister
+   */
+  unregisterFilter(filterId) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'UnregisterFilter',
+      'number',
+      ['number', 'string'],
+      [this.enginePtr, filterId]
+    );
+    checkResult(result, `Failed to unregister filter: ${filterId}`);
+  }
+
+  /**
+   * Unregisters all filters
+   */
+  unregisterAllFilters() {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'UnregisterAllFilters',
+      'number',
+      ['number'],
+      [this.enginePtr]
+    );
+    checkResult(result, 'Failed to unregister all filters');
+  }
+
+  /**
+   * Unregisters a specific sticker
+   * @param {string} stickerId - Sticker ID to unregister
+   */
+  unregisterSticker(stickerId) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    const result = Module.ccall(
+      'UnregisterSticker',
+      'number',
+      ['number', 'string'],
+      [this.enginePtr, stickerId]
+    );
+    checkResult(result, `Failed to unregister sticker: ${stickerId}`);
+  }
+
+  /**
+   * Unregisters all stickers
+   */
+  unregisterAllStickers() {
+     this._ensureInitialized();
+     const Module = this._getWasmModule();
+     const result = Module.ccall(
+       'UnregisterAllStickers',
+       'number',
+       ['number'],
+       [this.enginePtr]
+     );
+     checkResult(result, 'Failed to unregister all stickers');
+   }
+ 
+   /**
+    * Gets the list of registered filter IDs
+    * @returns {string[]} Array of registered filter IDs
+    */
+   getRegisteredFilters() {
+     this._ensureInitialized();
+     const Module = this._getWasmModule();
+     const jsonStr = Module.ccall(
+       'GetRegisteredFilters',
+       'string',
+       ['number'],
+       [this.enginePtr]
+     );
+     try {
+       return JSON.parse(jsonStr || '[]');
+     } catch (e) {
+       console.error('Failed to parse registered filters JSON:', e);
+       return [];
+     }
+   }
+ 
+   /**
+    * Gets the list of registered sticker IDs
+    * @returns {string[]} Array of registered sticker IDs
+    */
+   getRegisteredStickers() {
+     this._ensureInitialized();
+     const Module = this._getWasmModule();
+     const jsonStr = Module.ccall(
+       'GetRegisteredStickers',
+       'string',
+       ['number'],
+       [this.enginePtr]
+     );
+     try {
+       return JSON.parse(jsonStr || '[]');
+     } catch (e) {
+       console.error('Failed to parse registered stickers JSON:', e);
+       return [];
+     }
+   }
+ 
+   /**
+    * Internal method to set beauty parameters
    * @private
    */
   _setBeautyParam(functionName, param, value) {
@@ -589,6 +890,139 @@ class BeautyEffectEngine {
     checkResult(result, `Failed to set beauty parameter`);
   }
 
+  /**
+   * Sets engine callbacks (face landmarks detection)
+   * @param {Object} callbacks - Callback functions
+   * @param {Function} callbacks.onFaceLandmarks - Callback for face landmarks detection
+   * @param {number} [callbacks.maxFaces=10] - Maximum number of faces to support (affects shared buffer size)
+   */
+  setCallbacks(callbacks) {
+    this._ensureInitialized();
+    const Module = this._getWasmModule();
+    
+    // Initialize callback storage (if it doesn't exist)
+    if (!Module._face_landmarks_callbacks) {
+      Module._face_landmarks_callbacks = [];
+    }
+    
+    let callbackId = 0;
+    let sharedBufferPtr = null;
+    let sharedBufferSize = 0;
+    
+    if (callbacks && callbacks.onFaceLandmarks) {
+      // Get max faces (default 10)
+      const maxFaces = callbacks.maxFaces || 10;
+      
+      // Pre-allocate shared memory
+      // Metadata: 2 ints (frame_number, face_count) = 8 bytes
+      // Face data: maxFaces * 343 floats * 4 bytes = maxFaces * 1372 bytes
+      const metadataSize = 2 * 4;  // 2 ints
+      const faceDataSize = maxFaces * 343 * 4;  // 343 floats per face
+      sharedBufferSize = metadataSize + faceDataSize;
+      sharedBufferPtr = Module._malloc(sharedBufferSize);
+      
+      if (!sharedBufferPtr) {
+        throw new FacebetterError('Failed to allocate shared buffer for callbacks');
+      }
+      
+      // Register callback function (internal wrapper, reads data from shared memory)
+      // Push first, then get index as callbackId (allows callbackId to be 0)
+      Module._face_landmarks_callbacks.push(
+        (frameNumber, faceCount, dataPtr) => {
+          // Read data from shared memory (zero-copy)
+          const heap = Module.HEAPF32;
+          const dataOffset = dataPtr / 4;  // float is 4 bytes
+          
+          const results = [];
+          const FLOATS_PER_FACE = 343;
+          
+          for (let i = 0; i < faceCount; i++) {
+            const faceOffset = dataOffset + i * FLOATS_PER_FACE;
+            let offset = faceOffset;
+            
+            // Read rect
+            const rect = {
+              x: heap[offset++],
+              y: heap[offset++],
+              width: heap[offset++],
+              height: heap[offset++]
+            };
+            
+            // Read basic fields
+            const faceId = Math.round(heap[offset++]);
+            const faceAction = Math.round(heap[offset++]);
+            const score = heap[offset++];
+            const pitch = heap[offset++];
+            const roll = heap[offset++];
+            const yaw = heap[offset++];
+            
+            // Read key_points (111 points)
+            const keyPoints = [];
+            for (let j = 0; j < 111; j++) {
+              keyPoints.push({
+                x: heap[offset++],
+                y: heap[offset++]
+              });
+            }
+            
+            // Read visibility (111 points)
+            const visibility = [];
+            for (let j = 0; j < 111; j++) {
+              visibility.push(heap[offset++]);
+            }
+            
+            results.push({
+              rect,
+              key_points: keyPoints,
+              visibility,
+              face_id: faceId,
+              face_action: faceAction,
+              score,
+              pitch,
+              roll,
+              yaw
+            });
+          }
+          
+          // Call user callback
+          callbacks.onFaceLandmarks(results);
+        }
+      );
+      
+      // Get callback ID (index after push, can be 0)
+      callbackId = Module._face_landmarks_callbacks.length - 1;
+    }
+    
+    // Call C API
+    const result = Module.ccall(
+      'SetCallbacks',
+      'number',
+      ['number', 'number', 'number', 'number'],
+      [
+        this.enginePtr,
+        callbackId,
+        sharedBufferPtr || 0,
+        sharedBufferSize
+      ]
+    );
+    
+    checkResult(result, 'Failed to set callbacks');
+    
+    // Clean up old shared memory (if it exists)
+    if (this._callbackSharedBufferPtr) {
+      Module._free(this._callbackSharedBufferPtr);
+    }
+    
+    // Store new shared memory pointer for cleanup
+    if (sharedBufferPtr) {
+      this._callbackSharedBufferPtr = sharedBufferPtr;
+      this._callbackSharedBufferSize = sharedBufferSize;
+    } else {
+      this._callbackSharedBufferPtr = null;
+      this._callbackSharedBufferSize = 0;
+    }
+  }
+
   /**
    * Sets virtual background options (unified API, matches C++/Java/OC)
    * @param {VirtualBackgroundOptions|Object} options - Virtual background options
@@ -606,7 +1040,7 @@ class BeautyEffectEngine {
     let imageBufferPtr = null;
     
     try {
-      // 如果提供了背景图片，转换为 ImageData 并准备缓冲区
+      // If a background image is provided, convert to ImageData and prepare buffer
       if (opts.backgroundImage) {
         imageData = this._toImageData(opts.backgroundImage);
         const bufferSize = imageData.width * imageData.height * 4;
@@ -617,7 +1051,7 @@ class BeautyEffectEngine {
         view.set(imageData.data);
       }
       
-      // 使用统一的 SetVirtualBackground C 接口（与其他平台一致）
+      // Use unified SetVirtualBackground C interface (consistent with other platforms)
       const result = Module.ccall(
         'SetVirtualBackground',
         'number',
@@ -625,7 +1059,7 @@ class BeautyEffectEngine {
         [
           this.enginePtr,
           opts.mode,
-          imageBufferPtr || 0,  // 如果为 null，传递 0
+          imageBufferPtr || 0,  // If null, pass 0
           imageData ? imageData.width : 0,
           imageData ? imageData.height : 0,
           imageData ? imageData.width * 4 : 0
@@ -634,7 +1068,7 @@ class BeautyEffectEngine {
       
       checkResult(result, 'Failed to set virtual background');
     } finally {
-      // 释放内存
+      // Free memory
       if (imageBufferPtr) {
         Module._free(imageBufferPtr);
       }
@@ -674,10 +1108,11 @@ class BeautyEffectEngine {
    * @param {ImageData|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|Uint8ClampedArray} input - Input image
    * @param {number} width - Image width (required if input is Uint8ClampedArray)
    * @param {number} height - Image height (required if input is Uint8ClampedArray)
-   * @param {number} processMode - Process mode (use ProcessMode enum, default: ProcessMode.Image)
+   * @param {number} frameType - Frame type (use FrameType enum, default: FrameType.Video)
+   * @param {number} mirrorMode - Mirror mode applied to input before processing (MirrorMode enum, default: MirrorMode.None)
    * @returns {ImageData} Processed image data
    */
-  processImage(input, width, height, processMode = ProcessMode$1.Image) {
+  processImage(input, width, height, frameType = FrameType$1.Video, mirrorMode = MirrorMode$1.None) {
     this._ensureInitialized();
     const imageData = this._platformAPI.toImageData(input, width, height);
     const Module = this._getWasmModule();
@@ -695,7 +1130,7 @@ class BeautyEffectEngine {
       const result = Module.ccall(
         'ProcessImageRGBA',
         'number',
-        ['number', 'number', 'number', 'number', 'number', 'number', 'number'],
+        ['number', 'number', 'number', 'number', 'number', 'number', 'number', 'number'],
         [
           this.enginePtr,
           this.srcBufferPtr,
@@ -703,7 +1138,8 @@ class BeautyEffectEngine {
           imageData.height,
           imageData.width * 4,
           this.dstBufferPtr,
-          processMode
+          frameType,
+          mirrorMode
         ]
       );
 
@@ -722,6 +1158,65 @@ class BeautyEffectEngine {
     }
   }
 
+  /**
+   * Processes an external GPU texture.
+   *
+   * Note:
+   * - This interface is mainly used for integration with internal WASM or advanced scenarios.
+   * - textureHandle must be a texture handle (uint32) compatible with the OpenGL/WebGL context used by WASM.
+   * - For common web scenarios, it is recommended to use processImage with ImageData/Canvas etc.
+   *
+   * @param {number} textureHandle - External texture handle (GL_TEXTURE_2D)
+   * @param {number} width - Texture width
+   * @param {number} height - Texture height
+   * @param {number} stride - Row stride (usually width * 4)
+   * @param {number} [frameType] - Frame type (FrameType.Image / FrameType.Video)
+   * @param {number} [mirrorMode] - Mirror mode (MirrorMode enum; texture path does not support mirror, param reserved)
+   * @returns {number} Processed texture handle (GL_TEXTURE_2D, uint32)
+   */
+  processTexture(textureHandle,
+                 width,
+                 height,
+                 stride,
+                 frameType = FrameType$1.Video,
+                 mirrorMode = MirrorMode$1.None) {
+    this._ensureInitialized();
+    if (!textureHandle || width <= 0 || height <= 0 || stride <= 0) {
+      throw new FacebetterError('Invalid textureHandle or dimensions for processTexture');
+    }
+
+    const Module = this._getWasmModule();
+
+    try {
+      const result = Module.ccall(
+        'ProcessImageTexture',
+        'number',
+        ['number', 'number', 'number', 'number', 'number', 'number', 'number'],
+        [
+          this.enginePtr,
+          textureHandle,
+          width,
+          height,
+          stride,
+          frameType,
+          mirrorMode
+        ]
+      );
+
+      if (!result || result === 0) {
+        throw new FacebetterError('Failed to process external texture or got invalid output texture');
+      }
+
+      // Return processed texture handle for caller to continue using in same GL context
+      return result;
+    } catch (error) {
+      if (error instanceof FacebetterError) {
+        throw error;
+      }
+      throw new FacebetterError(`Texture processing error: ${error.message}`);
+    }
+  }
+
   /**
    * Ensures the engine is initialized
    * @private
@@ -842,77 +1337,6 @@ function toImageData(source, width, height) {
   throw new FacebetterError('Unsupported image source type');
 }
 
-/**
- * Gets User-Agent string for web platform
- * @returns {string} User-Agent string
- */
-function getUserAgentString() {
-  return 'FB/1.0 (web; wasm32)';
-}
-
-/**
- * Generates HMAC-SHA256 signature (browser version)
- * @param {string} key - HMAC key (app_key)
- * @param {string} data - Data to sign (timestamp string)
- * @returns {Promise<string>} Promise that resolves with hex-encoded signature
- */
-async function generateHMACSignature(key, data) {
-  const encoder = new TextEncoder();
-  const keyData = encoder.encode(key);
-  const messageData = encoder.encode(data);
-
-  const cryptoKey = await crypto.subtle.importKey(
-    'raw',
-    keyData,
-    { name: 'HMAC', hash: 'SHA-256' },
-    false,
-    ['sign']
-  );
-
-  const signature = await crypto.subtle.sign('HMAC', cryptoKey, messageData);
-
-  // Convert to hex string
-  const hashArray = Array.from(new Uint8Array(signature));
-  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-  return hashHex;
-}
-
-/**
- * Calls online_auth API to verify app_key (browser version)
- * @param {string} appId - Application ID
- * @param {string} appKey - Application key
- * @returns {Promise<Object>} Promise that resolves with response data
- */
-async function verifyAppKeyOnline(appId, appKey) {
-  try {
-    const timestamp = Math.floor(Date.now() / 1000);
-    const timestampStr = timestamp.toString();
-    const hmacSignature = await generateHMACSignature(appKey, timestampStr);
-
-    const requestBody = {
-      p_app_id: appId,
-      p_hmac_signature: hmacSignature,
-      p_timestamp: timestamp,
-      p_user_agent: getUserAgentString()
-    };
-
-    const response = await fetch('https://facebetter.pixpark.net/rest/v1/rpc/online_auth', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'User-Agent': getUserAgentString()
-      },
-      body: JSON.stringify(requestBody)
-    });
-
-    const responseData = await response.json();
-    return responseData;
-  } catch (error) {
-    console.error('Online auth request failed:', error);
-    return null;
-  }
-}
-
 /**
  * ESM Entry Point
  * For Vue/React/Vite/Webpack (ES Module)
@@ -1054,7 +1478,6 @@ const platformAPI = {
   getWasmModule,
   getWasmBuffer,
   toImageData: toImageData,
-  verifyAppKeyOnline: verifyAppKeyOnline,
   ensureGPUPixelCanvas,
   cleanupGPUPixelCanvas
 };
@@ -1078,8 +1501,10 @@ const BeautyType = BeautyType$1;
 const BasicParam = BasicParam$1;
 const ReshapeParam = ReshapeParam$1;
 const MakeupParam = MakeupParam$1;
+const ChromaKeyParam = ChromaKeyParam$1;
 const BackgroundMode = BackgroundMode$1;
-const ProcessMode = ProcessMode$1;
+const FrameType = FrameType$1;
+const MirrorMode = MirrorMode$1;
 const VirtualBackgroundOptions = VirtualBackgroundOptions$1;
 
 // Default export
@@ -1091,5 +1516,5 @@ var index = {
   loadWasmModule
 };
 
-export { BackgroundMode, BasicParam, ESMBeautyEffectEngine as BeautyEffectEngine, BeautyType, EngineConfig, FacebetterError, MakeupParam, ProcessMode, ReshapeParam, VirtualBackgroundOptions, createBeautyEffectEngine, index as default, getWasmBuffer, getWasmModule, loadWasmModule };
+export { BackgroundMode, BasicParam, ESMBeautyEffectEngine as BeautyEffectEngine, BeautyType, ChromaKeyParam, EngineConfig, FacebetterError, FrameType, MakeupParam, MirrorMode, ReshapeParam, VirtualBackgroundOptions, createBeautyEffectEngine, index as default, getWasmBuffer, getWasmModule, loadWasmModule };
 //# sourceMappingURL=facebetter.esm.js.map