Open-XY builds OP-XY firmware in the browser. It runs as a website or from a
single opxy-builder.html file, including offline from file://. Firmware never
leaves the browser.
Select I’m having trouble connecting to MTP in either the OS-copy guide or build-upload guide. The same help is available before connecting and after a failed transfer, including when copying manually.
The help button opens the fresh-install guide directly, assuming you have already closed other transfer apps and checked the connection.
For a fresh installation, Start fresh with OS 1.2.1 guides a full drive format and official OS reinstall before installing Open-XY. It erases user content and soundpacks; verify backups and obtain the official OS 1.2.1 update before proceeding. If you cannot back up data you need, stop. The guide requires an explicit acknowledgement before showing the format instructions and never formats the device itself.
With the dev menu enabled, 5. format drive is in te-boot, not the factory
menu (where track 5 writes the OS). Follow the device prompts and wait for
completion. Hold COM while switching on, then select 1. upload firmware.
The guide links to official OS 1.2.1 and walks through copying the .tfw file
and ejecting the removable disk to start the update. After reinstalling,
it returns to the original copy or install flow. See the
official update instructions.
A format and reinstall resolved a reported persistent MTP failure on a device with soundpacks installed. Soundpacks have not been established as the cause, and this procedure is not a guaranteed fix.
If MTP connects but os.ldr is missing, use The OS file is missing · Help me
recover it instead. That separate path guides an official reinstall without
directing you to format.
- Use a desktop browser exposing both Web MIDI and WebUSB, such as Chrome, Edge or Opera. Compatible browsers go straight to the risk notice; acknowledge it on every load. Unsupported browsers see a centered blocking message with no Continue button. Developer preview links still display the guide without enabling device access; returning to the builder restores the risk notice or browser block as appropriate.
- Choose Mac or Windows. Help me get the OS file starts the guided setup;
I already have the OS file opens the file picker. At the dev menu check,
No, it’s missing is the first option and leads to enabling the menu.
Choose the OS: the decrypted OP-XY OS 1.2.1 file
os.ldr, or an Open-XY build to change. Only OS 1.2.1 is supported; the.tfwupdate files teenage engineering hosts are a different, encrypted format. The stock file is in a device capture at/upgrade/firmware/blackfin/bin/os.ldr; a previously installed Open-XY build is at/os.ldr. On a Mac with WebUSB in a compatible browser, follow the OS file guide and select Read original OS. The guide confirms OS 1.2.1, opens Mac file transfer mode and asks you to quit Field Kit and OpenMTP. It reads the original firmware path, checks the exact stock hash and loads the OS directly into the builder, with an optional backup download. It does not change device files or fall back to the patched root OS. Keep file transfer open to resume installation later. Windows uses the manual copy guide; Mac users can also choose Copy it myself instead. Both transfer guides show a notice for the rare case where a factory reset or initialization leavesOPXY/upgrade/firmware/blackfin/bin/os.ldrmissing. The OS file is missing · Help me recover it shows how to exit file transfer, then Disable dev menu connects and sends the disable command in one click. The next page links to the official OS 1.2.1 download and explains how to power cycle, check that the menu is gone, and reinstall. After reinstalling, Try again goes straight to enabling the dev menu for the same computer. - Select machines. Synth rows have a playable preview of their C++ sound and display code. Open Preview controls to adjust parameters, play the keyboard and set its volume. The controls start collapsed; reopening them keeps parameter values, and closing them stops preview notes. Each row shows its code, data and state size against the memory meter. Machines from the catalog are marked Community and start unselected; their details name the maintainer and link to the machine's code at the commit the catalog pins. Open-XY's own example machines from the catalog are labelled as Open-XY machines. A personal kit's own machines are marked Yours. A machine whose catalog CPU measurement is above 4.5% of an audio block is marked CPU-high, in its row and details; hover or focus the mark for an immediate explanation of its effect on voice count (catalog). Above the list, search by name, maintainer, repository (such as a collection's name), description, kind or keyword, sort by name, maintainer or kind, and filter by kind, by the catalog's keywords or by your favorites. Keyword filters take up to three lines, in alphabetical order: when they don't all fit, the most used ones show, with any you are filtering by, and +N more shows the rest. Star a row to make it a favorite; favorites are kept in this browser only. Filtering never changes the selection: the count under the filters says how many selected machines it hides. Presets, beside the selection count, saves the selected machines under a name and chooses them again in one step, replacing the selection. Update on a preset replaces its machines with the current selection, as saving its name again does. Presets are kept in this browser only and name machines by ID: a machine the collection no longer offers is left out and named.
- Choose optional extensions using the same checkbox rows as machines. Select a row to read what it does and how to use it in the details panel. Firmware extensions start off; continuing with none is valid. The summary lists your machines, extensions and combined memory use. Conflicting Record-double-tap claims cannot be selected together. Grayscale machine graphics is also available on this page, including in collections without firmware extensions. It starts off; enabling it changes custom screens while leaving stock screens unchanged. It adds no extension runtime memory; the selection summary lists the graphics choice separately. Open Configure to see and customize the selected machines together. Checking the option sets grayscale as the default for all selected custom screens. Each custom screen has a Screen appearance control: Enforce grayscale or Keep original design, showing its current setting. Choosing a different appearance creates an individual override; choosing the overall default again clears it. The extension checkbox is on whenever any selected custom screen is configured for grayscale, and off when all use their original designs. Opening or closing Configure does not change it. Stock screens remain unchanged and have no override control. Overrides are retained while changing the selection in this session; only selected machines' overrides enter the installation package. The same dialog previews every selected machine with its setting applied. For machines with a browser module, it renders the default UI once and caches a frozen SVG snapshot. There is no animation loop or audio; changing graphics reuses the same frame, and reopening reuses the cached snapshots. Machines without a browser module show their static artwork with a fallback label. Machines using stock screens are identified when no visual preview is available. The dialog always shows the installation settings. Make all grayscale and Restore all originals set the default and apply it to every selected custom screen, clearing those machines' overrides. Unselected machines' explicit overrides stay in place. Both buttons update the graphics checkbox on Extensions; stock screens remain unchanged. Use Screen appearance below each screen to make individual exceptions. Done or Escape closes the dialog while keeping the choices. Checking Grayscale machine graphics sets every selected custom screen to grayscale; unchecking it restores all their original designs. Both actions clear the selected machines' overrides and preserve unselected machines' overrides. Grayscale converts the selected machines' custom SVG screens, including text, strokes, fills and the palette entries used by animations. It preserves geometry, opacity and motion; sample engines and effects retain their stock screens. Custom screens that are already grayscale, including all animation palette entries, retain their original SVG bytes and hashes unchanged. For colorful originals, a machine's validated developer-authored grayscale variant takes priority over automatic conversion. Without one, the builder separates distinct hue families into gray ranges, using brightness as a secondary cue and one consistent palette throughout animations. The tonal spacing adapts to the number of distinct colors and shades, giving sparse palettes wider separation. Neutral grays remain unchanged. Both routes check the packaged SVG paints before installation; see the conversion behavior. Invalid declared variants or unsupported paints stop the build with a message naming the machine; choose colorful or use corrected artwork. Changing the default or a per-machine override discards the prepared download and requires a new build. The build manifest records the default and selected overrides; machine sources and saved sound parameters are unchanged.
- Build the firmware, then follow the installation guide using the remembered computer choice. Mac browsers with WebUSB send the files directly; Windows downloads a ZIP to copy with File Explorer. The OS write step on the device is still manual.
The ZIP contains:
| File | Install |
|---|---|
os.ldr |
Device root, replacing the existing file |
content/op1_factory.json |
Replaces the menu file |
content/display/*.svg |
New screens for the selected machines; keep the stock files |
content/presets/<machine>/*.json |
Each selected instrument's init preset, default.json, and its own presets, in the instrument's folder |
layout.json, hashes |
Keep layout.json: it holds your machines' numbers, and loading it into the builder next time keeps them for your projects |
The ZIP and direct transfer use the same prepared files. build.json records
the graphics setting and hashes of the final artwork. Disabling Grayscale machine graphics keeps the original SVG bytes; automatic grayscale conversion changes
only paint attributes in the packaged
screens, without modifying the machines' source or audio code.
Every build shows its release at boot, OPEN 0.0.3-1.2.1 for 0.0.3, the version in
VERSION that the builder also shows under its name and records in
build.json. Timestretch starts without a sample;
choose one on its sample page. Ring Mod is a send effect and has no preset.
The builder accepts the stock OS 1.2.1 file or any Open-XY OS made from it,
including one from an earlier release: it rebuilds the stock image by undoing
the reviewed edits and accepts it only if it matches OS 1.2.1 exactly. An exact
output of the same collection also restores its machine and extension
selection; for any other, choose them again (the layout still keeps machine
numbers). Saved selection files also retain extensions; older selection files
without that field select none.
Encrypted .tfw, unknown patches and damaged files are rejected. Projects,
presets and samples on the device are not touched.
The MIDI helper, adapted from Ferret
(MIT, Bag of Waffles; see builder/ferret.mjs and builder/ferret.LICENSE),
enables or disables the dev menu after an explicit click and browser MIDI
permission. Each enable or disable button connects and sends the requested
command in one action; failures and cancellation leave the action available
on the same page. It sets or removes only the bootloader.dev flag; it never
transfers firmware. After enabling, separate illustrated steps guide you through
pressing track 8 to open the system menu, then track 8 to return, before asking
whether the dev menu appears. After installation, Disable dev menu sends the command directly
before restarting; if already restarted, return to te-boot first. MIDI
needs a desktop browser and a secure context; otherwise the helper links to
hosted Ferret. The separate WebUSB MTP client reads or sends files only after
an explicit click and USB permission, and releases the connection afterwards.
The firmware reserves 2 MiB of the application heap: 2032 KiB that every selected machine shares for code, data and state, and 16 KiB for relocated stock tables. The memory meter shows each machine's share; see memory and limits. CPU headroom is not measured.
Below the meter, Use 4 MiB for machines is an experimental option, off by
default. It grows the reservation to 4 MiB (4080 KiB for machines) by
shortening the application heap from 18 MiB to 16 MiB, using the profile's
reviewed experimental_memory layout: the module starts 2 MiB lower and the two
heap edits write the smaller size, while the tables, hooks and every other edit
are unchanged. The stock OS needs that heap for its interface, projects,
presets, file browsing and MTP, and running out of it is fatal, so this build
may be unstable under heavy use. The selection summary shows the choice,
build.json and layout.json record it (reserved_bytes, and
"memory": "expanded" in the layout). Loading an open-xy OS sets the option to what that OS
used (a stock OS keeps the current choice), and so does restoring a layout.json
that lists machines. A layout from an experimental size this site doesn't offer
keeps the current choice; machines that need more than the memory chosen use
this site's option when it is on, and otherwise the builder says to turn it on.
sdk.py build uses only the standard layout and refuses a 4 MiB layout.json;
sdk.py project write accepts it.
Projects save each track's machine by number, so a machine keeps its numbers
in your firmware for good (layouts). The builder remembers
your layout in this browser and writes it to layout.json in every download;
load that file under the machine list to build from another browser or
computer. A layout from a build for OS 1.2.0 still loads. Numbers given to a machine you drop stay held, so its projects never
open another machine. Adding a machine to the collection means adding it to
the native build; the builder is not a plugin loader and does not raise the
voice limit.
The app is in builder/. Use Node 22.12+:
npm ci
npm run dev # http://127.0.0.1:8918/
npm run test:webOpen http://127.0.0.1:8918/#preview/machines to browse and audition the machine
collection without uploading an OS file. Append a machine ID, for example
#preview/machines/fm2op, to open its details directly. Installation stays disabled;
the OS button returns to the normal builder entry. A configured collection is
required for machine previews.
#preview/settings remains an alias for the Extensions preview without an OS file. It also keeps
installation disabled; returning to Machines auditions the chosen graphics mode.
The extension picker has a direct preview at #preview/extensions, with no OS
file required. Building remains disabled in preview mode.
Installation screens have direct preview links, such as
http://127.0.0.1:8918/#preview/mac/transfer, #preview/mac/exit-transfer
and #preview/mac/write-os. The original-OS flow uses
#preview/source/mac/close-field-kit and #preview/source/mac/transfer.
Use #preview/source/mac/missing-os to preview the recovery side path.
Replace mac with windows to see the manual
copy route. These developer links open the selected step immediately, skipping
the disclaimer and requiring no OS file or build. Device actions are disabled in previews;
Preview next step continues past the send screen. These URLs are developer
tools and are not linked from the installation interface. Back to builder shows the usual disclaimer
if it has not been acknowledged; opening a preview does not acknowledge it.
The dev server serves only the browser source allowlist and the configured
collection; do not replace it with a server rooted at the repository. Previews
and bundles need a collection: point the ignored .env.local at a verified
export from Export a kit:
OPEN_XY_KIT=C:/Users/YOUR_USER/AppData/Local/OPXY-SDK/private/builds/browser-kit-001/opxy-builder.html
OPEN_XY_OUT_DIR=C:/Users/YOUR_USER/AppData/Local/OPXY-SDK/private/sites/browser-kit-001OPEN_XY_KIT may also name an exported kit.json. Collections contain stock
menu content, so they and site output must live outside every checkout; the
server and build reject checkout-local paths, including through symlinks,
junctions and other worktrees. UI changes need no native rebuild; machine source
changes need a new export.
npm run build:release writes the site to OPEN_XY_OUT_DIR (or --outDir),
which must be a fresh directory; npm run preview serves it at
http://127.0.0.1:8919/. Asset URLs are relative, so the site can be hosted at a
domain root or a subpath; serve it over HTTPS for MIDI. CI runs npm run build
with no collection as a UI check and never consumes private inputs.
wrangler.jsonc names the site open-xy and binds open-xy.com. The site is
static assets only, with no Worker script. The beta environment is a separate
open-xy-beta site at beta.open-xy.com, deployed from staging; production
is deployed from main. Merge work into staging, release beta, then open a
pull request from staging (or a release/<version> branch cut from it) to main and release
production. Catalog changes
merge into main (then main into staging), so a new machine can reach
production without an SDK release.
On the release host, after npx wrangler login, one command releases the
catalog:
python sdk.py release --stock-os <stock-1.2.1>/os.ldr --out <builds>/release-001 --deploy betaIt fetches every published catalog machine at its pinned commit
(confirming its tag), exports the release kit from them
(Export a kit, with release verification), runs the
builder's web tests, builds the site around the kit and deploys it. It deploys
beta only from staging and production only from main, and only when the
checkout is exactly that branch on origin: no local edits, nothing unpushed or
behind. With --deploy, --dry-run does everything except publish; without
--deploy it stops after the kit. --toolchain and --compiler name the
pinned tools when they are not in local/toolchain.
--out must be a new folder outside every checkout; the kit and the site are
written inside it.
The deploy rebuilds in release mode, fails without a valid collection, and
uploads only the release directory. npm run deploy:beta and
npm run deploy:cloudflare remain for deploying an existing kit, with
.env.local set as above and a fresh OPEN_XY_OUT_DIR.
To add a custom domain, make its parent an active Cloudflare zone, then use Workers & Pages → open-xy → Settings → Domains & Routes → Add → Custom Domain; see the custom-domain guide.
With the pinned native tools and Clang++ for wasm32:
python sdk.py kit --preview-cxx clang++ --stock-os "$env:LOCALAPPDATA/OPXY-SDK/private/stock-1.2.1/os.ldr" --out "$env:LOCALAPPDATA/OPXY-SDK/private/builds/browser-kit-001"--stock-content defaults to the repository's copy of op1_factory.json. The export runs the
full native build and its checks, then packages the native objects in link
order with each machine's machine.json and definition. The HTML carries the
authenticated stock menu and the SDK screen template; firmware stays
user-supplied. It is named only after every check passes.
A published kit comes from the release host, after
release verification. It holds the
catalog's machines fetched at their pinned commits
(--collection local/catalog/collection.json), each with its repository, tag,
commit and maintainer. For your own machines,
add --personal: it runs on any pinned host, Windows or Apple-silicon macOS,
and skips only that verification. Open the resulting opxy-builder.html, or
serve it as in web development, to select machines,
preview them and use the installation guide with your device. It accepts your
stock OS and builds of its own collection.
The browser links the normalized ELF32 Blackfin objects itself, supporting the
LUIMM16, HUIMM16, PCREL24, PCREL24_JUMP_L and BYTE4 relocations. Unsupported
sections, COMMON or weak symbols, unresolved imports, overlapping relocations,
range overflow, constructors and memory overflow are errors. A deselected
machine's startup and catalog callbacks resolve to kit_absent, which declines:
startup skips it and its menu name is left to stock. Its audio code and state
are omitted. Extensions use the same omission mechanism: a generated accessor
returns their callback descriptor, or resolves to kit_absent when deselected.
The registry skips absent descriptors and retains collection order. Deselected
extensions contribute no code or state; shared controller hooks still forward
stock behavior with an empty extension registry. Export a fresh kit after this
SDK change; older kits containing the fixed extension registry are rejected.
The export checks that:
- selecting the machines the native package links, with every extension, reproduces
its
os.ldrbyte for byte: every machine, or Open-XY's own when the collection doesn't fit at once (memory); - every non-empty selection with every extension choice (including none) matches GNU ld, including symbols and BSS;
- browser output matches the Python writer, with correct catalog, artwork and ZIP;
- every output is recognized and its selection restored, and corruption inside or outside the allowed edits is rejected.
Restoring a build removes the appended module record, restores the profile's edit intervals and FIRST record, checks the stock SHA-256, and accepts the file only if relinking its selection reproduces it exactly. Uploaded code is never executed or reused, so only outputs of the same kit are recognized.