Skip to content

0.2.0, One RoFormer family

Choose a tag to compare

View all tags
@github-actions github-actions released this 26 May 08:04
· 30 commits to main since this release
0.2.0
673846e

0.2.0 — One RoFormer family, one class, one configuration surface

hunterFormsBS 0.2.0 is a unification release.

Instead of maintaining separate BS-style, mel-band, transition, and experimental RoFormer entry points, the package now centers everything on one public separator class:

from hunterFormsBS import BandSplitRotator

BandSplitRotator is the single model family for BS-style bands, mel bands, custom filter banks, overlapping layouts, non-overlapping layouts, optional acceleration, optional segmentation-style mask estimation, and downstream training/inference configuration.

What changed

  • Unified the public separator API around BandSplitRotator.
  • Removed the split between separate BS-RoFormer-style and Mel-Band-RoFormer-style classes.
  • Moved separator configuration onto one constructor surface instead of spreading related settings across multiple wrapper classes.
  • Kept band layout as data: BS-style, mel-style, and custom behavior are now selected by freqs_per_bands, sample_rate + num_bands, or an explicit mask_filter_bank.
  • Preserved familiar downstream parameter names where possible, including attention, transformer, mask-estimator, STFT, loss, checkpointing, and output-normalization options.
  • Added a much larger extension surface for future model variants without requiring another public RoFormer class.

Why this is better

The architectural difference between BS-style and mel-band separators is now treated as a band-layout problem, not a reason to maintain separate model families.

That means one class can express:

  • classic non-overlapping BS-style band partitions;
  • automatic mel-band layouts;
  • custom Boolean mask_filter_bank layouts;
  • overlapping or non-overlapping frequency-band membership;
  • RoPE or PoPE positional encoding;
  • PyTorch scaled-dot-product attention paths;
  • optional SageAttention acceleration;
  • optional HyperACE-style segmentation-branch mask estimation;
  • multi-resolution STFT training loss;
  • memory-saving activation checkpointing.

The result is easier to configure, easier to compare, and easier to extend than maintaining another pile of specialized RoFormer wrappers.

Breaking changes

This release intentionally removes old public surface area.

Use this:

from hunterFormsBS import BandSplitRotator

Instead of older specialized imports such as:

from hunterFormsBS.bs_roformer import BSRoformer
from hunterFormsBS.mel_band_roformer import MelBandRoformer

Supporting pieces such as attention blocks, band-split layers, type records, and optional HyperACE components should be imported from their explicit submodules rather than from the top-level package namespace.

Migration examples

BS-style / non-overlapping layout

from hunterFormsBS import BandSplitRotator

model = BandSplitRotator(
    dim=dim,
    depth=depth,
    freqs_per_bands=freqs_per_bands,
    # other model, attention, STFT, and loss parameters here
)

Mel-band layout

from hunterFormsBS import BandSplitRotator

model = BandSplitRotator(
    dim=dim,
    depth=depth,
    sample_rate=44100,
    num_bands=60,
    melscale_fbanks_mel_scale="slaney",
    melscale_fbanks_norm="slaney",
    # other model, attention, STFT, and loss parameters here
)

Custom band layout

from hunterFormsBS import BandSplitRotator

model = BandSplitRotator(
    dim=dim,
    depth=depth,
    mask_filter_bank=mask_filter_bank,
    # other model, attention, STFT, and loss parameters here
)

Checkpoint note

When migrating older BS-style configurations, check mask_estimator_depth.

Some older configurations stored mask_estimator_depth=2 while effectively behaving like 1. In this package, use the direct value:

mask_estimator_depth=1

That is the most common fix for size-mismatch errors when loading older checkpoints.

Removed because unified

The removed pieces were not removed because the functionality disappeared. They were removed because the same behaviors now live behind one clearer abstraction.

In 0.2.0, BandSplitRotator is the extension point. New band layouts, attention options, positional encoders, mask-estimator branches, and compatibility behavior should extend the unified model rather than adding another top-level RoFormer class.

Summary

hunterFormsBS 0.2.0 makes the package smaller at the public API level and larger at the configuration level: one class, all separator parameters, many band-layout modes, and a cleaner path for future research variants.

Assets 2
Loading