# tolgaozuygur/speech_jammer architecture

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

- Interactive diagram: https://gitdiagram.com/tolgaozuygur/speech_jammer
- Repository: https://github.com/tolgaozuygur/speech_jammer

## Overview

This repository provides delayed auditory feedback (DAF) speech jammers: a Raspberry Pi version controlled by a Bluetooth gamepad, plus separate Ubuntu and Windows desktop alternatives. The Pi workflow detects the controller, responds to button events by starting or stopping delayed audio, and supports a held-button shutdown; its LED signals status. Desktop versions use either terminal input with ALSA loopback or a sounddevice callback stream. The README documents Raspberry Pi hardware and startup use; wiring beyond the sampled source is not assumed.

Main entry points: [`speech_jammer.py`](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py) (Gamepad event loop), [`for_desktop/speech_jammer_ubuntu.py`](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_ubuntu.py) (Ubuntu terminal loop), [`for_desktop/speech_jammer_win.py`](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_win.py) (Windows stream control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pi["Raspberry Pi"]
  node_pi_main["Pi entry and setup<br/>[speech_jammer.py]"]
  node_pi_discovery["Controller discovery<br/>[speech_jammer.py]"]
  node_pi_events["Gamepad event loop<br/>[speech_jammer.py]"]
  node_pi_audio["Delayed audio control<br/>[speech_jammer.py]"]
  node_pi_shutdown["Safe shutdown<br/>[speech_jammer.py]"]
end

subgraph group_desktop["Desktop alternatives"]
  node_ubuntu_cli["Ubuntu terminal loop"]
  node_ubuntu_audio["Ubuntu loopback control"]
  node_windows_main["Windows stream control"]
  node_windows_callback["Audio pass-through"]
end

subgraph group_io["Audio and controls"]
end

node_user(("User"))
node_controller["Bluetooth gamepad"]
node_gpio["Status LED"]
node_alsa_pi["ALSA loopback"]
node_shutdown_service["System shutdown"]
node_alsa_desktop["ALSA loopback"]
node_sounddevice["Sounddevice audio stream"]

node_user -->|"starts"| node_pi_main
node_pi_main -->|"calls"| node_pi_discovery
node_pi_discovery -->|"scans devices"| node_controller
node_pi_discovery -->|"blinks while waiting"| node_gpio
node_pi_discovery -->|"starts on connect"| node_pi_events
node_controller -->|"sends events"| node_pi_events
node_pi_events -->|"toggles on button"| node_pi_audio
node_pi_audio -->|"starts or terminates"| node_alsa_pi
node_pi_events -->|"sets status"| node_gpio
node_pi_events -->|"checks held buttons"| node_pi_shutdown
node_pi_shutdown -->|"flashes before shutdown"| node_gpio
node_pi_shutdown -->|"invokes"| node_shutdown_service
node_user -->|"enters commands"| node_ubuntu_cli
node_ubuntu_cli -->|"toggles on input"| node_ubuntu_audio
node_ubuntu_audio -->|"starts or terminates"| node_alsa_desktop
node_user -->|"enters commands"| node_windows_main
node_windows_main -->|"opens stream"| node_sounddevice
node_sounddevice -->|"invokes"| node_windows_callback
node_windows_callback -->|"passes audio through"| node_sounddevice

click node_pi_main "https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py"
click node_pi_discovery "https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py"
click node_pi_events "https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py"
click node_pi_audio "https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py"
click node_pi_shutdown "https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py"
click node_ubuntu_cli "https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_ubuntu.py"
click node_ubuntu_audio "https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_ubuntu.py"
click node_windows_main "https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_win.py"
click node_windows_callback "https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_win.py"

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_pi_main,node_pi_discovery,node_pi_events,node_pi_audio,node_pi_shutdown,node_user toneBlue
class node_ubuntu_cli,node_ubuntu_audio,node_windows_main,node_windows_callback toneAmber
class node_controller,node_gpio,node_alsa_pi,node_shutdown_service,node_alsa_desktop,node_sounddevice toneIndigo
```

## Components

### Raspberry Pi

- [Pi entry and setup](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py): `speech_jammer.py`
- [Controller discovery](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py): `speech_jammer.py`
- [Gamepad event loop](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py): `speech_jammer.py`
- [Delayed audio control](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py): `speech_jammer.py`
- [Safe shutdown](https://github.com/tolgaozuygur/speech_jammer/blob/main/speech_jammer.py): `speech_jammer.py`

### Desktop alternatives

- [Ubuntu terminal loop](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_ubuntu.py): `for_desktop/speech_jammer_ubuntu.py`
- [Ubuntu loopback control](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_ubuntu.py): `for_desktop/speech_jammer_ubuntu.py`
- [Windows stream control](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_win.py): `for_desktop/speech_jammer_win.py`
- [Audio pass-through](https://github.com/tolgaozuygur/speech_jammer/blob/main/for_desktop/speech_jammer_win.py): `for_desktop/speech_jammer_win.py`

### Other components

- **User**
- **Bluetooth gamepad**
- **Status LED**
- **ALSA loopback**
- **System shutdown**
- **ALSA loopback**
- **Sounddevice audio stream**

## Connections

- User → Pi entry and setup: starts
- Pi entry and setup → Controller discovery: calls
- Controller discovery → Bluetooth gamepad: scans devices
- Controller discovery → Status LED: blinks while waiting
- Controller discovery → Gamepad event loop: starts on connect
- Bluetooth gamepad → Gamepad event loop: sends events
- Gamepad event loop → Delayed audio control: toggles on button
- Delayed audio control → ALSA loopback: starts or terminates
- Gamepad event loop → Status LED: sets status
- Gamepad event loop → Safe shutdown: checks held buttons
- Safe shutdown → Status LED: flashes before shutdown
- Safe shutdown → System shutdown: invokes
- User → Ubuntu terminal loop: enters commands
- Ubuntu terminal loop → Ubuntu loopback control: toggles on input
- Ubuntu loopback control → ALSA loopback: starts or terminates
- User → Windows stream control: enters commands
- Windows stream control → Sounddevice audio stream: opens stream
- Sounddevice audio stream → Audio pass-through: invokes
- Audio pass-through → Sounddevice audio stream: passes audio through