#Jamcorder device API

This document describes the network API exposed by Jamcorder firmware. It is written for application and tooling authors who need to discover a Jamcorder, read its state, change settings, transfer files, or stream MIDI.

Purpose: help people access their MIDI data across devices and develop extensions that interact directly with Jamcorder.

The Jamcorder API exposes 167 /api/... paths. Always use the runtime discovery endpoints instead of assuming that every firmware build has every endpoint.

Security: the API is available to anyone on your network. Only connect your Jamcorder device to a trusted network. Endpoints can change persistent settings, delete extensions, reboot the device, and more. For your protection, no API endpoint exists that can delete recordings.

#Related documentation

• JMX MIDI files — the goals, binary structure, custom events, timestamps, bookmarks, stones, and parsing requirements for Jamcorder recordings.
• Local web extensions — static webpages hosted by Jamcorder from its SD card, with access to the complete device API.

#Contents

• Quick start
• Set up Jamcorder Wi-Fi
• Concepts and API domains
• Runtime discovery and compatibility
• HTTP contract
• JSON-plus-binary uploads
• WebSockets
• Endpoint reference
• Getting started and device information
• Music and recordings
• Storage and content
• Device health and feedback
• Updates and maintenance
• Connectivity and setup
• Engineering and manufacturing
• Non-API HTTP routes
• Other transports
• JFU mode

#Quick start

#Set up Jamcorder Wi-Fi

Before using the API, connect your Jamcorder device to Wi-Fi. You can set up Wi-Fi with the Jamcorder app or with Web-based setup.

#App-based setup PREFERRED

In the Jamcorder app, open Settings → [Jamcorder name] → Wi-Fi and follow the setup instructions.

#Web-based setup

Web-based setup lets you configure Wi-Fi from a browser without the app. Hold the device button for about 1.5 seconds, join the jamcorder-xxxxxxxx Wi-Fi network, and open http://192.168.0.1. Select your home network and enter its password.

#Connect to the API

Set JAMCORDER to the device address. A Jamcorder normally advertises jamcorder.local and a secondary mDNS name based on its full UUID; /api/wifi/info reports its current IP address. An IP address is least ambiguous when multiple Jamcorders share a network.

JAMCORDER=http://jamcorder.local

# Learn which API families this firmware supports.
curl --compressed "$JAMCORDER/api/meta/capabilities"

# Get the exact endpoint list for this running build.
curl --compressed "$JAMCORDER/api/meta/endpoints"

# Read device identity.
curl --compressed "$JAMCORDER/api/identities/get"

# Rename the device.
curl --compressed \
  -H 'Content-Type: application/json' \
  -d '{"jamcorderName":"Studio Jamcorder"}' \
  "$JAMCORDER/api/identities/rename/jamcorder"

curl --compressed is recommended because JSON responses larger than 1,000 bytes are returned with Content-Encoding: deflate.

#Concepts and API domains

#Identities and names

The identities object separates stable identifiers from user-facing labels:

Use UUIDs as database and synchronization keys; use names for UI. Names are not unique and none of these fields is an authentication credential. Treat UUIDs as stable for the life of a provisioned device, but allow them to change after a factory reset or reprovisioning.

#Device state and capabilities

/api/device-state/get is a broad snapshot intended for initial application startup. It combines identities, system information, settings, connectivity, storage, MIDI, recording, lifetime statistics, and current issues. Use the smaller subsystem endpoints for later refreshes so the client transfers and parses only the state it needs.

A capabilities response says which versioned feature families the device understands. /api/meta/endpoints says exactly which calls are present in the currently running firmware. Check both when compatibility matters: capability flags are convenient feature gates, while the endpoint list is definitive for an individual URI.

#Issues, alerts, and logs

These three APIs describe different levels of device health and activity:

/api/issues/current contains unresolved issue records. /api/issues/history also includes resolved records. Both include totalRaiseCount, which increases as conditions are raised and can help a client detect change. A record may contain issue, subIssue, occurrences, isResolved, first/latest wall-clock and since-boot timestamps, time since the previous occurrence, didBuzzUser, and an attached error object.

Calling /api/issues/clear/current marks all current records resolved. It does not repair the underlying condition and does not erase history. If the problem continues, firmware can raise the issue again. Applications should display known user-actionable issues prominently and retain unknown issue names for forward compatibility.

#Recordings, assets, and MIDI stones

Jamcorder records MIDI into its native JMX asset format. The library API lists recording assets and can convert the newest recording to a standard MIDI file. An asset is associated with the Jamcorder identity that created it; a single SD card can therefore contain assets from more than one device.

A MIDI stone is an indexed chunk of a JMX recording. Stone downloads and the stone WebSocket support incremental transfer without downloading an entire asset. A negative stoneIdx counts backward from the newest stone, which is useful for tailing a recording.

The MIDI APIs have separate roles: recorder controls what is captured, commands turns configured MIDI input into device actions such as bookmarks, I/O controls live routing between DIN, USB, Bluetooth, and WebSocket, piano state summarizes held and sustained notes, and lifetime statistics tracks cumulative playing activity.

#API domain guide

#Runtime discovery and compatibility

Call these endpoints before using a feature:

An endpoint entry has this shape:

{
  "uri": "/api/identities/get",
  "mimeType": "application/json",
  "sig": "voidToJson"
}

The sig determines the HTTP method and body type:

Endpoint availability can vary by firmware build, and MIDI player endpoints are not available in current builds. Treat /api/meta/endpoints as definitive for the connected device.

#HTTP contract

#Requests

• The server listens on plain HTTP port 80.
• Use GET or POST exactly as listed. Some diagnostic endpoints mutate state despite currently being registered as GET; the catalog calls these out.
• JSON request bodies use UTF-8 and should be sent as Content-Type: application/json.
• A JSON endpoint given an empty body receives an empty JSON object internally, but required fields still fail validation.
• There is no query-string parameter model. Inputs are JSON, upload metadata, or, for wildcard page routes, part of the URI.
• The server advertises Access-Control-Allow-Origin: *. Its wildcard OPTIONS handler permits POST and all request headers.

#Success responses

JSON endpoints return 200 OK and a resource-specific JSON value. There is no universal success envelope: some mutation endpoints include apiSuccess, success, or another status field, while read endpoints return their object directly. Treat the HTTP status as authoritative and parse the schema for the specific endpoint.

Large JSON responses are zlib-wrapped and carry Content-Encoding: deflate. Standards-compliant HTTP clients normally decode this automatically when they request compressed content.

Downloads use the MIME type shown by /api/meta/endpoints. File downloads may also set Content-Disposition and Content-Length.

#Error responses

An API failure returns 400 Bad Request with JSON similar to:

{
  "error1": "directory does not exist",
  "error2": "unable to list directory",
  "errorCodeNum": 2,
  "errorCodeStr": "generic",
  "uri": "/api/files/list/overview",
  "apiSuccess": false
}

Errors accumulate as error1, error2, and so on. Known errorCodeStr values are generic, nonexistant (spelling preserved by the wire protocol), timedOut, deviceGone, and canceled.

If a streaming download fails after response bytes have begun, the server can only close the stream; it cannot replace the partial body with the JSON error object.

#JSON-plus-binary uploads (JAMCJSBN)

Six upload endpoints accept a custom body consisting of optional JSON metadata followed by raw binary bytes:

offset  size  value
0       8     ASCII "JAMCJSBN"
8       4     JSON byte length, uint32 little-endian
12      N     N bytes of UTF-8 JSON (not NUL-terminated)
12 + N  ...   binary payload

Set Content-Length to the size of the entire framed body. The binary payload begins immediately after the JSON. If the first eight body bytes are not the magic value, the server treats the entire body as binary and supplies an empty metadata object. Endpoints that require metadata, such as file upload, must use the framed form.

Example Python body construction (the result can be sent with any HTTP client):

import json
import struct

metadata = json.dumps({"filepath": "/upload.bin"}, separators=(",", ":")).encode()
file_bytes = open("upload.bin", "rb").read()
body = b"JAMCJSBN" + struct.pack("<I", len(metadata)) + metadata + file_bytes

#WebSockets

WebSockets are HTTP-only and use ws://<device>/api/.... The server supports at most a small number of simultaneous sockets, so clients should reconnect with backoff and close unused streams.

The common binary frame convention reserves the first byte:

Reply to a one-byte 0x01 frame with a binary one-byte 0x02 frame. Current handlers update liveness on any received frame, but clients should use the defined pong value for forward compatibility.

Each MIDI record is:

MIDI-stone stream type values are 18 error string, 19 no asset yet, 21 raw file data, and 22 deflate-compressed file data.

#Endpoint reference

The detailed endpoint reference follows the same purpose-based order as the API domain guide. JSON in the request column means a UTF-8 JSON body. Empty means send a zero-length body. Paths containing /debug/ and sections explicitly marked dangerous are not stable application-facing contracts.

#Getting started and device information

#Meta

#System

#Device state

The aggregated response is convenient for initial UI hydration, but individual endpoints are preferable for polling a single subsystem.

#Identities

UUID fields are stable keys; name fields are editable labels. Renaming changes only the corresponding display name and returns the complete identities object.

#Time

unixtime is seconds since the Unix epoch. localOffset is minutes from UTC. timeSource must be factory, manual, or app; app is normally the right choice for an application client. daylightSavings is the firmware's CSV rule string and is optional; omitting it clears the rule.

#Music and recordings

#Piano

Piano state is a derived, real-time view of musical activity rather than a recording file. Use it to render a keyboard or activity UI without decoding the library.

#MIDI recorder

maxSilence is milliseconds. recordMode is grand, expressive, technical, or custom. In custom mode, statusMap and exprFidelity are numeric bitfields and ccFidelity is a 128-character hex encoding of 64 bytes. The three custom fields are optional and default to zero/null at the interface layer.

#MIDI commands

MIDI commands map selected incoming MIDI gestures to Jamcorder actions. The bookmark endpoint triggers that action directly; the settings endpoints control whether command families are accepted and which octave/safety note identifies them.

#MIDI I/O

All eight booleans are required when setting routes.

#Library

The library is the catalog of recorded JMX assets on storage. Listing can be continued with midiPathContinue; request only the optional metadata a client needs to reduce scanning work. The on-disk recording structure is documented in the JMX MIDI files specification.

#MIDI stones

stoneIdx may be an absolute stone index or a negative index counted backward from the newest stone.

#Lifetime statistics

Clearing lifetime statistics is destructive. The clear operation uses compare-and-clear protection. Both string values must exactly match a preceding get response or the request fails.

#Storage and content

#SD card — format is destructive

#Files

Filepaths are device-side absolute paths. Use paths returned by the API rather than assuming an SD-card mount name.

Download example:

curl --fail --output recording.jmx \
  -H 'Content-Type: application/json' \
  -d '{"filepath":"/recording.jmx"}' \
  "$JAMCORDER/api/files/download/simple"

#Extensions

Installed extension resources are served by the wildcard /extensions/* route. See Local web extensions for folder structure, packaging, browser API access, development, installation, and security guidance. The device-hosted extension page is /docs/extensions.

#Device health and feedback

#Alerts

Alert tokens mean that something changed; they are not complete state objects. Use the token to decide which read endpoint to refresh.

#Issues

Issues are structured, persistent health records rather than raw log messages. See Issues, alerts, and logs for record semantics and guidance on clearing them.

#Logs

#Coredump

#Buzzer

#Updates and maintenance

#OTA

Firmware images are encrypted device artifacts. Install operations can reboot the device or leave it running JFU; coordinate them as an exclusive workflow.

#Automatic reboot

#Factory reset — destructive

#Connectivity and setup

#Discovery mode

Discovery mode advertises a Wi-Fi hotspot used for Web-based setup. Entering discovery mode schedules a restart; the response only confirms that the transition was accepted, so clients must expect the connection to drop. See Web-based setup for setup instructions.

#Wi-Fi

SSID and password values are hex-encoded byte strings, not plain text. For example, Studio is 53747564696f. This preserves arbitrary SSID bytes. Changing credentials stores them but does not immediately move the device to the new network; reboot after receiving a successful response.

#Bluetooth

#USB

#Engineering and manufacturing

#Fabrication info

These endpoints expose manufacturing identity. set is intended for provisioning, not normal client use.

#Verbose logging

firehose, clear, persist, and unpersist mutate state even though the current registry exposes them as GET.

#Asset diagnostics

#Developer settings

Command numbers are firmware-internal. Read the list before changing one. The current implementation of /cmd/unset calls the same setter as /cmd/set; clients that need to clear a command should verify the returned state.

#Heap diagnostics

#System debug

#NVS debug

Writing NVS values changes persistent device state.

#Self-test

Test numbers are runtime-defined; fetch the list first. Factory-suite execution is registered as a GET even though it operates hardware.

#Factory mode and certificate provisioning

Factory mode must be unlocked before protected manufacturing writes. PEM values for the upload endpoints are hex-encoded bytes.

#STSAFE

#MIDI hardware tests

#Non-API HTTP routes

These routes serve built-in UI, diagnostics, and installed extension content. Their HTML is not a machine-readable API contract.

#Other transports

The same registry-backed API can be invoked over HTTP, Bluetooth BtHttp, or the serial console. WebSockets remain HTTP-only.

#Bluetooth BtHttp

BtHttp is exposed by service 02AA0001-4202-649d-ec11-dfdb58e9372d and characteristic 02AA0002-4202-649d-ec11-dfdb58e9372d. Subscribe to indications before writing a request.

Each BLE packet begins with a socket index and delimiter:

Message types are 20 request header, 21 request body, 40 response header, and 41 response body. Header messages are NUL-terminated string pairs. A request header begins with method and URI, then field-name/field-value pairs:

GET\0/api/device-state/get\0Content-Length\00\0

A response header begins with Status, its value, then response fields. Every BtHttp request must include a valid Content-Length, including 0 for a GET. Body bytes use the same JSON or JAMCJSBN representation as HTTP. The device can track up to six BLE clients and sixteen logical sockets in the current build.

#Serial console

When the console is enabled, each registered URI is also a command name. JSON input/download commands take a single JSON argument, for example:

/api/identities/get
/api/identities/rename/jamcorder {"jamcorderName":"Bench"}

The console also assigns numeric aliases based on registry order. These are diagnostic conveniences and are not stable across firmware versions. Binary downloads are delimited by [transmissionStart] and [transmissionComplete] and encoded as console-safe hex. Upload endpoints and WebSockets are not supported by the console transport.

#JFU mode

JFU is the firmware updater and recovery environment. Most integrations do not need to account for it. Clients that operate while JFU is running should use /api/meta/endpoints as the definitive runtime list.

#API endpoints available in JFU

The Verbose logging persistence endpoints, /api/verbose/debug/persist and /api/verbose/debug/unpersist, are not available in JFU.

#Non-API routes available in JFU