openvoice_realtime_conversation.mp4
✉️ Get notified when the packaged version releases
|
| |||
|
🛡️ Wiki |
|||
| ✨ Key Features |
|---|
| 🗣️ Real-time conversations |
| - Three speech engines: espeak, SpeechT5, OpenVoice - Auto language detection (OpenVoice) - Real-time voice-chat with LLMs |
| 🤖 Customizable AI Agents |
| - Custom agent names, moods, personalities - Retrieval-Augmented Generation (RAG) - Create AI personalities and moods |
| 📚 Enhanced Knowledge Retrieval |
| - RAG for documents/websites - Use local data to enrich chat |
| 🖼️ Image Generation & Manipulation |
| - Text-to-Image (Stable Diffusion 1.5, SDXL, Turbo) - Drawing tools & ControlNet - LoRA & Embeddings - Inpainting, outpainting, filters |
| 🌍 Multi-lingual Capabilities |
| - Partial multi-lingual TTS/STT/interface - English & Japanese GUI |
| 🔒 Privacy and Security |
| - Runs locally, no external API (default) - Customizable LLM guardrails & image safety - Disables HuggingFace telemetry - Restricts network access |
| ⚡ Performance & Utility |
| - Fast generation (~2s on RTX 2080s) - Docker-based setup & GPU acceleration - Theming (Light/Dark/System) - NSFW toggles - Extension API - Python library & API support |
| Language | TTS | LLM | STT | GUI |
|---|---|---|---|---|
| English | ✅ | ✅ | ✅ | ✅ |
| Japanese | ✅ | ✅ | ❌ | ✅ |
| Spanish | ✅ | ✅ | ❌ | ❌ |
| French | ✅ | ✅ | ❌ | ❌ |
| Chinese | ✅ | ✅ | ❌ | ❌ |
| Korean | ✅ | ✅ | ❌ | ❌ |
| Specification | Minimum | Recommended |
|---|---|---|
| OS | Ubuntu 22.04, Windows 10 | Ubuntu 22.04 (Wayland) |
| CPU | Ryzen 2700K or Intel Core i7-8700K | Ryzen 5800X or Intel Core i7-11700K |
| Memory | 16 GB RAM | 32 GB RAM |
| GPU | NVIDIA RTX 3060 or better | NVIDIA RTX 4090 or better |
| Network | Broadband (used to download models) | Broadband (used to download models) |
| Storage | 22 GB (with models), 6 GB (without models) | 100 GB or higher |
- Install system requirements
sudo apt update && sudo apt upgrade -y sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git nvidia-cuda-toolkit pipewire libportaudio2 libxcb-cursor0 gnupg gpg-agent pinentry-curses espeak xclip cmake qt6-qpa-plugins qt6-wayland qt6-gtk-platformtheme mecab libmecab-dev mecab-ipadic-utf8 libxslt-dev sudo apt install espeak sudo apt install espeak-ng-espeak - Create
airunnerdirectorysudo mkdir ~/.local/share/airunner sudo chown $USER:$USER ~/.local/share/airunner
- Install AI Runner - Python 3.13+ required
pyenvandvenvare recommended (see wiki for more info)pip install "typing-extensions==4.13.2" pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 pip install airunner[all_dev] - Run AI Runner
airunner
For more options, including Docker, see the Installation Wiki.
- Run AI Runner:
airunner - Run the downloader:
airunner-setup - Build templates:
airunner-build-ui
|
These are the sizes of the optional models that power AI Runner.
AI Runner uses the following stack
|
By default, AI Runner installs essential TTS/STT and minimal LLM components, but AI art models must be supplied by the user. Organize them under your local AI Runner data directory:
|
- The chatbot's mood and conversation summary system is always enabled by default. The bot's mood and emoji are shown with each bot message.
- When the LLM is updating the bot's mood or summarizing the conversation, a loading spinner and status message are shown in the chat prompt widget. The indicator disappears as soon as a new message arrives.
- This system is automatic and requires no user configuration.
- For more details, see the LLM Chat Prompt Widget README.
- The mood and summary engines are now fully integrated into the agent runtime. When the agent updates mood or summarizes the conversation, it emits a signal to the UI with a customizable loading message. The chat prompt widget displays this message as a loading indicator.
- See
src/airunner/handlers/llm/agent/agents/base.pyfor integration details andsrc/airunner/api/chatbot_services.pyfor the API function.
AI Runner includes an Aggregated Search Tool for querying multiple online services from a unified interface. This tool is available as a NodeGraphQt node, an LLM agent tool, and as a Python API.
Supported Search Services:
- DuckDuckGo (no API key required)
- Wikipedia (no API key required)
- arXiv (no API key required)
- Google Custom Search (requires
GOOGLE_API_KEYandGOOGLE_CSE_ID) - Bing Web Search (requires
BING_SUBSCRIPTION_KEY) - NewsAPI (requires
NEWSAPI_KEY) - StackExchange (optional
STACKEXCHANGE_KEYfor higher quota) - GitHub Repositories (optional
GITHUB_TOKENfor higher rate limits) - OpenLibrary (no API key required)
API Key Setup:
- Set the required API keys as environment variables before running AI Runner. Only services with valid keys will be queried.
- Example:
export GOOGLE_API_KEY=your_google_api_key export GOOGLE_CSE_ID=your_google_cse_id export BING_SUBSCRIPTION_KEY=your_bing_key export NEWSAPI_KEY=your_newsapi_key export STACKEXCHANGE_KEY=your_stackexchange_key export GITHUB_TOKEN=your_github_token
Usage:
- Use the Aggregated Search node in NodeGraphQt for visual workflows.
- Call the tool from LLM agents or Python code:
from airunner.tools.search_tool import AggregatedSearchTool results = await AggregatedSearchTool.aggregated_search("python", category="web")
- See
src/airunner/tools/README.mdfor more details.
Note:
- DuckDuckGo, Wikipedia, arXiv, and OpenLibrary do not require API keys and can be used out-of-the-box.
- For best results and full service coverage, configure all relevant API keys.
We welcome pull requests for new features, bug fixes, or documentation improvements. You can also build and share extensions to expand AI Runner’s functionality. For details, see the Extensions Wiki.
Take a look at the Contributing document and the Development wiki page for detailed instructions.
AI Runner uses pytest for all automated testing. Test coverage is a priority, especially for utility modules.
- Headless-safe tests:
- Located in
src/airunner/utils/tests/ - Can be run in any environment (including CI, headless servers, and developer machines)
- Run with:
pytest src/airunner/utils/tests/
- Located in
- Display-required (Qt/Xvfb) tests:
- Located in
src/airunner/utils/tests/xvfb_required/ - Require a real Qt display environment (cannot be run headlessly or with
pytest-qt) - Typical for low-level Qt worker/signal/slot logic
- Run with:
xvfb-run -a pytest src/airunner/utils/tests/xvfb_required/ # Or for a single file: xvfb-run -a pytest src/airunner/utils/tests/xvfb_required/test_background_worker.py - See the README in xvfb_required/ for details.
- Located in
- By default, only headless-safe tests are run in CI.
- Display-required tests are intended for manual or special-case runs (e.g., when working on Qt threading or background worker code).
- (Optional) You may automate this split in CI by adding a separate job/step for xvfb tests.
- All new utility code must be accompanied by tests.
- Use
pytest,pytest-qt(for GUI), andunittest.mockfor mocking dependencies. - For more details on writing and organizing tests, see the project coding guidelines and the
src/airunner/utils/tests/folder.
- Follow the copilot-instructions.md for all development, testing, and contribution guidelines.
- Always use the
airunnercommand in the terminal to run the application. - Always run tests in the terminal (not in the workspace test runner).
- Use
pytestandpytest-covfor running tests and checking coverage. - UI changes must be made in
.uifiles and rebuilt withairunner-build-ui.
- See the Wiki for architecture, usage, and advanced topics.
- API Service Layer
- Main Window Model Load Balancer
- Facehugger Shield Suite
- NodeGraphQt Vendor Module
- Xvfb-Required Tests
- ORM Models
For additional details, see the Wiki.