facebetter 1.5.1 → 2.0.0

package/README.md

@@ -20,7 +20,7 @@ Facebetter is a high-performance, cross-platform SDK for real-time face beauty a
 - **Precise Face Reshaping**: Comprehensive adjustments for face thinning, V-shape, eye enlargement, nose slimming, and chin/forehead contouring.
 - **Professional Makeup**: Real-time application of lipstick, blush, and more with parametric intensity control.
 - **AI Virtual Background**: High-precision portrait segmentation for background blur and custom image replacement.
-- **Premium Effects**: Includes 20+ real-time filters, animated stickers (in development), and professional-grade Chroma Key (Green Screen) removal.
+- **Premium Effects**: Includes 20+ real-time filters, 2D stickers, and professional-grade Chroma Key (Green Screen) removal.
 - **Developer Friendly**: Clean, well-documented JS API. Integrated in minutes with support for various input sources (Image, Video, Canvas, ImageData).
 - **Cross-Platform Consistency**: Shared core algorithms with Android, iOS, and Desktop SDKs ensure a unified experience across all devices.
 
@@ -36,38 +36,53 @@ Ideal for modern frontend environments like Vite, Webpack, React, or Vue.
 npm install facebetter
 ```
 
+This installs `facebetter-core` as well (declared as `facebetter-core` `^<same version>`). Do not add `facebetter-core` to your app unless you have a reason to import the runtime directly.
+
 ### via CDN
 
 For direct browser usage.
 
 ```html
-<!-- Import SDK via CDN -->
 <script src="https://cdn.jsdelivr.net/npm/facebetter/dist/facebetter.js"></script>
 ```
 
+The UMD build loads `facebetter-core` from the **same directory** as `facebetter.js`. A single jsDelivr URL for `facebetter` is not enough: also host `facebetter-core.js` next to it (from the `facebetter-core` package `dist/`), or use npm + a bundler.
+
 ---
 
 ## 🚀 Quick Start
 
 ### 1. Initialize the Engine
 
-Facebetter supports both online activation via `appId` / `appKey` and offline activation via `licenseJson`.
+Web 必须联网校验。`EngineConfig` **没有** `appId` / `appKey`：生产环境由你的服务器保管密钥并代理鉴权。本地调试、或你确认环境不会泄露密钥时，可以在调用处直连 Cloudflare。
 
 ```javascript
-import { BeautyEffectEngine, EngineConfig } from 'facebetter';
+import {
+  BeautyEffectEngine,
+  EngineConfig,
+  createDirectAuthFetcher,
+} from 'facebetter';
+
+// 方式 A：你的后端已经拿到 v2 token（compact JWS 或 {success, token}）
+const config = new EngineConfig({
+  licenseToken: await fetch('/api/facebetter/auth', { method: 'POST' }).then((r) => r.text()),
+});
+
+// 方式 B：把 WASM 的 nonce challenge 转发到你的后端（生产推荐）
+const config = new EngineConfig({
+  authProxyUrl: '/api/facebetter/auth',
+});
 
-// 1. Configure the engine
+// 方式 C：本地调试 / 无自己的服务器时，调用处直连 Cloudflare（密钥会出现在前端，不要用于生产）
 const config = new EngineConfig({
-  appId: 'YOUR_APP_ID',
-  appKey: 'YOUR_APP_KEY',
-  // Or use offline license
-  // licenseJson: '{...}'
+  fetchAuthResponse: createDirectAuthFetcher({
+    appId: 'your-app-id',
+    appKey: 'your-app-key',
+  }),
 });
 
-// 2. Create engine instance
 const engine = new BeautyEffectEngine(config);
 
-// 3. Initialize (Loads WASM resources and performs authentication)
 try {
   await engine.init();
   console.log('Facebetter Engine initialized successfully');
@@ -76,19 +91,46 @@ try {
 }
 ```
 
-### 2. Configure Beauty Parameters
+客户服务器代理示例（Node）：
 
 ```javascript
-import { BeautyType, BasicParam, ReshapeParam } from 'facebetter';
+import { createHmac } from 'node:crypto';
+
+app.post('/api/facebetter/auth', async (req, res) => {
+  const { nonce, timestamp, platform, user_agent } = req.body;
+  const appId = process.env.FB_APP_ID;
+  const appKey = process.env.FB_APP_KEY;
+  const payload = `v2|${appId}|${timestamp}|${nonce}|${platform}`;
+  const hmac = createHmac('sha256', appKey).update(payload).digest('hex');
+
+  const upstream = await fetch('https://facebetter.pixpark.net/facebetter/v2/auth', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      app_id: appId,
+      hmac_signature: hmac,
+      timestamp,
+      nonce,
+      platform,
+      user_agent,
+    }),
+  });
+  res.status(upstream.status).send(await upstream.text());
+});
+```
+
+iOS / Android 仍可用 `appId` + `appKey` 直连在线鉴权，或使用绑定 Bundle ID / Package Name 的离线 license。Web 不支持离线 license。
 
-// Enable specific beauty modules
-engine.setBeautyTypeEnabled(BeautyType.Basic, true);   // Basic skin retouching
-engine.setBeautyTypeEnabled(BeautyType.Reshape, true); // Face reshaping
+
+### 2. Configure Beauty Parameters
+
+```javascript
+import { Reshape } from 'facebetter';
 
 // Set skin smoothing intensity (0.0 - 1.0)
-engine.setBasicParam(BasicParam.Smoothing, 0.8);
+engine.setSmoothing(0.8);
 // Set eye enlargement intensity (0.0 - 1.0)
-engine.setReshapeParam(ReshapeParam.EyeSize, 0.5);
+engine.setReshape(Reshape.EyeSize, 0.5);
 ```
 
 ### 3. Process Video Stream
@@ -123,14 +165,35 @@ processFrame();
 | Method | Description |
 | :--- | :--- |
 | `init()` | Asynchronously initializes the engine and loads assets. |
-| `setBeautyTypeEnabled(type, enabled)` | Toggle specific modules (Basic, Reshape, Makeup, Background). |
-| `setBasicParam(param, value)` | Adjust skin retouching settings (Smoothing, Whitening, etc.). |
-| `setReshapeParam(param, value)` | Adjust face reshaping settings (Thinning, Eye Size, etc.). |
-| `setMakeupParam(param, value)` | Adjust makeup intensity (Lipstick, Blush, etc.). |
-| `setLipstickStyle(style)` | Switch lipstick style (Rouge / Coral / Pink). |
-| `setBlushStyle(style)` | Switch blush style (Classic / Peach / Rose). |
-| `setFilter(path, intensity)` | Apply a LUT filter with custom intensity. |
-| `setVirtualBackground(options)` | Configure background blur or image replacement. |
+| `setSmoothing(value)` | Set skin smoothing intensity. |
+| `setSmoothingStyle(style)` | Switch smoothing style. |
+| `setWhitening(value)` | Set skin whitening intensity. |
+| `setWhiteningStyle(style)` | Switch whitening style. |
+| `setSharpening(value)` | Set image sharpening intensity. |
+| `setRosiness(value)` | Set skin rosiness intensity. |
+| `setReshape(param, value)` | Adjust face reshaping settings (Thinning, Eye Size, etc.). |
+| `setLipstick(value)` | Set lipstick intensity. |
+| `setLipstickColor(style)` | Switch lipstick colour preset. |
+| `setBlush(value)` | Set blush intensity. |
+| `setBlushStyle(style)` / `setBlushColor(color)` | Switch blush style / colour. |
+| `setContour(value)` | Set contour intensity. |
+| `setContourStyle(style)` | Switch contour / highlight map. |
+| `setEyeShadow(value)` | Set eyeshadow intensity. |
+| `setEyeShadowStyle` / `setEyeShadowColor` | Eyeshadow style / colour. |
+| `setEyeLiner(value)` | Set eyeliner intensity. |
+| `setEyeLinerStyle` / `setEyeLinerColor` | Eyeliner style / colour. |
+| `setEyebrow(value)` | Set eyebrow intensity. |
+| `setEyebrowStyle` / `setEyebrowColor` | Eyebrow style / colour. |
+| `setEyelash(value)` | Set eyelash intensity. |
+| `setEyelashStyle` / `setEyelashColor` | Eyelash style / colour. |
+| `setPupil(value)` | Set pupil intensity. |
+| `setPupilColor(style)` | Switch contact-lens colourway. |
+| `setFilter(path or Uint8Array)` | Apply a LUT filter from an .fbd path or in-memory bytes. |
+| `clearFilter()` | Remove the current LUT filter. |
+| `setFilterIntensity(intensity)` | Set the current filter intensity [0.0, 1.0]. |
+| `setVirtualBackgroundBlur(level)` | Enable background blur. Level [0, 1] is continuous; 0 clears it. |
+| `setVirtualBackground(path or Uint8Array)` | Replace the background with a png/jpg path or encoded bytes. |
+| `clearVirtualBackground()` | Turn off virtual background. |
 | `processImage(source)` | Process an input source (Image, Video, Canvas, or ImageData). |
 | `destroy()` | Clean up resources and release WebAssembly memory. |
 
@@ -138,7 +201,7 @@ processFrame();
 
 ## ⚠️ Important Notes
 
-1. **WASM Asset Path**: By default, the SDK expects WASM and asset bundles in the `/facebetter/` directory. Ensure your static asset server is configured correctly.
+1. **Runtime package**: `import('facebetter-core')` is resolved by your bundler from `node_modules` (installed with `facebetter`). For a `<script>` tag, place `facebetter-core.js` beside `facebetter.js`.
 2. **Secure Context**: The SDK requires a Secure Context (HTTPS or localhost) to access modern browser features.
 3. **Performance Optimization**:
     - Always call `processImage` within a `requestAnimationFrame` loop.