What is LSDJ?¶

Little Sound DJ (or LSDJ) is a program for the Nintendo Game Boy that turns the humble Game Boy into a music workstation. More information about LSDJ can be found at the LSDJ website and the LSDJ wiki.

What is pylsdj?¶

pylsdj is a suite of tools for reading, writing and editing LSDJ’s save data, which includes the user’s saved songs and instruments.

Why?¶

Before pylsdj, the suite of tools available for interacting with LSDJ’s save data was sparse and fragmented. People who wanted to share and re-use instruments between songs or move songs between saves were met with partial solutions at best. pylsdj endeavors to be a one-stop solution for save data reading, writing and editing.

How Can I Help?¶

First and foremost, use it! You can also try out LSMC, which is really just a GUI on top of many of pylsdj’s functions.

Second, if you find a bug, file it. I know I haven’t hit all the potential use cases for this in tests, and your input will help me find and squash bugs.

Third, if you’re a developer, write some tests. If you find a feature pylsdj doesn’t have and you want to take a crack at it, fork the code and send me a pull request. I’m ready and willing to receive contributions from the community.

Known Limitations¶

pylsdj only works on save data for LSDJ versions 3.0.0 and above. Given that version 3.0.0 came out back in 2006 and marked a significant change in file structure, I feel like this is a reasonable point at which to freeze backwards-compatibility.

There are parts of the codebase that are much more messy than I’d like them to be, but perfect is the enemy of done.

Usage Examples¶

from pylsdj import filepack

# Here's a list of bytes
bytes = [0x12, 0x12, 0x12, 0x15, 0x15, 0x10]

# We can compress those bytes
compressed = filepack.compress(bytes)

# ... and then decompress them again
decompressed = filepack.decompress(compressed)

API Documentation¶

pylsdj.filepack.compress(raw_data)¶

Compress raw bytes with the filepack algorithm.

Parameters:	raw_data – an array of raw data bytes to compress
Return type:	a list of compressed bytes

pylsdj.filepack.decompress(compressed_data)¶

Decompress data that has been compressed by the filepack algorithm.

Parameters:	compressed_data – an array of compressed data bytes to decompress
Return type:	an array of decompressed bytes

Loading and Saving¶

If you’re writing an application using pylsdj, you’ll probably want to load and store it.

Accessing and Editing a .sav File’s Projects¶

A .sav file’s project_list field contains an ordered list of that file’s projects. You can insert, modify and delete pylsdj.Project objects in this list to modify the .sav file’s contents. Note that changes to the .sav file will not persist unless it is saved.

Usage Examples¶

from pylsdj import SAVFile

# Load .sav file from lsdj.sav
sav = SAVFile('lsdj.sav')

# Load a .sav file, passing loading progress to a callback
def my_callback(message, step, total_steps, continuing):
  print '%(m)s: %(s)d/%(t)d complete!' % { m: message, s: step, t: total_steps }

sav = SAVFile('lsdj.sav', my_callback)

# Get the file's project map (maps slot number to Project)
projects = sav.projects

# Save a savfile as lsdj_modified.sav, passing the same progress callback
# from the above example
sav.save('lsdj_modified.sav', my_callback)

API Documentation¶

class pylsdj.SAVFile(filename, callback=<function _noop_callback at 0x7fe18c5ecd70>)¶

project_list¶

The list of pylsdj.Project s that the .sav file contains

save(filename, callback=<function _noop_callback at 0x7fe18c5ecd70>)¶

Save this file.

Parameters:	filename (str) – the file to which to save the .sav file callback (function) – a progress callback function

Usage Examples¶

from pylsdj import Project, load_srm, load_lsdsng

# Load a .srm file
srm_proj = load_srm("test1.srm")

# Load a .lsdsng file
lsdsng_proj = load_srm("test2.lsdsng")

# Convert the .srm project to .lsdsng
srm_proj.save_lsdsng("test1_conv.lsdsng")

# Get the srm project's song
song = srm_proj.song

API Documentation¶

pylsdj.load_lsdsng(filename)¶

Load a Project from a .lsdsng file.

Parameters:	filename – the name of the file from which to load
Return type:	pylsdj.Project

pylsdj.load_srm(filename)¶

Load a Project from an .srm file.

Parameters:	filename – the name of the file from which to load
Return type:	pylsdj.Project

class pylsdj.Project(name, version, size_blks, data)¶

name = None¶

the project’s name

save(filename)¶

Save a project in .lsdsng format to the target file.

Parameters:	filename – the name of the file to which to save
Deprecated:	use save_lsdsng(filename) instead

save_lsdsng(filename)¶

Save a project in .lsdsng format to the target file.

Parameters:	filename – the name of the file to which to save

save_srm(filename)¶

Save a project in .srm format to the target file.

Parameters:	filename – the name of the file to which to save

size_blks = None¶

the size of the song in filesystem blocks

song¶

the song associated with the project

version = None¶

the project’s version (incremented on every save in LSDJ)

Notes¶

A song is defined by its sequence. A sequence consists of a number of sequence steps. Each step specifies a chain for each of the Game Boy’s four audio channels (pulse 1, pulse 2, wave, and noise). See Chains for more information on how Chains are structured.

A song’s sequence is stored in its sequence field as a two-dimensional dictionary of chains.

from pylsdj import Sequence

# Get the chain in step $3 of PU2 from the sequence
curr_chain = song.sequence[Sequence.PU2][0x3]

# Get that same chain from the global chains table
curr_chain_another_way = song.chains[curr_chain.index]

# Get chain $2D from the global chain table
chain_two_d = song.chains[0x2d]

Instruments¶

The sound of a note is determined by an instrument. An instrument can also refer to a synth or a macro table to control how it behaves over time.

A song contains global tables for instruments, synths and macro tables. These are stored in the song’s instruments, synths and tables fields, resp.

Appearance and Playback Behavior¶

Songs also have a number of fields that control the appearance of LSDJ and its synchronization setting. A complete overview of what all these settings do is out of this document’s scope; see the API documentation below for a list of supported settings.

API Documentation¶

class pylsdj.Song(song_data)¶

A song consists of a sequence of chains, one per channel.

bookmarks¶

list of screen bookmarks

chains¶

the song’s chain table, represented as a list of Chain objects

clock¶

the amount of time LSDJ has been used since the last memory reset, represented as a Clock object

clone¶

chain cloning depth; one of "deep", "slim"

colorset¶

the selected LSDJ colorset

file_changed¶

1 if the file has changed since last save, 0 otherwise

font¶

the selected LSDJ font

global_clock¶

the amount of time LSDJ has been used total, represented as a Clock object

grooves¶

the song’s groove table

instruments¶

the song’s instrument table, represented as a list of Instrument objects

key_delay¶

the delay before key repeat is activated for Game Boy buttons

key_repeat¶

the key repeat speed for Game Boy buttons

phrases¶

the song’s phrase table, represented as a list of Phrase objects

prelisten¶

if non-zero, play notes and instruments while entering them

sequence¶

the song’s sequence, showing the order in which chains are played on each of the four channels

song_version¶

the song’s version number

speech_instrument¶

the song’s speech instrument settings, represented as a SpeechInstrument object

sync_setting¶

LSDJ’s sync setting; one of "off", "slave", "master", "midi", "nano", and "keyboard"

tables¶

the song’s table of macro tables, represented as Table objects

tempo¶

the song’s tempo

Usage Examples¶

# Access the second transpose in chain $05
song.chains[0x05].transposes[1]

# Access the fifth phrase in chain $53
song.chains[0x53].phrase[4]

API Reference¶

class pylsdj.chain.Chain(song, index)¶

A chain is a sequence of phrases for a single channel. Each phrase can be transposed by a number of semitones.

API Documentation¶

class pylsdj.Phrase(song, index)¶

A phrase is a sequence of notes for a single channel.

fx¶

a list of the phrase’s effects, one byte per effect

fx_val¶

a list of the phrase’s effect parameters, one byte per effect

index¶

the phrase’s index within its parent song’s phrase table

instruments¶

a list of Instruments, None where no instrument is defined

notes¶

a list of the phrase’s notes, one byte per note

song¶

a reference to the phrase’s parent song

Usage Examples¶

Get a clock’s days

>>> clock.days
5

Set a clock’s hours:

>>> clock.hours = 6

API Documentation¶

class pylsdj.clock.TotalClock(clock_data)¶

checksum¶

the clock’s checksum (days + hours + minutes)

days¶

The total number of days on the clock.

hours¶

The total number of hours on the clock.

minutes¶

The total number of minutes on the clock.

class pylsdj.clock.Clock(clock_data)¶

hours¶

The total number of hours on the clock.

minutes¶

The total number of minutes on the clock.

Importing and Exporting Instruments¶

Instruments export in what I’m calling lsdinst format, which is really just a JSON encoding of the instrument’s data.

Importing an instrument is handled by its parent song, so that it can do the necessary bookkeeping if the instrument’s type changes.

class pylsdj.Instruments(song)

import_from_file(index, filename)

Import this instrument’s settings from the given file. Will automatically add the instrument’s synth and table to the song’s synths and tables if needed.

Note that this may invalidate existing instrument accessor objects.

Parameters:	index – the index into which to import filename – the file from which to load
Raises ImportException:
	if importing failed, usually because the song doesn’t have enough synth or table slots left for the instrument’s synth or table

class pylsdj.Instrument(song, index)¶

export_to_file(filename)¶

Export this instrument’s settings to a file.

Parameters:	filename – the name of the file

# Editing a song's instrument $06
instrument = song.instruments[0x06]

# Change the instrument's name
instrument.name = "ABCDE"

# Export the instrument to a file
instrument.export_to_file("my_instrument.lsdinst")

# Import the instrument, overwriting instrument $09
song.instruments.import_from_file(0x09, "my_instrument.lsdinst")

Instrument Fields¶

All instrument types have the following fields:

• name: the instrument’s name
• type: the instrument’s type (pulse, wave, noise, or kit)

Different instruments have different additional fields, corresponding to the fields that an instrument has in LSDJ. These fields are described below.

Usage Examples¶

# Get the raw waveforms for synth $3
waves = song.synths[0x3].waves

# Get the end volume for synth $9
vol = song.synths[0x9].end.volume

API Reference¶

class pylsdj.Synth(song, index)¶

distortion¶

use "clip" or "wrap" distortion

end¶

parameters for the end of the sound, represented as a SynthSoundParams object

filter_resonance¶

boosts the signal around the cutoff frequency, to change how bright or dull the wave sounds

filter_type¶

the type of filter applied to the waveform; one of "lowpass", "highpass", "bandpass", "allpass"

index¶

the synth’s index within its parent song’s synth table

phase_type¶

compresses the waveform horizontally; one of "normal", "resync", "resync2"

song¶

the synth’s parent Song

start¶

parameters for the start of the sound, represented as a SynthSoundParams object

wave_synth_overwrite_lock¶

if True, the synth’s waveforms override its synth parameters; if False, its synth parameters override its waveforms

waveform¶

the synth’s waveform type; one of "sawtooth", "square", "sine"

waves¶

a list of the synth’s waveforms, each of which is a list of bytes

class pylsdj.SynthSoundParams(params, overwrite_lock)¶

filter_cutoff¶

the filter’s cutoff frequency

phase_amount¶

the amount of phase shift, 0 = no phase, 0x1f = maximum phase

vertical_shift¶

the amount to shift the waveform vertically

volume¶

the wave’s volume

Usage Examples¶

# Get table $4 from the song's table of tables
table = song.tables[0x4]

# Alternatively, get it from instrument $b
table = song.instruments[0xb].table

# Set the envelope in row $5 to $A6
table.envelopes[0x5] = 0xa6

# Set the value of the first effect's parameter to 5 in row $6
table.fx1[0x6].value = 5

API Reference¶

class pylsdj.Table(song, index)¶

Each table is a sequence of transposes, commands, and amplitude changes that can be applied to any channel.

envelopes¶

a list of the table’s volume envelopes

fx1¶

a list of the table’s first effects, represented as TableFX objects

fx2¶

a list of the table’s first effects, represented as TableFX objects

index¶

the table’s index within its parent song’s table of macro tables

song¶

the table’s parent Song

transposes¶

a list of the table’s volume transposes

class pylsdj.TableFX(params, table_index, fx_index)¶

command¶

the effect’s command

value¶

the command’s parameter

Speech Instrument Structure¶

The speech instrument consists of a list of words. Each word has a name, and a list of sounds. Each sound consists of an allophone and a length.

Usage Examples¶

# Get word $5 defined in the speech instrument
word = song.speech_instrument.words[0x5]

# Extract the word's allophones
allophones = [sound.allophone for sound in word.sounds]

# Change the fifth allophone to 'OY'
word.sounds[4].allophone = 'OY'

# Change the length of the 10th allophone to 5
word.sounds[9].length = 5

# Change the 3rd word's name to 'WORD'
word.sounds[2].name = 'WORD'

API Documentation¶

class pylsdj.SpeechInstrument(song)¶

song¶

the speech instrument’s parent song

words¶

a list of the speech instrument’s defined words, as Word objects

class pylsdj.Word(song, index)¶

name¶

the word’s name

sounds¶

a list of the sounds that make up the word; each sound has an allophone and a length