# stakira/openutau architecture

> Architecture diagram of the GitHub repository stakira/openutau, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stakira/openutau
- Repository: https://github.com/stakira/openutau

## Overview

##### Project type and purpose
- OpenUtau is a full-stack, cross-platform desktop application for editing UTAU voice tracks.
- It uses a layered, component-based architecture: a rich Avalonia UI, a .NET Core “engine” library, a plugin system, and bundled native audio/ML libraries.

##### Top-level components
a. Presentation layer (UI)
- Technologies: Avalonia (XAML + C#), MVVM pattern
- Files: OpenUtau/*.axaml(.cs), ViewModels/, Views/, Controls/, Styles/, Strings/
- Responsibilities: render piano roll, dialogs, menus; capture user input; bind to ViewModels
b. Core engine library
- Project: OpenUtau.Core
- Sub-modules:
– Api: plugin interfaces (IG2p, IRenderer, IPlugin, PhonemizerRunner)
– Format: file I/O (USTx, VSQX, MusicXML, Wave)
– Analysis & Phonemizers: built-in dictionaries, Crepe ML model, DiffSinger, Enunu, Vogen, Voicevox adapters
– Classic: UTAU “classic” resampler runner, flag parser, voicebank loader
– Render: RenderEngine, RenderCache, Worldline integration
– SignalChain: mixing, faders, wave sources
– Audio: abstractions (IAudioOutput), backends (NAudio, MiniAudio)
– Util: file/INI/YAML parsers, path management, OS checks
- Responsibilities: load projects & voicebanks, run phonemizers, drive rendering, publish audio data to UI or files
c. Native modules (C++ worldline and dependencies)
- Directory: cpp/worldline + third_party
- Build system: Bazel, produces libworldline and friends
- Runtimes/: packaged native binaries (.dll/.so/.dylib) per OS/arch
- Responsibilities: low-level DSP (WORLDLINE resynthesis, fundamental frequency estimators, effects)
d. Plugin layer
- Project: OpenUtau.Plugin.Builtin (+ external plugins loaded via Core.Api)
- Built-in phonemizers for many languages and algorithms (VCV, CVVC, Arpasing, etc.)
- Responsibilities: extend or replace Core phonemizers; loaded at runtime by PluginLoader
e. Auxiliary scripts (Python)
- Directory: py/g2p
- Responsibilities: training G2P models; not part of the shipped runtime but important for contributors
f. Test suites
- Project: OpenUtau.Test
- Responsibilities: unit/integration tests for Core format parsers, plugins, worldline, UI tests

##### Relationships and data flows
- User → UI (Views & Controls) → ViewModels → Core.Api calls
- Core loads USTx/VSQX → Format module → Domain objects (UPart, UNote, etc.)
- Core invokes PluginRunner for phonemization → returns phoneme sequences
- Core.RenderEngine (Worldline wrapper) + SignalChain → raw audio buffers
- Audio module → platform-specific audio output → speakers
- UI polls PlaybackManager for progress and waveform previews
- PluginLoader uses reflection to discover IPlugin implementations in Plugin.Builtin and external .dlls
- Core library P/Invokes into native runtimes/libworldline
- File system stores voicebanks, settings, caches, render output

##### Architectural patterns & design principles
- MVVM for UI separation
- Layered architecture: Presentation → Application (ViewModels) → Domain/Engine → Infrastructure (native libs, file I/O)
- Plugin architecture following “inversion of control”: Core.Api interfaces, dynamic loading
- Single Responsibility: each Core subfolder focuses on one domain (Format, Phonemizers, Render, Audio)
- Cross-platform abstraction: IAudioOutput, LibraryLoader for native binaries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        direction TB
        UIApp["App.axaml / Program.cs"]:::ui
        Views["Views/"]:::ui
        ViewModels["ViewModels/"]:::ui
        Controls["Controls/"]:::ui
        Styles["Styles/"]:::ui
        Strings["Strings/"]:::ui
        Colors["Colors/"]:::ui
    end

    %% Core Engine Library
    subgraph "Core Engine Library (OpenUtau.Core)"
        direction TB
        Api["Api/"]:::core
        Format["Format/"]:::core
        Ustx["Ustx/"]:::core
        G2pCore["G2p/"]:::core
        Analysis["Analysis/"]:::core
        DiffSinger["DiffSinger/"]:::core
        Enunu["Enunu/"]:::core
        Vogen["Vogen/"]:::core
        Voicevox["Voicevox/"]:::core
        Classic["Classic/"]:::core
        Render["Render/"]:::core
        SignalChain["SignalChain/"]:::core
        AudioCore["Audio/"]:::core
        Util["Util/"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        subgraph "Native Modules (C++)"
            direction TB
            Worldline["cpp/worldline/"]:::native
            ThirdParty["cpp/third_party/"]:::native
            Bazel["BUILD & WORKSPACE"]:::native
        end
        Runtimes["runtimes/"]:::native
        PluginBuiltin["OpenUtau.Plugin.Builtin/"]:::plugin
        PluginData["OpenUtau.Plugin.Builtin/Data/"]:::plugin
        PythonScripts["py/g2p/"]:::external
        FileSystem["Voicebanks & Caches"]:::external
    end

    %% Test Suites
    subgraph "Test Suites"
        direction TB
        TestCore["OpenUtau.Test/Core/"]:::test
        TestClassic["OpenUtau.Test/Classic/"]:::test
        TestPlugins["OpenUtau.Test/Plugins/"]:::test
        TestApp["OpenUtau.Test/App/"]:::test
        TestFiles["OpenUtau.Test/Files/"]:::test
        TestProj["OpenUtau.Test/OpenUtau.Test.csproj"]:::test
    end

    %% UI to Core flows
    UIApp -->|"binds to"| ViewModels
    Views -->|renders| UIApp
    Controls -->|captures input| ViewModels
    ViewModels -->|calls| Api

    %% Core internal flows
    Api -->|loads| Format
    Format -->|produces| Ustx
    Ustx -->|domain objects| Render
    Api -->|invokes| G2pCore
    G2pCore -->|dictionary| Analysis
    Analysis -->|phonemes| Render
    Render -->|audio buffers| SignalChain
    SignalChain -->|mixed audio| AudioCore
    AudioCore -->|output| Runtimes
    Util -->|support| Api

    %% Plugins
    Api -->|PluginLoader| PluginBuiltin
    PluginBuiltin -->|data| PluginData

    %% Native modules
    Render -->|P/Invoke| Worldline
    Worldline -->|deps| ThirdParty
    Bazel -->|build| Worldline

    %% File system
    Format -->|loads/saves| FileSystem
    Render -->|writes| FileSystem

    %% Python scripts for contributors
    PythonScripts -.->|train models| G2pCore

    %% Test flows
    TestCore -->|tests| Api
    TestClassic -->|tests| Classic
    TestPlugins -->|tests| PluginBuiltin
    TestApp -->|tests| UIApp
    TestFiles -->|tests| Format

    %% Click Events
    click UIApp "https://github.com/stakira/openutau/blob/master/OpenUtau/App.axaml"
    click UIApp "https://github.com/stakira/openutau/blob/master/OpenUtau/Program.cs"
    click Views "https://github.com/stakira/openutau/tree/master/OpenUtau/Views/"
    click ViewModels "https://github.com/stakira/openutau/tree/master/OpenUtau/ViewModels/"
    click Controls "https://github.com/stakira/openutau/tree/master/OpenUtau/Controls/"
    click Styles "https://github.com/stakira/openutau/tree/master/OpenUtau/Styles/"
    click Strings "https://github.com/stakira/openutau/tree/master/OpenUtau/Strings/"
    click Colors "https://github.com/stakira/openutau/tree/master/OpenUtau/Colors/"
    click Api "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Api/"
    click Format "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Format/"
    click Ustx "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Ustx/"
    click G2pCore "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/G2p/"
    click Analysis "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Analysis/"
    click DiffSinger "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/DiffSinger/"
    click Enunu "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Enunu/"
    click Vogen "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Vogen/"
    click Voicevox "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Voicevox/"
    click Classic "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Classic/"
    click Render "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Render/"
    click SignalChain "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/SignalChain/"
    click AudioCore "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Audio/"
    click Util "https://github.com/stakira/openutau/tree/master/OpenUtau.Core/Util/"
    click Worldline "https://github.com/stakira/openutau/tree/master/cpp/worldline/"
    click ThirdParty "https://github.com/stakira/openutau/tree/master/cpp/third_party/"
    click Bazel "https://github.com/stakira/openutau/blob/master/cpp/BUILD.bazel"
    click Runtimes "https://github.com/stakira/openutau/tree/master/runtimes/"
    click PluginBuiltin "https://github.com/stakira/openutau/tree/master/OpenUtau.Plugin.Builtin/"
    click PluginData "https://github.com/stakira/openutau/tree/master/OpenUtau.Plugin.Builtin/Data/"
    click PythonScripts "https://github.com/stakira/openutau/tree/master/py/g2p/"
    click TestCore "https://github.com/stakira/openutau/tree/master/OpenUtau.Test/Core/"
    click TestClassic "https://github.com/stakira/openutau/tree/master/OpenUtau.Test/Classic/"
    click TestPlugins "https://github.com/stakira/openutau/tree/master/OpenUtau.Test/Plugins/"
    click TestApp "https://github.com/stakira/openutau/tree/master/OpenUtau.Test/App/"
    click TestFiles "https://github.com/stakira/openutau/tree/master/OpenUtau.Test/Files/"
    click TestProj "https://github.com/stakira/openutau/blob/master/OpenUtau.Test/OpenUtau.Test.csproj"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#000
    classDef core fill:#d4edda,stroke:#28a745,color:#000
    classDef native fill:#f8d7da,stroke:#dc3545,color:#000
    classDef plugin fill:#fff3cd,stroke:#fd7e14,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef test fill:#f0f0f0,stroke:#343a40,color:#000
```
