Yamaha XG Editor Spec

2026-07-28 - First SpaceAge XG Editor Specification

Product Goal

Build a SpaceAge-native Yamaha XG editor that makes QY-70/QY-100 and MU-series hardware feel understandable from inside the app without pretending that every Yamaha XG device is identical.

The first release should not be a total librarian. It should be a safe, Hardware Passport-backed editor for common XG part, mixer, effects, drum, and setup parameters. The editor must be able to explain what it can prove, what it can send, what is only staged, and what still needs manual verification.

Target Devices

• Yamaha QY-70
• Yamaha QY-100
• Yamaha MU-series modules, especially MU1000/MU2000/MU2000EX
• Later possible extension: CBX-K1XG, MU50/MU80/MU100/MU128, SW1000XG, XGlite instruments

Source Grounding

Use official Yamaha data lists and MIDI implementation charts as the primary truth source. Community editors may be studied for workflow only, not copied into SpaceAge unless the license is explicitly compatible.

Initial source stack:

• Yamaha QY100 Data List: https://data.yamaha.com/files/download/other_assets/0/318130/QY100E2.pdf
• Yamaha QY100 Owner's Manual: https://cf3.zzounds.com/media/QY100E1-7bf852c4978deec845140d3a4c37b277.pdf
• Yamaha QY70 List Book: https://www.deepsonic.ch/deep/docs_manuals/yamaha_qy70_list_book.pdf
• Yamaha MU1000/MU2000 List Book: https://data.yamaha.com/files/download/other_assets/2/316512/MU2000J2.pdf
• WebXGMIDI proof-of-concept reference: https://github.com/mrfloydst/webxgmidi
• WebXGMIDI parameter-list source pointer: http://www.studio4all.de/htmle/frameset091.html
• QXGEdit workflow reference: https://github.com/rncbc/qxgedit

Licensing note: QXGEdit is GPL-2.0-or-later and must remain reference-only for this commercial project. WebXGMIDI currently has no obvious repository license in the GitHub metadata checked on 2026-07-28, so treat it as reference-only unless permission/license clarity is obtained.

Current SpaceAge Foundation

SpaceAge already has the right lower-level blocks for this:

• A Hardware Editor Profile Registry now lists locked/read-only QY, CBX, MU, and generic GM/XG/GS editor paths before any deep editor controls are exposed.
• Parameter-table imports now use the selected Hardware Passport, when it clearly names a QY, CBX-K1XG, or MU1000/MU2000 device, to infer the expected editor parameter family and flag wrong-device tables earlier.
• Hardware Editor Unlock Readiness reports now explain why a profile remains locked: missing source tables, missing parameter preview rows, queue-safety gaps, profile mismatches, or required real-hardware receipts.
• The parameter-table import dialog now includes both row-level source proof and profile-level unlock readiness in the same copyable report.
• Hardware Editor Parameter Import Review now combines the expected Passport family, imported table proof, matched registry entry, and unlock readiness into a reusable machine-readable contract for both the current dialog and the future locked editor page.
• Locked Hardware Editor Page Plans now turn registry first-page recommendations into disabled page cards with lock reasons, disabled control groups, and next actions. This lets SpaceAge show the future QY/MU editor shape before any hardware sends are safe.
• Locked editor page plans now include a Safe Common MIDI Controls section so ordinary MIDI controls can be surfaced separately from deep vendor SysEx. The current safe layer includes Bank Select, Program Change, Channel Volume, Pan, Expression, Reverb Send, Chorus Send, Variation/Effect Send, Sustain, and Pitch Bend Range RPN. Yamaha/XG plans also list Harmonic Content and Brightness as reviewed common controls, still routed through guarded send policy.
• Hardware Passports for named hardware identity.
• Device templates for QY-70/QY-100, CBX-K1XG, generic GM/XG/GS modules, and now MU1000/MU2000.
• Structured source-proof fields on Hardware Setup templates: legal note, primary source URLs, required source artifacts, and unlock requirements.
• SysEx Vault concepts for named captures and guarded restore.
• RPN/NRPN preservation, Program/Bank preservation, channel routing, and MIDI Health proof reporting.
• Launch-proof cards that separate automated backend gates from real-world hardware proof.

Editor Architecture

The XG editor should be profile-driven.

Each supported hardware model gets a HardwareEditorProfile built from verified tables:

• Registry identity and lock state.

• Required source artifacts and unlock requirements.

• Manufacturer ID.

• Device number behavior.

• Model ID.

• Reset messages.

• Identity reply matching.

• Parameter address map.

• Data size per parameter.

• Min/max values.

• Signed/offset value encodings.

• Display label.

• Display unit.

• Default value, where known.

• Device-family applicability.

• Checksum policy.

• Send pacing policy.

• Acknowledgement/timeout policy.

The UI must not build raw SysEx strings by hand. Controls should bind to verified parameter descriptors, then the MIDI layer should build and queue the message.

For safe common MIDI controls, the UI should request a preview-only HardwareEditorSafeCommonControlActionPlan before any queue/send action. That plan is the contract for exact message order: CC controls become guarded CC messages, Program Change preserves the 0-127 wire / 1-128 display distinction, and RPN controls such as Pitch Bend Range include selector, Data Entry, and safety-null deselect messages. This keeps the hardware editor readable while preventing UI code from inventing MIDI message order.

First Editor Pages

1. Hardware Passport Header

• Device model.
• Firmware or manual/profile variant.
• MIDI input.
• MIDI output.
• Device number.
• Current route status.
• Test note.
• Request identity.
• Capture setup dump.
• Send confirmed setup.

2. Part Mixer

• Part/channel selector.
• Voice bank/program.
• Part volume.
• Expression.
• Pan.
• Reverb send.
• Chorus send.
• Variation send.
• Dry level where supported.
• Mute/solo only as SpaceAge-side monitoring helpers unless verified as hardware commands.

3. Part Sound

• Filter cutoff.
• Resonance.
• Attack.
• Decay.
• Release.
• Brightness.
• Harmonic content.
• Portamento on/off.
• Portamento time.
• Mono/poly where verified.
• Pitch bend range via RPN.

4. Effects

• Reverb type and parameters.
• Chorus type and parameters.
• Variation type and parameters.
• Insertion/system mode where supported.
• Return levels.
• EQ where supported.

5. Drum Part

• Drum channel selector, usually channel 10 by convention.
• Kit selection.
• Per-note drum controls where verified.
• Drum pitch, level, pan, reverb send, chorus send, filter, envelope, and alt group where supported.

6. Setup / SysEx

• XG reset.
• GM reset where applicable.
• Bulk dump request.
• Bulk dump capture.
• Confirmed restore.
• Compare captured setup against expected profile.
• Export setup as .syx and optionally embed into a MIDI file preamble.

Message Policy

Parameter changes must be explicit, paced, and receipted.

Rules:

• Preview never sends MIDI.
• Apply Draft may change the SpaceAge project, but must not send hardware MIDI.
• Send actions require visible confirmation.
• Every send creates a receipt with time, target device, message family, byte count, and verification status.
• Bulk sends require pacing to avoid device buffer errors.
• QY100 owner documentation warns about MIDI Buffer Full, XG data/address/size errors, and checksum errors, so SpaceAge must not blast dense SysEx without delay and status feedback.

UI Philosophy

This editor should feel like a hardware assistant, not a spreadsheet.

Recommended customer-facing language:

• "Choose your Yamaha box."
• "Tell SpaceAge where it is plugged in."
• "Send a tiny test note."
• "Capture the current setup."
• "Edit one part at a time."
• "Send this change."
• "Store this setup as a recall card."

The editor should make old hardware feel modern by reducing memory burden. A user should not need to know that XG Reverb Type lives behind address bytes to use it.

What Shane Needs To Obtain

To make QY-70/QY-100 and MU2000 support serious rather than approximate, collect:

• Exact PDFs or scans for each target device's Data List / List Book / MIDI Data Format.
• Owner's manuals for each target device.
• Firmware/edition notes, especially MU1000/MU2000 vs MU1000EX/MU2000EX.
• Any official Yamaha XG specification PDFs you can legally keep in the project research folder.
• Clear screenshots or scans of effect type lists and effect parameter tables.
• Drum setup parameter tables.
• Voice/bank lists.
• Identity reply examples from your actual devices, captured through SpaceAge when possible.
• SysEx bulk dumps from each device in a known state, saved as test fixtures only if you own/created the data.
• Notes about your desired default workflow: QY as sound module only, QY as sequencer, MU as 16-part module, MU as 32/64-part advanced rig, etc.
• Confirmation of which real hardware you own or can test physically.

Implementation Phases

Phase 1: Spec and Profile Skeleton

• Keep QY and MU editor profiles locked.
• Store verified sources and manual links.
• Add model-specific templates and checklists.
• Expose source-proof requirements as structured template data so the UI can show why deep editor pages are locked.
• Add parser/import path for a simple parameter CSV or JSON table.
• Surface the locked-editor proof in MIDI Setup previews: profile state, legal note, primary source, required artifact, and unlock requirement should be visible before a Hardware Passport draft is applied.
• Use HardwareEditorParameterDefinition rows for the first source-table format. Each row must name the profile family, parameter id, display name, page/group, SysEx address, value range/default, encoding, source artifact, source page or URL, queue-safe state, and source verification state.
• A HardwareEditorParameterImportPreview must remain read-only: it validates rows, reports warnings, and says whether a section is ready to unlock. It does not create a Hardware Passport, send SysEx, or enable deep controls by itself.
• JSON text/file previews are now supported for the source-table row format. A table file may provide profileFamily once at the root and place rows under parameters or rows; the preview inherits that family, counts verified/locked/queue-safe rows, and rejects broken or missing files with warnings.
• The MIDI Hardware Passports panel now exposes this as IMPORT TABLE. It is a preview/report doorway only; it does not write to a Passport, does not enable controls, and does not send hardware MIDI.
• The MIDI Hardware Passports panel also exposes EDITOR PLAN, a cold-copy path for the selected Passport's locked editor page plan. If no exact QY/MU/CBX family is inferred, it falls back to the generic GM/XG/GS editor plan.
• The MIDI Hardware Passports panel also exposes SAFE MIDI, a cold-copy path that copies exact preview plans for common MIDI controls on the selected Passport channel. This is the customer-facing bridge between generic MIDI usefulness and locked vendor SysEx depth.
• Locked editor plans include a source/unlock checklist covering primary source URLs, required source artifacts, unlock requirements, table-proof state, queue-safety state, and hardware-receipt state.
• A locked manual-test fixture lives at docs/Yamaha_XG_QY_Parameter_Table_Preview_Example.json. It exists to exercise the preview UI safely; it must not be promoted to an unlocked editor profile until every row is checked against official Yamaha pages.
• Source-table previews must report proof counters, not just a pass/fail state: source-ready rows, missing source proof, address issues, range/default issues, and profile mismatches. This lets a user or developer know whether a table is blocked by documentation, malformed data, or wrong-device content.
• The import dialog should lead with the short lock/readiness headline, then show the full copyable report. The goal is instant user comprehension plus a durable evidence trail.
• Matching imports should also show a locked editor page plan: Passport Header, Part Mixer, Part Sound, Effects, Drum Part, Multi EQ, PLG/Expansion, or other profile-specific pages. Every page remains disabled until source proof, queue safety, and real-hardware receipts are complete.

Phase 2: Safe Common XG Part Editor

• Expose common CC/RPN controls first: bank/program, volume, pan, expression, reverb/chorus/variation sends, pitch bend range.
• Use existing SpaceAge MIDI recording/export infrastructure.
• Send only after explicit confirmation.

Phase 3: SysEx Parameter Descriptors

• Add XG parameter descriptor registry.
• Add Yamaha SysEx packet builder.
• Add checksum helper where required.
• Add throttled send queue and receipts.

Phase 4: QY-70/QY-100 Editor

• Map verified QY part, effect, drum, and setup parameters.
• Add QY-specific bulk capture/restore guidance.
• Add SmartMedia/Data Filer notes as documentation, not app dependency.

Phase 5: MU1000/MU2000 Editor

• Map MU System, Multi Part, Effects, Multi EQ, Drums, and optional EX/GS/PLG differences.
• Add profile variant selector for base vs EX/GS firmware.
• Add safe setup recall cards.

Phase 6: Real Hardware Proof

• Run physical tests with at least one QY and one MU-class device.
• Save receipts for identity request, test note, simple part edit, effect edit, bulk capture, and guarded restore.
• Only then change editor state from locked to ready.

Open Questions

• Do we want XG editors only under Settings/Hardware Passports, or also as lane-level hardware instrument editors?
• Should a Hardware Passport own one XG module while lanes own parts, or should an advanced Polytimbral Lane own all parts?
• How much of QY sequencer-specific behavior belongs in SpaceAge if the app is mainly driving the QY as a sound source?
• Should setup dumps be embedded into exported MIDI files by default, or only by explicit export option?
• Should SpaceAge offer a "do not touch my hardware state" monitor-only mode for cautious users?

Near-Term Recommendation

Build the first visible version as a locked Yamaha XG Editor Plan inside Hardware Passports. It should show QY and MU device choices, source requirements, exact manual/data-list checklist, safe common MIDI controls, and disabled deep edit pages. Unlocking the deep pages should require a verified profile table and at least one physical-hardware proof receipt.