Skip to main content
The slskmessages module defines all protocol messages used in the Soulseek network.

​
Message Types

​
MessageType Constants

​
INTERNAL
str
Internal application messages
​
SERVER
str
Server protocol messages
​
PEER
str
Peer protocol messages
​
FILE
str
File transfer messages
​
DISTRIBUTED
str
Distributed network messages

​
Status Constants

​
UserStatus

​
OFFLINE
int
User is offline
​
AWAY
int
User is away
​
ONLINE
int
User is online

​
TransferRejectReason

​
QUEUED
str
Transfer is queued
​
BANNED
str
User is banned
​
FILE_NOT_SHARED
str
File is not shared
​
TOO_MANY_FILES
str
Queue file limit reached

​
Server Messages

​
Login

Authenticate with the Soulseek server. 
from pynicotine.slskmessages import Login

msg = Login(
    username="myusername",
    passwd="mypassword",
    version=160,
    minorversion=3
)
​
username
str
Username for authentication
​
passwd
str
Password for authentication
​
version
int
Client version number
​
success
bool
Whether login succeeded (received from server)
​
rejection_reason
str
Reason for login failure if unsuccessful

​
WatchUser

Subscribe to status updates for a user. 
from pynicotine.slskmessages import WatchUser

msg = WatchUser(user="username")
​
user
str
Username to watch
​
userexists
bool
Whether the user exists
​
status
int
User status (0=offline, 1=away, 2=online)
​
avgspeed
int
Average upload speed
​
files
int
Number of shared files
​
dirs
int
Number of shared directories

​
FileSearch

Initiate a global file search. 
from pynicotine.slskmessages import FileSearch

msg = FileSearch(token=12345, text="music artist album")
​
token
int
Unique search token for tracking results
​
text
str
Search query

​
JoinRoom

Join a chat room. 
from pynicotine.slskmessages import JoinRoom

msg = JoinRoom(room="music", private=False)
​
room
str
Name of the room to join
​
private
bool
Whether the room is private
​
users
list
List of UserData objects for room members
​
owner
str
Room owner (for private rooms)
​
operators
list
List of room operators (for private rooms)

​
Peer Messages

​
SharedFileListRequest

Request a peer’s shared file list. 
from pynicotine.slskmessages import SharedFileListRequest

msg = SharedFileListRequest()

​
FileSearchResponse

Respond to a search request with matching files. 
from pynicotine.slskmessages import FileSearchResponse

msg = FileSearchResponse(
    search_username="myusername",
    token=12345,
    shares=file_list,
    freeulslots=True,
    ulspeed=1000,
    inqueue=0
)
​
search_username
str
Username sending the results
​
token
int
Search token from the request
​
shares
list
List of matching files with metadata
​
freeulslots
bool
Whether upload slots are available
​
ulspeed
int
Average upload speed
​
inqueue
int
Number of files queued for this user

​
TransferRequest

Request to initiate a file transfer. 
from pynicotine.slskmessages import TransferRequest, TransferDirection

msg = TransferRequest(
    direction=TransferDirection.UPLOAD,
    token=67890,
    file="folder\\filename.mp3",
    filesize=1234567
)
​
direction
int
0 for download, 1 for upload
​
token
int
Unique transfer token
​
file
str
Virtual file path
​
filesize
int
Size of file in bytes

​
QueueUpload

Queue a file for upload. 
from pynicotine.slskmessages import QueueUpload

msg = QueueUpload(file="folder\\filename.mp3")
​
file
str
Virtual file path to queue

​
Utility Functions

​
initial_token()

def initial_token()
Generates a random initial token for searches and transfers.
​
token
int
Random token value

​
increment_token()

def increment_token(token)
Increments a token, wrapping at UINT32 limit.
​
token
int
Current token value
​
new_token
int
Incremented token value
from pynicotine.slskmessages import initial_token, increment_token

# Generate initial token
token = initial_token()
print(f"Initial token: {token}")

# Increment for each new search
token = increment_token(token)
print(f"Next token: {token}")

​
File Attributes

The FileAttributes class stores audio file metadata.
​
bitrate
int
Audio bitrate in kbps
​
length
int
Duration in seconds
​
vbr
int
Variable bitrate flag (0 or 1)
​
sample_rate
int
Sample rate in Hz
​
bit_depth
int
Bit depth for lossless audio
from pynicotine.slskmessages import FileAttributes

attrs = FileAttributes(
    bitrate=320,
    length=245,
    vbr=0,
    sample_rate=44100
)

print(f"Bitrate: {attrs.bitrate} kbps")
print(f"Duration: {attrs.length} seconds")

​
Message Packing/Unpacking

All message classes inherit from SlskMessage and implement:
  • make_network_message() - Serializes message to bytes
  • parse_network_message() - Deserializes bytes to message
Messages use little-endian byte order and length-prefixed strings for network transmission.

Build docs developers (and LLMs) love

Get started for freeTalk to us