Advanced Configuration

Overview

For power users, developers, and system administrators, Snapzy supports advanced programmatic configuration using a standard TOML file (config.toml). This allows you to manage all application preferences in plain text, sync them using dotfiles repositories, and set up automated deployments across macOS environments.

Getting Started

1. Enable Configuration Access

Open Snapzy Preferences (Cmd + ,) and navigate to the Advanced tab.
Click Set Up config.toml.
A native file dialog will prompt you to select or grant access to the configuration directory. Select the directory (usually ~/.config/snapzy/) and click Grant Access.

Once access is granted, Snapzy will automatically generate a default config.toml at:

~/.config/snapzy/config.toml

2. Synchronization & Background Loading

Auto-Apply on Launch: Snapzy parses and validates config.toml every time the application launches.
Background Sync: The app monitors config.toml for changes in the background. Edits made directly in your editor are validated and applied automatically within seconds (debounced to avoid incomplete reads).
Manual Sync: You can click Sync config.toml under Advanced Preferences to reload configurations instantly.
Restore Defaults: Clicking Restore Defaults in the UI regenerates the default TOML file, overwriting existing properties with original factory values.

Fully Commented Example TOML

Below is a complete template of a valid config.toml file with all available configurations and comments explaining each attribute.

# Snapzy TOML Configuration Schema Version (Must be 1)
schema_version = 1

# Minimum required Snapzy version for this file
snapzy_min_version = "1.20.0"

[general]
language = "system"                # "system" or language code: "en", "vi", "ja", "ko", "ru", "zh", "zh-tw"
appearance = "system"              # "system", "light", or "dark"
play_sounds = true                 # Play sound effects on capture/recording events
start_at_login = false             # Automatically launch Snapzy at macOS startup
export_location = "~/Pictures"     # Target folder for saving local captures (supports ~ expansions)

[updates]
check_automatically = true         # Automatically check for updates using Sparkle
download_automatically = false     # Download updates in the background without prompting

[diagnostics]
enabled = true                     # Enable local diagnostic logging for problem reporting
retention_days = 7                 # Number of days to retain logs (1 to 30)

[capture]
hide_desktop_icons = false         # Temporarily hide desktop icons during capture
hide_desktop_widgets = false       # Temporarily hide desktop widgets during capture

[capture.naming]
screenshot_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}" # Filename format
recording_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}"  # Filename format

[capture.screenshot]
format = "png"                     # "png", "jpeg", or "webp"
include_snapzy = false             # Include Snapzy's own UI overlay windows in screenshots
show_cursor = false                # Include the macOS mouse pointer in screenshots

[capture.scrolling]
show_hints = true                  # Show interactive guides during scrolling capture workflows

[capture.ocr]
success_notification = false       # Send a system notification when OCR finishes successfully

[capture.object_cutout]
auto_crop = true                   # Automatically crop cutout image bounds to the subject size

[capture.after.screenshot]
save = true                        # Save screenshots to local export location
quick_access = true                # Show Quick Access overlay after capture
copy_file = true                   # Copy generated file data to system clipboard
open_annotate = false              # Open image in Annotate editor automatically
upload_to_cloud = false            # Instantly upload captured image to configured cloud bucket

[capture.after.recording]
save = true                        # Save recordings to local export location
quick_access = true                # Show Quick Access overlay after recording
copy_file = true                   # Copy video file to system clipboard
open_annotate = false              # Open video in Video Editor automatically
upload_to_cloud = false            # Instantly upload video to configured cloud bucket

[recording]
format = "mov"                     # Video container format: "mov" or "mp4"
quality = "high"                   # Quality preset: "high", "medium", or "low"
fps = 30                           # Video frames-per-second target (1 to 120)
output_mode = "video"              # Export target: "video" (MP4/MOV) or "gif" (animated GIF)
capture_system_audio = true        # Record system output audio (requires virtual audio loopback)
capture_microphone = false         # Record microphone input audio
microphone_device_id = ""          # CoreAudio device UID string for microphone capture
remember_last_area = true          # Remember last selected region coordinates for subsequent captures
include_snapzy = false             # Include Snapzy overlays/toolbars in final recording outputs
show_cursor = true                 # Include macOS cursor in video stream
highlight_clicks = false           # Draw overlay highlight rings around clicks
show_keystrokes = false            # Display on-screen keystroke overlays during recording

[recording.mouse_highlight]
size = 50                          # Cursor highlight circle diameter in pixels (20 to 120)
animation_duration = 0.7           # Click animation ripple duration in seconds (0.1 to 3.0)
color = "#FF000080"                # Highlight circle color hex format (#RRGGBB or #RRGGBBAA)
opacity = 0.5                      # Alpha opacity for mouse overlay (0.0 to 1.0)
ripple_count = 3                   # Number of ripples per click animation (1 to 6)

[recording.keystrokes]
font_size = 18.0                   # Size of display font in points (10.0 to 48.0)
position = "bottomCenter"          # Overlay location: "topLeft", "topRight", "bottomLeft", "bottomRight", "bottomCenter", etc.
display_duration = 2.0             # Keystroke display duration in seconds (0.3 to 10.0)

[recording.annotation_shortcuts]
modifier = "shift"                 # Hold modifier key for annotation toolbar: "shift", "option", "command", "control"
hold_duration = 1.0                # Press-and-hold activation time in seconds (0.1 to 5.0)

[quick_access]
enabled = true                     # Enable Quick Access thumbnail overlay after capture
position = "bottomRight"           # Anchor corner: "topLeft", "topRight", "bottomLeft", "bottomRight"
auto_dismiss = true                # Automatically fade out panel after delay
auto_dismiss_delay = 10.0          # Delay duration in seconds before panel dismisses (3.0 to 30.0)
pause_countdown_on_hover = true    # Suspend auto-dismiss countdown timer when mouse hovers over panel
overlay_scale = 1.0                # Size scaling factor for the preview thumbnail (0.75 to 1.5)
drag_drop = true                   # Enable drag-and-drop actions for preview file paths
actions_order = ["copy", "annotate", "save", "cloud", "delete"] # Custom action button arrangement
enabled_actions = ["copy", "annotate", "save", "cloud", "delete"] # List of active buttons

[quick_access.slots]
center_top = "copy"                # Quick Access Action mapping for Slot
center_bottom = "annotate"         # Quick Access Action mapping for Slot
top_trailing = "save"              # Quick Access Action mapping for Slot
top_leading = "cloud"              # Quick Access Action mapping for Slot
bottom_leading = "delete"          # Quick Access Action mapping for Slot
bottom_trailing = ""               # Empty means unassigned slot

[history]
enabled = true                     # Enable local capture history logging
retention_days = 30                # Days to keep history records before purge (0 for infinite)
max_count = 500                    # Maximum allowed historical logs (0 to 1000)
background_style = "hud"           # Theme background: "hud" (transparent glass) or "solid"
open_on_launch = false             # Open history browser automatically when starting Snapzy

[history.floating]
enabled = true                     # Show floating history HUD bar on screen
position = "topCenter"             # Floating bar alignment: "topCenter", "bottomCenter", "center"
default_filter = "all"             # Initial filter: "all", "screenshot", "recording", "ocr", "cutout"
max_displayed_items = 10           # Max entries inside the HUD view (3 to 20)
scale = 1.0                        # Layout scale scaling modifier (0.8 to 1.2)
auto_clear_days = 0                # Clean up history entries older than X days (0 to 365)

[cloud]
provider = "aws_s3"                # Storage provider target: "aws_s3" or "cloudflare_r2"
bucket = "my-snapzy-bucket"        # AWS S3 / Cloudflare R2 bucket name
region = "us-east-1"               # Bucket region identifier (required for S3)
endpoint = ""                      # Custom endpoint URL string (required for Cloudflare R2)
custom_domain = ""                 # Base domain for clean public shareable links
expire_time = "7d"                 # Pre-signed links / lifecycle expire duration: "1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"
uploads_window_position = "center" # Upload panel layout target: "top", "center", "bottom"

[annotate]
clipboard_image_open_behavior = "ask" # Open clipboard behavior: "ask", "loadAutomatically", "doNothing"
close_after_drag = true            # Dismiss annotate window automatically after dragging image out
bring_forward_after_drag = false   # Bring target application to front after drag operations finish
quick_properties_sync = true       # Synchronize property values (color, stroke) instantly between tool options

[shortcuts]
enabled = true                     # Global hotkey listener toggle (must be true to register hotkeys)

[shortcuts.global.fullscreen]
enabled = true
key = "3"
modifiers = ["command", "shift"]

[shortcuts.global.area]
enabled = true
key = "4"
modifiers = ["command", "shift"]

[shortcuts.global.areaAnnotate]
enabled = true
key = "7"
modifiers = ["command", "shift"]

[shortcuts.global.scrollingCapture]
enabled = true
key = "6"
modifiers = ["command", "shift"]

[shortcuts.global.recording]
enabled = true
key = "5"
modifiers = ["command", "shift"]

[shortcuts.global.annotate]
enabled = true
key = "A"
modifiers = ["command", "shift"]

[shortcuts.global.videoEditor]
enabled = true
key = "E"
modifiers = ["command", "shift"]

[shortcuts.global.cloudUploads]
enabled = true
key = "L"
modifiers = ["command", "shift"]

[shortcuts.global.shortcutList]
enabled = true
key = "K"
modifiers = ["command", "shift"]

[shortcuts.global.ocr]
enabled = true
key = "2"
modifiers = ["command", "shift"]

[shortcuts.global.objectCutout]
enabled = true
key = "1"
modifiers = ["command", "shift"]

[shortcuts.global.history]
enabled = true
key = "H"
modifiers = ["command", "shift"]

[shortcuts.overlay.area_application_capture]
enabled = true
key = "SPACE"                      # Target specific hotkeys during selection overlay
modifiers = []

[shortcuts.overlay.recording_application_capture]
enabled = true
key = "SPACE"
modifiers = []

[shortcuts.annotate_tools]
disabled = []
# Map keys directly to annotation tool triggers: "1" to "8" (e.g. pen, rectangle, text)
"1" = "pen"
"2" = "arrow"
"3" = "rect"
"4" = "oval"
"5" = "text"
"6" = "blur"

[shortcuts.annotate_actions.copyAndClose]
enabled = true
key = "C"
modifiers = ["command"]

[shortcuts.annotate_actions.toggleSidebar]
enabled = true
key = "B"
modifiers = ["command"]

[shortcuts.annotate_actions.togglePin]
enabled = true
key = "P"
modifiers = ["command"]

[shortcuts.annotate_actions.cloudUpload]
enabled = true
key = "U"
modifiers = ["command"]

Configuration Properties Reference

General Section (`[general]`)

Property	Type	Default Value	Valid Options / Range	Description
`language`	String	`"system"`	`"system"`, `"en"`, `"vi"`, `"ja"`, `"ko"`, `"ru"`, `"zh"`, `"zh-tw"`	Language configuration for Snapzy UI.
`appearance`	String	`"system"`	`"system"`, `"light"`, `"dark"`	UI appearance theme mode.
`play_sounds`	Boolean	`true`	`true`, `false`	Enable/disable sound effects upon captures.
`start_at_login`	Boolean	`false`	`true`, `false`	Start application automatically on user login.
`export_location`	String	`"~/Pictures"`	Valid directory path	Local destination path for outputs.

Updates & Diagnostics

Property	Type	Default Value	Valid Options / Range	Description
`updates.check_automatically`	Boolean	`true`	`true`, `false`	Automatically poll Sparkle app cast for updates.
`updates.download_automatically`	Boolean	`false`	`true`, `false`	Auto-download new releases silently.
`diagnostics.enabled`	Boolean	`true`	`true`, `false`	Write runtime telemetry diagnostic logs to disk.
`diagnostics.retention_days`	Integer	`7`	`1` to `30`	Number of days to persist log files before purging.

Screenshot & Naming (`[capture]`)

Property	Type	Default Value	Valid Options / Range	Description
`hide_desktop_icons`	Boolean	`false`	`true`, `false`	Temporarily toggle desktop files visibility.
`hide_desktop_widgets`	Boolean	`false`	`true`, `false`	Temporarily hide widgets during capture.
`naming.screenshot_template`	String	`"Snapzy_{year}...`	Template format	File name layout patterns for screenshots.
`naming.recording_template`	String	`"Snapzy_{year}...`	Template format	File name layout patterns for video files.
`screenshot.format`	String	`"png"`	`"png"`, `"jpeg"`, `"webp"`	Target format for screen screenshots.
`screenshot.include_snapzy`	Boolean	`false`	`true`, `false`	Capture Snapzy's utility window panels.
`screenshot.show_cursor`	Boolean	`false`	`true`, `false`	Capture mouse cursor pointer arrow.
`scrolling.show_hints`	Boolean	`true`	`true`, `false`	Show visual hints during scrolling captures.
`ocr.success_notification`	Boolean	`false`	`true`, `false`	Send notifications on successful text extraction.
`object_cutout.auto_crop`	Boolean	`true`	`true`, `false`	Trim whitespace borders around object cutout boundaries.

After Capture Events

Property	Type	Default Value	Valid Options / Range	Description
`capture.after.screenshot.save`	Boolean	`true`	`true`, `false`	Write screenshot files automatically to export folder.
`capture.after.screenshot.quick_access`	Boolean	`true`	`true`, `false`	Spawn Quick Access float panel thumbnail.
`capture.after.screenshot.copy_file`	Boolean	`true`	`true`, `false`	Copy saved file directory path to clipboard.
`capture.after.screenshot.open_annotate`	Boolean	`false`	`true`, `false`	Launch screenshot directly in the Annotate editor.
`capture.after.screenshot.upload_to_cloud`	Boolean	`false`	`true`, `false`	Instantly trigger upload to cloud storage.
`capture.after.recording.save`	Boolean	`true`	`true`, `false`	Save recording files to local destination directory.
`capture.after.recording.quick_access`	Boolean	`true`	`true`, `false`	Spawn Quick Access float panel thumbnail.
`capture.after.recording.copy_file`	Boolean	`true`	`true`, `false`	Copy generated video location path to clipboard.
`capture.after.recording.open_annotate`	Boolean	`false`	`true`, `false`	Launch video directly in the Video Editor.
`capture.after.recording.upload_to_cloud`	Boolean	`false`	`true`, `false`	Automatically initiate background cloud uploads.

Screen Recording (`[recording]`)

Property	Type	Default Value	Valid Options / Range	Description
`format`	String	`"mov"`	`"mov"`, `"mp4"`	Video container format wrapper.
`quality`	String	`"high"`	`"high"`, `"medium"`, `"low"`	Target compression level.
`fps`	Integer	`30`	`1` to `120`	Captured frame rate density.
`output_mode`	String	`"video"`	`"video"`, `"gif"`	Export format.
`capture_system_audio`	Boolean	`true`	`true`, `false`	Capture computer sound outputs.
`capture_microphone`	Boolean	`false`	`true`, `false`	Capture voice microphone inputs.
`microphone_device_id`	String	`""`	Valid Audio Device ID	Specific hardware input selector.
`remember_last_area`	Boolean	`true`	`true`, `false`	Cache area capture coordinates context.
`show_cursor`	Boolean	`true`	`true`, `false`	Capture system mouse pointer path.
`highlight_clicks`	Boolean	`false`	`true`, `false`	Enable mouse highlight animation overlays.
`show_keystrokes`	Boolean	`false`	`true`, `false`	Draw pressed shortcuts overlay on stream.
`mouse_highlight.size`	Double	`50.0`	`20.0` to `120.0`	Outer diameter of mouse click circles.
`mouse_highlight.color`	String	`"#FF000080"`	HEX code (`#RRGGBBAA`)	Mouse click visual indicator stroke color.
`mouse_highlight.opacity`	Double	`0.5`	`0.0` to `1.0`	Hover highlight alpha transparency.
`mouse_highlight.ripple_count`	Integer	`3`	`1` to `6`	Ripple animations loop limit.
`keystrokes.font_size`	Double	`18.0`	`10.0` to `48.0`	Keystroke font text size in points.
`keystrokes.position`	String	`"bottomCenter"`	Screen corner enum	Position layout for keystrokes text HUD.
`keystrokes.display_duration`	Double	`2.0`	`0.3` to `10.0`	Keystroke panel persist timer on screen.
`annotation_shortcuts.modifier`	String	`"shift"`	Modifier key enum	Key to activate recording annotation toolbar.
`annotation_shortcuts.hold_duration`	Double	`1.0`	`0.1` to `5.0`	Activation hold threshold timer in seconds.

Quick Access Panel (`[quick_access]`)

Property	Type	Default Value	Valid Options / Range	Description
`enabled`	Boolean	`true`	`true`, `false`	Toggle post-capture overlay thumbnail.
`position`	String	`"bottomRight"`	Screen corner enum	Position anchor on target displays.
`auto_dismiss`	Boolean	`true`	`true`, `false`	Enable automatic hide countdown timer.
`auto_dismiss_delay`	Double	`10.0`	`3.0` to `30.0`	Dismiss countdown timer duration.
`pause_countdown_on_hover`	Boolean	`true`	`true`, `false`	Suspend dismiss timer on cursor hover.
`overlay_scale`	Double	`1.0`	`0.75` to `1.5`	Preview panel scale layout modifier.
`drag_drop`	Boolean	`true`	`true`, `false`	Allow direct dragging files from overlay.
`actions_order`	String Array	Defaults	Array of action UIDs	Button arrangement ordering.
`enabled_actions`	String Array	Defaults	Array of action UIDs	Active actions inside Quick Access grid.

History Browser (`[history]`)

Property	Type	Default Value	Valid Options / Range	Description
`enabled`	Boolean	`true`	`true`, `false`	Log capture events metadata.
`retention_days`	Integer	`30`	`0` to `90`	Automatic record removal limits (0 = infinite).
`max_count`	Integer	`500`	`0` to `1000`	Log density storage quota threshold.
`background_style`	String	`"hud"`	`"hud"`, `"solid"`	Panel styling visual presentation.
`open_on_launch`	Boolean	`false`	`true`, `false`	Spawn browser window on startup.
`floating.enabled`	Boolean	`true`	`true`, `false`	Show floating history HUD overlay.
`floating.position`	String	`"topCenter"`	Position HUD enum	Position alignment of floating browser panel.
`floating.max_displayed_items`	Integer	`10`	`3` to `20`	Max visible item cards inside float panel.
`floating.scale`	Double	`1.0`	`0.8` to `1.2`	Layout scale scaling modifier.

Cloud Storage Settings (`[cloud]`)

Property	Type	Default Value	Valid Options / Range	Description
`provider`	String	`"aws_s3"`	`"aws_s3"`, `"cloudflare_r2"`	Target cloud backend provider target.
`bucket`	String	`""`	Bucket name string	Remote storage folder identification bucket.
`region`	String	`"us-east-1"`	AWS S3 regions	Geographical location region code for AWS S3.
`endpoint`	String	`""`	Target HTTP API endpoint	Dedicated target URL endpoint (R2 specific).
`custom_domain`	String	`""`	Domain URL	Custom hostname mapping for public sharing URLs.
`expire_time`	String	`"7d"`	`"1d"`, `"3d"`, `"7d"`, `"14d"`, `"30d"`, `"60d"`, `"90d"`, `"permanent"`	Pre-signed upload download expire timer.
`uploads_window_position`	String	`"center"`	`"top"`, `"center"`, `"bottom"`	Align location of floating cloud upload HUD.

Annotate Editor Settings (`[annotate]`)

Property	Type	Default Value	Valid Options / Range	Description
`clipboard_image_open_behavior`	String	`"ask"`	`"ask"`, `"loadAutomatically"`, `"doNothing"`	Import clipboard images behavior when launching empty editor.
`close_after_drag`	Boolean	`true`	`true`, `false`	Close editor after dragging output image out.
`bring_forward_after_drag`	Boolean	`false`	`true`, `false`	Focus destination app layout after drag-and-drop.
`quick_properties_sync`	Boolean	`true`	`true`, `false`	Sync tools stroke size and colors instantly.

Validation & Issues

Snapzy strictly validates config.toml attributes when parsing:

Value Constraints: If an attribute exceeds valid ranges (e.g. fps = 150 or overlay_scale = 3.0), Snapzy will report an warning, ignore the invalid property, and use the default values instead.
Malformed Types: Specifying values of incorrect types (e.g. putting a string for a boolean property) results in an error. The app will ignore the parsing segment and retain previously loaded config attributes.
Issue Warnings: You can review TOML configuration validation warnings and errors directly inside the Advanced Preferences tab under the config sync status view.