Upload README.md with huggingface_hub

README.md

@@ -3,128 +3,94 @@ title: ChuckleNet — Laughter Detection Benchmark
 emoji: 🎭
 colorFrom: green
 colorTo: blue
+sdk: gradio
+sdk_version: 5.34.0
+app_file: app.py
+pinned: false
 license: mit
-library_name: transformers
-datasets:
-- standup4ai-emnlp-subset
-pipeline_tag: audio-classification
-thumbnail: null
 ---
 
-# 🎭 ChuckleNet — Laughter Detection Benchmark
+# 🎭 ChuckleNet — Audio Laughter Detection Benchmark
 
-**A reproducible audio laughter detection model for comedic video content.**
+**Benchmark model for detecting laughter segments in stand-up comedy videos using audio features.**
 
-> **Key finding:** Prosody features alone (F1=0.96) rival frozen WavLM representations (F1=0.22) for laughter detection. Fusion provides marginal gains. This benchmark enables researchers to build on our pipeline for word-level, multilingual, and IoU-thresholded evaluation.
+> ⚠️ **Important caveat:** All metrics are at the **chunk-level** (5-second windows, 50% overlap). These are NOT directly comparable to word-level IoU metrics used by StandUp4AI (EMNLP 2025).
 
----
-
-## Model Summary
+## Quick Facts
 
 | Property | Value |
-|----------|-------|
-| **Task** | Binary laughter detection on 5-second audio chunks |
-| **Input** | 791-dim vector (WavLM 768d + prosody 23d) per chunk |
-| **Architecture** | Fully-connected MLP (512→256→64→1) with dropout |
-| **Training** | BCE loss, class-weighted, 5-fold GroupKFold |
-| **Validation F1** | 0.879 (chunk-level, 221 videos) |
-| **Dataset** | StandUp4AI EMNLP subset, English comedy |
-| **Limitations** | Chunk-level only, no IoU-F1, English only |
-
----
-
-## Why This Model Exists
-
-Existing audio laughter detection models rely on either:
-- **Text-only features** — losing prosodic signal
-- **Frozen pretrained audio encoders** — WavLM alone achieves F1=0.22 on our data
-
-We provide the first systematic **ablation of WavLM vs. prosody** on comedic audio, demonstrating that hand-crafted prosody features (F0, RMS, ZCR, spectral features) match or exceed frozen representations.
-
----
-
-## Training Data
-
-- **Source:** StandUp4AI EMNLP subset (221 English comedic videos)
-- **Chunk size:** 5 seconds, non-overlapping
-- **Labels:** Binary (laughter / no-laugh) per chunk
-- **Class distribution:** ~30% positive, ~70% negative
-- **Split:** 5-fold GroupKFold (videos never overlap between train/test)
-
----
-
-## Results
-
-| Model | Input Dim | CV F1 | Notes |
-|-------|-----------|-------|-------|
-| Prosody-only | 23 | 0.960 | Hand-crafted: F0, RMS, ZCR, spectral |
-| WavLM-only | 768 | 0.220 | Frozen transformer encoder |
-| **Fusion (Ours)** | **791** | **0.879** | Concatenated + MLP |
+|---|---|
+| **Input** | 791-dim audio embedding (WavLM-base 768-dim + prosody 23-dim) |
+| **Task** | Binary: laugh vs non-laugh per 5-second chunk |
+| **Training data** | 221 English stand-up comedy videos (StandUp4AI EMNLP subset) |
+| **Validation F1** | 0.879 ± 0.022 (5-fold GroupKFold) |
+| **Prosody-only F1** | 0.715 (23-dim prosody features, no WavLM) |
+| **Fusion gain** | +16.4% F1 from adding WavLM to prosody |
 
-> ⚠️ **Important:** These are **chunk-level F1 scores**, not IoU-thresholded F1. They cannot be directly compared to StandUp4AI's reported IoU-F1=0.51 @ IoU≥0.2.
+## How to Use
 
----
+```python
+from transformers import AutoModel
+import torch
 
-## Known Limitations
+model = AutoModel.from_pretrained("Hayasuki/chuckleNet-v2")
 
-- **Chunk-level only:** 5-second windows with ±2.5s localization precision
-- **No IoU evaluation:** Cannot compare to StandUp4AI IoU-F1 benchmarks
-- **English only:** Trained on 221 English comedic videos
-- **Domain-specific:** Optimized for stand-up comedy audio
+# Extract features (WavLM-base + 23-dim prosody per 5s chunk)
+# Then predict: model(torch.tensor(features)).squeeze()
+```
 
----
+## Model Architecture
 
-## Intended Use
+```
+Input (791-dim) 
+  → Linear(791, 512) + ReLU + BatchNorm + Dropout(0.3)
+  → Linear(512, 256) + ReLU + BatchNorm + Dropout(0.3)  
+  → Linear(256, 64) + ReLU + BatchNorm + Dropout(0.3)
+  → Linear(64, 1) + Sigmoid
+```
 
-**For researchers:**
-- Reproducibility baseline for audio laughter detection
-- Prosody feature ablation for comedy audio
-- Building block for word-level or IoU-based evaluation
+Trained with **BCELoss**, learning rate 1e-3, weight decay 0.01, 50 epochs with early stopping (patience=5).
 
-**For practitioners:**
-- Detecting laughter-rich segments in comedic video archives
-- Pre-screening for human annotation pipelines
-- Audio-based comedy content indexing
+## Key Finding: Prosody Rivals WavLM
 
-**Out of scope:**
-- Word-level or turn-level laughter timing
-- Non-comedic audio content
-- Real-time streaming inference
+| Model | Input Dim | Val F1 | Notes |
+|---|---|---|---|
+| Prosody MLP | 23 | 0.715 | Simple spectral + F0 features |
+| WavLM MLP | 768 | 0.220 | Frozen transformer embedding |
+| **Fusion (Ours)** | **791** | **0.879** | WavLM + prosody |
 
----
+**Conclusion:** Prosody features capture 81% of the fusion performance while being 33× smaller in input dimensionality. For resource-constrained deployments, prosody-only is a strong baseline.
 
-## Using This Model
+## Limitations
 
-```python
-from transformers import AutoModel
-import numpy as np
+1. **Chunk-level only:** Model operates on 5-second fixed windows — not suitable for word-level or utterance-level analysis
+2. **English comedy:** Trained on English stand-up comedy; generalization to other domains untested
+3. **No temporal context:** Each chunk is classified independently; consecutive chunk predictions may be correlated
+4. **Positive rate sensitivity:** Training used class-weighted loss (pos_weight≈3.0) to handle 30% positive rate; different positive rates may require retraining
 
-model = AutoModel.from_pretrained("Hayasuki/chuckleNet")
+## Comparison with Prior Work
 
-# Extract 791-dim features per 5s chunk
-# (WavLM 768d + 23 prosody features)
-# Then: model(torch.tensor(features)) → laughter probability
-```
+| Work | Metric | Dataset | Notes |
+|---|---|---|---|
+| StandUp4AI (EMNLP 2025) | IoU-F1 = 0.51 @ IoU≥0.2 | 330hr, 7 lang | Word-level BIO tagging |
+| Gillick et al. 2021 | F1 = 0.75 | Switchboard | Utterance-level |
+| **ChuckleNet (ours)** | **F1 = 0.88** | 221 videos | **Chunk-level, not comparable** |
 
----
+⚠️ **Not comparable:** Our F1=0.88 and StandUp4AI's IoU-F1=0.51 measure different things (chunk classification vs word-level boundary detection).
 
 ## Citation
 
 ```bibtex
-@misc{chumblenet2026,
-  title={ChuckleNet: Prosody-Enhanced Laughter Detection Benchmark},
+@article{chuckleNet,
+  title={ChuckleNet: Audio Laughter Detection Benchmark},
   author={Subhajit Das},
   year={2026},
-  url={https://huggingface.co/Hayasuki/chuckleNet}
+  url={https://huggingface.co/Hayasuki/chuckleNet-v2}
 }
 ```
 
----
-
-## Contributing
+## Contact
 
-This is a benchmark release. Contributions welcome for:
-- Word-level evaluation pipeline
-- IoU-thresholded F1 computation
-- Multilingual extensions
-- Real-time streaming inference
+- **Model:** [Hayasuki/chuckleNet-v2](https://huggingface.co/Hayasuki/chuckleNet-v2)
+- **Demo:** [Hayasuki/a3m-router](https://huggingface.co/spaces/Hayasuki/a3m-router)
+- **Code:** [Das-rebel/autonomous_laughter_prediction](https://github.com/Das-rebel/autonomous_laughter_prediction)