Risa User Guide

Hello, and welcome! Thank you for trying Risa.

Guide version: Risa v2.3.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

Tracker Structure

The basic structure should feel familiar to LSDJ users:

• The song screen arranges chains over time.
• Chains arrange phrases.
• Phrases contain notes, instruments, and FX commands.
• Instruments define the sound used by notes.
• Tables provide per-tick modulation patterns.
• Grooves control row timing.

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 ZSAW instruments. DMC instruments select samples from the built-in or patched DPCM kits, and phrase notes choose which sample slot to trigger. ZSAW instruments synthesize pitched DMC playback, 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:

• PU1 can drive an auxiliary pulse attached to pulse 1.
• PU2 can drive an auxiliary pulse attached to pulse 2.

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.

Navigation and Playback

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
Hold B            Estimate selected song rows, on the song screen only
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.

On the song screen, hold B on an active selection to estimate its playback length. Playback must be stopped; if it is running, Risa shows STOP PLAY FIRST. The estimator simulates the selected song rows and tracks using the song's tempo, grooves, and hops, then shows DUR mm:ss in the status row. While CALC... is shown, press any button or D-pad direction to cancel.

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:

• Song screen chain cells.
• Chain screen phrase cells.
• Phrase screen instrument cells.
• Instrument screen table fields.

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.

For pulse and triangle tables, a left-column Lxx turns the transpose cell into a slide target offset. This target stays additive with the ordinary table transpose; L00 snaps without retriggering. Right-column pitched Lxx is ignored. DMC tables keep the separate Lxx looping sample-window behavior in either FX column.

See FX Commands for the command reference.

Pulse and Noise Instrument Envelopes

Pulse and noise instruments use the ENV. row for their default volume shape. It is edited as three two-hex-digit fields:

ENV. AA/DD/RR

The row has three envelope control values. In each value, the first digit sets a volume level and the second digit sets how quickly the sound moves toward the next volume level. Speed 1 is fastest, F is slowest, and 0 holds at the current level. For example, ENV. 32/AD/10 starts at volume 3, rises quickly to A, decays slowly to 1, then sustains there.

If A's speed digit is 0, the envelope holds at A's volume. The D and R fields are ignored and shown as --.

This instrument envelope starts when a note applies or restarts the instrument. Phrase/table Exy is still the live simple envelope command, with its own x=volume, y=rate encoding.

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.

ZSAW Instrument Settings

ZSAW instruments are melodic DMC-backed instruments for the DMC track. They use the same NES DMC playback hardware as sample kits, but synthesize a held tone with short DMC IRQ updates. In phrase rows, ZSAW notes are pitches, not kit sample slots.

TIMBR Timbre, 0..4.
ENV.  Envelope A/D/R.
TRANS Follow chain and project transpose.
TABLE Instrument table, or `--`.
T.SPD Table speed.

TIMBR selects the z-saw shape. 0 (SAW LO) and 1 (SAW HI) are saw variants anchored at the low and high ends of the DMC output range, respectively. 2 (SQU LO) and 3 (SQU HI) are square variants that alternate the envelope level with a low or high baseline. The paired variants have opposite bias/polarity and can differ slightly in their click character and interaction with the other NES channels, so choose whichever fits the mix. 4 (TRI) is triangle. Square and triangle timbres use a lower top displayed pitch than the saw timbres.

ENV. is the same A/D/R envelope shape used by pulse and noise instruments. It controls z-saw volume while the held DMC synth is active.

TRANS is on by default. When enabled, ZSAW notes follow chain and project transpose; turn it off to play the phrase note unchanged.

ZSAW does not have RATE, LOAD, or LOOP fields. Risa chooses the DMC rate from generated per-note tables, and the phrase note controls pitch.

The playable range is smaller than the pulse and triangle tracks because it is limited by the fastest DMC rate. Notes outside the range clamp to the nearest playable z-saw pitch instead of going silent.

ZSAW owns the DMC channel while a note is held. Kit samples cannot play at the same time, and Zxx DMC bias writes are ignored while z-saw is active. A held z-saw note also costs CPU during playback because the DMC IRQ is part of the synth.

Pitch FX that bend or modulate pulse/triangle notes do not retune ZSAW playback. Use note values and transpose for ZSAW pitch; Cxx, Fxx, Lxx, Pxx, and Vxx do not provide z-saw pitch modulation. Wxx rate changes and sample-window commands are for kit-style DMC sample playback.

Old projects that used WAVE instruments load as ZSAW instruments. The old wave sound is not preserved exactly; Risa maps those type-4 records to audible z-saw defaults and clamps high notes into the generated z-saw range.

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!