File size: 14,665 Bytes
1a0e6e8 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 | # 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.
|