Skip to main content

Frequently Asked Questions

Quick jump:

General Questions​

I love this project. How can I help?​

For regular users:

  • Let us know you like the project ❤️.
  • Introduce our project to friends, star us on GitHub
  • Make videos about this project and post them on social media - anything goes! (It would be even better if you share them with us, saves us the trouble of searching 😎)
  • Help others in the community (QQ, Discord) (this is really a big help for us!)
  • Let us know in QQ, Discord groups, or other channels that real people are actually using our project!

For users familiar with the project:

  • Help supplement the documentation, record problems you encounter
  • If you're not sure how to edit the documentation, you can message me directly

For programmers:

  • Check out the contribution guidelines, read the project issues, see if there are any issues you're interested in, and contribute.
  • We are very open to Pull Requests.

How to use the xxx LLM API service?​

Please fill in the relevant settings, such as API key, base url, etc., under the openai_compatible_llm settings. openai_compatible_llm accepts all LLM APIs that support the OpenAI API format.

How to choose the right LLM?​

  • If you want quick deployment without downloading models, we recommend using OpenAI Compatible API or Groq API
  • If you want to use local deployment, we recommend choosing a suitable model based on your available VRAM
  • For detailed instructions, please refer to the LLM Configuration Guide

What usage modes does the project support?​

  • Web mode: Access through a browser
  • Window mode: Default mode for desktop clients
  • Desktop pet mode: Provides a transparent background, globally top-most desktop companion experience
  • For detailed explanations, please refer to the Mode Introduction

How to use the Desktop Pet mode?​

  • Desktop pet mode: Provides a transparent background, globally top-most desktop companion experience
  • For detailed explanations, please refer to the Mode Introduction

Can this project be used on mobile phones?​

Currently, mobile support is relatively weak and there are many issues.

  • The project backend must run on a computer.
  • The Web frontend can be accessed on mobile, but https must be configured, otherwise the microphone cannot be activated. This is a browser limitation.
  • On iOS, you need to keep tapping to make the speech function work normally

Two talented developers are working on a Unity version of the frontend, which hopefully will solve these issues. We look forward to the day they complete it.

How to get the latest version of the frontend?​

  • Currently, the frontend does not support automatic updates. You can follow the Github Release page to get the latest version.
  • For detailed instructions, please refer to the Mode Introduction

What to do if Web displays {"detail": "Not Found"}?​

  • The frontend code hasn't been pulled to local. This error appears when you haven't obtained the complete project code. Please run git submodule update --init --recursive in the project directory to pull the project code.
  • For details, please refer to the two ways of obtaining project code mentioned in Quick Start/1. Get Project Code.
  • This is usually because Web using HTTP protocol cannot load HTTPS resources
  • You can solve this by allowing the website to load insecure content in browser settings:
    • Chrome: Click the shield icon on the right side of the address bar -> Site settings -> Insecure content -> Allow
    • Firefox: Click the lock icon on the left side of the address bar -> Turn off connection protection
    • Edge: Click the lock icon on the right side of the address bar -> Site permissions -> Insecure content -> Allow

What to do if the microphone is not working?​

  • Please ensure that you have granted microphone usage permission to the browser or application
  • Check if the microphone input volume is appropriate - sound that's too low or too short may not trigger voice detection. You can adjust the detection threshold in settings, for detailed settings please refer to Web Mode
  • If you're using the Electron desktop application, try restarting the application.
  • If all of the above methods are ineffective, you can visit https://www.vad.ricky0123.com/ to test microphone functionality. If this website also can't use the microphone normally, it might be a system audio setting or hardware issue

What to do if the desktop client can't be installed (Windows has protected your PC) or prompts "damaged"?​

  • Windows users can click "More info" and then choose "Run anyway"
  • macOS users need to adjust system settings and execute specific commands
  • For detailed solutions, please refer to Mode Introduction

What to do if microphone/camera/screen recording can't be used when accessing the Web interface remotely (Failed to start screen capture: NotSupportedError: Not supported)?​

  • This is because these features require a secure context (HTTPS or localhost)
  • If remote use is needed, HTTPS must be configured for the Web server
  • For detailed instructions, please refer to Mode Introduction

What to do if voice functionality is abnormal on iOS devices?​

  • This is a known issue caused by iOS security restrictions
  • You need to keep tapping to make the speech function work normally
  • For detailed instructions, please refer to Mode Introduction

What to do if switching modes in the Electron application causes the screen to go blank?​

  • This is a low-probability bug that's difficult to fix, and in practice it's rarely triggered.
  • Wait a few seconds, or restart the application to resolve it.

What to do if model expressions can't be displayed?​