proc-tap 0.2.0__tar.gz → 0.3.0__tar.gz

{proc_tap-0.2.0/src/proc_tap.egg-info → proc_tap-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proc-tap
-Version: 0.2.0
+Version: 0.3.0
 Summary: Cross-platform process-level audio capture library
 Author-email: m96-chan <y_harada@technologies.moe>
 License: MIT
@@ -28,16 +28,24 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
 Requires-Dist: pulsectl>=23.5.0; sys_platform == "linux"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: types-psutil; extra == "dev"
+Requires-Dist: scipy-stubs; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
 Provides-Extra: linux
 Requires-Dist: pulsectl>=23.5.0; extra == "linux"
+Provides-Extra: contrib
+Requires-Dist: faster-whisper>=1.0.0; extra == "contrib"
+Provides-Extra: hq-resample
+Requires-Dist: samplerate>=0.1.0; (python_version < "3.13" or sys_platform != "win32") and extra == "hq-resample"
 Dynamic: license-file
 
 <div align="center">
@@ -68,10 +76,10 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
 | Platform | Status | Backend | Notes |
 |----------|--------|---------|-------|
 | **Windows** | ✅ **Fully Supported** | WASAPI (C++ native) | Windows 10/11 (20H1+) |
-| **Linux** | 🧪 **Experimental** | PulseAudio/PipeWire | Basic support, sink monitor capture |
+| **Linux** | ✅ **Fully Supported** | PipeWire Native / PulseAudio | Per-process isolation, auto-fallback (v0.4.0+) |
 | **macOS** | 🧪 **Experimental** | Core Audio Process Tap | macOS 14.4+ (Sonoma) required |
 
-<sub>\* Linux and macOS support are experimental with limitations (see requirements). Windows is currently the only fully functional platform.</sub>
+<sub>\* Linux is fully supported with PipeWire/PulseAudio (v0.4.0+). macOS support is experimental (see requirements).</sub>
 
 </div>
 
@@ -83,11 +91,11 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
   (VRChat, games, browsers, Discord, DAWs, streaming tools, etc.)
 
 - 🌍 **Cross-platform architecture**
-  → Windows (fully supported) | Linux (experimental) | macOS (experimental, 14.4+)
+  → Windows (fully supported) | Linux (fully supported, v0.4.0+) | macOS (experimental, 14.4+)
 
 - ⚡ **Platform-optimized backends**
   → Windows: ActivateAudioInterfaceAsync (modern WASAPI)
-  → Linux: PulseAudio/PipeWire (experimental)
+  → Linux: PipeWire Native API / PulseAudio (fully supported, v0.4.0+)
   → macOS: Core Audio Process Tap API (macOS 14.4+)
 
 - 🧵 **Low-latency, thread-safe audio engine**
@@ -121,6 +129,22 @@ pip install proc-tap
   sudo dnf install pulseaudio-utils
   ```
 
+**Optional: High-Quality Audio Resampling** (74% faster / 3.8x speedup for sample rate conversion):
+
+```bash
+pip install proc-tap[hq-resample]
+```
+
+**Performance:** With `libsamplerate`, resampling achieves **0.66ms per 10ms chunk** (vs 2.6ms with scipy-only).
+
+**Compatibility Notes:**
+- ✅ **Python 3.10-3.12**: Works on all platforms
+- ✅ **Linux/macOS + Python 3.13+**: Should work (you can try it!)
+- ⚠️ **Windows + Python 3.13+**: May fail to build (as of 2025-01)
+  - If it fails, the library automatically falls back to scipy's polyphase filtering
+  - Still provides excellent audio quality, just 74% slower for resampling
+  - You can still try installing - if it works, great! If not, no harm done.
+
 📚 **[Read the Full Documentation](https://m96-chan.github.io/ProcTap/)** for detailed guides and API reference.
 
 **From TestPyPI** (for testing pre-releases):
@@ -147,13 +171,21 @@ pip install -e .
 - WASAPI support
 - **No admin privileges required**
 
-**Linux (Experimental):**
-- Linux with PulseAudio or PipeWire (with pulseaudio-compat)
+**Linux (Fully Supported - v0.4.0+):**
+- Linux with PulseAudio or PipeWire
 - Python 3.10+
-- `pulsectl` library: **automatically installed with `pip install proc-tap`**
-- `parec` command: install with `sudo apt-get install pulseaudio-utils`
-- ⚠️ **EXPERIMENTAL:** Basic PulseAudio support implemented
-- ⚠️ **LIMITATION:** Currently captures from entire sink monitor (may include other apps)
+- **Auto-detection:** Automatically selects best available backend
+- **Native PipeWire API** (recommended):
+  - `libpipewire-0.3-dev`: `sudo apt-get install libpipewire-0.3-dev`
+  - Ultra-low latency: ~2-5ms
+  - Auto-selected when available
+- **PipeWire subprocess:**
+  - `pw-record`: install with `sudo apt-get install pipewire-media-session`
+- **PulseAudio fallback:**
+  - `pulsectl` library: automatically installed
+  - `parec` command: `sudo apt-get install pulseaudio-utils`
+- ✅ **Per-process isolation** using null-sink strategy
+- ✅ **Graceful fallback** chain: Native → PipeWire subprocess → PulseAudio
 
 **macOS (Experimental):**
 - macOS 14.4 (Sonoma) or later
@@ -239,15 +271,29 @@ asyncio.run(main())
 
 ### Audio Format
 
-**Note:** The native extension uses a **fixed audio format** (hardcoded in C++):
+**Native Backend Format** (Windows WASAPI, hardcoded in C++):
 
 | Parameter | Value | Description |
 |-----------|-------|-------------|
-| Sample Rate | **44,100 Hz** | CD quality (fixed) |
-| Channels | **2** | Stereo (fixed) |
-| Bit Depth | **16-bit** | PCM format (fixed) |
+| Sample Rate | **44,100 Hz** | CD quality (fixed in C++) |
+| Channels | **2** | Stereo (fixed in C++) |
+| Bit Depth | **16-bit** | PCM format (fixed in C++) |
 
-The `StreamConfig` class exists for API compatibility but does not change the native backend format.
+**Output Format Conversion** (v0.2.1+):
+
+The `StreamConfig` class controls the **output format** through automatic conversion:
+- Native format → converted to match your `StreamConfig` settings
+- Supports sample rate conversion (e.g., 44.1kHz → 48kHz)
+- Supports channel conversion (mono ↔ stereo)
+- Supports bit depth conversion (8/16/24/32-bit)
+- Zero overhead when formats match (automatic bypass)
+
+Example:
+```python
+# Get audio as 48kHz mono 24-bit
+config = StreamConfig(sample_rate=48000, channels=1, width=3)
+tap = ProcTap(pid, config=config)
+```
 
 ---
 
@@ -312,7 +358,7 @@ finally:
 ## 🐧 Linux Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -330,7 +376,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=44100, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         input("Recording... Press Enter to stop.\n")
 finally:
@@ -348,7 +394,7 @@ finally:
 ## 🍎 macOS Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -366,7 +412,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=48000, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         print("⚠️  On first run, macOS will prompt for permission.")
         input("Recording... Press Enter to stop.\n")
@@ -403,9 +449,14 @@ pip install -e .
 - Windows SDK
 - CMake (if you modularize the C++ code)
 
-**Linux/macOS:**
+**Linux:**
+- No C++ compiler required (pure Python)
+- System dependencies: `pulseaudio-utils` or `pipewire` with `libpipewire-0.3-dev`
+
+**macOS:**
 - No C++ compiler required (pure Python)
-- Note: Backends are not yet functional on these platforms
+- Swift toolchain (optional, for building the Swift CLI helper)
+- If Swift is not available, pre-built binary is included in the package
 
 ---
 

{proc_tap-0.2.0 → proc_tap-0.3.0}/README.md

@@ -26,10 +26,10 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
 | Platform | Status | Backend | Notes |
 |----------|--------|---------|-------|
 | **Windows** | ✅ **Fully Supported** | WASAPI (C++ native) | Windows 10/11 (20H1+) |
-| **Linux** | 🧪 **Experimental** | PulseAudio/PipeWire | Basic support, sink monitor capture |
+| **Linux** | ✅ **Fully Supported** | PipeWire Native / PulseAudio | Per-process isolation, auto-fallback (v0.4.0+) |
 | **macOS** | 🧪 **Experimental** | Core Audio Process Tap | macOS 14.4+ (Sonoma) required |
 
-<sub>\* Linux and macOS support are experimental with limitations (see requirements). Windows is currently the only fully functional platform.</sub>
+<sub>\* Linux is fully supported with PipeWire/PulseAudio (v0.4.0+). macOS support is experimental (see requirements).</sub>
 
 </div>
 
@@ -41,11 +41,11 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
   (VRChat, games, browsers, Discord, DAWs, streaming tools, etc.)
 
 - 🌍 **Cross-platform architecture**
-  → Windows (fully supported) | Linux (experimental) | macOS (experimental, 14.4+)
+  → Windows (fully supported) | Linux (fully supported, v0.4.0+) | macOS (experimental, 14.4+)
 
 - ⚡ **Platform-optimized backends**
   → Windows: ActivateAudioInterfaceAsync (modern WASAPI)
-  → Linux: PulseAudio/PipeWire (experimental)
+  → Linux: PipeWire Native API / PulseAudio (fully supported, v0.4.0+)
   → macOS: Core Audio Process Tap API (macOS 14.4+)
 
 - 🧵 **Low-latency, thread-safe audio engine**
@@ -79,6 +79,22 @@ pip install proc-tap
   sudo dnf install pulseaudio-utils
   ```
 
+**Optional: High-Quality Audio Resampling** (74% faster / 3.8x speedup for sample rate conversion):
+
+```bash
+pip install proc-tap[hq-resample]
+```
+
+**Performance:** With `libsamplerate`, resampling achieves **0.66ms per 10ms chunk** (vs 2.6ms with scipy-only).
+
+**Compatibility Notes:**
+- ✅ **Python 3.10-3.12**: Works on all platforms
+- ✅ **Linux/macOS + Python 3.13+**: Should work (you can try it!)
+- ⚠️ **Windows + Python 3.13+**: May fail to build (as of 2025-01)
+  - If it fails, the library automatically falls back to scipy's polyphase filtering
+  - Still provides excellent audio quality, just 74% slower for resampling
+  - You can still try installing - if it works, great! If not, no harm done.
+
 📚 **[Read the Full Documentation](https://m96-chan.github.io/ProcTap/)** for detailed guides and API reference.
 
 **From TestPyPI** (for testing pre-releases):
@@ -105,13 +121,21 @@ pip install -e .
 - WASAPI support
 - **No admin privileges required**
 
-**Linux (Experimental):**
-- Linux with PulseAudio or PipeWire (with pulseaudio-compat)
+**Linux (Fully Supported - v0.4.0+):**
+- Linux with PulseAudio or PipeWire
 - Python 3.10+
-- `pulsectl` library: **automatically installed with `pip install proc-tap`**
-- `parec` command: install with `sudo apt-get install pulseaudio-utils`
-- ⚠️ **EXPERIMENTAL:** Basic PulseAudio support implemented
-- ⚠️ **LIMITATION:** Currently captures from entire sink monitor (may include other apps)
+- **Auto-detection:** Automatically selects best available backend
+- **Native PipeWire API** (recommended):
+  - `libpipewire-0.3-dev`: `sudo apt-get install libpipewire-0.3-dev`
+  - Ultra-low latency: ~2-5ms
+  - Auto-selected when available
+- **PipeWire subprocess:**
+  - `pw-record`: install with `sudo apt-get install pipewire-media-session`
+- **PulseAudio fallback:**
+  - `pulsectl` library: automatically installed
+  - `parec` command: `sudo apt-get install pulseaudio-utils`
+- ✅ **Per-process isolation** using null-sink strategy
+- ✅ **Graceful fallback** chain: Native → PipeWire subprocess → PulseAudio
 
 **macOS (Experimental):**
 - macOS 14.4 (Sonoma) or later
@@ -197,15 +221,29 @@ asyncio.run(main())
 
 ### Audio Format
 
-**Note:** The native extension uses a **fixed audio format** (hardcoded in C++):
+**Native Backend Format** (Windows WASAPI, hardcoded in C++):
 
 | Parameter | Value | Description |
 |-----------|-------|-------------|
-| Sample Rate | **44,100 Hz** | CD quality (fixed) |
-| Channels | **2** | Stereo (fixed) |
-| Bit Depth | **16-bit** | PCM format (fixed) |
+| Sample Rate | **44,100 Hz** | CD quality (fixed in C++) |
+| Channels | **2** | Stereo (fixed in C++) |
+| Bit Depth | **16-bit** | PCM format (fixed in C++) |
 
-The `StreamConfig` class exists for API compatibility but does not change the native backend format.
+**Output Format Conversion** (v0.2.1+):
+
+The `StreamConfig` class controls the **output format** through automatic conversion:
+- Native format → converted to match your `StreamConfig` settings
+- Supports sample rate conversion (e.g., 44.1kHz → 48kHz)
+- Supports channel conversion (mono ↔ stereo)
+- Supports bit depth conversion (8/16/24/32-bit)
+- Zero overhead when formats match (automatic bypass)
+
+Example:
+```python
+# Get audio as 48kHz mono 24-bit
+config = StreamConfig(sample_rate=48000, channels=1, width=3)
+tap = ProcTap(pid, config=config)
+```
 
 ---
 
@@ -270,7 +308,7 @@ finally:
 ## 🐧 Linux Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -288,7 +326,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=44100, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         input("Recording... Press Enter to stop.\n")
 finally:
@@ -306,7 +344,7 @@ finally:
 ## 🍎 macOS Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -324,7 +362,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=48000, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         print("⚠️  On first run, macOS will prompt for permission.")
         input("Recording... Press Enter to stop.\n")
@@ -361,9 +399,14 @@ pip install -e .
 - Windows SDK
 - CMake (if you modularize the C++ code)
 
-**Linux/macOS:**
+**Linux:**
+- No C++ compiler required (pure Python)
+- System dependencies: `pulseaudio-utils` or `pipewire` with `libpipewire-0.3-dev`
+
+**macOS:**
 - No C++ compiler required (pure Python)
-- Note: Backends are not yet functional on these platforms
+- Swift toolchain (optional, for building the Swift CLI helper)
+- If Swift is not available, pre-built binary is included in the package
 
 ---
 

{proc_tap-0.2.0 → proc_tap-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proc-tap"
-version = "0.2.0"
+version = "0.3.0"
 description = "Cross-platform process-level audio capture library"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,6 +35,8 @@ classifiers = [
 
 # Platform-specific dependencies (automatically installed based on OS)
 dependencies = [
+    "numpy>=1.20.0",
+    "scipy>=1.7.0",
     "pulsectl>=23.5.0; sys_platform == 'linux'",
 ]
 
@@ -47,7 +49,9 @@ Issues = "https://github.com/m96-chan/ProcTap/issues"
 dev = [
     "pytest",
     "mypy",
-    "types-setuptools"
+    "types-setuptools",
+    "types-psutil",
+    "scipy-stubs",
 ]
 docs = [
     "mkdocs-material>=9.0.0",
@@ -56,7 +60,51 @@ docs = [
 linux = [
     "pulsectl>=23.5.0",
 ]
+# Contrib modules with optional dependencies
+contrib = [
+    "faster-whisper>=1.0.0",
+]
+# High-quality resampling using libsamplerate (optional, scipy fallback available)
+# Note: samplerate package may fail to build on Windows with Python 3.13+ due to
+# C compiler compatibility issues (as of 2025-01). Non-Windows platforms and
+# Python <3.13 should work fine. If installation fails, scipy's polyphase
+# filtering provides excellent quality as a fallback (though 30-50% slower).
+# This is an optional optimization - the converter works well without it.
+hq-resample = [
+    "samplerate>=0.1.0; python_version < '3.13' or sys_platform != 'win32'",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["proctap*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = false
+
+# Platform-specific and optional dependencies
+[[tool.mypy.overrides]]
+module = [
+    "pulsectl",
+    "pulsectl.*",
+    "discord",
+    "discord.*",
+    "faster_whisper",
+    "faster_whisper.*",
+    "samplerate",
+    "samplerate.*",
+]
+ignore_missing_imports = true

{proc_tap-0.2.0 → proc_tap-0.3.0/src/proc_tap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proc-tap
-Version: 0.2.0
+Version: 0.3.0
 Summary: Cross-platform process-level audio capture library
 Author-email: m96-chan <y_harada@technologies.moe>
 License: MIT
@@ -28,16 +28,24 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
 Requires-Dist: pulsectl>=23.5.0; sys_platform == "linux"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: types-psutil; extra == "dev"
+Requires-Dist: scipy-stubs; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
 Provides-Extra: linux
 Requires-Dist: pulsectl>=23.5.0; extra == "linux"
+Provides-Extra: contrib
+Requires-Dist: faster-whisper>=1.0.0; extra == "contrib"
+Provides-Extra: hq-resample
+Requires-Dist: samplerate>=0.1.0; (python_version < "3.13" or sys_platform != "win32") and extra == "hq-resample"
 Dynamic: license-file
 
 <div align="center">
@@ -68,10 +76,10 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
 | Platform | Status | Backend | Notes |
 |----------|--------|---------|-------|
 | **Windows** | ✅ **Fully Supported** | WASAPI (C++ native) | Windows 10/11 (20H1+) |
-| **Linux** | 🧪 **Experimental** | PulseAudio/PipeWire | Basic support, sink monitor capture |
+| **Linux** | ✅ **Fully Supported** | PipeWire Native / PulseAudio | Per-process isolation, auto-fallback (v0.4.0+) |
 | **macOS** | 🧪 **Experimental** | Core Audio Process Tap | macOS 14.4+ (Sonoma) required |
 
-<sub>\* Linux and macOS support are experimental with limitations (see requirements). Windows is currently the only fully functional platform.</sub>
+<sub>\* Linux is fully supported with PipeWire/PulseAudio (v0.4.0+). macOS support is experimental (see requirements).</sub>
 
 </div>
 
@@ -83,11 +91,11 @@ Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
   (VRChat, games, browsers, Discord, DAWs, streaming tools, etc.)
 
 - 🌍 **Cross-platform architecture**
-  → Windows (fully supported) | Linux (experimental) | macOS (experimental, 14.4+)
+  → Windows (fully supported) | Linux (fully supported, v0.4.0+) | macOS (experimental, 14.4+)
 
 - ⚡ **Platform-optimized backends**
   → Windows: ActivateAudioInterfaceAsync (modern WASAPI)
-  → Linux: PulseAudio/PipeWire (experimental)
+  → Linux: PipeWire Native API / PulseAudio (fully supported, v0.4.0+)
   → macOS: Core Audio Process Tap API (macOS 14.4+)
 
 - 🧵 **Low-latency, thread-safe audio engine**
@@ -121,6 +129,22 @@ pip install proc-tap
   sudo dnf install pulseaudio-utils
   ```
 
+**Optional: High-Quality Audio Resampling** (74% faster / 3.8x speedup for sample rate conversion):
+
+```bash
+pip install proc-tap[hq-resample]
+```
+
+**Performance:** With `libsamplerate`, resampling achieves **0.66ms per 10ms chunk** (vs 2.6ms with scipy-only).
+
+**Compatibility Notes:**
+- ✅ **Python 3.10-3.12**: Works on all platforms
+- ✅ **Linux/macOS + Python 3.13+**: Should work (you can try it!)
+- ⚠️ **Windows + Python 3.13+**: May fail to build (as of 2025-01)
+  - If it fails, the library automatically falls back to scipy's polyphase filtering
+  - Still provides excellent audio quality, just 74% slower for resampling
+  - You can still try installing - if it works, great! If not, no harm done.
+
 📚 **[Read the Full Documentation](https://m96-chan.github.io/ProcTap/)** for detailed guides and API reference.
 
 **From TestPyPI** (for testing pre-releases):
@@ -147,13 +171,21 @@ pip install -e .
 - WASAPI support
 - **No admin privileges required**
 
-**Linux (Experimental):**
-- Linux with PulseAudio or PipeWire (with pulseaudio-compat)
+**Linux (Fully Supported - v0.4.0+):**
+- Linux with PulseAudio or PipeWire
 - Python 3.10+
-- `pulsectl` library: **automatically installed with `pip install proc-tap`**
-- `parec` command: install with `sudo apt-get install pulseaudio-utils`
-- ⚠️ **EXPERIMENTAL:** Basic PulseAudio support implemented
-- ⚠️ **LIMITATION:** Currently captures from entire sink monitor (may include other apps)
+- **Auto-detection:** Automatically selects best available backend
+- **Native PipeWire API** (recommended):
+  - `libpipewire-0.3-dev`: `sudo apt-get install libpipewire-0.3-dev`
+  - Ultra-low latency: ~2-5ms
+  - Auto-selected when available
+- **PipeWire subprocess:**
+  - `pw-record`: install with `sudo apt-get install pipewire-media-session`
+- **PulseAudio fallback:**
+  - `pulsectl` library: automatically installed
+  - `parec` command: `sudo apt-get install pulseaudio-utils`
+- ✅ **Per-process isolation** using null-sink strategy
+- ✅ **Graceful fallback** chain: Native → PipeWire subprocess → PulseAudio
 
 **macOS (Experimental):**
 - macOS 14.4 (Sonoma) or later
@@ -239,15 +271,29 @@ asyncio.run(main())
 
 ### Audio Format
 
-**Note:** The native extension uses a **fixed audio format** (hardcoded in C++):
+**Native Backend Format** (Windows WASAPI, hardcoded in C++):
 
 | Parameter | Value | Description |
 |-----------|-------|-------------|
-| Sample Rate | **44,100 Hz** | CD quality (fixed) |
-| Channels | **2** | Stereo (fixed) |
-| Bit Depth | **16-bit** | PCM format (fixed) |
+| Sample Rate | **44,100 Hz** | CD quality (fixed in C++) |
+| Channels | **2** | Stereo (fixed in C++) |
+| Bit Depth | **16-bit** | PCM format (fixed in C++) |
 
-The `StreamConfig` class exists for API compatibility but does not change the native backend format.
+**Output Format Conversion** (v0.2.1+):
+
+The `StreamConfig` class controls the **output format** through automatic conversion:
+- Native format → converted to match your `StreamConfig` settings
+- Supports sample rate conversion (e.g., 44.1kHz → 48kHz)
+- Supports channel conversion (mono ↔ stereo)
+- Supports bit depth conversion (8/16/24/32-bit)
+- Zero overhead when formats match (automatic bypass)
+
+Example:
+```python
+# Get audio as 48kHz mono 24-bit
+config = StreamConfig(sample_rate=48000, channels=1, width=3)
+tap = ProcTap(pid, config=config)
+```
 
 ---
 
@@ -312,7 +358,7 @@ finally:
 ## 🐧 Linux Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -330,7 +376,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=44100, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         input("Recording... Press Enter to stop.\n")
 finally:
@@ -348,7 +394,7 @@ finally:
 ## 🍎 macOS Example
 
 ```python
-from proctap import ProcessAudioTap, StreamConfig
+from proctap import ProcessAudioCapture, StreamConfig
 import wave
 
 pid = 12345  # Your target process ID
@@ -366,7 +412,7 @@ def on_data(pcm, frames):
 config = StreamConfig(sample_rate=48000, channels=2)
 
 try:
-    with ProcessAudioTap(pid, config=config, on_data=on_data):
+    with ProcessAudioCapture(pid, config=config, on_data=on_data):
         print("⚠️  Make sure the process is actively playing audio!")
         print("⚠️  On first run, macOS will prompt for permission.")
         input("Recording... Press Enter to stop.\n")
@@ -403,9 +449,14 @@ pip install -e .
 - Windows SDK
 - CMake (if you modularize the C++ code)
 
-**Linux/macOS:**
+**Linux:**
+- No C++ compiler required (pure Python)
+- System dependencies: `pulseaudio-utils` or `pipewire` with `libpipewire-0.3-dev`
+
+**macOS:**
 - No C++ compiler required (pure Python)
-- Note: Backends are not yet functional on these platforms
+- Swift toolchain (optional, for building the Swift CLI helper)
+- If Swift is not available, pre-built binary is included in the package
 
 ---
 

{proc_tap-0.2.0 → proc_tap-0.3.0}/src/proc_tap.egg-info/SOURCES.txt

@@ -13,8 +13,19 @@ src/proctap/_native.pyi
 src/proctap/core.py
 src/proctap/backends/__init__.py
 src/proctap/backends/base.py
+src/proctap/backends/converter.py
 src/proctap/backends/linux.py
 src/proctap/backends/macos.py
+src/proctap/backends/pipewire_native.py
 src/proctap/backends/windows.py
 src/proctap/contrib/__init__.py
-src/proctap/contrib/discord_source.py
+src/proctap/contrib/discord_source.py
+src/proctap/contrib/whisper_transcribe.py
+src/proctap/contrib/filters/__init__.py
+src/proctap/contrib/filters/base.py
+src/proctap/contrib/filters/chain.py
+src/proctap/contrib/filters/dsp.py
+src/proctap/contrib/filters/dynamics.py
+src/proctap/contrib/filters/vad.py
+tests/test_converter_optimizations.py
+tests/test_pipewire_native.py