# chiplex/chiptunify architecture

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

- Interactive diagram: https://gitdiagram.com/chiplex/chiptunify
- Repository: https://github.com/chiplex/chiptunify

## Overview

##### Main Components
- Core Modules (within the "chiptunify" package):
- Audio Processing: Located in chiptunify/audio/effects.py, this module applies the chiptune effects.
- MIDI Processing: Found in chiptunify/midi/converter.py, this part handles MIDI file inputs (notes/tempo) to guide the conversion.
- Model Processing: Under chiptunify/model, you have the voice_encoder.py and voice_converter.py. The voice encoder extracts key features from the input voice while the voice converter maps these features for conversion into a singing output.

- Scripts (in the "scripts" directory):
- train.py: For training the conversion model using new voice data.
- convert.py: Entry point for converting a given voice sample and MIDI file into a chiptune output.
- demo.py, debug.py, and ui.py: These support showcasing, debugging, and interfacing with the system.

- Auxiliary:
- README, requirements.txt, and docs provide additional context and usage instructions.

##### Relationships and Data Flow
- User Input: A voice sample (e.g., WAV file) and a MIDI file (containing musical note information) are provided.
- Pre-Processing:
- The voice sample is first processed by the Voice Encoder to extract its unique characteristics.
- Simultaneously, the MIDI file is processed by the MIDI Converter to generate musical guidelines.
- Conversion Process:
- The extracted voice features, alongside the MIDI-derived cues, are fed into the Voice Converter to generate an intermediate singing representation.
- Audio Effects Application:
- The output from the conversion process then flows to the Audio Effects module, which applies the desired chiptune effects (e.g., adjusting bit depth, distortion, bitcrush).
- Output:
- The final audio output is then generated (a transformed file with the chiptune singing).

##### Architectural Patterns and Technologies
- The module separation (audio, midi, model) indicates a separation of concerns – each major aspect of the conversion (feature extraction, MIDI handling, audio effects) is isolated.
- Data flows sequentially from input → feature extraction → conversion → effects, highlighting a pipeline architecture.
- The project is built in Python (with a dependency on PyTorch) making it clear that the AI model training/inference is a central component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Pipeline
    A["Voice Sample"]:::input
    B["MIDI File"]:::input
    C["Voice Encoder"]:::processing
    D["MIDI Converter"]:::processing
    E["Voice Converter"]:::processing
    F["Audio Effects Processor"]:::processing
    G["Final Chiptune Audio Output"]:::output

    %% Orchestration and Support Nodes
    H["Conversion Orchestration"]:::orchestration
    I["Training Orchestration"]:::orchestration
    J1["User Interface"]:::orchestration
    J2["Demo"]:::orchestration
    J3["Debug"]:::orchestration

    %% Auxiliary Documentation Nodes
    K["README & Guidelines"]:::aux
    K2["Docs"]:::aux

    %% Data Flow Connections for Main Pipeline
    A -->|"process"| C
    B -->|"process"| D
    C -->|"feature"| E
    D -->|"notes"| E
    E -->|"convert"| F
    F -->|"effects"| G

    %% Orchestration Connections
    H -->|"triggers"| A
    H -->|"triggers"| B
    I -.->|"train"| C
    I -.->|"train"| E
    J1 -->|"init"| H
    J2 -->|"init"| H
    J3 -->|"init"| H

    %% Styling for Vertical Orientation
    %% (Nodes will naturally stack vertically based on connections)

    %% Styles
    classDef input fill:#FFDDC1,stroke:#8B4000,stroke-width:2px;
    classDef processing fill:#CEF6F5,stroke:#008080,stroke-width:2px;
    classDef orchestration fill:#D7F3FF,stroke:#005073,stroke-width:2px;
    classDef output fill:#FFC6FF,stroke:#AA0078,stroke-width:2px;
    classDef aux fill:#FFFACD,stroke:#B8860B,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events
    click C "https://github.com/chiplex/chiptunify/blob/main/chiptunify/model/voice_encoder.py"
    click D "https://github.com/chiplex/chiptunify/blob/main/chiptunify/midi/converter.py"
    click E "https://github.com/chiplex/chiptunify/blob/main/chiptunify/model/voice_converter.py"
    click F "https://github.com/chiplex/chiptunify/blob/main/chiptunify/audio/effects.py"
    click I "https://github.com/chiplex/chiptunify/blob/main/scripts/train.py"
    click H "https://github.com/chiplex/chiptunify/blob/main/scripts/convert.py"
    click J1 "https://github.com/chiplex/chiptunify/blob/main/scripts/ui.py"
    click J2 "https://github.com/chiplex/chiptunify/blob/main/scripts/demo.py"
    click J3 "https://github.com/chiplex/chiptunify/blob/main/scripts/debug.py"
    click K "https://github.com/chiplex/chiptunify/blob/main/README.md"
    click K2 "https://github.com/chiplex/chiptunify/tree/main/docs/"
```
