# vtouchio/wizpr-ring-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/vtouchio/wizpr-ring-sdk
- Repository: https://github.com/vtouchio/wizpr-ring-sdk

## Overview

WizprRingSDK is a cross-platform Rust SDK for discovering WIZPR Rings, connecting over BLE, and delivering decoded audio and ring events. The principal workflow is application scan → candidate selection → connection → notification dispatch → audio/event channels. The portable core also provides ADPCM decoding, optional audio cleanup, protocol constants, and WAV serialization; the README documents a desktop capture example and host-managed input locking. Some connection internals and the desktop example were not sampled, so uncertain wiring is omitted.

Main entry points: [`crates/wizpr-ring/src/scanner.rs`](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/scanner.rs) (Ring scanner), [`crates/wizpr-ring/src/connection.rs`](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs) (Ring connection), [`examples/desktop/src/main.rs`](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/examples/desktop/src/main.rs) (Desktop capture), [`crates/wizpr-ring-core/src/processing.rs`](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/processing.rs) (Audio processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Device discovery"]
  node_scanner["Ring scanner<br/>[scanner.rs]"]
  node_candidate["Ring candidate<br/>[scanner.rs]"]
end

subgraph group_transport["BLE transport"]
  node_connection["Ring connection<br/>[connection.rs]"]
  node_dispatcher["Notification dispatcher<br/>[connection.rs]"]
  node_audio_channel["Audio channel<br/>[connection.rs]"]
  node_event_channel["Event channel<br/>[connection.rs]"]
end

subgraph group_core["Portable core"]
  node_protocol["BLE protocol constants<br/>[constants.rs]"]
  node_codec["IMA ADPCM codec<br/>[codec.rs]"]
  node_processing["Audio processing<br/>[processing.rs]"]
  node_audio_types["Audio chunks<br/>[audio.rs]"]
  node_event_parser["Ring event parser<br/>[events.rs]"]
  node_wav["WAV writer<br/>[audio.rs]"]
end

subgraph group_app["Application integration"]
  node_desktop["Desktop capture<br/>[main.rs]"]
  node_recordings["WAV recordings"]
end

node_application(("Application"))
node_ble["Bluetooth adapter"]

node_application -->|"scans for rings"| node_scanner
node_scanner -->|"scans through"| node_ble
node_scanner -->|"returns candidates"| node_candidate
node_application -->|"selects candidate"| node_candidate
node_candidate -->|"connects"| node_connection
node_connection -->|"connects and subscribes"| node_ble
node_connection -->|"starts"| node_dispatcher
node_dispatcher -->|"sends chunks"| node_audio_channel
node_dispatcher -->|"sends events"| node_event_channel
node_processing -->|"decodes with"| node_codec
node_application -->|"receives audio"| node_audio_channel
node_application -->|"receives events"| node_event_channel
node_application -->|"selects cleanup mode"| node_processing
node_desktop -.->|"scans and connects"| node_scanner
node_desktop -->|"saves recordings"| node_wav
node_wav -->|"writes WAV"| node_recordings
node_application -->|"requests input lock"| node_connection

click node_scanner "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/scanner.rs"
click node_candidate "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/scanner.rs"
click node_connection "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs"
click node_dispatcher "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs"
click node_audio_channel "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs"
click node_event_channel "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs"
click node_protocol "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/constants.rs"
click node_codec "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/codec.rs"
click node_processing "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/processing.rs"
click node_audio_types "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/audio.rs"
click node_event_parser "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/events.rs"
click node_wav "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/audio.rs"
click node_desktop "https://github.com/vtouchio/wizpr-ring-sdk/blob/main/examples/desktop/src/main.rs"

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_scanner,node_candidate toneBlue
class node_connection,node_dispatcher,node_audio_channel,node_event_channel toneAmber
class node_protocol,node_codec,node_processing,node_audio_types,node_event_parser,node_wav toneMint
class node_desktop,node_recordings toneRose
class node_application,node_ble toneIndigo
```

## Components

### Device discovery

- [Ring scanner](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/scanner.rs): `crates/wizpr-ring/src/scanner.rs`
- [Ring candidate](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/scanner.rs): `crates/wizpr-ring/src/scanner.rs`

### BLE transport

- [Ring connection](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs): `crates/wizpr-ring/src/connection.rs`
- [Notification dispatcher](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs): `crates/wizpr-ring/src/connection.rs`
- [Audio channel](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs): `crates/wizpr-ring/src/connection.rs`
- [Event channel](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring/src/connection.rs): `crates/wizpr-ring/src/connection.rs`

### Portable core

- [BLE protocol constants](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/constants.rs): `crates/wizpr-ring-core/src/constants.rs`
- [IMA ADPCM codec](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/codec.rs): `crates/wizpr-ring-core/src/codec.rs`
- [Audio processing](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/processing.rs): `crates/wizpr-ring-core/src/processing.rs`
- [Audio chunks](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/audio.rs): `crates/wizpr-ring-core/src/audio.rs`
- [Ring event parser](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/events.rs): `crates/wizpr-ring-core/src/events.rs`
- [WAV writer](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/crates/wizpr-ring-core/src/audio.rs): `crates/wizpr-ring-core/src/audio.rs`

### Application integration

- [Desktop capture](https://github.com/vtouchio/wizpr-ring-sdk/blob/main/examples/desktop/src/main.rs): `examples/desktop/src/main.rs`
- **WAV recordings**

### Other components

- **Application**
- **Bluetooth adapter**

## Connections

- Application → Ring scanner: scans for rings (evidence: `README.md`)
- Ring scanner → Bluetooth adapter: scans through (evidence: `crates/wizpr-ring/src/scanner.rs`)
- Ring scanner → Ring candidate: returns candidates (evidence: `crates/wizpr-ring/src/scanner.rs`)
- Application → Ring candidate: selects candidate (evidence: `README.md`)
- Ring candidate → Ring connection: connects (evidence: `crates/wizpr-ring/src/scanner.rs`)
- Ring connection → Bluetooth adapter: connects and subscribes (evidence: `crates/wizpr-ring/src/connection.rs`)
- Ring connection → Notification dispatcher: starts (evidence: `crates/wizpr-ring/src/connection.rs`)
- Notification dispatcher → Audio channel: sends chunks (evidence: `crates/wizpr-ring/src/connection.rs`)
- Notification dispatcher → Event channel: sends events (evidence: `crates/wizpr-ring/src/connection.rs`)
- Audio processing → IMA ADPCM codec: decodes with (evidence: `crates/wizpr-ring-core/src/processing.rs`)
- Application → Audio channel: receives audio (evidence: `README.md`)
- Application → Event channel: receives events (evidence: `README.md`)
- Application → Audio processing: selects cleanup mode (evidence: `README.md`)
- Desktop capture → Ring scanner: scans and connects
- Desktop capture → WAV writer: saves recordings (evidence: `README.md`)
- WAV writer → WAV recordings: writes WAV (evidence: `crates/wizpr-ring-core/src/audio.rs`)
- Application → Ring connection: requests input lock (evidence: `README.md`)