[Bug]: chunk_duration param causes issue if custom_output_names does not follow the regex.

[Kulin-Soni]

Describe the bug

After setting chunk_duration parameter in the Separator's initialization, there seems to be some issue with how file chunking and merging is handled unless the name follows the regex _\(([^)]+)\) which is from the _process_with_chunking method in Separator class.

In this case, it creates files as test_(stem_0).wav, test_(stem_1).wav... . These all contain the processed version of last chunk.

separator = Separator(
    output_dir="output"
    output_single_stem="Vocals",
    chunk_duration=600,
)
separator.load_model()
separator.separate("source.wav", {"Vocals": "test_vocals"})

The following case works fine:

separator.separate("source.wav", {"Vocals": "test_(foo)"})

I've tested this with instrumental aswell (with and without output_single_stem), and the issue persists.
If this issue is only for me or if am missing something, please let me know.

Expected Behaviour

Creates a single file test_vocal.wav that contains all the chunks combined with full audio.

Have you searched for existing issues? 🔎

• I have searched and found no existing issues.

Screenshots or Videos

No response

Logs

WARNING - separator - Could not extract stem name from test_vocals.wav, using stem_2
INFO - separator - Merging 1 chunks for stem: stem_0
INFO - audio_chunking - Merging 1 chunks into test\test_(stem_0).wav
INFO - audio_chunking - Exporting merged audio (237.5s) to test\test_(stem_0).wav
INFO - separator - Merging 1 chunks for stem: stem_1
INFO - audio_chunking - Merging 1 chunks into test\test_(stem_1).wav
INFO - audio_chunking - Exporting merged audio (237.5s) to test\test_(stem_1).wav
INFO - separator - Merging 1 chunks for stem: stem_2
INFO - audio_chunking - Merging 1 chunks into test\test_(stem_2).wav
INFO - audio_chunking - Exporting merged audio (237.5s) to test\test_(stem_2).wav
INFO - separator - Chunked processing completed. Output files: ['test\\test_(stem_0).wav', 'test\\test_(stem_1).wav', 'test\\test_(stem_2).wav']

System Info

Operating System: Windows 11
Python version: 3.13.2
FFMPEG version: 8.0.1
pydub version: 0.25.1
python-audio-separator version: 0.41.1

Additional Information

I have tested this with other models aswell and they have the same issue.

[coderabbitai]

🔗 Related PRs

#256 - Add file-level chunking for large audio files (fixes #158) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Build a reverse lookup map from sanitized custom filenames to original stem names at the start of _process_with_chunking
• Consult this map when the regex fails to match, before falling back to positional stem_N naming
• This ensures chunks are grouped by their actual stem identity rather than by position, fixing the incorrect merging behavior
• Add targeted unit tests to prevent regression and cover the previously untested code path

Design Choices

Design Choice 1: How should stem names be recovered when custom output names don't contain the `_(StemName)` pattern?

Options Considered:

1. Modify get_stem_output_path to always embed stem name in the filename - breaks user expectation that custom names are used as-is
2. Build a reverse lookup map from sanitized custom names to original stem names before processing chunks
3. Modify _separate_file to return stem metadata alongside paths - requires changes across all architecture separators

Chosen Option: 2

Rationale: Building a reverse lookup map is minimally invasive, changes only _process_with_chunking, and correctly handles the sanitization that get_stem_output_path applies to custom names.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Fix Stem Grouping for Custom Output Names

This phase addresses the root cause by adding a reverse lookup mechanism that maps sanitized custom filenames back to their original stem names, enabling correct chunk grouping when custom output names are provided.

Task 1: Build Reverse Lookup Map in `_process_with_chunking`

Add logic to construct a reverse mapping from sanitized custom names to stem names before the chunk processing loop begins.

• In audio_separator/separator/separator.py, at the start of _process_with_chunking (after temp directory creation), add logic to build a reverse map when custom_output_names is provided
• The map should be structured as {sanitized_name.lower(): original_stem_name} for each entry in custom_output_names
• Use self.model_instance.sanitize_filename() to apply the same sanitization that get_stem_output_path uses, ensuring exact filename matching
• Store this map in a local variable for use in the stem grouping logic

Task 2: Update Stem Extraction Logic to Use Reverse Map

Modify the stem grouping logic to consult the reverse map before falling back to positional stem_N naming.

• In the stem grouping section (around line 971), after the regex match fails, add a lookup against the reverse map
• Extract the base filename (without extension) from the chunk output path and normalize to lowercase
• Check if this base name exists in the reverse map; if so, use the mapped stem name instead of the fallback
• Only fall back to stem_N naming if both the regex fails AND the filename is not found in the reverse map
• This ensures chunks from the same stem are grouped together across all chunk iterations

Task 3: Add Unit Tests for Custom Output Names with Chunking

Add tests that verify correct behavior when custom output names are used with multi-chunk processing.

• In tests/unit/test_separator_chunking.py, add a new test method in TestSeparatorChunkingLogic or TestSeparatorChunkingEdgeCases
• Test scenario: custom_output_names={"Vocals": "my_vocals", "Instrumental": "my_instrumental"} with 2+ chunks
• Mock _separate_file to return files without _(StemName) pattern (e.g., my_vocals.wav, my_instrumental.wav)
• Assert that chunks are correctly grouped by stem name (not stem_0, stem_1)
• Assert that final merged output uses the custom names from custom_output_names
• Follow the existing test pattern using Mock(spec=Separator) and patching AudioChunker

🤖 Prompt for AI agents

This phase fixes the stem grouping bug in `_process_with_chunking` when
`custom_output_names` are used, and adds regression tests to cover the new
behavior.

**Task 1: Build Reverse Lookup Map (`audio_separator/separator/separator.py`)**
- At the start of `_process_with_chunking`, after temp directory creation, add a
conditional block that runs when `custom_output_names` is provided
- Iterate over each `stem_name, custom_name` pair in `custom_output_names`
- For each entry, call `self.model_instance.sanitize_filename(custom_name)` to
get the sanitized version (matching what `get_stem_output_path` produces)
- Build a local dict mapping `sanitized_name.lower()` → `original_stem_name`
- Store this as a local variable (e.g., `custom_name_to_stem`) for use later in
the stem grouping logic

**Task 2: Update Stem Extraction Logic
(`audio_separator/separator/separator.py`, around line 971)**
- In the stem grouping section, after the existing regex `_\(([^)]+)\)` fails to
match a chunk output path:
  - Extract the base filename (without extension) from the chunk output path
  - Normalize it to lowercase
  - Look up the base name in `custom_name_to_stem`
  - If found, use the mapped stem name for grouping
- Only fall back to positional `stem_N` naming if both the regex fails AND the
base name is not found in the reverse map

**Task 3: Add Unit Tests (`tests/unit/test_separator_chunking.py`)**
- Add a new test method to `TestSeparatorChunkingLogic` or
`TestSeparatorChunkingEdgeCases`
- Set up the test with `custom_output_names={"Vocals": "my_vocals",
"Instrumental": "my_instrumental"}` and 2+ chunks
- Mock `_separate_file` to return filenames without the `_(StemName)` pattern
(e.g., `my_vocals.wav`, `my_instrumental.wav`)
- Assert chunks are grouped by stem name (`"Vocals"`, `"Instrumental"`), not
`stem_0`/`stem_1`
- Assert final merged output filenames use the custom names
- Follow the existing pattern using `Mock(spec=Separator)` and patching
`AudioChunker`

Research

The audio separation library uses a chunking pipeline in _process_with_chunking (separator.py) to process large audio files in memory-safe segments. Each chunk is processed via _separate_file, which delegates to model-specific separators inheriting from CommonSeparator. Output filenames are generated by get_stem_output_path in common_separator.py, which produces either a default pattern {base}_({stem})_{model}.{ext} or a custom name {custom_name}.{ext}. The chunking pipeline uses regex to extract stem names from chunk output filenames for grouping, but this regex only matches the default naming pattern, not custom names.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase fixes the stem grouping bug in `_process_with_chunking` when
`custom_output_names` are used, and adds regression tests to cover the new
behavior.

**Task 1: Build Reverse Lookup Map (`audio_separator/separator/separator.py`)**
- At the start of `_process_with_chunking`, after temp directory creation, add a
conditional block that runs when `custom_output_names` is provided
- Iterate over each `stem_name, custom_name` pair in `custom_output_names`
- For each entry, call `self.model_instance.sanitize_filename(custom_name)` to
get the sanitized version (matching what `get_stem_output_path` produces)
- Build a local dict mapping `sanitized_name.lower()` → `original_stem_name`
- Store this as a local variable (e.g., `custom_name_to_stem`) for use later in
the stem grouping logic

**Task 2: Update Stem Extraction Logic
(`audio_separator/separator/separator.py`, around line 971)**
- In the stem grouping section, after the existing regex `_\(([^)]+)\)` fails to
match a chunk output path:
  - Extract the base filename (without extension) from the chunk output path
  - Normalize it to lowercase
  - Look up the base name in `custom_name_to_stem`
  - If found, use the mapped stem name for grouping
- Only fall back to positional `stem_N` naming if both the regex fails AND the
base name is not found in the reverse map

**Task 3: Add Unit Tests (`tests/unit/test_separator_chunking.py`)**
- Add a new test method to `TestSeparatorChunkingLogic` or
`TestSeparatorChunkingEdgeCases`
- Set up the test with `custom_output_names={"Vocals": "my_vocals",
"Instrumental": "my_instrumental"}` and 2+ chunks
- Mock `_separate_file` to return filenames without the `_(StemName)` pattern
(e.g., `my_vocals.wav`, `my_instrumental.wav`)
- Assert chunks are grouped by stem name (`"Vocals"`, `"Instrumental"`), not
`stem_0`/`stem_1`
- Assert final merged output filenames use the custom names
- Follow the existing pattern using `Mock(spec=Separator)` and patching
`AudioChunker`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[Kulin-Soni]

I have found the solution to it.

Issues

• The same custom output name was used for every processed chunk, each new chunk overwrote the previously generated file in the temporary directory.

• The system relies on the regex (_\(([^)]+)\)) for stem name detection, which failed when custom names were used

  Filename	Result
  chunk_001_(Vocals)_model_name.wav	Vocals
  chunk_002_(Instrumental)_model_name.wav	Instrumental
  custom_name.wav	no match ❌
  custom_(Foo).wav	Foo but invalid ⚠️

  In the last case, "Foo" is not a valid stem name, and so cannot be mapped to the output names (custom_output_names):

  output_names = {
      "Vocals": "vocals_output",
      "Drums": "drums_output",
      "Bass": "bass_output",
      "Other": "other_output",
      "Guitar": "guitar_output",
      "Piano": "piano_output",
  }
  
  output_files = separator.separate('audio1.wav', output_names)

Solution

In the _process_with_chunking method of the Separator class (around line 965), custom output names were being passed to _separate_file() during every chunk iteration.

try:
-  output_files = self._separate_file(chunk_path, custom_output_names)
+  output_files = self._separate_file(chunk_path)

This ensures:

• The processed chunks no longer have custom names, and thus prevent overwriting the previous chunk.
• The existing regex-based stem detection continues to work correctly.

Result

• Chunk outputs are no longer overwritten.
• Stem name is classified to valid output names keys.
• Custom output names still work correctly at the final output stage.