A naming convention for MT Pro variables, and an audit script for .bmtp files

Tips & Tricks
1

Hi all,

Usual disclaimer first: I do not work for Bome and this is not official guidance — I am a user sharing what I ran into, and I used an AI assistant to help me read the file format, test the hypotheses and write it up.

After chasing a silence on my live rig for an evening, I found the cause was a naming problem. So I wrote down a convention, together with a script that audits a .bmtp file. Sharing it in case it is useful, and mostly to get it corrected.

The failure it came from. A translator computed a controller number into a variable and put it in the Outgoing Action’s controller slot. A dead-zone branch used ‘Exit rules, execute Outgoing Action’, so it fired before that variable was assigned, emitting CC <whatever was left> = 0. Because the variable was global, ‘whatever was left’ was not bounded by that translator, and some of the values landed in 120-127. Those are Channel Mode messages: All Sound Off, All Notes Off, Poly On. The rig went quiet and nothing in the MIDI monitor looked like a cause.

The convention, in short.

One. Locals are oo pp qq rr ss tt uu vv ww xx and nothing else. Every other name is global whether you meant it or not. Default to a local: they are scoped per incoming event, so two translators using pp can never interfere.

Two. Give each local a fixed job — rr first data byte, pp second, qq channel, ss tt uu scratch, vv ww extra outputs, xx flag — so two values of the same type inside one chain have obvious homes.

Three. One global head letter per device, never per preset index. Presets get renumbered when you drag them, a keyboard does not. The second character carries the type.

Four. Never put a shared global in a controller-number slot, and use ‘Exit rules, don’t execute’ when a branch means ‘send nothing’.

Five. Write the legend in the translator name, in a Comment rule at the top of the chain, and in the preset’s Comments field. A literal backslash-n is a real line break there, and your own example projects use it that way, one variable per line.

The script reads a .bmtp and reports: names outside both documented ranges, globals written by more than one active preset, variables read in a preset that never writes them, variables read but never written anywhere, Outgoing Actions with a variable in the controller-number slot, early exits that fire before the assignment they depend on, and — when the project uses the MIDI Router — translators on a routed input port that can exit with noexecute: on that branch the raw message goes on through the router, as Steve explains below. Read-only.

This overlaps with the ‘Cross-Reference List of all Variables in a MT Pro Project’ thread here and pestrela’s bome_analyse_project.sh, which I only found afterwards. Credit where it is due. Mine is a complement, focused on scope and collisions rather than cross-referencing.

Repository: GitHub - Beennnn/bome-project-tools: Read, audit and safely rewrite Bome MIDI Translator Pro project files (.bmtp) — notes on the format, plus tools that edit it and test the result. Unofficial. · GitHub (MIT, plain Python, no dependency). It has grown into a small toolkit for anyone whose MT Pro project has outgrown checking by eye:

  • audit — the read-only report described above, now also covering the MIDI Router;
  • probe — send MIDI through the running MT Pro and check what comes out, and that nothing comes out where nothing should — a case that observes nothing only passes if it said it expected silence, so a test aimed at the wrong channel does not slip through;
  • project — edit a .bmtp from Python for the bulk changes that are tedious by hand: it takes a backup first, refuses to run while MT Pro is open, and leaves an unchanged preset byte-identical, so a diff shows exactly your change;
  • the format notes — everything I have worked out about the file so far, in the README.

It replaces the earlier bome-variable-naming repository.

Corrections so far (thanks Steve): oo is a local too — ten locals, not nine. And globals are not limited to the heads g h i j k l m n y z: a head from o to x followed by any character other than itself (oa, o1…) is global as well. The rest of the scope ranges still comes from the manual and old forum threads, so further corrections are welcome — I would rather fix the document than have people rely on it.

Thanks,

2

Actually, there are 10 local variables. “oo” is also a local variable. As you said they are good for avoiding name collision, but you can’t pass those between translators (unless the receiving translator as the same incoming trigger). You can, however pass local variables as values between certain translators like “Perform” and “Timers”.
Passing variable is a recent feature so be sure you upgrade to the latest version to make that work.

I usually uses oo, pp and qq as standard the other seven I use as temporary variables. Care must be given within rules to keep track of what you are using. Sometime within a translator when I’m done with a local variable, I may actually have rules that use it again for a different purpose.

I prefer to use locals whenever possible.

I usually track all of my globals in the rules of a single translator under a preset called “Init” with a translator “Initialize Global Variables” . I usually trigger the rules by a translator with an incoming trigger of “Project Start”.

I often use global variables here when they are meant to be shared between translators. The trick is to keep track of them.

Keep in mind that if you exit rules, skip outgoing action and the MIDI - IN message had something. The MIDI message will pass through untouched based on how you have your MIDI Router set. This is a nuance that has tripped me up more than once.

For global you can now also include o-x that include any letters that are not the same as the first letter so for first letter o, you can last letter (or number) anything bu o and it would be a global variable (ie oa or o1 ,).

Thanks for posting this! I’m sure other users out there will find this useful. I’ll upgrade you shortly so you can post the link.

Steve Caldwell
Bome Customer Care

Also available for paid consulting services: bome@sniz.biz
3

@SteveC — thank you, and the oo correction is now applied everywhere. Worth saying plainly what it cost, because it’s the worst kind of mistake for a linter: my convention didn’t just omit oo from the list, it cited it as an example of a name that only looks local. So the audit was reporting a genuine local as UNDOCUMENTED, and would have sent someone renaming a variable that was perfectly fine. Fixed in the script, the convention and my own rig’s comments.

Your note that locals can now be passed between translators through Perform and Timers turned out to matter more than I realised at the time — see below.

Since August I’ve been writing rather than only reading, and the tools have merged into one repository: GitHub - Beennnn/bome-project-tools: Read, audit and safely rewrite Bome MIDI Translator Pro project files (.bmtp) — notes on the format, plus tools that edit it and test the result. Unofficial. · GitHub (MIT). The audit and the convention moved there too; bome-variable-naming now points at it. Both had grown their own parser for the same format, which was the one duplication neither could justify.

What’s new is a library that edits a project and writes it back, plus a small MIDI probe that sends a message and asserts what comes out — including asserting that nothing comes out, which caught more of my own mistakes than the positive cases did.

The case that made it worth building. A translator has exactly one outgoing action, so N triggers each needing to reach M destinations costs N × M entries. I had 7 × 3 = 21 translators all saying the same thing. Restructuring through a Perform action brought it to 7 + 3 — and a fourth destination now costs one entry instead of seven. Your point about parameters is exactly what makes it work: each trigger passes which zone it concerns, and the three executors filter on it, so they don’t each need their own copy.

Done by hand that’s a careful afternoon of deleting, adding and renumbering. As a script it’s ten minutes and I can verify it afterwards.

What I had to work out about the format is written up in the README — how a translator spreads across four indexed keys, what Outgoing=None means, how Options encodes its rule count, that the channel is 0-based, how aliases interact with preset defaults. Same disclaimer as in August: observation rather than knowledge, verified against 1.9.2 by reopening what the scripts produced, and corrections are very welcome. The oo episode is a good argument for asking.

Which leads to a question I’d genuinely like to ask Bome: is any officially supported programmable interface on the roadmap?

Two fairly different needs, I think:

  • live control — activate a preset, add or drop a route while playing. MT Pro already has these actions internally; only outside access is missing. OSC would fit naturally, being the same shape as the MIDI it already speaks.
  • project editing — read the structure, add and remove translators, validate. That’s CRUD on a document rather than real-time control, so a local HTTP + JSON API would suit it far better.

The reason I’m asking now: Ableton doesn’t ship an MCP server either. They never wrote one. But because an open control surface exists — AbletonOSC, itself third-party — at least six community MCP servers have grown on top of it, and today an AI assistant can build and check a Live set directly. The vendor did none of that work. It was enough that something programmable existed.

That’s the whole request, really. Not ‘please build an MCP server’ — rather, if any supported programmable surface appears, that layer follows on its own. I’d be glad to build it.

Meanwhile the scripts work, but they’re inference against a file format, they invalidate the signature, and they can’t run while MT Pro is open. None of which would be true of a supported path.

4

Not that I know of, however I will pass along your request.

I believe there are plans to change the file format. I’m not sure of the priorities and timing on this though. As far a scripts signatures being invalidated, this is as designed, It shouldn’t affect functionality if you are using Bome MIDI Translator Pro, however if you are loading your file to BomeBox or using MIDI Translator BN, they will required a signed file so after you are done, you would need to load the project file into Bome MIDI Translator Pro and then save it out again to give it a new valid signature.

Steve Caldwell
Bome Customer Care

Also available for paid consulting services: bome@sniz.biz
1 Like
6

Hi Benoit,
thank you for all the hard work and the extra effort of posting here and creating the github repository.

The file format has grown over time, as you can probably tell. We have the idea to move to a JSON based file format, which will editing the project file itself much easier. But this is not a promise that we will do that.

Also, allowing free-form variables will be a game changer, and it is on our roadmap (although we do not know when it will make it into the public release).

Last, but not least, the idea of integrating an MCP server into MT Pro is compelling and we’re currently evaluating it. Thank you for bringing it up. Maybe, with good MCP integration, nobody will need free-form variables anymore or a nicer file format :wink:

I’ve moved this thread to the tips&tricks section, feel free to keep the first post up-to-date.

7

PS: the github link is not working. It’s probably a good idea to add the correct github link to the first post. Thanks!

8

Thanks Florian, and thanks Steve for your feedback.

I made a mistake. The github link is back now :slight_smile: — and the first post is up to date with it.

1 Like