facebetter 1.0.14 → 1.1.1

package/dist/facebetter.js

@@ -53,7 +53,13 @@
       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;
     }
 
     /**
@@ -61,11 +67,11 @@
      * @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() !== '';
     }
@@ -88,61 +94,87 @@
    * 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 = {
+    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
   };
 
   /**
@@ -178,8 +210,10 @@
     BackgroundMode: BackgroundMode$1,
     BasicParam: BasicParam$1,
     BeautyType: BeautyType$1,
+    ChromaKeyParam: ChromaKeyParam,
+    FrameType: FrameType$1,
     MakeupParam: MakeupParam$1,
-    ProcessMode: ProcessMode$1,
+    MirrorMode: MirrorMode$1,
     ReshapeParam: ReshapeParam$1,
     VirtualBackgroundOptions: VirtualBackgroundOptions$1
   });
@@ -217,7 +251,7 @@
         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;
@@ -235,20 +269,23 @@
       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;
       
@@ -326,23 +363,22 @@
      * @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,
@@ -354,48 +390,60 @@
 
           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
             ]
           );
 
@@ -408,9 +456,9 @@
 
           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;
         }
       })();
@@ -438,11 +486,18 @@
         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) {
@@ -547,7 +602,7 @@
 
     /**
      * 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) {
@@ -557,7 +612,7 @@
 
     /**
      * 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) {
@@ -567,7 +622,7 @@
 
     /**
      * 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) {
@@ -576,7 +631,253 @@
     }
 
     /**
-     * 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) {
@@ -595,6 +896,139 @@
       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
@@ -612,7 +1046,7 @@
       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;
@@ -623,7 +1057,7 @@
           view.set(imageData.data);
         }
         
-        // 使用统一的 SetVirtualBackground C 接口（与其他平台一致）
+        // Use unified SetVirtualBackground C interface (consistent with other platforms)
         const result = Module.ccall(
           'SetVirtualBackground',
           'number',
@@ -631,7 +1065,7 @@
           [
             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
@@ -640,7 +1074,7 @@
         
         checkResult(result, 'Failed to set virtual background');
       } finally {
-        // 释放内存
+        // Free memory
         if (imageBufferPtr) {
           Module._free(imageBufferPtr);
         }
@@ -680,10 +1114,11 @@
      * @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();
@@ -701,7 +1136,7 @@
         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,
@@ -709,7 +1144,8 @@
             imageData.height,
             imageData.width * 4,
             this.dstBufferPtr,
-            processMode
+            frameType,
+            mirrorMode
           ]
         );
 
@@ -728,6 +1164,65 @@
       }
     }
 
+    /**
+     * 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
@@ -1055,77 +1550,6 @@
     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;
-    }
-  }
-
   /**
    * Browser Entry Point
    * For <script> tag usage (UMD format)
@@ -1162,7 +1586,6 @@
     getWasmModule: getWasmModule,
     getWasmBuffer: getWasmBuffer,
     toImageData: toImageData,
-    verifyAppKeyOnline: verifyAppKeyOnline,
     ensureGPUPixelCanvas,
     cleanupGPUPixelCanvas
   };
@@ -1187,7 +1610,8 @@
   const ReshapeParam = ReshapeParam$1;
   const MakeupParam = MakeupParam$1;
   const BackgroundMode = BackgroundMode$1;
-  const ProcessMode = ProcessMode$1;
+  const FrameType = FrameType$1;
+  const MirrorMode = MirrorMode$1;
   const VirtualBackgroundOptions = VirtualBackgroundOptions$1;
 
   // Default export
@@ -1205,8 +1629,9 @@
   exports.BeautyType = BeautyType;
   exports.EngineConfig = EngineConfig;
   exports.FacebetterError = FacebetterError;
+  exports.FrameType = FrameType;
   exports.MakeupParam = MakeupParam;
-  exports.ProcessMode = ProcessMode;
+  exports.MirrorMode = MirrorMode;
   exports.ReshapeParam = ReshapeParam;
   exports.VirtualBackgroundOptions = VirtualBackgroundOptions;
   exports.createBeautyEffectEngine = createBeautyEffectEngine;