docs: add readme

README.md

@@ -0,0 +1,55 @@
+# mumble-stats-api
+> REST API to check who hopped on mumble before hopping yourself
+
+if you, like me, are trying to get off discord's claws, you're probably using [mumble](https://www.mumble.info/)
+
+mumble is open source, low-latency, encrypted and *cool*, but you need to download the native client to check who's up
+
+[mumble-web](https://github.com/Johni0702/mumble-web) is an awesome project which allows you to join from a web browser (like discord!), but you still need to *join* to check who's currently on
+
+## api to the rescue
+introducing **mumble-stats-api**: a persistent mumble bot which will expose current users on a public API endpoint:
+
+`$ curl https://example/net/mumble/api/ping?host=your.mumble.server`
+```
+{
+	"version":"1.5.255",
+	"users": 1,
+	"max_users": 50,
+	"bandwidth": 128000,
+	"latency": 42
+}
+```
+
+---
+
+`$ curl https://example.net/mumble/api/users`
+```
+[
+	{
+		"session": 33,
+		"actor": 33,
+		"name": "your_username",
+		"user_id": 1,
+		"channel_id": 16,
+		"comment": "optional user comment",
+		"properties": {
+			"mute": false,
+			"deaf": false,
+			"suppress": false,
+			"self_mute": true,
+			"self_deaf": false,
+			"priority_speaker": false,
+			"recording": false
+		}
+	}
+]
+```
+
+## live updates
+**mumble-stats-api** also exposes a websocket endpoint on `/ws`, to receive realtime events about users:
+ * every time an user is updated, the whole entity is sent as an event
+ * every time an user leaves the server, an object with `{"remove": <id>}` is sent
+
+## how it works
+basically it connects to your server (as bot so it doesn't increase the user count) and sits in any channel (move it freely). it only uses the control channel, no voice is sent or parsed ever.