asrfront 0.1.0__tar.gz

asrfront-0.1.0/.clang-format

@@ -0,0 +1,5 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 100
+PointerAlignment: Right
+AllowShortFunctionsOnASingleLine: Inline

asrfront-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Install tools (no native build needed)
+        run: uv sync --no-install-project
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync mypy --strict src/asrfront
+      - name: clang-format
+        run: >-
+          uv run --no-sync clang-format --dry-run --Werror
+          csrc/*.c csrc/*.h csrc/include/*.h tests/c/*.c bench/*.c src/asrfront/_ext.cpp
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest]
+        python: ["3.9", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build and install (editable)
+        run: uv sync
+      - name: Python tests
+        run: uv run --no-sync pytest -q
+      - name: Python tests with the plain-C kernels (MSVC code path)
+        run: uv run --no-sync pytest -q tests/python/test_whisper.py tests/python/test_sensevoice.py
+        env:
+          ASRFRONT_KERNELS: scalar
+      - name: C tests
+        run: |
+          uv run --no-sync cmake -S . -B build/ctest -DASRFRONT_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
+          uv run --no-sync cmake --build build/ctest --config Release
+          uv run --no-sync ctest --test-dir build/ctest -C Release --output-on-failure
+
+  reference:
+    # Compare against the original float32 libraries (torch, torchaudio).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --group ref
+      - run: uv run --no-sync pytest -q
+
+  sanitizers:
+    runs-on: ubuntu-latest
+    env:
+      SAN_FLAGS: -fsanitize=address,undefined -fno-sanitize-recover=all -fno-omit-frame-pointer
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: C tests under ASan/UBSan
+        run: |
+          uv sync --no-install-project
+          uv run --no-sync cmake -S . -B build/asan -G Ninja -DASRFRONT_BUILD_TESTS=ON \
+            -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_FLAGS="$SAN_FLAGS"
+          uv run --no-sync cmake --build build/asan
+          uv run --no-sync ctest --test-dir build/asan --output-on-failure
+      - name: Python tests under ASan/UBSan
+        run: |
+          uv pip install --no-build-isolation scikit-build-core nanobind
+          uv pip install --no-build-isolation -e . \
+            -C cmake.build-type=RelWithDebInfo -C build-dir=build/asan-py \
+            -C "cmake.define.CMAKE_C_FLAGS=$SAN_FLAGS" -C "cmake.define.CMAKE_CXX_FLAGS=$SAN_FLAGS" \
+            -C "cmake.define.CMAKE_SHARED_LINKER_FLAGS=-fsanitize=address,undefined"
+          LD_PRELOAD="$(gcc -print-file-name=libasan.so) $(gcc -print-file-name=libubsan.so)" \
+          ASAN_OPTIONS=detect_leaks=0 \
+            .venv/bin/python -m pytest -q

asrfront-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,89 @@
+name: Wheels
+
+# Release: bump the version (pyproject.toml + csrc/include/asrfront.h), commit, then
+#   git tag vX.Y.Z && git push origin vX.Y.Z
+# builds the sdist and all wheels, tests them and uploads them to PyPI.
+
+on:
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Upload the built wheels and sdist to TestPyPI"
+        type: boolean
+        default: false
+  push:
+    tags: ["v*"]
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check that the tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml version $version"
+            exit 1
+          fi
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build --sdist --out-dir dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build and test wheels (config in pyproject.toml [tool.cibuildwheel])
+        run: uvx --from "cibuildwheel>=3,<4" cibuildwheel --output-dir wheelhouse
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish-testpypi:
+    # Rehearsal: Actions -> Wheels -> Run workflow with "testpypi" checked.
+    # Trusted publishing: register this repository / wheels.yml / environment "testpypi"
+    # as a (pending) publisher on test.pypi.org first.
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true  # re-running for the same version is not an error
+
+  publish:
+    # Pushing a v* tag uploads to PyPI (only if the tag matches the version and every wheel
+    # built and passed its tests). Trusted publishing: register this repository /
+    # wheels.yml / environment "pypi" as a (pending) publisher on pypi.org first.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

asrfront-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.so
+*.pyd
+.venv/
+.pytest_cache/
+.ruff_cache/
+wheelhouse/

asrfront-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

asrfront-0.1.0/CMakeLists.txt

@@ -0,0 +1,113 @@
+cmake_minimum_required(VERSION 3.18...3.30)
+project(asrfront LANGUAGES C)
+
+# scikit-build-core sets SKBUILD=2, which option() would not treat as ON.
+if(SKBUILD)
+  set(_asrfront_python_default ON)
+else()
+  set(_asrfront_python_default OFF)
+endif()
+option(ASRFRONT_BUILD_PYTHON "Build the nanobind Python extension" ${_asrfront_python_default})
+option(ASRFRONT_BUILD_TESTS "Build C unit tests" OFF)
+option(ASRFRONT_BUILD_BENCH "Build C benchmarks" OFF)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# ---------------------------------------------------------------------------
+# C core: pure C11, links only against libm. No -ffast-math (reproducibility).
+# ---------------------------------------------------------------------------
+function(asrfront_c_options target)
+  target_include_directories(${target} PUBLIC csrc/include PRIVATE csrc)
+  set_target_properties(${target} PROPERTIES POSITION_INDEPENDENT_CODE ON)
+  if(MSVC)
+    target_compile_options(${target} PRIVATE /W4)
+  else()
+    target_compile_options(${target} PRIVATE -Wall -Wextra -Wpedantic -Wshadow)
+  endif()
+endfunction()
+
+# SIMD kernels: the same source compiled per ISA, selected at runtime (kernels.c).
+# No FMA flags anywhere, so every variant gives bit-identical results.
+add_library(asrfront_kernels_generic OBJECT csrc/kernels_impl.c)
+target_compile_definitions(asrfront_kernels_generic PRIVATE AF_ISA=generic)
+asrfront_c_options(asrfront_kernels_generic)
+set(ASRFRONT_KERNEL_OBJECTS $<TARGET_OBJECTS:asrfront_kernels_generic>)
+
+# Plain-C variant (no vector extensions), i.e. the MSVC code path; selectable with
+# ASRFRONT_KERNELS=scalar so it is tested on every platform.
+add_library(asrfront_kernels_scalar OBJECT csrc/kernels_impl.c)
+target_compile_definitions(asrfront_kernels_scalar PRIVATE AF_ISA=scalar AF_NO_VECTOR_EXT=1)
+asrfront_c_options(asrfront_kernels_scalar)
+list(APPEND ASRFRONT_KERNEL_OBJECTS $<TARGET_OBJECTS:asrfront_kernels_scalar>)
+
+if(CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|AMD64|amd64|x64)$")
+  add_library(asrfront_kernels_avx2 OBJECT csrc/kernels_impl.c)
+  target_compile_definitions(asrfront_kernels_avx2 PRIVATE AF_ISA=avx2)
+  target_compile_options(asrfront_kernels_avx2 PRIVATE $<IF:$<C_COMPILER_ID:MSVC>,/arch:AVX2,-mavx2>)
+  asrfront_c_options(asrfront_kernels_avx2)
+  list(APPEND ASRFRONT_KERNEL_OBJECTS $<TARGET_OBJECTS:asrfront_kernels_avx2>)
+  set(ASRFRONT_HAVE_AVX2 ON)
+endif()
+
+add_library(asrfront_core STATIC
+  csrc/common.c
+  csrc/fft.c
+  csrc/kernels.c
+  csrc/melbank.c
+  csrc/whisper.c
+  csrc/sensevoice.c
+  ${ASRFRONT_KERNEL_OBJECTS}
+)
+asrfront_c_options(asrfront_core)
+if(ASRFRONT_HAVE_AVX2)
+  target_compile_definitions(asrfront_core PRIVATE AF_HAVE_AVX2=1)
+endif()
+if(UNIX)
+  target_link_libraries(asrfront_core PUBLIC m)
+endif()
+
+# ---------------------------------------------------------------------------
+# Python extension
+# ---------------------------------------------------------------------------
+if(ASRFRONT_BUILD_PYTHON)
+  enable_language(CXX)
+  set(CMAKE_CXX_STANDARD 17)
+  set(CMAKE_CXX_STANDARD_REQUIRED ON)
+  # SKBUILD_SABI_COMPONENT is "Development.SABIModule" when building a stable-ABI wheel.
+  find_package(Python 3.9 REQUIRED COMPONENTS Interpreter Development.Module
+               ${SKBUILD_SABI_COMPONENT})
+  find_package(nanobind CONFIG REQUIRED)
+  nanobind_add_module(_ext STABLE_ABI NB_STATIC src/asrfront/_ext.cpp)
+  target_include_directories(_ext PRIVATE csrc)  # internal headers (test hooks)
+  target_link_libraries(_ext PRIVATE asrfront_core)
+  install(TARGETS _ext LIBRARY DESTINATION asrfront)
+endif()
+
+# ---------------------------------------------------------------------------
+# C unit tests
+# ---------------------------------------------------------------------------
+if(ASRFRONT_BUILD_TESTS)
+  enable_testing()
+  foreach(t test_api test_fft)
+    add_executable(${t} tests/c/${t}.c)
+    target_include_directories(${t} PRIVATE csrc)  # internal headers
+    target_link_libraries(${t} PRIVATE asrfront_core)
+    add_test(NAME ${t} COMMAND ${t})
+  endforeach()
+endif()
+
+# ---------------------------------------------------------------------------
+# C benchmarks
+# ---------------------------------------------------------------------------
+if(ASRFRONT_BUILD_BENCH)
+  foreach(b bench_fft bench_frontend)
+    add_executable(${b} bench/${b}.c)
+    target_include_directories(${b} PRIVATE csrc)
+    target_link_libraries(${b} PRIVATE asrfront_core)
+  endforeach()
+endif()

asrfront-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sinjin Jeong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asrfront-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.1
+Name: asrfront
+Version: 0.1.0
+Summary: Super-fast, dependency-free C frontends (log-mel, kaldi fbank) for Whisper and SenseVoice ASR models
+Keywords: asr,speech,whisper,sensevoice,fbank,mel-spectrogram,kaldi
+Author: sjjeong94
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/sjjeong94/asrfront
+Project-URL: Issues, https://github.com/sjjeong94/asrfront/issues
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Description-Content-Type: text/markdown
+
+# asrfront
+
+Super-fast frontend (feature extraction) for ASR models such as **Whisper** and
+**SenseVoiceSmall**.
+
+- native C core with no dependencies (own FFT, SIMD kernels with runtime CPU dispatch)
+- Python binding based on [nanobind](https://github.com/wjakob/nanobind), zero-copy NumPy output
+- numerically matches the reference implementations (see [Accuracy](#accuracy))
+
+```python
+import asrfront
+
+mel = asrfront.whisper.log_mel(audio)  # (80, 3000)
+feat = asrfront.sensevoice.fbank(audio, cmvn="am.mvn")  # (T', 560)
+```
+
+## Install
+
+```bash
+pip install asrfront
+```
+
+Wheels: Linux (x86_64, aarch64), Windows (x86_64); CPython 3.9+
+(one `abi3` wheel covers 3.12 and later). Building from source needs a C11/C++17 compiler.
+
+## Usage
+
+`audio` is a 16 kHz mono waveform: a float array in [-1, 1], int16 PCM, a list, or a CPU
+torch tensor. Resampling and decoding are out of scope.
+
+### Whisper
+
+```python
+from asrfront import whisper
+
+mel = whisper.log_mel(audio)  # (80, 3000): pad/trim to 30 s like whisper
+mel = whisper.log_mel(audio, n_mels=128)  # large-v3
+mel = whisper.log_mel(audio, pad_or_trim=False)  # (80, len(audio) // 160)
+
+batch = whisper.log_mel_batch([a1, a2, a3])  # (3, 80, 3000), multi-threaded
+```
+
+Equivalent to `whisper.log_mel_spectrogram(whisper.pad_or_trim(audio), n_mels)`.
+
+### SenseVoice
+
+```python
+from asrfront import sensevoice
+
+feat = sensevoice.fbank(audio, cmvn="path/to/am.mvn")  # (ceil(T / 6), 560)
+feats, lengths = sensevoice.fbank_batch([a1, a2], cmvn="path/to/am.mvn")  # zero-padded
+raw = sensevoice.fbank_raw(audio)  # (T, 80) kaldi fbank only
+shift, scale = sensevoice.load_cmvn("path/to/am.mvn")
+```
+
+Equivalent to FunASR's `WavFrontend` (`torchaudio.compliance.kaldi.fbank` on the int16-scaled
+waveform with a Hamming window, `dither=0`, then LFR `m=7, n=6` and CMVN from `am.mvn`).
+`dither=` and `seed=` are available; the RNG is reseeded on every call so identical inputs
+give identical outputs.
+
+### Threads
+
+All native calls release the GIL. The `*_batch` functions spread items over a thread pool
+(`n_threads=None` uses every available core); each Python thread uses its own native handle.
+
+## Performance
+
+30 s of audio, single thread, Intel i5-14400F (AVX2), best of N runs
+(`uv run --group ref --group bench python bench/compare.py`):
+
+| | asrfront | reference | speed-up |
+|---|---|---|---|
+| Whisper log-mel (80 × 3000) | 0.85–0.95 ms | openai-whisper `log_mel_spectrogram` (torch) 8.6–9.6 ms | ~10x |
+| | | librosa STFT + mel (numpy) 6.6–7.0 ms | ~7.7x |
+| SenseVoice fbank + LFR + CMVN | 1.3–1.4 ms | FunASR `WavFrontend` (torchaudio) 12–14 ms | ~9–10x |
+| kaldi fbank only | 1.3 ms | `torchaudio.compliance.kaldi.fbank` 11–12 ms | ~9x |
+
+Full results (thread scaling, input lengths, kernel variants, methodology):
+[`docs/benchmark.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/benchmark.md).
+
+Kernels process 8 frames at a time in SIMD lanes. On x86-64 an AVX2 build is selected at
+runtime when available (`asrfront._ext.kernel_isa()`); `ASRFRONT_KERNELS=generic` forces the
+baseline build. All variants give bit-identical results. Batch of 32 × 30 s: ~7.5 ms with
+16 threads.
+
+## Accuracy
+
+Maximum absolute error against float64 reference implementations
+([`tests/python/reference.py`](https://github.com/sjjeong94/asrfront/blob/main/tests/python/reference.py)) over 16 test signals (silence,
+tones, chirp, noise, clipping, DC offset, real speech, short and > 30 s inputs):
+
+| | worst case | speech | target |
+|---|---|---|---|
+| Whisper log-mel (80 and 128 mels) | 4.0e-5 | 1.3e-5 | 1e-4 |
+| kaldi fbank (log domain) | 7.7e-4 | 2.0e-4 | 1e-3 |
+| SenseVoice features with SenseVoiceSmall's `am.mvn` | 1.1e-4 | | |
+
+The whisper mel filters are bit-identical to whisper's `mel_filters.npz`. Against the
+original float32 libraries: ≤ 1e-4 vs. whisper (torch) and ≤ 2e-3 vs. torchaudio's kaldi
+fbank (torchaudio builds its mel banks in float32).
+
+## Development
+
+```bash
+uv sync                       # create .venv and build the extension (needs a C compiler)
+uv run pytest                 # tests; add --group ref for torch/torchaudio comparisons
+uv run --group ref pytest
+uv run cmake -S . -B build/ctest -G Ninja -DASRFRONT_BUILD_TESTS=ON -DASRFRONT_BUILD_BENCH=ON
+uv run cmake --build build/ctest && uv run ctest --test-dir build/ctest
+```
+
+The C API is in [`csrc/include/asrfront.h`](https://github.com/sjjeong94/asrfront/blob/main/csrc/include/asrfront.h). The preprocessing of each
+model is documented step by step in [`docs/whisper.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/whisper.md) and
+[`docs/sensevoice.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/sensevoice.md); see [`plan.md`](https://github.com/sjjeong94/asrfront/blob/main/plan.md) for design and
+implementation notes.
+
+## License
+
+MIT. Test data in `tests/data` comes from [openai/whisper](https://github.com/openai/whisper)
+(MIT); see [`tests/data/README.md`](https://github.com/sjjeong94/asrfront/blob/main/tests/data/README.md).

asrfront-0.1.0/README.md

@@ -0,0 +1,120 @@
+# asrfront
+
+Super-fast frontend (feature extraction) for ASR models such as **Whisper** and
+**SenseVoiceSmall**.
+
+- native C core with no dependencies (own FFT, SIMD kernels with runtime CPU dispatch)
+- Python binding based on [nanobind](https://github.com/wjakob/nanobind), zero-copy NumPy output
+- numerically matches the reference implementations (see [Accuracy](#accuracy))
+
+```python
+import asrfront
+
+mel = asrfront.whisper.log_mel(audio)  # (80, 3000)
+feat = asrfront.sensevoice.fbank(audio, cmvn="am.mvn")  # (T', 560)
+```
+
+## Install
+
+```bash
+pip install asrfront
+```
+
+Wheels: Linux (x86_64, aarch64), Windows (x86_64); CPython 3.9+
+(one `abi3` wheel covers 3.12 and later). Building from source needs a C11/C++17 compiler.
+
+## Usage
+
+`audio` is a 16 kHz mono waveform: a float array in [-1, 1], int16 PCM, a list, or a CPU
+torch tensor. Resampling and decoding are out of scope.
+
+### Whisper
+
+```python
+from asrfront import whisper
+
+mel = whisper.log_mel(audio)  # (80, 3000): pad/trim to 30 s like whisper
+mel = whisper.log_mel(audio, n_mels=128)  # large-v3
+mel = whisper.log_mel(audio, pad_or_trim=False)  # (80, len(audio) // 160)
+
+batch = whisper.log_mel_batch([a1, a2, a3])  # (3, 80, 3000), multi-threaded
+```
+
+Equivalent to `whisper.log_mel_spectrogram(whisper.pad_or_trim(audio), n_mels)`.
+
+### SenseVoice
+
+```python
+from asrfront import sensevoice
+
+feat = sensevoice.fbank(audio, cmvn="path/to/am.mvn")  # (ceil(T / 6), 560)
+feats, lengths = sensevoice.fbank_batch([a1, a2], cmvn="path/to/am.mvn")  # zero-padded
+raw = sensevoice.fbank_raw(audio)  # (T, 80) kaldi fbank only
+shift, scale = sensevoice.load_cmvn("path/to/am.mvn")
+```
+
+Equivalent to FunASR's `WavFrontend` (`torchaudio.compliance.kaldi.fbank` on the int16-scaled
+waveform with a Hamming window, `dither=0`, then LFR `m=7, n=6` and CMVN from `am.mvn`).
+`dither=` and `seed=` are available; the RNG is reseeded on every call so identical inputs
+give identical outputs.
+
+### Threads
+
+All native calls release the GIL. The `*_batch` functions spread items over a thread pool
+(`n_threads=None` uses every available core); each Python thread uses its own native handle.
+
+## Performance
+
+30 s of audio, single thread, Intel i5-14400F (AVX2), best of N runs
+(`uv run --group ref --group bench python bench/compare.py`):
+
+| | asrfront | reference | speed-up |
+|---|---|---|---|
+| Whisper log-mel (80 × 3000) | 0.85–0.95 ms | openai-whisper `log_mel_spectrogram` (torch) 8.6–9.6 ms | ~10x |
+| | | librosa STFT + mel (numpy) 6.6–7.0 ms | ~7.7x |
+| SenseVoice fbank + LFR + CMVN | 1.3–1.4 ms | FunASR `WavFrontend` (torchaudio) 12–14 ms | ~9–10x |
+| kaldi fbank only | 1.3 ms | `torchaudio.compliance.kaldi.fbank` 11–12 ms | ~9x |
+
+Full results (thread scaling, input lengths, kernel variants, methodology):
+[`docs/benchmark.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/benchmark.md).
+
+Kernels process 8 frames at a time in SIMD lanes. On x86-64 an AVX2 build is selected at
+runtime when available (`asrfront._ext.kernel_isa()`); `ASRFRONT_KERNELS=generic` forces the
+baseline build. All variants give bit-identical results. Batch of 32 × 30 s: ~7.5 ms with
+16 threads.
+
+## Accuracy
+
+Maximum absolute error against float64 reference implementations
+([`tests/python/reference.py`](https://github.com/sjjeong94/asrfront/blob/main/tests/python/reference.py)) over 16 test signals (silence,
+tones, chirp, noise, clipping, DC offset, real speech, short and > 30 s inputs):
+
+| | worst case | speech | target |
+|---|---|---|---|
+| Whisper log-mel (80 and 128 mels) | 4.0e-5 | 1.3e-5 | 1e-4 |
+| kaldi fbank (log domain) | 7.7e-4 | 2.0e-4 | 1e-3 |
+| SenseVoice features with SenseVoiceSmall's `am.mvn` | 1.1e-4 | | |
+
+The whisper mel filters are bit-identical to whisper's `mel_filters.npz`. Against the
+original float32 libraries: ≤ 1e-4 vs. whisper (torch) and ≤ 2e-3 vs. torchaudio's kaldi
+fbank (torchaudio builds its mel banks in float32).
+
+## Development
+
+```bash
+uv sync                       # create .venv and build the extension (needs a C compiler)
+uv run pytest                 # tests; add --group ref for torch/torchaudio comparisons
+uv run --group ref pytest
+uv run cmake -S . -B build/ctest -G Ninja -DASRFRONT_BUILD_TESTS=ON -DASRFRONT_BUILD_BENCH=ON
+uv run cmake --build build/ctest && uv run ctest --test-dir build/ctest
+```
+
+The C API is in [`csrc/include/asrfront.h`](https://github.com/sjjeong94/asrfront/blob/main/csrc/include/asrfront.h). The preprocessing of each
+model is documented step by step in [`docs/whisper.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/whisper.md) and
+[`docs/sensevoice.md`](https://github.com/sjjeong94/asrfront/blob/main/docs/sensevoice.md); see [`plan.md`](https://github.com/sjjeong94/asrfront/blob/main/plan.md) for design and
+implementation notes.
+
+## License
+
+MIT. Test data in `tests/data` comes from [openai/whisper](https://github.com/openai/whisper)
+(MIT); see [`tests/data/README.md`](https://github.com/sjjeong94/asrfront/blob/main/tests/data/README.md).

asrfront-0.1.0/bench/bench_fft.c

@@ -0,0 +1,55 @@
+/* Real FFT throughput: ns per transform for the frontend sizes. */
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+#include "asrfront.h"
+#include "fft.h"
+
+static double now_ns(void) {
+    struct timespec ts;
+    timespec_get(&ts, TIME_UTC);
+    return (double)ts.tv_sec * 1e9 + (double)ts.tv_nsec;
+}
+
+static void bench(int n, int iters) {
+    af_rfft *p = NULL;
+    if (af_rfft_create(n, &p) != AF_OK) {
+        fprintf(stderr, "create failed for n=%d\n", n);
+        exit(1);
+    }
+    float *x = malloc(n * sizeof(float));
+    float *pw = malloc((n / 2 + 1) * sizeof(float));
+    for (int i = 0; i < n; i++)
+        x[i] = (float)((i * 7919) % 1000) / 1000.0f - 0.5f;
+
+    volatile float sink = 0.0f;
+    for (int i = 0; i < iters / 10; i++) { /* warm-up */
+        af_rfft_power(p, x, pw);
+        sink += pw[1];
+    }
+    double best = 1e30;
+    for (int rep = 0; rep < 5; rep++) {
+        double t0 = now_ns();
+        for (int i = 0; i < iters; i++) {
+            x[0] = (float)i; /* defeat hoisting */
+            af_rfft_power(p, x, pw);
+            sink += pw[1];
+        }
+        double dt = (now_ns() - t0) / iters;
+        best = dt < best ? dt : best;
+    }
+    printf("rfft+power n=%4d: %8.1f ns/frame  (%6.3f ms per 3000 frames = 30 s)\n", n, best,
+           best * 3000 / 1e6);
+    (void)sink;
+    free(x);
+    free(pw);
+    af_rfft_destroy(p);
+}
+
+int main(int argc, char **argv) {
+    int iters = argc > 1 ? atoi(argv[1]) : 200000;
+    bench(400, iters);
+    bench(512, iters);
+    return 0;
+}