diff --git a/backend/README.md b/backend/README.md index 31be561b56e..710956e26ee 100644 --- a/backend/README.md +++ b/backend/README.md @@ -26,12 +26,12 @@ 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 - - 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/)) @@ -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` @@ -65,6 +67,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 diff --git a/docs/doc/developer/backend/Backend_Setup.mdx b/docs/doc/developer/backend/Backend_Setup.mdx index 4637c08bb3d..400bc56c9ee 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 ``` @@ -242,17 +242,26 @@ 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. + + 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. @@ -265,7 +274,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 +437,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