# sonic-visualiser/sonic-visualiser architecture

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

- Interactive diagram: https://gitdiagram.com/sonic-visualiser/sonic-visualiser
- Repository: https://github.com/sonic-visualiser/sonic-visualiser

## Overview

##### Project Type and Purpose
- Sonic Visualiser is a cross-platform desktop application used for visualising, annotating, and analysing audio files. It is primarily a multimedia tool with a graphical user interface built using Qt, combined with audio processing and plugin support.
- The README emphasizes its capabilities (waveform displays, spectrogram views, annotation features, feature-extraction plugins using Vamp, etc.) as well as its multi-platform nature (Linux, macOS, Windows) with separate build instructions and CI integrations.

##### Analyzing the File Structure
- Top-Level Directories/Files: The file tree shows multiple directories such as “main” (with the core UI and application code), “deploy” (platform-specific deployment and packaging scripts for Linux, macOS, and Windows), “i18n” (internationalization files), and “samples” and “templates” which provide sample data/configurations.
- Build Configuration: Files such as meson.build and meson_options.txt indicate that Meson is used as the build system. The presence of CI configuration files (e.g., in the .github/workflows directory and .appveyor.yml) further indicates automated builds/testing across different platforms.

##### Architectural Components
a. User Interface (Frontend):
- MainWindow, PreferencesDialog, Splash screen, and other GUI components built using Qt.
- Internationalisation support (i18n folder) that feeds strings and translations to the UI.

b. Audio Processing Core:
- Core routines handling audio file loading, waveform generation, spectrogram calculations, and annotations.
- Interaction with external libraries (FFTW3, libsndfile, PortAudio, etc.) and codecs to support various audio formats.

c. Plugin and Feature Extraction System:
- Interfaces for Vamp plugins and possibly LADSPA allowing feature extraction (e.g., beat tracking, pitch detection).
- Architecture should reflect extension points that allow integration of plugins.

d. OSC/Remote Control Interface:
- Communication module (OSCHandler.cpp) to support remote controlling of the application using the OSC protocol.

e. Deployment and Packaging Components:
- Directories under “deploy” show scripts and configuration details for packaging the application as AppImage, DEB packages on Linux, notarizing and signing on macOS, and various build scripts for Windows.

##### Relationships and Interactions
- The User Interface layer interacts with the core audio processing modules to display loaded audio and rendered visualisations (e.g., spectrogram and waveform views).
- The core audio engine, in turn, calls out to external libraries and plugins for specialised processing.
- The OSC component listens for and sends control messages to/from the UI and processing backend.
- Deployment components are somewhat orthogonal – they package the complete build into installable units, so you might represent them as enveloping the entire application to denote the build & distribution pipeline.

##### Architectural Patterns and Design Principles
- Modular Design: The separation between “main” (UI/logic), “deploy” (platform-specific packaging), “i18n” (translation), and “samples/templates” (example data) points toward a modular layout.
- Plugin/Extension Architecture: Support for Vamp and LADSPA plugins is central, so represent clear extension points.
- Cross-Platform Consideration: The build and deployment system is split for Linux, macOS, and Windows, so emphasize platform-specific adaptations in the deployment pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface (Frontend)"
        MW["MainWindow"]:::ui
        PD["PreferencesDialog"]:::ui
        SV["Splash Screen"]:::ui
        SR["Surveyer"]:::ui
        Res["Resource File (sonic-visualiser.qrc)"]:::ui
        Icons["Icons Directory"]:::ui
        I18n["Internationalisation (i18n)"]:::ui
    end

    subgraph "Audio Processing Core"
        Core["main.cpp & Processing Modules"]:::audio
    end

    subgraph "OSC/Remote Control Interface"
        OSC["OSCHandler"]:::osc
    end

    subgraph "Plugin and Feature Extraction"
        Vamp1["Vamp Plugin Info (README-Vamp.txt)"]:::plugin
        Vamp32["Vamp Plugin Info (README-Vamp32.txt)"]:::plugin
    end

    subgraph "Deployment and Packaging"
        Deploy["Deployment Scripts (deploy)"]:::deploy
        DeployLinux["Linux Packaging (deploy/linux)"]:::deploy
        DeployMac["macOS Deployment (deploy/macos)"]:::deploy
        DeployWin["Windows Deployment (deploy/win64)"]:::deploy
        CI1["CI Integration (.github/workflows)"]:::deploy
        CI2["Appveyor Config (.appveyor.yml)"]:::deploy
    end

    %% Relationships
    MW -->|"triggers"| Core
    PD -->|"configures"| Core
    SV -->|"initializes UI"| Core
    I18n -->|"feeds translations to"| MW
    Icons -->|"supplies graphics to"| Res
    Res -->|"provides resource data to"| MW

    MW -->|"sends OSC commands"| OSC
    OSC -->|"controls processing"| Core

    Core -->|"loads plugins"| Vamp1
    Core -->|"loads plugins"| Vamp32

    %% Deployment packaging wraps the entire application
    Core -->|"packaged in"| Deploy
    MW -->|"packaged in"| Deploy
    OSC -->|"packaged in"| Deploy
    Vamp1 -->|"packaged in"| Deploy

    Deploy -->|"includes"| DeployLinux
    Deploy -->|"includes"| DeployMac
    Deploy -->|"includes"| DeployWin
    Deploy --> CI1
    Deploy --> CI2

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef audio fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef osc fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef plugin fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef deploy fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click MW "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/MainWindow.cpp"
    click PD "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/PreferencesDialog.cpp"
    click SV "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/SVSplash.cpp"
    click SR "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/Surveyer.cpp"
    click Res "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/sonic-visualiser.qrc"
    click Icons "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/icons"
    click I18n "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/i18n"
    click Core "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/main.cpp"
    click OSC "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/main/OSCHandler.cpp"
    click Vamp1 "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/deploy/win64/README-Vamp.txt"
    click Vamp32 "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/deploy/win64/README-Vamp32.txt"
    click Deploy "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/deploy"
    click DeployLinux "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/deploy/linux"
    click DeployMac "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/deploy/macos"
    click DeployWin "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/deploy/win64"
    click CI1 "https://github.com/sonic-visualiser/sonic-visualiser/tree/default/.github/workflows"
    click CI2 "https://github.com/sonic-visualiser/sonic-visualiser/blob/default/.appveyor.yml"
```
