Merge beneficial changes from DerDaku/master: mDNS, Bluetooth, PCM optimization

[Copilot]

This PR evaluates and merges beneficial improvements from DerDaku/master PR #31 while avoiding breaking changes and feature duplication.

Changes Merged

1. Enhanced mDNS Library (dnssd2)

• Upgraded from mdns-js to dnssd2 for better service discovery
• Added serviceUp, serviceChanged, and serviceDown event handlers for robust device tracking
• Improved handling of AirPlay devices with dynamic IP addresses
• Better reliability for stereo paired HomePods during network changes

2. Bluetooth Input Support ✨

• Full Bluetooth audio input functionality via bluetoothctl
• Auto-connection for unpaired Bluetooth devices when selected
• Connection status tracking for paired devices
• Uses bluealsa for ALSA-compatible streaming
• Gracefully handles systems without Bluetooth support
• Step-by-step bluetoothctl pairing instructions added to README Usage section

3. PCM Device Scanning

• PCM device scanning is enabled by default for backward compatibility
• Use DISABLE_PCM=1 environment variable to disable scanning on systems that don't use ALSA PCM devices
• Improves performance when disabled on systems using only Bluetooth or AirPlay

4. AirPlay Streaming Stability

• Added {end: false} pipe option to prevent premature stream closure
• More reliable multi-device streaming

5. Updated Dependencies

• airtunes2: Pinned to v2.4.9 for Node 20 compatibility and stability
• bluetoothctl: Added support via DerDaku's node-bluetoothctl fork
• dnssd2: v1.0.0 for better mDNS handling

Changes NOT Merged (Avoided Duplication)

• Stereo HomePod Support: Already fully implemented in current codebase
• UI Dropdown Height Increase: Not applicable - current code uses checkboxes instead of dropdown

Testing

Added 10 new test cases covering:

• PCM environment variable behavior (enabled by default, can be disabled)
• Bluetooth device ID formatting and connection tracking
• mDNS service event handling (serviceUp, serviceChanged, serviceDown)
• AirPlay device regex patterns and stereo pairing detection
• Pipe stability options

Test Results: ✅ All 16 tests passing

Documentation

• Updated README with new features, prerequisites, and environment variables
• Added comprehensive CHANGES.md entry documenting all improvements
• Added detailed Bluetooth pairing guide with step-by-step bluetoothctl instructions in README Usage section
• Documented how paired devices appear in BabelPod and automatic connection behavior

Environment Variables

• DISABLE_PCM=1: Disable PCM device scanning. PCM scanning is enabled by default. Set this if you don't use ALSA PCM devices for better performance.
• BABEL_PORT=3000: Set the HTTP server port (default: 3000).

Migration Notes

PCM devices work by default with no configuration needed.

For systems without ALSA/PCM devices (better performance):

DISABLE_PCM=1 node index.js

For new Bluetooth support:

sudo apt-get install bluez
# Follow the detailed bluetoothctl pairing instructions in the README

Quality Assurance

• ✅ No breaking changes - all changes are backward compatible
• ✅ JavaScript syntax verification passed
• ✅ No security vulnerabilities in new dependencies
• ✅ Code style consistent with existing codebase
• ✅ Error handling patterns maintained

Fixes #4

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Merge beneficial changes from DerDaku/master</issue_title>
<issue_description>Please evaluate and merge this upstream pull request: #DerDaku:master.

Make sure there are no breaking changes and that there isn't duplication of features.

After merging, implement tests and review code quality to keep it in line with project guidelines.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #4

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[benlachman]

@copilot update your plan based on the updated issue.

[Copilot]

@copilot update your plan based on the updated issue.

I've reviewed the DerDaku/master PR afaden#31 and updated the plan. The PR includes:

1. Updated mdns library (mdns-js → dnssd2) with better service update handling
2. Updated Bluetooth library for Node 20 compatibility
3. PCM input/output as optional via ENV variable
4. Support for stereo paired HomePods
5. Increased UI height for output selection

I'm now evaluating each change to ensure no breaking changes or feature duplication before merging.

[benlachman]

@copilot What do I need to install (npm/apt-get) to test this PR?

[Copilot]

@copilot What do I need to install (npm/apt-get) to test this PR?

To test this PR, you'll need:

NPM packages (automatically installed):

npm install

This installs the new dependencies: dnssd2, bluetoothctl, and airtunes2@v2.4.9.

System packages (apt-get on Debian/Ubuntu):

# For basic audio functionality
sudo apt-get install alsa-utils

# For Bluetooth input support (optional)
sudo apt-get install bluez

# For Node.js native module compilation
sudo apt-get install build-essential

To test specific features:

• PCM devices: Run with PCM=1 node index.js
• Bluetooth: Pair devices first using bluetoothctl, then select them in the UI
• AirPlay: No additional setup needed - devices discovered automatically via mDNS

The Bluetooth feature gracefully degrades if bluez is not installed - the app will still work without it.

[benlachman]

@copilot Let's flip the behavior of the PCM environment variable. PCM device support should default to on, and DISABLE_PCM=1 should disable it.

[Copilot]

@copilot Let's flip the behavior of the PCM environment variable. PCM device support should default to on, and DISABLE_PCM=1 should disable it.

Changed in commit 465d01a. PCM device scanning is now enabled by default, and DISABLE_PCM=1 disables it.

Updated:

• Code logic to check !process.env.DISABLE_PCM
• README and CHANGES.md documentation
• Test cases to reflect the new behavior
• All 16 tests passing ✅

[benlachman]

@copilot Add basic directions on how to pair a Bluetooth device using bluetoothctl in the usage section of the README.

[Copilot]

@copilot Add basic directions on how to pair a Bluetooth device using bluetoothctl in the usage section of the README.

Added in commit d7cf3f9. The README now includes a "Pairing Bluetooth Devices" section in the Usage area with step-by-step bluetoothctl instructions:

1. Install bluez
2. Start bluetoothctl and enable scanning
3. Pair, trust, and connect to devices using MAC address
4. Exit bluetoothctl

The section explains that paired devices will automatically appear in BabelPod's input device list.