Risa User Guide

Documentation

Hello, and welcome! Thank you for trying Risa.

Guide version: Risa v2.0.0.

Risa follows the handheld tracker workflow established by LSDJ, and this guide assumes you're already familiar with it. If song, chain, phrase, instrument, table, groove, or hexadecimal editing concepts are new to you, start with the LSDJ manual:

https://www.littlesounddj.com/lsd/latest/documentation/LSDj_9_2_6.pdf

This guide focuses on what is different in Risa. It is not a replacement for the LSDJ manual or the full command reference.

If you encounter bugs or have suggestions for the software, please send an email to risa@laamaa.fi.

Happy tracking!

A note about save compatibility

Back up saves before upgrading Risa builds. Starting with v2.0.0, songs can use up to 0xFE phrases, so the save catalog region is 32 KB instead of the older 40 KB layout.

Very full older save catalogs may not fit into the current layout as-is. Export or delete songs before upgrading, then migrate or import the remaining material again.

Tracker Structure

The basic structure should feel familiar to LSDJ users:

Risa is inspired by LSDJ, but it targets NES hardware and does not have every LSDJ feature. When behavior differs, trust Risa's on-screen behavior and the Risa-specific reference pages.

NES Channels

Risa's main tracks are NES APU channels:

PU1  Pulse 1
PU2  Pulse 2
TRI  Triangle
NOI  Noise
DMC  DPCM sample playback

The pulse channels are the closest match to the Game Boy pulse channels. They are useful for leads, basses, chords, arps, and sharp percussion.

The triangle channel is a fixed-shape voice. It is often useful for bass and smooth melodic lines, but it does not have normal volume control like a Game Boy pulse or wave channel.

The noise channel is for drums, hats, snares, texture, and noise tones. Its pitch and mode behavior are NES-specific and vary between console regions.

The DMC channel can play kit-based DPCM samples or melodic WAVE instruments. DMC instruments select samples from the built-in or patched DPCM kits, and phrase notes choose which sample slot to trigger. WAVE instruments use built-in generated DPCM wave banks, so phrase notes behave as pitches instead.

The channels of the NES mixer are not perfectly independent in level, and DMC playback can change how the triangle and noise feel in the mix.

MMC5 Aux Pulses

Risa can also use two MMC5 expansion pulse channels:

These are not full extra tracker tracks. They share their parent pulse track's timing, instrument context, and mute state, and they do not have their own tables or FX. Aux notes are row-triggered snapshots rather than independent sequencer lanes; for example, ECHO keeps the delayed note from following later parent pitch or table changes. They are best used for detuned doubles, intervals, echoes, and simple second-note events.

See AUX Pulse Channels for more details.

Common LSDJ-style navigation still applies:

SELECT + RIGHT   Drill into the thing under the cursor
SELECT + LEFT    Drill back out
SELECT + DOWN    Open the groove screen from most tracker screens
SELECT + UP      Open settings from song or chain
START            Play or stop from the current context
SELECT + START   Start song playback from the current song row context
B + LEFT/RIGHT   Move across tracks or related chains
B + UP/DOWN      Page or move between related rows where supported

The exact target of drill-in depends on the current screen and cursor position. For example, song drills into a chain, chain drills into a phrase, phrase can drill into an instrument, and an Axx table command can drill into the referenced table.

Project Settings

Open project settings with SELECT+UP from the song or chain screen. This screen contains saved project settings and project actions:

TEMPO     Default project tempo.
TRANS     Global transpose.
THEME     Color theme.
FONT      UI font.
KEYREP    D-pad repeat delay and rate.
PREVIEW   Note preview while editing.
CLN SONG  Clear unused chains and phrases.
CLN INST  Clear or merge unused instruments and tables.
LD/SAVE   Open load/save.

TEMPO normally edits 040..295 BPM. Editing upward past 295 with a fresh press selects 4X, which runs one sequencer tick on every sub-frame: exactly four ticks per video frame. Holding right/up to auto-repeat stops at 295; press again to enter 4X. Phrase Txx commands still use only the normal tempo-byte range.

TRANS changes the global transpose. Edits wrap through the byte range, and the live playback transpose is applied when A is released.

Editing, Selection, and Cut

Basic value editing shortcuts:

A                 Place or audition a value, depending on the cell
A + D-pad         Edit the value under the cursor
A + B             Clear the current cell
SELECT + A        Paste when the clipboard matches the current screen

On phrase note cells, A+B on an empty cell inserts OFF instead of clearing. OFF is a note-off event: when playback reaches it, Risa cancels any pending delayed note, stops the current table, and silences the channel. On PU1/PU2, it also stops the matching MMC5 aux pulse. Press A+B on an OFF cell again to clear it back to empty. The same toggle applies to the AUX note column when it is visible.

Region selection:

SELECT + B        Start selection, or cycle the selection extent
D-pad             Extend the selection
B release         Copy the selected region
A + B             Cut the selected region
SELECT            Cancel an already active selection

The important LSDJ difference is cut: Risa cuts a selected region with A+B, not LSDJ's usual CUT shortcut. This keeps cut tied to the same clear/cut gesture used for a single cell.

Selection extent cycles by screen. On song, SELECT+B cycles from a rectangle to full selected row or rows, then exits. On phrase, chain, groove, and table screens, it cycles rectangle, full column, whole visible/editable area, then exits.

Cloning and Deep Cloning

Risa cloning uses a two-step gesture:

SELECT + B        Arm clone on a cloneable cell
SELECT + A        Clone
SELECT + A again  Deep clone the new chain, on the song screen only

Cloneable cells include:

If a clone is armed, SELECT+A clones instead of pasting and changes the current cell to use the new copy.

On the song screen, cloning a chain first creates a new chain that still points at the original phrases. Press SELECT+A again there to deep-clone the new chain's phrases too, making the copied song section independent before editing.

Commands and Tables

Risa uses familiar tracker command ideas, but command meanings are Risa-specific. Phrase rows have one FX slot. Table rows have two FX slots, but only commands that make sense inside a table are available there.

See FX Commands for the command reference.

DMC Instrument Settings

DMC instruments are sample instruments. Their parameters do not behave like pulse, triangle, or noise synth parameters:

RATE  Playback rate index, 0..F.
LOAD  Initial DMC output counter / DC bias, 00..7F.
LOOP  OFF, ON, or KIT.
KIT   DPCM kit used by this instrument.
TABLE Instrument table, or `--`.
T.SPD Table speed.

RATE sets the DMC playback rate. If it is 0, Risa uses the selected kit sample's stored default rate when the sample is triggered. A phrase Wxx command can change the live DMC rate.

LOAD sets the DMC output counter ($4011) when the sample is triggered. In tracker terms, it is the starting DC bias: it can affect loudness, triangle/noise mix interaction, and clicks. Phrase Zxx changes the live bias immediately; a later DMC row with an instrument value applies that instrument's LOAD before triggering the sample.

LOOP controls sample looping. OFF forces one-shot playback, ON forces looping, and KIT follows the loop flag stored in the selected kit sample.

KIT selects which DPCM kit this instrument uses. DMC phrase notes select sample slots inside that kit. Available samples depend on the ROM, and kit sample slots are not shifted by phrase or global transpose.

TABLE binds a table to the DMC instrument, or -- for none. T.SPD sets how quickly it advances. DMC tables are useful for rate changes, retriggers, and sample-window movement; see DMC Sample Window Commands for Fxx and Lxx.

WAVE Instrument Settings

WAVE instruments are melodic DMC-backed instruments for the DMC track. They use the same NES DMC playback hardware as sample kits, but with generated looped waveforms built into the ROM. In phrase rows, WAVE notes are pitches, not kit sample slots.

LOAD  Initial DMC output counter / DC bias, 00..7F.
LOOP  OFF, ON, or KIT.
SOUND Wave sound, 1 or 2.
TABLE Instrument table, or `--`.
T.SPD Table speed.

LOAD sets the DMC output counter ($4011) when the WAVE note is triggered. It can change the starting bias and click character of the note. A phrase Zxx command can still change the live DMC bias.

LOOP controls whether the generated wave playback loops. WAVE is intended for looped melodic playback, so ON is the normal setting.

SOUND selects the built-in wave family. 1 is the rounded organ-like sound. 2 is the brighter saw/stair sound. The second sound has a one-shot plucked startup character, but the loop itself stays steady.

WAVE does not have a RATE field. Risa chooses the DMC playback rate and sample length from generated per-note metadata, and the phrase note controls pitch. Unlike kit-based DMC sample slots, WAVE notes follow phrase transpose and project TRANS.

Pitch FX that bend or modulate pulse/triangle notes do not retune WAVE playback. Use note values and transpose for WAVE pitch; Cxx, Fxx, Lxx, Pxx, and Vxx do not provide WAVE pitch modulation.

TABLE binds a table to the WAVE instrument, or -- for none. T.SPD sets how quickly it advances. WAVE runs through the DMC path, so DMC bias and retrigger behavior can affect it, but Wxx rate changes and sample-window commands are mainly for kit-style DMC sample playback.

Thanks

Johan Kotlinski, for creating the LSDJ tracker and perfecting the handheld tracker workflow

Special thanks to people who have helped with testing, bug reports, early music and moral support: Ess, Avrilcadabra, cTrix, DEFENSE MECHANISM, DJ Diskmachine, HangOnGetReady, Infu, Mikey303, Nullsleep, Perhaps Bry, Tommitytom

Thank you to everyone who helped shake out rough builds and make the tracker better!