The Rules system is the heart of automation in Callers Caddy.
You define, When something is supposed to happen (trigger), whether a condition must be met – and What Then (action) happens.
All without scripting, all with a click.
And so that you know exactly what's currently available, here is the complete list of triggers, conditions, actions, and parameters.
Trigger
A trigger is the starting signal for a rule. I currently have 23 triggers implemented – from song events and app launches to keyboard shortcuts.
song_started
Triggered as soon as a song starts playing. Ideal for automatically loading a layout or displaying lyrics, for example.
song_stopped
It fires when a song has been completely stopped – not during pause. Useful for tidying up after a track or skipping ahead.
song_paused
It reacts to the moment you press the pause button. For example, you can use it to clear the fullscreen lyrics window.
song_resumed
Activates when a paused song resumes playing. This allows you to, for example, bring the lyrics back to the foreground.
song_changed
It fires as soon as another song is loaded – whether from the playlist or by clicking.
app_started
This is triggered exactly once: when the application starts. This loads your favorite layout or sets default values.
manager_closed
This reacts when you close the playlist manager. The default system rule then automatically focuses on the song list.
play_timer
It fires every 10 seconds during playback. This allows you to implement time-based warnings – for example, if a pattern runs for too long.
key_f1 to key_f12
Each F-key is its own trigger. You can freely assign them any actions you like – play, stop, change layout, whatever you need.
key_space
The spacebar as a trigger. Standard system rule: Play/Pause toggle – just like you know it from a media player.
key_l
The letter L acts as a trigger. By default, it opens the location dialog so you can quickly select your event.
key_p
The letter P acts as a trigger. By default, it toggles the playlist manager.
Conditions
A condition is optional – it restricts whether the rule is actually executed. If no condition is set, the action always runs. All conditions except one are parameterless.
song_type_is_singing
True, if the current song is marked as a "Singing Call". This allows you to control rules that only apply to singing calls.
song_type_is_pattern
True, if the song is entered as a "Patter". This allows you, for example, to initiate a different sequence at the Patter Stop than at the Singing.
lyrics_available
True, if a lyrics file is embedded for the current song. This prevents you from opening an empty lyrics window.
lyrics not available
The opposite is true if no lyrics file is present. Use this to perform an alternative action in that case.
loop_set
True if a loop is configured – more precisely: loop_in > 0.1 s or loop_out deviates from the song duration by more than 0.5 s. This means you can only activate the loop toggle if a loop is actually useful.
loop_not_set
The opposite of `loop_set`. Useful if you want to automatically set a best loop when the song starts, but only if one hasn't been set yet.
location_selected
True, if you have selected an event in the location dialog. This locks certain actions until the location is set.
location_not_selected
True if no location is active. This allows you, for example, to automatically open the location dialog when the app starts.
play_duration_above
Parameter: minutes (float, 0.5-60, default: 5) True if the song has been playing for more than X minutes. This allows you to implement time warnings – e.g., a red warning signal after 7 minutes of pattern.
Actions
Actions are what the rule actually does. I've implemented 30 actions, divided into areas like widget control, transport, loop, lyrics, and more.
dock_open
Parameter: dock_name Makes a widget visible and brings it to the foreground. You can use this to, for example, automatically display the lyrics when a song starts.
dock_close
Parameter: dock_name It hides a widget. Ideal for clearing away the lyrics or tidying up the layout when stopping.
dock_fullsize
Parameter: dock_name Displays a widget as a floating window at approximately 90x screen size. The previous state is saved so you can revert to it later.
dock_focus
Parameter: dock_name Makes a widget visible, brings it to the forefront. and gives him keyboard focus. That's the difference to dock_open.
auto_scroll_start
Starts auto-scrolling in the lyrics widget. You typically use this when starting a singing call.
auto_scroll_stop
Stops auto-scrolling. Useful when pausing or stopping, so the scrolling text doesn't continue.
layout_load
Parameter: layout_name Loads a saved layout by name. The special case ""default"" restores the state in front of a full-size window.
log_message
Parameter: message (Text) Writes a message to the rules log. Useful for debugging rule chains or logging events.
statusbar_message
Parameter: message (Text), duration_ms (int, Standard: 3000) Displays a temporary message in the status bar. This allows you to give yourself brief reminders during operation.
play
Starts playback (deferred via timer to prevent re-entry). Also works if a song is already loaded but stopped.
pause
Pauses the current song. Only executed when the pause button is active.
Stop
Stops playback completely. Only executed when the stop button is active.
fade_out
It introduces a 5-second fade-out. The song fades out gently – ideal at the end of a square riff.
play_pause_toggle
Switches between play and pause. That's the default function of the spacebar.
auto_advance
Loads the next song from the playlist. This allows you to create an automated sequence without manual clicking.
open_location_dialog
Opens the location dialog. Useful as a startup rule if you always want to select your event first.
toggle_manager
Toggles the visibility of the playlist manager. Corresponds to the standard shortcut on P.
system_ping
Plays a warning tone: 880 Hz and 1100 Hz, each for 150 ms, or a system beep as a fallback. You use this to audibly alert yourself to a time elapse.
warn_background
Parameter: level (int, 1–2) Color the play timer label. Level 1 = Orange (#f59e0b), Level 2 = Red (#ef4444This way you can see at a glance that something needs attention.
warn_background_reset
Resets the background color of the play timer label to normal. Use this when stopping or changing songs.
tempo_change
Parameter: delta (int, −50…+50, default: +2) Changes the "Today's Pace" by the specified percentage. The change only applies to this session and is not saved in the database.
song_tempo_change
Parameter: delta (int, −50…+50, default: +2) How tempo_change, but persistent: the new value is stored directly in the database with the song.
pitch_change
Parameter: delta (float, −6.0…+6.0, step: 0.5) Shifts the pitch by the specified semitone. Useful for quickly going an octave lower or higher with the press of a key.
volume_change
Parameter: delta (float, −1.0…+1.0, step: 0.05) Changes the song's volume relative to the current value. The range is between 0.0 and 1.0.
auto_set_best_loop
Analyzes the current song and automatically sets the best 64-beat loop. An overlay appears during the analysis – the song must have BPM data.
toggle_loop_active
Toggles the Loop Active checkbox on or off. This allows you to activate or deactivate the set loop with a single button press.
goto_position
Parameter: position (choice: start / loop_in / loop_out / end, Standard: start) Jumps to the specified position in the song. If crossfade is enabled, the transition will be smooth.
lyrics_auto_width
Automatically adjusts the width of the lyrics panel to the content. Useful after a layout change when the width is no longer correct.
photo_capture
Activate the camera, wait 500 ms for startup, and then take a picture. You can use this to automatically take a group photo.
photo_show
The photo dock displays as a fullscreen window (approximately 90 %). This allows you to present the captured image large on the screen.
This list is already impressive, but it will likely grow even further. It all depends on the many ideas from Callers Caddy users.
Remember, you can Save your rules too and exchange with other callers.