XiaomiTTS.Core 1.0.0

XiaomiTTS

A .NET 9 command-line tool for Xiaomi MiMo TTS (Text-to-Speech) synthesis. Converts text into WAV audio files by calling the MiMo platform REST API via HTTP/HTTPS.

中文文档 / Chinese Documentation

Features

• High-quality speech synthesis powered by the mimo-v2-tts model
• Supports both non-streaming and streaming (SSE) modes
• Real-time audio chunk reception in streaming mode, ideal for long text synthesis
• Generates standard WAV audio files (24 kHz / 16-bit / Mono)
• Native AOT compilation support for zero-dependency single-file executables (~5.6 MB)
• Real-time progress display, updated every second
• Structured logging system powered by Serilog with multi-sink output
• Comprehensive exception handling, error logging, and graceful error reporting
• Dependency Injection architecture following .NET Generic Host patterns
• Environment-based configuration with hot-reload support

Tech Stack

Backend Language & Runtime

Frameworks & Libraries

Logging & Observability

Third-Party APIs & Services

Testing & Quality

Build & Toolchain

Project Structure

XiaomiTTS/
├── XiaomiTTS.sln                          # Visual Studio solution file
├── README.md                              # English documentation
├── README-ZhCn.md                         # Chinese documentation
├── LICENSE                                # MIT License
│
├── XiaomiTTS.Core/                        # Core business logic class library
│   ├── XiaomiTTS.Core.csproj
│   ├── Abstractions/
│   │   ├── IFileSystem.cs                 # File system abstraction interface
│   │   └── FileSystem.cs                  # File system implementation
│   ├── Audio/
│   │   └── WavProcessor.cs                # WAV header validation & PCM-to-WAV conversion
│   ├── Configuration/
│   │   └── TtsOptions.cs                  # Strongly-typed TTS configuration model
│   ├── DependencyInjection/
│   │   └── ServiceCollectionExtensions.cs # DI service registration extensions
│   ├── Interfaces/
│   │   ├── ITtsClient.cs                  # TTS client interface (Dispose pattern)
│   │   ├── ISynthesisStrategy.cs          # Synthesis strategy interface (Strategy pattern)
│   │   └── IWavProcessor.cs              # WAV processor interface
│   ├── Models/
│   │   ├── ProgressInfo.cs                # Progress reporting data model
│   │   └── Tts/
│   │       ├── TtsRequest.cs              # TTS API request model
│   │       ├── TtsMessage.cs              # Chat message model
│   │       ├── TtsAudioOptions.cs         # Audio format configuration model
│   │       └── TtsJsonContext.cs           # AOT-compatible JSON source generator
│   └── Services/
│       ├── TtsClient.cs                   # TTS client facade (strategy delegation)
│       ├── NonStreamingSynthesisStrategy.cs  # Non-streaming synthesis implementation
│       └── StreamingSynthesisStrategy.cs     # Streaming (SSE) synthesis implementation
│
├── XiaomiTTS.Cli/                         # Command-line application
│   ├── XiaomiTTS.Cli.csproj
│   ├── Program.cs                         # Entry point (async Main, DI setup, orchestration)
│   ├── Cli/
│   │   ├── CommandLineParser.cs           # CLI argument parser with validation
│   │   └── ProgressDisplay.cs             # Real-time console progress display
│   ├── Logging/
│   │   ├── SerilogConfiguration.cs        # Serilog logger factory with multi-environment support
│   │   ├── TraceIdEnricher.cs             # Custom enricher for distributed trace ID
│   │   └── ConfigurationChangeWatcher.cs  # Hot-reload configuration change monitor
│   ├── Models/
│   │   └── CommandLineArgs.cs             # Parsed command-line arguments model
│   ├── appsettings.json                   # Default configuration (TTS + Serilog)
│   ├── appsettings.Development.json       # Development environment overrides
│   └── appsettings.Production.json        # Production environment configuration
│
├── XiaomiTTS.Tests/                       # Unit test project
│   ├── XiaomiTTS.Tests.csproj
│   ├── CommandLineParserTests.cs          # CLI argument parsing tests
│   ├── TtsClientTests.cs                  # TTS client initialization tests
│   ├── NonStreamingSynthesisStrategyTests.cs  # Non-streaming synthesis tests
│   ├── StreamingSynthesisStrategyTests.cs     # Streaming synthesis tests
│   ├── WavProcessorTests.cs              # WAV header validation & PCM conversion tests
│   ├── ModelsTests.cs                     # Data model tests
│   └── LoggingTests.cs                    # Logging configuration tests
│
├── sample_input.txt                       # Chinese sample input text
├── sample_input_en.txt                    # English sample input text
├── sample_long.txt                        # Long text sample
├── sample_song.txt                        # Lyrics sample
├── sample_style.txt                       # Style sample
├── run-tests.ps1                          # PowerShell test runner with coverage support
├── spec/
│   └── text2voice.md                      # Project requirement specification
├── skill/
│   └── xiaomi-local-tts/
│       └── SKILL.md                       # AI-assisted skill configuration
└── .trae/
    ├── rules/
    │   └── unittesting.md                 # Unit testing guidelines
    └── skills/
        └── xiaomi-tts/
            └── skill.md                   # AI skill definition

Environment Requirements

Required Dependencies

Optional Dependencies (Native AOT Publishing)

Getting Started

1. Clone the Repository

git clone https://github.com/your-username/XiaomiTTS.git
cd XiaomiTTS

2. Set Environment Variables

Windows (PowerShell):

$env:MIMO_API_KEY = "your-api-key-here"

Windows (CMD):

set MIMO_API_KEY=your-api-key-here

Linux / macOS:

export MIMO_API_KEY="your-api-key-here"

To make the variable persistent, add it to your shell profile (e.g., ~/.bashrc, ~/.zshrc) or use User Secrets for development.

3. Build the Project

dotnet build

4. Run the Program

# Basic usage (non-streaming mode)
dotnet run -- project:XiaomiTTS.Cli -- input.txt

# Specify output filename
dotnet run -- project:XiaomiTTS.Cli -- input.txt output.wav

# Streaming mode (recommended for long text)
dotnet run -- project:XiaomiTTS.Cli -- input.txt --stream

# Streaming mode with output filename
dotnet run -- project:XiaomiTTS.Cli -- input.txt output.wav --stream

# Use sample text
dotnet run -- project:XiaomiTTS.Cli -- sample_input.txt

5. Run Tests

# Run all tests
dotnet test XiaomiTTS.Tests/XiaomiTTS.Tests.csproj

# Run tests with code coverage
.\run-tests.ps1 -Coverage

# Run tests with coverage and open the report
.\run-tests.ps1 -Coverage -OpenReport

# Run tests with filter
.\run-tests.ps1 -Filter "FullyQualifiedName~CommandLineParser"

6. Native AOT Publish (Optional)

# Windows x64
dotnet publish XiaomiTTS.Cli/XiaomiTTS.Cli.csproj -c Release -r win-x64 --self-contained true

# Linux x64
dotnet publish XiaomiTTS.Cli/XiaomiTTS.Cli.csproj -c Release -r linux-x64 --self-contained true

# macOS x64
dotnet publish XiaomiTTS.Cli/XiaomiTTS.Cli.csproj -c Release -r osx-x64 --self-contained true

Published executables are located in XiaomiTTS.Cli/bin/Release/net9.0/<RID>/publish/ (~5.6 MB), with no .NET Runtime dependency required on the target machine.

CLI Arguments

Positional Arguments

Named Arguments

API Reference

Non-Streaming Mode

• Endpoint: https://api.xiaomimimo.com/v1/chat/completions
• Model: mimo-v2-tts
• Auth: Authorization: Bearer <API_KEY>
• Request Body:

{
  "model": "mimo-v2-tts",
  "messages": [
    {"role": "user", "content": "Convert the following text to speech"},
    {"role": "assistant", "content": "Text content to synthesize"}
  ],
  "voice": "mimo_default",
  "format": "wav"
}

• Response: JSON containing choices[0].message.audio.data (Base64-encoded audio)

Streaming Mode

• Endpoint: Same as above
• Request Body:

{
  "model": "mimo-v2-tts",
  "messages": [
    {"role": "user", "content": "Convert the following text to speech"},
    {"role": "assistant", "content": "Text content to synthesize"}
  ],
  "audio": {
    "format": "pcm16",
    "voice": "mimo_default"
  },
  "stream": true
}

• Response: SSE stream; each event contains choices[0].delta.audio.data (Base64-encoded PCM16 data)
• Audio Parameters: 24 kHz, 16-bit, Mono PCM

Exit Codes

Development Guidelines

• The project uses C# 12 syntax with nullable reference types and implicit usings enabled
• JSON serialization uses System.Text.Json source generators (TtsJsonContext) for AOT compatibility
• All asynchronous operations follow the async/await pattern with CancellationToken support for timeouts and cancellation
• Architecture follows the Strategy Pattern for synthesis modes and Dependency Injection via .NET Generic Host
• Configuration is managed through IOptions<T> pattern with environment-based overrides and hot-reload support
• File system operations are abstracted behind IFileSystem for testability
• All public types and methods include XML documentation comments
• Unit tests cover CLI parsing, client initialization, synthesis strategy logic, WAV processing, and logging configuration

Common Issues & Troubleshooting

Q: "未找到环境变量 MIMO_API_KEY" / "MIMO_API_KEY not found"

Ensure the environment variable is set before running the program. Verify with:

# Linux / macOS
echo $MIMO_API_KEY

# Windows PowerShell
echo $env:MIMO_API_KEY

Q: Build error "SDK 'Microsoft.NET.Sdk' not found"

Install .NET 9 SDK: https://dotnet.microsoft.com/download/dotnet/9.0

Q: Native AOT publish fails (Windows)

Ensure Visual Studio 2022 is installed with the "Desktop development with C++" workload selected. The C++ toolchain is required for native code compilation.

Q: Audio generated in streaming mode cannot be played

Streaming mode outputs PCM16 format, which the program automatically wraps into a standard WAV file. If the file cannot be played:

1. Check if the audio data from the API was received completely (look for timeout errors in logs)
2. Verify the output file size is larger than the WAV header size (44 bytes)
3. Try a shorter text input to rule out timeout issues

Q: Program exits with timeout (exit code 1)

The default timeout is 200 seconds. For very long texts, use streaming mode (--stream) to avoid timeouts. Streaming mode receives audio incrementally and is more resilient for large inputs.

Q: How to enable Seq log aggregation?

1. Start a Seq instance (default: http://localhost:5341)
2. Set "Seq": { "Enabled": true } in appsettings.json or via environment variables:

   $env:Seq__Enabled = "true"
   $env:Seq__ServerUrl = "http://localhost:5341"
   

Q: How to change log levels at runtime?

Modify appsettings.json while the application is running — the ConfigurationChangeWatcher detects changes and hot-reloads the Serilog minimum level without restarting the process.

References

• MiMo Platform API Documentation
• .NET 9 SDK Download
• Native AOT Deployment
• Serilog Documentation
• xunit Testing Framework

License

This project is licensed under the MIT License.