Update to Pro-TeVA branding and add architecture diagram

README.md

@@ -1,5 +1,5 @@
 ---
-title: ProTeVa Yoruba Tone Recognition
+title: Pro-TeVA Yoruba Tone Recognition
 emoji: 🎵
 colorFrom: blue
 colorTo: green
@@ -8,12 +8,25 @@ sdk_version: 5.49.1
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: 'ProTeVa: AI-powered tone recognition for Yoruba language.'
+short_description: 'Pro-TeVA: AI-powered tone recognition for Yoruba language.'
 ---
 
-# ProTeVa: Yoruba Tone Recognition
+# Pro-TeVA: Yoruba Tone Recognition
 
-This Space demonstrates **ProTeVa** (Prototype-based Tone Variant Autoencoder), a neural model for recognizing tone patterns in Yoruba language with intelligent word boundary detection.
+This Space demonstrates **Pro-TeVA** (Prototype-based Temporal Variational Autoencoder), an explainable neural model for recognizing tone patterns in Yoruba language.
+
+## About Pro-TeVA
+
+Many sub-Saharan African languages, including Yoruba, are tonal languages where pitch variations determine word meanings. These languages are typically low-resourced, making automatic tone recognition challenging yet crucial for speech processing applications.
+
+**Pro-TeVA** addresses this challenge by providing both high-performance tone recognition and explainable results that linguists can understand and trust. Unlike black-box models, Pro-TeVA offers transparency through:
+
+- **Interpretable Features**: Uses fundamental frequency (F0) as an acoustic feature that linguists can easily understand
+- **Visualizable Prototypes**: 10 learnable tone prototypes that cluster sound patterns in an interpretable way
+- **F0 Reconstruction**: Decoder outputs that explain model decisions through pitch contour predictions
+- **High Performance**: Achieves 17.74% Tone Error Rate, comparable to black-box models
+
+This transparency facilitates collaboration between computational and linguistic disciplines and accelerates dataset creation for low-resource tonal languages by enabling efficient pre-labeling of tones on transcriptions.
 
 ## Features
 
@@ -33,17 +46,22 @@ Yoruba is a tonal language with three contrastive tones:
 
 ## Model Architecture
 
-- **Feature Extractor**: HuBERT (Orange/SSA-HuBERT-base-60k)
-- **Encoder**: 2-layer Bidirectional GRU (512 hidden units)
-- **Decoder**: VanillaNN (2 blocks, 512 neurons)
-- **Prototype Layer**: 10 learnable tone prototypes
-- **F0 Reconstruction**: TorchYIN pitch estimation
-- **Output**: CTC-based sequence prediction
-- **Space Detection**: Multi-method acoustic boundary detection
+![Pro-TeVA Architecture](proteva_archi.png)
+
+Pro-TeVA integrates multiple components for explainable tone recognition:
+
+- **Feature Extractor**: HuBERT (Orange/SSA-HuBERT-base-60k) - Self-supervised speech representation
+- **Encoder**: 2-layer Bidirectional GRU (512 hidden units) - Captures temporal dependencies
+- **Variational Autoencoder**: Learns compact latent representations (z) of tone patterns
+- **Prototype Layer**: 10 learnable tone prototypes (P₁, P₂, ..., P₁₀) for clustering sound patterns
+- **Decoder**: VanillaNN (2 blocks, 512 neurons) - Reconstructs F0 contours for interpretability
+- **Classification Layer**: Linear + Softmax → CTC for sequence prediction
+- **F0 Extraction**: TorchYIN pitch estimation for interpretable acoustic features
+- **Space Detection**: Multi-method acoustic boundary detection (post-processing)
 
 ## Space Detection
 
-ProTeVa uses intelligent post-processing to detect word boundaries:
+Pro-TeVA uses intelligent post-processing to detect word boundaries:
 
 ### Detection Methods
 
@@ -125,7 +143,7 @@ If you use this model in your research, please cite:
 
 ```bibtex
 @article{proteva2025,
-  title={ProTeVa: Prototype-based Tone Variant Autoencoder for Yoruba Tone Recognition},
+  title={Pro-TeVA: Prototype-based Temporal Variational Autoencoder for Yoruba Tone Recognition},
   author={Your Name},
   year={2025},
   note={Hugging Face Space}

app.py

@@ -1,5 +1,5 @@
 """
-Gradio App for ProTeVa Yoruba Tone Recognition
+Gradio App for Pro-TeVA Yoruba Tone Recognition
 Hugging Face Spaces deployment
 """
 
@@ -17,7 +17,7 @@ TONE_INFO = config.TONE_INFO
 
 # ============ MODEL LOADING ============
 
-print("Loading ProTeVa tone recognition model...")
+print("Loading Pro-TeVA tone recognition model...")
 print(f"Checkpoint folder: {config.CHECKPOINT_FOLDER}")
 
 try:
@@ -204,11 +204,11 @@ custom_css = """
 }
 """
 
-with gr.Blocks(css=custom_css, title="ProTeVa Tone Recognition") as demo:
+with gr.Blocks(css=custom_css, title="Pro-TeVA Tone Recognition") as demo:
 
     gr.Markdown(
         f"""
-        # 🎵 ProTeVa: Yoruba Tone Recognition
+        # 🎵 Pro-TeVA: Yoruba Tone Recognition
 
         Upload an audio file or record your voice to detect Yoruba tone patterns.
 
@@ -272,31 +272,48 @@ with gr.Blocks(css=custom_css, title="ProTeVa Tone Recognition") as demo:
     gr.Markdown("### 📚 Example Audios")
     gr.Markdown("*Upload Yoruba speech samples to test the model*")
 
-    gr.Markdown(
-        f"""
-        ---
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown(
+                f"""
+                ---
 
-        **About ProTeVa:**
+                **About Pro-TeVA:**
 
-        ProTeVa (Prototype-based Tone Variant Autoencoder) is a neural model for tone recognition.
+                **Pro-TeVA** (Prototype-based Temporal Variational Autoencoder) is an explainable neural model for tone recognition.
 
-        **Model Architecture:**
-        - Feature Extractor: HuBERT (Orange/SSA-HuBERT-base-60k)
-        - Encoder: {config.RNN_LAYERS}-layer Bidirectional GRU ({config.RNN_NEURONS} neurons)
-        - Prototype Layer: {config.N_PROTOTYPES} learnable tone prototypes
-        - Decoder: F0 reconstruction
-        - Output: CTC-based tone sequence prediction + acoustic space detection
+                Unlike black-box models, Pro-TeVA provides transparency through:
+                - Interpretable F0 (pitch) features
+                - Visualizable tone prototypes
+                - F0 reconstruction for explainability
+                - High performance: 17.74% Tone Error Rate
 
-        **Space Detection:**
-        - Method: {config.SPACE_DETECTION_METHOD if config.ENABLE_SPACE_DETECTION else 'Disabled'}
-        - Uses F0 contours, silence patterns, and tone duration
-        - Automatically detects word boundaries in continuous speech
+                **Model Architecture:**
+                - Feature Extractor: HuBERT (Orange/SSA-HuBERT-base-60k)
+                - Encoder: {config.RNN_LAYERS}-layer Bidirectional GRU ({config.RNN_NEURONS} neurons)
+                - Variational Autoencoder: Compact latent representations
+                - Prototype Layer: {config.N_PROTOTYPES} learnable tone prototypes
+                - Decoder: F0 reconstruction (VanillaNN)
+                - Output: CTC-based sequence prediction
 
-        Built with ❤️ using SpeechBrain and Gradio
+                **Space Detection:**
+                - Method: {config.SPACE_DETECTION_METHOD if config.ENABLE_SPACE_DETECTION else 'Disabled'}
+                - Uses F0 contours, silence patterns, and tone duration
+                - Automatically detects word boundaries in continuous speech
+
+                Built with ❤️ using SpeechBrain and Gradio
+
+                **Model Checkpoint:** {config.CHECKPOINT_FOLDER}
+                """
+            )
+
+        with gr.Column(scale=1):
+            gr.Image(
+                value="proteva_archi.png",
+                label="Pro-TeVA Architecture",
+                show_label=True
+            )
 
-        **Model Checkpoint:** {config.CHECKPOINT_FOLDER}
-        """
-    )
 
 if __name__ == "__main__":
     demo.launch(