Nicotine+

Soulseek Protocol Documentation

Last updated on November 12, 2023

Since the official Soulseek client and server is proprietary software, this documentation has been compiled thanks to years of reverse engineering efforts. To preserve the health of the Soulseek network, please do not modify or extend the protocol in ways that negatively impact the network.

If you find any inconsistencies, errors or omissions in the documentation, please report them.

Sections

Packing

8-bit Integer

Number
1 Byte

16-bit Integer

Number
2 Bytes (little-endian)

32-bit Integer

Number
4 Bytes (little-endian)

64-bit Integer

Number
8 Bytes (little-endian)

Bool

Number
1 Byte (0 or 1)

String

Length of String String
uint32 bytes

Constants

Connection Types

Type Connection
P Peer To Peer
F File Transfer
D Distributed Network

Login Failure Reasons

Reason Description
INVALIDUSERNAME Username is longer than 30 characters or contains invalid characters (non-ASCII)
INVALIDPASS Password for existing user is incorrect
INVALIDVERSION Client version is outdated

User Status Codes

Code Status
0 Offline
1 Away
2 Online

Transfer Directions

Code Direction
0 Download from Peer
1 Upload to Peer

Transfer Rejection Reasons

In Use

String Comments
Banned SoulseekQt uses ‘File not shared.’ instead
Cancelled  
Complete  
File not shared. Note: Ends with a dot
File read error. Note: Ends with a dot
Pending shutdown. Note: Ends with a dot
Queued  
Too many files  
Too many megabytes  

Deprecated

String Comments
Blocked country Exclusive to Nicotine+, no longer used in Nicotine+ >=3.2.0
Disallowed extension Sent by Soulseek NS for filtered extensions
File not shared Exclusive to Nicotine+, no longer used in Nicotine+ >=3.1.1
Remote file error Sent by Soulseek NS in response to legacy download requests
User limit of x megabytes exceeded Exclusive to Nicotine+, no longer used in Nicotine+ >=3.1.1
User limit of x files exceeded Exclusive to Nicotine+, no longer used in Nicotine+ >=3.1.1

File Attribute Types

Code Attribute (unit)
0 Bitrate (kbps)
1 Duration (seconds)
2 VBR (0 or 1)
3 Encoder (unused)
4 Sample Rate (Hz)
5 Bit Depth (bits)

File Attribute Combinations

These combinations are actively used by clients. Other combinations are discouraged, unless the official client makes changes.

Server Messages

Send Receive
Send to Server Receive from Server

Server messages are used by clients to interface with the server. In Nicotine+, these messages are defined in slskmessages.py.

If you want a Soulseek server, check out Soulfind. Soulfind is obviously not exactly the same as the official proprietary Soulseek server, but it handles the protocol well enough (and can be modified).

Server Message Format

Message Length Code Message Contents
uint32 uint32 …

Server Message Codes

Code Message Status
1 Login  
2 Set Listen Port  
3 Get Peer Address  
5 Watch User  
6 Unwatch User  
7 Get User 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  
25 File Search Room Obsolete
26 File Search  
28 Set Online Status  
32 Ping  
33 Send Connect Token Obsolete
34 Send Download Speed Obsolete
35 Shared Folders & Files  
36 Get User Stats  
40 Queued Downloads Obsolete
41 Kicked from Server  
42 User Search  
51 Interest Add Deprecated
52 Interest Remove Deprecated
54 Get Recommendations Deprecated
56 Get Global Recommendations Deprecated
57 Get User Interests Deprecated
58 Admin Command Obsolete
60 Place In Line Response Obsolete
62 Room Added Obsolete
63 Room Removed Obsolete
64 Room List  
65 Exact File Search Obsolete
66 Global/Admin Message  
67 Global User List Obsolete
68 Tunneled Message Obsolete
69 Privileged Users  
71 Have No Parents  
73 Parent’s IP Deprecated
83 Parent Min Speed  
84 Parent Speed Ratio  
86 Parent Inactivity Timeout Obsolete
87 Search Inactivity Timeout Obsolete
88 Minimum Parents In Cache Obsolete
90 Distributed Ping Interval Obsolete
91 Add Privileged User Obsolete
92 Check Privileges  
93 Embedded Message  
100 Accept Children  
102 Possible Parents  
103 Wishlist Search  
104 Wishlist Interval  
110 Get Similar Users Deprecated
111 Get Item Recommendations Deprecated
112 Get Item Similar Users Deprecated
113 Room Tickers  
114 Room Ticker Add  
115 Room Ticker Remove  
116 Set Room Ticker  
117 Hated Interest Add Deprecated
118 Hated Interest Remove Deprecated
120 Room Search  
121 Send Upload Speed  
122 User Privileges Deprecated
123 Give Privileges  
124 Notify Privileges Deprecated
125 Acknowledge Notify Privileges Deprecated
126 Branch Level  
127 Branch Root  
129 Child Depth Deprecated
130 Reset Distributed  
133 Private Room Users  
134 Private Room Add User  
135 Private Room Remove User  
136 Private Room Drop Membership  
137 Private Room Drop Ownership  
138 Private Room Unknown Obsolete
139 Private Room Added  
140 Private Room Removed  
141 Private Room Toggle  
142 New Password  
143 Private Room Add Operator  
144 Private Room Remove Operator  
145 Private Room Operator Added  
146 Private Room Operator Removed  
148 Private Room Owned  
149 Message Users  
150 Join Global Room Deprecated
151 Leave Global Room Deprecated
152 Global Room Message Deprecated
153 Related Searches Obsolete
1001 Can’t Connect To Peer  
1003 Can’t Create Room  

Server Code 1

Login

We send this to the server right after the connection has been established. Server responds with the greeting message.

Sending Login Example

Message:

Data Message Length Message Code Username Length Username Password Length Password
Human 72 1 8 username 8 password
Hex 48 00 00 00 01 00 00 00 08 00 00 00 75 73 65 72 6e 61 6d 65 08 00 00 00 70 61 73 73 77 6f 72 64

… continued:

Data Version Hash Length Hash Minor Version
Human 160 32 d51c9a7e9353746a6020f9602d452929 1
Hex a0 00 00 00 20 00 00 00 64 35 31 63 39 61 37 65 39 33 35 33 37 34 36 61 36 30 32 30 66 39 36 30 32 64 34 35 32 39 32 39 01 00 00 00

Message as a Hex Stream:

Data Order

Server Code 2

SetWaitPort

We send this to the server to indicate the port number that we listen on (2234 by default).

If this value is set to zero, or the message is not sent upon login (which defaults the listen port to 0), remote clients handling a ConnectToPeer message will fail to properly purge the request. Confirmed in SoulseekQt 2020.3.12, but probably impacts most or all other versions.

Data Order

Server Code 3

GetPeerAddress

We send this to the server to ask for a peer’s address (IP address and port), given the peer’s username.

Data Order

Server Code 5

WatchUser

Used to be kept updated about a user’s stats. When a user’s stats have changed, the server sends a GetUserStats response message with the new user stats.

Data Order

Server Code 6

UnwatchUser

Used when we no longer want to be kept updated about a user’s stats.

Data Order

Server Code 7

GetUserStatus

The server tells us if a user has gone away or has returned.

Data Order

Server Code 13

SayChatroom

Either we want to say something in the chatroom, or someone else did.

Data Order

Server Code 14

JoinRoom

We send this message to the server when we want to join a room. If the room doesn’t exist, it is created.

Server responds with this message when we join a room. Contains users list with data on everyone.

Data Order

Server Code 15

LeaveRoom

We send this to the server when we want to leave a room.

Data Order

Server Code 16

UserJoinedRoom

The server tells us someone has just joined a room we’re in.

Data Order

Server Code 17

UserLeftRoom

The server tells us someone has just left a room we’re in.

Data Order

Server Code 18

ConnectToPeer

Either we ask server to tell someone else we want to establish a connection with them, or server tells us someone wants to connect with us. Used when the side that wants a connection can’t establish it, and tries to go the other way around (direct connection has failed).

See also: Peer Connection Message Order

Data Order

Server Code 22

MessageUser

Chat phrase sent to someone or received by us in private.

Data Order

Server Code 23

MessageAcked

We send this to the server to confirm that we received a private message. If we don’t send it, the server will keep sending the chat phrase to us.

Data Order

Server Code 25

FileSearchRoom

OBSOLETE, use RoomSearch server message

We send this to the server when we search for something in a room.

Data Order

Server Code 26

FileSearch

We send this to the server when we search for something. Alternatively, the server sends this message outside the distributed network to tell us that someone is searching for something, currently used for UserSearch and RoomSearch requests.

The token is a number generated by the client and is used to track the search results.

Data Order

Server Code 28

SetStatus

We send our new status to the server. Status is a way to define whether we’re available (online) or busy (away).

1 = Away
2 = Online

Data Order

Server Code 32

ServerPing

We send this to the server at most once per minute to ensure the connection stays alive.

Nicotine+ uses TCP keepalive instead.

Data Order

Server Code 33

SendConnectToken

OBSOLETE, no longer used

Data Order

Server Code 34

SendDownloadSpeed

OBSOLETE, use SendUploadSpeed server message

We used to send this after a finished download to let the server update the speed statistics for a user.

Data Order

Server Code 35

SharedFoldersFiles

We send this to server to indicate the number of folder and files that we share.

Data Order

Server Code 36

GetUserStats

The server sends this to indicate a change in a user’s statistics, if we’ve requested to watch the user in WatchUser previously. A user’s stats can also be requested by sending a GetUserStats message to the server, but WatchUser should be used instead.

Data Order

Server Code 40

QueuedDownloads

OBSOLETE, no longer sent by the server

The server sends this to indicate if someone has download slots available or not.

Data Order

Server Code 41

Relogged

The server sends this if someone else logged in under our nickname, and then disconnects us.

Data Order

Server Code 42

UserSearch

We send this to the server when we search a specific user’s shares. The token is a number generated by the client and is used to track the search results.

Data Order

Server Code 51

AddThingILike

DEPRECATED, used in Soulseek NS but not SoulseekQt

We send this to the server when we add an item to our likes list.

Data Order

Server Code 52

RemoveThingILike

DEPRECATED, used in Soulseek NS but not SoulseekQt

We send this to the server when we remove an item from our likes list.

Data Order

Server Code 54

Recommendations

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends us a list of personal recommendations and a number for each.

Data Order

Server Code 56

GlobalRecommendations

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends us a list of global recommendations and a number for each.

Data Order

Server Code 57

UserInterests

DEPRECATED, used in Soulseek NS but not SoulseekQt

We ask the server for a user’s liked and hated interests. The server responds with a list of interests.

Data Order

Server Code 58

AdminCommand

OBSOLETE

We send this to the server to run an admin command (e.g. to ban or silence a user) if we have admin status on the server.

Data Order

Server Code 60

PlaceInLineResponse

OBSOLETE, use PlaceInQueueResponse peer message

The server sends this to indicate change in place in queue while we’re waiting for files from another peer.

Data Order

Server Code 62

RoomAdded

OBSOLETE, no longer sent by the server

The server tells us a new room has been added.

Data Order

Server Code 63

RoomRemoved

OBSOLETE, no longer sent by the server

The server tells us a room has been removed.

Data Order

Server Code 64

RoomList

The server tells us a list of rooms and the number of users in them. When connecting to the server, the server only sends us rooms with at least 5 users. A few select rooms are also excluded, such as nicotine and The Lobby. Requesting the room list yields a response containing the missing rooms.

Data Order

  1. uint32 number of owned private rooms
  2. Iterate for number of owned private rooms
    1. string owned private room
  3. uint32 number of owned private rooms
  4. Iterate for number of owned private rooms
    1. uint32 number of users in owned private room
  1. uint32 number of private rooms (except owned)
  2. Iterate for number of private rooms (except owned)
    1. string private room
  3. uint32 number of private rooms (except owned)
  4. Iterate for number of private rooms (except owned)
    1. uint32 number of users in private rooms (except owned)
  1. uint32 number of operated private rooms
  2. Iterate for number of operated private rooms
    1. string operated private room

Server Code 65

ExactFileSearch

OBSOLETE, no results even with official client

We send this to search for an exact file name and folder, to find other sources.

Data Order

Server Code 66

AdminMessage

A global message from the server admin has arrived.

Data Order

Server Code 67

GlobalUserList

OBSOLETE, no longer used

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

Data Order

Server Code 68

TunneledMessage

OBSOLETE, no longer used

Server message for tunneling a chat message.

Data Order

Server Code 69

PrivilegedUsers

The server sends us a list of privileged users, a.k.a. users who have donated.

Data Order

Server Code 71

HaveNoParent

We inform the server if we have a distributed parent or not. If not, the server eventually sends us a PossibleParents message with a list of possible parents to connect to. If no candidates are found, no such message is sent by the server, and we eventually become a branch root.

Data Order

Server Code 73

SearchParent

DEPRECATED, sent by Soulseek NS but not SoulseekQt

We send the IP address of our parent to the server.

Data Order

Server Code 83

ParentMinSpeed

The server informs us about the minimum upload speed required to become a parent in the distributed network.

Data Order

Server Code 84

ParentSpeedRatio

The server sends us a speed ratio determining the number of children we can have in the distributed network. The maximum number of children is our upload speed divided by the speed ratio.

Data Order

Server Code 86

ParentInactivityTimeout

OBSOLETE, no longer sent by the server

Data Order

Server Code 87

SearchInactivityTimeout

OBSOLETE, no longer sent by the server

Data Order

Server Code 88

MinParentsInCache

OBSOLETE, no longer sent by the server

Data Order

Server Code 90

DistribPingInterval

OBSOLETE, no longer sent by the server

Data Order

Server Code 91

AddToPrivileged

OBSOLETE, no longer sent by the server

The server sends us the username of a new privileged user, which we add to our list of global privileged users.

Data Order

Server Code 92

CheckPrivileges

We ask the server how much time we have left of our privileges. The server responds with the remaining time, in seconds.

Data Order

Server Code 93

EmbeddedMessage

The server sends us an embedded distributed message. The only type of distributed message sent at present is DistribSearch (distributed code 3). If we receive such a message, we are a branch root in the distributed network, and we distribute the embedded message (not the unpacked distributed message) to our child peers.

Data Order

Server Code 100

AcceptChildren

We tell the server if we want to accept child nodes.

Data Order

Server Code 102

PossibleParents

The server send us a list of max 10 possible distributed parents to connect to. Messages of this type are sent to us at regular intervals, until we tell the server we don’t need more possible parents with a HaveNoParent message.

The received list always contains users whose upload speed is higher than our own. If we have the highest upload speed on the server, we become a branch root, and start receiving SearchRequest messages directly from the server.

Data Order

Server Code 103

WishlistSearch

We send the server one of our wishlist search queries at each interval.

Data Order

Server Code 104

WishlistInterval

The server tells us the wishlist search interval.

This interval is almost always 12 minutes, or 2 minutes for privileged users.

Data Order

Server Code 110

SimilarUsers

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends us a list of similar users related to our interests.

Data Order

Server Code 111

ItemRecommendations

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends us a list of recommendations related to a specific item, which is usually present in the like/dislike list or an existing recommendation list.

Data Order

Server Code 112

ItemSimilarUsers

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends us a list of similar users related to a specific item, which is usually present in the like/dislike list or recommendation list.

Data Order

Server Code 113

RoomTickerState

The server returns a list of tickers in a chat room.

Tickers are customizable, user-specific messages that appear on chat room walls.

Data Order

Server Code 114

RoomTickerAdd

The server sends us a new ticker that was added to a chat room.

Tickers are customizable, user-specific messages that appear on chat room walls.

Data Order

Server Code 115

RoomTickerRemove

The server informs us that a ticker was removed from a chat room.

Tickers are customizable, user-specific messages that appear on chat room walls.

Data Order

Server Code 116

RoomTickerSet

We send this to the server when we change our own ticker in a chat room. Sending an empty ticker string removes any existing ticker in the room.

Tickers are customizable, user-specific messages that appear on chat room walls.

Data Order

Server Code 117

AddThingIHate

DEPRECATED, used in Soulseek NS but not SoulseekQt

We send this to the server when we add an item to our hate list.

Data Order

Server Code 118

RemoveThingIHate

DEPRECATED, used in Soulseek NS but not SoulseekQt

We send this to the server when we remove an item from our hate list.

Data Order

Server Code 120

RoomSearch

We send this to the server to search files shared by users who have joined a specific chat room.

The token is a number generated by the client and is used to track the search results.

Data Order

Server Code 121

SendUploadSpeed

We send this after a finished upload to let the server update the speed statistics for ourselves.

Data Order

Server Code 122

UserPrivileged

DEPRECATED, use WatchUser and GetUserStatus server messages

We ask the server whether a user is privileged or not.

Data Order

Server Code 123

GivePrivileges

We give (part of) our privileges, specified in days, to another user on the network.

Data Order

Server Code 124

NotifyPrivileges

DEPRECATED, sent by Soulseek NS but not SoulseekQt

Data Order

Server Code 125

AckNotifyPrivileges

DEPRECATED, no longer used

Data Order

Server Code 126

BranchLevel

We tell the server what our position is in our branch (xth generation) on the distributed network.

Data Order

Server Code 127

BranchRoot

We tell the server the username of the root of the branch we’re in on the distributed network.

Data Order

Server Code 129

ChildDepth

DEPRECATED, sent by Soulseek NS but not SoulseekQt

We tell the server the maximum number of generation of children we have on the distributed network.

Data Order

Server Code 130

ResetDistributed

The server asks us to reset our distributed parent and children.

Data Order

Server Code 133

PrivateRoomUsers

The server sends us a list of room users that we can alter (add operator abilities / dismember).

Data Order

Server Code 134

PrivateRoomAddUser

We send this to inform the server that we’ve added a user to a private room.

Data Order

Server Code 135

PrivateRoomRemoveUser

We send this to inform the server that we’ve removed a user from a private room.

Data Order

Server Code 136

PrivateRoomDismember

We send this to the server to remove our own membership of a private room.

Data Order

Server Code 137

PrivateRoomDisown

We send this to the server to stop owning a private room.

Data Order

Server Code 138

PrivateRoomSomething

OBSOLETE, no longer used

Unknown purpose

Data Order

Server Code 139

PrivateRoomAdded

The server sends us this message when we are added to a private room.

Data Order

Server Code 140

PrivateRoomRemoved

The server sends us this message when we are removed from a private room.

Data Order

Server Code 141

PrivateRoomToggle

We send this when we want to enable or disable invitations to private rooms.

Data Order

Server Code 142

ChangePassword

We send this to the server to change our password. We receive a response if our password changes.

Data Order

Server Code 143

PrivateRoomAddOperator

We send this to the server to add private room operator abilities to a user.

Data Order

Server Code 144

PrivateRoomRemoveOperator

We send this to the server to remove private room operator abilities from a user.

Data Order

Server Code 145

PrivateRoomOperatorAdded

The server send us this message when we’re given operator abilities in a private room.

Data Order

Server Code 146

PrivateRoomOperatorRemoved

The server send us this message when our operator abilities are removed in a private room.

Data Order

Server Code 148

PrivateRoomOwned

The server sends us a list of operators in a specific room, that we can remove operator abilities from.

Data Order

Server Code 149

MessageUsers

Sends a broadcast private message to the given list of online users.

Data Order

Server Code 150

JoinGlobalRoom

DEPRECATED, used in Soulseek NS but not SoulseekQt

We ask the server to send us messages from all public rooms, also known as public room feed.

Data Order

Server Code 151

LeaveGlobalRoom

DEPRECATED, used in Soulseek NS but not SoulseekQt

We ask the server to stop sending us messages from all public rooms, also known as public room feed.

Data Order

Server Code 152

GlobalRoomMessage

DEPRECATED, used in Soulseek NS but not SoulseekQt

The server sends this when a new message has been written in the public room feed (every single line written in every public room).

Data Order

Server Code 153

RelatedSearch

OBSOLETE, server sends empty list as of 2018

The server returns a list of related search terms for a search query.

Data Order

Server Code 1001

CantConnectToPeer

We send this to say we can’t connect to peer after it has asked us to connect. We receive this if we asked peer to connect and it can’t do this. This message means a connection can’t be established either way.

See also: Peer Connection Message Order

Data Order

Server Code 1003

CantCreateRoom

Server tells us a new room cannot be created.

This message only seems to be sent if you try to create a room with the same name as an existing private room. In other cases, such as using a room name with leading or trailing spaces, only a private message containing an error message is sent.

Data Order

Peer Init Messages

Send Receive
Send to Peer Receive from Peer

Peer init messages are used to initiate a ‘P’, ‘F’ or ‘D’ connection to a peer. In Nicotine+, these messages are defined in slskmessages.py.

Peer Init Message Format

Message Length Code Message Contents
uint32 uint8 …

Peer Init Message Codes

Code Message
0 Pierce Firewall
1 Peer Init

Modern Peer Connection Message Order

Used by SoulseekQt, Nicotine+ 3.2.1 and later, Soulseek.NET-based clients (slskd, Seeker)

  1. User A sends ConnectToPeer to the Server with a unique token (indirect connection request)
  2. User A sends a PeerInit to User B (direct connection request)
  3. The Server sends a ConnectToPeer response to User B with the same token.
    If User B receives the PeerInit message, a connection is established, and user A is free to send peer messages.
    Otherwise, once User B receives the ConnectToPeer message from the Server, User B proceeds with step 4.
  4. User B sends a PierceFireWall to User A with the token included in the ConnectToPeer message.
    If this succeeds, a connection is established, and User A is free to send peer messages.
    If this fails, User B retries for ~1 minute. If this still fails, no connection is possible, and User B proceeds with step 5.
  5. User B sends a CantConnectToPeer to the Server.
  6. The Server sends a CantConnectToPeer response to User A.

Unlike SoulseekQt, Nicotine+ and Soulseek.NET-based clients skip step 5 in favor of letting the connection attempt time out on User A’s end.

Legacy Peer Connection Message Order

Used by Soulseek NS, Nicotine+ 3.2.0 and earlier, Museek+, soulseeX

  1. User A sends a PeerInit to User B.
    If this succeeds, a connection is established, and User A is free to send peer messages.
    If this fails (socket cannot connect), User A proceeds with an indirect connection request (step 2).
  2. User A sends ConnectToPeer to the Server with a unique token
  3. The Server sends a ConnectToPeer response to User B with the same token
  4. User B sends a PierceFireWall to User A with the same token.
    If this succeeds, a connection is established, and User A is free to send peer messages.
    If this fails, User B retries for ~1 minute. If this still fails, no connection is possible, and User B proceeds with step 5.
  5. User B sends a CantConnectToPeer to the Server.
  6. The Server sends a CantConnectToPeer response to User A.

Peer Init Code 0

PierceFireWall

This message is sent in response to an indirect connection request from another user. If the message goes through to the user, the connection is ready. The token is taken from the ConnectToPeer server message.

See also: Peer Connection Message Order

Data Order

Peer Init Code 1

PeerInit

This message is sent to initiate a direct connection to another peer. The token is apparently always 0 and ignored.

See also: Peer Connection Message Order

Data Order

Peer Messages

Send Receive
Send to Peer Receive from Peer

Peer messages are sent to peers over a ‘P’ connection. Only a single active connection to a peer is allowed. In Nicotine+, these messages are defined in slskmessages.py.

Peer Message Format

Message Length Code Message Contents
uint32 uint32 …

Peer Message Codes

Code Message Status
1 Private Message Obsolete, contents unknown
4 Shared File List Request  
5 Shared File List Response  
8 File Search Request Obsolete
9 File Search Response  
10 Room Invitation Obsolete, contents unknown
14 Cancelled Queued Transfer Obsolete, contents unknown
15 User Info Request  
16 User Info Response  
33 Send Connect Token Obsolete, contents unknown
34 Move Download To Top Obsolete, contents unknown
36 Folder Contents Request  
37 Folder Contents Response  
40 Transfer Request  
41 Download Response Deprecated
41 Upload Response  
42 Upload Placehold Obsolete
43 Queue Upload  
44 Place In Queue Response  
46 Upload Failed  
47 Exact File Search Request Obsolete, contents unknown
48 Queued Downloads Obsolete, contents unknown
49 Indirect File Search Request Obsolete, contents unknown
50 Upload Denied  
51 Place In Queue Request  
52 Upload Queue Notification Deprecated

Peer Code 4

GetShareFileList

We send this to a peer to ask for a list of shared files.

Data Order

Peer Code 5

SharedFileListResponse

A peer responds with a list of shared files after we’ve sent a SharedFileListRequest.

Data Order

Peer Code 8

FileSearchRequest

OBSOLETE, use UserSearch server message

We send this to the peer when we search for a file. Alternatively, the peer sends this to tell us it is searching for a file.

Data Order

Peer Code 9

FileSearchResponse

A peer sends this message when it has a file search match. The token is taken from original FileSearch, UserSearch or RoomSearch server message.

Data Order

Peer Code 15

UserInfoRequest

We ask the other peer to send us their user information, picture and all.

Data Order

Peer Code 16

UserInfoResponse

A peer responds with this after we’ve sent a UserInfoRequest.

Data Order

Peer Code 36

FolderContentsRequest

We ask the peer to send us the contents of a single folder.

Data Order

Peer Code 37

FolderContentsResponse

A peer responds with the contents of a particular folder (with all subfolders) after we’ve sent a FolderContentsRequest.

Data Order

Peer Code 40

TransferRequest

This message is sent by a peer once they are ready to start uploading a file to us. A TransferResponse message is expected from the recipient, either allowing or rejecting the upload attempt.

This message was formerly used to send a download request (direction 0) as well, but Nicotine+ >= 3.0.3, Museek+ and the official clients use the QueueUpload peer message for this purpose today.

Data Order

Peer Code 41 a

TransferResponse Download Response

DEPRECATED, use QueueUpload to request files

Response to TransferRequest

We (or the other peer) either agrees, or tells the reason for rejecting the file download.

Data Order

Peer Code 41 b

TransferResponse Upload Response

Response to TransferRequest

We (or the other peer) either agrees, or tells the reason for rejecting the file upload.

Data Order

Peer Code 42

PlaceholdUpload

OBSOLETE, no longer used

Data Order

Peer Code 43

QueueUpload

This message is used to tell a peer that an upload should be queued on their end. Once the recipient is ready to transfer the requested file, they will send a TransferRequest to us.

Data Order

Peer Code 44

PlaceInQueueResponse

The peer replies with the upload queue placement of the requested file.

Data Order

Peer Code 46

UploadFailed

This message is sent whenever a file connection of an active upload closes. Soulseek NS clients can also send this message when a file cannot be read. The recipient either re-queues the upload (download on their end), or ignores the message if the transfer finished.

Data Order

Peer Code 50

UploadDenied

This message is sent to reject QueueUpload attempts and previously queued files. The reason for rejection will appear in the transfer list of the recipient.

Data Order

Peer Code 51

PlaceInQueueRequest

This message is sent when asking for the upload queue placement of a file.

Data Order

Peer Code 52

UploadQueueNotification

DEPRECATED, sent by Soulseek NS but not SoulseekQt

This message is sent to inform a peer about an upload attempt initiated by us.

Data Order

File Messages

Send Receive
Send to Peer Receive from Peer

File messages are sent to peers over a ‘F’ connection, and do not have messages codes associated with them.

File Connection Message Format

Message Contents
…

File Connection Messages

Message
File Transfer Init
File Offset

File Transfer Init

FileTransferInit

We send this to a peer via a ‘F’ connection to tell them that we want to start uploading a file. The token is the same as the one previously included in the TransferRequest peer message.

Note that slskd and Nicotine+ <= 3.0.2 use legacy download requests, and send this message when initializing our file upload connection from their end.

Data Order

File Offset

FileOffset

We send this to the uploading peer at the beginning of a ‘F’ connection, to tell them how many bytes of the file we’ve previously downloaded. If nothing was downloaded, the offset is 0.

Note that Soulseek NS fails to read the size of an incomplete download if more than 2 GB of the file has been downloaded, and the download is resumed. In consequence, the client sends an invalid file offset of -1.

Data Order

Distributed Messages

Send Receive
Send to Node Receive from Node

Distributed messages are sent to peers over a ‘D’ connection, and are used for the distributed search network. Only a single active connection to a peer is allowed. In Nicotine+, these messages are defined in slskmessages.py.

Distributed Message Format

Message Length Code Message Contents
uint32 uint8 …

Distributed Message Codes

Code Message Status
0 Ping Deprecated
3 Search Request  
4 Branch Level  
5 Branch Root  
7 Child Depth Deprecated
93 Embedded Message  

Distributed Code 0

DistribPing

DEPRECATED, sent by Soulseek NS but not SoulseekQt

We ping distributed children every 60 seconds.

Data Order

Distributed Code 3

DistribSearch

Search request that arrives through the distributed network. We transmit the search request to our child peers.

Data Order

Distributed Code 4

DistribBranchLevel

We tell our distributed children what our position is in our branch (xth generation) on the distributed network.

If we receive a branch level of 0 from a parent, we should mark the parent as our branch root, since they won’t send a DistribBranchRoot message in this case.

Data Order

Distributed Code 5

DistribBranchRoot

We tell our distributed children the username of the root of the branch we’re in on the distributed network.

This message should not be sent when we’re the branch root.

Data Order

Distributed Code 7

DistribChildDepth

DEPRECATED, sent by Soulseek NS but not SoulseekQt

We tell our distributed parent the maximum number of generation of children we have on the distributed network.

Data Order

Distributed Code 93

DistribEmbeddedMessage

A branch root sends us an embedded distributed message. We unpack the distributed message and distribute it to our child peers.

The only type of distributed message sent at present is DistribSearch (distributed code 3).

Data Order

Credits

This documentation exists thanks to efforts from the following projects:

This site is open source. Improve this page.