bible-app/ACCORDANCE_OSC_SETUP.md

# Accordance OSC API Setup Guide

This guide will help you configure Accordance Bible Software to work with the Bible App's OSC integration.

## Important Note

**Accordance's OSC API may still be in development** based on the forum discussion you referenced. The current implementation is ready to receive Accordance data, but you may need to work with Accordance support or check their latest documentation for the exact OSC message format.

## Step 1: Update osc-config.json

First, update your `osc-config.json` file to include the Accordance port:

```json
{
  "address": "0.0.0.0",
  "port": 3333,
  "accordancePort": 3334,
  "allow": ["10.6.3.222"],
  "allowPrefixes": ["10."],
  "token": "?WaT3rs2016!"
}
```

**Note:** The `accordancePort` (3334) is a common default, but you may need to adjust this based on Accordance's actual OSC port.

## Step 2: Enable OSC in Accordance (If Available)

### Option A: Check Accordance Preferences

1. **Open Accordance Bible Software**
2. **Go to Preferences/Settings:**
   - Mac: `Accordance` → `Preferences` (or `Settings`)
   - Windows: `Edit` → `Preferences` (or `Tools` → `Options`)
3. **Look for OSC/API settings:**
   - Check for sections like:
     - "OSC" or "Open Sound Control"
     - "API" or "External Control"
     - "Network" or "Remote Control"
     - "Developer" or "Advanced"
4. **Enable OSC if found:**
   - Enable the OSC feature
   - Note the port number (default may be 3334 or 9000)
   - Update `accordancePort` in `osc-config.json` to match

### Option B: Check Accordance Documentation

1. **Visit Accordance Help:**
   - Press `F1` in Accordance or go to Help menu
   - Search for "OSC" or "API" or "Open Sound Control"
2. **Check Accordance Forums:**
   - Visit: https://forums.accordancebible.com/
   - Search for "OSC" or "API"
   - Check the forum post you referenced: https://forums.accordancebible.com/topic/37607-accordance-api-a-user-driven-vision-for-the-future/

### Option C: Contact Accordance Support

If OSC settings aren't visible in Preferences, the feature may:
- Be in beta/development
- Require a specific Accordance version
- Need to be enabled via command line or config file
- Not be available yet (based on the "user-driven vision" forum post)

**Contact Accordance Support:**
- Email: support@accordancebible.com
- Ask about: "OSC API for external applications" or "Open Sound Control integration"

## Step 3: Verify OSC Module Installation

Make sure the OSC module is installed in your Bible App:

```bash
cd bible-app
npm install osc
```

## Step 4: Test the Connection

### Test 1: Check Server Status

1. **Start your Bible App server**
2. **Open browser console** (F12)
3. **Run this command:**
   ```javascript
   fetch('/api/accordance/status').then(r => r.json()).then(console.log)
   ```

You should see:
```json
{
  "available": true,
  "configured": true,
  "oscModuleInstalled": true
}
```

### Test 2: Check Server Logs

When you start the server, look for:
```
[Accordance OSC] Listening on 127.0.0.1:3334
```

### Test 3: Test Word Query

1. **Click on a word** in the Bible App (with Select tool active)
2. **Check browser console** for Accordance API logs
3. **Check server console** for OSC message logs

## Step 5: Configure Accordance OSC Message Format

The current implementation sends OSC messages in this format:

```
Address: /accordance/word
Arguments: [word, reference]
```

**You may need to adjust this** based on Accordance's actual API. Common variations:

- `/accordance/lookup`
- `/accordance/instantDetails`
- `/accordance/wordInfo`
- `/accordance/query`

### How to Find the Correct Format

1. **Check Accordance OSC Documentation** (if available)
2. **Use OSC monitoring tools:**
   - Install an OSC monitor like `OSCulator` or `TouchOSC`
   - Monitor what messages Accordance sends/receives
3. **Contact Accordance Support** for the exact OSC address patterns

## Step 6: Update Server Code (If Needed)

If Accordance uses a different OSC format, update `server.js`:

```javascript
// In queryAccordanceViaOSC function, adjust the message:
const message = {
    address: '/accordance/YOUR_ACTUAL_ADDRESS',  // Change this
    args: [
        { type: 's', value: word },
        ...(reference ? [{ type: 's', value: reference }] : [])
    ]
};
```

## Troubleshooting

### "OSC module not available"
- Run: `npm install osc`
- Restart the server

### "Failed to create OSC client"
- Check that the port isn't already in use
- Try a different port number
- Check firewall settings

### "No response from Accordance"
- Verify Accordance is running
- Check that Accordance OSC is enabled
- Verify the port number matches
- Check that Accordance is listening on the correct address (127.0.0.1 vs 0.0.0.0)

### "Accordance response received but format not recognized"
- The OSC message format may be different
- Check server logs for the actual message format
- Update the response parser in `server.js`

## Current Status

**The integration is ready to receive Accordance data**, but since Accordance's OSC API may still be in development (based on the forum discussion), you may need to:

1. **Wait for Accordance to release the OSC API** (if not yet available)
2. **Work with Accordance support** to get beta access or documentation
3. **Use test data** in the meantime (which is what you're seeing now)

## Alternative: Using Accordance's Instant Details

If OSC API isn't available, you might be able to:
1. Use Accordance's **Instant Details** feature manually
2. Copy/paste definitions into your notes
3. Wait for Accordance to release the full OSC API

## Next Steps

1. ✅ Update `osc-config.json` with `accordancePort`
2. ✅ Check Accordance Preferences for OSC settings
3. ✅ Contact Accordance Support if OSC isn't available
4. ✅ Test the connection using the steps above
5. ⏳ Adjust OSC message format once you know Accordance's API

## Support Resources

- **Accordance Forums:** https://forums.accordancebible.com/
- **Accordance Support:** support@accordancebible.com
- **OSC Protocol Info:** https://opensoundcontrol.org/
- **Forum Post:** https://forums.accordancebible.com/topic/37607-accordance-api-a-user-driven-vision-for-the-future/