bible-app/ACCORDANCE_SETUP_STEPS.md

# Accordance OSC API Setup - Step by Step

Based on the Accordance forum discussion, here's how to set up the Accordance API integration:

## Step 1: Enable OSC in Accordance

1. **Open Accordance Bible Software**

2. **Go to Preferences:**
   - **Mac:** `Accordance` → `Preferences` (or press `Cmd + ,`)
   - **Windows:** `Edit` → `Preferences` (or `Tools` → `Options`)

3. **Enable OSC Server:**
   - Look for the **General** tab in Preferences
   - Find the option labeled **"Enable OSC Server"** or **"Enable OSC Support"**
   - **Check the box** to enable it
   - **Note the port number** displayed (typically **53000**)

4. **Save and Restart:**
   - Click **OK** or **Apply** to save
   - You may need to restart Accordance for changes to take effect

## Step 2: Update Your Config File

Your `osc-config.json` has been updated with the correct port (53000). Verify it looks like this:

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

**Important:** If Accordance shows a different port number in Preferences, update `accordancePort` to match.

## Step 3: Ensure Accordance is Running

- **Keep Accordance open** while using the Bible App
- The OSC server only works when Accordance is running
- Make sure Accordance isn't in the background/minimized (some versions require it to be active)

## Step 4: Test the Connection

### Test 1: Check Server Status

Open your browser console (F12) and run:

```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 your Bible App server, look for:
```
[Accordance OSC] Listening on 127.0.0.1:53000
```

### Test 3: Test Word Query

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

## Step 5: Understanding the OSC Message Format

The current implementation sends OSC messages like this:

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

**Note:** Based on the forum discussion, the exact OSC address pattern may vary. If Accordance doesn't respond, you may need to adjust the address pattern in `server.js`.

### Common Accordance OSC Addresses (may vary):

- `/accordance/word` - Word lookup (current)
- `/accordance/instantDetails` - Instant Details data
- `/accordance/lookup` - General lookup
- `/accordance/query` - Query command

## Troubleshooting

### "OSC Server not found" or "Connection refused"

1. **Verify Accordance OSC is enabled:**
   - Go back to Preferences → General
   - Make sure "Enable OSC Server" is checked
   - Note the exact port number shown

2. **Check the port matches:**
   - Accordance shows port: `53000` (or your custom port)
   - Your `osc-config.json` has: `"accordancePort": 53000`
   - They must match!

3. **Check firewall:**
   - Windows Firewall or Mac Firewall may be blocking OSC
   - Allow Accordance and Node.js through firewall
   - Or temporarily disable firewall to test

4. **Verify Accordance is running:**
   - Accordance must be open and running
   - Check Task Manager (Windows) or Activity Monitor (Mac) to confirm

### "No response from Accordance"

1. **Check server logs** for OSC send errors
2. **Verify OSC address pattern** - Accordance may use a different address
3. **Test with OSC monitor tool:**
   - Use a tool like `OSCulator` or `TouchOSC` to monitor OSC traffic
   - See what messages Accordance actually sends/receives

### "OSC module not installed"

Run in your terminal:
```bash
cd bible-app
npm install osc
```

Then restart your server.

## What the Integration Does

When you click on a word in the Bible App:

1. **Sends OSC message** to Accordance: `/accordance/word [word] [reference]`
2. **Waits for Accordance response** (up to 3 seconds)
3. **Parses the response** and displays it in the popup card
4. **Falls back to test data** if Accordance doesn't respond

## Next Steps After Setup

Once OSC is working:

1. **Test with common words** like "love", "faith", "god"
2. **Check the popup cards** for Accordance data
3. **Review server logs** to see OSC communication
4. **Adjust OSC address** if needed based on Accordance's actual API

## Important Notes

- **Accordance must be running** for the integration to work
- **OSC Server must be enabled** in Accordance Preferences
- **Port numbers must match** between Accordance and your config
- **The API may still be in development** - some features might not work yet

## Getting Help

If you're still having issues:

1. **Check Accordance Forums:** https://forums.accordancebible.com/
2. **Contact Accordance Support:** support@accordancebible.com
3. **Reference the forum post:** https://forums.accordancebible.com/topic/37607-accordance-api-a-user-driven-vision-for-the-future/

## Current Status

✅ Config file updated with port 53000  
✅ Server code ready to send/receive OSC messages  
⏳ **You need to:** Enable OSC Server in Accordance Preferences  
⏳ **Then:** Test by clicking words in the Bible App