From 326ae9da1b736688450a4a023c5985d0a5cd2957 Mon Sep 17 00:00:00 2001
From: Michael Winter <mwinter@unboundedpress.org>
Date: Fri, 20 Mar 2026 06:58:00 +0100
Subject: [PATCH] Add OSC Sender documentation to README

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/README.md b/README.md
index e0eb861..5b12ccb 100644
--- a/README.md
+++ b/README.md
@@ -128,3 +128,51 @@ Generated files go to `output/`:
 - `output_chords.txt` - Human-readable chords
 - `output_frequencies.txt` - Frequencies in Hz
 - `graph_path.json` - Hashes of graph nodes visited (for DCA Hamiltonian analysis)
+
+## OSC Sender
+
+The OSC sender allows real-time playback of generated chords via OSC messages.
+
+### Usage
+
+```bash
+# Direct usage
+python src/osc_sender.py
+
+# Via compact_sets.py (playback only)
+python compact_sets.py --osc-play
+
+# Generate and then playback
+python compact_sets.py --osc-play --osc-ip 192.168.4.200 --osc-port 54001
+```
+
+### Options
+
+--osc-play FILE       Enable OSC playback (default: output/output_chords.json)
+--osc-ip IP           Destination IP address (default: 192.168.4.200)
+--osc-port PORT       Destination port (default: 54001)
+--fundamental FREQ   Fundamental frequency in Hz (default: 100 Hz)
+
+### Interactive Controls
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Navigate backward/forward |
+| `p` | Toggle preview mode |
+| `Enter` | Send current chord (when not in preview mode) |
+| `[n]` + `Enter` | Jump to chord n |
+| `k` | Kill soft (15.0 Hz to all voices) |
+| `K` | Kill hard (0.0 Hz to all voices) |
+| `Escape` | Quit |
+
+### Preview Mode
+
+Preview mode ([PREVIEW]) disables sending; toggle with `p` to enable ([SEND]).
+
+### OSC Protocol
+
+Messages sent to `/freq` with: voice number (int), frequency (float).
+
+### Test Receiver
+
+For debugging, run `python src/test_receiver.py` in a separate terminal.