DUET docs: the system clipboard and its text format (summary)

How pattern blocks move between duet (m64's tracker, not yet published), openmpt, schism-tracker and any program that writes text to the OS clipboard. system-clipboard.md is the DUET-side reference; clipboard-format.md is a self-contained producer's guide for generators (such as 037-lab). This is one of the very few written specifications of the OpenMPT/ModPlug clipboard text format anywhere.

Key claims#

Two clipboards, five verbs#

• DUET has two clipboards that never touch: ALT+C/ALT+P work through an internal buffer nothing else sees; ALT+SHIFT+X opens the SYSTEM CLIPBOARD list — the same block verbs through the OS clipboard, as text. The verbs: ALT+SHIFT+C COPY, ALT+SHIFT+Z CUT, ALT+SHIFT+V PASTE, ALT+SHIFT+M MIX PASTE (only into empty fields), ALT+SHIFT+T TRANSLATE PASTE (onto another column kind with effects respelled). With no block marked, ALT+SHIFT+X marks the whole side the cursor stands on first.
• A paste lands top-left at the cursor, on as many channels as the text has and as many rows as the pattern has left (clipped at the end); it is one undoable edit, and the seam rules of the pattern editor apply unchanged (see s-duet-docs-grid-and-sides).
• The paste writes the fields the clipboard carries — from the first field that holds anything to the last. A notes-only text places notes and leaves the channel's instruments, volumes and effects standing; a text with an effect somewhere writes every field up to the effect, empties included. "So a melody tool need not know what is already on the channel."

The IT text format (OpenMPT's, exactly)#

An IT block is spelled exactly as openmpt and schism-tracker spell theirs, "so the clipboard moves between the three without conversion":

ModPlug Tracker  IT
|C-501v64A0F|...........
|...........|D#5..v40...
|===........|G-501......

• Header line: anything whose last three characters are IT. OpenMPT and DUET write ModPlug Tracker IT (note the two spaces before IT); Schism writes Pasted Pattern - IT. S3M and MPT headers read the same; XM and MOD read too, but their effect letters are another alphabet and are dropped with a count in the receipt.
• Then one line per row; each channel is | followed by eleven characters, four fields:

• Rows end in \r\n (OpenMPT's spelling); a bare \n reads too. Spaces read like dots. Write all eleven characters of every cell — OpenMPT and Schism are strict about the widths; DUET forgives a short cell (|C-5 alone is a note), a ragged row, and lowercase.
• A field the mark did not reach is spelled as spaces (OpenMPT's own convention: a mark of the volume column alone copies | v40 ); OpenMPT and Schism honour that on paste, and DUET's reader looks only at what the fields carry, so either spelling lands the same.

The SID dialects (DUET SID / DUET SW / DUET DUST / DUET DUSK)#

• A DUST, DUSK, SID or SID-Wizard block has no OpenMPT twin — its effect byte is another language — so those blocks wear DUET's own header word over the same grammar. DUET DUST and DUET DUSK carry the IT face byte for byte (the instrument is the D##/K## slot). DUET SID (a duet's SID column) and DUET SW (a SID-Wizard track) carry NOTE(3) INS(2) FX(2) PARAM(2) — nine characters, the three bytes in hex, the note in that column's own names, SW mnemonics included (vb3, gt+, ===).
• DUET SID and DUET SW are interchangeable on paste: they speak the same effect language, so either header lands whole on either kind of SID column — the note crosses converted, the effect verbatim. Only the instrument stays behind (the same byte selects the S## pool on one side, the module's bank on the other); ALT+S stamps the destination's. OpenMPT refuses the DUET headers, "which is right".

The producer's guide (for a generating program)#

• Give an app two copy buttons: COPY IT (ModPlug Tracker IT; pastes into DUET, OpenMPT and Schism — the default) and COPY SID (DUET SID; one button covers both SID column kinds — "Send DUET SID and stop thinking about it").
• A bare note cell: IT C-5........ (note + .. + ... + ... = 11 chars); SID C-5...... (note + .. + .. + .. = 9 chars).
• Portamento goes on the row of the note glided to: IT — tone portamento G + two hex digits in the effect field (G-5.....G08); SID — SID-Wizard effect 03 with the hex speed as its parameter (G-5..0308). See pitch-slide-and-portamento.
• The app writes no instruments (..): notes carry across silent until voiced — in DUET, mark the block and ALT+S stamps the selected instrument. The clipboard never carries instruments, samples or chord tables.
• If COPY IT text is pasted at a SID column, notes land but IT effects do not (different languages) — ALT+SHIFT+T (TRANSLATE PASTE) respells them.
• Verified examples ("these paste correctly today, checked against the running tracker"):

ModPlug Tracker  IT          DUET SID
|C-5........                 |C-5......
|E-5........                 |E-5......
|...........                 |.........
|G-5.....G08                 |G-5..0308

Plumbing, limits, headless#

• The terminal build shells out on the keypress: pbpaste/pbcopy on macOS; on Linux wl-paste/wl-copy, then xclip, then xsel. The window build (duet-gui) asks SDL, on Windows too. DUET never reads the clipboard on its own; the terminal's own paste (Cmd+V) types into the grid as keystrokes, which is not this.
• Refusals speak: no pattern block, an empty clipboard, a block of nothing but dots. Text with pieces DUET has no IT spelling for (an XM block's effects, a volume word IT lacks) pastes what it can: PASTED 4 ROWS x 2 CH - 3 PIECES OF THE TEXT HAVE NO IT SPELLING.
• Limits: DUET's send commands a–d are DUET's own — OpenMPT drops them, and Schism reads a lowercase letter in the effect place as a volume command. Anything past a cell's eleven characters (an MPTM block's extra columns) is ignored. The clipboard is text: samples, instruments and chord tables do not travel.
• Headless: --clipboard-file <path> makes the system clipboard a file (COPY writes it, PASTE reads it; the machine's clipboard is untouched) — a test copies in one run and pastes in another.

Practical takeaways#

• Any script or web tool can hand a tracker a melody: put the header line plus |-rows on the clipboard and paste. For IT targets keep every cell exactly 11 characters; for DUET's SID columns use the 9-character DUET SID dialect.
• C-5 = middle C is the alignment rule when generating from MIDI note numbers (60 → C-5).
• Blocks copied out of OpenMPT/Schism paste straight into DUET and vice versa — an actual interchange path between PC trackers, no file export needed.

Notable quotes#

• "Send DUET SID and stop thinking about it."
• "So a melody tool need not know what is already on the channel."

Relevance to the wiki#

The OpenMPT/ModPlug clipboard text format is documented almost nowhere else; these two pages pin its header rule, field widths, decimal-vs-hex split and the space-for-unmarked-fields convention, plus DUET's own SID dialects — exactly what 037-lab's export buttons target.

Pages touched#

duet (maintainer rewrite) · openmpt (clipboard text format section) · schism-tracker (clipboard interchange) · 037-lab (producer rules on the DUET side).