facebetter 1.0.14 → 1.1.0

package/README.md

@@ -0,0 +1,157 @@
+# Facebetter Web SDK
+
+<h2 align="center">
+  <a href="https://github.com/pixpark/facebetter-demo"><img src="./logo.svg" alt="Facebetter Logo" width="300"></a>
+</h2>
+
+Facebetter is a high-performance, cross-platform SDK for real-time face beauty and AR effects. The Web version leverages WebAssembly (WASM) and WebGL acceleration to provide professional-grade skin retouching, face reshaping, makeup, and virtual background capabilities directly in the browser.
+
+🔗 **Quick Links**
+- [Official Website](https://facebetter.net)
+- [Documentation](https://facebetter.net/docs.html)
+- [Live Demo](https://demo.facebetter.net/)
+
+---
+
+## 🌟 Key Features
+
+- **Extreme Performance**: Optimized with WASM and SIMD instructions for low-latency, real-time processing on all modern browsers.
+- **Advanced Skin Retouching**: Smoothing, whitening, rosy tint, and sharpening for a natural, high-end look.
+- **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.
+- **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.
+
+---
+
+## 📦 Installation
+
+### via npm (Recommended)
+
+Ideal for modern frontend environments like Vite, Webpack, React, or Vue.
+
+```bash
+npm install facebetter
+```
+
+### via CDN
+
+For direct browser usage.
+
+```html
+<!-- Import SDK via CDN -->
+<script src="https://cdn.jsdelivr.net/npm/facebetter/dist/facebetter.js"></script>
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize the Engine
+
+Facebetter supports both online activation via `appId` / `appKey` and offline activation via `licenseJson`.
+
+```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: '{...}'
+});
+
+// 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');
+} catch (error) {
+  console.error('Initialization failed:', error);
+}
+```
+
+### 2. Configure Beauty Parameters
+
+```javascript
+import { BeautyType, BasicParam, ReshapeParam } from 'facebetter';
+
+// Enable specific beauty modules
+engine.setBeautyTypeEnabled(BeautyType.Basic, true);   // Basic skin retouching
+engine.setBeautyTypeEnabled(BeautyType.Reshape, true); // Face reshaping
+
+// Set skin smoothing intensity (0.0 - 1.0)
+engine.setBasicParam(BasicParam.Smoothing, 0.8);
+// Set eye enlargement intensity (0.0 - 1.0)
+engine.setReshapeParam(ReshapeParam.EyeSize, 0.5);
+```
+
+### 3. Process Video Stream
+
+```javascript
+const videoElement = document.querySelector('video');
+const canvas = document.querySelector('canvas');
+const ctx = canvas.getContext('2d');
+
+function processFrame() {
+  if (engine.initialized) {
+    // Process the current frame and get the result as ImageData
+    const resultData = engine.processImage(videoElement);
+    
+    // Render to your canvas
+    if (resultData) {
+      ctx.putImageData(resultData, 0, 0);
+    }
+  }
+  requestAnimationFrame(processFrame);
+}
+
+processFrame();
+```
+
+---
+
+## 🛠️ API Overview
+
+### Core Methods
+
+| 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.). |
+| `setFilter(path, intensity)` | Apply a LUT filter with custom intensity. |
+| `setVirtualBackground(options)` | Configure background blur or image replacement. |
+| `processImage(source)` | Process an input source (Image, Video, Canvas, or ImageData). |
+| `destroy()` | Clean up resources and release WebAssembly memory. |
+
+---
+
+## ⚠️ 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.
+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.
+    - Match input resolution with the display canvas to avoid unnecessary scaling overhead.
+4. **Memory Management**: Always call `engine.destroy()` when the engine is no longer needed to prevent memory leaks in Single Page Applications (SPAs).
+
+---
+
+## 📄 Licensing & Support
+
+Facebetter offers a **Free Tier** and **Enterprise Licensing**:
+- **Free Tier**: 5,000 free minutes per month, including all Pro+ features (with watermark).
+- **Enterprise**: Watermark-free, usage-based or perpetual licensing with priority support.
+
+- For technical support, visit [Facebetter.net](https://facebetter.net).
+- For commercial licensing inquiries, contact [sales@pixpark.net](mailto:sales@pixpark.net).
+
+Copyright © 2025 Pixpark. All rights reserved.