HF-FlowSR: CBTBridge-Full

Official research implementation of HF-FlowSR with CBTBridge-Full for speech audio super-resolution.

This repository provides the model architecture, training and inference pipelines, and evaluation utilities used for CBTBridge-Full. The implementation supports bandwidth extension from multiple low-sampling-rate inputs to 48 kHz speech.

Pretrained models are not included in the current release. Model checkpoints will be made publicly available in a future release.

Repository Layout

src/hf_flowsr/
  configs/             CBTBridge-Full architecture and training configuration
  model.py             acoustic model, CBTBridge, and flow-matching wrapper
  modules.py           transformer and network components
  train_impl.py        training pipeline
  trainer.py           optimization and validation
  inference.py         shared prediction API
  protocol.py          degradation and evaluation utilities
  cli/                 training, inference, and evaluation commands
  third_party/bigvgan/ BigVGAN runtime and associated licenses

docs/                  model and evaluation documentation
data/                  expected dataset layout
checkpoints/           checkpoint directory
tests/                 regression and protocol tests

Installation

The codebase is developed with Python 3.10 and a CUDA-capable PyTorch environment.

Install the package with:

python -m pip install -e .

Please install a compatible CUDA-enabled PyTorch version according to your local environment.

HF-FlowSR uses BigVGAN for waveform reconstruction. A compatible 48 kHz BigVGAN checkpoint is required for waveform inference and evaluation.

The pretrained HF-FlowSR checkpoint will be released separately in a future update.

Training

Prepare clean 48 kHz speech organized in speaker subdirectories.

The default audio format is FLAC. WAV files can be used by specifying:

--audio-extension .wav

Model architecture and optimization settings are defined in:

src/hf_flowsr/configs/cbt_full.py

Example:

hf-flowsr-train \
  --data-root /path/to/train_audio \
  --vocoder-checkpoint /path/to/bigvgan_checkpoint \
  --output-dir runs/cbt_full

This command trains CBTBridge-Full from scratch and stores checkpoints and TensorBoard logs under the specified output directory.

The number of training epochs can be changed using:

--epochs

Inference

HF-FlowSR supports speech inputs sampled at:

• 8 kHz
• 12 kHz
• 16 kHz
• 24 kHz

The reconstructed waveform is generated at 48 kHz.

Example:

hf-flowsr-infer \
  --input low.wav \
  --output restored.wav \
  --checkpoint /path/to/hf_flowsr_checkpoint \
  --vocoder-checkpoint /path/to/bigvgan_checkpoint

Optional waveform post-processing can be enabled with:

--waveform-pp

This applies the low-frequency waveform anchoring procedure used by the evaluation pipeline.

Evaluation

The evaluation pipeline accepts clean 48 kHz reference speech and automatically generates bandwidth-limited inputs at:

8 kHz
12 kHz
16 kHz
24 kHz

For each input bandwidth, the model performs speech super-resolution and evaluates the reconstructed outputs using the unified evaluation protocol implemented in this repository.

Example:

hf-flowsr-eval \
  --audio-root /path/to/test_audio \
  --checkpoint /path/to/hf_flowsr_checkpoint \
  --vocoder-checkpoint /path/to/bigvgan_checkpoint \
  --output-dir results/cbt_full

For a quick pipeline check, use:

--limit 1

The evaluation pipeline produces:

per_utterance.csv
summary.csv

along with reconstructed waveform caches when enabled.

Detailed evaluation settings and metric definitions are provided in:

docs/EVALUATION_PROTOCOL.md

Users who wish to reproduce reported benchmark results should use the corresponding dataset split and evaluation settings described in the paper.

Pretrained Models

Pretrained HF-FlowSR / CBTBridge-Full model weights are currently not included in this repository.

The pretrained checkpoints will be released in a future update.

Once released, download instructions and checkpoint information will be provided here.

Development Checks

Run the regression tests with:

python -m unittest discover -s tests -v

Third-Party Components

This repository includes components derived from the following open-source projects:

• NVIDIA BigVGAN
• alias-free-torch

The corresponding third-party licenses are included with their source code.

Please refer to the individual license files for details.

Citation

If you find this repository useful for your research, please consider citing the corresponding HF-FlowSR paper.

Citation information will be added following publication.