Readability: Magic numbers scattered throughout codebase

[m96-chan]

Summary

Magic numbers are used throughout the codebase without explanation or named constants.

Locations and Examples

Audio format constants

# converter.py:252 - What is 32768.0?
audio = np.frombuffer(pcm_bytes, dtype=np.int16).astype(np.float32) / 32768.0

# converter.py:271 - What is 8388608.0?
audio = audio_int32.astype(np.float32) / 8388608.0  # 2^23

While the comment explains 2^23, named constants would be clearer.

Buffer sizes

# linux.py:204 - Why 50? What does it represent?
self._audio_queue: queue.Queue[bytes] = queue.Queue(maxsize=50)  # ~500ms buffer

# macos_screencapture.py:144 - Why 100?
self._audio_queue: queue.Queue = queue.Queue(maxsize=100)

Timeouts

# core.py:98 - Why 1.0 second?
self._thread.join(timeout=1.0)

# pipewire_native.py:290 - Why 10 seconds?
hr = pHandler->Wait(10000);

# pipewire_native.py:961 - Why 1000ms default?
def find_nodes_by_pid(self, pid: int, timeout_ms: int = 1000)

Format detection thresholds

# converter.py:155 - Why 400 bytes?
if len(pcm_bytes) < 400:  # Need at least 100 samples for reliable detection

# converter.py:184 - Why 100?
if int16_max > 100:  # Has significant signal (>100 to avoid false positives)

Impact

• Harder to understand the code's intent
• Difficult to tune parameters
• Risk of inconsistent values for same concepts

Suggested Fix

Define named constants at module or class level:

# Audio format constants
INT16_MAX = 32768
INT24_MAX = 8388608  # 2^23
FLOAT32_CLIP_RANGE = 1.0

# Buffer constants
DEFAULT_QUEUE_DEPTH_FRAMES = 50  # ~500ms at 10ms chunks
MIN_FORMAT_DETECTION_SAMPLES = 100
FORMAT_DETECTION_SIGNAL_THRESHOLD = 100

# Timeout constants (seconds)
THREAD_JOIN_TIMEOUT = 1.0
PIPEWIRE_ACTIVATION_TIMEOUT = 10.0
NODE_DISCOVERY_TIMEOUT = 1.0

Labels

readability, enhancement