Verdure Assistant

April 1, 2026 · View on GitHub

🤖 Multi-service intelligent assistant based on .NET 10.0 | Cross-platform AI voice interaction solution

Quick Start • Features • Platform Support • Architecture • Development • Documentation

Overview

Verdure Assistant is a multi-service intelligent assistant built on .NET 10.0. It provides a complete AI voice interaction solution with modern architecture, multiple deployment options, and support for Windows, Linux, macOS, and Android.

The project started around the XiaoZhi ecosystem and is evolving into a broader integration platform for multiple AI assistant services, with a strong focus on voice interaction, music playback, and cross-platform application development.

Working with VerdiBot

The Verdure.Assistant.Api project provides voice conversation and music playback APIs for VerdiBot. It can be deployed on Raspberry Pi and similar embedded devices, then accessed from hardware robots through HTTP APIs.

VerdiBot repository: https://github.com/maker-community/VerdiBot
VerdiBot docs: https://verdibot.verdure-hiro.cn/zh/

Experimental project note

This project is still under active experimental development. Many areas are already usable, but parts of the system are still being refined. The repository is intended both as a practical assistant project and as a learning resource for modern .NET cross-platform development.

Wake words

你好小电 (default)
你好小娜

Main usage modes

Console app: bind the device, start the console program, then say the wake word to begin talking.
WinUI app: open the desktop UI, connect first, then say the wake word to start the conversation.

Design Goals

Cross-platform compatibility for Windows, Linux, macOS, and Android
Modular architecture with clear layering and extension points
High-performance audio processing and network communication
Multiple user experiences: desktop, mobile, console, and Web API
Strong learning value with complete documentation and examples
Practical deployment options for real devices and services

Why This Project

Verdure Assistant is a real multi-project .NET solution rather than a minimal demo. It is useful if you want to study or extend:

WinUI 3 desktop development
.NET MAUI Android development
ASP.NET Core Web API design
MVVM and dependency injection patterns
WebSocket-based audio streaming
Audio processing with Opus and related tooling
Embedded and Raspberry Pi integration

Real-time speech recognition
Natural text-to-speech output
Opus-based audio encoding and decoding
Noise suppression and audio preprocessing
Wake word detection
Smart interruption during conversation

Communication

WebSocket support for real-time bidirectional audio and messages
MQTT integration for IoT scenarios
Secure transport with WSS
Automatic reconnect logic
RESTful HTTP API

User interfaces

WinUI 3 desktop app for Windows
.NET MAUI app for Android
Console app for cross-platform CLI usage
Web API for device and service integration

Music playback

Music search through integrated services
Streaming playback
Local cache management
Play, pause, stop, and seek controls
Real-time volume control

Developer-oriented design

Dependency injection across the solution
Shared ViewModels with MVVM
Detailed logging and diagnostics
Unit tests and sample projects
Extensive technical documentation

Project Structure

verdure-assistant/
├── src/
│   ├── Verdure.Assistant.Core/
│   ├── Verdure.Assistant.ViewModels/
│   ├── Verdure.Assistant.Console/
│   ├── Verdure.Assistant.WinUI/
│   ├── Verdure.Assistant.MAUI/
│   └── Verdure.Assistant.Api/
├── tests/
├── samples/
├── docs/
├── docs-website/
├── scripts/
├── assets/
└── Verdure.Assistant.slnx

Platform Support

WinUI 3 desktop app

Best for Windows desktop users and developers learning modern XAML-based application design.

Stack: WinUI 3, MVVM, dependency injection
Focus: modern Windows UI, XAML, audio integration, async patterns
Project doc: src/Verdure.Assistant.WinUI/README.md

.NET MAUI Android app

Best for mobile voice assistant scenarios and Android-focused cross-platform development.

Stack: .NET MAUI 10.0, Android foreground services, shared ViewModels
Focus: Android integration, permissions, background processing, mobile audio
Project doc: src/Verdure.Assistant.MAUI/README.md

Console app

Best for server-side deployment, debugging, and automation.

Stack: .NET 10 console app with cross-platform audio handling
Platforms: Windows, Linux, macOS
Project doc: src/Verdure.Assistant.Console/README.md

ASP.NET Core Web API

Best for robotics, Raspberry Pi deployment, and hardware integration.

Stack: ASP.NET Core Web API, REST, Swagger, music playback services
Platforms: Linux, Raspberry Pi, Windows, containerized deployments
Project doc: src/Verdure.Assistant.Api/README.md

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         UI Layer                            │
├──────────────┬──────────────┬──────────────┬────────────────┤
│  WinUI App   │  MAUI App    │ Console App  │   Web API      │
├──────────────┴──────────────┴──────────────┴────────────────┤
│                    ViewModel Layer (MVVM)                  │
├─────────────────────────────────────────────────────────────┤
│              Verdure.Assistant.ViewModels                  │
├─────────────────────────────────────────────────────────────┤
│                       Service Layer                        │
├────────────────┬────────────────┬──────────────┬────────────┤
│ Voice Chat     │ Music Playback │ Config       │ Validation │
├────────────────┼────────────────┼──────────────┼────────────┤
│ Audio Capture  │ Audio Output   │ Codec        │ State Mgmt │
├────────────────┴────────────────┴──────────────┴────────────┤
│                    Communication Layer                     │
├────────────────┬────────────────────────────────────────────┤
│ WebSocket      │ MQTT                                       │
├────────────────┴────────────────────────────────────────────┤
│             Core Layer (Verdure.Assistant.Core)            │
└─────────────────────────────────────────────────────────────┘

Key architectural ideas:

Clear separation of concerns across layers
Shared ViewModels to reduce duplicated UI logic
Interface-driven core abstractions
Dependency injection throughout the solution
Reusable core code across multiple platforms

Quick Start

Requirements

.NET 10.0 SDK or later
Visual Studio 2026 or Visual Studio Code

Additional platform-specific requirements:

Platform	Additional requirements
WinUI	Windows 10 1809+ or Windows 11, Windows App SDK
MAUI Android	Android SDK, emulator or physical device
API on Linux/Raspberry Pi	`mpg123` and optionally PortAudio

Installation

Clone the repository.

git clone https://github.com/maker-community/Verdure.Assistant.git
cd Verdure.Assistant

Restore dependencies.

dotnet restore

Build the solution.

dotnet build --configuration Release

Run an application

Console app:

dotnet run --project src/Verdure.Assistant.Console

WinUI app:

dotnet run --project src/Verdure.Assistant.WinUI

MAUI Android app:

dotnet build src/Verdure.Assistant.MAUI -t:Run -f net10.0-android

Web API:

dotnet run --project src/Verdure.Assistant.Api

Basic configuration

Example application configuration:

{
  "ServerUrl": "wss://your-server.com/ws",
  "EnableVoice": true,
  "AudioSampleRate": 16000,
  "AudioChannels": 1,
  "AudioFormat": "opus",
  "KeywordModel": "xiaodian"
}

API example:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      }
    }
  }
}

First run flow

Start the application you want to use.
Configure the server connection.
Test the connection.
Say the wake word to start voice interaction.

Quick environment test

Windows:

.\scripts\setup-dev.ps1

Linux or macOS:

./scripts/build.sh

Development

Run all tests:

dotnet test

Run a specific test project:

dotnet test tests/Verdure.Assistant.Core.Tests

Useful scripts:

scripts/setup-dev.ps1
scripts/build.ps1
scripts/test.ps1
scripts/build.bat
scripts/build.sh

Recommended workflow:

Set up the development environment.
Build in Debug.
Run tests.
Launch the specific app you are working on.

Documentation

English docs site: https://verdure-assistant.verdure-hiro.cn/en/
Chinese docs site: https://verdure-assistant.verdure-hiro.cn/zh/
Chinese root README: README.md
Contributing guide: CONTRIBUTING.md
Changelog: CHANGELOG.md

Platform-specific READMEs:

Additional technical notes are available in the docs/ directory.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the full process.

Typical contribution types:

Bug reports
Feature requests
Documentation improvements
Code contributions
UI and UX improvements

License

This project is released under the MIT License. See LICENSE.txt for details.

Acknowledgements

xiaozhi-esp32
py-xiaozhi
xiaozhi-sharp
All contributors and the open-source community