README.md

# Metode Penilaian Kemiripan Bacaan Al-Qur'an pada Pembelajaran DIROSA Menggunakan Representasi Audio WavLM dan Dynamic Time Warping

Repositori ini berisi implementasi dari penelitian skripsi berjudul **"Metode Penilaian Kemiripan Bacaan Al-Qur'an pada Pembelajaran DIROSA Menggunakan Representasi Audio WavLM dan Dynamic Time Warping"**.

Metode yang diajukan mengukur seberapa mirip bacaan Al-Qur'an seorang peserta DIROSA terhadap bacaan referensi, melalui pendekatan berbasis *deep audio representation learning*. Fitur audio diekstraksi menggunakan model pretrained **WavLM**, kemudian dibandingkan secara sekuensial menggunakan **Dynamic Time Warping (DTW)** untuk menghasilkan skor kemiripan.

---

## Daftar Isi

- [Gambaran Umum](#gambaran-umum)
- [Arsitektur Pipeline](#arsitektur-pipeline)
- [Struktur Direktori](#struktur-direktori)
- [Prasyarat](#prasyarat)
- [Instalasi](#instalasi)
- [Penggunaan](#penggunaan)
  - [Antarmuka Web (Streamlit)](#antarmuka-web-streamlit)
  - [Command Line Interface](#command-line-interface)
- [Dataset Audio](#dataset-audio)
- [Penjelasan Modul](#penjelasan-modul)
- [Konfigurasi dan Parameter](#konfigurasi-dan-parameter)
- [Analisis Korelasi](#analisis-korelasi)
- [Lisensi](#lisensi)

---

## Gambaran Umum

Metode ini membandingkan dua rekaman audio bacaan Al-Qur'an dan menghasilkan skor kemiripan pada skala 0--100. Pipeline pemrosesan meliputi empat tahap utama:

1. **Pemuatan dan pra-pemrosesan audio** -- resampling ke 16 kHz, konversi mono, VAD endpoint trimming, dan normalisasi amplitudo.
2. **Ekstraksi fitur** -- menggunakan model pretrained WavLM Base Plus (tersimpan lokal di folder `wavlm-base-plus/`) untuk menghasilkan representasi frame-level dari 12 layer transformer.
3. **Pencocokan sekuens** -- Dynamic Time Warping dengan jarak cosine dan batasan Sakoe-Chiba band.
4. **Penilaian** -- konversi jarak DTW ternormalisasi ke skor 0--100 melalui pemetaan logistik (sigmoid) yang telah dikalibrasi.

---

## Arsitektur Pipeline

```
Audio WAV (Peserta)  ──┐
                       ├──> AudioLoader ──> WavLMEncoder ──> DTWSimilarity ──> SimilarityScorer
Audio WAV (Referensi) ─┘    (16 kHz,       (frame-level     (cosine DTW,     (sigmoid score
                             mono, VAD,      features,        Sakoe-Chiba)      0-100)
                             normalisasi)    layer 1-12)
```

---

## Struktur Direktori

```
kode_inti_yudisium/
|
|-- app.py                    # Antarmuka web Streamlit (single, batch, korelasi)
|-- run_similarity.py         # CLI untuk single/batch processing
|-- scoring.py                # Orchestrator pipeline end-to-end
|-- wavlm_encoder.py          # Ekstraksi fitur WavLM (frozen, multi-layer)
|-- dtw_similarity.py          # DTW dengan Sakoe-Chiba band dan konversi skor
|-- audio_loader.py           # Pemuatan audio, VAD trimming, normalisasi
|-- correlation_analysis.py   # Analisis korelasi Spearman/Pearson dan visualisasi
|-- create_dataset.py         # Skrip pembuatan dataset final (merge skor + rating)
|-- dataset_final.csv         # Dataset gabungan skor sistem dan rating Ustadz
|-- requirements.txt          # Daftar dependensi Python
|
|-- audio referensi/          # 20 file WAV bacaan referensi (Pertemuan 1-20)
|-- audio peserta/            # Rekaman peserta, terorganisir per subfolder
|   |-- peserta 1/
|   |-- peserta 2/
|   |-- peserta 3/
|   |-- peserta 4/
|   |-- peserta 5/
|
|-- README.md
```

---

## Prasyarat

- **Python** 3.9 atau lebih baru
- **PyTorch** dengan dukungan CUDA (opsional, untuk akselerasi GPU)
- Koneksi internet diperlukan saat pertama kali menjalankan program untuk mengunduh model WavLM dari HuggingFace Hub

> Model WavLM secara otomatis berjalan di GPU jika PyTorch CUDA tersedia.
> Jika tidak, sistem akan fallback ke CPU secara transparan.

---

## Instalasi

1. Clone atau unduh repositori ini.

2. Buat virtual environment (direkomendasikan):

   ```bash
   python -m venv venv
   # Windows
   venv\Scripts\activate
   # Linux / macOS
   source venv/bin/activate
   ```

3. Install dependensi:

   ```bash
   pip install -r requirements.txt
   ```

   Dependensi utama:

   | Paket              | Versi    | Fungsi                                      |
   |--------------------|----------|---------------------------------------------|
   | `torch`            | 2.12.0   | Backend deep learning, komputasi tensor     |
   | `torchaudio`       | 2.11.0   | Pemuatan dan resampling audio               |
   | `transformers`     | 4.57.3   | Model WavLM dari HuggingFace               |
   | `numpy`            | 2.3.5    | Operasi numerik dan array                   |
   | `scipy`            | 1.16.3   | Uji statistik (Spearman, Pearson)           |
   | `pandas`           | 2.3.3    | Manipulasi data tabular                     |
   | `soundfile`        | 0.13.1   | Pembacaan file audio WAV (fallback loader)  |
   | `webrtcvad-wheels` | 2.0.14   | Voice Activity Detection (endpoint trimming)|
   | `streamlit`        | 1.52.2   | Antarmuka web interaktif                    |
   | `matplotlib`       | 3.10.8   | Visualisasi grafik dan plot                 |

---

## Penggunaan

### Antarmuka Web (Streamlit)

Jalankan aplikasi web interaktif:

```bash
streamlit run app.py
```

Aplikasi menyediakan tiga tab utama:

| Tab                              | Fungsi                                                                                 |
|----------------------------------|----------------------------------------------------------------------------------------|
| **Single Processing**            | Upload dua file audio (referensi dan peserta), pilih layer, lihat skor dan visualisasi |
| **Batch Processing (Folder)**    | Proses seluruh folder `audio peserta/` terhadap `audio referensi/`, ekspor CSV         |
| **Analisis Korelasi (Overview)** | Visualisasi hubungan skor sistem vs rating Ustadz (Spearman, Pearson, heatmap)         |

Fitur antarmuka:

- Preview waveform sebelum dan sesudah pra-pemrosesan (VAD + normalisasi)
- Pemilihan layer WavLM (1--12) secara individual atau seluruhnya
- Visualisasi alignment path DTW dan cost matrix heatmap
- Diagnostik internal DTW (opsional)
- Interpretasi skor otomatis (Sangat Mirip, Mirip, Cukup Mirip, Kurang Mirip)

### Command Line Interface

**Mode Single** -- bandingkan dua file audio:

```bash
python run_similarity.py audio_peserta.wav audio_referensi.wav
```

Opsi tambahan:

```bash
python run_similarity.py audio1.wav audio2.wav --detailed --json
```

**Mode Batch** -- proses seluruh folder:

```bash
python run_similarity.py \
    --participant-dir "audio peserta" \
    --reference-dir "audio referensi" \
    --recursive \
    --output hasil_batch.csv
```

Parameter CLI yang tersedia:

| Parameter            | Default                       | Keterangan                                       |
|----------------------|-------------------------------|--------------------------------------------------|
| `--model`            | `./wavlm-base-plus`          | Model WavLM (path lokal, sudah tersedia di repo)     |
| `--device`           | auto-detect                   | Device komputasi (`cuda` / `cpu`)                |
| `--distance`         | `cosine`                      | Metrik jarak DTW (`cosine` / `euclidean`)        |
| `--no-normalize`     | _disabled_                    | Nonaktifkan normalisasi jarak DTW                |
| `--detailed`         | _disabled_                    | Tampilkan metrik detail (single mode)            |
| `--json`             | _disabled_                    | Output dalam format JSON                         |
| `--recursive`        | _disabled_                    | Cari file WAV secara rekursif (batch mode)       |
| `--output`           | `similarity_results.csv`      | Path output batch (`.csv` / `.xlsx`)             |

---

## Dataset Audio

Dataset audio yang digunakan dalam penelitian ini terdiri dari 20 frasa bacaan DIROSA (Pertemuan 1--20) yang dibacakan oleh 5 peserta, masing-masing dibandingkan terhadap satu audio referensi per frasa.

**Unduh dataset audio:**

[https://drive.google.com/drive/folders/1wO7WvfKn4bnWfLxaVSHSOqn0psosf8oB?usp=sharing](https://drive.google.com/drive/folders/1wO7WvfKn4bnWfLxaVSHSOqn0psosf8oB?usp=sharing)

Setelah diunduh, letakkan isi folder sesuai struktur berikut:

```
kode_inti_yudisium/
|-- audio referensi/
|   |-- Dirosa Pertemuan 1.wav
|   |-- Dirosa Pertemuan 2.wav
|   |-- ...
|   |-- Dirosa Pertemuan 20.wav
|
|-- audio peserta/
|   |-- peserta 1/
|   |   |-- Dirosa Pertemuan 1.wav
|   |   |-- Dirosa Pertemuan 2.wav
|   |   |-- ...
|   |-- peserta 2/
|   |-- ...
```

Format audio: **WAV, mono, 16-bit PCM**. Audio akan di-resample ke 16 kHz secara otomatis jika diperlukan.

---

## Penjelasan Modul

### `audio_loader.py` -- AudioLoader

Bertanggung jawab atas seluruh tahap pra-pemrosesan audio:

- **Pemuatan audio**: menggunakan `soundfile` sebagai loader utama (tanpa dependensi FFmpeg), dengan fallback ke `torchaudio`.
- **Resampling**: konversi otomatis ke 16 kHz (target sample rate WavLM).
- **Konversi mono**: audio stereo dirata-ratakan menjadi satu kanal.
- **VAD Endpoint Trimming**: menggunakan WebRTC VAD dengan mekanisme hysteresis (onset/offset) untuk menghapus segmen hening di awal dan akhir tanpa memotong jeda internal.
- **Energy Refinement**: pemangkasan berbasis RMS envelope untuk menghilangkan sisa noise atau napas yang lolos dari VAD.
- **Normalisasi amplitudo**: penskalaan waveform ke rentang [-1, 1].

### `wavlm_encoder.py` -- WavLMEncoder

Mengekstraksi fitur frame-level menggunakan model pretrained WavLM (frozen, tanpa fine-tuning):

- Mendukung ekstraksi dari satu layer tertentu atau beberapa layer sekaligus.
- Model berjalan di GPU secara otomatis jika CUDA tersedia.
- Pipeline PyTorch-only (TensorFlow/Flax dinonaktifkan secara eksplisit).

### `dtw_similarity.py` -- DTWSimilarity

Modul inti pencocokan sekuens:

- **Cost matrix**: jarak cosine atau Euclidean (vectorised).
- **DTW dengan Sakoe-Chiba band**: membatasi jalur warping untuk efisiensi dan menghindari alignment yang tidak realistis.
- **Backtracking**: rekonstruksi optimal warping path.
- **Konversi skor**: pemetaan logistik (sigmoid) dari jarak ternormalisasi ke skala 0--100.

Kalibrasi default (midpoint=0.3, steepness=10.0):

| Jarak (d)    | Skor     | Interpretasi        |
|--------------|----------|---------------------|
| ~ 0.05       | ~ 92     | Sangat mirip        |
| ~ 0.15       | ~ 82     | Mirip               |
| ~ 0.30       | = 50     | Borderline          |
| ~ 0.35       | ~ 38     | Kurang mirip        |
| > 0.50       | < 12     | Sangat berbeda      |

### `scoring.py` -- SimilarityScorer

Orchestrator yang menghubungkan seluruh komponen pipeline:

- `compute_similarity()` -- mengembalikan jarak DTW mentah.
- `compute_similarity_score_normalized()` -- mengembalikan skor 0--100.
- `compute_detailed_similarity()` -- mengembalikan hasil lengkap per layer termasuk warping path, cost matrix, diagnostik, dan waveform.

### `correlation_analysis.py`

Modul analisis statistik untuk validasi metode:

- Korelasi **Spearman** (monotonic) dan **Pearson** (linear) antara skor sistem dan rating Ustadz.
- Visualisasi: bar chart, scatter plot, heatmap, dan diagram pasangan frasa.

### `create_dataset.py`

Skrip utilitas untuk menggabungkan hasil batch processing (skor per layer) dengan rating manual Ustadz menjadi satu dataset (`dataset_final.csv`).

### `run_similarity.py`

CLI entry point yang mendukung mode single (dua file) dan batch (dua folder), dengan output CSV/XLSX.

### `app.py`

Antarmuka web berbasis Streamlit yang menyatukan seluruh fungsionalitas pipeline dalam tampilan interaktif.

---

## Konfigurasi dan Parameter

Parameter utama pipeline dikonfigurasi melalui `SimilarityScorer`:

| Parameter            | Default                       | Keterangan                                                |
|----------------------|-------------------------------|-----------------------------------------------------------|
| `model_name`         | `./wavlm-base-plus`          | Model WavLM (path lokal, sudah tersedia di repo)            |
| `distance_metric`    | `cosine`                      | Metrik jarak untuk DTW                                   |
| `sakoe_chiba_ratio`  | `0.1`                         | Lebar band Sakoe-Chiba (fraksi dari panjang sekuens)     |
| `normalize_dtw`      | `True`                        | Normalisasi jarak DTW berdasarkan panjang warping path   |
| `score_midpoint`     | `0.3`                         | Titik tengah sigmoid (jarak yang menghasilkan skor 50)   |
| `score_steepness`    | `10.0`                        | Ketajaman transisi sigmoid                               |

Parameter VAD (dikonfigurasi melalui `AudioLoader`):

| Parameter                | Default | Keterangan                                                      |
|--------------------------|---------|-----------------------------------------------------------------|
| `vad_mode`               | `1`     | Agresivitas WebRTC VAD (0--3, 1--2 direkomendasikan)            |
| `vad_frame_ms`           | `10`    | Panjang frame VAD dalam milidetik (10, 20, atau 30)             |
| `vad_onset_frames`       | `2`     | Jumlah frame voiced berturut-turut untuk mendeteksi onset       |
| `vad_offset_frames`      | `4`     | Jumlah frame unvoiced berturut-turut untuk mendeteksi offset    |
| `energy_trim_threshold`  | `0.06`  | Threshold energi untuk pemangkasan tambahan pasca-VAD           |

---

## Analisis Korelasi

File `dataset_final.csv` berisi 101 pasangan data (5 peserta x ~20 frasa) dengan kolom:

| Kolom           | Keterangan                                         |
|-----------------|-----------------------------------------------------|
| `ID_Pasangan`   | Identifier unik pasangan peserta-frasa              |
| `ID_Peserta`    | ID peserta (1--5)                                   |
| `ID_Frasa`      | Nama file frasa (Dirosa Pertemuan X.wav)            |
| `Score L1`--`Score L12` | Skor kemiripan dari masing-masing layer WavLM |
| `rating`        | Penilaian manual Ustadz (ground truth)              |

Analisis korelasi Spearman digunakan untuk mengidentifikasi layer WavLM yang paling berkorelasi dengan penilaian manusia, sehingga dapat dipilih representasi yang paling relevan secara perseptual.

---

## Lisensi

Proyek ini dikembangkan untuk keperluan akademis (skripsi). Model WavLM Base Plus (`wavlm-base-plus/`) bersumber dari [microsoft/wavlm-base-plus](https://huggingface.co/microsoft/wavlm-base-plus) dan mengikuti lisensi yang ditetapkan oleh Microsoft Research.