-
Notifications
You must be signed in to change notification settings - Fork 80
Developer Documentation
This page explains how the network remote works.
When enabling the network remote, Clementine opens a TCP server socket on port 5500 (can be changed in the settings). It listens for incoming connections and checks their validity. If Clementine refuses non private ips, it drops the connection without any response.
The communication between Clementine and its clients works via protocol buffers. Info on protocol buffer: https://github.com/google/protobuf
You can find the protocol buffer file here: ext/libclementine-remote/remotecontrolmessages.proto
Packets have the following structure :
+----------------+------------------------------------------------+
| Packet length | Payload (message) |
+----------------+------------------------------------------------+
Packet length is a 32 bits Big Endian Unsigned Integer that determines the payload size.
All send and received messages must contain the message "Message" with a messagetype, that is defined on the top of the file and the default protocol buffer file version. Most messages have a seperate type specific message inside "Message". When sending / receiving you have to fill / parse it.
After the client connected to Clementine, it has to send a CONNECT message with the optional authentication code. If Clementine requires an auth code, Clementine will drop the client if any other messages are received with a DISCONNECT message which includes the reason.
Once the connect message was received, Clementine sends "first data" to the client. This contains the current track, all playlists, current volume, repeat and shuffe mode and, if in the connect message requested, all song metadata from all playlists.
You can control Clementine by sending "Message" with the control types like PLAY, PAUSE, STOP, LOVE, BAN, change track / playlist, etc. Clementine will execute the command immediatly.
Clementine will send the song metadata of the currenly played song after a track starts. If something changes, like volume, playlist songs, playlists, shuffle mode, repeat mode, it sends the change directly to the clients. You don't have to request a state, Clementine informs all clients directly.
Clementine sends every 10 seconds a keep alive message. Use this to determine if the connection is lost.
When Clementine closes, it sends a DISCONNECT message to all clients.
If the client want to disconnect, it should send a DISCONNECT message to the client, too.
Each protocol buffer message must include a version number. It has a default tag and need to be filled from the default protocol buffer instance:
msg->set_version(msg->default_instance().version());
Protocol buffers are backwards compatible, but newer features might not work with an older protocol buffer file version. Those messages are normally ignored and should not cause misbehaviour in your client application.