ivabus/lonelyradio
1
0
Fork 0
mirror of https://github.com/ivabus/lonelyradio synced 2024-11-24 09:05:09 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add basic protocol documentation

Browse source 
Signed-off-by: Ivan Bushchik <ivabus@ivabus.dev>
This commit is contained in:
Ivan Bushchik 2024-08-27 12:21:35 +03:00
parent d43dcde7a2
commit dfb86522fb
No known key found for this signature in database
GPG key ID: 2F16FBF3262E090C
2 changed files with 66 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -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

65
docs/protocol.md Normal file
View file

@ -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
}
]
}
```