# tinaishe-dr/virtual_mbira architecture

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

- Interactive diagram: https://gitdiagram.com/tinaishe-dr/virtual_mbira
- Repository: https://github.com/tinaishe-dr/virtual_mbira

## Overview

Virtual Mbira is a browser-based instrument and loop studio. Players choose either instrument, strike keys with mouse, keyboard, or touch, tune and shape the voice, then record and manage layered loops for playback or WAV export. The main runtime responsibilities visible in the excerpts are input/session orchestration, musical mapping and session encoding, and Web Audio synthesis/rendering; the README documents additional gallery, cultural information, and media capabilities. Source excerpts do not show all UI wiring, so undocumented connections are omitted.

Main entry points: [`app.js`](https://github.com/tinaishe-dr/virtual_mbira/blob/main/app.js) (Recording and layers), [`audio.js`](https://github.com/tinaishe-dr/virtual_mbira/blob/main/audio.js) (Voice playback), [`index.html`](https://github.com/tinaishe-dr/virtual_mbira/blob/main/index.html) (Instrument, gallery, context), [`server.js`](https://github.com/tinaishe-dr/virtual_mbira/blob/main/server.js) (Local media server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Playing instruments"]
  node_app["Instrument UI<br/>[app.js]"]
  node_music["Tuning and events<br/>[music.js]"]
end

subgraph group_studio["Loop studio"]
  node_studio["Recording and layers<br/>[app.js]"]
  node_session[("Saved session")]
  node_wav["WAV export<br/>[audio.js]"]
end

subgraph group_sound["Audio engine"]
  node_audio["Voice playback<br/>[audio.js]"]
  node_banks["Reference sound banks<br/>[reference-bank.js]"]
  node_nyungabank["Nyunga sound bank<br/>[nyunga-bank.js]"]
end

subgraph group_content["Media and context"]
  node_page["Instrument, gallery, context<br/>[index.html]"]
  node_media["Performance video"]
  node_server["Local media server<br/>[server.js]"]
end

node_player(("Player"))

node_player -->|"plays and configures"| node_app
node_app -->|"maps pitches"| node_music
node_app -->|"plays notes"| node_audio
node_app -->|"records and controls"| node_studio
node_studio -->|"mixes events"| node_music
node_studio -->|"saves and restores"| node_session
node_studio -->|"plays mix"| node_audio
node_studio -->|"exports mix"| node_wav
node_wav -->|"renders offline"| node_audio
node_audio -->|"decodes voice"| node_banks
node_audio -->|"decodes voice"| node_nyungabank
node_page -->|"presents video"| node_media
node_player -->|"explores"| node_page
node_player -->|"requests page and media"| node_server
node_server -->|"serves ranges"| node_media

click node_app "https://github.com/tinaishe-dr/virtual_mbira/blob/main/app.js"
click node_music "https://github.com/tinaishe-dr/virtual_mbira/blob/main/music.js"
click node_audio "https://github.com/tinaishe-dr/virtual_mbira/blob/main/audio.js"
click node_banks "https://github.com/tinaishe-dr/virtual_mbira/blob/main/reference-bank.js"
click node_nyungabank "https://github.com/tinaishe-dr/virtual_mbira/blob/main/nyunga-bank.js"
click node_studio "https://github.com/tinaishe-dr/virtual_mbira/blob/main/app.js"
click node_wav "https://github.com/tinaishe-dr/virtual_mbira/blob/main/audio.js"
click node_page "https://github.com/tinaishe-dr/virtual_mbira/blob/main/index.html"
click node_media "https://github.com/tinaishe-dr/virtual_mbira/blob/main/assets/mbira-performance.mp4"
click node_server "https://github.com/tinaishe-dr/virtual_mbira/blob/main/server.js"

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_app,node_music toneBlue
class node_studio,node_session,node_wav toneAmber
class node_audio,node_banks,node_nyungabank toneMint
class node_page,node_media,node_server toneRose
class node_player toneIndigo
```

## Components

### Playing instruments

- [Instrument UI](https://github.com/tinaishe-dr/virtual_mbira/blob/main/app.js): `app.js`
- [Tuning and events](https://github.com/tinaishe-dr/virtual_mbira/blob/main/music.js): `music.js`

### Loop studio

- [Recording and layers](https://github.com/tinaishe-dr/virtual_mbira/blob/main/app.js): `app.js`
- **Saved session**
- [WAV export](https://github.com/tinaishe-dr/virtual_mbira/blob/main/audio.js): `audio.js`

### Audio engine

- [Voice playback](https://github.com/tinaishe-dr/virtual_mbira/blob/main/audio.js): `audio.js`
- [Reference sound banks](https://github.com/tinaishe-dr/virtual_mbira/blob/main/reference-bank.js): `reference-bank.js`
- [Nyunga sound bank](https://github.com/tinaishe-dr/virtual_mbira/blob/main/nyunga-bank.js): `nyunga-bank.js`

### Media and context

- [Instrument, gallery, context](https://github.com/tinaishe-dr/virtual_mbira/blob/main/index.html): `index.html`
- [Performance video](https://github.com/tinaishe-dr/virtual_mbira/blob/main/assets/mbira-performance.mp4): `assets/mbira-performance.mp4`
- [Local media server](https://github.com/tinaishe-dr/virtual_mbira/blob/main/server.js): `server.js`

### Other components

- **Player**

## Connections

- Player → Instrument UI: plays and configures (evidence: `README.md`)
- Instrument UI → Tuning and events: maps pitches (evidence: `app.js`)
- Instrument UI → Voice playback: plays notes (evidence: `README.md`)
- Instrument UI → Recording and layers: records and controls (evidence: `app.js`)
- Recording and layers → Tuning and events: mixes events (evidence: `README.md`)
- Recording and layers → Saved session: saves and restores (evidence: `app.js`)
- Recording and layers → Voice playback: plays mix (evidence: `README.md`)
- Recording and layers → WAV export: exports mix (evidence: `README.md`)
- WAV export → Voice playback: renders offline (evidence: `audio.js`)
- Voice playback → Reference sound banks: decodes voice (evidence: `audio.js`)
- Voice playback → Nyunga sound bank: decodes voice (evidence: `audio.js`)
- Instrument, gallery, context → Performance video: presents video (evidence: `README.md`)
- Player → Instrument, gallery, context: explores (evidence: `README.md`)
- Player → Local media server: requests page and media (evidence: `README.md`)
- Local media server → Performance video: serves ranges (evidence: `server.js`)
