facebetter 1.5.1 → 2.0.1

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,47 @@ 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`. Host these next to `facebetter.js`:
+
+- `facebetter-core.js`
+- `facebetter-core.wasm`
+- `resource.fbd`
+
+A single jsDelivr URL for `facebetter` is not enough. npm + a bundler is simpler.
+
 ---
 
 ## 🚀 Quick Start
 
 ### 1. Initialize the Engine
 
-Facebetter supports both online activation via `appId` / `appKey` and offline activation via `licenseJson`.
+Web 必须联网校验。`EngineConfig` **没有** `appId` / `appKey`：由你的服务器换 token，再传入 `licenseToken`。
 
 ```javascript
-import { BeautyEffectEngine, EngineConfig } from 'facebetter';
-
-// 1. Configure the engine
-const config = new EngineConfig({
-  appId: 'YOUR_APP_ID',
-  appKey: 'YOUR_APP_KEY',
-  // Or use offline license
-  // licenseJson: '{...}'
+import {
+  BeautyEffectEngine,
+  EngineConfig,
+} from 'facebetter';
+
+const licenseToken = await fetch('/api/facebetter/auth', {
+  method: 'POST',
+}).then((r) => {
+  if (!r.ok) throw new Error(`auth failed: ${r.status}`);
+  return r.text();
 });
 
-// 2. Create engine instance
-const engine = new BeautyEffectEngine(config);
+const engine = new BeautyEffectEngine(new EngineConfig({ licenseToken }));
 
-// 3. Initialize (Loads WASM resources and performs authentication)
 try {
   await engine.init();
   console.log('Facebetter Engine initialized successfully');
@@ -76,19 +85,59 @@ try {
 }
 ```
 
-### 2. Configure Beauty Parameters
+#### 服务端代理（Node）
+
+密钥只放在服务器环境变量。签名串为 `v2|{app_id}|{timestamp}|{nonce}|web`，HMAC-SHA256（hex）后请求上游，把**响应原文**返回给前端：
 
 ```javascript
-import { BeautyType, BasicParam, ReshapeParam } from 'facebetter';
+import { createHmac, randomBytes } from 'node:crypto';
+
+const AUTH_URL = 'https://facebetter.pixpark.net/facebetter/v2/auth';
+
+app.post('/api/facebetter/auth', async (req, res) => {
+  const appId = process.env.FB_APP_ID;
+  const appKey = process.env.FB_APP_KEY;
+  if (!appId || !appKey) {
+    res.status(500).json({ error: 'FB_APP_ID / FB_APP_KEY not configured' });
+    return;
+  }
 
-// Enable specific beauty modules
-engine.setBeautyTypeEnabled(BeautyType.Basic, true);   // Basic skin retouching
-engine.setBeautyTypeEnabled(BeautyType.Reshape, true); // Face reshaping
+  const nonce = randomBytes(16).toString('hex');
+  const timestamp = Math.floor(Date.now() / 1000);
+  const platform = 'web';
+  const payload = `v2|${appId}|${timestamp}|${nonce}|${platform}`;
+  const hmac = createHmac('sha256', appKey).update(payload).digest('hex');
+
+  const upstream = await fetch(AUTH_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      app_id: appId,
+      hmac_signature: hmac,
+      timestamp,
+      nonce,
+      platform,
+      user_agent: req.headers['user-agent'] || '',
+    }),
+  });
+  res.status(upstream.status).send(await upstream.text());
+});
+```
+
+可运行参考：[Demo `api/facebetter/auth.js`](https://github.com/pixpark/facebetter-sdk/blob/main/demo/web/react/api/facebetter/auth.js)。完整说明见 [Auth & License](https://facebetter.net/docs/intro/license)。
+
+iOS / Android 仍可用 `appId` + `appKey` 直连在线鉴权，或使用绑定 Bundle ID / Package Name 的离线 license。Web 不支持离线 license。
+
+
+### 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 +172,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 +208,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`). The SDK then downloads `facebetter-core.wasm` and `resource.fbd` from that package. For a `<script>` tag, place `facebetter-core.js`, `facebetter-core.wasm`, and `resource.fbd` beside `facebetter.js`. Pass `onProgress` to `init()` for download progress.
 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.