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

1. Open Snapzy Preferences (Cmd + ,) and navigate to the Advanced tab.
2. Click Set Up config.toml.
3. 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.