proc-tap 0.2.0__py3-none-any.whl

proc_tap-0.2.0.dist-info/METADATA

@@ -0,0 +1,444 @@
+Metadata-Version: 2.4
+Name: proc-tap
+Version: 0.2.0
+Summary: Cross-platform process-level audio capture library
+Author-email: m96-chan <y_harada@technologies.moe>
+License: MIT
+Project-URL: Homepage, https://github.com/m96-chan/ProcTap
+Project-URL: Repository, https://github.com/m96-chan/ProcTap
+Project-URL: Issues, https://github.com/m96-chan/ProcTap/issues
+Keywords: audio,capture,wasapi,windows,linux,macos,pulseaudio,coreaudio,process,loopback
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C++
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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"
+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"
+Dynamic: license-file
+
+<div align="center">
+
+# 📡 ProcTap
+
+**Cross-Platform Per-Process Audio Capture**
+
+[![PyPI version](https://img.shields.io/pypi/v/proc-tap?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/proc-tap/)
+[![Python versions](https://img.shields.io/pypi/pyversions/proc-tap?logo=python&logoColor=white)](https://pypi.org/project/proc-tap/)
+[![Downloads](https://img.shields.io/pypi/dm/proc-tap?logo=pypi&logoColor=white)](https://pypi.org/project/proc-tap/)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux*%20%7C%20macOS*-blue)](https://github.com/m96-chan/ProcTap)
+
+[![Build wheels](https://github.com/m96-chan/ProcTap/actions/workflows/build-wheels.yml/badge.svg)](https://github.com/m96-chan/ProcTap/actions/workflows/build-wheels.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![GitHub stars](https://img.shields.io/github/stars/m96-chan/ProcTap?style=social)](https://github.com/m96-chan/ProcTap/stargazers)
+
+---
+
+ProcTap is a Python library for per-process audio capture with platform-specific backends.
+
+**Capture audio from a specific process only** — without system sounds or other app audio mixed in.
+Ideal for VRChat, games, DAWs, browsers, and AI audio analysis pipelines.
+
+### Platform Support
+
+| Platform | Status | Backend | Notes |
+|----------|--------|---------|-------|
+| **Windows** | ✅ **Fully Supported** | WASAPI (C++ native) | Windows 10/11 (20H1+) |
+| **Linux** | 🧪 **Experimental** | PulseAudio/PipeWire | Basic support, sink monitor capture |
+| **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>
+
+</div>
+
+---
+
+## 🚀 Features
+
+- 🎧 **Capture audio from a single target process**
+  (VRChat, games, browsers, Discord, DAWs, streaming tools, etc.)
+
+- 🌍 **Cross-platform architecture**
+  → Windows (fully supported) | Linux (experimental) | macOS (experimental, 14.4+)
+
+- ⚡ **Platform-optimized backends**
+  → Windows: ActivateAudioInterfaceAsync (modern WASAPI)
+  → Linux: PulseAudio/PipeWire (experimental)
+  → macOS: Core Audio Process Tap API (macOS 14.4+)
+
+- 🧵 **Low-latency, thread-safe audio engine**
+  → 44.1 kHz / stereo / 16-bit PCM format (Windows)
+
+- 🐍 **Python-friendly high-level API**
+  - Callback-based streaming
+  - Async generator streaming (`async for`)
+
+- 🔌 **Native extensions for high-performance**
+  → C++ extension on Windows for optimal throughput
+
+---
+
+## 📦 Installation
+
+**From PyPI**:
+
+```bash
+pip install proc-tap
+```
+
+**Platform-specific dependencies are automatically installed:**
+- Windows: No additional dependencies
+- Linux: `pulsectl` is automatically installed, but you also need system packages:
+  ```bash
+  # Ubuntu/Debian
+  sudo apt-get install pulseaudio-utils
+
+  # Fedora/RHEL
+  sudo dnf install pulseaudio-utils
+  ```
+
+📚 **[Read the Full Documentation](https://m96-chan.github.io/ProcTap/)** for detailed guides and API reference.
+
+**From TestPyPI** (for testing pre-releases):
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ proctap
+```
+
+**From Source**:
+
+```bash
+git clone https://github.com/m96-chan/ProcTap
+cd ProcTap
+pip install -e .
+```
+
+---
+
+## 🛠 Requirements
+
+**Windows (Fully Supported):**
+- Windows 10 / 11 (20H1 or later)
+- Python 3.10+
+- WASAPI support
+- **No admin privileges required**
+
+**Linux (Experimental):**
+- Linux with PulseAudio or PipeWire (with pulseaudio-compat)
+- 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)
+
+**macOS (Experimental):**
+- macOS 14.4 (Sonoma) or later
+- Python 3.10+
+- Swift CLI helper binary (proctap-macos)
+- Audio capture permission
+- ⚠️ **EXPERIMENTAL:** Core Audio Process Tap API support implemented
+- ⚠️ **REQUIREMENT:** Requires macOS 14.4+ for Process Tap API
+
+---
+
+## 🧰 Basic Usage (Callback API)
+
+```python
+from proctap import ProcTap, StreamConfig
+
+def on_chunk(pcm: bytes, frames: int):
+    print(f"Received {len(pcm)} bytes ({frames} frames)")
+
+pid = 12345  # Target process ID
+
+tap = ProcTap(pid, StreamConfig(), on_data=on_chunk)
+tap.start()
+
+input("Recording... Press Enter to stop.\n")
+
+tap.close()
+```
+
+---
+
+## 🔁 Async Usage (Async Generator)
+
+```python
+import asyncio
+from proctap import ProcTap
+
+async def main():
+    tap = ProcTap(pid=12345)
+    tap.start()
+
+    async for chunk in tap.iter_chunks():
+        print(f"PCM chunk size: {len(chunk)} bytes")
+
+asyncio.run(main())
+```
+
+---
+
+## 📄 API Overview
+
+### `class ProcTap`
+
+**Control Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Start WASAPI per-process capture |
+| `stop()` | Stop capture |
+| `close()` | Release native resources |
+
+**Data Access:**
+
+| Method | Description |
+|--------|-------------|
+| `iter_chunks()` | Async generator yielding PCM chunks |
+| `read(timeout=1.0)` | Synchronous: read one chunk (blocking) |
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `is_running` | bool | Check if capture is active |
+| `pid` | int | Get target process ID |
+| `config` | StreamConfig | Get stream configuration |
+
+**Utility Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `set_callback(callback)` | Change or remove audio callback |
+| `get_format()` | Get audio format info (dict) |
+
+### Audio Format
+
+**Note:** The native extension uses a **fixed audio format** (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) |
+
+The `StreamConfig` class exists for API compatibility but does not change the native backend format.
+
+---
+
+## 🎯 Use Cases
+
+- 🎮 Record audio from one game only
+- 🕶 Capture VRChat audio cleanly (without system sounds)
+- 🎙 Feed high-SNR audio into AI recognition models
+- 📹 Alternative to OBS "Application Audio Capture"
+- 🎧 Capture DAW/app playback for analysis tools
+
+---
+
+## 📚 Example: Save to WAV
+
+```python
+from proctap import ProcTap
+import wave
+
+pid = 12345
+
+wav = wave.open("output.wav", "wb")
+wav.setnchannels(2)
+wav.setsampwidth(2)  # 16-bit PCM
+wav.setframerate(44100)  # Native format is 44.1 kHz
+
+def on_data(pcm, frames):
+    wav.writeframes(pcm)
+
+with ProcTap(pid, on_data=on_data):
+    input("Recording... Press Enter to stop.\n")
+
+wav.close()
+```
+
+---
+
+## 📚 Example: Synchronous Read API
+
+```python
+from proctap import ProcTap
+
+tap = ProcTap(pid=12345)
+tap.start()
+
+try:
+    while True:
+        chunk = tap.read(timeout=1.0)  # Blocking read
+        if chunk:
+            print(f"Got {len(chunk)} bytes")
+            # Process audio data...
+        else:
+            print("Timeout, no data")
+except KeyboardInterrupt:
+    pass
+finally:
+    tap.close()
+```
+
+---
+
+## 🐧 Linux Example
+
+```python
+from proctap import ProcessAudioTap, StreamConfig
+import wave
+
+pid = 12345  # Your target process ID
+
+# Create WAV file
+wav = wave.open("linux_capture.wav", "wb")
+wav.setnchannels(2)
+wav.setsampwidth(2)
+wav.setframerate(44100)
+
+def on_data(pcm, frames):
+    wav.writeframes(pcm)
+
+# Create stream config (Linux backend respects these settings)
+config = StreamConfig(sample_rate=44100, channels=2)
+
+try:
+    with ProcessAudioTap(pid, config=config, on_data=on_data):
+        print("⚠️  Make sure the process is actively playing audio!")
+        input("Recording... Press Enter to stop.\n")
+finally:
+    wav.close()
+```
+
+**Linux-specific requirements:**
+- Install system package: `sudo apt-get install pulseaudio-utils` (provides `parec` command)
+- Python dependency `pulsectl` is automatically installed with `pip install proc-tap`
+- The target process must be actively playing audio
+- See [examples/linux_basic.py](examples/linux_basic.py) for a complete example
+
+---
+
+## 🍎 macOS Example
+
+```python
+from proctap import ProcessAudioTap, StreamConfig
+import wave
+
+pid = 12345  # Your target process ID
+
+# Create WAV file
+wav = wave.open("macos_capture.wav", "wb")
+wav.setnchannels(2)
+wav.setsampwidth(2)
+wav.setframerate(48000)  # macOS backend default is 48 kHz
+
+def on_data(pcm, frames):
+    wav.writeframes(pcm)
+
+# Create stream config (macOS backend respects these settings)
+config = StreamConfig(sample_rate=48000, channels=2)
+
+try:
+    with ProcessAudioTap(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")
+finally:
+    wav.close()
+```
+
+**macOS-specific requirements:**
+- macOS 14.4 (Sonoma) or later
+- Swift CLI helper binary (proctap-macos) - automatically built during installation if Swift toolchain available
+- Audio capture permission - macOS will prompt on first run
+- The target process must be actively playing audio
+- See [examples/macos_basic.py](examples/macos_basic.py) for a complete example
+
+**Building the Swift helper manually:**
+```bash
+cd swift/proctap-macos
+swift build -c release
+cp .build/release/proctap-macos ../../src/proctap/bin/
+```
+
+---
+
+## 🏗 Build From Source
+
+```bash
+git clone https://github.com/m96-chan/ProcTap
+cd ProcTap
+pip install -e .
+```
+
+**Windows Build Requirements:**
+- Visual Studio Build Tools
+- Windows SDK
+- CMake (if you modularize the C++ code)
+
+**Linux/macOS:**
+- No C++ compiler required (pure Python)
+- Note: Backends are not yet functional on these platforms
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! We have structured issue templates to help guide your contributions:
+
+- 🐛 [**Bug Report**](../../issues/new?template=bug_report.yml) - Report bugs or unexpected behavior
+- ✨ [**Feature Request**](../../issues/new?template=feature_request.yml) - Suggest new features or enhancements
+- ⚡ [**Performance Issue**](../../issues/new?template=performance.yml) - Report performance problems or optimizations
+- 🔧 [**Type Hints / Async**](../../issues/new?template=type_hints_async.yml) - Improve type annotations or async functionality
+- 📚 [**Documentation**](../../issues/new?template=documentation.yml) - Improve docs, examples, or guides
+
+**Special Interest:**
+- PRs from WASAPI/C++ experts are especially appreciated
+- **Linux backend improvements** (PulseAudio/PipeWire per-app isolation)
+- **macOS backend testing** (Core Audio Process Tap on macOS 14.4+)
+- Cross-platform testing and compatibility
+- Performance profiling and optimization
+
+---
+
+## 📄 License
+
+```
+MIT License
+```
+
+---
+
+## 👤 Author
+
+**m96-chan**  
+Windows Audio / VRChat Tools / Python / C++  
+https://github.com/m96-chan
+

proc_tap-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+proc_tap-0.2.0.dist-info/licenses/LICENSE,sha256=FiyqJ_4TNSUs7HHCiqXCutVSrbJfsZdPXv9NKA5MVeM,1091
+proctap/__init__.py,sha256=wK06NgXN8ruwGLjMd3WrkcHi34jyGWzqG7QUE8Gr7Pk,376
+proctap/_native.pyi,sha256=hGjzU9yBw2Iq0Vi4jH0-vUi9p0-0-SXDgYggIwpzgXU,1986
+proctap/core.py,sha256=FGGgv_GvP0qnyOox2nRrZXpLU_zecHu6NeJT65eLK14,7003
+proctap/backends/__init__.py,sha256=xsd1W0GqYeOxGK8sFIOoQ4kRv9Pac3Gyf-vpVmEIgeM,1921
+proctap/backends/base.py,sha256=uXVHkHXCOnSJeqfkGdYLZjTyUKIbnXDXwvuUGDa3MM8,1832
+proctap/backends/linux.py,sha256=TfCiycX3ZR16pC-b9UyCQhxBpoWsBi65OZSiyihfm4E,16756
+proctap/backends/macos.py,sha256=-zcBwgcb573icfSptTCym6QXRTg8L2y1BrYC7WInhQk,11524
+proctap/backends/windows.py,sha256=av54ybDlmw98_vU5tChh9BaQmRCtHSlt-ojMnByT5R0,2401
+proctap/contrib/__init__.py,sha256=bOWsaQpMCFzTjFSbeGwMsU6sZTIzv6tytzIKIPMmvC8,371
+proctap/contrib/discord_source.py,sha256=ke7tf1Pno6UWcP-2RlOFFlvcBzM2PQz5CmkgIRtarQI,12130
+proc_tap-0.2.0.dist-info/METADATA,sha256=gCl8b3amKNKz39E5hXl59Cwfl3LTyPwj4StfTbpWpOU,12997
+proc_tap-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+proc_tap-0.2.0.dist-info/top_level.txt,sha256=kVtWrrRDOidR8WST84nlggk_gaKSGlrlgIdgezwbJw0,8
+proc_tap-0.2.0.dist-info/RECORD,,

proc_tap-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

proc_tap-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yusuke Harada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proc_tap-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+proctap

proctap/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("proc-tap")
+except PackageNotFoundError:
+    # 開発中の editable install やビルド前など
+    __version__ = "0.0.0"
+
+from .core import ProcessAudioTap, StreamConfig
+
+__all__ = ["ProcessAudioTap", "StreamConfig", "__version__"]

proctap/_native.pyi

@@ -0,0 +1,83 @@
+"""Type stubs for _native C++ extension module."""
+
+from typing import Optional
+
+class ProcessLoopback:
+    """
+    Native C++ implementation of WASAPI process-specific audio capture.
+
+    Uses ActivateAudioInterfaceAsync for per-process loopback recording
+    on Windows 10 20H1+ / Windows 11.
+    """
+
+    def __init__(self, process_id: int) -> None:
+        """
+        Initialize ProcessLoopback for a specific process.
+
+        Args:
+            process_id: Target process ID to capture audio from
+
+        Raises:
+            RuntimeError: If initialization fails
+        """
+        ...
+
+    def start(self) -> None:
+        """
+        Start audio capture.
+
+        Raises:
+            RuntimeError: If capture fails to start
+        """
+        ...
+
+    def stop(self) -> None:
+        """
+        Stop audio capture.
+
+        Raises:
+            RuntimeError: If capture fails to stop
+        """
+        ...
+
+    def read(self) -> Optional[bytes]:
+        """
+        Read captured audio data.
+
+        Returns:
+            PCM audio data as bytes, or None if no data is available
+
+        Note:
+            Returns raw PCM data in the format specified by get_format()
+        """
+        ...
+
+    def get_format(self) -> dict[str, int]:
+        """
+        Get audio format information.
+
+        Returns:
+            Dictionary with keys:
+            - 'sample_rate': Sample rate in Hz (e.g., 48000)
+            - 'channels': Number of channels (e.g., 2 for stereo)
+            - 'bits_per_sample': Bits per sample (e.g., 16)
+        """
+        ...
+
+    def is_process_specific(self) -> bool:
+        """
+        Check if process-specific capture is active.
+
+        Returns:
+            True if capturing from specific process, False if system-wide fallback
+        """
+        ...
+
+    def get_last_error(self) -> str:
+        """
+        Get the last error message.
+
+        Returns:
+            Error message string, or empty string if no error
+        """
+        ...

proctap/backends/__init__.py

@@ -0,0 +1,71 @@
+"""
+Backend selection module for ProcTap.
+
+Automatically selects the appropriate audio capture backend based on the
+current operating system.
+"""
+
+from __future__ import annotations
+
+import sys
+import platform
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import AudioBackend
+
+
+def get_backend(
+    pid: int,
+    sample_rate: int = 44100,
+    channels: int = 2,
+    sample_width: int = 2,
+) -> "AudioBackend":
+    """
+    Get the appropriate audio capture backend for the current platform.
+
+    Args:
+        pid: Process ID to capture audio from
+        sample_rate: Sample rate in Hz (default: 44100)
+        channels: Number of channels (default: 2 for stereo)
+        sample_width: Bytes per sample (default: 2 for 16-bit)
+
+    Returns:
+        Platform-specific AudioBackend implementation
+
+    Raises:
+        NotImplementedError: If the current platform is not supported
+        ImportError: If the backend for the current platform cannot be loaded
+
+    Note:
+        Windows backend uses fixed format (44100Hz, 2ch, 16-bit) and ignores
+        sample_rate, channels, and sample_width parameters.
+    """
+    system = platform.system()
+
+    if system == "Windows":
+        from .windows import WindowsBackend
+        # Windows backend uses fixed format from C++ extension
+        return WindowsBackend(pid)
+
+    elif system == "Linux":
+        from .linux import LinuxBackend
+        return LinuxBackend(
+            pid=pid,
+            sample_rate=sample_rate,
+            channels=channels,
+            sample_width=sample_width,
+        )
+
+    elif system == "Darwin":  # macOS
+        from .macos import MacOSBackend
+        return MacOSBackend(pid)
+
+    else:
+        raise NotImplementedError(
+            f"Platform '{system}' is not supported. "
+            "Supported platforms: Windows, Linux (in development), macOS (planned)"
+        )
+
+
+__all__ = ["get_backend", "AudioBackend"]