clippy.yaml.example

# Clippy configuration (YAML)
#
# Precedence at runtime:
#   CLI flags > Environment (.env) > clippy.yaml > built-in defaults
#
# Tip: keep secrets (client IDs, tokens) in .env or environment variables.
# This file is for non-secret settings and preferences.

identity:
  # Default Twitch broadcaster login, used when --broadcaster is omitted
  broadcaster: ""
  # Default ingestion source when --discord/--no-discord is omitted: "" (Helix)
  # or "discord". --discord/--no-discord on the CLI always overrides this.
  source: ""

selection:
  # Minimum views to include a clip
  min_views: 1
  # Number of clips included in each compilation
  clips_per_compilation: 12
  # How many compilations to produce per run
  compilations: 2

sequencing:
  # Probability (0.0 - 1.0) of inserting a random transition between clips
  transition_probability: 0.35
  # Disable random transitions entirely (static.mp4 is still used between clips)
  no_random_transitions: false
  # How to build the eligible transition pool:
  #   explicit = only use assets.transitions
  #   discover = scan the transitions dir for transition_*.mp4
  #   hybrid   = combine both
  transition_mode: explicit
  # Optional denylist applied after selection/discovery
  transition_exclude: []
  # Optional weights for specific transitions (higher = more likely)
  transitions_weights: { }
  # Avoid repeat transitions within the last N picks (0 disables)
  transition_cooldown: 1

audio:
  # If true, silence static.mp4 even when the global flag is false
  silence_static: false
  # Apply EBU R128 loudness normalization to every Twitch clip (prevents jarring volume jumps)
  audio_normalize_clips: true
  # Normalize loudness for transition/intro/outro assets (EBU R128)
  audio_normalize_transitions: true

encoding:
  # Video bitrate target (used as NVENC maxrate; VBR with CQ)
  bitrate: 12M
  # Audio bitrate
  audio_bitrate: 192k
  # Framerate and resolution for outputs
  fps: '60'
  resolution: 1920x1080
  # yt-dlp format selection (Twitch clips)
  yt_format: "bestvideo[ext=mp4][height<=1080]+bestaudio[ext=m4a]/best[ext=mp4][height<=1080]"
  # Container options
  container_ext: mp4
  container_flags: "-movflags +faststart"
  # NVENC tuning
  nvenc:
    preset: slow
    cq: '19'
    gop: '120'
    rc_lookahead: '20'
    aq_strength: '8'
    spatial_aq: '1'
    temporal_aq: '1'

paths:
  # Working directory for intermediates
  cache: ./cache
  # Final outputs directory
  output: ./output

behavior:
  # Max concurrent workers for download/normalize stage
  max_concurrency: 4
  # Skip a clip if it fails after retries (true) or abort run (false)
  skip_bad_clip: true
  # Force rebuild even if intermediate files exist (same as --rebuild)
  rebuild: false
  # Force rebuild of normalized non-clip assets (cache/_trans)
  transitions_rebuild: false
  # Enable overlay (avatar + text) on clips
  enable_overlay: true
  # --- Cache retention policy ---
  # Keep per-clip processed files between runs (reuse on --rebuild).
  # When false (default), per-clip dirs are deleted at end of each run.
  keep_clips: false
  # Delete cached clip dirs older than N days. 0 = keep forever (requires keep_clips: true).
  cache_ttl_days: 0
  # Cap total cached clip size in MB; evicts oldest first. 0 = unlimited (requires keep_clips: true).
  cache_max_size_mb: 0

assets:
  # Required: static mp4 file name in your transitions directory
  static: static.mp4
  # Optionally list custom names for intros and outros
  # intro: [intro.mp4, intro_2.mp4]
  # outro: [outro.mp4, outro_2.mp4]
  # Explicit allowlist for random transitions.
  # Only files listed here are eligible for random insertion.
  # transitions: [transition_01.mp4, transition_02.mp4, transition_03.mp4]

  # Optional logo watermark, independent of the creator-credit overlay above
  # (behavior.enable_overlay) — works with or without it. Same convention as
  # intro/outro: empty means off.
  # watermark: logo.png
  # x/y are raw ffmpeg overlay expressions, not parsed — any expression the
  # overlay filter accepts works. A few common ones:
  #   top-left, 10px margin:      watermark_x: "10"              watermark_y: "10"
  #   bottom-right, 20px margin:  watermark_x: "main_w-overlay_w-20"
  #                               watermark_y: "main_h-overlay_h-20"
  # watermark_x: "10"
  # watermark_y: "10"
  # watermark_alpha: 1.0   # 0.0 (invisible) - 1.0 (opaque)

discord:
  # Optional: used when running with --discord
  # Discord channel ID to read clip links from
  channel_id: 000000000000000000
  # How many recent messages to scan for clip links
  message_limit: 200
  # Notes:
  # - Save your bot token in .env as DISCORD_TOKEN (do not put secrets in YAML)
  # - Enable "Message Content Intent" in the Discord Developer Portal

# Notes:
# - Use TRANSITIONS_DIR env var to point to a custom transitions folder.
# - Set TRANSITIONS_DIR to a custom directory if your transitions are not under ./transitions.

# ---------------------------------------------------------------------------
# Profiles (optional) — per-streamer defaults and branding
# ---------------------------------------------------------------------------
# A profile is a partial copy of this file that is merged over the top level,
# so it can override anything above: the channel, intro/outro clips, clip
# counts, encoding. Anything a profile does not mention keeps the value above.
#
# There is always a built-in "default" profile meaning "no overrides": the
# values in this file and the transitions root. `clippy profile use default`
# drops active_profile again.
#
#   clippy profile            create or edit one (short, no credentials)
#   clippy profile use NAME   make NAME the default
#   clippy --list-profiles    show what is defined
#   clippy --profile NAME     use NAME for a single run
#
# Precedence: this file  ->  profile  ->  CLI flags.
#
# active_profile: theflood
#
# profiles:
#   theflood:
#     identity:
#       broadcaster: theflood
#       source: discord   # this streamer's clips always come from a Discord channel
#     assets:
#       intro: [intro.mp4]
#       outro: [outro.mp4]
#     selection:
#       clips_per_compilation: 20
#   someoneelse:
#     identity:
#       broadcaster: someoneelse
#     assets:
#       intro: [other_intro.mp4]
#
# Per-profile artwork: put a profile's own clips in transitions/<profile>/.
# Assets resolve from there first and fall back to transitions/, so shared
# files like static.mp4 stay in the root and need no duplication.
#
#   transitions/
#     static.mp4            <- shared
#     theflood/
#       intro.mp4           <- only when the theflood profile is active
#       outro.mp4