1 files changed, 54 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..92f8291
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# Beeps
+
+A program for generating soundtracks of recurrent beeps.
+
+## Beeps
+
+The following beeps can be heard:
+
+* Pairs of recurring beeps every 15 seconds. A high pitch beep immediately
+  followed by a low pitch beep marks the transition to a 15 second period filled
+  with 3 second interval beeps. A low pitch beep immediately followed by a high
+  pitch beep marks the transition to a 15 second period of silence.
+* Beeps at 3 second intervals only heard during every other 15 second interval
+  starting with the first interval.
+* Double chirps at 5 minute intervals overlapping with the period transition
+  beeps.
+* A final set of wind-down beeps at the end of the specified duration.
+
+This is useful if you have a task you need to repeatedly do for the duration of
+15 seconds at a rate of one every 3 seconds with breaks of 15 seconds to do a
+different task. For example some kind of physical exercise.
+
+The 5 minute chirps help track progress through the track.
+
+The final wind-down beeps let you know when you should stop.
+
+## Usage
+
+Run `beeps 300` for a roughly 5 minute track (additional time required for
+initial beep and wind-down beeps). The program will output a 8 bit unsigned 8kHz
+PCM track. This can be piped directly into a program like `aplay` or converted
+into other formats.
+
+The provided `GNUMakefile` (which depends on GNU Make) can be used to produce
+Ogg Vorbis or MP3 files containing tracks of 5, 10 and 15 minute duration.
+
+## Samples
+
+* 5 minutes  
+  [Download 5m.ogg (60KiB)][5m.ogg]  
+  [Download 5m.mp3 (295KiB)][5m.mp3]
+* 10 minutes  
+  [Download 10m.ogg (114KiB)][10m.ogg]  
+  [Download 10m.mp3 (588KiB)][10m.mp3]
+* 15 minutes  
+  [Download 15m.ogg (168KiB)][15m.ogg]  
+  [Download 15m.mp3 (881KiB)][15m.mp3]
+
+[5m.ogg]: https://the-tk.com/files/beeps/5m.ogg
+[5m.mp3]: https://the-tk.com/files/beeps/5m.mp3
+[10m.ogg]: https://the-tk.com/files/beeps/10m.ogg
+[10m.mp3]: https://the-tk.com/files/beeps/10m.mp3
+[15m.ogg]: https://the-tk.com/files/beeps/15m.ogg
+[15m.mp3]: https://the-tk.com/files/beeps/15m.mp3