Nicotine+

Soulseek Protocol Documentation

Last updated on April 25, 2025

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 byte string

Bytes

Length of Bytes Bytes
uint32 byte array

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

Upload Permissions

Code Status
0 No One
1 Everyone
2 Users in List
3 Permitted Users

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. Certain attributes can be missing if a file does not provide them.

Server Messages

Server messages are used by clients to interface with the server over a connection (TCP). 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
1 Login
2 Set Listen Port
3 Get Peer Address
5 Watch User
6 Unwatch User
7 Get User Status
11 Ignore User OBSOLETE
12 Unignore User OBSOLETE
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
50 Similar Recommendations OBSOLETE
51 Interest Add DEPRECATED
52 Interest Remove DEPRECATED
54 Get Recommendations DEPRECATED
55 My Recommendations OBSOLETE
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 Cancel Membership
137 Private Room Disown
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 Operators
149 Message Users
150 Join Global Room DEPRECATED
151 Leave Global Room DEPRECATED
152 Global Room Message DEPRECATED
153 Related Searches OBSOLETE
160 Excluded Search Phrases
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 Hex Stream

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 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

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 status. Whenever a user’s status changes, the server sends a GetUserStatus message.

Note that the server does not currently send stat updates (GetUserStats) when watching a user, only the initial stats in the WatchUser response. As a consequence, stats can be outdated.

Data Order

Server Code 6

UnwatchUser

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

Data Order

Server Code 7

GetUserStatus

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

Data Order

Server Code 11

IgnoreUser

OBSOLETE, no longer used

We send this to the server to tell a user we have ignored them.

The server tells us a user has ignored us.

Data Order

Server Code 12

UnignoreUser

OBSOLETE, no longer used

We send this to the server to tell a user we are no longer ignoring them.

The server tells us a user is no longer ignoring us.

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.

As long as we’re in the room, the server will automatically send us status/stat updates for room users, including ourselves, in the form of GetUserStatus and GetUserStats messages.

Room names must meet certain requirements, otherwise the server will send a MessageUser message containing an error message. Requirements include:

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

We send this to the server to attempt an indirect connection with a user. The server forwards the message to the user, who in turn attempts to establish a connection to our IP address and port from their end.

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).

When changing our own status, the server sends us a GetUserStatus message when enabling away status, but not when disabling it.

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.

The server used to send a response message in the past, but this is no longer the case.

Nicotine+ uses TCP keepalive instead of sending this message.

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.

In the past, the server sent us this message for UserSearch requests from other users. Today, the server sends a FileSearch message instead.

Data Order

Server Code 50

SimilarRecommendations

OBSOLETE

We send this to the server when we are adding a recommendation to our “My recommendations” list, and want to receive a list of similar recommendations.

The server sends a list of similar recommendations to the one we want to add. Older versions of the official Soulseek client would display a dialog containing such recommendations, asking us if we want to add our original recommendation or one of the similar ones instead.

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 55

MyRecommendations

OBSOLETE

We send this to the server to ask for our own list of added likes/recommendations (called “My recommendations” in older versions of the official Soulseek client).

The server sends us the list of recommendations it knows we have added. For any recommendations present locally, but not on the server, the official Soulseek client would send a AddThingILike message for each missing item.

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

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.

In the past, the server sent us this message for RoomSearch requests from other users. Today, the server sends a FileSearch message instead.

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 members (excluding the owner) in a private room we are in.

Data Order

Server Code 134

PrivateRoomAddUser

We send this to the server to add a member to a private room, if we are the owner or an operator.

The server tells us a member has been added to a private room we are in.

Data Order

Server Code 135

PrivateRoomRemoveUser

We send this to the server to remove a member from a private room, if we are the owner or an operator. Owners can remove operators and regular members, operators can only remove regular members.

The server tells us a member has been removed from a private room we are in.

Data Order

Server Code 136

PrivateRoomCancelMembership

We send this to the server to cancel 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 tells us we were added to a private room.

Data Order

Server Code 140

PrivateRoomRemoved

The server tells us we were 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 member.

The server tells us a member received operator abilities in a private room we are in.

Data Order

Server Code 144

PrivateRoomRemoveOperator

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

The server tells us operator abilities were removed for a member in a private room we are in.

Data Order

Server Code 145

PrivateRoomOperatorAdded

The server tells us we were given operator abilities in a private room we are in.

Data Order

Server Code 146

PrivateRoomOperatorRemoved

The server tells us our operator abilities were removed in a private room we are in.

Data Order

Server Code 148

PrivateRoomOperators

The server sends us a list of operators in a private room we are in.

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 160

ExcludedSearchPhrases

The server sends a list of phrases not allowed on the search network. File paths containing such phrases should be excluded when responding to search requests.

Data Order

Server Code 1001

CantConnectToPeer

We send this when we are not able to respond to an indirect connection request. We receive this if a peer was not able to respond to our indirect connection request. The token is taken from the ConnectToPeer message.

Do not rely on receiving this message from peers. Keep a local timeout for indirect connections as well.

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 we 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

Peer init messages are used to initiate a P, F or D connection (TCP) 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) and User B’s username. The token is stored for later use (see step 6).
  2. User A sends GetPeerAddress to the Server with User B’s username.
  3. The Server responds to User A with GetPeerAddress, which gives User A the IP address of User B.
  4. User A sends a PeerInit to User B (direct connection request) using the IP address received in step 3.
  5. The Server sends a ConnectToPeer response to User B with the same token as in step 1. 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 6.
  6. 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, no connection is possible, and User B proceeds with step 7.
  7. User B sends a CantConnectToPeer to the Server.
  8. The Server sends a CantConnectToPeer response to User A.

Legacy Peer Connection Message Order

Used by Soulseek NS, Nicotine+ 3.2.0 and earlier (excluding step 5-7), Museek+ (excluding step 7), soulseeX

  1. User A sends GetPeerAddress to the Server with User B’s username.
  2. The Server responds to User A with GetPeerAddress, which gives User A the IP address of User B.
  3. User A sends a PeerInit to User B using the IP address received in step 1. 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 4).
  4. User A sends ConnectToPeer to the Server with a unique token.
  5. The Server sends a ConnectToPeer response to User B with the same token.
  6. 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, no connection is possible, and User B proceeds with step 7.
  7. User B sends a CantConnectToPeer to the Server.
  8. The Server sends a CantConnectToPeer response to User A.
  9. After 20 seconds, user A retries an indirect connection request (step 2) up to three times before giving up.

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

Peer messages are sent to peers over a P connection (TCP). 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
1 Private Message OBSOLETE
4 Shared File List Request
5 Shared File List Response
8 File Search Request OBSOLETE
9 File Search Response
10 Room Invitation OBSOLETE
14 Cancelled Queued Transfer OBSOLETE
15 User Info Request
16 User Info Response
33 Send Connect Token OBSOLETE
34 Move Download To Top OBSOLETE
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
48 Queued Downloads OBSOLETE
49 Indirect File Search Request OBSOLETE
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

File messages are sent to peers over a F connection (TCP), 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

Example Flow for Downloading a File

  1. We send a FileSearch message to the server, storing the token for later use.
  2. The server propagates the search query through the search network.
  3. We receive a ConnectToPeer message from the server for any peers that have a match for the search query.
    See Peer Connection Order for how to connect to a peer (in this scenario, we assume the role of User B).
  4. If a connection is established, we expect the peer to send us a FileSearchResponse message.
  5. If we decide to download a file received in the message from step 4, we send a QueueUpload message to the peer.
  6. The peer sends us a TransferRequest message.
  7. We send the peer a TransferResponse, accepting the transfer request. We store the filesize for later use.
  8. We receive a ConnectToPeer message from the server with the username of the peer, this time with an F connection.
  9. We send a PierceFireWall message to the peer, which lets the peer know they can begin transferring the file to us.
  10. The peer sends us the file data in small chunks until the transfer is complete, or until the connection is dropped. See UploadFailed for handling failed transfers.
    We can use the filesize stored previously to check how much data we expect to receive.
  11. Once the transfer is complete, we are free to persist the file to disk.

Distributed Messages

Distributed messages are sent to peers over a D connection (TCP), 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
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: