# voicevox/voicevox_core architecture

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

- Interactive diagram: https://gitdiagram.com/voicevox/voicevox_core
- Repository: https://github.com/voicevox/voicevox_core

## Overview

##### Project Type and Purpose
- This repository is the “VOICEVOX CORE” audio‐synthesis engine, written in Rust and published as a core library for speech synthesis.
- It provides a high‐performance Rust core (crates/voicevox_core), a C ABI wrapper (crates/voicevox_core_c_api), and multiple language bindings (Python, Java). Users can embed this core in downstream applications (C++, Python scripts, JVM apps, mobile runtimes).

##### File‐Structure Analysis
- Top‐level “crates/” directory:
- voicevox_core: the Rust engine implementing text analysis, feature extraction, inference (via ONNXRuntime), waveform generation.
- voicevox_core_c_api: exposes C functions (FFI layer) around voicevox_core for .dll/.so/.dylib distribution; uses cbindgen.
- voicevox_core_python_api: Rust-based PyO3 crate producing a wheel; wraps the C API or directly links to core.
- voicevox_core_java_api: JNI/Gradle project producing Android/iOS libraries and JVM JAR, wrapping the C API.
- voicevox_core_macros: proc macros used by core and bindings for code generation.
- test_util, downloader, xtask: helper crates for testing, model downloading, build scripting.
- Examples directory: C++ (Unix/Windows), Python, Kotlin. They consume the C API or the Python wheel.
- build_util: shell scripts for packaging iOS XCFramework and code‐signing.
- CI workflows (.github/workflows): build & test across languages, lint, release.
- model/: sample model files (VVM format) used by the engine.

##### README Insights
- The engine ships prebuilt C‐API libraries and Python wheels in GitHub Releases.
- The project emphasizes multi-language distribution and FFI compatibility.
- External dependencies: ONNX Runtime (for model inference), OpenJTalk (for Japanese text processing).

a. Main Components
- Rust Core (voicevox_core crate)
- Proc-Macro Helpers (voicevox_core_macros)
- C API Layer (voicevox_core_c_api)
- Python Binding (voicevox_core_python_api)
- Java Binding (voicevox_core_java_api)
- Model Downloader (crates/downloader)
- Test Utilities (crates/test_util)
- Build Scripts & Packaging (xtask, build_util)
- CI/CD Pipeline (GitHub Actions workflows)
- Example Clients (C++, Python, Kotlin projects)
b. Relationships & Data Flows
- voicevox_core depends on voicevox_core_macros and links to ONNX Runtime & OpenJTalk.
- voicevox_core_c_api links to the compiled core and exposes extern "C" functions.
- Python and Java bindings consume the C API (via FFI) or link directly to Rust via PyO3/JNI.
- Example clients call into the C API or import the Python module.
- downloader fetches model assets (.onnx, .json) into a local cache for both tests and runtime.
- xtask generates C headers, updates version info, and drives build‐time codegen.
- build_util scripts package the compiled libraries into platform‐specific frameworks.
- CI workflows build and test each crate, package artifacts, and deploy releases.
c. Architectural Patterns & Principles
- Layered FFI architecture: Core → C API → Language Bindings → Clients
- Code‐generation with proc macros and xtask for DRY FFI bindings
- Separation of concerns: model management (downloader), testing (test_util), build packaging (build_util/xtask)
- Cross-platform packaging using shell scripts and GitHub Actions
d. Key Technologies & Frameworks
- Rust and Cargo
- ONNX Runtime (inference runtime)
- OpenJTalk (text processing)
- PyO3 (Python binding)
- JNI/Gradle (Java binding)
- cbindgen (C header generation)
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Layer
    subgraph "Core Layer"
        direction TB
        VOICEVOX_MACROS["voicevox_core_macros"]:::core
        VOICEVOX_CORE["voicevox_core"]:::core
    end

    %% FFI Layer
    subgraph "FFI Layer"
        direction TB
        C_API["voicevox_core_c_api"]:::ffi
    end

    %% Language Bindings
    subgraph "Language Bindings"
        direction TB
        PYTHON_API["voicevox_core_python_api"]:::binding
        JAVA_API["voicevox_core_java_api"]:::binding
    end

    %% Helpers & Tooling
    subgraph "Helpers & Tooling"
        direction TB
        DOWNLOADER["Model Downloader"]:::helper
        TEST_UTIL["Test Utilities"]:::helper
        XTASK["xtask"]:::helper
        BUILD_UTIL["build_util"]:::helper
    end

    %% Clients & Examples
    subgraph "Clients & Examples"
        direction TB
        CPP_EX["C++ Examples"]:::client
        PY_EX["Python Example"]:::client
        KT_EX["Kotlin Example"]:::client
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ONNX["ONNX Runtime"]:::external
        OPENJTALK["OpenJTalk"]:::external
        MODEL_FILES["Model Files"]:::document
    end

    %% CI/CD
    CI["GitHub Actions CI/CD"]:::cloud

    %% Connections
    VOICEVOX_MACROS -->|"codegen"| VOICEVOX_CORE
    ONNX -->|runtime inference| VOICEVOX_CORE
    OPENJTALK -->|text processing| VOICEVOX_CORE
    MODEL_FILES -->|load assets| VOICEVOX_CORE

    VOICEVOX_CORE -->|"exposed via extern C"| C_API
    C_API -->|"wrapped by PyO3/JNI"| PYTHON_API
    C_API -->|"wrapped by JNI"| JAVA_API

    PYTHON_API -->|"import module"| PY_EX
    C_API -->|"call extern API"| CPP_EX
    JAVA_API -->|"use JAR/Android lib"| KT_EX

    DOWNLOADER -->|fetch models| VOICEVOX_CORE
    TEST_UTIL -->|test harness| VOICEVOX_CORE

    XTASK -->|generate headers/version| C_API
    XTASK -->|build scripts| BUILD_UTIL
    BUILD_UTIL -->|package libraries| PYTHON_API
    BUILD_UTIL -->|package libraries| JAVA_API

    CI -->|build & test| VOICEVOX_CORE
    CI -->|build & test| C_API
    CI -->|build & test| PYTHON_API
    CI -->|build & test| JAVA_API
    CI -->|run scripts| XTASK
    CI -->|run scripts| BUILD_UTIL
    CI -->|deploy artifacts| PYTHON_API
    CI -->|deploy artifacts| JAVA_API
    CI -->|deploy artifacts| C_API

    %% Click Events
    click VOICEVOX_MACROS "https://github.com/voicevox/voicevox_core/tree/main/crates/voicevox_core_macros"
    click VOICEVOX_CORE "https://github.com/voicevox/voicevox_core/tree/main/crates/voicevox_core"
    click C_API "https://github.com/voicevox/voicevox_core/tree/main/crates/voicevox_core_c_api"
    click PYTHON_API "https://github.com/voicevox/voicevox_core/tree/main/crates/voicevox_core_python_api"
    click JAVA_API "https://github.com/voicevox/voicevox_core/tree/main/crates/voicevox_core_java_api"
    click DOWNLOADER "https://github.com/voicevox/voicevox_core/tree/main/crates/downloader"
    click TEST_UTIL "https://github.com/voicevox/voicevox_core/tree/main/crates/test_util"
    click XTASK "https://github.com/voicevox/voicevox_core/tree/main/crates/xtask"
    click BUILD_UTIL "https://github.com/voicevox/voicevox_core/blob/main/build_util/make_ios_xcframework.bash"
    click CI "https://github.com/voicevox/voicevox_core/blob/main/.github/workflows/ci.yml"
    click CPP_EX "https://github.com/voicevox/voicevox_core/tree/main/example/cpp/unix/"
    click PY_EX "https://github.com/voicevox/voicevox_core/tree/main/example/python/"
    click KT_EX "https://github.com/voicevox/voicevox_core/tree/main/example/kotlin/"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#4a7ebb,color:#000;
    classDef ffi fill:#d9ead3,stroke:#6aa84f,color:#000;
    classDef binding fill:#f9cb9c,stroke:#e69138,color:#000;
    classDef helper fill:#ebebeb,stroke:#a6a6a6,color:#000;
    classDef client fill:#d0a4f5,stroke:#8e35ef,color:#000;
    classDef external fill:#f4cccc,stroke:#cc0000,color:#000;
    classDef cloud fill:#d9d2e9,stroke:#674ea7,color:#000;
    classDef document fill:#fff2cc,stroke:#bf9000,color:#000;
```
