# xiph/speexdsp architecture

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

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

## Overview

##### Project Type and Purpose
- SpeexDSP is an open-source, cross-platform digital signal processing (DSP) library written in C.
- It provides core DSP routines—echo cancellation, pre-processing, resampling, jitter buffering, FFT, filterbanks, etc.—to be embedded in VoIP or multimedia applications.

##### File Tree Analysis
- Top-level items:
- Build infrastructure: configure.ac, Makefile.am, autogen.sh, acinclude.m4, etc.
- Platform folders: win32/, macosx/, ti/, symbian/, bfin/ (Blackfin) – each contains project files or Makefiles for target builds.
- Directory: include/speex – public headers for the API.
- libspeexdsp/: core C source for all DSP algorithms.
- Tests: under libspeexdsp (test*.c), plus platform-specific test projects under win32.
- Core architectural pattern: modular C library with clear separation between
a) public API (headers in include/speex)
b) algorithm implementations (libspeexdsp/*.c/.h),
c) platform abstraction (os_support.h, arch-specific fixed_*.h),
d) test harnesses,
e) build targets for multiple architectures.

##### Relevant README Insights
- Confirms SpeexDSP is a patent‐free DSP library.
- Directs users to INSTALL for build/install instructions.

##### Components
a. Main Components
- Public API Layer: include/speex/*.h
- DSP Core Modules (libspeexdsp):
– Echo cancellation (echo.c, speex_echo.h)
– Preprocessor (preprocess.c, speex_preprocess.h)
– Resampler (resample.c, speex_resampler.h)
– Jitter buffer (jitter.c, speex_jitter.h)
– FFT and filterbank (kiss_fft.c, filterbank.c)
– Misc math/utility (misc modules, os_support.h)
- Platform Abstraction Layer:
– os_support.{h,c} for threading, memory
– arch-specific fixed-point headers (fixed_arm4.h, fixed_bfin.h, etc.)
- Build System & Toolchain: autoconf/automake scripts, platform subdirectories (Win32 VS projects, macOS Xcode, TI DSP).
- Tests & Regression: test*.c, platform test projects.

b. Relationships & Data Flows
- Host Application → Public API → DSP Core Modules → Platform Abstraction → OS/HW.
- DSP Core Modules may call each other (e.g., preprocessor uses FFT, filterbank).
- Build System orchestrates compilation of core, linking public headers, generating .so/.dll/.a.
- Tests invoke API and verify algorithm outputs.

c. Architectural Patterns & Principles
- Layering: API layer over algorithm implementations, with a thin OS abstraction.
- Modularity: each DSP function in its own C module with corresponding header.
- Platform-specific specialization via #ifdef and separate arch headers.
- Separation of concerns: core DSP logic is pure C, independent of OS or build system.

d. Key Technologies & Frameworks
- C language (ANSI C99)
- Autotools (autoconf, automake) for UNIX builds
- Visual Studio & Xcode project files for Windows/macOS
- DSP techniques: FFT (KISS FFT), fixed-point math, filterbanks, jitter buffering.

##### Final Recommendations
- Be exhaustive but clear: show all layers and how they interact rather than every single source file.
- Cross-platform nature by grouping platform projects around the core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    App["Host Application"]:::external

    subgraph "Public API Layer"
        direction TB
        API_speex_buffer["speex_buffer.h"]:::api
        API_speex_echo["speex_echo.h"]:::api
        API_speex_jitter["speex_jitter.h"]:::api
        API_speex_preprocess["speex_preprocess.h"]:::api
        API_speex_resampler["speex_resampler.h"]:::api
        API_speexdsp_types["speexdsp_types.h"]:::api
        API_speexdsp_config["speexdsp_config_types.h.in"]:::api
    end

    subgraph "DSP Core Modules"
        direction TB
        EchoModule["Echo Cancellation"]:::core
        PreprocessModule["Preprocessor"]:::core
        ResamplerModule["Resampler"]:::core
        JitterModule["Jitter Buffer"]:::core
        FFTFilterModule["FFT & Filterbank"]:::core
        MiscModule["Misc Math/Utility"]:::core
    end

    subgraph "Platform Abstraction Layer"
        direction TB
        OSSupport["os_support.h"]:::platform
        ArchHeaders["Architecture Headers"]:::platform
    end

    BuildSystem["Build System & Toolchain"]:::build
    LibraryArtifact(("libspeexdsp (.a/.so/.dll)")):::build

    subgraph "Tests & Documentation"
        direction TB
        Tests["Test Harnesses"]:::test
        Docs["Documentation"]:::doc
    end

    OS_HW["OS / Hardware"]:::external

    %% Relationships
    App -->|"calls"| API_speex_buffer
    App -->|calls| API_speex_echo
    App -->|calls| API_speex_jitter
    App -->|calls| API_speex_preprocess
    App -->|calls| API_speex_resampler

    API_speex_echo -->|uses| EchoModule
    API_speex_preprocess -->|uses| PreprocessModule
    API_speex_resampler -->|uses| ResamplerModule
    API_speex_jitter -->|uses| JitterModule

    PreprocessModule -->|calls FFT| FFTFilterModule
    FFTFilterModule -->|relies on| MiscModule

    EchoModule -->|uses| MiscModule
    JitterModule -->|uses| MiscModule

    EchoModule -->|calls| OSSupport
    PreprocessModule -->|calls| OSSupport
    ResamplerModule -->|calls| OSSupport
    JitterModule -->|calls| OSSupport
    FFTFilterModule -->|calls| OSSupport
    MiscModule -->|calls| OSSupport

    OSSupport -->|depends on| ArchHeaders
    ArchHeaders -->|configures| OS_HW
    OSSupport -->|interfaces with| OS_HW

    BuildSystem -->|compiles| EchoModule
    BuildSystem -->|compiles| PreprocessModule
    BuildSystem -->|compiles| ResamplerModule
    BuildSystem -->|compiles| JitterModule
    BuildSystem -->|compiles| FFTFilterModule
    BuildSystem -->|compiles| MiscModule
    BuildSystem -->|links| LibraryArtifact

    Tests -->|invoke API| API_speex_echo
    Tests -->|invoke API| API_speex_resampler
    Tests -->|verify| LibraryArtifact

    Docs -->|includes| LibraryArtifact

    %% Click Events
    click API_speex_echo "https://github.com/xiph/speexdsp/blob/master/include/speex/speex_echo.h"
    click API_speex_preprocess "https://github.com/xiph/speexdsp/blob/master/include/speex/speex_preprocess.h"
    click API_speex_resampler "https://github.com/xiph/speexdsp/blob/master/include/speex/speex_resampler.h"
    click API_speex_jitter "https://github.com/xiph/speexdsp/blob/master/include/speex/speex_jitter.h"
    click EchoModule "https://github.com/xiph/speexdsp/blob/master/libspeexdsp/echo_diagnostic.m"
    click PreprocessModule "https://github.com/xiph/speexdsp/blob/master/libspeexdsp/preprocess.c"
    click ResamplerModule "https://github.com/xiph/speexdsp/blob/master/libspeexdsp/resample.c"
    click OSSupport "https://github.com/xiph/speexdsp/blob/master/libspeexdsp/os_support.h"
    click BuildSystem "https://github.com/xiph/speexdsp/blob/master/configure.ac"
    click Tests "https://github.com/xiph/speexdsp/blob/master/libspeexdsp/testresample.c"
    click Docs "https://github.com/xiph/speexdsp/blob/master/doc/manual.pdf"

    %% Styles
    classDef api fill:#ccffcc,stroke:#2d882d,color:#000;
    classDef core fill:#cce5ff,stroke:#1a5dab,color:#000;
    classDef platform fill:#ffe0b3,stroke:#cc7a00,color:#000;
    classDef build fill:#e0e0e0,stroke:#808080,color:#000;
    classDef test fill:#fff2cc,stroke:#d6a600,color:#000;
    classDef doc fill:#fff2cc,stroke:#d6a600,color:#000;
    classDef external fill:#f2f2f2,stroke:#999999,color:#000;
```
