Document Rosetta2 incompatibility on macOS (#723)

* Initial plan

* Add Rosetta2 incompatibility documentation for macOS

Co-authored-by: umireon <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: umireon <[email protected]>

Author: Copilot

FAQ.md

@@ -101,13 +101,20 @@
 - CPU: AVX support required. Multi-core recommended. GPU support is planned for the future.
 - High CPU usage with multiple sources or high resolution. Use lighter models (e.g., SelfieSeg) if needed.
 
+### macOS Architecture Compatibility
+
+- **Apple Silicon (M1/M2/M3/etc.):** Use the Universal binary installer. Intel binaries running via Rosetta2 are **not supported** and will cause crashes.
+- **Intel Macs:** Use the Universal binary installer. Apple Silicon binaries running on Intel are **not supported**.
+- Always ensure your OBS Studio installation matches your Mac's architecture to avoid compatibility issues.
+
 ---
 
 ## 5. Troubleshooting
 
 - **"Failed to load" error:** Missing dependencies or wrong install path. Recheck installation steps.
 - **Black/transparent background:** Check filter settings and source order.
-- **OBS crashes:** Use latest OBS/plugin, remove conflicting plugins, report with OBS log on GitHub if needed.
+- **OBS crashes on macOS:** If running on Apple Silicon, ensure you are NOT using an Intel OBS binary via Rosetta2. If on Intel Mac, ensure you are NOT using an Apple Silicon OBS binary. The plugin does not support cross-architecture translation and will crash. Use OBS Studio and the plugin built for your Mac's native architecture.
+- **OBS crashes (other platforms):** Use latest OBS/plugin, remove conflicting plugins, report with OBS log on GitHub if needed.
 - **"Cannot find model file":** Missing model files. Reinstall the plugin.
 
 ---

README.md

@@ -60,7 +60,7 @@ If you are looking for hands-on help or private consultation please select a [sp
 GPU support:
 
 - On Windows, we plan to support WinML acceleration.
-- On Mac we support CoreML for acceleration, which is efficient on Appli Silicon.
+- On Mac we support CoreML for acceleration, which is efficient on Apple Silicon. **Note:** This plugin does not support cross-architecture translation (Rosetta2). Intel binaries on Apple Silicon or Apple Silicon binaries on Intel will crash.
 - On Linux CUDA and ROCM are supported if this plugin is built from source. Ensure your ONNX Runtime installation has CUDA or ROCM support.
 - The goal of this plugin is to be available for everyone on every system, even if they don't own a GPU.
 

pages/src/pages/macos.astro

@@ -21,6 +21,11 @@ if (!asset) throw new Error("macOS asset not found!");
   <main class="white-box">
     <h1>Install OBS Background Removal on macOS</h1>
 
+    <div style="background-color: #fff3cd; border: 1px solid #ffc107; border-radius: 4px; padding: 12px; margin-bottom: 20px;">
+      <strong>⚠️ Architecture Compatibility Warning:</strong><br />
+      This plugin does <strong>NOT</strong> support cross-architecture translation (Rosetta2). If you run an Intel OBS binary on Apple Silicon via Rosetta2, or an Apple Silicon binary on Intel Macs, the plugin will crash. Always use OBS Studio and this plugin built for your Mac's native architecture.
+    </div>
+
     <ol>
       <li>
         <strong>Download the Plugin Installer:</strong><br />