aioslsk is a Python library for the SoulSeek protocol built on top of asyncio.

Supported Python versions are currently 3.9 - 3.13

You can find the full documentation here

pip install aioslsk

Starting the client and sending a private message:

import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand
from aioslsk.settings import Settings, CredentialsSettings

# Create default settings and configure credentials
settings: Settings = Settings(
    credentials=CredentialsSettings(
        username='my_user',
        password='Secret123'
    )
)

async def main():
    client: SoulSeekClient = SoulSeekClient(settings)

    await client.start()
    await client.login()

    # Send a private message
    await client.execute(PrivateMessageCommand('my_friend', 'Hi!'))

    await client.stop()

asyncio.run(main())

Install poetry and setup the project dependencies by running:

poetry install

A tool is available to start the client for debugging purposes (try out commands to the server, ...):

1. Create a settings.json file containing valid credentials in the tools/debug/ directory (or pass a path using --settings). To generate a simple settings file:

   poetry run python -m aioslsk.settings generate -u "Hello" -p "World" > tools/debug/settings.json

2. To start the REPL run:

   # Reads from tools/debug/settings.json
   poetry run python -m tools.debug.debug_mode
   # Reads from specific file
   poetry run python -m tools.debug.debug_mode --settings ~/custom_settings.json

3. Run an example command (the aioslsk.commands module is aliased to the cmds variable):

   await client(cmds.GetPeerAddressCommand('some user'), response=True)

4. To close the REPL execute exit() or press Ctrl+Z

Optionally the script takes a --cache-dir that will read/write the transfer and shares cache from the given directory

cd docs/
poetry run make html

Running all tests:

poetry run pytest tests/

Running all tests with code coverage report:

poetry run pytest --cov=aioslsk --cov-report term-missing tests/

A mock server implementation is available for testing, to start the server run:

# By default the server listens on port 2416
poetry run python -m tests.e2e.mock.server
# Specifying multiple listening ports
poetry run python -m tests.e2e.mock.server --port 2416 2242

Configure the hostname or IP of the server in your client and connect. If such configuration is not possible you can add an entry to the hosts file of your system. For example:

127.0.0.1      server.slsknet.org

Use --help to get a list of available options.

The package uses several dependencies:

• mutagen : library used for extracting audio metadata
• aiofiles : asyncio library for filesystem management
• async-upnp-client : library for managing UPnP configuration
• pydantic-settings : library for managing settings
• async-timeout : library providing timeout class