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` · `browser` · `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.