The Soulseek Protocol

Original, most up-to-date version on the Museek-Plus Trac

Server Messages

Server Messages Peer Messages Distributed Messages Museek Data Types

Send Send to Server
Receive Receive from Server

These messages are used by clients to interface with the server. Internal Server messages are spooky and not understood, since the OSS crowd doesn't have access to it's source code. If you want a Soulseek server, check out Soulfind. Soulfind is obviously not the exact same the official Soulseek server, but it handles the protocol well enough (and can be modified).

In museekd, these messages are sent and received in Museek/ServerConnection.cc and defined in Museek/ServerMessages.hh

The Message format

Message Length Code Message Contents

Message Index

CodeMessage
1 Login
2 Set Listen Port
3 Get Peer Address
5 Add User
7 Get Status
13 Say in Chat Room
14 Join Room
15 Leave Room
16 User Joined Room
17 User Left Room
18 Connect To Peer
22 Private Messages
23 Acknowledge Private Message
26 File Search
28 Set Online Status
32 Ping
34 Send Speed
35 Shared Folders & Files
36 Get User Stats
41 Kicked from Server
42 User Search
51 Interest Add
52 Interest Remove
54 Get Recommendations
56 Get Global Recommendations
64 Room List
65 Exact File Search
66 Global/Admin Message
69 Privileged Users
71 Have No Parents
86 Parent Inactivity Timeout
87 Search Inactivity Timeout
88 Minimum Parents In Cache
90 Distributed Alive Interval
91 Add Privileged User
92 Check Privileges
102 Net Info
103 Wishlist Search
104 Wishlist Interval
110 Get Similar Users
111 Get Item Recommendations
112 Get Item Similar Users
113 Room Tickers
114 Room Ticker Add
115 Room Ticker Remove
116 Set Room Ticker
117 Hated Interest Add
118 Hated Interest Remove
120 Room Search
121 Send Upload Speed
122 User Privileges
123 Give Privileges
1001 Cannot Connect

Server Code 1

Login
Museekd: SLogin
Send your username, password, and client version.

  • Send
    1. string username
    2. string password
    3. uint32 version number 182 is used for Museek+
  • Receive
    1. data buffer Windows Soulseek uses this hash to determine if it's connected to the official server
    2. uchar success
    3. string greet

Server Code 2

Set Listen Port
Museekd: SSetListenPort
The port you listen for connections on (2234 by default)

  • Send
    1. uint32 port
  • Receive
    • No Message

Server Code 3

Get Peer Address
Museekd: SGetPeerAddress

  • Send
    1. string username
  • Receive
    1. string username
    2. ip ip
    3. uint32 port

Server Code 5

Add User
Museekd: SAddUser
Watch this user's status

  • Send
    1. string username
  • Receive
    1. string username
    2. char exists converted to Boolean

Server Code 7

Get Status
Museekd: SGetStatus

  • Send
    1. string username
  • Receive
    1. string username
    2. uint32 status 0 == Offline, 1 == Away; 2 == Online
    3. bool privileged 0 == not, 1 == yes (New addition)

Server Code 13

Say in Chat Room
Museekd: SSayChatroom

  • Send
    1. string room
    2. string message
  • Receive
    1. string room
    2. string username
    3. string message

Server Code 14

Join a Room
Museekd: SJoinRoom

  • Send
    1. string room
  • Receive
    1. string room
    2. uint32 number of users in room
    3. Iterate the number of users museekd uses a vector of strings
      1. string user
    4. uint32 number of userdata (unused in museekd)
    5. Iterate the number of users museekd uses a vector of userdata
      1. uint32 status
      2. data userdata
    6. uint32 number of userdata (unused in museekd)
    7. Iterate the userdata vector of userdata (and add unpacked data to User Data)
      1. uint32 avgspeed
      2. uint32 downloadnum
      3. uint32 ??? (Unused)
      4. uint32 files
      5. uint32 dirs
    8. Iterate thru userdata
      1. uint32 slotsfull

ServerMessages?.hh then Iterates thru userdata and users (For passing message to daemon)

  • Add data to RoomData users[string username ] = data

Server Code 15

Leave Room
Museekd: SLeaveRoom

  • Send (leave room)
    1. string room
  • Receive (left room)
    1. string room

Server Code 16

A User Joined a Room
Museekd: SUserJoinedRoom

  • Send
    • No Message
  • Receive
    1. string username
    2. string room
    3. uint32 status
    4. uint32 avgspeed
    5. uint32 downloadnum
    6. uint32 ??? (Unused)
    7. uint32 files
    8. uint32 dirs
    9. uint32 slotsfull

Server Code 17

A User Left a Room
Museekd: SUserLeftRoom
A user (not you) left a room you are in.

  • Send
    • No Message
  • Receive
    1. string username
    2. string room

Server Code 18

Connect To Peer
Museekd: SConnectToPeer
A message you send to the server to notify a client that you want to connect to it, after direct connection has failed. See also: Code 1001 CannotConnect

  • Send
    1. uint32 token
    2. string username
    3. string type P or F
  • Receive
    1. string username
    2. string type P or F
    3. ip ip
    4. uint32 port
    5. uint32 token

Server Code 22

Private Messages
Museekd: SPrivateMessage

  • Send
    1. string username
    2. string message
  • Receive
    1. uint32 ID
    2. uint32 timestamp
    3. string username
    4. string message

Server Code 23

Acknowledge Private Message
Museekd: SAckPrivateMessage
Acknowledge that you received a Private message. If we do not send it, the server will keep sending the chat phrase to us. (Museekd also Reset timestamps to account for server-time bugginess)

  • Send
    1. uint32 message ID
  • Receive
    1. uint32 message ID

Server Code 26

File Search
Museekd: SFileSearch
The ticket is a random number generated by the client and used to track the search results.

  • Send
    1. uint32 ticket
    2. string search query
  • Receive search request from another user
    1. string username
    2. uint32 ticket
    3. string search query

Server Code 28

Set Online Status
Museekd: SSetStatus
Status is a way to define whether you're available or busy. 0 = Online and 1 = Away

  • Send
    1. uint32 status
  • Receive
    • No Message

Server Code 32

Ping
Museekd: SPing

  • Send
    • Empty Message
  • Receive
    • Empty Message

Server Code 34

Send Speed
Note: This Message is defunct and no longer used by Soulseek, message 121 is used instead
Museekd: SSendSpeed

  • Send average transfer speed
    1. string username
    2. uint32 speed
  • Receive
    • No Message

Server Code 35

Shared Folders & Files
Museekd: SSharedFoldersFiles

  • Send
    1. uint32 dirs
    2. uint32 files
  • Receive
    • No Message

Server Code 36

Get User Stats
Museekd: SGetUserStats

  • Send
    1. string username
  • Receive
    1. string username
    2. uint32 avgspeed
    3. uint32 downloadnum
    4. uint32 ??? (Unused)
    5. uint32 files
    6. uint32 dirs

Server Code 40

Queued Downloads

Server Code 41

Kicked from Server
Museekd: SKicked
You were disconnected (probably by another user with your name connecting to the Server) so don't try to reconnect automatically.

  • Send
    • Empty Message
  • Receive
    • Empty Message

Server Code 42

User Search
Museekd: SUserSearch
Search a specific user's shares

  • Send
    1. string username
    2. uint32 ticket
    3. string search query
  • Receive
    1. string username
    2. uint32 ticket
    3. string search query

Server Code 51

Add Liked Interest
Museekd: SInterestAdd

  • Send
    1. string item
  • Receive
    1. string item

Server Code 52

Remove Liked Interest
Museekd: SInterestRemove

  • Send
    1. string item
  • Receive
    1. string item

Server Code 54

Get Recommendations
Museekd: SGetRecommendations

  • Send
    • Empty Message
  • Receive
    1. uint32 number of total recommendations
    2. Iterate for number of total recommendations
      1. string recommendation
      2. uint32 number of recommendations this recommendation has

Server Code 56

Get Global Recommendations
Museekd: SGetGlobalRecommendations

  • Send
    • Empty Message
  • Receive
    1. uint32 number of total recommendations
    2. Iterate for number of total recommendations
      1. string recommendation
      2. uint32 number of recommendations this recommendation has

Server Code 64

Room List
Museekd: SRoomList
List of rooms and the number of users in them. Soulseek has a room size requirement of about 50 users when first connecting. Refreshing the list will download all rooms.

  • Send
    • Empty Message
  • Receive
    1. uint32 number of rooms
    2. Iterate for number of rooms
      1. string room
    3. uint32 number of rooms (unused in museekd)
    4. Iterate for number of rooms
      1. uint32 number of users in room

Server Code 65

Exact File Search
Museekd: SExactFileSearch

  • Send
    • No Message
  • Receive
    1. string username
    2. uint32 ticket
    3. string filename
    4. string path
    5. off_t filesize
    6. uint32 checkum

Server Code 66

Global / Admin Message
Museekd: SGlobalMessage
Admins send this message

  • Send
    • No Message
  • Receive
    1. string message

Server Code 69

Privileged Users
Museekd: SPrivilegedUsers

  • Send
    • No Message
  • Receive
    1. uint32 number of users
    2. Iterate number of users
      1. string user

Server Code 71

Have No Parents
Museekd: SHaveNoParents

  • Send
    1. uchar have_parents (is a boolean internal to museekd)
  • Receive
    • No Message

Server Code 83 - 83

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 84 - 84

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 86

Parent Inactivity Timeout
Museekd: SParentInactivityTimeout

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 87

Search Inactivity Timeout
Museekd: SSearchInactivityTimeout

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 88

Minimum Parents In Cache
Museekd: SMinParentsInCache

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 90

Distributed Alive Interval
Museekd: SDistribAliveInterval

  • Send
    • No Message
  • Receive
    1. uint32 number

Server Code 91

Add Privileged User
Museekd: SAddPrivileged
Add a new privileged user to your list of privileged users

  • Send
    • No Message
  • Receive
    1. string user

Server Code 92

Check Privileges
Museekd: SCheckPrivileges

  • Send
    • Empty Message
  • Receive
    1. uint32 time_left

Server Code 102

Net Info
Museekd: SNetInfo

  • Send
    • Empty Message
  • Receive list of search parents
    1. uint32 number of parents
    2. Iterate for number of rooms
      1. string user
      2. IP IP address
      3. uint32 number of users in room

Server Code 103

Wishlist Search
Museekd: SWishlistSearch

  • Send
    1. uint32 ticket
    2. string search query
  • Receive
    • No Message

Server Code 104

Wishlist Interval
Museekd: SWishlistInterval

  • Send
    • No Message
  • Receive
    1. uint32 interval

Server Code 110

Get Similar Users
Museekd: SGetSimilarUsers

  • Send
    • Empty Message
  • Receive
    1. uint32 number of users
    2. Iterate for number of user
      1. string user
      2. uint32 status

Server Code 111

Get Item Recommendations
Museekd: SGetItemRecommendations

  • Send
    1. string item
  • Receive
    1. uint32 number of recommendations
    2. Iterate for number of recommendations
      1. string recommendation
      2. uint32 number of recommendations for this recommendation

Server Code 112

Get Item Similar Users
Museekd: SGetItemSimilarUsers

  • Send
    1. string item
  • Receive
    1. uint32 number of users
    2. Iterate for number of user
      1. string user
      2. uint32 0

Server Code 113

Room Tickers
Museekd: SRoomTickers

  • Send
    • No Message
  • Receive
    1. string room
    2. uint32 number of users
    3. Iterate for number of user
      1. string user
      2. string tickers

Server Code 114

Room Ticker Add
Museekd: SRoomTickerAdd

  • Send
    • No Message
  • Receive
    1. string room
    2. string user
    3. string ticker

Server Code 115

Room Ticker Remove
Museekd: SRoomTickerRemove

  • Send
    • No Message
  • Receive
    1. string room
    2. string user

Server Code 116

Set Room Ticker
Museekd: SSetRoomTicker

  • Send
    1. string room
    2. string ticker
  • Receive
    • No Message

Server Code 117

Add Hated Interest
Museekd: SInterestHatedAdd

  • Send
    1. string item
  • Receive
    1. string item

Server Code 118

Remove Hated Interest
Museekd: SInterestHatedRemove

  • Send
    1. string item
  • Receive
    1. string item

Server Code 120

Room Search
Museekd: SRoomSearch

  • Send
    1. string room
    2. string ticket
    3. string search query
  • Receive
    1. string user
    2. string ticket
    3. string search query

Server Code 121

Send Upload Speed
Museekd: SSetUploadSpeed


  • Send
    1. uint32 speed (in bits-per-second)
  • Receive
    • No Message

Server Code 122

A user's Soulseek Privileges
Museekd: SUserPrivileges

  • Send
    1. string user
  • Receive
    1. string user
    2. char privileged (boolean internal to museekd)

Server Code 123

Give Soulseek Privileges to user
Museekd: SGivePrivileges

  • Send
    1. string user
    2. uint32 days
  • Receive
    • No Message

Server Code 1001

Cannot Connect
Museekd: SCannotConnect
See also: Code 18 ConnectToPeer

  • Send to the Server if we cannot connect to a peer.
    1. uint32 token
    2. string user
  • Receive this response means we are both firewalled or otherwise unable to connect to each other.
    1. uint32 token
    2. string user

Peer Messages

Server Messages Peer Messages Distributed Messages Museek Data Types

Send Send to Peer
Receive Receive from Peer

In museekd, these messages are sent and received in Museek/PeerConnection.cc and defined in Museek/PeerMessages.hh

The Message format

Message Length Code Message Contents

Message Index

Code Message
4 Shares Request
5 Shares Reply
8 Search Request
9 Search Reply
15 Info Request
16 Info Reply
36 Folder Contents Request
37 Folder Contents Reply
40 Transfer Request
41 Upload Reply
41 Download Reply
41 Transfer Reply
42 Upload Placehold
43 Queue Download
44 Upload Queue Notification
46 Upload Failed
50 Queue Failed
51 Place In Queue Request
52 Upload Queue Notification

Peer Code 4

Shares Request
Museekd: PSharesRequest

  • Send
    • Empty Message
  • Receive
    • Empty Message

Peer Code 5

Shares Reply
Museekd: PSharesReply

  • Send shares database
    1. Iterate thru shares database
      1. data
  • Receive shares database
    1. decompress
    2. uint32 number of directories
    3. Iterate number of directories
      1. string directory
      2. uint32 number of files
      3. Iterate number of files
        1. char ??? (unused by museekd)
        2. string filename
        3. off_t size File size
        4. string ext Extentsion
        5. uint32 number of attributes
        6. Iterate number of attributes
          1. uint32 place in attributes (unused by museekd)
          2. uint32 attribute

Peer Code 8

Search Request
Museekd: PSearchRequest

  • Send
    1. uint32 ticket
    2. string query
  • Receive
    1. uint32 ticket
    2. string query

Peer Code 9

Search Reply
Museekd: PSearchReply

  • Send
    1. string user
    2. uint32 ticket
    3. uint32 results size number of results
    4. Iterate for number of results
      1. uchar 1
      2. string filename
      3. uint32 size
      4. string ext
      5. uint32 attribute size
      6. Iterate number of attributes
        1. uint32 place in attributes
        2. uint32 attribute
  • Receive
    1. string user
    2. uint32 ticket
    3. uint32 results size number of results
    4. Iterate for number of results museekd pop buffer
      1. string filename
      2. off_t size
      3. string ext
      4. uint32 number of attributes
      5. Iterate number of attributes
        1. uint32 place in attributes
        2. uint32 attribute

Peer Code 15

Info Request
Museekd: PInfoRequest

  • Send
    • Empty Message
  • Receive
    • Empty Message

Peer Code 16

Info Reply
Museekd: PInfoReply

  • Send description, picture, totalupl, queuesize, slotfree
    1. string description
    2. Check contents of picture
      • If picture is not empty
        1. uchar has_picture 1
        2. vector of uchar picture
      • If picture is empty
        1. uchar has_picture 0
    3. uint totalupl
    4. uint queuesize
    5. uint32 slotsfree
  • Receive
    1. string description
    2. char has_picture
    3. Check contents of has_picture
      1. If has_picture is not empty
        1. vector of uchar picture
    1. uint32 totalupl
    2. uint32 queuesize
    3. uint32 slotsfree

Peer Code 36

Folder Contents Request
Museekd: PFolderContentsRequest

  • Send
    1. uint32 number of files in directory
    2. Iterate number of files in directory
      1. string file
  • Receive
    1. uint32 number of files in directory
    2. Iterate number of files in directory
      1. string file

Peer Code 37

Folder Contents Reply
Museekd: PFolderContentsReply

  • Send
    1. uint32 number of folders
    2. Iterate for number of folders
      1. string dir
      2. uint32 number of files
      3. Iterate number of files
        1. char true
        2. string file
        3. off_t size
        4. string ext Extension
        5. uint32 number of attributes
          1. uint32 attribute number
          2. uint32 attribute
  • Receive
    1. uint32 number of folders
    2. Iterate for number of folders
      1. string dir
      2. uint32 number of files
      3. Iterate number of files
        1. char ??? (unused by museekd)
        2. string file
        3. off_t size
        4. string ext Extension
        5. uint32 number of attributes
          1. uint32 attribute number
          2. uint32 attribute

Peer Code 40

Transfer Request
Museekd: PTransferRequest

  • Send
    1. uint32 direction
    2. uint32 ticket
    3. string filename
    4. Check contents of direction
      • off_t filesize if direction == 1
  • Receive
    1. uint32 direction
    2. uint32 ticket
    3. string filename
    4. Check contents of direction
      • off_t filesize if direction == 1

Peer Code 41 a

Upload Reply
Museekd: PUploadReply

  • Send
    1. string ticket
    2. uchar allowed
    3. Check contents of allowed
      • off_t filesize if allowed == 1
      • string reason if allowed == 0
  • Receive
    • No Message

Peer Code 41 b

Download Reply
Museekd: PDownloadReply

  • Send
    1. string ticket
    2. uchar allowed
    3. Check contents of allowed
      • string reason if allowed == 0
  • Receive
    • No Message

Peer Code 41 c

Transfer Reply
Museekd: PTransferReply

  • Send
    • No Message
  • Receive
    1. string ticket
    2. char allowed == 1
    3. Check contents of allowed
      • off_t filesize if allowed == 1
      • string reason if allowed == 0

Peer Code 42

Upload Placehold
Museekd: PUploadPlacehold

  • Send
    1. string filename
  • Receive
    1. string filename

Peer Code 43

Queue Download
Museekd: PQueueDownload

  • Send
    1. string filename
  • Receive
    1. string filename

Peer Code 44

Place In Queue Reply
Museekd: PPlaceInQueueReply

  • Send
    1. string filename
    2. string place
  • Receive
    1. string filename
    2. string place

Peer Code 46

Upload Failed
Museekd: PUploadFailed

  • Send
    1. string filename
  • Receive
    1. string filename

Peer Code 50

Queue Failed
Museekd: PQueueFailed

  • Send
    1. string filename
    2. string reason
  • Receive
    1. string filename
    2. string reason

Peer Code 51

Place In Queue Request
Museekd: PPlaceInQueueRequest

  • Send
    1. string filename
  • Receive
    1. string filename

Peer Code 52

Upload Queue Notification
Museekd: PUploadQueueNotification

  • Send
    • Empty Message
  • Receive
    • Empty Message

Distributed Messages

Server Messages Peer Messages Distributed Messages Museek Data Types

Send Send to Node
Receive Receive from Node

In museekd, these messages are sent and received in Museek/DistribConnection.cc and defined in Museek/DistribMessages.hh

The Message format

Message Length Code Message Contents

Message Index

Code Message
0 Ping
3 Search Request

Distributed Code 0

Ping
Museekd: DPing

  • Send
    • Empty Message
  • Receive
    • Empty Message

Distributed Code 3

Search Request
Museekd: DSearchRequest

  • Send
    1. uint32 unknown
    2. string user
    3. uint32 ticket
    4. string query
  • Receive
    1. uint32 unknown
    2. string user
    3. uint32 ticket
    4. string query

Museek Data Types

Server Messages Peer Messages Distributed Messages Museek Data Types

StringMap

  • std::map<std::string, std::string>

StringList

  • std::vector<std::string>

WStringList

  • std::vector<std::wstring> WStringList

WTickers

  • std::map<std::string, std::wstring>

Recommendations, SimilarUsers, RoomList

  • std::map<std::string, uint32>

NetInfo

  • std::map<std::string, std::pair<std::string, uint32> >

UserData

  1. uint32 status Online Status
  2. uint32 avgspeed Average Speed
  3. uint32 downloadnum Number of downloaded files
  4. uint32 files Files shared
  5. uint32 dirs Directories shared
  6. bool slotsfull Slots full

RoomData

  • std::map<std::string, UserData>

Folder

  • std::map<std::string, FileEntry>

Shares

  • std::map<std::string, Folder>

WFolder

  • std::map<std::wstring, FileEntry>

Folders

  • std::map<std::string, Shares>

WShares

  • std::map<std::wstring, WFolder>

WFolders

  • std::map<std::wstring, WShares>