audiotee/audiotee-js/DEVELOPMENT.md

AudioTee.js Development Guide

This guide covers setting up the development environment and workflow for AudioTee.js.

Project Structure

audiotee-js/
├── package.json           # npm package configuration with node-pre-gyp
├── index.js              # Main entry point, uses node-pre-gyp to find binary
├── lib/
│   └── AudioTeeStream.js # Core streaming class
├── scripts/
│   └── build.js          # Build script that copies AudioTee binary
├── test/
│   └── test.js           # Interactive and automated tests
├── examples/
│   └── basic-usage.js    # Usage examples and demos
├── .github/workflows/
│   └── release.yml       # CI/CD for automated releases
└── README.md             # User documentation

Initial Setup

1. Clone and Install Dependencies

git clone <your-audiotee-js-repo>
cd audiotee-js
npm install

2. Build AudioTee Binary

You'll need the AudioTee Swift project to build the binary:

# Option A: If AudioTee is in parent directory (current setup)
cd ../audiotee
swift build -c release
cd ../audiotee-js

# Option B: If AudioTee is elsewhere, set the path
export AUDIOTEE_BINARY_PATH=/path/to/audiotee/.build/release/audiotee

3. Build the Package

npm run build

This copies the AudioTee binary to bin/audiotee and makes it executable.

Development Workflow

Testing

# Interactive test - requires audio playback
npm test

# Quick automated test
npm test quick

# Run examples
node examples/basic-usage.js
node examples/basic-usage.js 2  # Save to file example

Building for Different Architectures

# For Intel Macs (if you have access)
npm run build

# For Apple Silicon (if you have access)  
npm run build

# Clean build artifacts
npm run clean

Testing the Package Locally

# Test the package as if installed from npm
npm pack
npm install -g audiotee-js-1.0.0.tgz

# Test in another directory
cd /tmp
node -e "const { AudioTeeStream } = require('audiotee-js'); console.log('✅ Works!')"

Release Process

1. Prepare Release

1. Update version in package.json
2. Update CHANGELOG.md (if you add one)
3. Test thoroughly on both Intel and Apple Silicon if possible
4. Commit changes

2. Create GitHub Release

git tag v1.0.0
git push origin v1.0.0

Then create a release on GitHub. This will trigger the automated build process.

3. Automated Release (via GitHub Actions)

The workflow will:

1. Build AudioTee binary for Intel and Apple Silicon
2. Package binaries using node-pre-gyp
3. Upload binaries to GitHub releases
4. Publish package to npm
5. Test the published package

4. Manual Release (if needed)

# Build and package
npm run build
npm run package

# Publish binary to GitHub releases
npm run publish-binary

# Publish to npm
npm publish

Configuration

Environment Variables

• AUDIOTEE_BINARY_PATH - Path to AudioTee binary for building
• GITHUB_TOKEN - For publishing binaries to GitHub releases
• NODE_AUTH_TOKEN - For publishing to npm

node-pre-gyp Configuration

The binary distribution is configured in package.json:

{
  "binary": {
    "module_name": "audiotee",
    "module_path": "./bin/",
    "remote_path": "v{version}/",
    "package_name": "audiotee-v{version}-{platform}-{arch}.tar.gz",
    "host": "https://github.com/your-org/audiotee-js/releases/download/"
  }
}

Update the host URL to match your repository.

Troubleshooting

Binary Not Found During Build

# Check if AudioTee is built
ls -la ../audiotee/.build/release/audiotee

# Or set custom path
export AUDIOTEE_BINARY_PATH=/path/to/your/audiotee/binary
npm run build

Permission Issues

# Make sure binary is executable
chmod +x bin/audiotee

# Check binary works
./bin/audiotee --help

node-pre-gyp Issues

# Clear cache
npm run clean
rm -rf node_modules
npm install

# Debug node-pre-gyp
DEBUG=node-pre-gyp npm run package

Code Style

• Follow the patterns in .cursorrules
• Use functional programming where possible
• No semicolons (per project preference)
• Handle errors via EventEmitter, don't throw
• Use British English in documentation
• Comprehensive JSDoc for public APIs

Testing Checklist

Before releasing:

• Basic audio capture works
• Both JSON and binary formats work
• Sample rate conversion works
• Process filtering works (if testable)
• Error handling works (invalid args, missing binary, etc.)
• Package installs and works on clean system
• Examples in README work
• CI/CD builds successfully

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Update documentation
6. Submit a pull request

Publishing Checklist

• Version updated in package.json
• Tests pass
• Documentation updated
• GitHub release created
• CI/CD completed successfully
• npm package published
• Installation test passes