Request for BetterTouchTool Preset Format Documentation

Configuration Help & General Discussion
,
1

Hello Andreas (or BetterTouchTool team),

I'm working on a developer tooling project that aims to programmatically create and manage BetterTouchTool presets. After examining exported .bttpreset files, I can see they use a JSON format, but I'd like to better understand the schema and structure to ensure I'm creating valid presets.

What I'm Building

I'm developing a Node.js library that would allow developers to:

  • Create BTT presets programmatically
  • Validate preset files against a schema
  • Generate complex automation workflows through code
  • Version control and share presets more effectively

Specific Information Needed

  1. JSON Schema: Is there an official JSON schema for .bttpreset files?
    If not, would you kindly provide one or help us create one?

  2. Meaning of Numeric Codes: What do the numeric codes represent in fields like singleFingerTapRight and BTTPredefinedActionType?

  3. Required Fields: What are the minimum required fields for a valid preset?
    I see fields like BTTPresetName, BTTPresetUUID, and BTTPresetContent, but I'm unsure which ones are mandatory.

  4. Trigger Types: Is there documentation for all possible trigger types and their required properties?
    For example, I see values like -1, 629, 1000, etc. for BTTTriggerType.

  5. Action Types: Similarly, is there documentation for all possible action types (BTTPredefinedActionType) and their required properties?

    • Also, is there documentation for the values in BTTTriggerType and for similar fields, which looks like only support certain values?
    • What are the allowed values for BTTAdditionalConfiguration and BTTAdditionalActions, they sound like flexible fields which can be set to different values(-types)?

  6. Cryptic Fields: What do fields like BTTHUDActionConfiguration, BTTMenuAttributedText, BTTFloatingMenuRenderedPreview or BTTIfConditionData represent?

    • How can I generate valid values for these fields? / How can I encrypt the values of these fields?
    • How can I decrypt the values of these fields?

  7. Script Integration: I see that BTT supports JavaScript for Apple (JXA) in actions like "Execute JavaScript for Apple" and shell scripts in "Execute Terminal Command".

    • How are these scripts stored within the preset JSON structure?
    • Are there specific fields like BTTAdditionalConfiguration.BTTScriptToRun that contain the script content?
    • What are the limitations on script size or complexity within presets?
    • For external scripts, what's the recommended approach for referencing them in a portable way across different machines?
    • Are there any security considerations or encoding requirements when embedding scripts in presets?

  8. UUID Generation: Are there any requirements for UUID generation, or can we use standard UUID v4?

  9. Versioning: How does BTT handle preset versioning?
    Are there compatibility concerns when creating presets for different BTT versions?

  10. Testing: Any recommendations for testing programmatically generated presets before importing them into BTT?

Why This Would Be Valuable

Having this documentation would enable:

  • More developers to build tools around BTT
  • Better integration with development workflows
  • Fewer issues with malformed presets
  • The ability to generate complex presets that would be tedious to create manually

I've already started examining the structure by exporting presets, but official documentation would be immensely helpful to ensure I'm not missing anything important.

Thank you for considering this request. BetterTouchTool is a wonderful tool, and having better developer documentation would make it even more powerful for automation workflows.

Best regards,
Tobias Hochgürtel

btt-preset-analysis.md.txt (4.1 KB)
btt-preset-schema-draft.ts.js (8.9 KB)

2 Likes
2

I’m currently working on that :slight_smile:
Lots of things have grown over 15 years, so it’s not really straightforward, but it will soon all be documented

2 Likes
3

I can be your beta tester or reviewer for your BTT Present Format documentation :upside_down_face:

that would help me now because I get forward with my project.

  • Otherwise, there is no estimation of when you will publish the updated docs?

Meanwhile, I'll continue with analysis based on examining existing presets.

4

i have planned to do it sometime during the next 1-3 weeks

1 Like