You can deploy this model and start earning money today!

devnetint/
wavlm-dirosa

Name: wavlm-dirosa
Availability: InStock

safetensors

Views

No views yet

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
Arsitektur Pipeline
Struktur Direktori
Prasyarat
Instalasi
Penggunaan
- Antarmuka Web (Streamlit)
- Command Line Interface
Dataset Audio
Penjelasan Modul
Konfigurasi dan Parameter
Analisis Korelasi
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:

Pemuatan dan pra-pemrosesan audio -- resampling ke 16 kHz, konversi mono, VAD endpoint trimming, dan normalisasi amplitudo.
Ekstraksi fitur -- menggunakan model pretrained WavLM Base Plus (tersimpan lokal di folder wavlm-base-plus/) untuk menghasilkan representasi frame-level dari 12 layer transformer.
Pencocokan sekuens -- Dynamic Time Warping dengan jarak cosine dan batasan Sakoe-Chiba band.
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

Clone atau unduh repositori ini.
Buat virtual environment (direkomendasikan):

bash
1python -m venv venv 2# Windows 3venv\Scripts\activate 4# Linux / macOS 5source venv/bin/activate

Install dependensi:

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:

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:

python run_similarity.py audio_peserta.wav audio_referensi.wav

Opsi tambahan:

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

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 dan mengikuti lisensi yang ditetapkan oleh Microsoft Research.

devnetint/wavlm-dirosa