From 471c3fd6b4eeb17ca2e78e0d8e18e0af2ccc2d4f Mon Sep 17 00:00:00 2001
From: nightcityblade <nightcityblade@gmail.com>
Date: Tue, 16 Jun 2026 11:09:57 +0800
Subject: [PATCH] docs: add macOS OpenMP workaround

---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.md b/README.md
index 09416da..6fd59c5 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ input from microphone and pre-recorded audio files.
   - [Raw PCM Input](#raw-pcm-input)
 - [Browser Extensions](#browser-extensions)
 - [Whisper Live Server in Docker](#whisper-live-server-in-docker)
+- [Troubleshooting](#troubleshooting)
 - [Future Work](#future-work)
 - [Blog Posts](#blog-posts)
 - [Contact](#contact)
@@ -308,6 +309,21 @@ Refer to [`ios-client`](https://github.com/collabora/WhisperLive/tree/main/Audio
   docker run -it -p 9090:9090 ghcr.io/collabora/whisperlive-cpu:latest
   ```
 
+## Troubleshooting
+
+#### macOS OpenMP runtime conflict
+On macOS, especially on Intel Macs, `faster_whisper`/`ctranslate2` can conflict with OpenMP runtimes loaded by other Python packages. If the server aborts with a duplicate OpenMP runtime error, run the server with `KMP_DUPLICATE_LIB_OK=TRUE`:
+
+```bash
+KMP_DUPLICATE_LIB_OK=TRUE python3 run_server.py --port 9090 \
+                      --backend faster_whisper \
+                      --max_clients 4 \
+                      --max_connection_time 600 \
+                      --no_single_model
+```
+
+This workaround is intended for local development and testing. For production deployments, prefer using a clean environment that loads only one OpenMP runtime.
+
 ## Future Work
 - [x] Add translation to other languages on top of transcription.