# funorange/osu-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/funorange/osu-trainer
- Repository: https://github.com/funorange/osu-trainer

## Overview

##### Project type and purpose
- This is a Windows desktop application (C# WinForms) called “osu-trainer” whose goal is to let users modify the difficulty of osu! beatmaps quickly.
- It features a graphical UI, internal logic for difficulty calculation and song speed adjustment, plus integration with external tools (oppai-ng, soundstretch) and submodules (beatmap parser, global keyboard hook).

##### File structure
- Top-level:
– osu-trainer.sln (Visual Studio solution)
– osu-trainer/ (main project folder)
– binaries/ (third-party executables)
– submodules/ (FsBeatmapParser, globalKeyboardHook)
– images/, resources/
- In osu-trainer/:
– Controls/ (custom WinForms controls)
– Forms/ (UI screens: MainForm, HotkeyForm, UpdaterForm, etc.)
– Core classes: DifficultyCalculator.cs, BeatmapEditor.cs, SongSpeedChanger.cs, UserProfile.cs, Settings.cs, JunUtils.cs
– Properties/ (resources, settings, datasources)
– packages.config, App.config, version.txt
- Patterns:
– Presentation layer (Forms + Controls)
– Business logic layer (map/difficulty editing, speed changing)
– External integration layer (invoking oppai-ng, soundstretch, hooking keyboard)
– Data layer (user profiles, app settings, output files on disk)

##### README for additional insights
- Confirms: quick beatmap difficulty modification, profile & hotkey support, disk-cleanup functionality
- Lists used third-party libraries and licenses, hinting at external-tool integration and resource usage

##### Main components
a. Presentation Layer (WinForms UI)
– MainForm, HotkeyForm, DeleteMp3sForm, UpdaterForm, etc.
– Custom Controls (OsuButton, RatioBar, SongDisplay)
b. Application Core / Business Logic
– BeatmapEditor (parses .osu files via FsBeatmapParser)
– DifficultyCalculator (calculates star rating changes via oppai-ng)
– SongSpeedChanger (calls soundstretch to change mp3 speed)
– UserProfile & Settings (manages user preferences, hotkeys, output folders)
– JunUtils (utility routines)
c. External & Third-Party Integrations
– FsBeatmapParser submodule (reads/writes beatmap files)
– globalKeyboardHook submodule (captures global hotkeys, interacts with target process)
– oppai.exe (star rating calculation)
– soundstretch.exe (audio speed processing)
d. Data & File System
– Output folder for generated beatmaps (mp3 + .osu)
– Disk cleanup module (DeleteMp3sForm)
– Versioning and update checker (UpdaterForm + updater.exe)

##### Relationships and interactions
- UI → invokes Application Core methods
- Core → calls FsBeatmapParser to load/save beatmaps
- Core → launches oppai.exe and reads its output
- Core → launches soundstretch.exe and waits for completion
- KeyboardHook → raises events consumed by Core/Forms for quick triggering
- Core → reads/writes UserProfile & Settings from local app data
- Disk Cleanup UI → deletes files from output directories
- Updater UI → checks version.txt + invokes updater.exe

##### Architectural patterns & design principles
- Layered architecture: Presentation / Business / Integration / Data
- Modular components: submodules encapsulate parsing and hooking logic
- Process-based isolation: external tools run as separate processes
- Event-driven input: global hotkeys fire events into the UI/core

##### Detail without overcompensation
- Custom controls, forms, core classes, submodules, and external tools.
- How hotkey events traverse from the OS hook submodule up into the UI/core.
- Invocation of oppai.exe and soundstretch.exe as separate processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        MainForm["MainForm"]:::ui
        HotkeyForm["HotkeyForm"]:::ui
        DeleteMp3sForm["DeleteMp3sForm"]:::ui
        UpdaterForm["UpdaterForm"]:::ui
        RenameProfileForm["RenameProfileForm"]:::ui
        SongsFolderForm["SongsFolderForm"]:::ui
        OsuButton["OsuButton"]:::ui
        RatioBar["RatioBar"]:::ui
        SongDisplay["SongDisplay"]:::ui
        StarsDisplay["StarsDisplay"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        BeatmapEditor["BeatmapEditor"]:::core
        DifficultyCalculator["DifficultyCalculator"]:::core
        SongSpeedChanger["SongSpeedChanger"]:::core
        UserProfile["UserProfile"]:::core
        Settings["Settings"]:::core
        JunUtils["JunUtils"]:::core
    end

    %% External Services & Libraries
    subgraph "External Services & Libraries"
        direction TB
        FsBeatmapParser["FsBeatmapParser"]:::module
        globalKeyboardHook["globalKeyboardHook"]:::module
        oppai["oppai.exe"]:::exec
        soundstretch["soundstretch.exe"]:::exec
        updaterExe["updater.exe"]:::exec
    end

    %% Data & File System
    subgraph "Data & File System"
        direction TB
        ProfileStore["UserProfile Store"]:::storage
        SettingsFile["Settings File"]:::storage
        OutputFolder["Output Folder"]:::storage
        BeatmapFiles["Beatmap Files"]:::storage
        VersionFile["version.txt"]:::storage
        AppConfig["App.config"]:::storage
    end

    %% Connections
    MainForm -->|"invokes"| BeatmapEditor
    MainForm -->|"invokes"| SongSpeedChanger
    MainForm -->|"reads/writes"| UserProfile
    MainForm -->|"reads/writes"| Settings
    MainForm -->|"uses"| JunUtils
    HotkeyForm -->|"configures"| UserProfile
    DeleteMp3sForm -->|"deletes files in"| OutputFolder
    UpdaterForm -->|"checks"| VersionFile
    UpdaterForm -->|"invokes"| updaterExe

    BeatmapEditor -->|"parses beats via"| FsBeatmapParser
    DifficultyCalculator -->|"executes"| oppai
    SongSpeedChanger -->|"executes"| soundstretch
    globalKeyboardHook -->|"raises events to"| MainForm
    globalKeyboardHook -->|"raises events to"| BeatmapEditor

    UserProfile -->|"stored in"| ProfileStore
    Settings -->|"stored in"| SettingsFile
    BeatmapEditor -->|"reads/writes"| BeatmapFiles
    SongSpeedChanger -->|"writes mp3 to"| OutputFolder

    %% Click Events
    click MainForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/MainForm.cs"
    click HotkeyForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/HotkeyForm.cs"
    click DeleteMp3sForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/DeleteMp3sForm.cs"
    click UpdaterForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/UpdaterForm.cs"
    click RenameProfileForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/RenameProfileForm.cs"
    click SongsFolderForm "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Forms/SongsFolderForm.cs"
    click OsuButton "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Controls/OsuButton.cs"
    click RatioBar "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Controls/RatioBar.cs"
    click SongDisplay "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Controls/SongDisplay.cs"
    click StarsDisplay "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Controls/StarsDisplay.cs"
    click BeatmapEditor "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/BeatmapEditor.cs"
    click DifficultyCalculator "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/DifficultyCalculator.cs"
    click SongSpeedChanger "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/SongSpeedChanger.cs"
    click UserProfile "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/UserProfile.cs"
    click Settings "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/Settings.cs"
    click JunUtils "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/JunUtils.cs"
    click FsBeatmapParser "https://github.com/funorange/osu-trainer/tree/master/osu-trainer/submodules/FsBeatmapParser/"
    click globalKeyboardHook "https://github.com/funorange/osu-trainer/tree/master/osu-trainer/submodules/globalKeyboardHook/"
    click oppai "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/binaries/oppai.exe"
    click soundstretch "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/binaries/soundstretch.exe"
    click updaterExe "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/updater.exe"
    click AppConfig "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/App.config"
    click VersionFile "https://github.com/funorange/osu-trainer/blob/master/osu-trainer/version.txt"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#DFFFE0,stroke:#22863a,color:#22863a
    classDef module fill:#FFEDD5,stroke:#d15704,color:#d15704,stroke-dasharray: 5 5
    classDef exec fill:#EDEDED,stroke:#6a737d,color:#6a737d,shape:hexagon
    classDef storage fill:#FFF5B1,stroke:#735c0f,color:#735c0f,shape:cylinder
```
