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)
+}
+```