bible-app/ACCORDANCE_INTEGRATION.md

# Accordance API Integration Guide

This guide explains how to use the Accordance Bible Software API integration to enhance popup cards for underlined words in the Bible App.

## Overview

The Accordance integration allows your Bible App to query Accordance Bible Software for enhanced word information, including:
- Strong's numbers
- Lexical forms
- Morphology information
- Definitions
- Usage notes
- Cross-references
- Commentary references
- Original language details

## Setup

### 1. Configure Accordance OSC Settings

The integration uses OSC (Open Sound Control) to communicate with Accordance. Your `osc-config.json` file is already configured:

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

**Note:** You may need to add an `accordancePort` field to specify the port Accordance listens on (commonly 3334). Update your config:

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

### 2. Enable Accordance OSC in Accordance

1. Open Accordance Bible Software
2. Go to Preferences/Settings
3. Enable OSC support (if available)
4. Configure the OSC port (default is often 3334)
5. Ensure Accordance is running when using the Bible App

### 3. Verify Integration

The integration will automatically check if Accordance is available when you click on underlined words. If Accordance is not running or not configured, the app will fall back to the standard word information.

## How It Works

### Word Click Flow

1. User clicks on an underlined word in the Bible text
2. The app fetches basic word information (Greek/Hebrew) from local dictionaries
3. If Accordance is available, the app queries Accordance via OSC for additional information
4. The popup card displays:
   - Standard Greek/Hebrew information
   - Enhanced Accordance data (if available)

### API Endpoints

The integration adds two server endpoints:

- **GET `/api/accordance/status`** - Check if Accordance is available
- **POST `/api/accordance/word`** - Query Accordance for word information

### Client-Side Module

The `accordance-api.js` module provides:

- `queryAccordanceWord(word, reference)` - Query Accordance for a specific word
- `enhanceWordInfoWithAccordance(wordInfo, word, reference)` - Enhance existing word info with Accordance data
- `checkAccordanceAvailability()` - Check if Accordance integration is available

## Customizing Accordance OSC Commands

Based on the Accordance API forum discussion, you may need to adjust the OSC message format in `server.js`. The current implementation uses:

```
/accordance/word [word] [reference]
```

You may need to modify this based on Accordance's actual OSC API. Check the Accordance documentation or forum for the correct OSC address patterns.

### Example OSC Message Format

```javascript
{
  address: '/accordance/word',
  args: [
    { type: 's', value: 'love' },
    { type: 's', value: 'John 3:16' }
  ]
}
```

## Popup Display

When Accordance data is available, the popup card will show an "Accordance" section with:

- **Strong's:** Strong's number (e.g., G25)
- **Lexical Form:** Base form of the word
- **Morphology:** Grammatical information
- **Definition:** Detailed definition
- **Usage:** Usage notes
- **Original Language:** Original language text
- **Cross References:** Related verses
- **Commentaries:** Commentary references

## Troubleshooting

### Accordance Data Not Appearing

1. **Check Accordance is running:** Ensure Accordance Bible Software is running
2. **Verify OSC port:** Check that Accordance's OSC port matches your config
3. **Check network:** Ensure both apps can communicate (same machine or network)
4. **Review console:** Check browser console for Accordance API errors
5. **Test status endpoint:** Visit `/api/accordance/status` to verify configuration

### OSC Connection Issues

- Ensure the OSC module is installed: `npm i osc`
- Check firewall settings if using network communication
- Verify IP addresses in `osc-config.json` match your network setup

## Future Enhancements

Based on the Accordance API forum discussion, potential enhancements include:

1. **Real-time Instant Details:** Display Accordance's Instant Details panel data
2. **Commentary Integration:** Show commentary excerpts directly in popups
3. **Cross-Reference Navigation:** Make cross-references clickable
4. **Multiple Resource Support:** Query multiple Accordance resources simultaneously
5. **Caching:** Cache Accordance responses for better performance

## References

- Accordance API Forum Discussion: https://forums.accordancebible.com/topic/37607-accordance-api-a-user-driven-vision-for-the-future/
- OSC Protocol Documentation: Standard OSC protocol for inter-application communication

## Support

For issues or questions:
1. Check the browser console for error messages
2. Verify Accordance is running and OSC is enabled
3. Review the server logs for OSC communication errors
4. Consult Accordance documentation for OSC API details