SoulSeek Protocol Documentation

Version History
Introduction
Overview
Constants
Messages
Server Messages
Peer Messages
Message Sequences

Version History

2003-01-26: Added peer messages and login sequence, had revelation about reusing existing peer socket from search result for file request, BriEnigma
2003-01-20: Initial revision, BriEnigma
CVS version ID: $Id: soulseek_protocol.html,v 1.1 2003/04/02 05:52:24 simon_mld Exp $
Mental Note: When updating this document, remember to upload the latest version to the SourceForge project documentation web page.

Introduction

The SoulSeek protocol is not officially documented anywhere. This document is the result of effort by members of the SoleSeek project team. It was pieced together by examining the Python SoulSeek source code, as well as sniffing network packets. (Hey, Nir! Please don't sue us inder the DMCA for reverse engineering the protocol!) This document should not be considered the official specification. It is our best guess at how the protocol works.

Overview

The SoulSeek protocol consists of a finite number of messages. Some of these messages are used for communicating between the client and server. Others are used for communications between a client and a peer (another client). All of these messages (with the exception of a couple of peer messages TODO:...are PeerInit and PierceFW the only exceptions?...) follow a standard format.

There are a few datatypes that the message blocks use:
(TODO: endian-ness? I always get mixed up.)

Integer 4 bytes, network byte ordering

Byte 1 byte

String an integer (4 bytes) that specifies the length of the string, followed by the string data as 8-bit characters. The string is not null-terminated.

TODO: are other datatypes used?

The standard message blocks start with an integer. This integer defines the size of the message payload--everything contained in the message, but not including the 4-bytes length. The payload starts with an integer that we shall call the message code that describes what type of message this is. The datatype and meaning of the remaining payload data is dependant on the message code. For example, the following is a very simple message, the Login message from the client to the server:

Message Length

Message Payload

4-byte-integer: 30

4-byte-integer: 1

4-byte-integer: 8

4-byte-integer: 6

4-byte-integer: 200

Message Code 1 == "Login" (4 bytes)

String, length 8 (12 bytes)

String, length 6 (10 bytes)

Version (4 bytes)

This sends a message to the server with message code 1. Since message code 1 is the Login message, the server knows to expect two strings and an integer. The fist string, we can see is of length 8 and contains the letters "JohnGalt". The second string is of length 6 and contains the letters "secret". The remaining integer is the number 200.

It is worth noting that messages with the same code may have different payloads, depending on the direction of the message: client-to-server (generally, a request) or server-to-client (generally, a response). In the above example, the message is a Login message from the client to the server. The server responds to the client with message that also has the message code 1 ("Login"), but has a different payload. Login messages originating at the server (we can think of it as a Login response message) contain a byte (1/0 for success/fail) followed by a string (a message about the results of the login or a server greeting).

Constants

The SoulSeek protocol makes use of several constants:

Status Codes
-1	Unknown
0	Offline
1	Away
2	Online
Transfer Direction
0	Download
1	Upload
TODO: There are probably more...

Messages

Jump directly to a server message: Login:1 SetWaitPort:2 GetPeerAddress:3 AddUser:5 GetUserStatus:7 SayChatroom:13 JoinRoom:14 LeaveRoom:15 UserJoinedRoom:16 UserLeftRoom:17 ConnectToPeer:18 MessageUser:22 MessageAcked:23 FileSearch:26 SetStatus:28 SharedFoldersFiles:35 GetUserStats:36 QueuedDownloads:40 PlaceInLineResponse:60 RoomAdded:62 RoomRemoved:63 RoomList:64 ExactFileSearch:65 AdminMessage:66 GlobalUserList:67 TunneledMessage:68 PrivilegedUsers:69 AddToPrivileged:91 CheckPrivileges:92 CantConnectToPeer:1001
Jump directly to a peer message: PeerInit PierceFW GetSharedFileList:4 SharedFileList:5 FileSearchResult:9 UserInfoRequest:15 UserInfoReply:16 FolderContentsRequest:36 FolderContentsResponse:37 TransferRequest:40 TransferResponse:41 PlaceholdUpload:42 QueueUpload:43 PlaceInQueue:44 UploadFailed:46 QueueFailed:50 PlaceInQueueRequest:51

Server Messages

Login:1

Client-to-Server (attempt to login)

integer	1 (Message Code)
string	Username
string	Password
integer	Version

Server-to-Client (login success/fail)

integer	1 (Message Code)
byte	success (0=fail, 1=success)
string	Login message (error message or greeting message)

SetWaitPort:2

Client-to-Server
This is sent to the server to tell it what port we are listening on.

integer	2 (Message Code)
integer	port number (generally 2234)

Server-to-Client
It is believed that SetWaitPort messages are not sent from the server to the client.

GetPeerAddress:3

Client-to-Server
This is sent to the server to ask for a peer's address (IP address and port), given the peer's username.

integer	3 (Message Code)
string	username

Server-to-Client
This is the response from the server.

integer	3 (Message Code)
string	username this address belongs to
integer	IP address
integer	port number

AddUser:5

Client-to-Server
This message is sent when you want to start monitoring the online status of a user. Once we start "watching" a user by sending this message, the server will send (TODO: is the message AddUser or GetUserStatus) messages to us whenever the user changes status (away, back, offline, etc).
Note: There also seems to be a GetPeerAddress response message returned automatically, along with the AddUser response message--even though the GetPeerAddress request was never made. Can anyone confirm this?

integer	5 (Message Code)
string	username to start watching

Server-to-Client

integer	5 (Message Code)
string	username being watching
byte	whether the user exists

GetUserStatus:7

Client-to-Server
This message is used to request a user's current status.

integer	7 (Message Code)
string	username to get status of

Server-to-client
This message is used by the server to report back to us a user's current status.

integer	7 (Message Code)
string	username this status applies to
integer	status code, see above

SayChatroom:13

Client-to-Server
This message is sent to say something in a chatroom.

integer	13 (Message Code)
string	room
string	message

Server-to-Client
Somebody said something in a chatroom we are in.

integer	13 (Message Code)
string	room
string	username
string	message

JoinRoom:14

Client-to-Server
We would like to join a chatroom.

integer	14 (Message Code)
string	room

Server-to-Client
We have joined the room. Here is a list of all the people in the room. (This could very easily be a giant set of data!)

integer	14 (Message Code)
string	room
integer	number of users in this room
string	username #1
string	username #2
: :
string	username #n
integer	number of status code intgers (should be the same as number of users in the above field)
integer	status code of username #1
integer	status code of username #2
: :
integer	status code of username #n
integer	number of statistics records (should be the same as number of users in the above field)
integer	stats record 1: avgspeed of username #1
integer	stats record 1: downloadnum of username #1
integer	stats record 1: something of username #1
integer	stats record 1: files of username #1
integer	stats record 1: dirs of username #1
integer	stats record 2: avgspeed of username #2
integer	stats record 2: downloadnum of username #2
integer	stats record 2: something of username #2
integer	stats record 2: files of username #2
integer	stats record 2: dirs of username #2
: :
integer	stats record n: avgspeed of username #n
integer	stats record n: downloadnum of username #n
integer	stats record n: something of username #n
integer	stats record n: files of username #n
integer	stats record n: dirs of username #n
integer	number of slotsfull records
integer	slotsfull field of username #1
integer	slotsfull field of username #2
: :
integer	slotsfull field of username #n

LeaveRoom:15

Client-to-Server
We would like to leave a chatroom.

integer	15 (Message Code)
string	room

Server-to-Client
Server tells us we have left the room. Note that, in theory, this could happen at any time--it may not necessarily be a response to a LeaveRoom message. It is entirely possible that the server could send this to kick you out of a room (although this author has never seen it happen).

integer	15 (Message Code)
string	room

UserJoinedRoom:16

Client-to-Server
This message is not sent from the client.

Server-to-Client
User "x" has entered chat room "y".

integer	16 (Message Code)
string	room
string	username

UserLeftRoom:17

Client-to-Server
This message is not sent from the client.

Server-to-Client
User "x" has left chat room "y".

integer	17 (Message Code)
string	room
string	username

ConnectToPeer:18

Client-to-Server If we cannot establish a direct connection to a user (for example, they are behind a firewall), we send this message to the server, which will tell the peer to connect back to us.

integer	18 (Message Code)
integer	token
string	username
string	type: "P"/"F" (see PeerInit)

Server-to-Client
If someone cannot establish a connection with us (for instance, we are behind a firewall), the server sends this message to us. We then attempt to establish a direct connection to the peer.

integer	18 (Message Code)
string	username
string	type: "P"/"F" (see PeerInit)
integer	ip address
integer	port
integer	token

MessageUser:22

Client-to-Server
Send a private chat message to a user

integer	22 (Message Code)
string	username
string	message

Server-to-Client
Somebody sent us a private chat message

integer	22 (Message Code)
integer	message ID
integer	timestamp
string	username
string	message

MessageAcked:23

Client-to-Server
Confirmation of receiving a private chat message. If we do not send it, the server will keep sending the chat phrase to us.

integer	23 (Message Code)
integer	message ID

Server-to-Client
This message is not sent from the server to the client.

FileSearch:26

Client-to-Server
We send this to the server when we want to search for something.

integer	26 (Message Code)
integer	token
string	search text

Server-to-Client The server sends this to tell us someone is searching for something.

integer	26 (Message Code)
string	username
integer	token
string	search text

SetStatus:28

Client-to-Server
Change my away/online status.

integer	28 (Message Code)
integer	new status, see above

Server-to-Client
This message is not sent from the server to the client.

SharedFoldersFiles:35

Server-to-Client
We send this to the server to tell it how many files and folders we are sharing.

integer	35 (Message Code)
integer	folder count
integer	file count

Server-to-Client
This message is not sent from the server to the client.

GetUserStats:36

Client-to-Server This message is not sent from the client to the server.

Server-to-Client
The server sends this message to us to indicate a change in a user's statistics.

integer	36 (Message Code)
string	username
integer	avgspeed
integer	downloadnum
integer	something
integer	files
integer	dirs

QueuedDownloads:40

Client-to-Server
It is unknown whether this is valid.

Server-to-Client
The server sends this to indicate if someone has download slots available.

integer	40 (Message Code)
string	username
integer	slotsfull

PlaceInLineResponse:60

Client-to-Server
Ask the server what place in line we are ...?

integer	60 (Message Code)
string	username
integer	token (token of original file request?)
integer	place (...?)

Server-to-Client The server sends this to indicate change in place in queue while we're waiting for files from the other peer.

integer	60 (Message Code)
string	username
integer	token (token of original file request?)
integer	place

RoomAdded:62

Client-to-Server
Unknown if this is valid.

Server-to-Client
The server tells us a new room has been added

integer	62 (Message Code)
string	room name

RoomRemoved:63

Client-to-Server
Unknown if this is valid.

Server-to-Client
The server tells us a room has been removed

integer	62 (Message Code)
string	room name

RoomList:64

Client-to-Server
Request a list of rooms?

integer

64 (Message Code)

Server-to-Client
The server tells us a list of rooms.

integer	64 (Message Code)
integer	number of rooms
string	name of room #1
string	name of room #2
: :
string	name of room #n
integer	user count records
integer	user count in room #1
integer	user count in room #2
: :
integer	user count in room #n

ExactFileSearch:65

Client-to-Server
It is unknown whether this is valid. Normal file search is a symmetric operation (the Client-to-Server and Server-to-Client messages are exactly the same and both valid), which would lead one to believe that maybe the ExactFileSearch works the same way.

Server-to-Client
Someone is searching for a file with an exact name

integer	65 (Message Code)
integer	token
string	filename
string	folder
integer	size
integer	checksum
string	username

AdminMessage:66

Client-to-Server
unknown if this is valid

Server-to-Client
The admin is sending a broadcast message. ("The service is going down for maintenance in 10 minutes!")

integer	66 (Message Code)
string	message

GlobalUserList:67

Client-to-Server
We send this to get a global list of all users online.

integer

67 (Message Code)

Server-to-Client
The list of users.

integer	67 (Message Code)
See user list format in JoinRoom message

TunneledMessage:68

Used to tunnel a message through the server, I would assume...(?)

integer	68 (Message Code)
string	username (to? from? depends on direction?)
integer	code
integer	token
integer	IP address
integer	port
string	message

PrivilegedUsers:69

Client-to-Server
Get a list of all users that made a donation

integer

69 (Message Code)

Server-to-Client
The returned list of users

integer	69 (Message Code)
integer	number of users
string	username #1
string	username #2
: :
string	username #n

AddToPrivileged:91

TODO, but likely something only an admin can do. We would assume it takes a username and a duration.

CheckPrivileges:92

Client-to-Server
How much privileged time do I have left from my donation?

integer

92 (Message Code)

Server-to-Client
You have this many days.

integer	69 (Message Code)
integer	number of days(?)

CantConnectToPeer:1001

Client-to-Server
We send this to say we cannot connect to a peer after it has asked us to connect.

integer	1001 (Message Code)
integer	token
string	username

Server-to-Client
The server sends this if we asked a peer to connect and it cannot do it. This means a connection cannot be established in either direction--both parties are firewalled.

integer	1001 (Message Code)
integer	token

Relogged?

Server sends this if someone else logged in under our nickname then disconnects us.

RemoveUser?

Client-to-Server
Used when we no longer want to be kept updated about a user's status. This message is defined in the Python code, but not associated with a message code. Maybe it falls into one of the message code gaps?

integer	??? (Message Code)
string	username to stop watching

CantCreateRoom?

Server-to-Client
The server sends this to tell us a new room cannot be created?

Peer Messages

Jump directly to a peer message: PeerInit PierceFW GetSharedFileList:4 SharedFileList:5 FileSearchResult:9 UserInfoRequest:15 UserInfoReply:16 FolderContentsRequest:36 FolderContentsResponse:37 TransferRequest:40 TransferResponse:41 PlaceholdUpload:42 QueueUpload:43 PlaceInQueue:44 UploadFailed:46 QueueFailed:50 PlaceInQueueRequest:51

PierceFW

This is the very first message send by peer that established a connection, if it has been asked by other peer to do so. Token is taken from ConnectToPeer server message.

PeerInit

This message is sent by peer that initiated a connection, not necessarily a peer that actually established it. Token apparently can be anything. Type is 'P' if it's anything but filetransfer, 'F' otherwise.

byte	1 (Message Code) Note that this is a BYTE!
string	username
string	type
integer	??? This seems to always be a constant (300 or 0x0000012c)
integer	token

GetSharedFileList:4

Client-to-Peer
The client sends this to a peer to ask for a list of files.

integer

4 (Message Code)

Peer-to-Client
It is unknown whether this is used.

SharedFileList:5

Client-to-Peer
It is unknown whether this is used.

Peer-to-Client
A peer responds with this message when sent a GetSharedFileList. This message can be a little complex, considering it contains data from three nested loops: directories, which contain files, which contain attributes. When implementing parsing of this message, it may be helpful to note that within each directory, the list of files (each with its own list of sttributes) is in the exact same format as the list of files returned from FileSearchResult.

integer	5 (Message Code)
The following data is zlib compressed:
integer	Number of directories
string	Directory name #1
integer	Number of files in directory #1
byte?	Dir#1, File#1 code(?)
string	Dir#1, File#1 filename
integer	Dir#1, File#1 size1
integer	Dir#1, File#1 size2
string	Dir#1, File#1 ext
integer	Dir#1, File#1 number of attributes
integer	Dir#1, File#1, Attr#1 type
integer	Dir#1, File#1, Attr#1 value
: :
integer	Dir#1, File#1, Attr#n value
: : : :
integer	Dir#n, File#n, Attr#n value

FileSearchResult:9

Client-to-Peer
It is unknown whether this is used.

Peer-to-Client
This is sent in response to a file search match. Token is taken from original FileSearch message. You will note that the file data is similar to that of SharedFileList, only without the outermost loop (directories). It contains simply a list of files, each with a list of attributes.

integer	9 (Message Code)
The following data is zlib compressed:
string	username
integer	token
integer	Number of files
byte	File #1, code
string	File #1, filename
integer	File #1, size1
integer	File #1, size2
string	File #1, ext
integer	File #1, number of attributes
integer	File #1, Attr #1 type
integer	File #1, Attr #1 value
: :
integer	File #n, Attr #n value
byte	Free upload slots
integer	Upload speed
integer	In Queue

UserInfoRequest:15

Client-to-Peer

integer

15 (Message Code)

Peer-to-Client
It is unknown whether this is used.

UserInfoReply:16

Client-to-Peer
It is unknown whether this is used.

Peer-to-Client

integer	16 (Message Code)
string	User's description
byte	Does this user have a pic?
string	This data element is only present if the previous byte is true. This string contains the user pic file content
integer	User uploads
integer	Total uploads
integer	Queue size
integer	Slots available

FolderContentsRequest:36

FolderContentsResponse:37

TransferRequest:40

Client-to-Peer
Ask a peer for a file. See the sequences section at the bottom of this document. Token is [new, unique token? taken from another message?].

integer	40 (Message Code)
integer	Direction constant, see above
integer	Token
string	filename
integer	This data field is only present if direction==1. File size.

Peer-to-Client
Tell a peer we are about to send them a file. (Used when piercing a firewall?) The message format is exactly the same as the client-to-peer version.

TransferResponse:41

Client-to-Peer or Peer-to-Client
This is the proper response to a TransferRequest message. "Yes, I agree to take the file" or "no, I do not agree to take the file." Token is taken from TransferRequest message.

integer	41 (Message Code)
integer	Token
byte	Allowed?
If Allowed is true:
integer	Optionally, the file size
If Allowed is false:
string	Optionally, a message explaining why the request was denied

PlaceholdUpload:42

Not sure yet.

integer	42 (Message Code)
string	Filename

QueueUpload:43

Not sure yet.

integer	43 (Message Code)
string	Filename

PlaceInQueue:44

Client-to-Peer
It is unknown whether this is used.

Peer-to-Client
You are in queue position x for file y. This is the response to a PlaceInQueueRequest.

integer	44 (Message Code)
string	filename
integer	place

UploadFailed:46

Not sure yet.

integer	46 (Message Code)
string	Filename

QueueFailed:50

Not sure yet.

integer	50 (Message Code)
string	Filename
string	Reason

PlaceInQueueRequest:51

Client-to-Peer
What place in your queue am I? The response is a PlaceInQueue message.

integer

51 (Message Code)

Peer-to-Client
It is unknown whether this is used.

Message Sequences

This section will attempt to describe the message sequences for common operations.

Login

User logs in successfully, gets server greeting, gets privileged user list, gets chat room list, starts monitoring buddies

client sends Login message
client sends SetWaitPort message
server sends Login response message
server automatically sends a RoomList response
server automatically sends a PrivilegedUsers response
client sends SharedFoldersFiles message
client sends AddUser message for each buddy in buddy list
server sends AddUser response for each buddy in the buddy list

Search

TODO: User performs a search

Chat

TODO: User enters a room, listens, speaks, then exits room

Obtaining Peer Address, basic

This sequence will grab a peer's address (ip+port), given the username, in the most simple manner.

Client sends GetPeerAddress message
Server sends GetPeerAddress response

Obtaining Peer Address, advanced

This sequence will start monitoring a user (as if that user were on your buddy list), and use that information to not only obtain the address, but get notified if the user goes offline. This is the method that the Python SoulSeek client uses.

client sends GetUserStatus message to server
server responds with GetUserStatus message with status
client sends AddUser message to server
server responds with AddUser message
server sends unsolicited GetPeerAddress message

Note: The following File Transfer scenarios cover every combination and permutation of the three states (client FW, peer FW, queue). They all assume the peer address has been obtained by one of the above methods.

File Transfer, basic

Client may or may not be firewalled, peer is not firewalled, peer has no wait queue

client opens a "P" type socket to the peer. This need not be a NEW socket. If a "P" type connection to the peer has already been established (for instance, because the peer has sent you a search result), it can be reused.
client sends PeerInit "P" message immediately followed by TransferRequest message
peer optionally sends back 12 bytes (the 5th is zero or one)
(Note from Brian: I am a little bit worried about the random 12 bytes that sometimes get sent before a TransferResponse message. The first four bytes are obviously not a message length. Like I said in the comments, the Python code (slskproto.py:SlskProtoThread..process_peer_input()) has some wacky if-elseif-else logic in there that gets called only if it is a non "F" peer connection and it is the first message received.)
peer sends back TransferResponse message
client opens second socket to peer
client sends PeerInit "F" message to peer
peer sends file
client closes second socket to peer

File Transfer, firewall

TODO: Client is not firewalled, peer is firewalled, peer has no wait queue

File Transfer, two firewalls

Client is firewalled, peer is firewalled, wait queue does not matter

A peer-to-peer connection in this situation is impossible

File Transfer, queue 1

TODO: Client is not firewalled, peer is not firewalled, peer has wait queue

File Transfer, queue 2

TODO: Client is not firewalled, peer is firewalled, peer has wait queue

File Transfer, queue 3

TODO: Client is firewalled, peer is not firewalled, peer has no wait queue

End of Document

Integer	4 bytes, network byte ordering
Byte	1 byte
String	an integer (4 bytes) that specifies the length of the string, followed by the string data as 8-bit characters. The string is not null-terminated.
TODO:	are other datatypes used?

SoulSeek Protocol Documentation

Table of Contents

Version History

Introduction

Overview

Constants

Messages

Server Messages

Login:1

SetWaitPort:2

GetPeerAddress:3

AddUser:5

GetUserStatus:7

SayChatroom:13

JoinRoom:14

LeaveRoom:15

UserJoinedRoom:16

UserLeftRoom:17

ConnectToPeer:18

MessageUser:22

MessageAcked:23

FileSearch:26

SetStatus:28

SharedFoldersFiles:35

GetUserStats:36

QueuedDownloads:40

PlaceInLineResponse:60

RoomAdded:62

RoomRemoved:63

RoomList:64

ExactFileSearch:65

AdminMessage:66

GlobalUserList:67

TunneledMessage:68

PrivilegedUsers:69

AddToPrivileged:91

CheckPrivileges:92

CantConnectToPeer:1001

Relogged?

RemoveUser?

CantCreateRoom?

Peer Messages

PierceFW

PeerInit

GetSharedFileList:4

SharedFileList:5

FileSearchResult:9

UserInfoRequest:15

UserInfoReply:16

FolderContentsRequest:36

FolderContentsResponse:37

TransferRequest:40

TransferResponse:41

PlaceholdUpload:42

QueueUpload:43

PlaceInQueue:44

UploadFailed:46

QueueFailed:50

PlaceInQueueRequest:51

Message Sequences

Login

Search

Chat

Obtaining Peer Address, basic

Obtaining Peer Address, advanced

File Transfer, basic

File Transfer, firewall

File Transfer, two firewalls

File Transfer, queue 1

File Transfer, queue 2

File Transfer, queue 3