Protocol Messages (slskmessages)

The slskmessages module defines all protocol messages used in the Soulseek network.

Message Types

MessageType Constants

str

Internal application messages

str

Server protocol messages

str

Peer protocol messages

str

File transfer messages

str

Distributed network messages

Status Constants

UserStatus

int

User is offline

int

User is away

int

User is online

TransferRejectReason

str

Transfer is queued

str

User is banned

str

File is not shared

str

Queue file limit reached

Server Messages

Authenticate with the Soulseek server.

from pynicotine.slskmessages import Login

msg = Login(
    username="myusername",
    passwd="mypassword",
    version=160,
    minorversion=3
)

str

Username for authentication

str

Password for authentication

int

Client version number

bool

Whether login succeeded (received from server)

str

Reason for login failure if unsuccessful

WatchUser

Subscribe to status updates for a user.

from pynicotine.slskmessages import WatchUser

msg = WatchUser(user="username")

str

Username to watch

bool

Whether the user exists

int

User status (0=offline, 1=away, 2=online)

int

Average upload speed

int

Number of shared files

int

Number of shared directories

FileSearch

Initiate a global file search.

from pynicotine.slskmessages import FileSearch

msg = FileSearch(token=12345, text="music artist album")

int

Unique search token for tracking results

str

Search query

JoinRoom

Join a chat room.

from pynicotine.slskmessages import JoinRoom

msg = JoinRoom(room="music", private=False)

str

Name of the room to join

bool

Whether the room is private

list

List of UserData objects for room members

str

Room owner (for private rooms)

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
)

str

Username sending the results

int

Search token from the request

list

List of matching files with metadata

bool

Whether upload slots are available

int

Average upload speed

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
)

int

0 for download, 1 for upload

int

Unique transfer token

str

Virtual file path

int

Size of file in bytes

QueueUpload

Queue a file for upload.

from pynicotine.slskmessages import QueueUpload

msg = QueueUpload(file="folder\\filename.mp3")

str

Virtual file path to queue

Utility Functions

initial_token()

def initial_token()

Generates a random initial token for searches and transfers.

int

Random token value

increment_token()

def increment_token(token)

Increments a token, wrapping at UINT32 limit.

int

Current token value

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.

int

Audio bitrate in kbps

int

Duration in seconds

int

Variable bitrate flag (0 or 1)

int

Sample rate in Hz

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.

Core Modules

Network

Features

Protocol Messages (slskmessages)

Message Types

MessageType Constants

Status Constants

UserStatus

TransferRejectReason

Server Messages

WatchUser

FileSearch

JoinRoom

Peer Messages

SharedFileListRequest

FileSearchResponse

TransferRequest

QueueUpload

Utility Functions

initial_token()

increment_token()

File Attributes

Message Packing/Unpacking

​Message Types

​MessageType Constants

​Status Constants

​UserStatus

​TransferRejectReason

​Server Messages

​Login

​WatchUser

​FileSearch

​JoinRoom

​Peer Messages

​SharedFileListRequest

​FileSearchResponse

​TransferRequest

​QueueUpload

​Utility Functions

​initial_token()

​increment_token()

​File Attributes

​Message Packing/Unpacking

Message Types

MessageType Constants

Status Constants

UserStatus

TransferRejectReason

Server Messages

Login

WatchUser

FileSearch

JoinRoom

Peer Messages

SharedFileListRequest

FileSearchResponse

TransferRequest

QueueUpload

Utility Functions

initial_token()

increment_token()

File Attributes

Message Packing/Unpacking