# lostlmbecile/sparking-zero-audio-modding-tool architecture

> Architecture diagram of the GitHub repository lostlmbecile/sparking-zero-audio-modding-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lostlmbecile/sparking-zero-audio-modding-tool
- Repository: https://github.com/lostlmbecile/sparking-zero-audio-modding-tool

## Overview

This project is a Windows-only audio modding suite designed to handle game audio files by extracting, converting, processing, packaging, and injecting various audio assets. The system comprises three distinct tools:
- The main tool (SparkingZeroAudioModdingTool) that oversees general modding tasks such as extracting files from various formats (.acb, .awb, .uasset), converting them from HCA to WAV and vice versa, and packaging them back into mod files.
- The BgmModdingTool sub-module which specializes in handling background music (BGM) injection, specifically managing AWB file headers and uasset injections, along with index/cue mapping.
- The AddWavMetadata sub-module that adds metadata to WAV files (covering Title, Album, Artist, Genre, and Track Number).

##### Main Components
a. User Input / File Interaction:
– Represent the user interface (CLI or drag-and-drop file operations) that accepts various file types and folders from the user.
b. Core Modding Components:
– SparkingZeroAudioModdingTool as the central coordinator handling general modding operations, from file extraction to packaging.
– BgmModdingTool, a sub-module specifically responsible for extracting AWB headers and injecting data into game files.
– AddWavMetadata tool, responsible for enriching WAV files with metadata.
c. Processing Pipelines and File Handling:
– Components for file extraction, conversion between formats (WAV ↔ HCA), packaging into mod-specific containers (utoc, ucas, pak), Dll integration and index mapping.
d. External Dependencies:
e. Supporting Configuration and Resources:
– Config files (config.ini, keys.csv) that guide the modding process.
– Resource files and manifests (app.manifest and resources.rc present in multiple resource directories) that set application metadata and Windows-specific runtime data.

##### Relationships and Data Flow
– User inputs files (AWB, ACB, uasset, WAV files) into the main tool.
– Main tool feeds extracted files to the conversion pipeline (HCA conversion via vgmstream-cli).
– Once converted, files flow into packaging steps where mod archives are built.
– For BGM-specific operations, AWB headers and uasset components are extracted/injected by the BgmModdingTool module.
– Metadata addition to WAV files is handled by the AddWavMetadata module.
b. That configuration settings (e.g., file paths, key files) drive parts of the process and are read early in the workflow.

##### Architectural Patterns or Design Principles
a. Modular Design: Each tool/sub-module handles a specific aspect of the overall modding process.
b. Decoupling of core functionalities: The separation between general modding, BGM injection, and metadata addition invites clear boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UI["File Input (CLI/Drag-Drop)"]:::external

    %% Configuration & Resources
    Config["Config Files (config.ini, keys.csv)"]:::config
    Resources["Resource Files (app.manifest, resources.rc)"]:::config

    %% Core Modding Tools
    subgraph "Core Tools"
        MainTool["SparkingZeroAudioModdingTool"]:::internal
        BgmTool["BgmModdingTool"]:::internal
        WavMetadata["AddWavMetadata"]:::internal
    end

    %% Processing Pipelines
    subgraph "Processing Pipelines"
        FE["File Extraction & Processing"]:::internal
        AC["Audio Conversion (HCA↔WAV)"]:::internal
        PK["Packaging & Index Mapping"]:::internal
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Vgm["vgmstream-cli"]:::external
        Acb["AcbEditor"]:::external
        VGA["VGAudioCli"]:::external
        UPak["UnrealPak"]:::external
        UReZen["UnrealReZen"]:::external
    end

    %% Data Flow and Relationships
    UI -->|"provides input"| MainTool
    Config -->|"configuration"| MainTool
    Resources -->|"runtime metadata"| MainTool

    MainTool -->|"initiates"| FE
    FE -->|"extracted files"| AC
    AC -->|"converted audio"| PK
    PK -->|"mod file package"| MainTool

    MainTool -->|"triggers"| BgmTool
    BgmTool -->|"processes BGM files"| PK
    Resources -->|"BGM resources"| BgmTool

    AC -->|"sends WAV for metadata"| WavMetadata
    WavMetadata -->|"outputs enhanced WAV"| PK

    %% External calls
    AC -->|"calls"| Vgm
    BgmTool -->|"calls"| Acb
    BgmTool -->|"calls"| VGA
    PK -->|"invokes"| UPak
    PK -->|"invokes"| UReZen

    %% Click Events for Component Mapping
    click MainTool "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/Source/main.c"
    click BgmTool "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/BGM_Source/main.c"
    click WavMetadata "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/WAV Metadata Tool/main.c"
    click FE "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/Source/file_extractor.c"
    click AC "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/Source/audio_converter.c"
    click PK "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/Source/file_packer.c"
    click Config "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/config.ini"
    click Resources "https://github.com/lostlmbecile/sparking-zero-audio-modding-tool/blob/main/Resources/app.manifest"

    %% Class Definitions for Styling
    classDef internal fill:#BFD7B5,stroke:#333,stroke-width:2px;
    classDef external fill:#F7A072,stroke:#333,stroke-width:2px;
    classDef config fill:#C2DFFF,stroke:#333,stroke-width:2px;
```
