# xiph/rnnoise architecture

> Architecture diagram of the GitHub repository xiph/rnnoise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiph/rnnoise
- Repository: https://github.com/xiph/rnnoise

## Overview

#### Purpose and public entry points
RNNoise is a C library for real-time 48 kHz mono speech noise suppression using hybrid DSP plus a recurrent neural-network model. The public API is `include/rnnoise.h`; runtime denoising state/model management is implemented in `src/denoise.c` and exposed through the example CLI `examples/rnnoise_demo.c`.

#### Build, packaging, and model acquisition
The project uses Autotools: `autogen.sh` prepares the build, `configure.ac` selects platform capabilities/options, and `Makefile.am` builds the library, tools, and example. `download_model.sh` obtains default model assets excluded from Git. Installed-library metadata is generated from `rnnoise.pc.in`; the build can instead omit embedded weights and require runtime model loading.

#### Real-time denoising pipeline
`src/denoise.c` owns the frame-by-frame processing flow: accept PCM samples, derive spectral/pitch features, run neural inference, derive suppression/filter controls, and synthesize denoised output. DSP primitives and shared internal definitions sit in `src/denoise.h`, `src/common.h`, and `src/arch.h`. The library boundary is intentionally sample/frame-oriented rather than file or network oriented.

#### Signal-analysis stages
Feature extraction depends on FFT and LPC/pitch analysis. `src/kiss_fft.c` provides spectral transforms; `src/celt_lpc.c` supports linear-prediction analysis; `src/pitch.c` estimates pitch-related features. These stages transform input audio into the fixed neural-network feature representation and support reconstruction/control decisions after inference.

#### Neural model execution and embedded weights
Inference is implemented by `src/nnet.c` and recurrent layers in `src/rnn.c`, with network shape/weight declarations in `src/nnet_arch.h`. The standard compiled-in model is represented by `src/nnet_default.c` and `src/rnnoise_tables.c`. A binary model can alternatively be supplied through the public model-loading API; model lifetime must outlive active denoise states.

#### CPU-specialized inference
The baseline C implementation is supplemented by vector abstractions in `src/vec.h`, `src/vec_avx.h`, and `src/vec_neon.h`. On x86, runtime CPU detection and dispatch support AVX2/SSE4.1 kernels through `src/x86/x86cpu.c`, `src/x86/nnet_avx2.c`, and `src/x86/nnet_sse4_1.c`. Configuration can select a fixed target architecture or enable x86 runtime dispatch.

#### Training-to-deployment pipeline
Offline feature generation is a native executable rooted in `src/dump_features.c`, which mixes clean speech, background/foreground noise, and optional RIR augmentation into float feature records. PyTorch training lives in `torch/rnnoise/train_rnnoise.py` with model definitions in `torch/rnnoise/rnnoise.py`; sparsity support is under `torch/sparsification/`. `torch/rnnoise/dump_rnnoise_weights.py` exports trained checkpoints into C weight sources that replace the embedded runtime model.

#### External data and operational boundaries
Training requires externally supplied raw 16-bit, 48 kHz PCM speech/noise data and optionally float RIR files; dataset references are in `datasets.txt`. The supplied CLI reads/writes raw machine-endian PCM only, while the library itself has no web service, database, or network runtime dependency. External network access is limited to model/data download and developer training workflows.

Main entry points: [`src/denoise.c`](https://github.com/xiph/rnnoise/blob/main/src/denoise.c) (Frame denoising), [`src/nnet.c`](https://github.com/xiph/rnnoise/blob/main/src/nnet.c) (Neural inference), [`configure.ac`](https://github.com/xiph/rnnoise/blob/main/configure.ac) (Autotools build), [`torch/rnnoise/train_rnnoise.py`](https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/train_rnnoise.py) (PyTorch training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime denoising"]
  node_public_api["Public C API<br/>API header<br/>[rnnoise.h]"]
  node_demo_cli["PCM demo CLI<br/>[rnnoise_demo.c]"]
  node_denoise["Frame denoising<br/>processing core<br/>[denoise.c]"]
  node_dsp_defs["DSP internals<br/>internal headers<br/>[denoise.h]"]
  node_fft["Spectral transforms<br/>DSP<br/>[kiss_fft.c]"]
  node_lpc_pitch["LPC and pitch analysis<br/>DSP<br/>[pitch.c]"]
end

subgraph group_inference["Model inference"]
  node_nnet["Neural inference<br/>network executor<br/>[nnet.c]"]
  node_rnn["Recurrent layers<br/>network layer<br/>[rnn.c]"]
  node_model_arch["Network architecture<br/>model declarations<br/>[nnet_arch.h]"]
  node_embedded_model["Embedded default model<br/>C weights<br/>[nnet_default.c]"]
  node_x86_dispatch{{"x86 optimized dispatch<br/>CPU dispatch<br/>[x86cpu.c]"}}
end

subgraph group_training["Training and export"]
  node_feature_dump["Feature generation<br/>offline native tool<br/>[dump_features.c]"]
  node_external_audio[("Speech, noise, and RIR data<br/>external dataset<br/>[datasets.txt]")]
  node_train["PyTorch training<br/>training script<br/>[train_rnnoise.py]"]
  node_torch_model["PyTorch model<br/>model definition<br/>[rnnoise.py]"]
  node_weight_export["C weight export<br/>model exporter"]
end

subgraph group_build["Build and distribution"]
  node_autotools["Autotools build<br/>build system<br/>[configure.ac]"]
  node_model_download["Default model download<br/>asset acquisition<br/>[download_model.sh]"]
  node_pkgconfig["Package metadata<br/>pkg-config template<br/>[rnnoise.pc.in]"]
end

node_demo_cli -->|"uses"| node_public_api
node_public_api -->|"creates and processes frames"| node_denoise
node_denoise -->|"uses"| node_dsp_defs
node_denoise -->|"extracts spectral features"| node_fft
node_denoise -->|"derives pitch features"| node_lpc_pitch
node_denoise -->|"runs feature inference"| node_nnet
node_nnet -->|"executes recurrent layers"| node_rnn
node_nnet -->|"uses network layout"| node_model_arch
node_nnet -->|"uses weights"| node_embedded_model
node_x86_dispatch -->|"accelerates kernels"| node_nnet
node_external_audio -->|"source material"| node_feature_dump
node_feature_dump -->|"feature records"| node_train
node_torch_model -->|"defines model"| node_train
node_train -->|"trained checkpoint"| node_weight_export
node_weight_export -->|"generates replacement weights"| node_embedded_model
node_autotools -->|"builds"| node_demo_cli
node_autotools -->|"builds library"| node_denoise
node_autotools -->|"configures target or dispatch"| node_x86_dispatch
node_autotools -->|"generates installed metadata"| node_pkgconfig
node_model_download -.->|"supplies default assets"| node_embedded_model

click node_public_api "https://github.com/xiph/rnnoise/blob/main/include/rnnoise.h"
click node_demo_cli "https://github.com/xiph/rnnoise/blob/main/examples/rnnoise_demo.c"
click node_denoise "https://github.com/xiph/rnnoise/blob/main/src/denoise.c"
click node_dsp_defs "https://github.com/xiph/rnnoise/blob/main/src/denoise.h"
click node_fft "https://github.com/xiph/rnnoise/blob/main/src/kiss_fft.c"
click node_lpc_pitch "https://github.com/xiph/rnnoise/blob/main/src/pitch.c"
click node_nnet "https://github.com/xiph/rnnoise/blob/main/src/nnet.c"
click node_rnn "https://github.com/xiph/rnnoise/blob/main/src/rnn.c"
click node_model_arch "https://github.com/xiph/rnnoise/blob/main/src/nnet_arch.h"
click node_embedded_model "https://github.com/xiph/rnnoise/blob/main/src/nnet_default.c"
click node_x86_dispatch "https://github.com/xiph/rnnoise/blob/main/src/x86/x86cpu.c"
click node_feature_dump "https://github.com/xiph/rnnoise/blob/main/src/dump_features.c"
click node_external_audio "https://github.com/xiph/rnnoise/blob/main/datasets.txt"
click node_train "https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/train_rnnoise.py"
click node_torch_model "https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/rnnoise.py"
click node_weight_export "https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/dump_rnnoise_weights.py"
click node_autotools "https://github.com/xiph/rnnoise/blob/main/configure.ac"
click node_model_download "https://github.com/xiph/rnnoise/blob/main/download_model.sh"
click node_pkgconfig "https://github.com/xiph/rnnoise/blob/main/rnnoise.pc.in"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_demo_cli,node_denoise,node_dsp_defs,node_fft,node_lpc_pitch toneBlue
class node_nnet,node_rnn,node_model_arch,node_embedded_model,node_x86_dispatch toneAmber
class node_feature_dump,node_external_audio,node_train,node_torch_model,node_weight_export toneMint
class node_autotools,node_model_download,node_pkgconfig toneRose
```

## Components

### Runtime denoising

Real-time C library processing path.

- [Public C API](https://github.com/xiph/rnnoise/blob/main/include/rnnoise.h): API header · `include/rnnoise.h`
- [PCM demo CLI](https://github.com/xiph/rnnoise/blob/main/examples/rnnoise_demo.c): CLI · Reads and writes raw machine-endian PCM. · `examples/rnnoise_demo.c`
- [Frame denoising](https://github.com/xiph/rnnoise/blob/main/src/denoise.c): processing core · Owns feature extraction, inference controls, and synthesis. · `src/denoise.c`
- [DSP internals](https://github.com/xiph/rnnoise/blob/main/src/denoise.h): internal headers · `src/denoise.h`
- [Spectral transforms](https://github.com/xiph/rnnoise/blob/main/src/kiss_fft.c): DSP · `src/kiss_fft.c`
- [LPC and pitch analysis](https://github.com/xiph/rnnoise/blob/main/src/pitch.c): DSP · `src/pitch.c`

### Model inference

Neural execution and deployed weights.

- [Neural inference](https://github.com/xiph/rnnoise/blob/main/src/nnet.c): network executor · `src/nnet.c`
- [Recurrent layers](https://github.com/xiph/rnnoise/blob/main/src/rnn.c): network layer · `src/rnn.c`
- [Network architecture](https://github.com/xiph/rnnoise/blob/main/src/nnet_arch.h): model declarations · `src/nnet_arch.h`
- [Embedded default model](https://github.com/xiph/rnnoise/blob/main/src/nnet_default.c): C weights · Can be replaced by runtime-loaded binary model. · `src/nnet_default.c`
- [x86 optimized dispatch](https://github.com/xiph/rnnoise/blob/main/src/x86/x86cpu.c): CPU dispatch · Selects AVX2 or SSE4.1 inference kernels at runtime. · `src/x86/x86cpu.c`

### Training and export

Offline data, training, and model generation.

- [Feature generation](https://github.com/xiph/rnnoise/blob/main/src/dump_features.c): offline native tool · Mixes speech, noise, and optional RIR into float feature records. · `src/dump_features.c`
- [Speech, noise, and RIR data](https://github.com/xiph/rnnoise/blob/main/datasets.txt): external dataset · Externally supplied 48 kHz PCM and optional float RIR files. · `datasets.txt`
- [PyTorch training](https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/train_rnnoise.py): training script · `torch/rnnoise/train_rnnoise.py`
- [PyTorch model](https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/rnnoise.py): model definition · `torch/rnnoise/rnnoise.py`
- [C weight export](https://github.com/xiph/rnnoise/blob/main/torch/rnnoise/dump_rnnoise_weights.py): model exporter · Converts trained checkpoints into C weight sources. · `torch/rnnoise/dump_rnnoise_weights.py`

### Build and distribution

Autotools build and optional model acquisition.

- [Autotools build](https://github.com/xiph/rnnoise/blob/main/configure.ac): build system · Configures and builds the library, tools, and example. · `configure.ac`
- [Default model download](https://github.com/xiph/rnnoise/blob/main/download_model.sh): asset acquisition · Obtains model assets excluded from Git. · `download_model.sh`
- [Package metadata](https://github.com/xiph/rnnoise/blob/main/rnnoise.pc.in): pkg-config template · `rnnoise.pc.in`

## Connections

- PCM demo CLI → Public C API: uses
- Public C API → Frame denoising: creates and processes frames
- Frame denoising → DSP internals: uses
- Frame denoising → Spectral transforms: extracts spectral features
- Frame denoising → LPC and pitch analysis: derives pitch features
- Frame denoising → Neural inference: runs feature inference
- Neural inference → Recurrent layers: executes recurrent layers
- Neural inference → Network architecture: uses network layout
- Neural inference → Embedded default model: uses weights
- x86 optimized dispatch → Neural inference: accelerates kernels
- Speech, noise, and RIR data → Feature generation: source material
- Feature generation → PyTorch training: feature records
- PyTorch model → PyTorch training: defines model
- PyTorch training → C weight export: trained checkpoint
- C weight export → Embedded default model: generates replacement weights
- Autotools build → PCM demo CLI: builds
- Autotools build → Frame denoising: builds library
- Autotools build → x86 optimized dispatch: configures target or dispatch
- Autotools build → Package metadata: generates installed metadata
- Default model download → Embedded default model: supplies default assets
