Switched from PyYAML to ruamel.yaml for comment-preserving config and improved example config layout.

config.example.yaml

@@ -1,100 +1,88 @@
+owncast:
+  # REQUIRED: URL where viewers access your stream.
+  # Example: "https://stream.logal.dev"
+  url: ""
+
+  # REQUIRED: API access token for the Owncast integrations API.
+  # Generate one in Owncast under Admin -> Integrations -> Access Tokens.
+  access_token: ""
+
+  # OPTIONAL: admin API access for privileged operations like user
+  # management, server configuration, and moderation.
+  admin:
+    enabled: false
+    username: "admin"
+    password: "abc123"
+
 owlbot:
   # Address and port to bind the web server.
-  # Default: 127.0.0.1:8081
   host: "127.0.0.1"
   port: 8081
 
   # Secret token for the webhook URL path (/webhook/<secret>).
-  # A cryptographically secure secret is generated on first run and saved
-  # back to this file automatically. Leave this empty unless you have a
-  # specific reason to set it manually.
+  # Auto-generated on first run. Leave empty unless you have a specific
+  # reason to set it manually.
   webhook_secret: ""
 
-  # Public base URL for Owlbot's web server. Used to construct URLs
-  # generated by modules (e.g. via ctx.routes.url_for()).
-  #
-  # Set this if Owlbot is hosted on a different domain than your Owncast
-  # instance. If not set, falls back to owncast.url.
+  # Public base URL for Owlbot's web server. Set this if Owlbot is
+  # hosted on a different domain than your Owncast instance.
   #public_base_url: "https://owlbot.example.com"
 
   # Prefix character for chat commands.
-  # Default: "!"
-  #command_prefix: "!"
+  command_prefix: "!"
 
   # Maximum seconds to wait for an event or command handler to complete.
   # If a handler exceeds this, it is cancelled.
-  # Default: 30.0
-  #handler_timeout: 30.0
+  handler_timeout: 30.0
 
   # Directory for per-module SQLite databases. Each module gets its own
   # <module_name>.db file in this directory. Relative paths are resolved
   # from the working directory.
-  # Default: "data"
-  #storage_dir: "data"
+  storage_dir: "data"
 
-  # Maximum number of SQLite connections per module in the connection pool.
-  # Connections are created lazily as needed, up to this limit.
-  # Default: 4
-  #pool_size: 4
-
-  # Directory containing user modules. Built-in modules are loaded from the
-  # package regardless of this setting.
-  # Default: "modules" (relative to the working directory)
-  #modules_dir: "modules"
+  # Directory containing user modules. Built-in modules are loaded from
+  # the package regardless of this setting.
+  modules_dir: "modules"
 
   # Directory for the owlbot.log file. When set, logs are written to
   # owlbot.log in this directory in addition to stdout. When unset,
   # logs go to stdout only.
   #log_dir: "logs"
 
-owncast:
-  # URL where viewers access your stream (e.g. "https://stream.logal.dev").
-  # Required.
-  url: ""
-
-  # API access token for the Owncast integrations API. Required for
-  # sending messages, hiding messages, listing connected clients, etc.
-  # Generate one in Owncast under Admin -> Integrations -> Access Tokens.
-  access_token: ""
-
-  # Optional admin API access for privileged operations like user
-  # management, server configuration, and moderation. If not enabled,
-  # ctx.admin_client will be None in handlers.
-  admin:
-    enabled: false
-    username: "admin"
-    password: "abc123"
+  # Maximum number of SQLite connections per module in the connection pool.
+  # Connections are created lazily as needed, up to this limit.
+  pool_size: 4
 
 # Per-module configuration. Each key is a module name (the filename without
 # .py for single-file modules, or the directory name for package modules).
 # Modules are enabled by default; set enabled: false to disable.
-# Modules can define their own config keys via ctx.config.register_defaults()
-# in their setup() function.
 modules:
-  # clips:
-  #   # Seconds of recent stream footage to keep available for clipping.
-  #   # Default: 300
-  #   cache_duration: 300
-  #   # Minimum clip length in seconds.
-  #   # Default: 5
-  #   min_clip_length: 5
-  #   # Maximum clip length in seconds.
-  #   # Default: 120
-  #   max_clip_length: 120
-  #   # Directory where saved clip files are stored.
-  #   # Default: "data/clips"
-  #   clips_dir: "data/clips"
-  #   # Seconds before an unused clip editor session expires.
-  #   # Default: 900
-  #   session_expiry: 900
-  #   # Seconds to keep stream footage available after the stream stops.
-  #   # Default: 120
-  #   grace_period: 120
+  clips:
+    enabled: true
 
-  # custom_commands:
-  #   # Default cooldown in seconds for newly created custom commands.
-  #   # Default: 5
-  #   default_cooldown: 5
-  #   # Maximum placeholder nesting depth in custom command responses.
-  #   # Default: 4
-  #   max_nesting_depth: 4
+    # How far back (in seconds) viewers can clip from the live stream.
+    #cache_duration: 300
+    # Minimum clip length in seconds.
+    #min_clip_length: 5
+    # Maximum clip length in seconds.
+    #max_clip_length: 120
+    # Directory where saved clip files are stored.
+    #clips_dir: "data/clips"
+    # Seconds before a clip editing session expires if unused.
+    #session_expiry: 900
+    # Seconds to keep footage available after stream stops.
+    #grace_period: 120
+
+  custom_commands:
+    enabled: true
+
+    # Default cooldown in seconds for new custom commands.
+    #default_cooldown: 5
+    # Maximum nesting depth for placeholders in command responses.
+    #max_nesting_depth: 4
+
+  quotes:
+    enabled: true
+
+  timers:
+    enabled: true