Table of Contents

Introduction

Key Features

Installation

Option 1: Install from PyPI (Recommended)

pip install chunkformer

Option 2: Install from source

# Clone the repositorygit clone https://github.com/your-username/chunkformer.gitcd chunkformer# Install in development modepip install -e.

Pretrained Models

Usage

Feature Extraction

fromchunkformerimportChunkFormerModelimporttorchdevice="cuda:0"# Load a pre-trained model from Hugging Face or local directorymodel=ChunkFormerModel.from_pretrained("khanhld/chunkformer-ctc-large-vie").to(device)x,x_len=model._load_audio_and_extract_features("path/to/audio")# x: (T, F), x_len: intx=x.unsqueeze(0).to(device)x_len=torch.tensor([x_len],device=device)# Extract featurefeature,feature_len=model.encode(xs=x,xs_lens=x_len,chunk_size=64,left_context_size=128,right_context_size=128,)print("feature: ",feature.shape)print("feature_len: ",feature_len)

Python API

Classification

fromchunkformerimportChunkFormerModel# Load a pre-trained classification model from Hugging Face or local directorymodel=ChunkFormerModel.from_pretrained("path/to/classification/model")# Single audio classificationresult=model.classify_audio(audio_path="path/to/audio.wav",chunk_size=-1,# -1 for full attentionleft_context_size=-1,right_context_size=-1,)print(result)

Transcription

fromchunkformerimportChunkFormerModel# Load a pre-trained encoder from Hugging Face or local directorymodel=ChunkFormerModel.from_pretrained("khanhld/chunkformer-ctc-large-vie")# For single long-form audio transcriptiontranscription=model.endless_decode(audio_path="path/to/long_audio.wav",chunk_size=64,left_context_size=128,right_context_size=128,total_batch_duration=14400,# in secondsreturn_timestamps=True)print(transcription)# For batch processing of multiple audio filesaudio_files= ["audio1.wav","audio2.wav","audio3.wav"]transcriptions=model.batch_decode(audio_paths=audio_files,chunk_size=64,left_context_size=128,right_context_size=128,total_batch_duration=1800# Total batch duration in seconds)fori,transcriptioninenumerate(transcriptions):print(f"Audio{i+1}:{transcription}")

Command Line

Long-Form Audio Transcription

chunkformer-decode \    --model_checkpoint path/to/hf/checkpoint/repo \    --audio_file path/to/audio.wav \    --total_batch_duration 14400 \    --chunk_size 64 \    --left_context_size 128 \    --right_context_size 128

[00:00:01.200] - [00:00:02.400]: this is a transcription example[00:00:02.500] - [00:00:03.700]: testing the long-form audio

Batch Audio Transcription

chunkformer-decode \    --model_checkpoint path/to/hf/checkpoint/repo \    --audio_list path/to/data.tsv \    --total_batch_duration 14400 \    --chunk_size 64 \    --left_context_size 128 \    --right_context_size 128

WER: 0.1234

Classification

chunkformer-decode \    --model_checkpoint path/to/classification/model \    --audio_file path/to/audio.wav

Training

Citation

@INPROCEEDINGS{10888640,author={Le, Khanh and Ho, Tuan Vu and Tran, Dung and Chau, Duc Thanh},booktitle={ICASSP 2025 - 2025 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)},title={ChunkFormer: Masked Chunking Conformer For Long-Form Speech Transcription},year={2025},volume={},number={},pages={1-5},keywords={Scalability;Memory management;Graphics processing units;Signal processing;Performance gain;Hardware;Resource management;Speech processing;Standards;Context modeling;chunkformer;masked batch;long-form transcription},doi={10.1109/ICASSP49660.2025.10888640}}

Acknowledgments