# kojix2/vovx architecture

> Architecture diagram of the GitHub repository kojix2/vovx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kojix2/vovx
- Repository: https://github.com/kojix2/vovx

## Overview

VOVX is a Crystal desktop speech tool: it accepts text, splits it into sentences, synthesizes speech through VOICEVOX, and plays each sentence while preparing the next. Its GUI exposes voice, speed, playback, and stop controls; it can launch an unavailable engine and persists settings. The README also documents macOS Services integration and Linux clipboard fallback. Source excerpts were unavailable, so relationships below are limited to documented behavior; paths identify modules from the tree, not inspected implementations.

Main entry points: [`src/vovx/app.cr`](https://github.com/kojix2/vovx/blob/main/src/vovx/app.cr) (Application), [`src/vovx/voicevox_client.cr`](https://github.com/kojix2/vovx/blob/main/src/vovx/voicevox_client.cr) (VOICEVOX client), [`src/vovx/cli.cr`](https://github.com/kojix2/vovx/blob/main/src/vovx/cli.cr) (Text input), [`src/vovx/ui/settings_window.cr`](https://github.com/kojix2/vovx/blob/main/src/vovx/ui/settings_window.cr) (Settings window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and UI"]
  node_stdin["Text input<br/>[cli.cr]"]
  node_clipboard["Clipboard fallback<br/>[cli.cr]"]
  node_app["Application<br/>[app.cr]"]
  node_main_window["Main window<br/>[main_window.cr]"]
  node_settings_window["Settings window<br/>[settings_window.cr]"]
  node_app_state["UI state<br/>[app_state.cr]"]
  node_service["macOS Services"]
end

subgraph group_speech["Speech workflow"]
  node_text["Sentence splitting<br/>[text.cr]"]
  node_client["VOICEVOX client<br/>[voicevox_client.cr]"]
  node_voice_style["Voice selection"]
  node_playback["Audio playback"]
  node_audio_export["Audio export<br/>[audio_exporter.cr]"]
  node_wav["WAV handling<br/>[wav.cr]"]
end

subgraph group_runtime["Runtime integration"]
  node_engine["VOICEVOX Engine"]
  node_launcher["Engine launcher<br/>[launcher.cr]"]
  node_startup["Engine startup"]
end

subgraph group_prefs["Preferences"]
  node_settings[("Saved settings<br/>[settings.cr]")]
  node_paths["App paths<br/>[paths.cr]"]
end

node_user(("User"))

node_user -->|"provides text"| node_stdin
node_stdin -->|"supplies input"| node_app
node_user -.->|"provides fallback"| node_clipboard
node_clipboard -.->|"supplies text"| node_app
node_user -->|"invokes service"| node_service
node_service -->|"starts reading"| node_app
node_user -->|"controls playback"| node_main_window
node_user -->|"sets voice and speed"| node_settings_window
node_app -->|"splits sentences"| node_text
node_app -->|"requests synthesis"| node_client
node_client -->|"uses engine"| node_engine
node_app -->|"plays sentences"| node_playback
node_playback -->|"overlaps synthesis"| node_client
node_app -->|"tries engine launch"| node_launcher
node_launcher -->|"starts if unavailable"| node_engine
node_app -->|"restores and saves"| node_settings
node_app -.->|"presents controls"| node_main_window
node_settings_window -.->|"updates preferences"| node_settings

click node_stdin "https://github.com/kojix2/vovx/blob/main/src/vovx/cli.cr"
click node_clipboard "https://github.com/kojix2/vovx/blob/main/src/vovx/cli.cr"
click node_app "https://github.com/kojix2/vovx/blob/main/src/vovx/app.cr"
click node_main_window "https://github.com/kojix2/vovx/blob/main/src/vovx/ui/main_window.cr"
click node_settings_window "https://github.com/kojix2/vovx/blob/main/src/vovx/ui/settings_window.cr"
click node_app_state "https://github.com/kojix2/vovx/blob/main/src/vovx/ui/app_state.cr"
click node_service "https://github.com/kojix2/vovx/blob/main/src/vovx/service_workflow.cr"
click node_text "https://github.com/kojix2/vovx/blob/main/src/vovx/text.cr"
click node_client "https://github.com/kojix2/vovx/blob/main/src/vovx/voicevox_client.cr"
click node_voice_style "https://github.com/kojix2/vovx/blob/main/src/vovx/voice_style_option.cr"
click node_playback "https://github.com/kojix2/vovx/blob/main/src/vovx/playback_controller.cr"
click node_audio_export "https://github.com/kojix2/vovx/blob/main/src/vovx/audio_exporter.cr"
click node_wav "https://github.com/kojix2/vovx/blob/main/src/vovx/wav.cr"
click node_launcher "https://github.com/kojix2/vovx/blob/main/src/vovx/platform/launcher.cr"
click node_startup "https://github.com/kojix2/vovx/blob/main/src/vovx/ui/voicevox_startup.cr"
click node_settings "https://github.com/kojix2/vovx/blob/main/src/vovx/settings.cr"
click node_paths "https://github.com/kojix2/vovx/blob/main/src/vovx/paths.cr"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdin,node_clipboard,node_app,node_main_window,node_settings_window,node_app_state,node_service,node_user toneBlue
class node_text,node_client,node_voice_style,node_playback,node_audio_export,node_wav toneAmber
class node_engine,node_launcher,node_startup toneMint
class node_settings,node_paths toneRose
```

## Components

### Input and UI

- [Text input](https://github.com/kojix2/vovx/blob/main/src/vovx/cli.cr): `src/vovx/cli.cr`
- [Clipboard fallback](https://github.com/kojix2/vovx/blob/main/src/vovx/cli.cr): `src/vovx/cli.cr`
- [Application](https://github.com/kojix2/vovx/blob/main/src/vovx/app.cr): `src/vovx/app.cr`
- [Main window](https://github.com/kojix2/vovx/blob/main/src/vovx/ui/main_window.cr): `src/vovx/ui/main_window.cr`
- [Settings window](https://github.com/kojix2/vovx/blob/main/src/vovx/ui/settings_window.cr): `src/vovx/ui/settings_window.cr`
- [UI state](https://github.com/kojix2/vovx/blob/main/src/vovx/ui/app_state.cr): `src/vovx/ui/app_state.cr`
- [macOS Services](https://github.com/kojix2/vovx/blob/main/src/vovx/service_workflow.cr): `src/vovx/service_workflow.cr`

### Speech workflow

- [Sentence splitting](https://github.com/kojix2/vovx/blob/main/src/vovx/text.cr): `src/vovx/text.cr`
- [VOICEVOX client](https://github.com/kojix2/vovx/blob/main/src/vovx/voicevox_client.cr): `src/vovx/voicevox_client.cr`
- [Voice selection](https://github.com/kojix2/vovx/blob/main/src/vovx/voice_style_option.cr): `src/vovx/voice_style_option.cr`
- [Audio playback](https://github.com/kojix2/vovx/blob/main/src/vovx/playback_controller.cr): `src/vovx/playback_controller.cr`
- [Audio export](https://github.com/kojix2/vovx/blob/main/src/vovx/audio_exporter.cr): `src/vovx/audio_exporter.cr`
- [WAV handling](https://github.com/kojix2/vovx/blob/main/src/vovx/wav.cr): `src/vovx/wav.cr`

### Runtime integration

- **VOICEVOX Engine**
- [Engine launcher](https://github.com/kojix2/vovx/blob/main/src/vovx/platform/launcher.cr): `src/vovx/platform/launcher.cr`
- [Engine startup](https://github.com/kojix2/vovx/blob/main/src/vovx/ui/voicevox_startup.cr): `src/vovx/ui/voicevox_startup.cr`

### Preferences

- [Saved settings](https://github.com/kojix2/vovx/blob/main/src/vovx/settings.cr): `src/vovx/settings.cr`
- [App paths](https://github.com/kojix2/vovx/blob/main/src/vovx/paths.cr): `src/vovx/paths.cr`

### Other components

- **User**

## Connections

- User → Text input: provides text (evidence: `README.md`)
- Text input → Application: supplies input (evidence: `README.md`)
- User → Clipboard fallback: provides fallback (evidence: `README.md`)
- Clipboard fallback → Application: supplies text (evidence: `README.md`)
- User → macOS Services: invokes service (evidence: `README.md`)
- macOS Services → Application: starts reading (evidence: `README.md`)
- User → Main window: controls playback (evidence: `README.md`)
- User → Settings window: sets voice and speed (evidence: `README.md`)
- Application → Sentence splitting: splits sentences (evidence: `README.md`)
- Application → VOICEVOX client: requests synthesis (evidence: `README.md`)
- VOICEVOX client → VOICEVOX Engine: uses engine (evidence: `README.md`)
- Application → Audio playback: plays sentences (evidence: `README.md`)
- Audio playback → VOICEVOX client: overlaps synthesis (evidence: `README.md`)
- Application → Engine launcher: tries engine launch (evidence: `README.md`)
- Engine launcher → VOICEVOX Engine: starts if unavailable (evidence: `README.md`)
- Application → Saved settings: restores and saves (evidence: `README.md`)
- Application → Main window: presents controls
- Settings window → Saved settings: updates preferences
