From dfb86522fba75ea781485a662433ef9d32839001 Mon Sep 17 00:00:00 2001
From: Ivan Bushchik <ivabus@ivabus.dev>
Date: Tue, 27 Aug 2024 12:21:35 +0300
Subject: [PATCH] Add basic protocol documentation

Signed-off-by: Ivan Bushchik <ivabus@ivabus.dev>
---
 README.md        |  2 +-
 docs/protocol.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/protocol.md

diff --git a/README.md b/README.md
index 8439e90..ac9c1f5 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,7 @@ Look into `--help` for detailed info on usage.
 
 [monolib](./monolib) provides a C API compatible with lonelyradio for creating custom clients.
 
-The full protocol specification will be available later. If you would like to learn more about it now, please refer to the monolib.
+[Protocol documentation] shortly describes the protocol used in lonelyradio. Please refer to monolib and verify custom clients with the reference lonelyradio server.
 
 #### monolib API stability
 
diff --git a/docs/protocol.md b/docs/protocol.md
new file mode 100644
index 0000000..dd4d0f1
--- /dev/null
+++ b/docs/protocol.md
@@ -0,0 +1,65 @@
+# lonelyradio protocol (0.7)
+
+## Introduction
+
+The lonelyradio protocol is designed to be minimal yet functional for music streaming purposes.
+
+The lonelyradio protocol operates at the application layer, establishing communication between the server and client. In its reference implementation, it runs atop the TCP protocol, but it could also be implemented on top of any other transport protocol, such as UDP, WebSocket, and so on.
+
+The lonelyradio protocol uses [MessagePack](https://msgpack.org) to encode messages. Structures used in communication are defined in the `lonelyradio_types` crate.
+
+## Establishing connection
+
+1. The client sends a «hello» packet («lonelyra», 8 bytes)
+    1. The server checks the hello packet
+2. The server sends «ServerCapabilities» which informs the client about supported audio encoders (raw pcm s16le must be supported by all server implementations)
+3. Then the client picks one of the requests:
+    1. Play (p) (see example 1.1)
+    2. ListPlaylist (lpl) (see example 1.2)
+    3. PlayPlayList (ppl) (see example 1.3)
+4. The server responds with one of RequestResult
+    1. Ok -> The server begins sending PlayMessage’s
+        1. TrackMetadata indicates the start of the new track
+        2. FragmentMetadata indicates the start of a new fragment and defines the number of bytes in it
+            1. FragmentMetadata is always followed by a fragment
+    2. Playlist is only returned on ListPlaylist and shows available playlists
+    3. Error indicates an error
+
+To get «next track» just reestablish the connection.
+
+## Examples
+
+Examples show JSON representation of MessagePack
+
+### 1.1
+
+```json
+{
+  "p": { // e and co definicions could be found in	lonelyradio_types crate
+    "e": "Pcm16",
+    "co": -1
+  }
+}
+```
+
+### 1.2
+
+Just string encoded to MessagePack
+
+```json
+"lpl"
+```
+
+### 1.3
+
+```json
+{
+  "ppl": [
+    "someplaylist",
+    {
+      "e": "Pcm16",
+      "co": -1
+    }
+  ]
+}
+```