From 8985b849e67cba19fa1e783545c714407d8ad422 Mon Sep 17 00:00:00 2001
From: Hayleigh Thompson <me@hayleigh.dev>
Date: Thu, 20 Aug 2026 21:34:28 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20a=20basic=20readme.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/README.md b/README.md
index ea6c095..e497929 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,57 @@
 # beep
+
+Say (or sing) hi to beep! Beep is a friendly little library for making sounds with
+the Web Audio API. Similar to how frontend libraries like Lustre or React provide
+a declarative wrapper around low-level DOM APIs, beep makes it simple to describe
+audio processing graphs and handles the hard work of making it real under the
+hood.
+
+Let's make some sound:
+
+```gleam
+import beep
+import beep/param
+import gleam/javascript/promise
+
+pub fn main() {
+  let engine = beep.new()
+  let graph = [
+    beep.oscillator([param.frequency(220.0)], [
+      beep.gain([param.gain(0.2)], [
+        beep.destination(),
+      ]),
+    ])
+  ]
+
+  use _ <- promise.await(beep.start(engine))
+
+  beep.commit(engine, graph)
+}
+```
+
+> **Note**: while this example shows off the basic api, you might find it doesn't
+> work if you run it in the browser. That's because adtech stops us having nice
+> things. In most modern browsers, an audio context (or a `beep.AudioEngine`) can
+> only be started in response to a direct user interaction like a button click.
+
+Hey that wasn't so bad! Notice how the structure of graph dictates the connections
+between nodes. For comparison, here's the equivalent code in vanilla JavaScript
+working directly with the Web Audio API:
+
+```javascript
+async function main() {
+  const context = new AudioContext()
+
+  const oscillator = context.createOscillator()
+  oscillator.frequency.value = 220
+
+  const gain = context.createGain()
+  gain.gain.value = 0.2
+
+  await context.start()
+
+  oscillator.start()
+  oscillator.connect(gain)
+  gain.connect(context.destination)
+}
+```
-- 
2.51.2