fix: prevent chunk overwrite with custom output names, clarify demucs defaults (#270)

Fix chunking bug where custom_output_names passed to _separate_file caused
chunks to overwrite each other (fixes #259). Custom names are now only applied
to the final merged output. Adds regression test with multi-chunk + multi-stem
scenario that verifies _separate_file is called without custom names.

Also clarifies demucs_params segment_size documentation: "Default" maps to 40
for older Demucs models and 10 for Demucs v4/htdemucs.

Incorporates work from PR #260 (@Kulin-Soni) and PR #264 (@Madduri-Ganesh)
with additional test coverage.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: beveradb

README.md

@@ -618,7 +618,7 @@ You can also rename specific stems:
 - **`use_autocast`:** (Optional) Flag to use PyTorch autocast for faster inference. Do not use for CPU inference. `Default: False`
 - **`mdx_params`:** (Optional) MDX Architecture Specific Attributes & Defaults. `Default: {"hop_length": 1024, "segment_size": 256, "overlap": 0.25, "batch_size": 1, "enable_denoise": False}`
 - **`vr_params`:** (Optional) VR Architecture Specific Attributes & Defaults. `Default: {"batch_size": 1, "window_size": 512, "aggression": 5, "enable_tta": False, "enable_post_process": False, "post_process_threshold": 0.2, "high_end_process": False}`
-- **`demucs_params`:** (Optional) Demucs Architecture Specific Attributes & Defaults. `Default: {"segment_size": "Default", "shifts": 2, "overlap": 0.25, "segments_enabled": True}`
+- **`demucs_params`:** (Optional) Demucs Architecture Specific Attributes & Defaults. `Default: {"segment_size": "Default", "shifts": 2, "overlap": 0.25, "segments_enabled": True}` _(Note: `segment_size` "Default" uses the model's internal default, typically 40 for older Demucs models and 10 for Demucs v4/htdemucs)_
 - **`mdxc_params`:** (Optional) MDXC Architecture Specific Attributes & Defaults. `Default: {"segment_size": 256, "override_model_segment_size": False, "batch_size": 1, "overlap": 8, "pitch_shift": 0}`
 - **`ensemble_algorithm`:** (Optional) Algorithm to use for ensembling multiple models. `Default: 'avg_wave'`
 - **`ensemble_weights`:** (Optional) Weights for each model in the ensemble. `Default: None` (equal weights)

audio_separator/separator/separator.py

@@ -1088,7 +1088,7 @@ def _process_with_chunking(self, audio_file_path, custom_output_names=None):
                     self.model_instance.output_dir = temp_dir
 
                 try:
-                    output_files = self._separate_file(chunk_path, custom_output_names)
+                    output_files = self._separate_file(chunk_path)
 
                     # Dynamically group chunks by stem name
                     for stem_path in output_files:

tests/unit/test_separator_chunking.py

@@ -318,7 +318,7 @@ def test_state_restoration_after_chunking(self, mock_chunker_class):
 
         # Track state changes during _separate_file call
         state_during_processing = {}
-        def track_state(chunk_path, custom_names):
+        def track_state(chunk_path, custom_names=None):
             state_during_processing['chunk_duration'] = separator.chunk_duration
             state_during_processing['output_dir'] = separator.output_dir
             state_during_processing['model_output_dir'] = separator.model_instance.output_dir
@@ -500,8 +500,13 @@ def test_audio_chunker_initialization(self, mock_chunker_class):
         mock_chunker_class.assert_called_once_with(15.0, separator.logger)
 
     @patch('audio_separator.separator.audio_chunking.AudioChunker')
-    def test_custom_output_names_parameter(self, mock_chunker_class):
-        """Test that custom_output_names parameter is handled correctly."""
+    def test_custom_output_names_applied_to_merged_output(self, mock_chunker_class):
+        """Test that custom_output_names are applied to final merged output, not per-chunk.
+
+        Regression test for issue #259: when custom_output_names were passed to
+        _separate_file for each chunk, chunks would get the same custom name and
+        overwrite each other, producing corrupted output.
+        """
         # Setup mock separator
         separator = Mock(spec=Separator)
         separator.logger = self.logger
@@ -511,18 +516,25 @@ def test_custom_output_names_parameter(self, mock_chunker_class):
         separator.model_instance = Mock()
         separator.model_instance.output_dir = self.temp_dir
 
-        # Mock chunker behavior
+        # Mock chunker behavior - multiple chunks to reproduce the overwrite bug
         mock_chunker = Mock()
         mock_chunker_class.return_value = mock_chunker
         mock_chunker.split_audio.return_value = [
             os.path.join(self.temp_dir, "chunk_0000.wav"),
+            os.path.join(self.temp_dir, "chunk_0001.wav"),
+            os.path.join(self.temp_dir, "chunk_0002.wav"),
         ]
 
-        separator._separate_file = Mock(return_value=[
-            os.path.join(self.temp_dir, "chunk_0000_(Vocals).wav"),
+        separator._separate_file = Mock(side_effect=[
+            [os.path.join(self.temp_dir, "chunk_0000_(Vocals).wav"),
+             os.path.join(self.temp_dir, "chunk_0000_(Instrumental).wav")],
+            [os.path.join(self.temp_dir, "chunk_0001_(Vocals).wav"),
+             os.path.join(self.temp_dir, "chunk_0001_(Instrumental).wav")],
+            [os.path.join(self.temp_dir, "chunk_0002_(Vocals).wav"),
+             os.path.join(self.temp_dir, "chunk_0002_(Instrumental).wav")],
         ])
 
-        custom_names = {"Vocals": "my_custom_vocals"}
+        custom_names = {"Vocals": "my_custom_vocals", "Instrumental": "my_custom_instrumental"}
 
         # Import and call the actual method
         from audio_separator.separator.separator import Separator as RealSeparator
@@ -532,9 +544,25 @@ def test_custom_output_names_parameter(self, mock_chunker_class):
             custom_output_names=custom_names
         )
 
-        # Verify custom name was used in output
-        assert len(result) == 1
-        assert "my_custom_vocals" in os.path.basename(result[0])
+        # Verify _separate_file was called WITHOUT custom_output_names for each chunk
+        # This is the core of the fix: chunks must use default naming to avoid overwrites
+        for call_args in separator._separate_file.call_args_list:
+            args, kwargs = call_args
+            assert len(args) == 1, f"_separate_file should be called with only chunk_path, got args: {args}"
+            assert "custom_output_names" not in kwargs, \
+                f"_separate_file should not receive custom_output_names, got kwargs: {kwargs}"
+
+        # Verify custom names were applied to the final merged output
+        assert len(result) == 2
+        output_basenames = [os.path.basename(path) for path in result]
+        assert any("my_custom_instrumental" in name for name in output_basenames)
+        assert any("my_custom_vocals" in name for name in output_basenames)
+
+        # Verify all 3 chunks were processed for each stem
+        assert mock_chunker.merge_chunks.call_count == 2
+        for merge_call in mock_chunker.merge_chunks.call_args_list:
+            chunk_list = merge_call[0][0]
+            assert len(chunk_list) == 3, f"Each stem should merge 3 chunks, got {len(chunk_list)}"
 
 
 class TestSeparatorChunkingEdgeCases: