# 24f3002840/spank-mic architecture
> Architecture diagram of the GitHub repository 24f3002840/spank-mic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/24f3002840/spank-mic
- Repository: https://github.com/24f3002840/spank-mic
## Overview
1. **Overall shape**
- This repository is a small, single-binary Go application (`main.go`) plus bundled MP3 assets.
- The runtime behavior is local and event-driven: listen to the microphone, detect a transient “slap-like” sound, then play a response sound.
2. **Primary entrypoint**
- `main.go` is the only code entrypoint visible in the tree, so the app is likely organized as one CLI process rather than multiple packages or services.
- The README shows the binary is launched directly from the terminal and controlled entirely by flags.
3. **Input subsystem: microphone capture**
- The key architectural change from the upstream project is that input comes from the Mac microphone instead of accelerometer/IOKit sensing.
- PortAudio is the external runtime dependency that provides cross-device audio input on macOS; this is why the project requires `brew install portaudio`.
- The data stream is therefore raw audio samples flowing from the microphone into the detection logic.
4. **Detection subsystem: transient sound analysis**
- The app listens for loud, short-lived audio spikes such as slaps, knocks, or claps.
- The README describes an adaptive noise floor and RMS/peak transient detection, so the detector likely maintains a moving baseline and compares current amplitude against it.
- This is the core decision boundary: sample stream in, “trigger” event out.
5. **Response subsystem: audio playback**
- When a trigger is detected, the program plays a response MP3.
- Playback is local and file-based; there is no remote service or network dependency in the architecture.
- The audio response path is separate from detection: one subsystem senses events, another chooses and plays sounds.
6. **Sound library layout**
- The `audio/` directory is the content layer for responses.
- Each subdirectory represents a response mode or sound pack:
- `audio/pain/` for default “ow” style reactions
- `audio/sexy/` for escalating responses
- `audio/halo/` for Halo-style death sounds
- `audio/lizard/` for a minimal/custom variant with a single clip
- This is an asset boundary, not logic; the code likely enumerates files in these folders and selects among them.
7. **Mode selection and escalation**
- The README exposes CLI modes such as default, `--sexy`, `--halo`, `--fast`, `--volume-scaling`, and `-c` for custom sounds.
- Architecturally, this implies a configuration layer that selects a sound pack, sensitivity profile, cooldown timing, and optional intensity-based behavior.
- “Sexy” mode appears to use repeated detections as a state signal, escalating the response over time rather than treating every event identically.
8. **Configuration boundaries**
- User-controlled parameters appear to be handled through command-line flags rather than config files or a server API.
- Important runtime controls include sensitivity (`--min-amplitude`), cooldown/response pacing (`--fast`), and volume behavior (`--volume-scaling`).
- This means the application’s external surface area is the CLI, not a UI or network interface.
9. **Platform and system dependency**
- The project is explicitly macOS-oriented.
- Its main native dependency is PortAudio; there is no indication of a database, daemon, or cloud integration.
- The absence of sudo in the README is architecturally important: the microphone-based design removes the privileged system boundary that the original accelerometer approach needed.
10. **Repository content vs runtime code**
- Most of the repository is static media assets, not source code.
- `go.mod` and `go.sum` show a standard Go module layout, but the functional logic appears concentrated in one file.
- `blog-复盘.md` is documentation/postmortem content and does not appear to participate in the runtime path.
11. **End-to-end data flow**
- Microphone input is sampled through PortAudio.
- The detector computes loudness/transient features and updates an adaptive noise baseline.
- A trigger event selects a sound from the active pack.
- The selected MP3 is played locally through the audio output path.
- Optional mode logic changes which pack is used and how the selection/volume/cooldown behaves.
12. **Diagram-friendly summary**
- The architecture is best drawn as one local CLI process with four logical blocks: audio input, signal detection, response selection, and MP3 playback.
- External boundaries are limited to macOS microphone hardware, PortAudio, and the local filesystem holding bundled sound assets.
Main entry points: [`main.go`](https://github.com/24f3002840/spank-mic/blob/main/main.go) (CLI app), [`README.md`](https://github.com/24f3002840/spank-mic/blob/main/README.md) (Flags), [`audio/pain`](https://github.com/24f3002840/spank-mic/tree/main/audio/pain) (Pain pack), [`audio/sexy`](https://github.com/24f3002840/spank-mic/tree/main/audio/sexy) (Sexy pack)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_runtime["Runtime"]
node_main["CLI app
Go binary
[main.go]"]
node_flags["Flags
CLI config
[README.md]"]
node_capture["Mic capture
audio input"]
node_samples["Sample stream
PCM data"]
node_noise{{"Noise floor
baseline"}}
node_detect{{"Transient detect
signal analysis"}}
node_trigger(("Trigger event"))
node_mode{{"Mode logic
policy"}}
node_pack["Sound pack
asset selector"]
node_playlist{{"Clip choice
selection"}}
node_playback["Playback
audio output"]
end
subgraph group_assets["Audio Assets"]
node_pain["Pain pack
asset pack"]
node_sexy["Sexy pack
asset pack"]
node_halo["Halo pack
asset pack"]
node_lizard["Lizard pack
asset pack"]
end
subgraph group_external["External Dependencies"]
node_portaudio["PortAudio
native audio lib"]
node_fs[("Filesystem
local storage")]
end
node_main -->|"parses"| node_flags
node_main -->|"starts"| node_capture
node_capture -->|"uses"| node_portaudio
node_capture -->|"emits"| node_samples
node_samples -->|"updates"| node_noise
node_samples -->|"analyzes"| node_detect
node_noise -->|"thresholds"| node_detect
node_detect -->|"fires"| node_trigger
node_flags -->|"configures"| node_mode
node_trigger -->|"routes"| node_mode
node_mode -->|"selects"| node_pack
node_pack -->|"defaults to"| node_pain
node_pack -->|"may choose"| node_sexy
node_pack -->|"may choose"| node_halo
node_pack -->|"may choose"| node_lizard
node_pack -->|"enumerates"| node_playlist
node_playlist -->|"reads"| node_fs
node_playlist -->|"sends"| node_playback
node_playback -->|"streams from"| node_fs
node_main -->|"orchestrates"| node_playback
click node_main "https://github.com/24f3002840/spank-mic/blob/main/main.go"
click node_flags "https://github.com/24f3002840/spank-mic/blob/main/README.md"
click node_pain "https://github.com/24f3002840/spank-mic/tree/main/audio/pain"
click node_sexy "https://github.com/24f3002840/spank-mic/tree/main/audio/sexy"
click node_halo "https://github.com/24f3002840/spank-mic/tree/main/audio/halo"
click node_lizard "https://github.com/24f3002840/spank-mic/tree/main/audio/lizard"
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_main,node_flags,node_capture,node_samples,node_noise,node_detect,node_trigger,node_mode,node_pack,node_playlist,node_playback toneBlue
class node_pain,node_sexy,node_halo,node_lizard toneAmber
class node_portaudio,node_fs toneMint
```
## Components
### Runtime
Single Go CLI process and its internal stages
- [CLI app](https://github.com/24f3002840/spank-mic/blob/main/main.go): Go binary · Single-process entrypoint that wires flags, capture, detection, and playback · `main.go`
- [Flags](https://github.com/24f3002840/spank-mic/blob/main/README.md): CLI config · Command-line controls for mode, sensitivity, cooldown, and volume behavior · `README.md`
- **Mic capture**: audio input · Reads raw microphone samples as the input stream
- **Sample stream**: PCM data · Continuous audio frames flowing from capture into analysis
- **Noise floor**: baseline · Adaptive background level used to ignore ambient sound
- **Transient detect**: signal analysis · Computes loudness and peak/RMS spikes to identify slap-like events
- **Trigger event**: event · Detection output that starts response selection and playback
- **Mode logic**: policy · Chooses default, sexy, halo, fast, or custom response behavior
- **Sound pack**: asset selector · Resolves which audio folder and clip set to use for the active mode
- **Clip choice**: selection · Picks a specific MP3 from the selected pack, possibly with escalation
- **Playback**: audio output · Plays the chosen response sound locally
### Audio Assets
Bundled response sound packs on disk
- [Pain pack](https://github.com/24f3002840/spank-mic/tree/main/audio/pain): asset pack · Default ow/ouch response clips · `audio/pain`
- [Sexy pack](https://github.com/24f3002840/spank-mic/tree/main/audio/sexy): asset pack · Escalating response clips for repeated triggers · `audio/sexy`
- [Halo pack](https://github.com/24f3002840/spank-mic/tree/main/audio/halo): asset pack · Halo-style death sound clips · `audio/halo`
- [Lizard pack](https://github.com/24f3002840/spank-mic/tree/main/audio/lizard): asset pack · Minimal custom response clip set · `audio/lizard`
### External Dependencies
Platform and library boundaries
- **PortAudio**: native audio lib · Cross-platform audio input backend used for microphone access
- **Filesystem**: local storage · Reads bundled MP3 files from the repository tree
## Connections
- CLI app → Flags: parses · Loads CLI options before runtime starts
- CLI app → Mic capture: starts · Initializes microphone listening
- Mic capture → PortAudio: uses · Delegates device I/O to PortAudio
- Mic capture → Sample stream: emits · Produces the raw audio stream
- Sample stream → Noise floor: updates · Feeds adaptive baseline tracking
- Sample stream → Transient detect: analyzes · Computes amplitude and transient features
- Noise floor → Transient detect: thresholds · Provides background level for trigger decisions
- Transient detect → Trigger event: fires · Emits an event when a slap-like spike is found
- Flags → Mode logic: configures · Selects sensitivity and response policy
- Trigger event → Mode logic: routes · Hands detection events to mode-specific logic
- Mode logic → Sound pack: selects · Chooses the active response pack
- Sound pack → Pain pack: defaults to · Uses pain pack for standard reactions
- Sound pack → Sexy pack: may choose · Uses escalating sexy pack when enabled
- Sound pack → Halo pack: may choose · Uses Halo pack when enabled
- Sound pack → Lizard pack: may choose · Uses custom lizard pack when enabled
- Sound pack → Clip choice: enumerates · Exposes the clips available in the selected folder
- Clip choice → Filesystem: reads · Loads the chosen MP3 from local disk
- Clip choice → Playback: sends · Hands off the selected clip for output
- Playback → Filesystem: streams from · Consumes audio assets from the filesystem
- CLI app → Playback: orchestrates · Coordinates end-to-end event handling and response playback