Instruments¶

pylsdj.Instrument is a wrapper class allowing manipulation of a project’s instrument. It is typically accessed by looking up the instrument in its parent song’s instruments field.

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.

Raises ImportException:
Parameters:	index – the index into which to import filename – the file from which to load
	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

Usage Examples¶

# 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.

Vibrato¶

The pulse, wave, and kit instrument types all have a vibrato control, accessed through their vibrato fields, which has the following structure:

class pylsdj.Vibrato(data)¶

direction¶: ‘down’ or ‘up’

type¶: hf (for high frequency sine), sawtooth, saw or square

Pulse Instruments¶

class pylsdj.PulseInstrument(song, index)¶

automate¶: if True, automation is on

envelope¶: the noise instrument’s volume envelope (8-bit integer)

name¶: the instrument’s name (5 characters, zero-padded)

phase_finetune¶: detune pulse channel 1 down, channel 2 up; in LSDJ, this is PU FINE (4-bit integer)

phase_transpose¶: detune pulse channel 2 this many semitones; in LSDJ, this is PU2 TUNE (8-bit integer)

sound_length¶: the instrument sound’s length, a 6-bit integer or unlimited if the sound plays forever

sweep¶: modulates the sound’s frequency; only works on pulse 1 (8-bit integer)

table¶: a `pylsdj.Table` referencing the instrument’s table, or None if the instrument doesn’t have a table

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

vibrato¶: instrument’s vibrato settings

wave¶: the pulse’s wave width; 12.5%, 25%, 50% or 75%

Wave Instruments¶

class pylsdj.WaveInstrument(song, index)¶

automate¶: if True, automation is on

name¶: the instrument’s name (5 characters, zero-padded)

play_type¶: how to play the synth sound; once, loop, ping-pong, or manual

repeat¶: the synth sound’s repeat point (4-bit integer)

speed¶: how fast the sound should be played back (4-bit integer)

steps¶: length of the synth sound (4-bit integer)

synth¶: the wave’s synth settings

table¶: a `pylsdj.Table` referencing the instrument’s table, or None if the instrument doesn’t have a table

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

vibrato¶: instrument’s vibrato settings

volume¶: the sound’s volume; 0 through 3

Noise Instrument Fields¶

class pylsdj.NoiseInstrument(song, index)¶

automate¶: if True, automation is on

envelope¶: the noise instrument’s volume envelope (8-bit integer)

name¶: the instrument’s name (5 characters, zero-padded)

s_cmd¶: free or stable. When free, altering noise shape with the S command can sometimes mute the sound. When stable, sound will never be muted by accident. My understanding is that this setting exists for backwards-compatibility of behavior in old LSDJ instruments

sound_length¶: the instrument sound’s length, a 6-bit integer or unlimited if the sound plays forever

sweep¶: modulates the sound’s frequency; only works on pulse 1 (8-bit integer)

table¶: a `pylsdj.Table` referencing the instrument’s table, or None if the instrument doesn’t have a table

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

Kit Instrument Fields¶

class pylsdj.KitInstrument(song, index)¶

automate¶: if True, automation is on

dist_type¶: algorithm used when two kits are mixed together; clip, shape, shap2 or wrap

half_speed¶: if true, play samples at half their normal speed

keep_attack_1¶: loop sample in kit 1 and start playing from beginning

keep_attack_2¶: loop sample in kit 2 and start playing from beginning

kit_1¶: the index of the first kit in LSDJ’s kit list

kit_2¶: the index of the second kit in LSDJ’s kit list

length_1¶: the length of kit 1’s sound (0 means ‘always play the sample to the end’ and is displayed as AUT in LSDJ)

length_2¶: the length of kit 2’s sound (0 means ‘always play the sample to the end’ and is displayed as AUT in LSDJ)

loop_1¶: loop sample in kit 1 and start playing from an offset

loop_2¶: loop sample in kit 2 and start playing from an offset

name¶: the instrument’s name (5 characters, zero-padded)

offset_1¶: kit 1’s loop start point (if loop_1 is True and keep_attack_1 is False)

offset_2¶: kit 2’s loop start point (if loop_2 is True and keep_attack_2 is False)

pitch¶: sample pitch shift (8-bit integer)

table¶: a `pylsdj.Table` referencing the instrument’s table, or None if the instrument doesn’t have a table

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

vibrato¶: instrument’s vibrato settings

volume¶: the kit’s volume; 0 to 3