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:

{
  "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:

fetch('/api/accordance/status').then(r => r.json()).then(console.log)

You should see:

{
  "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:

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