DUET docs: the grid and the two sides (summary)

Four user pages of duet (m64's own tracker, not yet published): the SID half (the-duet.md), the sid-wizard half (sid-wizard.md), the impulse-tracker half (impulse-tracker.md) and the shared pattern editor (pattern-editor.md). Together they describe how one grid carries IT channels, real SID voices, synth columns and a SID-Wizard module's tracks.

Key claims#

The SID setup (PROJECT page, F12)#

• The SETUP section holds up to four SID chips. SHIFT+LEFT/RIGHT walk a chip through off > 8580 > 6581 > off; switching the first chip on turns an [IT] session into a [DUET] and puts that chip's three SID columns on the grid (headers 1:1 1:2 1:3, chip:voice); each further chip adds three more. Every chip has its own MODEL and PAN; [ MOVE SIDS HOME ] returns the SID columns to their fixed home at the end of the grid.
• QUALITY is one knob for every chip — how reSID resamples the chip clock to the audio rate: FAST (cheapest, aliases), INTERP, RESAMPLE (band-limits, costliest). Model, pan and quality all change live, without stopping the song, and all are saved in the project (.zon).
• The DUST and DUSK rows under the chips arm the synth slots (see s-duet-docs-dust-dusk).

The SID columns' language#

• A SID column plays S## instruments — sid-wizard instruments held in the project's pool (load a .swi or import from a module).
• The instrument field takes an S## number, $3F for legato (L=, the next note slurs in without a restart), or a nibble effect $4x–$7F (waveform, sustain, release, chord); ENTER on an empty field lists them.
• The effect field is two hex bytes (effect number + data) from SID-Wizard's own list: slides, portamento, vibrato, waveform and ADSR sets, table jumps, detune, pulse width, cutoff. The nibble families ride effect $17 — a volume translated from an IT block lands as 17 5x, a sustain.
• The note field carries no note-FX in an IT song — only a real .swm has them. Note off (===) gates the voice.
• The cells live in the song's .it as ordinary pattern bytes; only the project's SID setup makes them mean SID — which is why a duet is saved as a project.

Co-play, and mute/solo by voice#

• A co-play ([CO]) pairs the .it with a real .swm instead of armed chips: the module's tracks appear beside the channels, playing on the IT song's clock, with subtunes, tempo programs and the W## bank all present. + CO-PLAY (SWM...) on the PROJECT page pairs (and, pressed again, unpairs); duet song.it tune.swm starts paired. A session has one SID half or the other — armed chips must be switched off before pairing.
• Ctrl+M (or ALT+F9) mutes the column under the cursor, ALT+F10 solos it, and on the SID side the column is a voice. The receipts name where each mute is saved: 1:1 MUTED (saved in the project) (one voice of one chip), SW01 MUTED (saved in the project) (one track of the co-play module), CH01 MUTED (saved in the song) (an IT channel, kept in the .it as other trackers keep it). Solo (SOLO 1:1 on (1 soloed)) leaves one voice ringing alone.

The project page#

• Top to bottom: SONG (name, author, GLOBAL VOL, MIX VOL, speed/tempo, IT CHANNELS, hop sizes) · FILE OPERATIONS (OPEN, NEW, NEW IT, NEW SWM..., + CO-PLAY, SAVE, SAVE AS, EXPORT WAV, and with chips on EXPORT SID -> .SWM) · SETUP (the SID setup) · FILES (what the open project holds).
• Headless, duet --sid-channels 4,5,6 song.it a.swi ... binds SID voices onto IT channels directly.

The SID-Wizard side ([SWM] sessions and co-plays)#

• A track column on the grid is a phrase — the header names both (SW01:03↕28: track 1, phrase $03, 28 rows) and every column ends at its own length. +/- page through phrases on a track column; F6 loops the phrases on screen as a combination.
• The note column has effects of its own: ENTER lists vibrato amplitudes $60–$6F (a placed one reads vb0–vbF, SHIFT+LEFT/RIGHT dial it), portamento, sync and ring on/off, gate on/off; === plays as SID-Wizard's gate-off.
• SWM SONG face (F11; in a co-play TAB from the SONG page): the subtune strip, then one order list per track — tracks advance independently, "which is how SID-Wizard songs breathe". Keys: 0–F set the phrase, SHIFT+arrows count it, n repeats the row's entry below, N places the first unused phrase, DEL drops the position. Entry kinds (Ctrl+P lists them): PHRASE (0–F), TRANSPOSE (t, semitones from the next pattern on), MAIN VOLUME (v), TRACK TEMPO (s), SEPARATOR RULE (+). ENTER on a phrase entry opens it in the pattern editor; SHIFT+ENTER opens the whole row (all tracks together); U## is a jump to another subtune.
• Subtunes: a module holds several songs; SHIFT+LEFT/RIGHT on the strip pick one, [+ SUBTUNE] adds one, F5 plays the one shown.
• Tempo: the strip's TEMPO is the subtune's default, shown as a pair (6/4) when it is a funktempo. The TEMPO pane holds the module's tempo programs (◀ 01/3E ▶), each a looping list of tempos played row after row, sharing a 119-byte budget; values 0–127 per row; effects $12/$15 (main and track tempo program) start one from the grid.
• The SWI editor (a W## in a module's bank, an S## in a project's pool): parameters ADSR (two bytes), HARD-RST and HR (the hard-restart ADSR, frame count and type), VIB, OCTAVE, default CHORD, ARP speed, MULTISPEED rates for pulse and filter (see multispeed), WF1 (first-frame waveform), TABLE-RESET; SIZE 46/120 counts bytes against SID-Wizard's budget. Below, the three instrument-tables side by side — WF ARP DET, PULSE, FILTER — plus the CHORD pane, "SID-Wizard's own table programs, byte for byte"; table jumps are $09–$0B in the effect list. SPACE jams the instrument while editing.
• Chords: a bank of 32 (◀ 01/20 ▶) shared by the whole module (in a duet, by the project); a chord is a list of semitone offsets ending in RETURN (hold the last note) or LOOP (cycle); played by arp $7F, FX $7x / big-FX 07 (see chord-arpeggio).
• [ NEW SWM... ] asks for the size first: .swm 1 SID, 3 tracks, ins cap 36 · .sws 2 SIDs, 6 tracks, cap 29 · .swt 3 SIDs, 9 tracks, cap 26 · .swq 4 SIDs, 12 tracks, cap 22. A duet's SID columns can leave as a real module: [ EXPORT SID -> .SWM ] (the chip count picks the extension), or --export-swm headless.

The Impulse Tracker side#

• Everything lives in the song's .it and plays the same in other IT players. The SOUNDS switch on the PROJECT page picks SAMPLES mode (the grid's instrument column names P## slots directly) or INSTRUMENTS mode (I## instruments); a loaded song opens in the mode it was written in.
• The I## instrument has five faces — GENERAL · MAP · VOL · PAN · PITCH. GENERAL: NNA (CUT / CONTINUE / NOTE-OFF / FADE — see new-note-actions), DUP + DCA (duplicate check and its action), FADEOUT, INS-VOL 0..128, PAN / P-PAN (pitch-pan spread around CENTRE), RANDOM vol/pan, CUTOFF / RESONANCE (the IT filter's start values, -- = untouched). MAP is one row per key (sample + note; a spreads the row under the cursor to every key). VOL/PAN/PITCH are the three instrument-envelopes: a switch row (on/off, SUS band, LOOP band, CARRY; on PITCH also FILTER, turning it into a filter envelope — toggles e, c, f, s/S, l/L) over a node table (TICK and VAL; SHIFT+arrows drag a node, ENTER inserts at the midpoint, BKSP removes).
• The P## sample: C5 rate (SHIFT+UP/DOWN a semitone, SHIFT+LEFT/RIGHT one hertz), VOL/SVOL (default note volume 0..64 and global level), PAN, LOOP/SUS (FORWARD, PINGPONG or off; SUS is a second loop used only while the note is held — see sample-looping), VIB auto-vibrato. Buttons: [LOAD], [SAVE] (writes the sample as a .wav beside the song at its own C5 rate, at once), [CLEAR]/[CLR+NOTES], [OSC], [EDIT]. EDIT SAMPLE works on a copy — CROP TO LOOP, REVERSE, NORMALIZE, dialed fades; an EDITS line stacks them, SPACE auditions, only its [ SAVE ] commits.
• The order list (F11, SONG page — see orderlist): each position names a pattern; the footer counts the song (233 orders · 179 patterns · 1 unused · total 41:07). Keys: 0–F type the pattern (hex), SHIFT+arrows count, n repeats below, N places a NEW section (first unused or fresh pattern), DEL/BKSP drop, +/- place +++ (skip) and --- (end), ENTER opens the pattern, F7 plays from the position. The CHANNELS table beside it holds per-channel VOL, PAN (L/M/R hard left/centre/right, S surround) and a MUTE cell; with SID chips on, the same table places the chips' voices.
• Song knobs (what the .it header holds): GLOBAL VOL 0..128 (the volume Vxx moves), MIX VOL 0..128 (48 is Impulse Tracker's default, 128 is unity; both scale everything, SID and synth columns included), SPEED/TEMPO (as Axx/Txx set them), IT CHANNELS (lowering it parks columns — they keep playing; raising brings them back), CH-HOP / P-HOP (how far Ctrl+LEFT/RIGHT and Ctrl+"+"/"-" hop).

The pattern editor (the grid)#

• F2 from anywhere; TAB flips to the instruments page. Rows numbered in hex. Fields per column kind: channel CH01 = note · instrument · volume · effect (letter + value); SID column 1:1 and track SW01:03↕28 = note · instrument · effect (two hex bytes); synth column DUST1/DUSK1 = note · instrument · volume · effect. Where a shorter pattern ends, a rule (── 20 ──) closes the column and the longer ones continue. A │ seam separates channels from the SID/synth blocks; SPLIT (Ctrl+T) pins those blocks to the right edge.
• Cursor: arrows move field to field (a channel's effect field is two stops: letter, value); PGUP/PGDN jump 16 rows; Ctrl+LEFT/RIGHT hop CH-HOP columns; ALT+LEFT/RIGHT jump between zones (channels / synth block / SID block / co-play tracks) and wrap; ALT+UP/DOWN add and remove IT channels from the grid.
• EDIT and JAM: SPACE toggles. In JAM the letter rows play the current instrument without writing.
• Typing: piano rows Z S X D C V ... (lower octave), Q 2 W 3 E R ... (upper), [ ] octave; ` note off ===, 1 note cut ^^^, ~ fade ~~~, . clears. Instrument fields are shifting hex (type both digits); a channel's volume field is decimal 0–64; SHIFT+LEFT/RIGHT transpose a note a semitone, SHIFT+UP/DOWN an octave. A typed note carries the current jam instrument (footer P01 S01, stepped with ; and ').
• Patterns: +/- step, Ctrl+G goes to a number, L sets pattern length (hex, up to $C8). Every pattern number exists from the start; the order list decides what plays.
• Views: Ctrl+V cycles a co-play's grid view — IT (channels alone), UNITY (both on one row axis), POLY (a shorter pattern wraps and repeats until the longest ends), SWM (tracks alone). Ctrl+W cycles channel width (FULL / NOTE+INS / NOTE); Ctrl+F follow; F3 cycles the note pulse's seven looks.
• Marks and blocks: ALT+B starts a mark that follows the cursor over rows and fields; ENTER/ALT+E holds it; ALT+D grows it a rung at a time (beat, bar, rest of column, channel, whole side); ALT+L marks the channel, twice the side. Verbs: ALT+C/ALT+Z copy/cut, ALT+P paste, ALT+M paste into empty fields only, ALT+SHIFT+P translate paste, ALT+Q/ALT+A transpose ±1 semitone (+SHIFT ±1 octave), ALT+S set every note to the current instrument, DEL clear. Ctrl+P opens the block command list (plus INTERPOLATE, REVERSE ROWS, ROLL UP/DOWN, BOUNCE TO AUDIO = Ctrl+B).
• Cross-column paste: same kind → the block lands whole. Between the two kinds of SID column (a duet's SID channels and a module's tracks) notes and effects cross (one effect language); only the instrument stays behind (different banks) — ALT+S stamps the destination's. Onto a different kind altogether, plain paste carries notes alone; ALT+SHIFT+P (translate paste) carries the effects too, respelled: an IT H64 vibrato lands on a track as 0825 (SID-Wizard vibrato, nearest depth/rate), a volume becomes a sustain nibble, an IT arpeggio becomes a chord (the report names the chord slots written). A TRANSLATE REPORT names every conversion and drop (2 FX ACROSS, 0 DROPPED); an effect crosses only as letter+value pair.
• Sync markers: ALT+G opens the SYNC MARKER popup on the cursor's cell — an inaudible point with a decimal value 0–65535, saved in the .zon, delivered to a host program (demo, game) playing the song through libduet when the row plays. Markers sit only on IT-grid columns (channel, SID or synth column); a SID-Wizard track refuses, and so does a bare [IT] session (a marker lives in the .zon). A reused pattern fires its marker at every occurrence; a marked cell wears an amber wash.
• The FX picker: ENTER on a volume or effect field lists what that field can take — the IT letters A–Z, the ten volume commands, the SID-Wizard effects by number, and DUET's send commands a–d — with a teaching line per entry. On a track's or SID column's empty instrument field it opens the INS-FX list (legato + nibble effects); on a filled one it jumps to that instrument.
• Undo: Ctrl+Z/Ctrl+Y per target (the pattern being edited is its own undo target); Ctrl+U opens the undo history, ENTER travels to an entry.

Practical takeaways#

• The two SID column kinds speak one effect language, so material moves freely between a duet's SID channels and a module's tracks; the translate paste (ALT+SHIFT+P) is the road for IT ↔ SID material and reports every conversion.
• IT vibrato → SID-Wizard vibrato, IT volume → sustain nibble (17 5x), IT arpeggio → chord: a concrete crosswalk between the impulse-tracker and sid-wizard effect worlds (compare effect-command-crosswalk).
• MIX VOL 48 = Impulse Tracker's default, 128 = unity — useful when levelling an .it for other players.
• SID-Wizard workflow survives intact inside DUET: independent per-track order lists, transpose/tempo entries, funktempo pairs, tempo programs on a 119-byte budget, 32 shared chords, .swi instruments with the standard three tables.

Notable quotes#

• "SID columns in an IT song carry no note-FX — only a real .swm has them."
• "Each cell places a phrase at that position; the tracks advance independently, which is how SID-Wizard songs breathe."
• "TRANSLATE: an effect is its letter AND its value - the mark holds only one stop of the pair."

Relevance to the wiki#

First full description of duet's editing surface: the SID setup, both sides' vocabularies, the cross-column translate paste and the sync markers. Grounds the duet entity rewrite and cross-references the SID-Wizard concepts (hard-restart, instrument-tables, shuffle-funktempo, multispeed, chord-arpeggio) as they appear in a modern host.

Pages touched#

duet (rewritten by the maintainer from this and the sibling summaries s-duet-docs-formats, s-duet-docs-dust-dusk, s-duet-docs-clipboard, s-duet-docs-sounds-mixer-bounce).