nanotracker-api-sdk: Skill for Codex

Author a pattern via the Local API

When to use

Any time you're writing pattern data — placing notes, building a drum loop, copying / shifting cells, creating new patterns, arranging the order list, changing tempo. All of this goes through nanotracker_execute.

The contract

nanotracker_execute {
  "commands": [ /* one or more LocalApiCommand */ ],
  "opts": { "undoDescription": "human-readable label", "dryRun": false }
}

• opts.undoDescription is required unless dryRun is true.
• Whole batch is validated, then either fully applied or fully rejected. One undo entry per batch.
• Hard limits: 10,000 commands, 64 patterns created, 1 MiB payload, 20 batches/sec.

Common cell ops

{ "op": "setCell",    "patternId": 0, "row": 0,  "channel": 0,
  "cell": { "note": 49, "instrument": 1, "volume": 64 } }

{ "op": "setNoteOff", "patternId": 0, "row": 8,  "channel": 0 }

{ "op": "clearCell",  "patternId": 0, "row": 0,  "channel": 0 }

{ "op": "setRange",   "patternId": 0, "rowStart": 0,
  "channels": [0, 1, 2],
  "cells": [
    [ {"note": 49, "instrument": 1, "volume": 64}, {}, {} ],
    [ {}, {"note": 53, "instrument": 1, "volume": 48}, {} ]
  ] }

setRange is much cheaper than many setCell commands when you're filling a region. The cells array is [row][channelIndex] where channelIndex indexes into the channels array, not into the project's channel list.

Note encoding

• Tracker note 1 = C-0, note 49 = C-4 (middle C, MIDI 60), note 97 = note-off, note 0 = empty.
• tracker = midi - 11.
• volume: 0xFF means "use the sample's default" — not 255 dB.

Note-offs

A note-off ends the currently-playing voice on a channel. In the pattern editor this is the == cell. Use the dedicated setNoteOff op:

{ "op": "setNoteOff", "patternId": 0, "row": 48, "channel": 0 }

It writes the canonical cell { note: 97, instrument: 0, volume: 0xFF, effect: 0 } — the same shape you'd place by typing ==. setCell with { note: 97 } works too but merges — the old instrument and volume fields stay on the cell, which reads as a note-off that also holds an instrument, which is almost never what you want. Prefer setNoteOff.