feat: refactor parallel audio processing with improved type hints and modularity

## CHANGES

- Upgrade version from 0.5.3 to 0.6.0
- Remove Python version file (.python-version)
- Modernize type hints using PEP 585 syntax
- Add audio directory to package exclusions
- Refactor parallel processing with helper functions
- Improve code organization with clearer function boundaries
- Add comprehensive docstrings to new functions
- Fix import order for better code readability
- Add "jsonschema" to spell check dictionary

Author: ksylvan

.python-version

@@ -2,18 +2,18 @@
 
 import concurrent.futures
 import logging
-from typing import Any, Optional, Tuple, List
+from typing import Any, Optional
 
 import numpy as np
 
 from binaural_generator.core.data_types import AudioStep, NoiseConfig
 from binaural_generator.core.exceptions import AudioGenerationError, ConfigurationError
 from binaural_generator.core.noise import NoiseFactory, NoiseStrategy
 from binaural_generator.core.tone_generator import (
-    mix_beats_and_noise, # Import the public mixer
     _process_beat_step,
     config_step_to_audio_step,
     generate_tone,
+    mix_beats_and_noise,
 )
 
 logger = logging.getLogger(__name__)
@@ -27,7 +27,7 @@ def generate_step_in_parallel(
     previous_freq: Optional[float],
     *,
     title: str = "Binaural Beat",
-) -> Tuple[int, np.ndarray, np.ndarray, float, float]:
+) -> tuple[int, np.ndarray, np.ndarray, float, float]:
     """Generate audio for a single step, to be used in parallel processing.
 
     This function adapts _process_beat_step for concurrent execution.
@@ -97,7 +97,7 @@ def _submit_tone_generation_tasks(
     base_freq: float,
     *,
     title: str = "Binaural Beat",
-) -> list[Tuple[int, concurrent.futures.Future, float, float]]:
+) -> list[tuple[int, concurrent.futures.Future, float, float]]:
     """Submit tone generation tasks to the thread pool."""
     futures_context = []
     for idx, audio_step in enumerate(audio_steps, start=1):
@@ -111,7 +111,7 @@ def _submit_noise_task(
     executor: concurrent.futures.ThreadPoolExecutor,
     noise_config: NoiseConfig,
     total_num_samples: int,
-) -> Optional[Tuple[concurrent.futures.Future, NoiseStrategy]]:
+) -> Optional[tuple[concurrent.futures.Future, NoiseStrategy]]:
     """Submits the noise generation task if needed."""
     if (
         noise_config.type == "none"
@@ -137,9 +137,9 @@ def _submit_noise_task(
 
 def _collect_beat_results(
     beat_futures_with_context: list[
-        Tuple[int, concurrent.futures.Future, float, float]
+        tuple[int, concurrent.futures.Future, float, float]
     ],
-) -> list[Tuple[int, np.ndarray, np.ndarray, float, float]]:
+) -> list[tuple[int, np.ndarray, np.ndarray, float, float]]:
     """Collect results from beat futures, wait for completion, sort by index."""
     results = []
     future_to_context = {
@@ -162,7 +162,7 @@ def _collect_beat_results(
 
 
 def _collect_noise_result(
-    noise_task: Optional[Tuple[concurrent.futures.Future, NoiseStrategy]],
+    noise_task: Optional[tuple[concurrent.futures.Future, NoiseStrategy]],
     noise_config: NoiseConfig,
 ) -> Optional[np.ndarray]:
     """Waits for and collects the noise generation result if the task was submitted."""
@@ -184,7 +184,7 @@ def _collect_noise_result(
 
 
 def _combine_audio_segments(
-    step_results: list[Tuple[int, np.ndarray, np.ndarray, float, float]],
+    step_results: list[tuple[int, np.ndarray, np.ndarray, float, float]],
 ) -> tuple[np.ndarray, np.ndarray, float]:
     """Combine audio segments into continuous channels."""
     if not step_results:
@@ -207,18 +207,17 @@ def _combine_audio_segments(
     return left_channel, right_channel, total_duration
 
 
-# Removed _mix_noise_if_present as mix_beats_and_noise is now imported and used directly
-
 def _execute_parallel_tasks(
     audio_steps: list[AudioStep],
     noise_config: NoiseConfig,
     sample_rate: int,
     base_freq: float,
     total_num_samples: int,
-    title: str,
-    max_workers: Optional[int],
-) -> Tuple[
-    List[Tuple[int, np.ndarray, np.ndarray, float, float]], Optional[np.ndarray]
+    *,
+    title: str = "Binaural Beat",
+    max_workers: Optional[int] = None,
+) -> tuple[
+    list[tuple[int, np.ndarray, np.ndarray, float, float]], Optional[np.ndarray]
 ]:
     """Executes beat and noise generation tasks in parallel using a thread pool."""
     logger.info("Starting parallel generation of beats and noise...")
@@ -243,16 +242,11 @@ def generate_audio_sequence_parallel(
     *,
     title: str = "Binaural Beat",
     max_workers: Optional[int] = None,
-) -> Tuple[np.ndarray, np.ndarray, float]:
+) -> tuple[np.ndarray, np.ndarray, float]:
     """Generates the complete stereo audio sequence in parallel, including noise."""
-    logger.info("Preparing audio steps for parallel generation...")
-    audio_steps = prepare_audio_steps(steps)
-
-    total_duration = sum(step.duration for step in audio_steps)
-    total_num_samples = int(sample_rate * total_duration)
-    logger.debug(
-        "Total duration: %.2f s, Total samples: %d", total_duration, total_num_samples
-    )
+    # Prepare audio steps and calculate duration
+    duration_info = _prepare_and_calculate_duration(steps, sample_rate)
+    audio_steps, total_duration, total_num_samples = duration_info
 
     # Execute tasks in parallel
     step_results, noise_signal = _execute_parallel_tasks(
@@ -261,11 +255,63 @@ def generate_audio_sequence_parallel(
         sample_rate,
         base_freq,
         total_num_samples,
-        title,
-        max_workers,
+        title=title,
+        max_workers=max_workers,
+    )
+
+    # Process audio segments
+    left_final, right_final = _process_audio_segments(
+        step_results, noise_signal, noise_config, total_duration
     )
 
-    # Combine and Mix Sequentially
+    return left_final, right_final, total_duration
+
+
+def _prepare_and_calculate_duration(
+    steps: list[dict[str, Any]], sample_rate: int
+) -> tuple[list[AudioStep], float, int]:
+    """Prepare audio steps and calculate total duration.
+
+    Args:
+        steps: List of step configuration dictionaries
+        sample_rate: Audio sample rate in Hz
+
+    Returns:
+        tuple containing:
+        - List of prepared AudioStep objects
+        - Total duration in seconds
+        - Total number of samples
+    """
+    logger.info("Preparing audio steps for parallel generation...")
+    audio_steps = prepare_audio_steps(steps)
+
+    total_duration = sum(step.duration for step in audio_steps)
+    total_num_samples = int(sample_rate * total_duration)
+    logger.debug(
+        "Total duration: %.2f s, Total samples: %d", total_duration, total_num_samples
+    )
+
+    return audio_steps, total_duration, total_num_samples
+
+
+def _process_audio_segments(
+    step_results: list[tuple[int, np.ndarray, np.ndarray, float, float]],
+    noise_signal: Optional[np.ndarray],
+    noise_config: NoiseConfig,
+    total_duration: float,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Process audio segments by combining and mixing with noise if needed.
+
+    Args:
+        step_results: List of step result tuples
+        noise_signal: Optional noise signal to mix
+        noise_config: Noise configuration parameters
+        total_duration: Total duration in seconds (for validation)
+
+    Returns:
+        tuple of left and right channel arrays
+    """
+    # Combine beat segments
     left_beats, right_beats, combined_duration = _combine_audio_segments(step_results)
 
     # Verify combined duration (logging only)
@@ -276,6 +322,27 @@ def generate_audio_sequence_parallel(
             combined_duration,
         )
 
+    # Apply final processing
+    return _apply_final_processing(left_beats, right_beats, noise_signal, noise_config)
+
+
+def _apply_final_processing(
+    left_beats: np.ndarray,
+    right_beats: np.ndarray,
+    noise_signal: Optional[np.ndarray],
+    noise_config: NoiseConfig,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Apply final processing steps to the audio channels.
+
+    Args:
+        left_beats: Left channel beat data
+        right_beats: Right channel beat data
+        noise_signal: Optional noise signal to mix
+        noise_config: Noise configuration
+
+    Returns:
+        tuple of final left and right channels
+    """
     # Mix noise if applicable
     if noise_signal is not None and noise_config.amplitude > 0:
         logger.info("Mixing '%s' noise with beat segments...", noise_config.type)
@@ -293,4 +360,4 @@ def generate_audio_sequence_parallel(
     left_final = left_final.astype(np.float64)
     right_final = right_final.astype(np.float64)
 
-    return left_final, right_final, total_duration # Use initial total_duration
+    return left_final, right_final

binaural_generator/core/parallel.py

@@ -35,6 +35,7 @@
         "ipython",
         "isort",
         "Jirakittayakorn",
+        "jsonschema",
         "Kraus",
         "levelname",
         "mccabe",

cspell.json

@@ -1,6 +1,6 @@
 [project]
 name = "binaural-generator"
-version = "0.5.3"
+version = "0.6.0"
 description = "Generate binaural beat audio with background noise for brainwave entrainment"
 authors = [{ name = "Kayvan Sylvan", email = "kayvan@sylvan.com" }]
 license = "MIT"
@@ -45,6 +45,9 @@ dev = [
     "twine>=6.1.0",
 ]
 
+[tool.setuptools.packages.find]
+exclude = ["audio"]
+
 [tool.setuptools.package-data]
 binaural_generator = ["scripts/*"]