PipeWire Node.js Client

Node.js library for PipeWire audio programming. Build audio applications, synthesizers, and streaming solutions using modern JavaScript patterns.

✨ Why This Library?

• 🚀 Real-Time Performance - Native C++ core optimized for low-latency audio
• 🎵 JavaScript-Friendly - Develop using idiomatic JavaScript
• 🔧 Modern Patterns - ES modules, iterators, explicit resource managment with using, built with TypeScript
• 🎛️ PipeWire Native - Direct integration with Linux's professional audio system

🚀 Quick Start

Prerequisites

This library requires PipeWire development libraries to be installed on your system:

Ubuntu/Debian

sudo apt update
sudo apt install libpipewire-0.3-dev pkg-config

Fedora/RHEL/Rocky Linux

sudo dnf install pipewire-devel pkgconf-pkg-config

Arch Linux

sudo pacman -S pipewire pkg-config

Installation

npm install pw-client

import { startSession } from "pw-client";

// Create processing thread for PipeWire
const session = await startSession();

try {
  // Create audio stream
  const stream = await session.createAudioOutputStream({
    name: "My Audio App",
    channels: 2, // Stereo output
  });

  try {
    await stream.connect();

    // Generate PCM audio samples
    function* generateTone(frequency: number, duration: number) {
      const totalSamples = duration * stream.rate * stream.channels;
      const cycle = (Math.PI * 2) / stream.rate;
      let phase = 0;

      for (let i = 0; i < totalSamples; i += stream.channels) {
        const sample = Math.sin(phase * frequency) * 0.2; // 20% volume

        // Output to both stereo channels
        for (let ch = 0; ch < stream.channels; ch++) {
          yield sample;
        }
        phase += cycle;
      }
    }

    // Play 2-second A4 note
    await stream.write(generateTone(440, 2.0));
  } finally {
    await stream.dispose(); // Clean up stream
  }
} finally {
  await session.dispose(); // Clean up session
}

📁 Complete Example: Run the full example with npx tsx examples/quick-start.mts

📚 Documentation

🎓 Tutorials - Learn by doing

• Getting Started - Your first PipeWire audio application
• Building a Simple Synthesizer - Create a tone generator
• Working with Stereo Audio - Multi-channel audio programming

🔧 How-to Guides - Solve specific problems

• Choose the Right Audio Quality - Match quality to your use case
• Generate Common Waveforms - Sine, square, sawtooth waves
• Monitor Stream Events - Handle connection state and errors

📖 Reference - Look up technical details

• API Reference - Complete class and method documentation
• Audio Sample Formats - Sample value ranges and formats

💡 Explanation - Understand the concepts

• Architecture Overview - How the library is designed
• Quality-Based API Design - Why we chose quality over formats
• Resource Management - Manual vs automatic cleanup patterns

🎵 Examples

Check out the examples/ directory for complete working demos. Use npx tsx to run them without having to compile:

npx tsx examples/getting-started.mts

� Troubleshooting

Installation Issues

"Package 'pipewire-0.3' not found"

• Install PipeWire development headers (see Prerequisites above)
• Verify with: pkg-config --exists pipewire-0.3 && echo "PipeWire found"

"node-gyp rebuild failed"

• Ensure you have build tools: sudo apt install build-essential (Ubuntu/Debian)
• Check Node.js version: node --version (requires >= 22.0.0)
• Try cleaning build cache: npm run build:native --clean

"libpipewire-0.3.so not found at runtime"

• Install PipeWire runtime: sudo apt install pipewire (Ubuntu/Debian)
• Check if PipeWire is running: systemctl --user status pipewire

Runtime Issues

"Failed to connect to PipeWire daemon"

• Ensure PipeWire is running: systemctl --user start pipewire
• Check permissions: Your user should be in the audio group

For more help:

• Check the troubleshooting guide
• Search existing issues
• Ask on GitHub Discussions

�📋 Prerequisites

• Linux with PipeWire - PipeWire 0.3+ required
• Node.js 22+ - ES modules and modern features required
• Build tools - GCC, make, Python 3
• PipeWire headers - libpipewire-0.3-dev package

🤝 Contributing

1. Read Contributing Guidelines
2. Check Architecture Overview
3. Follow Coding Style
4. See Documentation Authoring Guide for docs/examples
5. Run examples to test changes

📄 License

MIT License - see LICENSE file for details.

🎵 Build amazing audio applications with modern JavaScript and professional PipeWire performance!