From 40a95b4d0a0ff4d540ac8eb2543c396e7ea22e3a Mon Sep 17 00:00:00 2001 From: alemi Date: Wed, 28 Feb 2024 18:03:47 +0100 Subject: [PATCH] docs: add readme --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e525acf --- /dev/null +++ b/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": }` 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.