janitor

commit f0deb13814f78688ada4a75f7bac4956e22a8aea
parent 50d721e3346b065c5ceba659095b39371e488198
Author: Damian Myrda <damian@prime8.dev>
Date:   Tue,  6 Jan 2026 09:36:17 -0600

Improve README with architecture, usage, and quick start guide

Diffstat:
M
README.md
 | 
86
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-

1 file changed, 85 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
@@ -1,3 +1,87 @@
 # Janitor
 
-A tool for labelling files into three categories: speech, music, and noise.
+An audio classification tool that labels audio files into three categories: **speech**, **music**, and **noise**.
+
+## Overview
+
+Janitor uses the [Audio Spectrogram Transformer (AST)](https://github.com/YuanGongND/ast) model pretrained on AudioSet to classify audio content. It consists of two components:
+
+- **Service**: A GPU-accelerated inference server that runs the AST model with batched processing
+- **CLI**: A client that extracts mel-filterbank features from audio files and sends them to the service for classification
+
+## Architecture
+
+```
+┌─────────────────┐      safetensors      ┌─────────────────┐
+│   CLI Client    │  ─────────────────►   │  Inference      │
+│                 │                       │  Service        │
+│  - Audio decode │      HTTP POST        │                 │
+│  - Resample     │  ◄─────────────────   │  - AST Model    │
+│  - Fbank extract│      JSON label       │  - Batching     │
+└─────────────────┘                       └─────────────────┘
+```
+
+## Features
+
+- Classify individual files or entire directories recursively
+- Copy or move files to separate directories based on classification
+- Concurrent file processing with configurable parallelism
+- GPU acceleration with CUDA support
+- Batched inference for improved throughput
+
+## Quick Start
+
+### 1. Build and run the service
+
+```bash
+cd service
+
+# Build the model (requires conda)
+./build_model.sh
+
+# Run on CPU
+cargo build --release
+
+# Or with CUDA support
+TORCH_CUDA_VERSION=cu121 cargo build --release
+
+# Start the service
+cargo run --release
+```
+
+### 2. Run the CLI
+
+```bash
+cd cli
+cargo build --release
+
+# Classify a single file
+cargo run --release -- audio.mp3
+
+# Classify a directory
+cargo run --release -- /path/to/audio/
+
+# Move files to separate directories by label
+cargo run --release -- move /path/to/audio/ \
+  --speech-dir ./speech \
+  --music-dir ./music \
+  --noise-dir ./noise
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `cli/` | Command-line client for audio processing and classification |
+| `service/` | Inference server running the AST model |
+| `cli/fbank/` | Rust bindings to kaldi-native-fbank for feature extraction |
+
+## Requirements
+
+- Rust 1.70+
+- Conda (for building the model)
+- CUDA 11.8 or 12.1 (optional, for GPU acceleration)
+
+## License
+
+See [LICENSE](LICENSE) for details.