bible-app/OSC_FEEDBACK_PATHS.md

OSC Feedback Paths Reference

This document lists all OSC feedback paths that the Bible App sends back to Companion (or other OSC clients) after processing commands.

Feedback Message Format

All feedback messages follow this format:

• Address: /bibleapp/feedback/<command>
• Arguments:
  1. Status (integer): 1 = success, 0 = failure
  2. Error Message (string, optional): Only present if status is 0 and an error occurred
  3. Original Command (string): The original OSC command address that triggered this feedback

Complete List of Feedback Paths

Command Feedback Paths

Feedback Path	Command	Description
/bibleapp/feedback/undo	/bibleapp/undo or /undo	Undo last action
/bibleapp/feedback/redo	/bibleapp/redo	Redo last undone action
/bibleapp/feedback/reset	/bibleapp/reset or /reset	Reset the entire app
/bibleapp/feedback/clear	/bibleapp/clear	Clear current tab
/bibleapp/feedback/clear_all	/bibleapp/clear_all	Clear all tabs
/bibleapp/feedback/close	/bibleapp/close or /bibleapp/close_active_tab	Close active tab
/bibleapp/feedback/tab_left	/bibleapp/tab/left or /bibleapp/prev_tab	Switch to previous tab
/bibleapp/feedback/tab_right	/bibleapp/tab/right or /bibleapp/next_tab	Switch to next tab
/bibleapp/feedback/new_bible_tab	/bibleapp/new or /bibleapp/new/tab	Create new Bible tab
/bibleapp/feedback/new_whiteboard_tab	/bibleapp/new/whiteboard	Create new whiteboard tab
/bibleapp/feedback/new_notes_tab	/bibleapp/new/notes	Create new notes tab
/bibleapp/feedback/splash_show	/bibleapp/splash/show or /splash/show	Show splash screen
/bibleapp/feedback/tool	/bibleapp/tool (invalid)	Generic tool command (when invalid)
/bibleapp/feedback/tool_pen	/bibleapp/tool with pen	Select pen tool
/bibleapp/feedback/tool_highlight	/bibleapp/tool with highlight	Select highlight tool
/bibleapp/feedback/tool_erase	/bibleapp/tool with erase	Select erase tool
/bibleapp/feedback/tool_select	/bibleapp/tool with select	Select select tool
/bibleapp/feedback/pen_color/<hex6>	/bibleapp/pen/color or /bibleapp/pen/color/<color>	Set pen color (color-specific feedback path)

The Information Line (recommended for the one button you actually watch)

/bibleapp/feedback/information is a single path carrying one short human-readable string. It is the button to put on Companion during a service: it answers the two things that cannot be seen from the booth — which tab he has moved to, and whether the splash is up over the top of it.

Feedback Path	Arguments	Sent when
/bibleapp/feedback/information	s: the status line	Whenever the line's content changes

It reads like this:

2/5 Bible | John 3 | LIVE
4/5 Sync | Romans 8 | SPLASH
1/3 Whiteboard | Pen | LIVE

Pick what goes in it under Settings › OSC › Information line. The pieces always appear in the order below, whatever order they are ticked in; anything the app has not reported yet is simply left out. Untick all of them to switch the line off.

Field	Looks like	Notes
tab	2/5 Bible	Position among the tabs actually on the row, then the kind. The ProPresenter Sync tab shows as Sync, never Bible.
passage	John 3	Scripture tabs only (Bible, Sync, Alpha)
translation	ESV
tool	Pen	Pen / Highlighter / Eraser / Select
color	#ffff00	Current pen colour
splash	LIVE or SPLASH	LIVE = the TV is showing the app. The safety net.
ppsync	PP LIVE, PP DOWN, PP OFF	Receiving slides / link down / not switched on

Default: tab, passage, splash.

Companion setup: one OSC listener on /bibleapp/feedback/information, with its first argument put on the button text. Nothing else is needed — every per-thing path below keeps working unchanged for the buttons that already use them.

Tab Button Colours (boolean, for Companion feedbacks)

The information line above is words — right for button text, useless for a colour. A Companion colour comes from a boolean feedback: 1 lights the button, 0 puts it out. So which tab is active also goes out as 1/0 per tab, in two flavours:

Feedback Path	Description
/bibleapp/feedback/state/tab_active/<n>	1 while the n-th tab on the row is the one showing (n = 1…16)
/bibleapp/feedback/state/tab_kind/<kind>	1 while a tab of that kind is showing

<kind> is one of: bible · sync · whiteboard · notes · media · alpha · announcements · graphics · maps · prayer · ask.

• Use tab_active for a row of buttons that mirrors the tab bar.
• Use tab_kind for a fixed button that asks "is he on the whiteboard?" — that one stays right however the tabs are reordered.
• The ProPresenter Sync tab lights tab_kind/sync, never tab_kind/bible, even though it is a Bible tab underneath.
• A tab_kind lights for any tab of that kind. With three Bible tabs open, tab_kind/bible is 1 on all three and tab_active/<n> says which one.

No button can be left stranded. Every slot and every kind is re-sent on each change — the active one as 1, all 25 others as 0 — so a button cannot stay lit for a tab he has already left. Slots past the end of the row are sent 0 and simply stay dark. That is ~27 tiny UDP packets per tab change.

Switch it off under Settings › OSC › Tab button colours (feedbackTabStates, default on).

Companion setup: add an OSC listener on the path you want (say /bibleapp/feedback/state/tab_kind/whiteboard), then a boolean feedback on = 1 that sets the button's background colour. Repeat per button. Pair it with the information line on one extra button if you also want the passage in text.

Live State Feedback Paths

These feedback paths are sent when the user changes state in the app UI (not only when OSC commands run), so Companion can keep buttons in sync with what is currently active.

Feedback Path	Trigger	Description
/bibleapp/feedback/state/tool_pen	Any tool change	1 when Pen is active, 0 otherwise
/bibleapp/feedback/state/tool_highlight	Any tool change	1 when Highlighter is active, 0 otherwise
/bibleapp/feedback/state/tool_erase	Any tool change	1 when Eraser is active, 0 otherwise
/bibleapp/feedback/state/tool_select	Any tool change	1 when Select is active, 0 otherwise
/bibleapp/feedback/state/pen_color/<hex6>	Pen color change	1 for selected color, 0 for previously active color
/bibleapp/feedback/state/splash_visible	Splash show/hide	1 while splash is visible, 0 when hidden
/bibleapp/feedback/state/ppsync_enabled	ProPresenter Sync switched on/off in Settings	1 while "Follow ProPresenter" is on, 0 otherwise
/bibleapp/feedback/state/ppsync_live	ProPresenter link goes live / drops	1 while slides are being received from ProPresenter, 0 otherwise (connecting, dropped, off)
/bibleapp/feedback/state/action_refresh	Reset/Refresh action	Pulses 1 then 0 for button flash/light behavior
/bibleapp/feedback/state/action_undo	Undo button/action	Pulses 1 then 0
/bibleapp/feedback/state/action_redo	Redo button/action	Pulses 1 then 0
/bibleapp/feedback/state/action_clear	Clear current tab action	Pulses 1 then 0
/bibleapp/feedback/state/action_clear_all	Clear all tabs action	Pulses 1 then 0
/bibleapp/feedback/state/action_splash_show	Splash show action	Pulses 1 then 0
/bibleapp/feedback/state/action_new_bible_tab	New Bible tab action	Pulses 1 then 0
/bibleapp/feedback/state/action_new_whiteboard_tab	New whiteboard tab action	Pulses 1 then 0
/bibleapp/feedback/state/action_new_notes_tab	New notes tab action	Pulses 1 then 0

Error Feedback Paths

Feedback Path	Description
/bibleapp/feedback/blocked	IP address was blocked (not in allowed list)
/bibleapp/feedback/unknown	No matching route found for the command

Example Feedback Messages

Success Example

Address: /bibleapp/feedback/undo
Arguments:
  - i: 1 (success)
  - s: "/bibleapp/undo" (original command)

Failure Example

Address: /bibleapp/feedback/undo
Arguments:
  - i: 0 (failure)
  - s: "Token validation failed" (error message)
  - s: "/bibleapp/undo" (original command)

Blocked IP Example

Address: /bibleapp/feedback/blocked
Arguments:
  - i: 0 (failure)
  - s: "IP 192.168.1.100 not in allowed list" (error message)
  - s: "/bibleapp/undo" (original command)

Companion Configuration

IMPORTANT: Companion feedback can be received on either its OSC listener or UDP listener, depending on your setup:

1. Enable a Feedback Listener:

   • OSC Listener port is commonly 12321
   • UDP Listener port is commonly 16759 (often used by "Listen for OSC messages" feedback)

2. Add OSC Listener Action: In your Companion button/action, add a listener that watches:

   • OSC Path: /bibleapp/feedback/undo (or the specific feedback path you want)
   • Listen Port: Should match the listener port you enabled in Companion (16759 or 12321)
   • Expected Arguments: Integer (1 = success, 0 = failure)

3. Feedback Port in Bible App: Set a fixed feedback port that matches your Companion module's feedback listener.

   • Recommended: use a dedicated port such as 18000.
   • If you leave it empty, Bible App auto-detects sender port and falls back to 16759.
   • Avoid using ports that are already in use (EADDRINUSE in Companion logs).

4. Button Feedback: Use the feedback paths to update button states:

   • Status 1 = Button pressed successfully (can use for button highlight/confirmation)
   • Status 0 = Command failed (can use for error indication)

5. Example Companion Actions:

   • Listen to /bibleapp/feedback/undo → Update button state when undo completes
   • Listen to /bibleapp/feedback/tool_pen → Highlight pen tool button when selected
   • Listen to /bibleapp/feedback/pen_color/ff3333 (or your exact hex color) → Highlight only that specific color button
   • Listen to /bibleapp/feedback/state/tool_pen → Keep Pen button active even for UI-only tool changes
   • Listen to /bibleapp/feedback/state/action_refresh → Flash a refresh/reset button on press
   • Listen to /bibleapp/feedback/state/action_undo, /action_redo, /action_clear, /action_clear_all → Flash those action buttons on app-side presses
   • Listen to /bibleapp/feedback/state/action_new_bible_tab, /action_new_whiteboard_tab, /action_new_notes_tab → Flash tab-creation buttons
   • Listen to /bibleapp/feedback/state/splash_visible → Keep splash button lit while splash is visible
   • Listen to /bibleapp/feedback/state/pen_color/<hex6> → Keep selected pen color button active

Troubleshooting: If feedback isn't working:

• Verify Companion listener is ON and the port matches Bible App feedback port (for example 18000)
• Check that you have an OSC Listener action configured to receive /bibleapp/feedback/* messages
• Verify firewall isn't blocking the configured UDP port
• Check the Bible App log viewer (File → Log Viewer) to see if packets are being sent

Configuration

Feedback can be configured in the OSC settings:

• Information line: which pieces go into /bibleapp/feedback/information (default: tab, passage, splash; none = line off)
• Tab button colours: per-tab 1/0 on state/tab_active/<n> and state/tab_kind/<kind> (default: on)
• Feedback Enabled: Enable/disable feedback (default: enabled)
• Feedback Address: Target address for feedback (default: sender's address)
• Feedback Port: Target port for feedback (recommended fixed port such as 18000; if empty, sender port then 16759)

Feedback is sent automatically after each OSC command is processed, unless disabled in settings.