pysunvox

Python bindings for the SunVox modular synthesizer library.

Features

• High-level Pythonic API with context managers, properties, and type hints
• Low-level 1:1 wrappers of the C sv_* functions
• Full access to modules, controllers, patterns, and playback
• Thread-safe slot locking

Installation

pip install pysunvox

Quick Start

import time
from pysunvox import SunVox

with SunVox(sample_rate=44100) as sv:
    with sv.open_slot(0) as slot:
        slot.load("song.sunvox")
        print(f"Song: {slot.name}, BPM: {slot.bpm}")
        slot.volume = 256
        slot.play_from_beginning()
        time.sleep(10)
        slot.stop()

Command-Line Interface

pysunvox provides a CLI for common operations:

# Show help
pysunvox --help

# Display project information
pysunvox info song.sunvox

# List all modules in a project
pysunvox info song.sunvox --modules

# Show detailed module info (including controllers)
pysunvox info song.sunvox --module 1

# List all patterns
pysunvox info song.sunvox --patterns

# Scan and analyze all songs in a directory
pysunvox songs /path/to/songs

# Scan recursively
pysunvox songs /path/to/songs -r

# Play a project
pysunvox play song.sunvox

# Play with options
pysunvox play song.sunvox --duration 30 --volume 200 --line 0

# Show version information
pysunvox info --version

CLI Commands

Command	Description
info <file>	Show project metadata (name, BPM, TPL, duration, counts)
info <file> -m/--modules	List all modules with type, name, and flags
info <file> -M/--module <id>	Show detailed module info including controllers
info <file> -p/--patterns	List all patterns with tracks, lines, and position
info --version	Show pysunvox and SunVox library versions
songs <dir> [-r]	Scan and analyze all songs in a directory
play <file>	Play a project (-d duration, -v volume, -l start line)

API Overview

High-Level API

The high-level API provides Pythonic classes with context managers:

from pysunvox import SunVox, Slot, Module, Pattern

# Initialize engine and open a slot
with SunVox(sample_rate=44100) as sv:
    with sv.open_slot(0) as slot:
        # Load and play a project
        slot.load("project.sunvox")
        slot.play()

        # Access song properties
        print(f"BPM: {slot.bpm}, TPL: {slot.tpl}")
        print(f"Length: {slot.length_lines} lines")

        # Work with modules
        for i in range(slot.num_modules):
            module = slot.get_module(i)
            if module.exists:
                print(f"Module {i}: {module.name} ({module.type})")

        # Create modules (requires lock)
        with slot.lock():
            synth = slot.new_module("Generator", "MySynth", x=256, y=256)
            synth.connect_to(0)  # Connect to Output

        # Access module controllers
        ctl = synth.get_controller(0)
        print(f"{ctl.name}: {ctl.value} (range: {ctl.min_value}-{ctl.max_value})")
        ctl.value = 128

        # Work with patterns
        with slot.lock():
            pattern = slot.new_pattern("MyPattern", tracks=4, lines=32)
            pattern.set_event(track=0, line=0, note=60, vel=128, module=synth.num + 1)

        # Save the project
        slot.save("modified.sunvox")

Low-Level API

Direct access to sv_* functions via the _core module:

from pysunvox import _core

# Initialize
_core.init(None, 44100, 2, 0)
_core.open_slot(0)

# Load and play
_core.load(0, "song.sunvox")
_core.play_from_beginning(0)

# Query state
print(f"BPM: {_core.get_song_bpm(0)}")
print(f"Current line: {_core.get_current_line(0)}")

# Cleanup
_core.stop(0)
_core.close_slot(0)
_core.deinit()

Constants

from pysunvox import (
    # Note commands
    NOTECMD_NOTE_OFF,
    NOTECMD_ALL_NOTES_OFF,
    NOTECMD_PLAY,
    NOTECMD_STOP,

    # Init flags
    SV_INIT_FLAG_NO_DEBUG_OUTPUT,
    SV_INIT_FLAG_OFFLINE,
    SV_INIT_FLAG_AUDIO_FLOAT32,

    # Module flags
    SV_MODULE_FLAG_EXISTS,
    SV_MODULE_FLAG_GENERATOR,
    SV_MODULE_FLAG_EFFECT,
)

Supported Platforms

Pre-built wheels are available for:

• macOS: x86_64, arm64
• Linux: x86_64, aarch64 (glibc only, no musl/Alpine)
• Windows: AMD64

Python versions: 3.10, 3.11, 3.12, 3.13, 3.14

Building from Source

Requires the SunVox library for developers.

# Install dependencies and build
make sync
make build

# Run tests
make test

# Build wheel with bundled library
make wheel

# Clean build artifacts
make clean

Windows Build Requirements

Building on Windows requires:

• Visual Studio 2022 (or compatible MSVC toolchain)
• CMake 3.15+
• Python development headers

The build process automatically generates an import library (sunvox.lib) from the DLL using Visual Studio's lib.exe. Wheel packaging uses delvewheel to bundle the SunVox DLL.

License / Credits

All rights for SunVox and its developer library reserved to its author, Alexander Zolotov.

See: https://warmplace.ru

Powered by SunVox (modular synth & tracker) Copyright (c) 2008 - 2024, Alexander Zolotov nightradio@gmail.com, WarmPlace.ru