api-load-sample

Load a sample via the Local API

When to use

The user has files in <project>/samples/ (or wants to know what's there) and wants to bring one into an instrument slot, optionally snapping its length to a number of rows.

Project-required

Every call in this flow returns { ok: false, errors: [{ code: "noProject" }] } if no project is open. Tell the user to open one via PROJECT > EXPLORER. Don't retry.

Three steps

# 1. See what's available (recursive — includes subfolders)
nanotracker_assets_list

# 2. Load a file into a slot (1..31). fileName can contain "/" for subfolders —
#    pass the full 'name' field from list() verbatim.
nanotracker_assets_load { "slot": 1, "fileName": "Drums/break.wav" }
nanotracker_assets_load { "slot": 2, "fileName": "kick.wav" }

# 3. (Optional) Snap a loop to N rows at the project's bpm/speed
nanotracker_execute {
  "commands": [{ "op": "conformSampleToRows", "sampleId": 1, "rows": 16 }],
  "opts": { "undoDescription": "conform amen to 1 bar" }
}

Subdirectories

assets.list walks <project>/samples/ recursively (max depth 8) and returns entries with three name-like fields:

{
  "name":      "Drums/break.wav",              // full path, forward-slash, pass to load
  "leafName":  "break.wav",                    // just the filename
  "directory": "Amens",                        // parent folder (empty at top level)
  "size":      1494512,
  "lastModified": 1473590967000
}

For a library organised by pack (e.g. Drums/, Basses/, One-Shots/Synths/) the list is flat — one entry per file — but the directory field makes it easy to filter or group in your own code.

conformSampleToRows computes the stretchRatio so the sample plays for exactly rows rows at the project's current bpm/speed. Useful for drum loops that should fit one bar (16 rows by default), two bars (32 rows), etc.

Direct stretch

If you know the exact ratio:

{ "op": "setSampleStretchRatio", "sampleId": 1, "ratio": 2 }