# mctop4ik/midiwavconverter architecture

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

- Interactive diagram: https://gitdiagram.com/mctop4ik/midiwavconverter
- Repository: https://github.com/mctop4ik/midiwavconverter

## Overview

#### Purpose and Entry Point
Zetni is a C++ music-rendering/synthesis tool. It converts text-based song definitions into audio using patterns, instruments, effects, sampled WAV assets, and WAV output. The executable entry point is `src/zetni_main.cc`; build composition is defined by `CMakeLists.txt`.

#### Input-to-Output Pipeline
The orchestration layer in `src/zetni-pipeline.cc` connects parsing, synthesis, and file output. Music source files such as `examples/badapple.txt` and `examples/interstellar.txt` are parsed into an internal music representation, rendered by the engine, then serialized as waveform data through `src/zetni-wavefile.cc`.
Key contracts are exposed in `includes/zetni/zetni-pipeline.h`, `includes/zetni/zetni-music-file.h`, and `includes/zetni/zetni-wavefile.h`.

#### Syntax and Music Parsing
`src/zetni-syntax-analyzator.cc` performs syntax-level analysis before semantic music parsing. `src/zetni-parser.cc` handles the broader source format, while `src/zetni-pattern-parser.cc` creates pattern-specific structures.
The resulting pattern model is implemented in `src/zetni-pattern.cc` and declared by `includes/zetni/zetni-pattern.h`. This separates textual notation concerns from playback/rendering behavior.

#### Pattern Execution
Patterns are executable sequences of instructions. Two central instruction types are:
- Instrument playback: `src/pattern-instructions/zetni-instrument-play-pattern-instruction.cc`
- Pattern invocation/composition: `src/pattern-instructions/zetni-call-another-pattern-instruction.cc`

Their interfaces in `includes/zetni/interfaces/zetni-pattern-instruction-interface.h` and related headers allow the engine to schedule notes and reuse named patterns without coupling the parser directly to concrete instruction implementations.

#### Rendering Engine and Envelope Control
`src/zetni-engine.cc` is the primary audio-rendering boundary: it consumes parsed music/pattern data, invokes instruments, applies effects, and produces sample streams. `src/zetni-adsr.cc` supplies ADSR envelope behavior for note amplitude shaping.
Core abstractions are defined in `includes/zetni/interfaces/zetni-engine-interface.h`, `includes/zetni/zetni-engine.h`, and `includes/zetni/zetni-adsr.h`.

#### Instrument Layer
Concrete sound sources include procedural oscillators and a sample-based instrument:
`src/instruments/zetni-instruments-sine.cc`, `src/instruments/zetni-instruments-square.cc`, and `src/instruments/zetni-instruments-sampler.cc`.
The sampler reads repository WAV assets such as `samples/piano.wav` and `samples/kick.wav`; WAV decoding is handled by `src/zetni-wavefile.cc`. Common instrument dispatch/registration is centralized in `src/zetni-instruments.cc` behind `includes/zetni/interfaces/zetni-instrument-interface.h`.

#### Effects and External Dependencies
Effects are modular post- or per-signal transformations, with gain, echo, and tremolo implementations in `src/effects/zetni-effect-gain.cc`, `src/effects/zetni-effect-echo.cc`, and `src/effects/zetni-effect-tremolo.cc`. `src/zetni-effects.cc` manages effect selection/application through `includes/zetni/interfaces/zetni-effect-interface.h`.
The repository shows no network services, databases, or cloud infrastructure. Runtime dependencies are local filesystem access to song definitions and WAV samples/output; CMake is the build-system integration point.

Main entry points: [`src/zetni-engine.cc`](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-engine.cc) (Rendering Engine), [`src/zetni-pipeline.cc`](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pipeline.cc) (Render Pipeline), [`src/zetni-wavefile.cc`](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-wavefile.cc) (WAV Reader/Writer), [`src/zetni-pattern.cc`](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pattern.cc) (Pattern Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Music Inputs"]
  node_songs["Song Definitions<br/>music source<br/>[badapple.txt]"]
  node_samples["WAV Sample Assets<br/>audio assets<br/>[piano.wav]"]
end

subgraph group_parse["Parsing &amp; Patterns"]
  node_syntax["Syntax Analysis<br/>parser stage"]
  node_music_parser["Music Parser<br/>[zetni-parser.cc]"]
  node_pattern_parser["Pattern Parser"]
  node_pattern_model["Pattern Model<br/>music model<br/>[zetni-pattern.cc]"]
  node_instrument_instruction["Instrument Play<br/>pattern instruction"]
  node_pattern_call["Pattern Call<br/>pattern instruction"]
end

subgraph group_render["Audio Rendering"]
  node_engine["Rendering Engine<br/>audio engine<br/>[zetni-engine.cc]"]
  node_adsr["ADSR Envelope<br/>amplitude control<br/>[zetni-adsr.cc]"]
  node_instruments["Instrument Registry<br/>instrument dispatch"]
  node_sound_sources["Oscillators &amp; Sampler<br/>instrument implementations"]
  node_effects["Effects Manager<br/>effect dispatch<br/>[zetni-effects.cc]"]
  node_effect_impls["Gain, Echo &amp; Tremolo<br/>effect implementations"]
end

node_build["CMake Build<br/>[CMakeLists.txt]"]
node_main["CLI Entry Point<br/>executable<br/>[zetni_main.cc]"]
node_pipeline["Render Pipeline<br/>orchestrator<br/>[zetni-pipeline.cc]"]
node_wavefile["WAV Reader/Writer<br/>waveform I/O<br/>[zetni-wavefile.cc]"]
node_output["WAV Output<br/>audio file"]

node_build -->|"builds"| node_main
node_main -->|"starts"| node_pipeline
node_songs -->|"source input"| node_pipeline
node_pipeline -->|"analyzes"| node_syntax
node_syntax -->|"validated text"| node_music_parser
node_music_parser -->|"parses patterns"| node_pattern_parser
node_pattern_parser -->|"builds"| node_pattern_model
node_instrument_instruction -.->|"instruction type"| node_pattern_model
node_pattern_call -.->|"instruction type"| node_pattern_model
node_pipeline -->|"renders"| node_engine
node_pattern_model -->|"scheduled patterns"| node_engine
node_engine -->|"shapes notes"| node_adsr
node_engine -->|"invokes"| node_instruments
node_instruments -->|"selects"| node_sound_sources
node_samples -->|"sample data"| node_wavefile
node_wavefile -->|"decoded WAV"| node_sound_sources
node_engine -->|"applies"| node_effects
node_effects -->|"selects"| node_effect_impls
node_engine -->|"sample stream"| node_wavefile
node_pipeline -->|"writes through"| node_wavefile
node_wavefile -->|"serializes"| node_output

click node_build "https://github.com/mctop4ik/midiwavconverter/blob/master/CMakeLists.txt"
click node_main "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni_main.cc"
click node_songs "https://github.com/mctop4ik/midiwavconverter/blob/master/examples/badapple.txt"
click node_pipeline "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pipeline.cc"
click node_syntax "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-syntax-analyzator.cc"
click node_music_parser "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-parser.cc"
click node_pattern_parser "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pattern-parser.cc"
click node_pattern_model "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pattern.cc"
click node_instrument_instruction "https://github.com/mctop4ik/midiwavconverter/blob/master/src/pattern-instructions/zetni-instrument-play-pattern-instruction.cc"
click node_pattern_call "https://github.com/mctop4ik/midiwavconverter/blob/master/src/pattern-instructions/zetni-call-another-pattern-instruction.cc"
click node_engine "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-engine.cc"
click node_adsr "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-adsr.cc"
click node_instruments "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-instruments.cc"
click node_sound_sources "https://github.com/mctop4ik/midiwavconverter/blob/master/src/instruments/zetni-instruments-sampler.cc"
click node_effects "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-effects.cc"
click node_effect_impls "https://github.com/mctop4ik/midiwavconverter/blob/master/src/effects/zetni-effect-gain.cc"
click node_samples "https://github.com/mctop4ik/midiwavconverter/blob/master/samples/piano.wav"
click node_wavefile "https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-wavefile.cc"

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_songs,node_samples toneBlue
class node_syntax,node_music_parser,node_pattern_parser,node_pattern_model,node_instrument_instruction,node_pattern_call toneAmber
class node_engine,node_adsr,node_instruments,node_sound_sources,node_effects,node_effect_impls toneMint
class node_build,node_main,node_pipeline,node_wavefile,node_output toneNeutral
```

## Components

### Music Inputs

- [Song Definitions](https://github.com/mctop4ik/midiwavconverter/blob/master/examples/badapple.txt): music source · `examples/badapple.txt`
- [WAV Sample Assets](https://github.com/mctop4ik/midiwavconverter/blob/master/samples/piano.wav): audio assets · `samples/piano.wav`

### Parsing & Patterns

- [Syntax Analysis](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-syntax-analyzator.cc): parser stage · `src/zetni-syntax-analyzator.cc`
- [Music Parser](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-parser.cc): parser · `src/zetni-parser.cc`
- [Pattern Parser](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pattern-parser.cc): parser · `src/zetni-pattern-parser.cc`
- [Pattern Model](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pattern.cc): music model · Executable pattern sequences and instructions. · `src/zetni-pattern.cc`
- [Instrument Play](https://github.com/mctop4ik/midiwavconverter/blob/master/src/pattern-instructions/zetni-instrument-play-pattern-instruction.cc): pattern instruction · `src/pattern-instructions/zetni-instrument-play-pattern-instruction.cc`
- [Pattern Call](https://github.com/mctop4ik/midiwavconverter/blob/master/src/pattern-instructions/zetni-call-another-pattern-instruction.cc): pattern instruction · `src/pattern-instructions/zetni-call-another-pattern-instruction.cc`

### Audio Rendering

- [Rendering Engine](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-engine.cc): audio engine · Schedules patterns and produces audio samples. · `src/zetni-engine.cc`
- [ADSR Envelope](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-adsr.cc): amplitude control · `src/zetni-adsr.cc`
- [Instrument Registry](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-instruments.cc): instrument dispatch · `src/zetni-instruments.cc`
- [Oscillators & Sampler](https://github.com/mctop4ik/midiwavconverter/blob/master/src/instruments/zetni-instruments-sampler.cc): instrument implementations · Sine, square, and WAV-sample sound sources. · `src/instruments/zetni-instruments-sampler.cc`
- [Effects Manager](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-effects.cc): effect dispatch · `src/zetni-effects.cc`
- [Gain, Echo & Tremolo](https://github.com/mctop4ik/midiwavconverter/blob/master/src/effects/zetni-effect-gain.cc): effect implementations · `src/effects/zetni-effect-gain.cc`

### Other components

- [CMake Build](https://github.com/mctop4ik/midiwavconverter/blob/master/CMakeLists.txt): build · `CMakeLists.txt`
- [CLI Entry Point](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni_main.cc): executable · `src/zetni_main.cc`
- [Render Pipeline](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-pipeline.cc): orchestrator · Coordinates parsing, rendering, and WAV output. · `src/zetni-pipeline.cc`
- [WAV Reader/Writer](https://github.com/mctop4ik/midiwavconverter/blob/master/src/zetni-wavefile.cc): waveform I/O · Decodes sampled WAV files and serializes rendered output. · `src/zetni-wavefile.cc`
- **WAV Output**: audio file

## Connections

- CMake Build → CLI Entry Point: builds
- CLI Entry Point → Render Pipeline: starts
- Song Definitions → Render Pipeline: source input
- Render Pipeline → Syntax Analysis: analyzes
- Syntax Analysis → Music Parser: validated text
- Music Parser → Pattern Parser: parses patterns
- Pattern Parser → Pattern Model: builds
- Instrument Play → Pattern Model: instruction type
- Pattern Call → Pattern Model: instruction type
- Render Pipeline → Rendering Engine: renders
- Pattern Model → Rendering Engine: scheduled patterns
- Rendering Engine → ADSR Envelope: shapes notes
- Rendering Engine → Instrument Registry: invokes
- Instrument Registry → Oscillators & Sampler: selects
- WAV Sample Assets → WAV Reader/Writer: sample data
- WAV Reader/Writer → Oscillators & Sampler: decoded WAV
- Rendering Engine → Effects Manager: applies
- Effects Manager → Gain, Echo & Tremolo: selects
- Rendering Engine → WAV Reader/Writer: sample stream
- Render Pipeline → WAV Reader/Writer: writes through
- WAV Reader/Writer → WAV Output: serializes