`
Usually you should store all files used by the webview in the Preset's data directory. You can reference these files from within the webview using the presetfile:// protocol. For example `
`
### Refreshing the Content
By default the content of the webview will stay loaded in background and it is assumed that it doesn't change. However during development you often want to see the latest changes immediately. To achieve this, open the advanced section and select "Do NOT keep content active in background". Afterwards the webview will reload everytime you hide/unhide it.
results matching ""
===================
No results matching ""
======================
---
# Standard Button & Formatting · GitBook
[Standard Button & Formatting](https://docs.folivora.ai/)
==========================================================
Standard Stream Deck Buttons
============================
This documentation uses the following example preset to explain some of the features. [Example Preset Direct Link](https://folivora.ai/releases/ExampleStreamDeck.bttpreset)
Function
--------
Stream Deck Buttons can be used to trigger any sort of action in BetterTouchTool. In their standard configuration a button press triggers the assigned action sequence as soon as you press the button down.
Appearance
----------
There are many ways to customize the appearance of Stream Deck buttons in BetterTouchTool:
* Changing the background color
* Using rich text including any color and font combination
* Using all sorts of icons including SF Symbol icons (see [https://developer.apple.com/sf-symbols/](https://developer.apple.com/sf-symbols/)
)
BetterTouchTool integrates a very basic rich text editor that lets you adjust fonts, colors & spacing. For more control you can also use the Apple Text Edit app and then just copy the formatted text into the BTT editor.
### Example: Adjusting Space Between Lines
To adjust the spacing between lines select the "Other..." option from the spacing dropdown:
In BTT the "Line height - at most" setting works best to make smaller spacing:
Advanced Configuration
----------------------
Stream Deck Buttons do offer various advanced options, see the following examples:
* [Button with different actions for long press and short press](https://docs.folivora.ai/docs/1302_stream_deck_long_press.html)
* [Button which repeats its actions while being pressed](https://docs.folivora.ai/docs/1303_stream_deck_repeat.html)
* [Showing buttons only on specific devices](https://docs.folivora.ai/docs/1305_stream_deck_specific_devices.html)
results matching ""
===================
No results matching ""
======================
---
# Development Hints · GitBook
[Development Hints](https://docs.folivora.ai/)
===============================================
Development Hints
-----------------
Some useful tips & tricks that make working with the web view easier.
1.) **Use an external HTML file.** Best solution is to place it in the preset's data folder and reference it using BTT\_PRESET\_PATH/thenameofthefile.html. You can use your facorite editor (I recommend Visual Studio Code) to edit the file. .
2.) **Disable caching while developing.** You probably want the webview to automatically reload when hiding / closing it. To achieve this, enable the "DO NOT keep active in background" option. .
3.) **Use the debugger / inspector.** You can right-click any BTT webview and choose "Inspect Element" to open the webview inspector. This can be a bit slow though. If you want faster debugging enable Safari's developer mode, then you can also access the BTT webviews through the Safari Develop menu:
.
results matching ""
===================
No results matching ""
======================
---
# Starter Template · GitBook
[Starter Template](https://docs.folivora.ai/)
==============================================
A simple example menu that shows various possibilities:
It should look like this: 
Named Trigger: Test
Set Brightness to 60%
Say Hello World
Show Apple Script Dialog
Close the Webview
Get Currently Playing Song
Custom Menu
\",\"width\":200,\"height\":300}"
}
### Show Searchable List
> Shows searchable list of items.
Parameters:
* **BTTPredefinedActionType**: 465
* **BTTGenericActionConfig**: List configuration (deprecated - use BTTAdditionalActionData)
* **BTTActionCustomScriptSettings**: Script settings (optional)
* **BTTAdditionalActionData**: JSON object with searchable list configuration
* `BTTActionSearchableListIconBackgroundColor`: string - Icon background color (hex)
* `BTTActionSearchableListInputBehavior`: number - Input behavior mode
* `BTTActionSearchableListPosition`: number - List position on screen
* `scriptSettings`: object - Script configuration for dynamic content
Example:
{
"BTTPredefinedActionType": 465,
"BTTAdditionalActionData": {
"BTTActionSearchableListIconBackgroundColor": "#0084FF",
"BTTActionSearchableListInputBehavior": 0,
"BTTActionSearchableListPosition": 0,
"scriptSettings": {
"items": ["Item 1", "Item 2", "Item 3"],
"placeholder": "Search..."
}
}
}
### Show Floating Web View
> Shows floating window with web content.
Parameters:
* **BTTPredefinedActionType**: 249
* **BTTActionURLToLoad**: URL or HTML file path
* **BTTActionFloatingHTMLConfig**: Window configuration
* **BTTActionFloatingHTMLName**: Window name (optional)
Example:
{
"BTTPredefinedActionType": 249,
"BTTActionURLToLoad": "https://example.com",
"BTTActionFloatingHTMLConfig": "{\"width\":800,\"height\":600,\"x\":100,\"y\":100}"
}
### Close Floating Web View
> Closes floating web view window.
Parameters:
* **BTTPredefinedActionType**: 372
* **BTTGenericActionConfig**: Window identifier
Example:
{
"BTTPredefinedActionType": 372,
"BTTGenericActionConfig": "webview-1"
}
### Show HUD
> Shows heads-up display with message.
Parameters:
* **BTTPredefinedActionType**: 254
* **BTTHUDActionConfiguration**: HUD configuration including text and duration (deprecated - use BTTAdditionalActionData)
* **BTTAdditionalActionData**: JSON object with HUD configuration
* `BTTActionHUDText`: string - Main text to display
* `BTTActionHUDIcon`: string - Path to icon image
* `BTTActionHUDIconHeight`: number - Icon height in pixels
* `BTTActionHUDIconWidth`: number - Icon width in pixels
* `BTTActionHUDDuration`: number - Display duration in seconds
* `BTTActionHUDBackgroundColor`: string - Background color (hex)
* `BTTActionHUDTextColor`: string - Text color (hex)
* `BTTActionHUDMinWidth`: number - Minimum HUD width
* `BTTActionHUDMinHeight`: number - Minimum HUD height
* `BTTActionHUDSize`: number - Size preset (0=small, 1=medium, 2=large)
* `BTTActionHUDTextSize`: number - Font size in points
* `BTTActionHUDSlideDirection`: number - Animation direction (0=fade, 1=slide from top, 2=slide from bottom)
* `BTTActionHUDPosition`: number - Screen position (0=center, 1=top, 2=bottom, 3=left, 4=right)
* `BTTActionHUDScreen`: number - Display screen (0=main, 1=mouse screen)
* `BTTActionHUDOnlyShowWhenModifierPressed`: number - Show only with modifier key
* `BTTActionHUDDetailsText`: string - Additional details text
* `BTTActionHUDDetailsImage`: string - Path to additional image
* `BTTActionHUDActionType`: number - HUD action type
Example:
{
"BTTPredefinedActionType": 254,
"BTTAdditionalActionData": {
"BTTActionHUDText": "Action completed!",
"BTTActionHUDDuration": 2,
"BTTActionHUDBackgroundColor": "#000000",
"BTTActionHUDTextColor": "#FFFFFF",
"BTTActionHUDSize": 1,
"BTTActionHUDPosition": 0,
"BTTActionHUDSlideDirection": 0
}
}
### Show Notification
> Shows system notification.
Parameters:
* **BTTPredefinedActionType**: 371
* **BTTNotificationTitle**: Notification title
* **BTTNotificationText**: Notification body
Example:
{
"BTTPredefinedActionType": 371,
"BTTNotificationTitle": "BetterTouchTool",
"BTTNotificationText": "Task completed successfully"
}
### Haptic Feedback
> Triggers haptic feedback on trackpad.
Parameters:
* **BTTPredefinedActionType**: 255
* **BTTHapticFeedbackAction**: Pattern type (1-22)
Example:
{
"BTTPredefinedActionType": 255,
"BTTHapticFeedbackAction": 1
}
### Show Color Picker
> Shows the color picker dialog.
Parameters:
* **BTTPredefinedActionType**: 94
Example:
{
"BTTPredefinedActionType": 94
}
### Show Cheat Sheet
> Shows keyboard shortcut cheat sheet.
Parameters:
* **BTTPredefinedActionType**: 354
* **BTTAdditionalActionData**: JSON object with cheat sheet configuration
* `BTTActionCheatSheetTitleTextColor`: string - Title text color (hex)
* `BTTActionCheatSheetDescriptionTextColor`: string - Description text color (hex)
* `BTTActionCheatSheetBackground`: string - Background color (hex)
* `BTTActionCheatSheetBackgroundAlpha`: number - Background transparency (0-1)
* `BTTActionCheatSheetItemsPerColumn`: number - Number of items per column
* `BTTActionCheatSheetItemHeight`: number - Height of each item
* `BTTActionCheatSheetWindowCornerRadius`: number - Window corner radius
* `BTTActionCheatSheetWindowWidth`: number - Window width
* `BTTActionCheatSheetWindowPadding`: number - Window padding
* `BTTActionCheatSheetItemBackground`: string - Item background color (hex)
* `BTTActionCheatSheetItemBorderColor`: string - Item border color (hex)
* `BTTActionCheatSheetShowIcon`: boolean - Show app icons
* `BTTActionCheatSheetShowActiveAppOnly`: boolean - Show only active app shortcuts
Example:
{
"BTTPredefinedActionType": 354,
"BTTAdditionalActionData": {
"BTTActionCheatSheetBackground": "#000000",
"BTTActionCheatSheetBackgroundAlpha": 0.9,
"BTTActionCheatSheetTitleTextColor": "#FFFFFF",
"BTTActionCheatSheetDescriptionTextColor": "#CCCCCC",
"BTTActionCheatSheetItemsPerColumn": 10,
"BTTActionCheatSheetShowIcon": true
}
}
### Hide/Toggle Cheat Sheet
> Controls cheat sheet visibility.
Parameters:
* **BTTPredefinedActionType**:
* Hide: 355
* Toggle: 356
Example:
{
"BTTPredefinedActionType": 356
}
### Open URL
> Opens URL in default browser.
Parameters:
* **BTTPredefinedActionType**: 59
* **BTTOpenURL**: URL to open
* **BTTOpenURLBrowser**: Specific browser (optional)
* **BTTOpenURLTerminalCommand**: Use terminal command flag (optional)
Example:
{
"BTTPredefinedActionType": 59,
"BTTOpenURL": "https://folivora.ai",
"BTTOpenURLBrowser": "com.apple.Safari"
}
### Post Distributed Notification
> Posts a system-wide notification.
Parameters:
* **BTTPredefinedActionType**: 136
* **BTTPostDistributedNotificationName**: Notification name
* **BTTActionUserInfo**: Notification data (optional)
Example:
{
"BTTPredefinedActionType": 136,
"BTTPostDistributedNotificationName": "com.myapp.notification"
}
### Change Input Source
> Changes keyboard input source/language.
Parameters:
* **BTTPredefinedActionType**: 420
* **BTTGenericActionConfig**: Input source ID
* **BTTAdditionalActionData**: JSON object with configuration (optional)
* `BTTActionChangeInputSourceID`: Input source identifier
* Other `BTTActionChangeInputSource*` keys for additional settings
Example:
{
"BTTPredefinedActionType": 420,
"BTTGenericActionConfig": "com.apple.keylayout.US",
"BTTAdditionalActionData": {
"BTTActionChangeInputSourceID": "com.apple.keylayout.US"
}
}
### Change Default Browser
> Changes system default browser.
Parameters:
* **BTTPredefinedActionType**: 492
* **BTTGenericActionConfig**: Browser bundle identifier
Example:
{
"BTTPredefinedActionType": 492,
"BTTGenericActionConfig": "com.google.Chrome"
}
### Set Function Key Mode
> Sets function key behavior.
Parameters:
* **BTTPredefinedActionType**: 436
* **BTTGenericActionConfig**: Mode (0=F keys, 1=media keys)
Example:
{
"BTTPredefinedActionType": 436,
"BTTGenericActionConfig": "1"
}
### Call macOS Service
> Calls a macOS service by name.
Parameters:
* **BTTPredefinedActionType**: 435
* **BTTGenericActionConfig**: Service name
Example:
{
"BTTPredefinedActionType": 435,
"BTTGenericActionConfig": "Look Up in Dictionary"
}
### Set Icon for File
> Sets custom icon for file/folder/app.
Parameters:
* **BTTPredefinedActionType**: 473
* **BTTGenericActionConfig**: File path
* **BTTGenericActionConfig2**: Icon path or data
Example:
{
"BTTPredefinedActionType": 473,
"BTTGenericActionConfig": "/Applications/MyApp.app",
"BTTGenericActionConfig2": "/path/to/icon.icns"
}
### Create Snap Area
> Creates a new window snap area.
Parameters:
* **BTTPredefinedActionType**: 391
* **BTTGenericActionConfig**: Snap area configuration
Example:
{
"BTTPredefinedActionType": 391,
"BTTGenericActionConfig": "{\"x\":0,\"y\":0,\"width\":640,\"height\":480}"
}
### Edit Snap Areas
> Opens snap area editor.
Parameters:
* **BTTPredefinedActionType**: 392
Example:
{
"BTTPredefinedActionType": 392
}
### Trigger Snap Area
> Triggers specific snap area.
Parameters:
* **BTTPredefinedActionType**: 168
* **BTTDragPointUUID**: Snap area identifier
* **BTTResizeWindowToRect**: Window rect (optional)
Example:
{
"BTTPredefinedActionType": 168,
"BTTDragPointUUID": "left-half"
}
### Plugin Action
> Executes a BTT plugin action.
Parameters:
* **BTTPredefinedActionType**: 280
* **BTTGenericActionConfig2**: Plugin identifier
* **BTTAdditionalActionData**: Plugin parameters
Example:
{
"BTTPredefinedActionType": 280,
"BTTGenericActionConfig2": "com.example.plugin",
"BTTAdditionalActionData": "{\"action\":\"custom\"}"
}
### Comment
> No-op action for adding comments in action sequences.
Parameters:
* **BTTPredefinedActionType**: 490
* **BTTComment**: Comment text
Example:
{
"BTTPredefinedActionType": 490,
"BTTComment": "This is a comment explaining the next actions"
}
### Separator
> Visual separator in action lists.
Parameters:
* **BTTPredefinedActionType**: 323
Example:
{
"BTTPredefinedActionType": 323
}
### AI Actions
> AI-related actions for ChatGPT integration.
Parameters:
* **BTTPredefinedActionType**:
* Add User Message: 530
* Switch Model: 537
* **BTTGenericActionConfig**: AI configuration
Example:
{
"BTTPredefinedActionType": 530,
"BTTGenericActionConfig": "{\"message\":\"Hello AI\",\"conversation\":\"main\"}"
}
### AI Chat Window
> Opens an AI chat window with customizable settings.
Parameters:
* **BTTPredefinedActionType**: 999
* **BTTAdditionalActionData**: JSON object with AI configuration
* `BTTAISystemPrompt`: string - System prompt for the AI
* `BTTAIAPIKey`: string - API key for AI service (secure)
* `BTTAIAPIKey1`: string - Alternative API key 1
* `BTTAIAPIKey2`: string - Alternative API key 2
* `BTTAICustomURL`: string - Custom API endpoint URL
* `BTTAIModel`: string - Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet-latest")
* `BTTAISInitialScreenshot`: number - Screenshot capture option (0=None, 1=Interactive, 2=Focused Window)
* `BTTAIUserChatBubbleColor`: string - Custom color for user messages (hex)
* `BTTAISystemChatBubbleColor`: string - Custom color for AI responses (hex)
* `BTTAIWindowBackgroundColor`: string - Background color for AI window (hex)
Example:
{
"BTTPredefinedActionType": 999,
"BTTAdditionalActionData": {
"BTTAIModel": "gpt-4o",
"BTTAISystemPrompt": "You are a helpful assistant",
"BTTAISInitialScreenshot": 1,
"BTTAIUserChatBubbleColor": "#0084FF",
"BTTAISystemChatBubbleColor": "#E9E9EB"
}
}
### Stage Manager Actions
> Controls macOS Stage Manager.
Parameters:
* **BTTPredefinedActionType**:
* Enable/Disable: 360
* Activate Stage: 357
* Cycle Stages: 358
* Cycle Backward: 363
* Activate Stage with Apps: 359
* Show Switcher: 361
* Toggle Recent: 362
* **BTTStageManagerStageNumber**: Stage number (for activate)
* **BTTStageManagerRequiredApps**: App identifiers (for activate with apps)
* **BTTStageManagerRequiredWindows**: Window identifiers (optional)
Example:
{
"BTTPredefinedActionType": 357,
"BTTStageManagerStageNumber": "1"
}
### Dock Actions
> Performs actions on dock items.
Parameters:
* **BTTPredefinedActionType**:
* Quit App: 145
* Minimize: 146
* Show All Windows: 147
* Send Shortcut: 148
Example:
{
"BTTPredefinedActionType": 145
}
### Toggle Actions
> Various toggle actions.
Parameters:
* **BTTPredefinedActionType**:
* Mouse Cursor Hidden: 140
* Cursor Size: 123
* Mouse Speed: 126
* Black Screen: 313
Example:
{
"BTTPredefinedActionType": 140
}
### Login/Security Actions
> Login and security related actions.
Parameters:
* **BTTPredefinedActionType**:
* Login Screen: 9
* Free Menu Bar: 86
Example:
{
"BTTPredefinedActionType": 9
}
### Advanced Click Actions
> Clicks with specific modifiers.
Parameters:
* **BTTPredefinedActionType**:
* Cmd+Click: 2
* Ctrl+Click: 87
* Alt+Click: 88
* Shift+Click: 89
* Cmd+Shift+Click: 111
* Cmd+Double Click: 149
Example:
{
"BTTPredefinedActionType": 2
}
### Gesture Control
> Controls for trackpad/mouse gestures.
Parameters:
* **BTTPredefinedActionType**:
* Begin Gesture: 75
* End Gesture: 76
* End Immediately: 83
* Swipe Left: 77
* Swipe Right: 78
* Swipe Up: 79
* Swipe Down: 80
* Rotate Left: 81
* Rotate Right: 82
Example:
{
"BTTPredefinedActionType": 75
}
### Zoom In/Out
> System zoom controls.
Parameters:
* **BTTPredefinedActionType**:
* Zoom In: 11
* Zoom Out: 12
Example:
{
"BTTPredefinedActionType": 11
}
### Window Snapping
> Split screen and window snapping.
Parameters:
* **BTTPredefinedActionType**:
* Split Screen Left: 163
* Split Screen Right: 164
Example:
{
"BTTPredefinedActionType": 163
}
### Fullscreen
> Fullscreen control.
Parameters:
* **BTTPredefinedActionType**: 112
Example:
{
"BTTPredefinedActionType": 112
}
### No Action
> Placeholder that performs no action.
Parameters:
* **BTTPredefinedActionType**: -1
Example:
{
"BTTPredefinedActionType": -1
}
* * *
Additional Missing Actions
--------------------------
### Change Default Browser/Handler
> Changes the default application handler for specific file types, URL schemes, or UTIs. Parameters:
>
> * **BTTPredefinedActionType**: 492
> * **BTTAdditionalActionData**: JSON object with configuration
> * `BTTActionChangeDefaultBrowserUTI`: string - Scheme/UTI/Extension (e.g. "http://", "adobe.pdf", ".txt")
> * `BTTActionChangeDefaultBrowserApp`: object - Application info
> * `name`: string - Application name
> * `path`: string - Path to application
> * `bundleIdentifier`: string - Bundle ID Example:
>
> {
> "BTTPredefinedActionType": 492,
> "BTTAdditionalActionData": {
> "BTTActionChangeDefaultBrowserUTI": "http://",
> "BTTActionChangeDefaultBrowserApp": {
> "name": "Safari",
> "path": "/Applications/Safari.app",
> "bundleIdentifier": "com.apple.Safari"
> }
> }
> }
>
>
### OCR (Extract Text from Image)
> Performs optical character recognition on screen content or images. Parameters:
>
> * **BTTPredefinedActionType**: 498
> * **BTTAdditionalActionData**: JSON object with OCR configuration
> * `BTTOCRSourceType`: number - Source type (0=screenshot, 1=file, 2=clipboard)
> * `BTTOCRFileAtPath`: string - Path to image file (when sourceType=1)
> * `BTTOCRAutoDetectLanguage`: boolean - Auto-detect language
> * `BTTOCRLanguages`: array - Language codes (e.g., \["en-US", "de-DE"\])
> * `BTTOCRCustomWords`: array - Custom words for recognition
> * `BTTOCRJoinBasedOnScreenCoordinates`: boolean - Join text based on position
> * `BTTOCRJoinFoundStringsWithCharacter`: string - Character to join text (e.g., " " or "\\n")
> * `BTTOCRSaveToVariable`: string - Variable name to save result
> * `BTTOCRCopyToClipboard`: boolean - Copy result to clipboard Example:
>
> {
> "BTTPredefinedActionType": 498,
> "BTTAdditionalActionData": {
> "BTTOCRSourceType": 0,
> "BTTOCRAutoDetectLanguage": true,
> "BTTOCRCopyToClipboard": true,
> "BTTOCRSaveToVariable": "ocr_result"
> }
> }
>
>
### Remap Key
> Remaps keyboard input with customizable modifier keys and key codes. Parameters:
>
> * **BTTPredefinedActionType**: 483
> * **BTTAdditionalActionData**: JSON object with key remapping configuration
> * `BTTActionRemapKeyOutDownCommand`: number (0/1) - Command key on key down
> * `BTTActionRemapKeyOutDownControl`: number (0/1) - Control key on key down
> * `BTTActionRemapKeyOutDownShift`: number (0/1) - Shift key on key down
> * `BTTActionRemapKeyOutDownOption`: number (0/1) - Option key on key down
> * `BTTActionRemapKeyOutDownFn`: number (0/1) - Fn key on key down
> * `BTTActionRemapKeyOutUpCommand`: number (0/1) - Command key on key up
> * `BTTActionRemapKeyOutUpControl`: number (0/1) - Control key on key up
> * `BTTActionRemapKeyOutUpShift`: number (0/1) - Shift key on key up
> * `BTTActionRemapKeyOutUpOption`: number (0/1) - Option key on key up
> * `BTTActionRemapKeyOutUpFn`: number (0/1) - Fn key on key up
> * `BTTActionRemapKeyOutKeyUsingKeyCode`: boolean - Use key code instead of string
> * `BTTActionRemapKeyOutKeyUsingString`: boolean - Use string instead of key code
> * `BTTActionRemapKeyOutKeyString`: string - Key as string (when using string mode)
> * `BTTActionRemapKeyOutKeyCode`: number - Key code (when using key code mode) Example:
>
> {
> "BTTPredefinedActionType": 483,
> "BTTAdditionalActionData": {
> "BTTActionRemapKeyOutDownCommand": 1,
> "BTTActionRemapKeyOutDownShift": 1,
> "BTTActionRemapKeyOutKeyUsingKeyCode": true,
> "BTTActionRemapKeyOutKeyCode": 0
> }
> }
>
>
### Send Data to Connected BTT Mobile/iOS Device
> Sends data to a connected BetterTouchTool mobile device. Parameters:
>
> * **BTTPredefinedActionType**: 285
> * **BTTAdditionalActionData**: JSON object with configuration
> * `BTTGenericDeviceSendDataInputMode`: number - Input mode
> * `BTTGenericDeviceSendDataKeySend`: string - Key to send
> * `BTTGenericDeviceSendDataSendOnUp`: boolean - Send on key up
> * `BTTGenericDeviceSendDataInput`: string - Data to send Example:
>
> {
> "BTTPredefinedActionType": 285,
> "BTTAdditionalActionData": {
> "BTTGenericDeviceSendDataInputMode": 0,
> "BTTGenericDeviceSendDataKeySend": "test_key",
> "BTTGenericDeviceSendDataInput": "Hello from Mac!"
> }
> }
>
>
### Unlock Screen (with Password)
> Unlocks the Mac screen using a stored password. Parameters:
>
> * **BTTPredefinedActionType**: 159
> * **BTTAdditionalActionData**: JSON object with configuration
> * `unlockPassword`: string - The password (stored securely) Example:
>
> {
> "BTTPredefinedActionType": 159,
> "BTTAdditionalActionData": {
> "unlockPassword": "encrypted_password_data"
> }
> }
>
>
* * *
Additional Notes
----------------
### Action Sequences
Multiple actions can be chained together by including them in an array:
[\
{\
"BTTPredefinedActionType": 345,\
"BTTDelayNextActionBy": "1.0"\
},\
{\
"BTTPredefinedActionType": 193,\
"BTTStringToType": "Hello World"\
}\
]
### Conditional Actions
Many actions support conditions via the `BTTTriggerConditionsData` field:
{
"BTTPredefinedActionType": 49,
"BTTLaunchPath": "/Applications/Safari.app",
"BTTTriggerConditionsData": {
"conditions": [\
{\
"type": "app_not_running",\
"bundle_identifier": "com.apple.Safari"\
}\
]
}
}
### Action Categories
Actions can be organized by category using `BTTActionCategory`:
* 0: Standard
* 1: Hover
* 2: Long Press
* 3: Touch Release
* 4: Hover End
* 5: Hyper Key Release
* 6: Right Click
* 7: Change to False
* 8: Appear
* 9: Disappear
### Helper Functions
function getModifierBitmask(modifiers) {
const modifierMap = {
"Shift": 1 << 17,
"Control": 1 << 18,
"Left Control": 1 << 0,
"Right Control": 1 << 13,
"Option": 1 << 19,
"Left Option": 1 << 5,
"Right Option": 1 << 6,
"Command": 1 << 20,
"Left Command": 1 << 3,
"Right Command": 1 << 4,
"Function": 1 << 23
};
let bitmask = 0;
for (const modifier of modifiers) {
if (modifierMap[modifier] !== undefined) {
bitmask |= modifierMap[modifier];
} else {
console.warn(`Unknown modifier: ${modifier}`);
}
}
return bitmask;
}
* 18: Custom Context Menu
### Generic Configuration Fields
When specific property names aren't mapped for an action, these generic fields are used as fallbacks:
* `BTTGenericActionConfig`: Primary configuration string/JSON (used when gesture.launchPath isn't specifically mapped)
* `BTTGenericActionConfig2`: Secondary configuration (used when gesture.additionalActionString isn't specifically mapped)
* `BTTAdditionalActionData`: Complex data as JSON or base64 (typically from gesture.actionData)
### Special Data Handling
Some actions use special data storage:
* `BTTFindPositionOfImageImage`: Base64 encoded image data
* `BTTFindPositionOfImageImageDark`: Base64 encoded dark mode variant
* `BTTActionCustomScriptSettings`: Base64 encoded script settings
* `BTTAdditionalActionData`: Can contain JSON objects or base64 encoded data
### Shortcuts and Modifiers
When using keyboard shortcuts:
* `BTTShortcutToSend`: The actual key or key combination
* `BTTShortcutModifierKeys`: Modifier keys for general shortcuts
* `BTTRequiredModifierKeys`: Modifier keys for non-shortcut triggers
* `BTTShortcutUpDown`: Whether to send key up/down events
### Best Practices
1. Always include `BTTPredefinedActionType` with the correct action ID
2. Use the specific property names documented here instead of generic fallbacks when possible
3. String values should be properly escaped in JSON
4. Numeric values can be strings or numbers depending on the action
5. Test actions individually before combining in sequences
6. Use conditions to make actions context-aware
7. Leverage variables for dynamic behavior
8. Group related actions using control flow structures
This documentation covers all available BetterTouchTool actions as of the current version. Actions may be added or modified in future releases.
results matching ""
===================
No results matching ""
======================
---
# Simple JSON Format · GitBook
[Simple JSON Format](https://docs.folivora.ai/)
================================================
BetterTouchTool Simple JSON Format
==================================
BetterTouchTool 4.764 introduced a new "Simple JSON Format", which can currently be used with the predefined actions "Show Custom Context Menu (New)" and "Choose From List" and with Floating Menus. It allows to retrieve the content for those menus dynamically using Java Script & JSON. It allows you to use any of [BTT's Java Script capabilities](https://docs.folivora.ai/docs/1106_java_script.html)
to produce the output JSON.
* [BetterTouchTool Simple JSON Format](https://docs.folivora.ai/docs/1108_simple_format.html#bettertouchtool-simple-json-format)
* [How to create dynamic menus based on the Simple JSON Format](https://docs.folivora.ai/docs/1108_simple_format.html#how-to-create-dynamic-menus-based-on-the-simple-json-format)
* [Supported Properties](https://docs.folivora.ai/docs/1108_simple_format.html#supported-properties)
* [Simple example](https://docs.folivora.ai/docs/1108_simple_format.html#simple-example)
* [Allowed Properties:](https://docs.folivora.ai/docs/1108_simple_format.html#allowed-properties)
* [title](https://docs.folivora.ai/docs/1108_simple_format.html#title)
* [subtitle](https://docs.folivora.ai/docs/1108_simple_format.html#subtitle)
* [subitems](https://docs.folivora.ai/docs/1108_simple_format.html#subitems)
* [setvariable](https://docs.folivora.ai/docs/1108_simple_format.html#setvariable)
* [templateitemuuid](https://docs.folivora.ai/docs/1108_simple_format.html#templateitemuuid)
* [icon](https://docs.folivora.ai/docs/1108_simple_format.html#icon)
* [action](https://docs.folivora.ai/docs/1108_simple_format.html#action)
* [named](https://docs.folivora.ai/docs/1108_simple_format.html#named)
* [uuid](https://docs.folivora.ai/docs/1108_simple_format.html#uuid)
* [shortcut](https://docs.folivora.ai/docs/1108_simple_format.html#shortcut)
* [js](https://docs.folivora.ai/docs/1108_simple_format.html#js)
* [btt](https://docs.folivora.ai/docs/1108_simple_format.html#btt)
* [keyboard](https://docs.folivora.ai/docs/1108_simple_format.html#keyboard)
* [Action Categories](https://docs.folivora.ai/docs/1108_simple_format.html#action-categories)
* [Examples](https://docs.folivora.ai/docs/1108_simple_format.html#examples)
* [Example: Create an AI / App Launcher:](https://docs.folivora.ai/docs/1108_simple_format.html#example-create-an-ai--app-launcher)
* [Example: Get result from Apple Shortcut:](https://docs.folivora.ai/docs/1108_simple_format.html#example-get-result-from-apple-shortcut)
* [Example: Execute multiple actions from one item (example types abc)](https://docs.folivora.ai/docs/1108_simple_format.html#example-execute-multiple-actions-from-one-item-example-types-abc)
* [Example: Fetch menu from some server:](https://docs.folivora.ai/docs/1108_simple_format.html#example-fetch-menu-from-some-server)
* [Example: Usage With Custom Menu Bar Items](https://docs.folivora.ai/docs/1108_simple_format.html#example-usage-with-custom-menu-bar-items)
* [Example: Floating Menu App Switcher](https://docs.folivora.ai/docs/1108_simple_format.html#example-floating-menu-app-switcher)
* [Typescript Definition](https://docs.folivora.ai/docs/1108_simple_format.html#typescript-definition)
How to create dynamic menus based on the Simple JSON Format
-----------------------------------------------------------
For the predefined actions "Show Custom Context Menu" and "Choose From List" you need to click the "Retrieve Content Dynamically Via Java Script" checkbox. 
For Floating Menus you need to set a Content Script. 
Then you can have a async function that returns a JSON. You can use any of BTT's [scripting functions](https://docs.folivora.ai/docs/1106_java_script.html)
inside that Java Script (e.g. run Shell or Apple Scripts and much more). **Note** Make sure to set the async function to call in the separate text field.
Supported Properties
--------------------
* [title](https://docs.folivora.ai/docs/1108_simple_format.html#title)
* [subtitle](https://docs.folivora.ai/docs/1108_simple_format.html#subtitle)
* [icon](https://docs.folivora.ai/docs/1108_simple_format.html#icon)
* [setvariable](https://docs.folivora.ai/docs/1108_simple_format.html#setvariable)
* [subitems](https://docs.folivora.ai/docs/1108_simple_format.html#subitems)
* [templateItemUUID](https://docs.folivora.ai/docs/1108_simple_format.html#templateitemuuid)
* [action](https://docs.folivora.ai/docs/1108_simple_format.html#action)
Simple example
--------------
async function retrieveJSON() {
let items = [\
{\
"title": "trigger some shortcut",\
"icon": "sfsymbol::globe",\
"action": "shortcut::TheShortcutFromTheShortcutsApp"\
},\
{\
"title": "trigger some named trigger",\
"icon": "sfsymbol::house",\
"action": "named::TheNameOfTheBTTNamedTrigger"\
}\
];
return JSON.stringify(items);
}
**Complex example**
async function retrieveJSON() {
let items = [\
{\
"title": "hello world",\
"icon": "sfsymbol::globe"\
},\
{\
title: "some title",\
subtitle: "some subtitle",\
subitems: [\
{\
title: "some sub-item",\
action: "named::NameOfNamedTriggerInBTT",\
icon: "sfsymbol::house::weight@@light::size@@30"\
},\
{\
title: "some sub-item2",\
icon: "base64::iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",\
action: "shortcut::NameOfShortcutInShortcutsApp@@OptionalInput"\
},\
],\
icon: "sfsymbol::star::color@@B53E93",\
// this shows various forms of actions. In case you are just triggering\
// a single action, it does not need to be an array.\
action: [\
`btt::paste_text@@{"text": "hello world"}`,\
"keyboard::0", //type a\
"keyboard::11", //type b\
"keyboard::8", //type c\
"js::runShellScript({script: `say hello`})",\
{\
btt: "paste_text",\
args: {\
text: "hello world 2",\
insert_by_pasting: true,\
},\
},\
\
{\
shortcut: "theNameOfTheShortcut",\
input: "some optional input",\
},\
],\
},\
];
return JSON.stringify(items);
}
 
You'll find more examples on [https://community.folivora.ai](https://community.folivora.ai/)
for example here is an example that will list all apps / files in a specified folder: [Example to list all files in a folder](https://community.folivora.ai/t/show-folder-content-in-custom-context-menu/39331/3?u=andreas_hegenberg)
* * *
Allowed Properties:
===================
title
-----
supported properties color & size
Examples:
{
"title": "hello::size@@30::color@@#000000"
}
Alternative syntax:
{
"title": {
"text": "some title",
"size": 30,
"color": "#000000"
}
}
* * *
subtitle
--------
supported properties color & size. Only works in the "choose from list action".
Examples:
{
"subtitle": "some subtitle::size@@30::color@@#000000"
}
Alternative syntax:
{
"subtitle": {
"text": "some subtitle",
"size": 30,
"color": "#000000"
}
}
* * *
subitems
--------
Examples:
{
"title": "submenu",
"subitems": [\
{\
"title": "hello"\
},\
{\
"title": "world"\
}\
]
}
* * *
setvariable
-----------
this allows to set a variable value before the action is executed. If the simple string based action format is used, the **setvariable** must be at the top level of the item definition. If you have multiple actions all string based actions will use that setvariable definition. If you use the object based action definition you can set a variable per action.
Examples:
{
"title": "some item title",
"action": "keyboard::0"
"setvariable": "variablename@@value"
}
Alternative syntax:
{
"title": "some item title",
"setvariable": {
"name": "variablename",
"value": "test"
},
"action": [\
"keyboard::0",\
"keyboard::1" \
]
}
Alternative syntax with actions as objects:
{
"title": "some item title",
"action": [\
{\
btt: "paste_text",\
setvariable: {\
name: "the_variable",\
value: "some text",\
},\
\
args: {\
text: "(BTT)@variable:the_variable(BTT)",\
insert_by_pasting: true,\
},\
},\
{\
btt: "paste_text",\
setvariable: {\
name: "some_other_variable",\
value: "some other text",\
},\
\
args: {\
text: "(BTT)@variable:some_other_variable(BTT)",\
insert_by_pasting: true,\
},\
} \
]
}
* * *
templateitemuuid
----------------
This is only for use within [Floating Menus](https://docs.folivora.ai/docs/1600_floating_menus.html)
, it allows you to use the configuration of any Floating Menu Item you have created in the BTT UI as a template. You can get the UUID of any item in BTT by right-clicking it. The item used as a template can also be from a disabled menu and can even be disabled itself.
Examples:
[{\
templateItemUUID: "1D974882-9376-4B09-81FC-E427F79CBD25",\
"title": "some title"\
},\
{\
templateItemUUID: "1D974882-9376-4B09-81FC-E427F79CBD25",\
"title": "another title",\
"icon": "sfsymbol::sun.max"\
},\
{\
templateItemUUID: "1D974882-9376-4B09-81FC-E427F79CBD25",\
"title": "third title",\
"icon": "sfsymbol::house"\
}\
]
* * *
icon
----
this allows to define an icon
Supported properties: type (sfsymbol, size, path, base64, background, width, height)
Examples:
{
"icon": "sfsymbol::star"
}
Or with more options:
{
"icon": "sfsymbol::star::weight@@light::color@@#fefefe::color@@#000000::background@@#B53E93"
}
From file:
{
"icon": "path::~/Downloads/test.png::width@@40::height@@40"
}
From base64:
{
"icon": "base64::base64code"
}
Alternative syntax:
{
"icon": {
"type": "sfymbol",
"sfymbol": "star",
"weight": "light",
"colors" : ["#000000", "#fefefe"],
"background": "#B53E93",
"size" : 30
}
}
* * *
action
------
Supported properties named, shortcut, js, keyboard, uuid, btt. Can also be an array of actions.
* * *
### named
This will trigger a named trigger configured in BTT (see [http://docs.folivora.ai/docs/1002\_named\_triggers.html](http://docs.folivora.ai/docs/1002_named_triggers.html)
)
{"title": "trigger named trigger", "action": "named::theNameOfTheNamedTrigger"},
Alternative syntax:
{
"title": "trigger named trigger alternative",
"action": {
"named": "helloworld"
},
"icon": "sfsymbol::star.leadinghalf.filled"
}
* * *
### uuid
This will trigger any trigger configured in BTT using its UUID
{"title": "trigger via uuid", "action": "uuid::4ff033d2-8f67-490d-b281-3124d452ef07"},
Alternative syntax:
{
"title": "trigger via UUID alternative",
"action": {
"uuid": "4ff033d2-8f67-490d-b281-3124d452ef07"
}
}
* * *
### shortcut
This will trigger a shortcut configured in Apple's shortcuts app
{"title": "trigger shortcut form shortcuts app", "action": "shortcut::theNameOfTheShortcut@@someOptionalInput"},
Alternative syntax:
{
"title": "trigger shortcut form shortcuts app alternative",
"action": {
"shortcut": "theNameOfTheShortcut",
"input": "some optional input"
}
}
* * *
### js
This will run BTT Java Script which also allows to run shell scripts or apple scripts and trigger ny of BTT's scripting functions ([http://docs.folivora.ai/docs/1106\_java\_script.html](http://docs.folivora.ai/docs/1106_java_script.html)
)
E.g. run some shell script:
{"title": "say hello", "action": "js::runShellScript({script: `say hello`})"},
Or run some arbitrary apple script:
{
title: "show some apple script dialog",
action: {
js: `(async () => {
// put the Apple Script into a string (back ticks are great for multi-line strings)
let appleScript = \`
set theDialogText to "The curent date and time is " & (current date) & "."
set result to display dialog theDialogText
return result
\`;
// this will execute the Apple Script and store the result in the result variable.
let result = await runAppleScript(appleScript);
// do whatever you want with the result
// at the end you always need to call returnToBTT to exit the script / return the value to BTT.
returnToBTT(result);
// it is important that this function self-executes ()
})()
`,
},
},
* * *
### btt
This can run any of BTT's scripting functions ([http://docs.folivora.ai/docs/1102\_apple\_script.html](http://docs.folivora.ai/docs/1102_apple_script.html)
). To see how to configure & trigger a specific action you can right-click the action in BTT and choose "copy java script to trigger action".
"action": `btt::paste_text@@{"text": "hello world"}`
Alternative syntax
{
"title": "paste item 1",
"action": {
"btt":"paste_text",
"args": {
"text": "ddasdas",
"insert_by_pasting": true
}
}
},
{
"title": "application expose",
"action": {
"btt": "trigger_action",
"args": {
"json": {
"BTTActionCategory": 0,
"BTTPredefinedActionType": 6,
"BTTPredefinedActionName": "Application Expose"
}
}
}
}
* * *
### keyboard
This can trigger a keyboard shortcut.
It needs to constist of comma separated modifier keys (cmd, shift, opt, fn, ctrl) and one key code at the end. A list of key codes can e.g. be found here: [https://eastmanreference.com/complete-list-of-applescript-key-codes](https://eastmanreference.com/complete-list-of-applescript-key-codes)
"action": "keyboard::shift,opt,0"
Action Categories
-----------------
Some items in BTT support different action categories, e.g. a floating menu button that can trigger one action on left-click but another action on right-click. If you want to make us of that, instead of defining your action via the "action" property, you need to define it via the "actions" property. The syntax for every action category defined in the "actions" object is the same as discussed in the previous section.
{
title: "test item 0",
actions: {
standard: "keyboard::0",
rightclick: "keyboard::1"
},
}
Possible action category names are listed here, however they availability depends on the BTT feature you are using:
* standard
* rightclick
* hover
* longpress
* touchrelease
* hoverend
* hyperkeyrelease
* changetofalse
* appear
* disappear
* ondrop
Examples
========
Example: Create an AI / App Launcher:
-------------------------------------
The tutorial for this is available in our community forum: [https://community.folivora.ai/t/tutorial-ai-and-app-launcher-using-the-new-scriptable-choose-from-list/39811](https://community.folivora.ai/t/tutorial-ai-and-app-launcher-using-the-new-scriptable-choose-from-list/39811)
Example: Get result from Apple Shortcut:
----------------------------------------
async function retrieveJSON() {
let weather = await runAppleShortcut({name: "weather", "input": ""});
let items = [\
{"title": weather},\
{"title": "test item 2"},\
{"title": "test item 3", "icon": "sfsymbol::star"}\
];
return JSON.stringify(items);
}
Example: Execute multiple actions from one item (example types abc)
-------------------------------------------------------------------
async function retrieveJSON() {
let items = [\
{\
"title": "multiple actions (type abc)", \
"action": [\
"keyboard::0", //type a\
"keyboard::11", //type b\
"keyboard::8", //type c\
],\
"icon": "sfsymbol::keyboard"\
},\
];
return JSON.stringify(items);
}
Example: Fetch menu from some server:
-------------------------------------
async function retrieveJSON() {
const response = await fetch('https://folivora.ai/various/test-menu.json');
const data = await response.json();
const jsonString = JSON.stringify(data);
return jsonString;
}
Example: Usage With Custom Menu Bar Items
-----------------------------------------
Works with custom menubar items as well when assigning the "Show Context Menu New" action: 
Example: Floating Menu App Switcher
-----------------------------------
Preset download: [https://share.folivora.ai/sharedPreset/55076196-7d17-4b8f-bbae-4dbd17c3ad87](https://share.folivora.ai/sharedPreset/55076196-7d17-4b8f-bbae-4dbd17c3ad87)
Code:
async function retrieveJSON() {
// this calls a internal BTT function to get all launched apps sorted by last usage
let apps = await BTTActions.copyLaunchedApplicationsInFrontToBackOrder();
let menuItems = [];
let i=0;
for (let app of apps) {
// we only want to show 10 apps
if(i>9) {break;}
i++;
let item = {
templateItemUUID: "BFBD1B46-0E72-49CF-B4DB-C2CB017E82B2",
title: "",
action: `js::(async () => {runShellScript({script: 'open "${app.BundlePath}"'})})()`,
icon: `path::${app.AppIconPath}::width@@40`
};
menuItems.push(item);
}
return JSON.stringify(menuItems);
}
Typescript Definition
=====================
Here is a basic \*.d.ts that tries to describe the structure:
declare module "SimpleFormat" {
// The root format is an array of SimpleFormatItems.
export type SimpleFormat = SimpleFormatItemBase[];
export interface SimpleFormatItemBase {
title?: string | AttributedText;
meta?: string; // some meta information, can e.g. used when filtering searchable list
type?: SimpleFormatItemType;
submenu?: SimpleFormatItemBase[];
background?: string;
icon?: string | IconDefinition;
actions?: { [key in ActionCategory]?: Action }; // this can be used if an item supports more than one action category
action?: Action;
setvariable?: string | SetVariableDefinition;
}
// Represents a single "Choose From List" Item
export interface SimpleFormatItemChooseFromList extends SimpleFormatItemBase {
subtitle?: string | AttributedText;
}
// Represents a single Floating Menu Item
export interface SimpleFormatItemFloatingMenu extends SimpleFormatItemBase {
width?: number;
height?: number;
templateitemuuid?: string; // defines the base item to use as template
}
// Represents the definition of an icon, which can be specified in various ways.
export interface IconDefinition {
type: "sfsymbol" | "path" | "base64";
value?: string; // For 'sfsymbol' type.
path?: string; // For 'path' type.
base64?: string; // For 'base64' type.
weight?: string; // Applicable for 'sfsymbol'.
size?: number; // Applicable for 'sfsymbol'.
colors?: RGBAColor[]; // Applicable for 'sfsymbol'.
background?: RGBAColor;
width?: number;
height?: number;
}
// Represents a variable setting action.
export interface SetVariableDefinition {
name: string;
value: string;
}
// Base interface for actions that can have a 'setvariable' property.
interface BaseAction {
setvariable?: string | SetVariableDefinition;
}
// Action type for executing BTT scripts.
export interface BTTAction extends BaseAction {
btt: string;
input?: any;
args?: any;
json?: any;
}
// Action type for triggering named triggers in BTT.
export interface NamedAction extends BaseAction {
named: string;
}
// Action type for triggering actions by UUID in BTT.
export interface UUIDAction extends BaseAction {
uuid: string;
}
// Action type for executing JavaScript code.
export interface JSAction extends BaseAction {
js: string;
}
// Action type for performing keyboard shortcuts.
export interface KeyboardAction extends BaseAction {
keyboard: string;
}
// Action type for running Shortcuts app shortcuts.
export interface ShortcutAction extends BaseAction {
shortcut: string;
input?: string;
}
// Defines the action, which can be a string, an action definition, or an array of actions.
export type Action =
| string
| ActionString
| ActionDefinition
| (string | ActionString | ActionDefinition)[];
// Union type of all possible action definitions.
export type ActionDefinition =
| BTTAction
| NamedAction
| UUIDAction
| JSAction
| KeyboardAction
| ShortcutAction;
export type ActionCategory =
| "standard"
| "hover"
| "longpress" //not yet supported
| "touchrelease" //not yet supported
| "hoverend"
| "hyperkeyrelease" //not yet supported
| "rightclick"
| "changetofalse" //not yet supported
| "appear"
| "disappear"
| "ondrop";
// Represents attributed text, which can be a simple string or an object with styling.
export type AttributedText =
| string
| {
text: string;
color?: RGBAColor;
size?: string;
};
// Represents the possible item types, matching the Swift enum.
export type SimpleFormatItemType =
| "standard"
| "separator" //requires BTT 4.805, in previous versions set the title of an item to ---
| "back" //floating menu only
| "textField" //floating menu only
| "slider"; //floating menu only
// these are attempts at defining the string based definitions
type Digit = `${number}`;
type Whitespace = " " | "";
type Comma = `${Whitespace},${Whitespace}`;
export type RGBAColor =
`rgba(${Whitespace}${Digit}${Whitespace}${Comma}${Digit}${Whitespace}${Comma}${Digit}${Whitespace}${Comma}${Digit}${Whitespace})`;
// Type representing known icon types.
type IconType = "sfsymbol" | "path" | "base64";
// Type representing known icon keys.
type IconKey =
| "weight"
| "color"
| "background"
| "size"
| "width"
| "height";
// Type representing a key-value pair in icon strings.
type IconKeyValuePair = `::${IconKey}@@${string}`;
// Icon string pattern with up to 5 key-value pairs.
export type IconString =
| `${IconType}::${string}`
| `${IconType}::${string}${IconKeyValuePair}`
| `${IconType}::${string}${IconKeyValuePair}${IconKeyValuePair}`
| `${IconType}::${string}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}`
| `${IconType}::${string}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}`
| `${IconType}::${string}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}${IconKeyValuePair}`;
// Type representing known action types.
type ActionType = "btt" | "keyboard" | "js" | "uuid" | "named" | "shortcut";
// Type representing known action keys.
type ActionKey = "input" | "function" | "args" | "json";
// Type representing a key-value pair in action strings.
type ActionKeyValuePair = `@@${string}`;
// Action string pattern with optional key-value pair.
export type ActionString =
| `${ActionType}::${string}`
| `${ActionType}::${string}${ActionKeyValuePair}`;
}
results matching ""
===================
No results matching ""
======================
---
# Stream Deck · GitBook
[Stream Deck](https://docs.folivora.ai/)
=========================================
BetterTouchTool Stream Deck
===========================
Starting with version 3.800 BetterTouchTool supports all of the various Stream Deck devices: [https://www.elgato.com/de/stream-deck](https://www.elgato.com/de/stream-deck)
Examples to get started:
------------------------
Download the example preset and look at the various examples described here.
[Example Preset Direct Link](https://folivora.ai/releases/ExampleStreamDeck.bttpreset)
List of examples:
* [Standard button with various formatting options applied](https://docs.folivora.ai/docs/1301_stream_deck_standard_button.html)
* [Button with different actions for long press and short press](https://docs.folivora.ai/docs/1302_stream_deck_long_press.html)
* [Button which repeats its actions while being pressed](https://docs.folivora.ai/docs/1303_stream_deck_repeat.html)
* [Showing / changing buttons while holding other buttons](https://docs.folivora.ai/docs/1304_changing_buttons_while_holding.html)
* [Showing buttons only on specific devices](https://docs.folivora.ai/docs/1305_stream_deck_specific_devices.html)
* [Groups](https://docs.folivora.ai/docs/1306_stream_deck_groups.html)
* [Stream Deck Pedal](https://docs.folivora.ai/docs/1307_stream_deck_pedal.html)
* [App Specific Configurations](https://docs.folivora.ai/docs/1308_stream_deck_appspecific.md)
* [Script Widgets](https://docs.folivora.ai/docs/1309_script_widgets.html)
* [Custom Swift Plugins](https://docs.folivora.ai/docs/1310_custom_swift_plugins.html)
Basics:
-------
### Operating Mode
BetterTouchTool supports two oeprating modes for the Stream Deck devices.
### Mode 1 (preferred): Fully Controlled by BetterTouchTool
This is the preferred and most performant mode.
In this mode, you must not be running the original Stream Deck software. BetterTouchTool directly talks to the Stream Deck devices.
In this mode you just configure everything in BetterTouchTool. No additional setup is necessary.
**This mode is only possible due to the open source code from the awesome Hammerspoon app. For even more advanced automations (via Lua scripting) you should check it out at [https://www.hammerspoon.org/](https://www.hammerspoon.org/)
**
### Mode 2: Stream Deck Plugin
In this mode you'll need to install a Stream Deck Plugin and place multiple copies of it in your configuration in the original Stream Deck software. BetterTouchTool will then talk to the original Stream Deck software to render the buttons you configure. When pressing one of the buttons, the original Stream Deck software will talk to BetterTouchTool to execute the assigned actions.
In Plugin mode it is recommended to use fixed identifiers to correctly place the BTT items on your Stream Deck. See next.
BetterTouchTool Stream Deck Layout Concept
------------------------------------------
The Stream Deck items in BTT are (like anything else in BTT) defined as a list. You can reorder that list by dragging the items around.
By default BetterTouchTool starts placing buttons / widgets from that list on the top left of the Stream Deck and then just continues until the row is full. It then continues by placing items in the next row - and so on. If all rows are full, BTT automatically adds a new page and starts again on the top left of that page.
In case you do have some more dynamic scenario, the order defined by the list in BTT might not be enough. For these cases there are two additional options:
### 1.) Display Order
You can use the "display order" property in the settings of every item to define a additional
### 2.) Fixed Position
However BetterTouchTool also allows you to specify specific positions for items. (e.g. row 3 col 2). If BTT is fully controlling the Stream Deck you can set the specific row and column in the item's configuration, otherwise you can tell BTT to place the item on a specific identifier defined in the Stream Deck app.
By default all buttons are visible on any connected Stream Deck device, however you can make them only display only on devices with specific serial numbers
### 3.) Fixed Identifier in Plugin Mode
When using BetterTouchTool in Plugin Mode, you can not specify the row / col directly. Instead you can set an identifier that matches the identifier you set in the Stream Deck software.
results matching ""
===================
No results matching ""
======================
---
# Notch Bar (Deprecated) · GitBook
[Notch Bar (Deprecated)](https://docs.folivora.ai/)
====================================================
BetterTouchTool Notch Bar
=========================
### Deprecation Notice 06/2023:
The Notch Bar functionality will sometime in the near future be migrated to the powerful new "Floating Menu / Widget" functionality. This should mostly be automatic, but if you start right now, I'd recommend to experiment with the Floating Menu's instead of the Notch Bar.
* * *
The Notch Bar was introduced with BetterTouchTool 3.690 and is intended to be a super customizable menubar replacement for any type of Mac. It is called Notch Bar, because it is especially useful on Macbooks with a Notch. 
Also have a look at this recent MacStories article: [MacStories: Early Experiments with BetterTouchTools Notch Bar](https://www.macstories.net/mac/early-experiments-with-bettertouchtools-notch-bar-as-a-visual-shortcuts-launcher-for-macos/)
Example Preset
--------------
Here is a small example preset that showcases most of the Notch Bar functionality:
[Example Preset Direct Link](https://folivora.ai/releases/ExampleNotchBarNew.bttpreset)
Quick Start
-----------
* If possible, **please use a dark wallpaper**, so your standard macOS menubar shows white icons and white text. In this mode the BTT Notch Bar works best.
* As soon as you add your first Notch Bar trigger, your macOS menubar will go away. To hide the BTT Notch Bar use the predefined action "Toggle BTT Notch Bar" or right-click the black area.
* The BTT Notch Bar offers two modes: **Widget Mode** and **Menubar Mode**. To switch between modes, **scroll up/down on the Notch Bar**, alternatively use the predefined action "Toggle BTT Notch Bar Mode" or right-click the Notch Bar.
* Use the **Status Item Widget** to show the system's top right status items on the BTT Notch Bar.
* There is currently a known incompatibility with an app called Magnet. The Notch Bar does not behave correctly while this app is running.
**Please use the community platform to learn more or share your ideas / setups**:
[https://community.folivora.ai](https://community.folivora.ai/)
More Notch Bar Topics:
======================
* [Notch Bar Setup](https://docs.folivora.ai/docs/1201_notch_bar_setup.html)
* [Notch Bar Item Placement](https://docs.folivora.ai/docs/1203_notch_bar_placement.html)
* [Notch Bar Customization](https://docs.folivora.ai/docs/1202_notch_bar_customization.html)
results matching ""
===================
No results matching ""
======================
---
# Notch Bar Placement · GitBook
[Notch Bar Placement](https://docs.folivora.ai/)
=================================================
BetterTouchTool Notch Bar Item Placement
========================================
The Notch Bar is split into 4 parts. On the very left is a fixed area that is not scrollable. This is followed by a scrollable area that goes to the left edge of the Notch and another scrollable area that comes right after the Notch. At the end there is again a fixed non-scrollable area on the very right.
The fixed areas have higher priority, this means if you put many items into the fixed left or right areas, the scrollable areas will become smaller.
On standard screens you might not need both of the scrollable areas.
results matching ""
===================
No results matching ""
======================
---
# Generic Devices · GitBook
[Generic Devices](https://docs.folivora.ai/)
=============================================
Generic Device Support
======================
Many input devices produce relatively simple output, however, they can be difficult to use without proper software support. To make it possible to use almost any input device with BetterTouchTool, I have begun working on "Generic Device Support." The concept is straightforward. BTT connects to a device and provides you with raw input data. You write a small JavaScript function that interprets the input data and activates triggers in BTT.
This is a work in progress and there is not much documentation available yet. In this example video I'm using the Siri Remote as an example and show how to make BetterTouchTool recognize its buttons:
results matching ""
===================
No results matching ""
======================
---
# Notch Bar Customization · GitBook
[Notch Bar Customization](https://docs.folivora.ai/)
=====================================================
BetterTouchTool Notch Bar Customization
=======================================
Standard Customization
----------------------
Every item or widget you put onto the Notch Bar does offer the option to add extra CSS styles or classes to it (scroll to the very bottom of the UI/Colors section). This is the easiest way to achieve customization. 
HTML Widgets
------------
BetterTouchTool allows you to add completely custom HTML, CSS and Java Script widgets. These widgets can contain any HTML/CSS/JS that is supported by the latest Safari.
To trigger the actions assigned to the custom HTML widget in BTT, use the triggerAssignedActions function like this:
Something
Full Customization
------------------
The BTT Notch Bar is **completely** customizable because it is based on HTML5. All templates are located in ~/Library/Application Support/BetterTouchTool/NotchBar
You can use any function available to the BTT floating webview, see
* \[Floating HTML Menu\] (10\_0\_floating\_html\_menu.md)
However these files can change when upgrading to a newer BTT version (BTT will ask what to do when a new version contains changes). In general it's best to just edit the two user files which will not be changed on BTT updates.:
BTTNotchBarUser.css BTTNotchBarUser.js
In case you need to include custom Notch Bar layouts in your presets, you can also move them to ~/Library/Application Support/BetterTouchTool/PresetBundles/YOURPRESETFOLDER, then they will be exported when you export your preset.
results matching ""
===================
No results matching ""
======================
---
# Example Device Scripts · GitBook
[Example Device Scripts](https://docs.folivora.ai/)
====================================================
User Generated Device Scripts to use the devices on macOS
=========================================================
Surface Dial
------------
[Surface Dial on community.folivora.ai](https://community.folivora.ai/t/generic-devices-report-repeated-events-even-if-monitored-bytes-dont-change/30101/11?u=andreas_hegenberg)
Griffin Power Mate
------------------
[https://heavyconsulting.net/blog/2023/2023-02-02-touch-of-power](https://heavyconsulting.net/blog/2023/2023-02-02-touch-of-power)
Philips Foot Pedal
------------------
[Philips Foot Pedal on community.folivora.ai](https://community.folivora.ai/t/generic-devices-philips-footcontrol-acc2330/30751)
Microsoft Presenter+
--------------------
[Microsoft Presenter+ community.folivora.ai](https://community.folivora.ai/t/generic-devices-help-microsoft-presenter/35915/5)
Xbox Adaptive Controller
------------------------
[Xbox Adaptive Controller on community.folivora.ai](https://community.folivora.ai/t/generic-devices-please-give-function-analyzedeviceinput-access-to-the-previous-state/30592/9?u=andreas_hegenberg)
PS4 Dualshock
-------------
[PS4 Dualshock on community.folivora.ai](https://community.folivora.ai/t/generic-devices-ps4-dualshock/34868/10?u=andreas_hegenberg)
results matching ""
===================
No results matching ""
======================
---
# Notch Bar Setup · GitBook
[Notch Bar Setup](https://docs.folivora.ai/)
=============================================
BetterTouchTool Notch Bar Setup
===============================
The Notch Bar setup allows you to hide or show specific containers on the Notch Bar.
One important setting is the "Show original status icons" option. This allows you to either show the real macOS status items or hide them to make space for other things. If you decide to hide the original status icons for some mode, you can still use the "Status Items Widget" to get access to a subset of your items.
By default the original status icons are shown while in Menubar Mode but are hidden in Widget Mode.
results matching ""
===================
No results matching ""
======================
---
# Unknown
\# h@llo.ai - Specialized Sub Agents Subagents can be configured in the "Automations, Named & Other Triggers" section: !\[Agent\](media/3013\_halloai\_subagents2025-09-17T06:44:03.803Z.png) To make them available in your main assistant, you need to enable them in the "allowed subagents" section in your main assistant configuration: !\[alt text\](media/3013\_halloai\_subagents2025-09-17T06:46:44.664Z.png) In case your subagent doesn't show up there, try to open & close your main assistant once. More coming soon!
---
# 404 Not Found
Not Found
=========
The requested URL was not found on this server.
* * *
Apache Server at docs.folivora.ai Port 443
---
# 404 Not Found
Not Found
=========
The requested URL was not found on this server.
* * *
Apache Server at docs.folivora.ai Port 443
---
# 404 Not Found
Not Found
=========
The requested URL was not found on this server.
* * *
Apache Server at docs.folivora.ai Port 443
---