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:

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

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:

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

// 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/