From a517feb99cf46f4e1db2e5c0e3b6311c8909bd38 Mon Sep 17 00:00:00 2001 From: 491034170 <142008960+491034170@users.noreply.github.com> Date: Sun, 14 Jun 2026 12:32:13 +0800 Subject: [PATCH 1/5] Document backend Python 3.11 requirement in README --- backend/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/backend/README.md b/backend/README.md index 31be561b56e..0b3e17ad215 100644 --- a/backend/README.md +++ b/backend/README.md @@ -28,10 +28,10 @@ This README provides a quick setup guide for the Omi backend. For a comprehensiv Replace `` with your Google Cloud Project ID. This should generate the `application_default_credentials.json` file in the `~/.config/gcloud` directory. This file is read automatically by gcloud in Python. -4. Install Python - - Mac: `brew install python` - - Windows: `choco install python` - - Nix envdir: It should be pre-installed +4. Install Python 3.11 + - Mac: `brew install python@3.11` + - Windows: Install Python 3.11 from [python.org](https://www.python.org/downloads/windows/), then verify `python --version` prints `3.11.x` + - Nix envdir: It should be pre-installed; verify `python --version` prints `3.11.x` 5. Install `pip` if it doesn't exist (follow instructions on [pip installation page](https://pip.pypa.io/en/stable/installation/)) @@ -65,6 +65,9 @@ This README provides a quick setup guide for the Omi backend. For a comprehensiv **Option A: Using a virtual environment (recommended)** ```bash + # Verify Python 3.11 before creating the virtual environment + python --version + # Create a virtual environment python -m venv venv From e144242c91c99f677c71d74b1fac351a263a8306 Mon Sep 17 00:00:00 2001 From: 491034170 <142008960+491034170@users.noreply.github.com> Date: Sun, 14 Jun 2026 12:32:13 +0800 Subject: [PATCH 2/5] Align backend setup guide with Python 3.11 --- docs/doc/developer/backend/Backend_Setup.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/doc/developer/backend/Backend_Setup.mdx b/docs/doc/developer/backend/Backend_Setup.mdx index 4637c08bb3d..a2c689bbeef 100644 --- a/docs/doc/developer/backend/Backend_Setup.mdx +++ b/docs/doc/developer/backend/Backend_Setup.mdx @@ -242,15 +242,20 @@ OAuth is required for user authentication. You need to configure both Google and ``` + The backend Docker images run Python 3.11, so use Python 3.11 locally as well. If your package manager installs a newer default Python, install or select Python 3.11 before creating the virtual environment. + ```bash - brew install python git ffmpeg opus + brew install python@3.11 git ffmpeg opus ``` + Install Python 3.11 from [python.org](https://www.python.org/downloads/windows/), then install the remaining system tools: + ```powershell - choco install python git.install ffmpeg + choco install git.install ffmpeg + python --version # should print 3.11.x ``` Opus is included in Windows 10 version 1903 and above. @@ -265,7 +270,8 @@ OAuth is required for user authentication. You need to configure both Google and ```bash - # Create virtual environment (use Python 3.9-3.12) + # Create virtual environment with Python 3.11 + python --version python -m venv venv ``` @@ -427,7 +433,7 @@ OAuth is required for user authentication. You need to configure both Google and - On Windows, you may need to enable script execution: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` - - Make sure you're using Python 3.9-3.12 + - Make sure you're using Python 3.11 From 5e135f2119b775c6bb43707f9da62ea2324c461d Mon Sep 17 00:00:00 2001 From: 491034170 <142008960+491034170@users.noreply.github.com> Date: Sun, 14 Jun 2026 12:34:24 +0800 Subject: [PATCH 3/5] Document Windows gcloud ADC path --- backend/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/README.md b/backend/README.md index 0b3e17ad215..8aa160edb4a 100644 --- a/backend/README.md +++ b/backend/README.md @@ -26,7 +26,7 @@ This README provides a quick setup guide for the Omi backend. For a comprehensiv gcloud auth application-default login --project ``` Replace `` with your Google Cloud Project ID. - This should generate the `application_default_credentials.json` file in the `~/.config/gcloud` directory. This file is read automatically by gcloud in Python. + This should generate the `application_default_credentials.json` file in the gcloud config directory (`~/.config/gcloud` on macOS/Linux or `%APPDATA%\gcloud` on Windows). This file is read automatically by gcloud in Python. 4. Install Python 3.11 - Mac: `brew install python@3.11` From a804bc3b4890531484f7ff357b95fe2169255dda Mon Sep 17 00:00:00 2001 From: 491034170 <142008960+491034170@users.noreply.github.com> Date: Sun, 14 Jun 2026 12:34:24 +0800 Subject: [PATCH 4/5] Use PowerShell syntax for Windows credentials copy --- docs/doc/developer/backend/Backend_Setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doc/developer/backend/Backend_Setup.mdx b/docs/doc/developer/backend/Backend_Setup.mdx index a2c689bbeef..140c7a1ac40 100644 --- a/docs/doc/developer/backend/Backend_Setup.mdx +++ b/docs/doc/developer/backend/Backend_Setup.mdx @@ -143,7 +143,7 @@ New to backend development? Install [Homebrew](https://docs.brew.sh/Installation ```powershell - copy %APPDATA%\gcloud\application_default_credentials.json google-credentials.json + Copy-Item "$env:APPDATA\gcloud\application_default_credentials.json" .\google-credentials.json ``` From 452ec2b781aa4c91cfeb2ba44dd34ac82f0de2a8 Mon Sep 17 00:00:00 2001 From: 491034170 <142008960+491034170@users.noreply.github.com> Date: Wed, 17 Jun 2026 08:17:47 +0800 Subject: [PATCH 5/5] docs(backend): align Windows Opus setup note --- backend/README.md | 4 +++- docs/doc/developer/backend/Backend_Setup.mdx | 6 +++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/backend/README.md b/backend/README.md index 8aa160edb4a..710956e26ee 100644 --- a/backend/README.md +++ b/backend/README.md @@ -42,7 +42,9 @@ This README provides a quick setup guide for the Omi backend. For a comprehensiv 7. Install `opus` (required for audio processing) - Mac: `brew install opus` - - Windows: You should already have it if you're on Windows 10 version 1903 and above + - Windows: install a native `libopus` build and make sure its DLL directory is on `PATH` + - MSYS2 UCRT64 example: `pacman -S mingw-w64-ucrt-x86_64-opus` + - Add `C:\msys64\ucrt64\bin` to `PATH`, then verify from a new shell with `where.exe opus.dll` 8. Move to the backend directory: `cd backend` diff --git a/docs/doc/developer/backend/Backend_Setup.mdx b/docs/doc/developer/backend/Backend_Setup.mdx index 140c7a1ac40..400bc56c9ee 100644 --- a/docs/doc/developer/backend/Backend_Setup.mdx +++ b/docs/doc/developer/backend/Backend_Setup.mdx @@ -257,7 +257,11 @@ OAuth is required for user authentication. You need to configure both Google and choco install git.install ffmpeg python --version # should print 3.11.x ``` - Opus is included in Windows 10 version 1903 and above. + + The Python `opuslib` package still needs a native `libopus` DLL on `PATH`. One common setup is MSYS2 UCRT64: + install MSYS2, run `pacman -S mingw-w64-ucrt-x86_64-opus`, add `C:\msys64\ucrt64\bin` to `PATH`, + then open a new shell and verify with `where.exe opus.dll`. + Python, Git, and FFmpeg are typically pre-installed. Install opus via your package manager if needed.