marcosremar2/wav2vec2-pronunciation-pt

Wav2Vec2 Portuguese Pronunciation Assessment

Sistema de avaliação de pronúncia em português usando Wav2Vec2 para detecção de erros de pronúncia e feedback pedagógico.

Baseado em

• Phonological Level wav2vec2-based Mispronunciation Detection (Shahin et al., 2023)
• Assessment of L2 Oral Proficiency using Speech LLMs (2025)
• Speak & Improve Challenge 2025
• Mispronunciation Detection with Wav2Vec2 and LLM

Arquitetura

Áudio do Aluno
      │
      ▼
┌─────────────────────────────────────┐
│  Wav2Vec2 XLSR Phoneme Model        │
│  facebook/wav2vec2-xlsr-53-espeak   │
└─────────────────────────────────────┘
      │
      ▼
  Fonemas Falados (IPA)
      │
      │                    Texto Esperado
      │                         │
      │                         ▼
      │            ┌─────────────────────────┐
      │            │  eSpeak-ng Phonemizer   │
      │            └─────────────────────────┘
      │                         │
      │                         ▼
      │               Fonemas de Referência
      │                         │
      ▼                         ▼
┌─────────────────────────────────────┐
│   Needleman-Wunsch Alignment        │
│   (Alinhamento de Sequências)       │
└─────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────┐
│   Detecção de Erros                 │
│   - Substituições                   │
│   - Deleções                        │
│   - Inserções                       │
└─────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────┐
│   Feedback Pedagógico               │
│   - Score CEFR (A1-C2)              │
│   - Erros por palavra               │
│   - Dicas de articulação            │
└─────────────────────────────────────┘

Instalação

1. Dependências do Sistema

# macOS
brew install espeak-ng ffmpeg

# Ubuntu/Debian
sudo apt install espeak-ng ffmpeg

2. Dependências Python

pip install -r requirements.txt

3. Verificar Instalação

python tests/test_local.py

Uso

Uso Básico

from src.pipeline import PronunciationAssessmentPipeline

# Inicializar pipeline
pipeline = PronunciationAssessmentPipeline()

# Avaliar pronúncia
result = pipeline.assess(
    text="Bom dia",
    audio_path="recording.wav"
)

# Ver resultados
print(f"Accuracy: {result.scores['accuracy']}%")
print(f"CEFR Level: {result.scores['cefr_level']}")

for feedback in result.feedback:
    print(f"- {feedback}")

Gerar Áudios de Teste

from src.audio_generator import PortugueseAudioGenerator

generator = PortugueseAudioGenerator()

# Gerar áudio de teste
audio = generator.generate_wav("O rato roeu a roupa")
print(f"Saved to: {audio.file_path}")

Extração de Fonemas

from src.phoneme_extractor import PortuguesePhonemeExtractor

extractor = PortuguesePhonemeExtractor()

result = extractor.extract_phonemes("recording.wav")
print(f"Phonemes: {result['phoneme_string']}")

Modelos Disponíveis

Modelo	Descrição	Uso
multilingual_phoneme	facebook/wav2vec2-xlsr-53-espeak-cv-ft	Reconhecimento de fonemas multilíngue (387 labels IPA)
portuguese_asr	lgris/wav2vec2-large-xlsr-open-brazilian-portuguese	ASR para português brasileiro

Métricas

O sistema calcula as seguintes métricas:

• Accuracy: Percentual de fonemas corretos
• Phoneme Error Rate (PER): Taxa de erros fonêmicos
• Fluency Score: Estimativa de fluência
• Completeness: Percentual de fonemas não omitidos
• CEFR Level: Nível estimado (A1-C2)

Tipos de Erros Detectados

1. Substituição: Fonema trocado por outro
2. Deleção: Fonema omitido
3. Inserção: Fonema extra adicionado

Estrutura do Projeto

wav2vec2-portuguese-pronunciation/
├── src/
│   ├── __init__.py              # Exports
│   ├── phoneme_extractor.py     # Extração de fonemas via Wav2Vec2
│   ├── reference_phonemizer.py  # Geração de fonemas via eSpeak
│   ├── alignment.py             # Alinhamento Needleman-Wunsch
│   ├── audio_generator.py       # Geração de áudio com gTTS
│   └── pipeline.py              # Pipeline completo
├── tests/
│   └── test_local.py            # Testes locais
├── data/
│   └── audio/                   # Áudios gerados
├── requirements.txt
└── README.md

Referências

1. Shahin, M. et al. (2023). Phonological Level wav2vec2-based Mispronunciation Detection and Diagnosis Method. arXiv:2311.07037
2. Facebook AI (2021). wav2vec2-xlsr-53-espeak-cv-ft. HuggingFace
3. Lucas Gris (2021). wav2vec2-large-xlsr-open-brazilian-portuguese. HuggingFace

Licença

MIT License