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.

License

This project is licensed under the Apache License, Version 2.0. Copyright 2025 Tristan McBride Sr.

Acknowledgments

Project by:

• Tristan McBride Sr.
• Sybil