How Sampultu talks to the KORG volca sample 2

Plain text copy for agents and scripts: volca-sample-2-interop.md

What software has to do to work reliably with a volca sample 2 over USB MIDI: the documented protocol, and the behaviour we found by measuring that the documentation does not mention.

Sampultu is an independent app and is not affiliated with, sponsored or endorsed by KORG Inc. KORG and volca sample 2 are named only to identify the hardware this describes.

Unless a line says otherwise, numbers were measured on 2026-11-06 on one volca sample 2, firmware 1.1, in single channel mode on channel 1, from macOS over USB, with standalone CoreMIDI probes and confirmed in the app. Android and iOS timing has not been measured to the same depth. Treat this as what one unit does, and test yours.

The short version

  1. Use the UMP input path on Apple platforms. The legacy packet list path silently drops parts of large replies.
  2. Never send a request while another is outstanding.
  3. Never send a note during an upload.
  4. A sequencer note destroys any SysEx reply it lands in, on the device itself. Reads during playback must expect that and retry, off the beat.
  5. A pattern write to the panel only takes whole while the sequencer runs. Stopped, it is acknowledged and mostly ignored.
  6. Upload acknowledgements arrive after the flash commit, so their timeout must scale with the size of the sample.
  7. Audio is 31,250 Hz, 16-bit, signed, little-endian, mono. Nothing else.

Identifying the device

  • Search Device: send F0 42 50 00 55 F7. The reply gives the channel and the model ID, family 2D 01, member 08 00.
  • Universal Identity Request also works: F0 7E 7F 06 01 F7.
  • SysEx is strictly request and response. The device never volunteers SysEx, and pressing panel buttons sends none.
  • It answers the documented dumps and the Identity Request. Functions 0x10, 0x12, 0x72 and 0x1C are dead on this device. There is no pattern select: loading a pattern is a read of the stored pattern followed by a write to the current sequence.

Function IDs

IDMeaning
0x11Current sequence dump request
0x1BSample space dump request
0x1DSequence dump request
0x1ESample header dump request
0x1FSample data dump request
0x41Current sequence dump
0x4BSample space dump
0x4DSequence dump
0x4ESample header dump
0x4FSample data dump

Status replies: 0x23 ACK, 0x24 busy, 0x25 sample memory full, 0x26 data format error.

Sample format

The volca stores one thing, and converters have to land on it exactly.

  • 31,250 Hz, 16-bit signed little-endian, mono.
  • 200 slots. The sample header is 32 bytes: name of 24 ASCII characters, length in frames as a little-endian u32, level as u16, speed as u16. Default level is 0xFFFF and default speed is 0x4000.
  • Non-printable name characters should be replaced before writing. Sampultu uses an underscore.
  • The sample space dump reports 14-bit sector counts, and a sector is 4,096 bytes.
  • A sample is one single SysEx message, however long. A 3.2 MB transfer is one message.

Timing

OperationMeasured
Sample header read0.6 ms each, 200 in 128 ms with no rest
Read throughputabout 460 KB/s
16 patterns247 ms
Delete of an empty slot0.6 ms
Write commitabout 60 KB/s, regardless of send pacing

The device is much faster than early assumptions, ours included. An app that takes 10 seconds to read 200 headers is waiting on itself.

Overlapping requests lose replies and gain nothing. With a window of 2, 199 of 200 replies arrived. With 16, 185 of 200.

Writes commit at about 60 KB/s whether sent at 1 KB per 2 ms or as one 16 MB burst, and every variant read back identical. Pacing is not what protects the device on macOS. Android is unmeasured.

After deleting a big sample the next request can answer busy for under half a second. A 68.6 ms pause appears in every dump, so do not treat a short silence as the end of a reply.

Uploads

The ACK comes after the flash commit. Audio of 44.8 seconds waited 44.4 seconds after the send finished. A flat 30 second timeout fails anything over about 31 seconds of audio. Sampultu waits a base timeout plus one second per 50,000 bytes.

A status byte during an upload kills it. A note sent mid-transfer ends the upload with no reply, the old audio survives, the device then answers busy for a while, and data sent during that busy state is ignored in silence. Sampultu holds short messages until outgoing SysEx is finished, passes real-time bytes, and drops auditions rather than queueing them.

After an aborted upload, wait for a header ACK before sending data.

Header-only writes are ignored.

Reads during playback

This is the least obvious behaviour we found.

A note from the running sequencer destroys any SysEx reply it lands in, on the device itself. Nothing downstream can repair it. After the note, every remaining data byte arrives as a running-status note-off. One capture held 346,903 fake note-offs against 2,057 real note-ons. Real sequencer note-offs have velocity 0x40, which is how they are told apart.

In one run, 53 of 174 sample reads were hit and 0 of 96 pattern reads, because a pattern reply is short enough to fit between steps.

Usually the wreck ends with a SysEx end carrying no data, and the device answers the next request within 1 ms. If the note lands early there is no end at all. The device ignores requests made during a wreck. CoreMIDI also flushes a false end just before the note.

It took three layers to survive this:

  1. The native MIDI parsers drop the wreck and report an empty F0 F7 at its end. Real note-ons still pass through.
  2. The UMP parser holds a pending F7 behind channel messages until the line is quiet, with a 2 ms settle and a 200 ms stall limit.
  3. Dart gives each read a deadline sized to its reply, one second plus the bytes at 300 KB/s, and retries.

Retries must be off the beat. A 1,000 ms deadline is exactly 8 steps at 120 BPM, so every retry met the same note. Sampultu staggers silent retries by 47 ms.

Writing a pattern to the panel

A 0x41 write only takes whole while the sequencer runs. Stopped, the device sends an ACK and the panel keeps its samples, steps, mutes, levels and name. Active Steps and trigger delay do land, which makes the failure look like a partial bug in your own encoder.

The fix is to wrap it: Start, write, Stop. That takes 21 ms and fires no notes for holds up to about 800 ms. The volca echoes received Start and Stop to the host about 1 ms later, so those echoes need hiding for a short window. Sampultu uses 40 ms. 150 ms hid a real Start.

Sampultu treats the sequencer as running if the transport says so or a note arrived in the last 2.5 seconds.

Pattern blob

The PTST format is in Korg's MIDI implementation document, tables 1 to 3. An edit dump is 9,076 bytes and a pattern dump 9,077, including the header and excluding F0 and F7. Three details the tables do not spell out:

  • Active Steps are bytes 8 and 9, and they take over 0x41.
  • Per-step trigger delay lives at offsets +48 to +63, biased by 128. A raw 0 means use the stored knob, and it is ignored unless the part's motion bit is on. A value of 38 moved a note 2 clocks, and 127 moved it 4.
  • Mute is inverted on the wire, so a zeroed part reads as muted.

What the device tells you

Output is sparse.

  • Sequencer notes echo as 90 nn 7F and 80 nn 40, with note = 48 + part.
  • Muted parts still echo their notes, so mutes cannot be inferred from the echo.
  • CC 91 (reverb mix) is sent only when the knob moves.
  • Clock is free-running and never stops.
  • Start and Stop from the panel are sent. Per-part knobs send only during motion record.
  • It is silent on mutes, motion, part select and stopped knobs.

Real-time control

  • Function settings, the ones set by holding FUNC at power-on, can be neither read nor written. The channel comes from Search Device. Mode and RX Short Message can only be found by a closed-loop probe: change something, read it back.
  • In single channel mode CC 3 and 35 do nothing, silently. Sample select is NRPN: CC 98 = part * 12 + 9 with part counted from 0, then CC 6 for the MSB and CC 38 for the LSB. Samples 0 to 99 use MSB 0 and 100 to 199 use MSB 1.
  • CC 7 and note 48 work in both modes, so they are the safe things to test with.

Seeking

Song Position is plain SPP with one MIDI beat per step, F2 p 00, and it only works from a settled stop: about 400 ms after Stop, followed by Continue. That worked 15 times of 15. It is ignored during playback and at about 150 ms after Stop. F2 00 0p restarts at step 1.

START and calibration

  • START 127 reaches 90.0% of a sample, plus or minus 0.3%. It does not reach the end.
  • SPEED 64 is the recorded rate, and +32 is one octave, confirmed by ear.
  • AMP DECAY 127 is no decay and 0 is a blip. A zero-filled pattern is not neutral: zero SPEED is quarter speed and zero HIGH CUT is nearly silent.

CoreMIDI

On macOS the volca's source reports MIDI 1.0 over UMP, so UMP is the native transport and MIDIPacketList is the emulated one. With two input ports on one source, receiving the same dump at the same moment over the same cable, the legacy port completed 0 of 4 reads and the UMP port 4 of 4. Legacy loses whole 48-byte USB packets. If large reads truncate, it is not your cable.

Getting audio onto it well

At 31,250 Hz the band ends at 15.6 kHz, so the converter matters more than usual. This is what Sampultu does from version 1.0.7, with numbers from test signals run through the old and new code.

Resampling. A Kaiser-windowed sinc centred on the output Nyquist, 62 zero crossings a side with beta 10.06. From 44.1 kHz:

TonePrevious filterNow
13 kHz-0.1 dB0.0 dB
14 kHz-3.0 dB0.0 dB
15 kHz-14.8 dB0.0 dB
15.5 kHz-28.5 dB-3.2 dB
16.5 kHz aliased to 14.75 kHz-52 dB-106 dB
18 kHz aliased to 13.25 kHz-63 dB-110 dB

Sixty seconds of audio takes about 1.2 seconds on a Mac.

No clipping. Filtering makes peaks ring past full scale, and float files can simply be over. The whole sample is turned down just enough rather than clamped.

Mono that cannot vanish. Stereo folds by averaging, unless the fold loses more than 6 dB beyond what uncorrelated stereo would, in which case the sides were cancelling and the louder channel is used instead.

Dither. Resampled audio is reduced to 16 bits with high-passed triangular dither. True silence stays silent, and a fixed seed means one file always converts to the same bytes.

One road. Compressed files are decoded to 44,100 Hz stereo by the platform and then take the same path as a WAV, so the quality does not depend on the phone.

Nothing touches audio that needs no conversion. A file already at 31,250 Hz, 16-bit and mono comes through bit for bit.

Accepted directly: WAV (8, 16, 24, 32 and 64-bit PCM, 32 and 64-bit float, mu-law, A-law, RF64, RIFX) and AIFF or AIFC (PCM, sowt, float, mu-law, A-law). Everything else goes to the platform's decoder, as does any WAV our reader cannot follow, such as ADPCM.

Patterns as MIDI files

Sampultu writes a pattern as a format 0 file at 96 ticks to the beat: the notes the volca's sequencer sends, note 48 + part, on one channel, a sixteenth to a step, velocity 127. Skipped steps and muted parts are left out because they make no sound. The tempo is the one the volca is running at, read from its clock.

Importing lays a file's first bar onto a pattern's steps and keeps its samples, levels, motion and name. Notes 48 to 57 go to their own parts. Several channels mean one part per channel, as MULTI mode has it. Anything else gives each pitch a part, lowest first, so a DAW's drum loop lands on the ten parts in order. A muted part that receives notes is unmuted, and the loop length becomes the bar the notes reach, in whole beats.

Testing

integration_test/wire_under_playback_test.dart in the Sampultu repo covers playback behaviour on real hardware. It writes only slot 199 and restores the panel, and it needs the app closed, because an open app reacts to Start echoes.

Short want lengths in a probe silently truncate a backup, so use exact dump lengths or read until quiet.

Known gaps

  • Android and iOS timing is not measured to this depth. The Android parser is unit tested only.
  • One stuck-read failure was seen once in about 15 hardware runs: a read during playback stayed silent through every retry until the process ended, while a new client could still talk to the device. Unexplained.
  • The analogue path after the volca's DAC is unmeasured, so nothing here compensates for it.