API Documentation

This module mirrors most of the C++ API of libsidplayfp 1.8. Some methods of the public interfaces are not implemented in the corresponding wrapper classes. These are methods which are meant for internal use, are deprecated or very rarely useful.

SID Player and Configuration

SidPlayfp is the main interface to play sidtunes and control the emulation. For an example see Usage example.

class libsidplayfp.SidPlayfp

Main interface to libsidplayfp to play tunes.

cia1_timerA

Get the CIA 1 Timer A programmed value.

config

Current engine configuration. (see SidConfig)

configure()

Configure engine using SidPlayfp.config. An SidPlayfpConfigError is raised if engine could not be configured.

debug(enable, file_=None)

Enable debugging.

From sidplayfp.h:

Control debugging. Only has effect if library have been compiled with the --enable-debug option.

error

Current error message.

fast_forward(percent)

Set fast-forward factor.

Parameters:

percent (int) – fast-forward factor in percent.

info

Get the current player information. (see SidInfo)

is_playing

Check if the engine is playing or stopped.

load(tune)

Load a tune.

Parameters:

tune (SidTune) – sidtune to load

Raises:

SidPlayfpLoadError – if an error occurs

play(buffer, length=None)

Run the emulation and produce samples to play if a buffer is given. If length is not given, it will be calculated from len(buffer) // 2.

Parameters:

• buffer (a mutable buffer) – buffer to write samples to

• length (int) – length of buffer (assuming 16-bit samples)

Returns:

number of produced samples

Return type:

int

set_roms(kernal, basic=None, character=None)

Set ROM images.

Parameters:

• kernal (buffer) – Kernal ROM

• basic (buffer) – Basic ROM, generally only needed for BASIC tunes.

• character (buffer) – character generator ROM

stop()

Stop the engine.

time

The current playing time in seconds.

class libsidplayfp.SidConfig(obj=None)

An instance of this class is used to transport emulator settings to and from the interface class. Writing to any property is allowed (and necessary to configure the engine).

default_c64_model

Intended c64 model when unknown or forced. (see C64Model)

default_sid_model

Intended sid model when unknown or forced. (see SidModel)

fast_sampling

Faster low-quality emulation (only reSID/fp)

force_c64_model

Force the model to default_c64_model ignoring tune’s clock setting.

force_sid_model

Force the sid model to default_sid_model.

frequency

Sampling frequency.

left_volume

Left channel volume.

playback

Playback mode. (see Playback)

power_on_delay

Power on delay cycles.

right_volume

Right channel volume.

sampling_method

Sampling method. (see SamplingMethod)

second_sid_address

address of 2nd sid

sid_emulation

Selected sid emulation (SidBuilder)

Reading this property always returns a SidBuilder, however as this is an abstract class the internal object is actually one of ReSIDfpBuilder, ReSIDBuilder.

Writing to this property supports any of these classes as it is casted internally.

third_sid_address

address of 3rd sid

class libsidplayfp.SidInfo(obj)

This provides information about the sid engine implementation.

basic_desc

Description of the loaded basic ROM image

channels

Number of output channels (1-mono, 2-stereo)

chargen_desc

Description of the loaded character ROM image

credits

Array of library credits

driver_addr

Address of the driver

driver_length

Size of the driver in bytes

kernal_desc

Description of the loaded kernal ROM image

maxsids

Number of SIDs supported by this library

name

Library name

power_on_delay

Power on delay

speed_string

Describes the speed current song is running at

version

Library version

SidTunes

Sidtunes can be loaded from files using SidTune. Using its method SidTune.get_info() some information can be gathered about the tune. Note however that sidtunes do not store their intentional playtime. That must be provided separately, e.g. by using a songlength database and SidDatabase.

class libsidplayfp.SidTune(filename=None, source_buffer=None)

Load a sidtune from a file.

filename specifies a path to a sidtune to load. If source_buffer is given a sidtune is created from that buffer using read(). If neither is given, an error is raised. This is in contrast too the underlying C++ library libsidplayfp which allows to create a SidTune instance in an invalid state.

Parameters:

• filename (bytes) – path to sidtune

• source_buffer (bytes) – buffer of complete sidtune

Raises:

SidTuneError – if loading a given tune fails

From SidTune.h:

To retrieve data from standard input pass in filename “-“. If you want to override the default filename extensions use this contructor. Please note, that if the specified “fileName” does exist and the loader is able to determine its file format, this function does not try to append any file name extension. See “SidTune.cpp” for the default list of file name extensions. You can specify “fileName = 0”, if you do not want to load a sidtune. You can later load one with open().

create_MD5()

Calculates the MD5 hash of the tune.

Returns:

md5 of this tune

Return type:

bytes

get_info(song_num=None)

Retrieve sub-song specific information. If song_num is None, information about the current active song is returned.

Parameters:

song_num (int or None) – song number get information

Returns:

Information about song

Return type:

SidTuneInfo

load(filename)

Load a sidtune into an existing object from a file.

Raises:

SidTuneError – if loading a given tune fails

read(source_buffer)

Load a sidtune into an existing object from a buffer.

Raises:

SidTuneError – if reading a given tune fails

select_song(song_num)

Select subtune. song_num=0 selects the starting song.

Parameters:

song_num (int) – sub-song to load

Returns:

active song number, 0 if no tune is loaded

Return type:

int

status

Determine current state of object. Upon error condition use status_string to get a descriptive text string.

status_string

Error/status message of last operation.

class libsidplayfp.SidTuneInfo(obj)

This interface is used to get values from SidTune objects.

Create instances of this class by calling SidTune.get_info().

c64data_len

Length of raw C64 data without load address.

clock_speed

The tune clock speed. (see SidClock)

comment_strings

Tune (MUS) comments.

Returns:

tune information

Return type:

list

compatibility

Compatibility requirements. (see SidCompatibility)

current_song

The tune that has been initialized.

data_file_len

Length of single-file sidtune file.

data_filename

A first file: e.g. “foo.sid” or “foo.mus”.

fix_load

Whether load address might be duplicate.

format_string

The name of the identified file format.

info_filename

A second file: e.g. “foo.str” or None if no second file.

info_strings

Return tune information: Song title, author and release information.

Returns:

tune information

Return type:

list

init_addr

Init Address.

load_addr

Load Address.

path

Path to sidtune files.

play_addr

Play Address.

reloc_pages

Number of pages available for relocation.

reloc_start_page

First available page for relocation.

sid_chips

Get the number of SID chips required by the tune.

get_sid_chip_base(i)

The SID chip base address(es) used by the sidtune.

Parameters:

i (int) – chip number

Return type:

int

sid_chip_bases

Get a list of SID chip base addresses. Uses SidTuneInfo.get_sid_chip_base() to retrieve SidTuneInfo.sid_chips base addresses and returns them as a list.

get_sid_model(i)

The SID chip model(s) requested by the sidtune.

Parameters:

i (int) – chip number

Return type:

SidModel

sid_models

Returns a list of SID chip models of length SidTuneInfo.sid_chips (uses SidTuneInfo.get_sid_model() internally).

song_speed

Intended speed.

songs

The number of songs.

start_song

The default starting song.

Enumerations

Several enumerations to support SidConfig, SidInfo and SidTuneInfo.

class libsidplayfp.SidModel

An enumeration.

UNKNOWN = 0

SID model unknown.

MODEL6581 = 1

MOS6581 required.

MODEL8580 = 2

MOS8580 required.

ANY = 3

Any SID model can be used.

class libsidplayfp.C64Model

C64 model

DREAN = 3

DREAN

NTSC = 1

NTSC

OLD_NTSC = 2

Old NTSC

PAL = 0

PAL

class libsidplayfp.Playback

Mono or stereo playback.

MONO = 1

Mono playback (1 channel)

STEREO = 2

Stereo playback (2 channels)

class libsidplayfp.SamplingMethod

Sampling method.

INTERPOLATE = 0

residfp: ZeroOrderResample

RESAMPLE_INTERPOLATE = 1

residfp: TwoPassSincResample

class libsidplayfp.SidClock

An enumeration.

ANY = 3

Any clock can be used

NTSC = 2

NTSC clock required

PAL = 1

PAL clock required

UNKNOWN = 0

Clock unknown

class libsidplayfp.SidCompatibility

An enumeration.

C64 = 0

File is C64 compatible

PSID = 1

File is PSID specific

R64 = 2

File is Real C64 only

BASIC = 3

File requires C64 Basic

Exceptions

class libsidplayfp.SidError

Base class for Exceptions from libsidplayfp.

class libsidplayfp.SidPlayfpConfigError

Error raised while setting SidPlayfp.config.

class libsidplayfp.SidPlayfpLoadError

Error raised by SidPlayfp.load() while loading a tune.

class libsidplayfp.SidTuneError

Error raised when loading or reading a SidTune fails.

SidBuilder Classes

To play a SidTune, an emulation of the SID chip is needed. There are three options: ReSIDfpBuilder and ReSIDBuilder, which provide the actual emulation implementation. SidBuilder is the abstract (only in the C++ implementation) base class of these but does not provide an implementation. You probably should never need to create an instance of this class by yourself.

class libsidplayfp.SidBuilder(obj)

Wrapper for sid builders. Base class of ReSIDfpBuilder and ReSIDBuilder.

Parameters:

obj (sidbuilder*) – sid builder to wrap

libsidplayfp offers two additional methods sidemu *lock(EventContext *env, SidConfig::sid_model_t model); and void unlock(sidemu *device); which are not offered by this wrapper class. These functions are intended for internal use to provide the player with the required SID chips even though they are part of sidbuilder’s public interface.

avail_devices

Number of available devices, 0 if any number is available.

create(sids)

Create sids sid emulators.

Parameters:

sids (int) – the number of required sid emulators

Returns:

number of created sid emulators

Return type:

int

credits

credits of this sid builder.

error

current error message

filter(enable)

Toggle sid filter emulation.

Parameters:

enable (bool) – Enable of disable filter emulation

name

The builder’s name

status

current error status: True if no error occurred, False otherwise

used_devices

The number of used devices, 0 if none are used.

class libsidplayfp.ReSIDfpBuilder(name=None, cast=None, cdata=None)

ReSIDfp Builder Class, inherits from SidBuilder.

If name passed, a new ReSIDfpBuilder will be created. If cast is given, the underlying object will be casted to a ReSIDfpBuilder without further checks. If cdata is given, it will be treated as a cffi-cdata object and casted to a ReSIDfpBuilder.

If a new builder is created this owns that builder object, so be sure that the instance of this class is not garbage collected until you don’t need the builder any more.

If no new builder is created but just casted, this instance does not own the underlying cdata object.

Parameters:

• name (str) – Name of new builder (creates new object)

• cast (SidBuilder) – wrapper class to cast into ReSIDfpBuilder

• cdata (cffi cdata (usually <cdata 'struct sidbuilder *'>)) – (for internal use) cdata object to cast into ReSIDfpBuilder*

filter_6581_curve(filter_curve)

Set 6581 filter curve.

Parameters:

filter_curve (double) – filterCurve from 0.0 (light) to 1.0 (dark) (default 0.5)

filter_8580_curve(filter_curve)

Set 8580 filter curve.

Parameters:

filter_curve (double) – curve center frequency (default 12500)

class libsidplayfp.ReSIDBuilder(name=None, cast=None, cdata=None)

ReSID Builder Class

For an explanation on the parameter see ReSIDfpBuilder.

bias(dac_bias)

The bias is given in millivolts, and a maximum reasonable control range is approximately -500 to 500.

Songlength Database Utility

SidDatabase can be used to read song lengths from the songlength database (songlength.txt from HVSC). It is included in libsidplayfp however it is not actually required to play sidtunes.

class libsidplayfp.SidDatabase

An utility class to deal with the songlength database.

close()

Close the songlength database.

error

Get descriptive error message.

length(tune_or_md5, song_num=None)

Get the length of the selected subtune in seconds. If a SidTune is passed the length of the currently selected subtune is returned.

Parameters:

• tune_or_md5 (SidTune or bytes) – SidTune or md5 of a SidTune

• song_num (None or int) – song number of subtune (required if an md5 is passed)

Returns:

tune length in seconds

Return type:

int

Raises:

SidDatabaseError – if length could not be determined

open(filename)

Open the songlength DataBase.

Parameters:

filename – full path to songlength db

Raises:

SidDatabaseError – if songlength db could not be loaded

class libsidplayfp.SidDatabaseError

Exception raised by SidDatabase

Access to internal C wrapper

As libsidplayfp is written in C++, it was necessary to write a wrapper for all methods of all public interface’s classes. cffi makes that effort rather simple. All wrapper methods are available from libsidplay.lib, however these are not documented as that api is not guaranteed to be stable. It is available from the source at libsidplayfp/libsidplayfp_wrapper.cpp and the corresponding header file. An interface to the ffi is provided by libsidplayfp.ffi. This can be used to cast the internal cdata objects.