Update README.md

README.md

@@ -1,10 +1,107 @@
 ---
+base_model:
+- MarvinLvn/BabyHuBERT
+datasets:
+- PERCEPT-R
+language:
+- multilingual
+license: openrail
+metrics:
+- f1
+- accuracy
+pipeline_tag: audio-classification
 tags:
 - model_hub_mixin
 - pytorch_model_hub_mixin
+- child_speech
+- child_vocalization
+- speech_maturity
+library_name: transformers
 ---
 
-This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
-- Code: https://github.com/tiantiaf0627/childvox-release
-- Paper: [More Information Needed]
-- Docs: [More Information Needed]
+# BabyHuBERT for PERCEPT-R Classification (Audio classification of /ɹ/ in children)
+
+# Model Description
+This model includes the implementation for audio classification of /ɹ/ in children described in <a href="https://arxiv.org/abs/2605.29257"><strong>**ChildVox: A Speech, Audio, and Large Audio-Language Model Benchmark in Understanding and Characterizing Sound across Childhood**</strong></a> (Accepted to EMNLP 2026 Main)
+
+Github repository: https://github.com/tiantiaf0627/childvox-release
+
+The model is fine-tuned on the **PERCEPT-R** dataset, a large-scale corpus for audio classification of /ɹ/ in children.
+
+The included categories are:
+```
+[
+  'Derhotic',
+  'Rhotic'
+]
+```
+
+# How to use this model
+
+## Download repo
+```bash
+git clone git@github.com:tiantiaf0627/childvox-release
+```
+## Install the package
+```bash
+conda create -n childvox python=3.10
+cd childvox
+pip install -e .
+```
+
+## Load the model
+```python
+# Load libraries
+import torch
+import torch.nn.functional as F
+from src.model.childvox.hubert_audio import BabyHuBERTWrapper
+
+# Find device
+device = torch.device("cuda") if torch.cuda.is_available() else "cpu"
+
+# Load model from Huggingface
+# We provide model with different folds, and specify the fold from 1, 2, 3, 4, 5
+model = BabyHuBERTWrapper.from_pretrained("tiantiaf/childvox-percet_r-babyhubert", fold_idx=1).to(device)
+model.eval()
+```
+
+## Prediction
+```python
+# Label List
+label_list = [
+  'Derhotic',
+  'Rhotic'
+]
+
+# Load data, here just zeros as the example
+# The child word reading segments used in training are short, so we cap the input at 2 seconds
+# You need to prepare your audio to a length of 2 seconds, 16kHz and mono channel
+max_audio_length = 2 * 16000
+data = torch.zeros([1, 160000]).float().to(device)[:, :max_audio_length]
+logits, embeddings = model(data, return_feature=True)
+
+# Probability and output
+r_prob = F.softmax(logits, dim=1)
+print(label_list[torch.argmax(r_prob).detach().cpu().item()])
+```
+
+Responsible Use: Child speech data is highly sensitive. Users should respect the privacy and consent of the children and families whose recordings are processed, obtain approval from the appropriate ethics/IRB body, and adhere to the relevant laws and regulations in their jurisdictions when using ChildVox.
+
+## If you have any questions, please contact: Tiantian Feng (tiantiaf@usc.edu)
+
+❌ **Out-of-Scope Use**
+- Clinical or diagnostic applications (e.g., screening for developmental or language disorders)
+- Individual-level developmental assessment without expert human review
+- Surveillance
+- Privacy-invasive applications
+- No commercial use
+
+#### If you like our work or use the models in your work, kindly cite the following. We appreciate your recognition!
+```
+@article{feng2026childvox,
+  title={ChildVox: A Speech, Audio, and Large Audio-Language Model Benchmark in Understanding and Characterizing Sound across Childhood},
+  author={Feng, Tiantian and Xu, Anfeng and Shi, Xuan and Kommineni, Aditya and Siam, Shakhrul Iman and Micheletti, Megan and Shi, Zhonghao and Tager-Flusberg, Helen and Zhang, Mi and Perry, Lynn K and others},
+  journal={arXiv preprint arXiv:2605.29257},
+  year={2026}
+}
+```