Soulseek Protocol Documentation
Table of contents
Version HistoryIntroductionOverViewConstantsmentagesSserver Messagespeer MessagesMessage SEQUENCES
Version History2003-10-05: Added Integer to the Login Message Containing The IP of the Client.
Arend Van Beelen JR.
2003-10-04: Correct Statement About Soulseek Message Byte-Ordering. They Are Little-Endian.
Robert Sayre
2003-03-16: Added Piercefw Message Summary, Added to PlaceinQueuerequest Message Summary,
Robert Sayre
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: protocol.html, v 1.11 2003/10/12 19:23:18 Franklinmint 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?.) Integer4 bytes, little endianByte1 byteStringan 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 datapes 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 LengthMessage Payload4-byte-integer: 304-byte-integer: 14-byte-integer: 8JohnGalt4-byte-integer: 6secret4-byte-integer: 200Message 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 longth 6 and contacts 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-1Unknown0Offline1Away2onlineTransfer Direction0Download1Uploadtodo: There Are PROBLY 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
AdminMinMESSAGE: 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: 1Client-to-Server (Attempt to Login) Integer1 (Message Code) StringUserNameStringPasswordintegerVersion
Server-to-Client (Login Success / Fail)
integer1 (Message Code) bytesuccess (0 = fail, 1 = success) stringLogin message (error message or greeting message) integerOptional integer containing the external IPv4 address of the client. Only sent if the login was successful.
Setwaitport: 2Client-to-Server
This is Sent To The Server to Tell It What Port We Are Listening ON.
Integer2 (Message Code) Integerport Number (GeneLe 2234)
Server-to-client
It is believed That SetWaitport Messages Are Not Sent from The Server to The Client.
GetPeerAddress: 3Client-to-Server
This is Sent To The Server To ask for a peer's address (IP Address and port), Given the Peer's UserName.
INTEGER3 (Message Code) StringUsername
Server-to-client
This is the response from the server.
Integer3 (Message Code) StringUserName this Address Belongs Tointegerip Addressintegerport Number
AddUser: 5Client-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: Thee Also Seems To Be a getpeeraddress response message returned Automatic, Along With The AddUser Response Message - Even Though The getpeeraddress Request Was NEVER MADE. CAN Anyone Confirm this?
INTEGER5 STRINGUSERNAME to Start Watching
Server-to-client
Integer5 (Message Code) StringUsername Being WatchingBytewhether The User EXISTS
GetUserstatus: 7Client-to-Server
This message is buy to request a user's current status.integer7 (Message Code) StringUserName To Get Status of
Server-to-client
This message is buy............
Integer7 (Message Code) StringUsername this Status Applies Tointegerstatus Code, See Above
Saychatroom: 13Client-to-Server
THIS Message IS Sent to Say Something in a chatroom.
Integer13 (Message Code) StringRoomstringMessage
Server-to-client
Somebody said Something in a chatroom we are in.
Integer13 (Message Code) stringroomstringusernamestringmessage
Joinroom: 14Client-to-Server
WE Would Like to join a chatroom.
INTEGER14 (Message Code) StringRoom
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!)
integer14 (Message Code) stringroomintegernumber of users in this roomstringusername # 1stringusername # 2 :: stringusername #nintegernumber of status code intgers (should be the same as number of users in the above field) integerstatus code of username # 1integerstatus code of username # 2: : integerstatus code of username #nintegernumber of statistics records (should be the same as number of users in the above field) integerstats record 1: avgspeed of username # 1integerstats record 1: downloadnum of username # 1integerstats record 1: something of username # 1integerstats record 1: files of username # 1integerstats record 1: dirs of username # 1integerstats record 2: avgspeed of username # 2integerstats record 2: downloadnum of username # 2integerstats record 2: something of username # 2integerstats record 2: files of username # 2integerstats record 2: Dirs of username # 2 :: Integerstats Record N: avgspeed of username #nintegerstats record N: Downloadnum of Username #nintegerstats record N: Something Of u sername #nintegerstats record n: files of username #nintegerstats record n: dirs of username #nintegernumber of slotsfull recordsintegerslotsfull field of username # 1integerslotsfull field of username # 2 :: integerslotsfull field of username #nLeaveRoom: 15Client-to-Server
WE Would Like to Leave a chatroom.
INTEGER15 (Message Code) StringRoom
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).
INTEGER15 (Message Code) StringRoom
UserJoinedroom: 16Client-to-Server
This message is not Sent from the client.server-to-client
User "X" HAS Entered Chat Room "Y".
INTEGER16 (Message Code) StringRoomstringUsername
Userleftroom: 17Client-to-Server
This message is not sample from the client.
Server-to-client
User "x" HAS LEFT CHAT ROOM "Y".
INTEGER17 (Message Code) StringRoomstringUsername
ConnectToPeer: 18Client-to-Server If we can not 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.
Integer18 (Message Code) IntegertoKenstringUserNameStringType: "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 the attempt to establish a Direct Connection to the Peer.
Integer18 StringUserNameStringType: "P" / "f" Integerip Addressintegerportintegertoken
Messageuser: 22Client-to-Server
Send a private chat message to a user
INTEGER22 (Message Code) StringUserNameStringMessage
Server-to-client
SomeBody Sent US a Private chat message
INTEGER22 IntegerMessage IDintegertimeStampstringUsernameStringMessage
Messageacked: 23Client-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.
INTEGER23 (Message Code) IntegerMessage ID
Server-to-client
This message is not sample from the server to the client.
FileSearch: 26Client-to-Server
We send this to the server................
INTEGER26 (Message Code) IntegertoKenstringSearch Text
Server-to-client the server sends this to tell us someone is searching for something.integer26 (Message Code) StringUserNameintegertoKenstringSearch Text
SetStatus: 28Client-to-Server
Change my away / online status.
INTEGER28 (Message Code) Integernew Status, See Above
Server-to-client
This message is not sample from the server to the client.
SharedFoldersFiles: 35Server-to-Client
We send this to the server to tell it how much files and folders we are sharing.
INTEGER35 (Message Code) IntegerFolder Countintegerfile Count
Server-to-client
This message is not sample from the server to the client.
GetUserstats: 36client-to-server this message is not sample from the client to the server.
Server-to-client
The Server Sends this message to us to indeicate a change in a user's statistics.
Integer36 (Message Code) StringUserNameintegeravgspeedintegerDownloadNuminTegersometHingintegerFilesintegerDirs
QueuedDownloads: 40Client-to-Server
IT is unknown WHETHER this is Valid.
Server-to-client
The Server Sends this to indeicate if someone Has Download Slots Available.
INTEGER40 (Message Code) StringUserNameintegerslotsfull
PlaceinLineResponse: 60Client-to-Server
Ask THE Server What Place in line we are ...?
Integer60 (Message Code) STRINGUSERNAMEINTEGERTOKEN (TOKEN OF Original File Request?) Integerplace (...?)
Server-to-client the Server sends this to indeicate change in place in queue while we're waiting for files from the Other peer.
Integer60 (Message Code) STRINGUSERNAMEINTEGERTOKEN (TOKEN OF Original File Request?) Integerplace
Roomadded: 62Client-to-Server
Unknown if this is valid.
Server-to-client
The Server Tells US A New Room Has Been Added
Integer62 (Message Code) StringRoom Name
RoomRemoved: 63Client-to-Server
Unknown if this is valid.server-to -client
The Server Tells US A Room Has Been Removed
Integer62 (Message Code) StringRoom Name
Roomlist: 64Client-to-Server
REQUEST A LIST OF ROOMS?
INTEGER64 (Message Code)
Server-to-client
The Server Tells US A List of rooms.
integer64 (Message Code) integernumber of roomsstringname of room # 1stringname of room # 2 :: stringname of room #nintegeruser count recordsintegeruser count in room # 1integeruser count in room # 2 :: integeruser count in room #n
ExactFileSearch: 65Client-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 search for a file with an exact name
Integer65 (Message Code) IntegertoKenStringFileNameStringFolderintegersizeintegerChecksumstringUsername
AdminMinMESSAGE: 66Client-to-Server
Unknown if this is valid
Server-to-client
("The Service IS Going Down for Maintenance in 10 minutes!")
INTEGER66 (Message Code) StringMessage
GLOBALUSERLIST: 67Client-to-Server
WE Send this to get a global list of all users online.
INTEGER67 (Message Code)
Server-to-client
The list of users.
Integer67 (Message Code) See User List Format in JoinRoom Message
TunnelaredMessage: 68used to Tunnel a Message Through the Server, I Would Assume ... (?)
Integer68 (Message Code) STRINGUSERNAME (To? from? Depends on Direction?) Integercodeintegertokenintegerip AddressintegerportstringMessage
PrivilegedUsers: 69Client-to-Server
Get a list of all Users That Made a Donation
INTEGER69 (Message Code)
Server-to-Clientthe Returned List of Users
Integer69 (Message Code) Integernumber of Usersstringusername # 1StringUsername # 2 :: StringUsername #n
Addtoprivileged: 91todo, But Likey Something Only An Admin Can do. We would associate it takes a usrname and a duration.
CheckPrivileges: 92Client-to-Server
How much privileged time do i Have Left from my donation?
INTEGER92 (Message Code)
Server-to-client
You Have this Many Days.
Integer69 (Message Code) IntegerNumber of Days (?)
CantconnectTopeer: 1001Client-to-Server
We send this to say we cannot Connect to a peer after it Has asked us to connect.
INTEGER1001 (Message Code) IntegertoKenStringusername
Server-to-client
The Server Sends this if we ask a peer to connect and it cannot do it. This Means a connection cannot Be Established in Either Direction - Both Parties Are Firewalled.
INTEGER1001 (Message Code) INTEGERTOKEN
Relogged? Server Sends this if someone else logged in Under Our Nickname Then Disconnects US.
REMOVEUSER? Client-to-Server
User's Status. This Message is defined in Python Code, But Not Associated WITHON CODE, BUT NOT ASSOCIATED WITHON Code
Integer ??? (Message Code) StringUserName 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
PeerInitThis 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.byte1 (Message Code) Note that this Is A Byte! StringUserNameStringTypeinteger ??? this seems to always be a constant (300 or 0x0000012c) INTEGERTOKEN
.
Byte0 (Message Code) Note That Is A Byte! INTEGERTOKEN
GetSharedFileList: 4Client-to-peer
The Client Sends this to a peer to ask for a list of files.
INTEGER4 (Message Code)
Peer-to-Client
IT is unknown WHETHER THIS Used.
SharedFileList: 5Client-to-Peer
IT is unknown WHETHER THIS 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.
integer5 (Message Code) The following data is zlib compressed: integerNumber of directoriesstringDirectory name # 1integerNumber of files in directory # 1byte Dir # 1, File # 1 code stringDir # 1, File # 1 filenameintegerDir # 1, File # 1? (?) Size1integerdir # 1, File # 1 size2stringdir # 1, file # 1 extintegerdir # 1, file # 1 Number of AttributesintegerDir # 1, File # 1, Attr # 1 TypeintegerDir # 1, File # 1, Attr # 1 value :: Integerdir # 1, File # 1, Attr # n value :::: Integerdir # n, file # n, attr # n value
FileSearchResult: 9client-to-peerit is unknown WHETHER this is buy.
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.
integer9 (Message Code) The following data is zlib compressed: stringusernameintegertokenintegerNumber of filesbyteFile # 1, codestringFile # 1, filenameintegerFile # 1, size1integerFile # 1, size2stringFile # 1, extintegerFile # 1, number of attributesintegerFile # 1, Attr # 1 typeintegerFile # 1 , Attr # 1 value :: IntegerFile #n, Attr # N Valuebytefree Upload Slotsintegerupload Speedintegerin Queue
Userinforequest: 15Client-to-peer
INTEGER15 (Message Code)
Peer-to-Client
IT is unknown WHETHER THIS Used.
Userinforeply: 16Client-to-Peer
IT is unknown WHETHER THIS Used.
Peer-to-Client
integer16 (Message Code) stringUser's descriptionbyteDoes this user have a pic? stringThis data element is only present if the previous byte is true. This string contains the user pic file contentintegerUser uploadsintegerTotal uploadsintegerQueue sizeintegerSlots available
FolderContentSRequest: 36
FolderContentsResponse: 37
TransferRequest: 40Client-to-Peer
Ask a peer for a file. See the sequences section operation. Token is [new, unique token? Taken from another message?].
Integer40 (Message Code) IntegerDirection Constant, See AboveintegertoKenStringFileNameintegerthis Data Field is Only Present if DiRecion == 1. File Size.
Peer-to-Client
TELL a peer we are about to send the letter. (Used WHEN PIERCING A FILEWALL?) The message format is exactly the as the client-to-peer version.transferResponse: 41client-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.
INTEGER41 (Message Code) INTEGERTOKENBYTEALLOWED? IF AlloWed Is True: IntegerOptionally, The File Sizeif Allowed IS False: StringOptionally, a Message Explaining Why The Request Was Denied
PlaceHoldupload: 42Not Sure Yet.
Integer42 (Message Code) StringFileName
QueueUPload: 43Not Sure Yet.
INTEGER43 (Message Code) StringFileName
PlaceinQueue: 44Client-to-Peer
IT is unknown WHETHER THIS Used.
Peer-to-Client
You are in queue position x for file y. This is the response to a placeinqueuerequest.
Integer44 (Message Code) StringFileNameIntegerplace
UploadFailed: 46Not Sure Yet.
INTEGER46 (Message Code) StringFileName
Queuefailed: 50Not Sure Yet.
Integer50 (Message Code) StringFileNameStringReason
PlaceinQueueRequest: 51Client-to-Peer
What place in your queue am i? The response is a placeinqueue message.
INTEGER51 (Message Code) StringFileName
Peer-to-Client
IT is unknown WHETHER THIS Used.
Message sequences
This Section Will Attempt to Describe The Message Sequences for Common Operations.
Loginuser logs in success, 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 listSearchTODO : User Performs a Search
Chattodo: User Entes a room, Listens, Speaks, Then EXIXES Room
Obtaining Peer Address, Basices 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, advancedThis 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). The ALL Assume The Peer Address Has Been Obtained by One of the Above Methods.
File Transfer, BasicClient May Or May Not Be Firewalled, Peer Has No Wait Queue
Client Opens a "P" Type Socket To The Peer. This NEER 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 Peerfile Transfer, FireWallTodo: Client Is Not Firewalled, Peer Is Firewalled, Peer Has No Wait Queue
File Transfer, TWO FireWallsClient is Firewalled, Peer IS Firewalled, Wait Queue Does Not Matter
A peer-to-peer connection in this situation is ilossible
File Transfer, Queue 1TODO: Client Is Not Firewalled, Peer Is Not Firewalled, Peer Has Wait Queue
File Transfer, Queue 2Todo: Client Is Not Firewalled, Peer Is Firewalled, Peer Has Wait Queue
File Transfer, Queue 3Todo: Client Is Firewalled, Peer Is Not Firewalled, Peer Has No Wait Queue
End of document
