🎵 Audio Capture

A Node.js module based on Swift and CoreAudio for capturing Mac system audio streams. Solves the technical challenge of Node.js being unable to directly access macOS system speaker audio streams.

中文版本 | English Version

✨ Features

• 🎯 System-level Capture: Uses CoreAudio Process Tap technology to capture audio output from all applications
• ⚡ High Performance: Swift native code provides near-C language performance
• 🔧 Easy API: Provides clean JavaScript interface with Promise and event-driven support
• 🎵 Real-time Processing: Supports real-time audio data processing and format conversion
• 📁 Multi-format Output: Supports WAV format audio file output
• 🛡️ Error Handling: Comprehensive error handling and state management
• 📊 Detailed Logging: Provides detailed debugging and status logs

🚀 Quick Start

Installation

# Install from GitHub
npm install git+https://github.com/sparticleinc/mac-audio-capture.git

# Or clone repository and install locally
git clone https://github.com/sparticleinc/mac-audio-capture.git
cd mac-audio-capture
npm install

Basic Usage

const AudioCapture = require('./lib');

async function captureAudio() {
    // Create audio capture instance
    const capture = new AudioCapture({
        sampleRate: 48000,
        channelCount: 2
    });
    
    // Listen to events
    capture.on('started', () => console.log('🎙️ Started capturing'));
    capture.on('stopped', () => console.log('🛑 Stopped capturing'));
    capture.on('error', (error) => console.error('❌ Error:', error.message));
    
    try {
        // Record 5 seconds of audio
        const filePath = await capture.record(5000, 'output.wav');
        console.log('✅ Recording completed:', filePath);
    } catch (error) {
        console.error('Recording failed:', error.message);
    }
}

captureAudio();

Advanced Usage

const AudioCapture = require('./lib');

async function advancedCapture() {
    const capture = new AudioCapture();
    
    // Configure audio capture
    await capture.configure({
        sampleRate: 44100,
        channelCount: 1,
        logPath: './logs/audio.log'
    });
    
    // Start capture
    await capture.startCapture({ interval: 100 });
    
    // Real-time audio data processing
    capture.on('data', (audioData) => {
        console.log(`📊 Received ${audioData.length} audio segments`);
        // Process audio data here
    });
    
    // Record for 3 seconds
    await new Promise(resolve => setTimeout(resolve, 3000));
    
    // Stop capture
    await capture.stopCapture();
    
    // Save as WAV file
    const filePath = await capture.saveToWav('advanced-output.wav');
    console.log('File saved:', filePath);
}

📖 API Documentation

AudioCapture Class

Constructor

new AudioCapture(options?: AudioCaptureConfig)

Parameters:

• options (optional): Configuration options
  • sampleRate: Sample rate (default: 48000)
  • channelCount: Number of channels (default: 2)
  • logPath: Log file path

Methods

configure(options)

Configure audio capture

await capture.configure({
    sampleRate: 44100,
    channelCount: 1,
    logPath: './audio.log'
});

startCapture(options)

Start audio capture

await capture.startCapture({ interval: 100 });

stopCapture()

Stop audio capture

await capture.stopCapture();

record(durationMs, outputPath)

Record audio for specified duration

const filePath = await capture.record(5000, 'output.wav');

saveToWav(outputPath, audioData)

Save audio data as WAV file

const filePath = await capture.saveToWav('output.wav');

getAudioData()

Get current audio data

const audioData = capture.getAudioData();

clearBuffer()

Clear audio buffer

capture.clearBuffer();

Events

• configured: Triggered when configuration is complete
• started: Triggered when capture starts
• stopped: Triggered when capture stops
• data: Triggered when audio data is received
• saved: Triggered when file save is complete
• error: Triggered when an error occurs

🛠️ Development

Requirements

• Node.js 16+
• macOS 14.4+
• Swift 5.3+
• Xcode Command Line Tools

Install Dependencies

npm install

Build

# Development build
npm run dev

# Production build
npm run build

Test

npm test

Run Examples

npm run example

Code Formatting

npm run format
npm run lint

🏗️ Technical Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Node.js App   │    │   NAPI Binding  │    │  Swift Module   │
│                 │◄──►│                 │◄──►│                 │
│  JavaScript API │    │  C++ Interface  │    │  CoreAudio API  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  Audio Buffer   │    │  Process Tap    │
                       │                 │    │                 │
                       │  Base64 Data    │    │  System Audio   │
                       └─────────────────┘    └─────────────────┘

Core Technologies

1. CoreAudio Process Tap: System-level audio capture
2. Aggregate Device: Virtual audio device management
3. NAPI (Node-API): Cross-language binding
4. Event-Driven Architecture: Event-driven architecture
5. Real-time Audio Processing: Real-time audio processing

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Issues and Pull Requests are welcome!

Contributing Guidelines

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

If you encounter issues or have suggestions, please:

1. Check the Issues page
2. Create a new Issue
3. Contact the maintainer

⚠️ Important Usage Notice

System Audio Recording Permission Required

Before using this module, you must manually enable system audio recording permission for your application:

1. Open System Preferences > Privacy & Security > Screen Recording & System Audio Recording
2. Find your application in the list
3. Enable "System Audio Recording Only" for your app
4. Restart your application after granting permission

Note: This module requires system audio recording permission to capture system audio streams. Without proper permission, the module may run but will not capture actual system audio data.

Permission Setup Steps:

1. Navigate to System Preferences:

   • Open System Preferences (or System Settings on newer macOS versions)
   • Go to Privacy & Security
   • Find "Screen Recording & System Audio Recording"

2. Enable Permission for Your App:

   • Locate your application in the list
   • Check the box for "System Audio Recording Only"
   • If your app is not listed, click the "+" button to add it

3. Restart Your Application:

   • Close your application completely
   • Reopen your application
   • Test audio capture functionality

Troubleshooting Permission Issues

If you encounter issues with audio capture:

1. Verify Permission Settings:

   • Ensure your app has "System Audio Recording Only" permission
   • Check that no other apps are using system audio recording
   • Restart your application after permission changes

2. Common Issues:

   • If no audio is captured, check permission settings
   • If permission option is not visible, update macOS to latest version
   • If app is not in permission list, manually add it using the "+" button

3. Alternative Permission Locations:

   • On some macOS versions: System Preferences > Security & Privacy > Privacy > Microphone
   • Look for "System Audio" option in microphone settings

Build Issues

If build fails, make sure:

• Xcode Command Line Tools installed: xcode-select --install
• Swift version >= 5.3: swift --version
• Node.js version >= 16: node --version

📋 TODO List

High Priority

• Implement accurate permission checking - Add proper system audio recording permission validation
• Add permission status detection - Real-time permission status monitoring
• Improve error handling - Better error messages for permission-related issues

Medium Priority

• Add audio format validation - Validate audio format compatibility
• Implement audio quality settings - Configurable audio quality options
• Add audio device selection - Allow users to select specific audio devices
• Implement audio effects - Basic audio processing features
• Add streaming support - Real-time audio streaming capabilities

🙏 Acknowledgments

• CoreAudio - Apple's audio framework
• NAPI - Node.js native API
• Swift NAPI Bindings - Swift and NAPI binding library

🎯 Project Support

This project is supported by Felo Subtitles - an AI-powered real-time translation and multilingual subtitle tool that easily enables cross-language communication.

Why Felo Subtitles?

• 🎯 Smart Speaker Recognition: Advanced context analysis and speaker identification technology that accurately distinguishes meeting participants and automatically labels each speech segment with clear identity
• 📊 Intelligent Summary Templates: Automatically extracts key information and generates structured summaries
• 🏥 Industry Professional Vocabulary: Customizable speech recognition dictionaries and translation terminology databases help improve recognition and translation accuracy for industry terms, brand names, and personal names
• 🌐 Real-time Subtitle Sharing: Through a single sharing link, Felo Subtitles allows anyone to view subtitle content in real-time, improving cross-regional collaboration efficiency

Try Felo Subtitles Now →

---

Note: This module only supports macOS systems and requires appropriate audio permissions.