car-diagnosis

Diagnose a car fault from its sound — an honest, end-to-end audio-ML pipeline (scrape → clean → CLAP → calibrated triage). Proof of concept.

Developer ToolsPythonMIT 264 30Health 82

GitHub

What is it?

What it is

An audio-based car fault diagnosis system that provides calibrated triage results, identifying faults, their location in the car, and likely parts with uncertainty awareness.

Why it exists

To demonstrate a reliable, calibrated approach for diagnosing car faults from noisy audio (e.g., phone recordings) using a cleaning + training pipeline that generalizes to other audio datasets.

Who should use it

ML engineers/researchers interested in audio fault detectionDevelopers wanting to build or extend audio-ML pipelinesHobbyists and car enthusiasts experimenting with diagnostic toolsEducators teaching audio ML or signal processing

Who should avoid it

Professional mechanics needing a certified diagnostic toolUsers seeking a safety-critical or medical-grade diagnosis systemNon-technical users without Python or command-line experienceThose looking for a plug-and-play app with no setup

How it works

A quick walkthrough in plain English

How car-diagnosis works

Step 1 of 3

You interact with it

Open car-diagnosis, send a request, or connect it to your stack.

Features

End-to-end audio-ML pipeline for car fault diagnosis from audio

Automated scraping of fault-sound clips from YouTube/TikTok

Audio cleaning cascade to isolate mechanical sound from speech, music, and noise

Uses frozen CLAP model to generate 512-d embeddings

Trains lightweight linear heads for fault detection, localization, and part identification

Provides calibrated uncertainty estimates and returns "UNCERTAIN" when confidence low

Available as CLI tool and live web application

Supports ingesting custom audio recordings

Includes interactive demos for audio separation and CLAP embedding visualization

Ships with pre-trained model and synthetic demo clip for offline use

Advantages

Honest about limitations; avoids overconfident predictions
Calibrated probabilities with low expected calibration error (ECE ≈ 0.04)
Reusable cleaning + training recipe for other audio datasets
Works with noisy, real-world phone recordings (YouTube/TikTok style)
MIT license permits free use and modification
Quickstart: clone and run inference immediately with bundled model and demo
No external setup required for offline training/fixtures
Transparent documentation: model card, defense, architecture guides
Provides both fault detection and localization (zones, parts) with ranked lists
Interactive web UI for uploading clips and getting explanations

Disadvantages

Proof-of-concept; modest performance (AUROC 0.79 for fault detection) reflects difficulty of task
Not suitable for safety-critical or standalone diagnostic use
Limited to social‑style / targeted‑upload audio (YouTube, TikTok, deliberate phone clips)
Model accuracy varies by fault type; some heads (e.g., knock) were demoted due to poor out‑of‑sample performance
Requires Python 3.11 and specific dependencies (uv, joblib, etc.)
Performance ceiling limited by quality of scraped audio; clean engine audio yields higher AUROC (0.93) but real‑world phone clips are noisier
Small dataset (1,031 video groups) may limit generalization to unseen fault types
No GPU acceleration mentioned; inference may be CPU‑only and slower for long clips

Installation

native

git clone <repo> && cd car-diagnosis
uv venv && source .venv/bin/activate
uv pip install -e ".[scrape,web,dev,viz]"
cardiag doctor
cardiag train --fixtures
cardiag diagnose <clip.wav>
cardiag serve --model models

FAQ

How do I install cardiag and run a quick diagnosis?

Clone the repo, create a uv venv, install with `uv pip install -e \(.[scrape,web,dev,viz]\)`, then run `cardiag diagnose <clip.wav>` to get a verdict, region, and ranked parts.

What does the model return when it is unsure about a fault?

When the audio does not support a confident call, cardiag returns `UNCERTAIN` instead of bluffing; the model is calibrated (ECE ≈ 0.04) to know its limits.

How does the audio cleaning pipeline work?

The `clean()` cascade isolates short mechanical spans from noisy YouTube/TikTok or phone audio by removing speech, music, and road noise; spans longer than ~10 s are windowed so CLAP never truncates them.

What performance can I expect from cardiag on real‑world phone clips?

Out‑of‑sample AUROC for fault vs. normal is 0.79 (95 % CI 0.76‑0.83); the correct fault zone appears in the top‑3 about 75 % of the time, and the correct part family in the top‑3 about 45‑65 % of the time.

Can I add my own recordings or scrape new data to retrain the model?

Yes. Use `cardiag ingest ./my_audio --kind fault --cause <label>` to bring in your own clips, or `cardiag scrape youtube|tiktok` to build a corpus, then run `cardiag train` (or `cardiag train --fixtures` for a quick offline test).

Loading documentation…

View on GitHub