# AudioMap
[](https://python.org)
[](https://github.com/yourusername/audiomap)
Cross-platform audio device mapping library for macOS, Windows, and Linux with comprehensive device UID support for both input and output audio devices.
## Features
- 🔍 **Cross-platform**: Support for macOS, Windows, and Linux
- 🎤 **Input Device Detection**: Detect microphones, line inputs, and other audio input devices
- 🔊 **Output Device Detection**: Detect speakers, headphones, and other audio output devices
- 🆔 **Device UID Support**: Get unique device identifiers (UIDs) for precise device targeting
- 📝 **Unified API**: Same API interface across all platforms
- 🛠️ **Native Implementation**:
- macOS: Uses CoreAudio API with native UID support
- Windows: Uses pycaw + comtypes with device ID extraction
- Linux: Uses ALSA tools with device identifier mapping
- 🎯 **Lightweight**: Minimal dependencies, high performance
- 📱 **Command Line Tool**: Built-in CLI interface
## Installation
### Basic Installation
```bash
pip install audiomap
```
### Platform-specific Dependencies
**Windows:**
```bash
pip install audiomap[windows]
```
**Development:**
```bash
pip install audiomap[dev]
```
### Platform-specific Dependencies
**Windows users need additional packages:**
```bash
pip install audiomap[windows]
```
**Developer installation:**
```bash
pip install audiomap[dev]
```
## Quick Start
### Basic Usage
```python
from audiomap import list_audio_input_devices, list_audio_output_devices
# List all input devices
input_devices = list_audio_input_devices()
for device in input_devices:
print(f"Input device: {device['name']} (UID: {device['id']})")
# List all output devices
output_devices = list_audio_output_devices()
for device in output_devices:
print(f"Output device: {device['name']} (UID: {device['id']})")
```
### Using Class Interface
```python
from audiomap import AudioDeviceDetector
detector = AudioDeviceDetector()
# Get all devices with UIDs
all_devices = detector.list_all_devices()
print(f"Input devices: {len(all_devices['input'])}")
print(f"Output devices: {len(all_devices['output'])}")
# Display device information including UIDs
for device in all_devices['input']:
print(f"Input: {device['name']} (UID: {device['id']})")
for device in all_devices['output']:
print(f"Output: {device['name']} (UID: {device['id']})")
# Find specific devices by name
macbook_devices = detector.find_device_by_name("MacBook")
for device in macbook_devices:
print(f"Found device: {device['name']} - UID: {device['id']}")
# Get device statistics
stats = detector.get_device_count()
print(f"Total: {stats['total']} audio devices")
```
### Command Line Usage
```bash
# List all devices with UIDs
audiomap
# List input devices only
audiomap --input-only
# List output devices only
audiomap --output-only
# JSON format output with UIDs
audiomap --json
# Find devices containing "MacBook"
audiomap --find "MacBook"
# Show device count only
audiomap --count-only
```
## API Documentation
### Utility Functions
#### `list_audio_input_devices()`
Returns a list of all audio input devices with their unique identifiers.
**Returns:**
- `List[Dict[str, str]]`: Device list, each device contains:
- `id`: Device unique identifier (UID) - platform-specific format
- `name`: Human-readable device name
- `platform`: Platform name ("Windows", "Darwin", "Linux")
#### `list_audio_output_devices()`
Returns a list of all audio output devices with their unique identifiers.
**Returns:**
- `List[Dict[str, str]]`: Device list (same format as above)
### AudioDeviceDetector Class
#### `list_input_devices()`
List all audio input devices.
#### `list_output_devices()`
List all audio output devices.
#### `list_all_devices()`
List all audio devices.
**Returns:**
```python
{
"input": List[Dict[str, str]],
"output": List[Dict[str, str]]
}
```
#### `get_device_count()`
Get device count statistics.
**Returns:**
```python
{
"input": int, # Number of input devices
"output": int, # Number of output devices
"total": int # Total number of devices
}
```
#### `find_device_by_name(name, device_type="both")`
Find devices by name.
**Parameters:**
- `name (str)`: Device name (supports partial matching)
- `device_type (str)`: Device type, options: "input", "output", "both"
## Platform Requirements
### macOS
- No additional dependencies (uses built-in CoreAudio)
- Supports all audio device types
- **UID Format**: CoreAudio device UID (e.g., "BuiltInSpeakers", "AppleUSBAudioEngine:...")
### Windows
- Requires installation: `pip install pycaw comtypes`
- Supports WASAPI devices
- **UID Format**: Windows device ID (e.g., "{0.0.0.00000000}.{12345678-...}")
### Linux
- Requires ALSA tools: `sudo apt-get install alsa-utils`
- Supports ALSA and PulseAudio/PipeWire devices
- **UID Format**: ALSA device name (e.g., "default", "hw:0,0", "pulse")
## Device UID Support
AudioMap provides comprehensive device UID support across all platforms:
### What are Device UIDs?
Device UIDs (Unique Identifiers) are platform-specific strings that uniquely identify audio devices. Unlike device names which can change or be duplicated, UIDs provide a reliable way to target specific audio hardware.
### Platform-Specific UID Implementation
- **macOS**: Uses CoreAudio's native device UID system
- **Windows**: Extracts Windows device IDs through WASAPI
- **Linux**: Uses ALSA device identifiers
### Using UIDs in Your Application
```python
devices = list_audio_input_devices()
for device in devices:
uid = device['id'] # Platform-specific unique identifier
name = device['name'] # Human-readable name
platform = device['platform'] # Platform identifier
print(f"Device: {name}")
print(f"UID: {uid}")
print(f"Platform: {platform}")
```
## Error Handling
```python
from audiomap import AudioDeviceDetector
from audiomap.exceptions import AudioDetectionError, DependencyMissingError
try:
detector = AudioDeviceDetector()
devices = detector.list_input_devices()
except DependencyMissingError as e:
print(f"Missing dependency: {e}")
except AudioDetectionError as e:
print(f"Detection error: {e}")
```
## Output Examples
### macOS Output Example
```
=== Audio Input Devices ===
Found 3 input devices:
1. MacBook Pro Microphone (UID: BuiltInMicrophoneDevice)
2. WH-1000XM6 (UID: 58-18-62-13-51-61:input)
3. BlackHole 2ch (UID: BlackHole2ch_UID)
=== Audio Output Devices ===
Found 4 output devices:
1. MacBook Pro Speakers (UID: BuiltInSpeakerDevice)
2. WH-1000XM6 (UID: 58-18-62-13-51-61:output)
3. BlackHole 2ch (UID: BlackHole2ch_UID)
4. Multi-Output Device (UID: ~:AMS2_StackedOutput:0)
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/yourusername/audiomap.git
cd audiomap
pip install -e .[dev]
```
### Run Tests
```bash
pytest tests/
```
### Build Package
```bash
python -m build
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
Issues and Pull Requests are welcome!
## Changelog
### v1.0.0
- Initial release
- Support for macOS, Windows, and Linux
- Command line tool included
- Complete error handling
Raw data
{
"_id": null,
"home_page": null,
"name": "audiomap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "audio, device, detection, uid, cross-platform, macos, windows, linux, coreaudio, wasapi, alsa",
"author": null,
"author_email": "Andy Lee <mail@andylee.tw>",
"download_url": "https://files.pythonhosted.org/packages/e3/3d/97a65a58a05f89a831adabd2b73d50312731464d07fdf859a6aa3ac8901c/audiomap-1.0.1.tar.gz",
"platform": null,
"description": "# AudioMap\n\n[](https://python.org)\n[](https://github.com/yourusername/audiomap)\n\nCross-platform audio device mapping library for macOS, Windows, and Linux with comprehensive device UID support for both input and output audio devices.\n\n## Features\n\n- \ud83d\udd0d **Cross-platform**: Support for macOS, Windows, and Linux\n- \ud83c\udfa4 **Input Device Detection**: Detect microphones, line inputs, and other audio input devices\n- \ud83d\udd0a **Output Device Detection**: Detect speakers, headphones, and other audio output devices\n- \ud83c\udd94 **Device UID Support**: Get unique device identifiers (UIDs) for precise device targeting\n- \ud83d\udcdd **Unified API**: Same API interface across all platforms\n- \ud83d\udee0\ufe0f **Native Implementation**: \n - macOS: Uses CoreAudio API with native UID support\n - Windows: Uses pycaw + comtypes with device ID extraction\n - Linux: Uses ALSA tools with device identifier mapping\n- \ud83c\udfaf **Lightweight**: Minimal dependencies, high performance\n- \ud83d\udcf1 **Command Line Tool**: Built-in CLI interface\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install audiomap\n```\n\n### Platform-specific Dependencies\n\n**Windows:**\n```bash\npip install audiomap[windows]\n```\n\n**Development:**\n```bash\npip install audiomap[dev]\n```\n\n### Platform-specific Dependencies\n\n**Windows users need additional packages:**\n```bash\npip install audiomap[windows]\n```\n\n**Developer installation:**\n```bash\npip install audiomap[dev]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom audiomap import list_audio_input_devices, list_audio_output_devices\n\n# List all input devices\ninput_devices = list_audio_input_devices()\nfor device in input_devices:\n print(f\"Input device: {device['name']} (UID: {device['id']})\")\n\n# List all output devices\noutput_devices = list_audio_output_devices()\nfor device in output_devices:\n print(f\"Output device: {device['name']} (UID: {device['id']})\")\n```\n\n### Using Class Interface\n\n```python\nfrom audiomap import AudioDeviceDetector\n\ndetector = AudioDeviceDetector()\n\n# Get all devices with UIDs\nall_devices = detector.list_all_devices()\nprint(f\"Input devices: {len(all_devices['input'])}\")\nprint(f\"Output devices: {len(all_devices['output'])}\")\n\n# Display device information including UIDs\nfor device in all_devices['input']:\n print(f\"Input: {device['name']} (UID: {device['id']})\")\n \nfor device in all_devices['output']:\n print(f\"Output: {device['name']} (UID: {device['id']})\")\n\n# Find specific devices by name\nmacbook_devices = detector.find_device_by_name(\"MacBook\")\nfor device in macbook_devices:\n print(f\"Found device: {device['name']} - UID: {device['id']}\")\n\n# Get device statistics\nstats = detector.get_device_count()\nprint(f\"Total: {stats['total']} audio devices\")\n```\n\n### Command Line Usage\n\n```bash\n# List all devices with UIDs\naudiomap\n\n# List input devices only\naudiomap --input-only\n\n# List output devices only\naudiomap --output-only\n\n# JSON format output with UIDs\naudiomap --json\n\n# Find devices containing \"MacBook\"\naudiomap --find \"MacBook\"\n\n# Show device count only\naudiomap --count-only\n```\n\n## API Documentation\n\n### Utility Functions\n\n#### `list_audio_input_devices()`\nReturns a list of all audio input devices with their unique identifiers.\n\n**Returns:**\n- `List[Dict[str, str]]`: Device list, each device contains:\n - `id`: Device unique identifier (UID) - platform-specific format\n - `name`: Human-readable device name\n - `platform`: Platform name (\"Windows\", \"Darwin\", \"Linux\")\n\n#### `list_audio_output_devices()`\nReturns a list of all audio output devices with their unique identifiers.\n\n**Returns:**\n- `List[Dict[str, str]]`: Device list (same format as above)\n\n### AudioDeviceDetector Class\n\n#### `list_input_devices()`\nList all audio input devices.\n\n#### `list_output_devices()`\nList all audio output devices.\n\n#### `list_all_devices()`\nList all audio devices.\n\n**Returns:**\n```python\n{\n \"input\": List[Dict[str, str]],\n \"output\": List[Dict[str, str]]\n}\n```\n\n#### `get_device_count()`\nGet device count statistics.\n\n**Returns:**\n```python\n{\n \"input\": int, # Number of input devices\n \"output\": int, # Number of output devices \n \"total\": int # Total number of devices\n}\n```\n\n#### `find_device_by_name(name, device_type=\"both\")`\nFind devices by name.\n\n**Parameters:**\n- `name (str)`: Device name (supports partial matching)\n- `device_type (str)`: Device type, options: \"input\", \"output\", \"both\"\n\n## Platform Requirements\n\n### macOS\n- No additional dependencies (uses built-in CoreAudio)\n- Supports all audio device types\n- **UID Format**: CoreAudio device UID (e.g., \"BuiltInSpeakers\", \"AppleUSBAudioEngine:...\")\n\n### Windows \n- Requires installation: `pip install pycaw comtypes`\n- Supports WASAPI devices\n- **UID Format**: Windows device ID (e.g., \"{0.0.0.00000000}.{12345678-...}\")\n\n### Linux\n- Requires ALSA tools: `sudo apt-get install alsa-utils`\n- Supports ALSA and PulseAudio/PipeWire devices \n- **UID Format**: ALSA device name (e.g., \"default\", \"hw:0,0\", \"pulse\")\n\n## Device UID Support\n\nAudioMap provides comprehensive device UID support across all platforms:\n\n### What are Device UIDs?\nDevice UIDs (Unique Identifiers) are platform-specific strings that uniquely identify audio devices. Unlike device names which can change or be duplicated, UIDs provide a reliable way to target specific audio hardware.\n\n### Platform-Specific UID Implementation\n- **macOS**: Uses CoreAudio's native device UID system\n- **Windows**: Extracts Windows device IDs through WASAPI\n- **Linux**: Uses ALSA device identifiers\n\n### Using UIDs in Your Application\n```python\ndevices = list_audio_input_devices()\nfor device in devices:\n uid = device['id'] # Platform-specific unique identifier\n name = device['name'] # Human-readable name\n platform = device['platform'] # Platform identifier\n \n print(f\"Device: {name}\")\n print(f\"UID: {uid}\")\n print(f\"Platform: {platform}\")\n```\n\n## Error Handling\n\n```python\nfrom audiomap import AudioDeviceDetector\nfrom audiomap.exceptions import AudioDetectionError, DependencyMissingError\n\ntry:\n detector = AudioDeviceDetector()\n devices = detector.list_input_devices()\nexcept DependencyMissingError as e:\n print(f\"Missing dependency: {e}\")\nexcept AudioDetectionError as e:\n print(f\"Detection error: {e}\")\n```\n\n## Output Examples\n\n### macOS Output Example\n```\n=== Audio Input Devices ===\nFound 3 input devices:\n 1. MacBook Pro Microphone (UID: BuiltInMicrophoneDevice)\n 2. WH-1000XM6 (UID: 58-18-62-13-51-61:input)\n 3. BlackHole 2ch (UID: BlackHole2ch_UID)\n\n=== Audio Output Devices ===\nFound 4 output devices:\n 1. MacBook Pro Speakers (UID: BuiltInSpeakerDevice)\n 2. WH-1000XM6 (UID: 58-18-62-13-51-61:output)\n 3. BlackHole 2ch (UID: BlackHole2ch_UID)\n 4. Multi-Output Device (UID: ~:AMS2_StackedOutput:0)\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yourusername/audiomap.git\ncd audiomap\npip install -e .[dev]\n```\n\n### Run Tests\n\n```bash\npytest tests/\n```\n\n### Build Package\n\n```bash\npython -m build\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nIssues and Pull Requests are welcome!\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Support for macOS, Windows, and Linux\n- Command line tool included\n- Complete error handling\n",
"bugtrack_url": null,
"license": null,
"summary": "Cross-platform audio device mapping with UID support",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/andylee830914/audiomap",
"Issues": "https://github.com/andylee830914/audiomap/issues",
"Repository": "https://github.com/andylee830914/audiomap.git"
},
"split_keywords": [
"audio",
" device",
" detection",
" uid",
" cross-platform",
" macos",
" windows",
" linux",
" coreaudio",
" wasapi",
" alsa"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6242b1047c97141f84524aed4fae1addcf3448db5c4f547a1d5539f1fdc598c1",
"md5": "dd57e8a7ebe35190854dfdcbeaf34dd7",
"sha256": "fd279e7f118ab8ea2e05a7c98ee64018f3853c5b9c131ccce9c8f107656c0c31"
},
"downloads": -1,
"filename": "audiomap-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd57e8a7ebe35190854dfdcbeaf34dd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 12213,
"upload_time": "2025-08-21T17:16:01",
"upload_time_iso_8601": "2025-08-21T17:16:01.315828Z",
"url": "https://files.pythonhosted.org/packages/62/42/b1047c97141f84524aed4fae1addcf3448db5c4f547a1d5539f1fdc598c1/audiomap-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e33d97a65a58a05f89a831adabd2b73d50312731464d07fdf859a6aa3ac8901c",
"md5": "3772d1302516f0f8a552e099679bbac9",
"sha256": "6bb00b7a29f04285f7bc5a2a38b279a3ef6a610f3c725c2c5b426eaefe31ccf2"
},
"downloads": -1,
"filename": "audiomap-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3772d1302516f0f8a552e099679bbac9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 14250,
"upload_time": "2025-08-21T17:16:03",
"upload_time_iso_8601": "2025-08-21T17:16:03.015279Z",
"url": "https://files.pythonhosted.org/packages/e3/3d/97a65a58a05f89a831adabd2b73d50312731464d07fdf859a6aa3ac8901c/audiomap-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 17:16:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andylee830914",
"github_project": "audiomap",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "audiomap"
}
JSON
