# gogul09/deep-drum architecture

> Architecture diagram of the GitHub repository gogul09/deep-drum, 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/gogul09/deep-drum
- Repository: https://github.com/gogul09/deep-drum

## Overview

#### Purpose and Entry Point
This is a static, browser-based intelligent music demo. It generates continuous drum patterns from a seeded rhythm and arpeggios from input notes plus chord context, using Magenta DrumsRNN and ImprovRNN concepts. The application starts from `index.html`, with presentation styling in `css/app.scss` and compiled `css/app.css`.

#### Browser Runtime and UI Layer
The client runs entirely in the browser; no server, API, database, or deployment runtime is represented in the repository. Materialize provides UI styling/components, while Nexus appears to provide interactive music-control widgets.
- `index.html`
- `externals/css/materialize.css`
- `externals/js/materialize.js`
- `js/nexus.js`

#### Control and State Coordination
Control changes are centralized through an update layer, which likely propagates user selections—such as tempo, instruments, patterns, or musical settings—to the sequencing and playback modules. Multi-selection/tag behavior is separated from the main control updater.
- `js/update_controls.js`
- `js/multiple_tag.js`
- `js/gpad.js`

#### Generative Music Stages
The core generation pipeline is split by musical role. `deepdrum.js` is the drum-pattern generation integration corresponding to the README’s DrumsRNN behavior. `arp_and_bass.js` handles generated arpeggio/bass behavior associated with ImprovRNN-style chord-conditioned note generation. `chord_finder.js` supplies harmonic context to the arpeggiator.
- `js/deepdrum.js`
- `js/arp_and_bass.js`
- `js/chord_finder.js`

#### Musical Representation and Scheduling
Music-theory utilities, MIDI/note mapping, and timeline scheduling form the boundary between generated symbolic patterns and audible playback. Generated or user-entered notes must be mapped into playable pitches/instruments and placed on a time sequence.
- `js/tonal.js`
- `js/reverse_midi_map.js`
- `js/timeline.js`

#### Audio Engine and Local Media Boundary
Tone.js is the browser audio runtime. Playback depends on repository-hosted audio samples rather than an external streaming service: piano samples in Salamander, guitar samples, bass, and several named drum kits. The generation/control code ultimately drives this audio layer.
- `js/tone.js`
- `sounds/salamander/C4.mp3`
- `sounds/acoustic_guitar/A3.wav`
- `sounds/drum-kits/analog/kick.mp3`

#### Primary Flow
User interaction in the page and Nexus/Materialize controls updates application state. Seed rhythms feed the drum generator; notes and detected/selected chords feed the arpeggio generator. These symbolic outputs pass through tonal/MIDI mapping and the timeline, then Tone.js schedules local instrument samples for browser playback. The important boundary is between generative pattern logic (`js/deepdrum.js`, `js/arp_and_bass.js`) and deterministic sequencing/audio playback (`js/timeline.js`, `js/tone.js`).

Main entry points: [`js/update_controls.js`](https://github.com/gogul09/deep-drum/blob/master/js/update_controls.js) (Control updater), [`index.html`](https://github.com/gogul09/deep-drum/blob/master/index.html) (App entry page), [`js/tone.js`](https://github.com/gogul09/deep-drum/blob/master/js/tone.js) (Tone.js engine), [`js/arp_and_bass.js`](https://github.com/gogul09/deep-drum/blob/master/js/arp_and_bass.js) (Arpeggio & bass generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_page["App entry page<br/>HTML entry<br/>[index.html]"]
  node_materialize_css["Materialize styles<br/>UI framework<br/>[materialize.css]"]
  node_materialize_js["Materialize controls<br/>UI framework<br/>[materialize.js]"]
  node_nexus["Nexus music widgets<br/>control widgets<br/>[nexus.js]"]
end

subgraph group_control["Control State"]
  node_control_updates["Control updater<br/>state coordinator<br/>[update_controls.js]"]
  node_multiple_tags["Multi-select tags<br/>selection behavior<br/>[multiple_tag.js]"]
  node_gpad["Gesture pad<br/>input control<br/>[gpad.js]"]
end

subgraph group_generation["Music Generation"]
  node_drum_generator{{"DrumsRNN integration<br/>drum generation<br/>[deepdrum.js]"}}
  node_chord_finder["Chord finder<br/>harmony analysis<br/>[chord_finder.js]"]
  node_arp_bass{{"Arpeggio &amp; bass generator<br/>note generation<br/>[arp_and_bass.js]"}}
end

subgraph group_sequencing["Representation &amp; Scheduling"]
  node_tonal["Music theory utilities<br/>tonal mapping<br/>[tonal.js]"]
  node_reverse_midi["MIDI pitch mapping<br/>note mapping"]
  node_timeline["Timeline scheduler<br/>symbolic sequencer<br/>[timeline.js]"]
end

subgraph group_audio["Audio Playback"]
  node_tone["Tone.js engine<br/>browser audio runtime<br/>[tone.js]"]
  node_piano_samples["Piano samples<br/>local media<br/>[C4.mp3]"]
  node_guitar_samples["Guitar samples<br/>local media<br/>[A3.wav]"]
  node_drum_samples["Drum-kit samples<br/>local media<br/>[kick.mp3]"]
end

node_page -->|"styles"| node_materialize_css
node_page -->|"loads"| node_materialize_js
node_page -->|"loads"| node_nexus
node_page -->|"initializes"| node_control_updates
node_materialize_js -->|"UI changes"| node_control_updates
node_nexus -->|"music controls"| node_control_updates
node_multiple_tags -->|"selections"| node_control_updates
node_gpad -->|"gestures"| node_control_updates
node_control_updates -->|"seed and settings"| node_drum_generator
node_control_updates -->|"input notes"| node_chord_finder
node_control_updates -->|"notes and settings"| node_arp_bass
node_chord_finder -->|"chord context"| node_arp_bass
node_drum_generator -->|"drum events"| node_timeline
node_arp_bass -->|"generated notes"| node_tonal
node_tonal -->|"resolved pitches"| node_reverse_midi
node_reverse_midi -->|"playable events"| node_timeline
node_timeline -->|"scheduled playback"| node_tone
node_tone -->|"loads"| node_piano_samples
node_tone -->|"loads"| node_guitar_samples
node_tone -->|"loads"| node_drum_samples

click node_page "https://github.com/gogul09/deep-drum/blob/master/index.html"
click node_materialize_css "https://github.com/gogul09/deep-drum/blob/master/externals/css/materialize.css"
click node_materialize_js "https://github.com/gogul09/deep-drum/blob/master/externals/js/materialize.js"
click node_nexus "https://github.com/gogul09/deep-drum/blob/master/js/nexus.js"
click node_control_updates "https://github.com/gogul09/deep-drum/blob/master/js/update_controls.js"
click node_multiple_tags "https://github.com/gogul09/deep-drum/blob/master/js/multiple_tag.js"
click node_gpad "https://github.com/gogul09/deep-drum/blob/master/js/gpad.js"
click node_drum_generator "https://github.com/gogul09/deep-drum/blob/master/js/deepdrum.js"
click node_chord_finder "https://github.com/gogul09/deep-drum/blob/master/js/chord_finder.js"
click node_arp_bass "https://github.com/gogul09/deep-drum/blob/master/js/arp_and_bass.js"
click node_tonal "https://github.com/gogul09/deep-drum/blob/master/js/tonal.js"
click node_reverse_midi "https://github.com/gogul09/deep-drum/blob/master/js/reverse_midi_map.js"
click node_timeline "https://github.com/gogul09/deep-drum/blob/master/js/timeline.js"
click node_tone "https://github.com/gogul09/deep-drum/blob/master/js/tone.js"
click node_piano_samples "https://github.com/gogul09/deep-drum/blob/master/sounds/salamander/C4.mp3"
click node_guitar_samples "https://github.com/gogul09/deep-drum/blob/master/sounds/acoustic_guitar/A3.wav"
click node_drum_samples "https://github.com/gogul09/deep-drum/blob/master/sounds/drum-kits/analog/kick.mp3"

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_page,node_materialize_css,node_materialize_js,node_nexus toneBlue
class node_control_updates,node_multiple_tags,node_gpad toneAmber
class node_drum_generator,node_chord_finder,node_arp_bass toneMint
class node_tonal,node_reverse_midi,node_timeline toneRose
class node_tone,node_piano_samples,node_guitar_samples,node_drum_samples toneIndigo
```

## Components

### Browser UI

- [App entry page](https://github.com/gogul09/deep-drum/blob/master/index.html): HTML entry · Loads the browser application and its client-side modules. · `index.html`
- [Materialize styles](https://github.com/gogul09/deep-drum/blob/master/externals/css/materialize.css): UI framework · `externals/css/materialize.css`
- [Materialize controls](https://github.com/gogul09/deep-drum/blob/master/externals/js/materialize.js): UI framework · `externals/js/materialize.js`
- [Nexus music widgets](https://github.com/gogul09/deep-drum/blob/master/js/nexus.js): control widgets · `js/nexus.js`

### Control State

- [Control updater](https://github.com/gogul09/deep-drum/blob/master/js/update_controls.js): state coordinator · Propagates musical and playback control changes. · `js/update_controls.js`
- [Multi-select tags](https://github.com/gogul09/deep-drum/blob/master/js/multiple_tag.js): selection behavior · `js/multiple_tag.js`
- [Gesture pad](https://github.com/gogul09/deep-drum/blob/master/js/gpad.js): input control · `js/gpad.js`

### Music Generation

- [DrumsRNN integration](https://github.com/gogul09/deep-drum/blob/master/js/deepdrum.js): drum generation · Generates continuous drum patterns from seeded rhythms. · `js/deepdrum.js`
- [Chord finder](https://github.com/gogul09/deep-drum/blob/master/js/chord_finder.js): harmony analysis · Supplies chord context for generated parts. · `js/chord_finder.js`
- [Arpeggio & bass generator](https://github.com/gogul09/deep-drum/blob/master/js/arp_and_bass.js): note generation · Generates chord-conditioned arpeggio and bass patterns. · `js/arp_and_bass.js`

### Representation & Scheduling

- [Music theory utilities](https://github.com/gogul09/deep-drum/blob/master/js/tonal.js): tonal mapping · `js/tonal.js`
- [MIDI pitch mapping](https://github.com/gogul09/deep-drum/blob/master/js/reverse_midi_map.js): note mapping · `js/reverse_midi_map.js`
- [Timeline scheduler](https://github.com/gogul09/deep-drum/blob/master/js/timeline.js): symbolic sequencer · Places generated notes and drums onto playback time. · `js/timeline.js`

### Audio Playback

- [Tone.js engine](https://github.com/gogul09/deep-drum/blob/master/js/tone.js): browser audio runtime · Schedules and plays instrument voices in the browser. · `js/tone.js`
- [Piano samples](https://github.com/gogul09/deep-drum/blob/master/sounds/salamander/C4.mp3): local media · `sounds/salamander/C4.mp3`
- [Guitar samples](https://github.com/gogul09/deep-drum/blob/master/sounds/acoustic_guitar/A3.wav): local media · `sounds/acoustic_guitar/A3.wav`
- [Drum-kit samples](https://github.com/gogul09/deep-drum/blob/master/sounds/drum-kits/analog/kick.mp3): local media · `sounds/drum-kits/analog/kick.mp3`

## Connections

- App entry page → Materialize styles: styles
- App entry page → Materialize controls: loads
- App entry page → Nexus music widgets: loads
- App entry page → Control updater: initializes
- Materialize controls → Control updater: UI changes
- Nexus music widgets → Control updater: music controls
- Multi-select tags → Control updater: selections
- Gesture pad → Control updater: gestures
- Control updater → DrumsRNN integration: seed and settings
- Control updater → Chord finder: input notes
- Control updater → Arpeggio & bass generator: notes and settings
- Chord finder → Arpeggio & bass generator: chord context
- DrumsRNN integration → Timeline scheduler: drum events
- Arpeggio & bass generator → Music theory utilities: generated notes
- Music theory utilities → MIDI pitch mapping: resolved pitches
- MIDI pitch mapping → Timeline scheduler: playable events
- Timeline scheduler → Tone.js engine: scheduled playback
- Tone.js engine → Piano samples: loads
- Tone.js engine → Guitar samples: loads
- Tone.js engine → Drum-kit samples: loads