---
# HoloWave
## Overview
**HoloWave** is a modern, thread-safe audio playback manager for Python applications.
It provides robust, low-latency sound signaling, channel management, and cross-platform fallbacks for automation, agent systems, and productivity tools.
**Highlights:**
* **Low-latency sound playback:** Instantly play any supported audio file with minimal delay.
* **Thread-safe singleton:** Designed for multi-threaded, interactive, or automated applications.
* **Custom sound mapping:** Associate sounds with keys or events for rapid notification and feedback.
* **Automatic cross-platform fallback:** Produces a system beep if audio hardware or files are unavailable.
* **Flexible channel management:** Control mixer channels, output routing, and concurrency with ease.
---
## Why HoloWave?
Standard sound modules are often limited to blocking playback, lack robust error handling, or require boilerplate for channel management.
**HoloWave** solves these problems by:
* Providing a **centralized, extensible interface** for all sound playback.
* Robust error handling and fallback signaling on any OS.
* Supporting channel-based playback for overlapping or grouped sounds.
* Ensuring safe operation in multi-threaded or interactive environments.
---
## Key Features
* **Simple Sound Playback:**
Play any loaded audio file by key, with non-blocking channel control.
* **Cross-Platform Support:**
Uses `pygame` for playback, with built-in system beep fallback.
* **Custom Sound Mapping:**
Map sound files to any integer or string keys for quick event-driven playback.
* **Thread-Safe Singleton:**
Safe to use across threads or in long-running service applications.
* **Robust Error Handling:**
Handles missing files, mixer errors, and hardware issues gracefully.
---
## How It Works
1. **Instantiate HoloWave** in your Python application.
2. **Map sounds to keys or events** in your app logic.
3. **Trigger playback** by calling `getSound(key)` from any thread or event handler.
4. **Automatically falls back** to system beep if playback fails.
---
## FAQ
**Q: Does HoloWave require a specific folder or class naming?**
A: No. Organize your project and sound files as you see fit.
**Q: Can I use HoloWave for overlapping or concurrent sounds?**
A: Yes. Channel management allows for multiple simultaneous sounds.
**Q: Is HoloWave thread-safe and production-ready?**
A: Yes. The singleton implementation and locking ensure safe use in all environments.
---
## Code Examples
You can find code examples on my [GitHub repository](https://github.com/TristanMcBrideSr/TechBook).
---
## License
This project is licensed under the [Apache License, Version 2.0](LICENSE).
Copyright 2025 Tristan McBride Sr.
---
## Acknowledgments
Project by:
- Tristan McBride Sr.
- Sybil
Raw data
{
"_id": null,
"home_page": null,
"name": "HoloWave",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "\"Tristan McBride Sr.\" <142635792+TristanMcBrideSr@users.noreply.github.com>",
"keywords": "AI, Agents, Speech Recognition, Productivity, Automation",
"author": "Tristan McBride Sr.",
"author_email": "\"Tristan McBride Sr.\" <142635792+TristanMcBrideSr@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/64/b9/f86c87d453e8325d481b7047a21c6f4ed4e476f210a73611184af4c971d3/holowave-0.1.0.tar.gz",
"platform": null,
"description": "\ufeff\r\n---\r\n\r\n# HoloWave\r\n\r\n## Overview\r\n\r\n**HoloWave** is a modern, thread-safe audio playback manager for Python applications.\r\nIt provides robust, low-latency sound signaling, channel management, and cross-platform fallbacks for automation, agent systems, and productivity tools.\r\n\r\n**Highlights:**\r\n\r\n* **Low-latency sound playback:** Instantly play any supported audio file with minimal delay.\r\n* **Thread-safe singleton:** Designed for multi-threaded, interactive, or automated applications.\r\n* **Custom sound mapping:** Associate sounds with keys or events for rapid notification and feedback.\r\n* **Automatic cross-platform fallback:** Produces a system beep if audio hardware or files are unavailable.\r\n* **Flexible channel management:** Control mixer channels, output routing, and concurrency with ease.\r\n\r\n---\r\n\r\n## Why HoloWave?\r\n\r\nStandard sound modules are often limited to blocking playback, lack robust error handling, or require boilerplate for channel management.\r\n\r\n**HoloWave** solves these problems by:\r\n\r\n* Providing a **centralized, extensible interface** for all sound playback.\r\n* Robust error handling and fallback signaling on any OS.\r\n* Supporting channel-based playback for overlapping or grouped sounds.\r\n* Ensuring safe operation in multi-threaded or interactive environments.\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n* **Simple Sound Playback:**\r\n Play any loaded audio file by key, with non-blocking channel control.\r\n\r\n* **Cross-Platform Support:**\r\n Uses `pygame` for playback, with built-in system beep fallback.\r\n\r\n* **Custom Sound Mapping:**\r\n Map sound files to any integer or string keys for quick event-driven playback.\r\n\r\n* **Thread-Safe Singleton:**\r\n Safe to use across threads or in long-running service applications.\r\n\r\n* **Robust Error Handling:**\r\n Handles missing files, mixer errors, and hardware issues gracefully.\r\n\r\n---\r\n\r\n## How It Works\r\n\r\n1. **Instantiate HoloWave** in your Python application.\r\n2. **Map sounds to keys or events** in your app logic.\r\n3. **Trigger playback** by calling `getSound(key)` from any thread or event handler.\r\n4. **Automatically falls back** to system beep if playback fails.\r\n\r\n---\r\n\r\n## FAQ\r\n\r\n**Q: Does HoloWave require a specific folder or class naming?**\r\nA: No. Organize your project and sound files as you see fit.\r\n\r\n**Q: Can I use HoloWave for overlapping or concurrent sounds?**\r\nA: Yes. Channel management allows for multiple simultaneous sounds.\r\n\r\n**Q: Is HoloWave thread-safe and production-ready?**\r\nA: Yes. The singleton implementation and locking ensure safe use in all environments.\r\n\r\n---\r\n\r\n## Code Examples\r\n\r\nYou can find code examples on my [GitHub repository](https://github.com/TristanMcBrideSr/TechBook).\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the [Apache License, Version 2.0](LICENSE).\r\nCopyright 2025 Tristan McBride Sr.\r\n\r\n---\r\n\r\n## Acknowledgments\r\n\r\nProject by:\r\n- Tristan McBride Sr.\r\n- Sybil\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Modern Sound manager for modern AI-driven applications.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/TristanMcBrideSr"
},
"split_keywords": [
"ai",
" agents",
" speech recognition",
" productivity",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25ee101db4b7be83bb1bf6d232e0302b4ce31e202492a7563f3b03271376e5a7",
"md5": "25aa61500f748806478f129520a7eee3",
"sha256": "bbc2408f45bcb49130fdcbf8ba064b20ed26f2423baf05630949d719219b6d43"
},
"downloads": -1,
"filename": "holowave-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25aa61500f748806478f129520a7eee3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 4055,
"upload_time": "2025-08-04T03:29:32",
"upload_time_iso_8601": "2025-08-04T03:29:32.164211Z",
"url": "https://files.pythonhosted.org/packages/25/ee/101db4b7be83bb1bf6d232e0302b4ce31e202492a7563f3b03271376e5a7/holowave-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64b9f86c87d453e8325d481b7047a21c6f4ed4e476f210a73611184af4c971d3",
"md5": "83a0a8dce3fd7f75be461fabd64d6e38",
"sha256": "69b8ce4360afdcd3180630df9d7ec7df5e28c9befd9307af38902ef28c0be018"
},
"downloads": -1,
"filename": "holowave-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "83a0a8dce3fd7f75be461fabd64d6e38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4218,
"upload_time": "2025-08-04T03:29:33",
"upload_time_iso_8601": "2025-08-04T03:29:33.373280Z",
"url": "https://files.pythonhosted.org/packages/64/b9/f86c87d453e8325d481b7047a21c6f4ed4e476f210a73611184af4c971d3/holowave-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 03:29:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "holowave"
}
JSON