facebetter 1.0.14 → 1.1.0

package/dist/facebetter.js

@@ -54,6 +54,12 @@
       this.appKey = config.appKey || null;
       this.licenseJson = config.licenseJson || null;
       this.resourcePath = '/facebetter/resource.bundle';
+      /**
+       * 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,75 @@
    * 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)
   };
 
   /**
    * 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
   };
 
   /**
@@ -178,8 +198,9 @@
     BackgroundMode: BackgroundMode$1,
     BasicParam: BasicParam$1,
     BeautyType: BeautyType$1,
+    ChromaKeyParam: ChromaKeyParam,
+    FrameType: FrameType$1,
     MakeupParam: MakeupParam$1,
-    ProcessMode: ProcessMode$1,
     ReshapeParam: ReshapeParam$1,
     VirtualBackgroundOptions: VirtualBackgroundOptions$1
   });
@@ -217,7 +238,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;
@@ -242,6 +263,10 @@
       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;
@@ -326,23 +351,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 +378,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/rest/v1/rpc/report_sdk_usage';
+                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/rest/v1/rpc/online_auth_v2';
+                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 +444,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 +474,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 +590,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 +600,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 +610,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) {
@@ -575,6 +618,28 @@
       this._setBeautyParam('SetBeautyParamMakeup', param, value);
     }
 
+    /**
+     * 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);
+    }
+
     /**
      * Internal method to set beauty parameters
      * @private
@@ -595,6 +660,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 +810,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 +821,7 @@
           view.set(imageData.data);
         }
         
-        // 使用统一的 SetVirtualBackground C 接口（与其他平台一致）
+        // Use unified SetVirtualBackground C interface (consistent with other platforms)
         const result = Module.ccall(
           'SetVirtualBackground',
           'number',
@@ -631,7 +829,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 +838,7 @@
         
         checkResult(result, 'Failed to set virtual background');
       } finally {
-        // 释放内存
+        // Free memory
         if (imageBufferPtr) {
           Module._free(imageBufferPtr);
         }
@@ -680,10 +878,10 @@
      * @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)
      * @returns {ImageData} Processed image data
      */
-    processImage(input, width, height, processMode = ProcessMode$1.Image) {
+    processImage(input, width, height, frameType = FrameType$1.Video) {
       this._ensureInitialized();
       const imageData = this._platformAPI.toImageData(input, width, height);
       const Module = this._getWasmModule();
@@ -709,7 +907,7 @@
             imageData.height,
             imageData.width * 4,
             this.dstBufferPtr,
-            processMode
+            frameType
           ]
         );
 
@@ -728,6 +926,62 @@
       }
     }
 
+    /**
+     * 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)
+     * @returns {number} Processed texture handle (GL_TEXTURE_2D, uint32)
+     */
+    processTexture(textureHandle,
+                   width,
+                   height,
+                   stride,
+                   frameType = FrameType$1.Video) {
+      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'],
+          [
+            this.enginePtr,
+            textureHandle,
+            width,
+            height,
+            stride,
+            frameType
+          ]
+        );
+
+        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
@@ -797,6 +1051,15 @@
       return this._offscreenCanvas;
     }
 
+    /**
+     * Internal method for online authentication (Deprecated: logic moved to WASM layer)
+     * @private
+     */
+    async _verifyAppKeyOnline(appId, appKey) {
+      // This method is now deprecated as logic is moved to WASM layer via Module.onOnlineAuth
+      return null;
+    }
+
   }
 
   /**
@@ -1109,7 +1372,7 @@
         p_user_agent: getUserAgentString()
       };
 
-      const response = await fetch('https://facebetter.pixpark.net/rest/v1/rpc/online_auth', {
+      const response = await fetch('https://facebetter.pixpark.net/rest/v1/rpc/online_auth_v2', {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -1187,7 +1450,7 @@
   const ReshapeParam = ReshapeParam$1;
   const MakeupParam = MakeupParam$1;
   const BackgroundMode = BackgroundMode$1;
-  const ProcessMode = ProcessMode$1;
+  const FrameType = FrameType$1;
   const VirtualBackgroundOptions = VirtualBackgroundOptions$1;
 
   // Default export
@@ -1205,8 +1468,8 @@
   exports.BeautyType = BeautyType;
   exports.EngineConfig = EngineConfig;
   exports.FacebetterError = FacebetterError;
+  exports.FrameType = FrameType;
   exports.MakeupParam = MakeupParam;
-  exports.ProcessMode = ProcessMode;
   exports.ReshapeParam = ReshapeParam;
   exports.VirtualBackgroundOptions = VirtualBackgroundOptions;
   exports.createBeautyEffectEngine = createBeautyEffectEngine;