marcosremar2/orpheus-ptbr-annotation-pipeline

Orpheus TTS - Pipeline de Anotação para Português Brasileiro

Pipeline completo para anotar datasets de fala em português brasileiro para fine-tuning do Orpheus TTS.

🎯 Objetivo

Melhorar datasets de TTS em português brasileiro adicionando:

• ✅ Anotações de emoções (felicidade, tristeza, raiva, etc.)
• ✅ Tags do Orpheus (<laugh>, <sigh>, <breath>, etc.)
• ✅ Metadados de áudio (qualidade, SNR, duração)
• ✅ Alinhamento fonético (timestamps de palavras e fonemas)
• ✅ Anotações prosódicas (pausas, taxa de fala)

📁 Estrutura do Projeto

orpheus-ptbr-annotation-pipeline/
├── scripts/
│   ├── 1_download_datasets.py      # Download de datasets
│   ├── 2_train_annotators.py       # Treinar modelos de anotação
│   ├── 3_annotate_dataset.py       # Anotar com emoções e metadados
│   ├── 4_add_orpheus_tags.py       # Adicionar tags do Orpheus
│   ├── 5_phonetic_alignment.py     # Alinhamento fonético
│   ├── 6_prosodic_annotation.py    # Anotações prosódicas
│   ├── 7_validation_tool.py        # Validação manual
│   └── 8_export_to_orpheus.py      # Exportar formato final
├── data/
│   ├── raw/                         # Datasets originais
│   ├── processed/                   # Datasets processados
│   └── annotated/                   # Dataset final anotado
├── models/
│   ├── emotion_classifier/          # Modelo de classificação de emoções
│   └── event_detector/              # Detector de eventos não-verbais
├── logs/                            # Logs de execução
└── configs/                         # Configurações

🚀 Instalação

1. Clone o repositório

git clone <repository-url>
cd orpheus-ptbr-annotation-pipeline

2. Instale as dependências

pip install -r requirements.txt

3. (Opcional) Instale Montreal Forced Aligner para alinhamento fonético

conda install -c conda-forge montreal-forced-aligner
mfa model download acoustic portuguese_brazil_mfa
mfa model download dictionary portuguese_brazil_mfa

📋 Uso

Pipeline Completo

Execute os scripts em ordem:

1. Download de Datasets

cd scripts
python 1_download_datasets.py --dataset marcosremar2/orpheus-tts-portuguese-dataset

Este script irá:

• Baixar seu dataset do HuggingFace
• Criar instruções para obter VERBO e emoUERJ
• Preparar estrutura de diretórios

2. Treinar Anotadores

python 2_train_annotators.py

Este script irá:

• Carregar modelo pré-treinado de emotion recognition (wav2vec2)
• Configurar detector de eventos não-verbais
• Salvar modelos em ../models/

3. Anotar Dataset

python 3_annotate_dataset.py --input ../data/raw/orpheus-portuguese-original/data.parquet

Para testar em uma amostra pequena:

python 3_annotate_dataset.py --max-samples 100

Este script irá:

• Detectar emoções em cada áudio
• Identificar eventos não-verbais (, , etc.)
• Extrair metadados de qualidade (SNR, clipping, etc.)

4. Adicionar Tags do Orpheus

python 4_add_orpheus_tags.py --input ../data/processed/annotated_dataset.parquet

Este script irá:

• Inserir tags do Orpheus no texto baseado nos eventos detectados
• Criar campo text_with_tags com anotações

5. Alinhamento Fonético

python 5_phonetic_alignment.py

Este script adiciona placeholders para alinhamento fonético (requer MFA instalado).

6. Anotações Prosódicas

python 6_prosodic_annotation.py

Este script irá:

• Detectar pausas e quebras prosódicas
• Calcular taxa de fala (palavras/segundo)

7. Validação Manual

python 7_validation_tool.py --num-samples 10

Ferramenta interativa para validar anotações e fazer correções manuais.

8. Exportar para Orpheus

python 8_export_to_orpheus.py --output-name orpheus_ptbr_annotated

Este script irá:

• Preparar dataset no formato do Orpheus TTS
• Salvar em múltiplos formatos (Parquet, CSV, HF Dataset)
• Criar dataset card (README.md)

📊 Formato do Dataset Final

O dataset anotado terá a seguinte estrutura:

{
    'audio': {
        'array': [...],  # Array de áudio
        'sampling_rate': 16000
    },
    'text': 'Olá <laugh> como você está? <breath>',  # Texto com tags
    'duration_seconds': 3.5,
    'metadata': {
        'emotion': 'happiness',
        'emotion_confidence': 0.92,
        'quality_estimate': 'high',
        'detected_events': ['<laugh>', '<breath>'],
        'speaking_rate': 4.2,  # palavras por segundo
        'estimated_snr_db': 28.5
    }
}

🎯 Tags do Orpheus Suportadas

Tag	Descrição	Exemplo
<laugh>	Risada	"Foi engraçado "
<chuckle>	Risadinha	"Bem talvez"
<sigh>	Suspiro	" Está bem"
<breath>	Respiração	"E então continuamos"
<cough>	Tosse	" Desculpe"
<gasp>	Ofegante	" Incrível!"

📦 Datasets Utilizados

Primário

• Seu dataset: marcosremar2/orpheus-tts-portuguese-dataset (118k samples)

Referência (para treinar anotadores)

• VERBO: 1.167 samples com 7 emoções
• emoUERJ: 377 samples com 4 emoções
• CORAA: Corpus grande de fala espontânea

🔧 Configuração Avançada

Modificar detecção de emoções

Edite scripts/2_train_annotators.py para usar outro modelo:

emotion_trainer.load_pretrained_model(
    model_name="seu-modelo/emotion-pt-br"
)

Ajustar detecção de eventos

Edite models/event_detector/event_detector_config.json:

{
  "events": {
    "<laugh>": {
      "threshold": 0.7
    }
  }
}

📈 Qualidade das Anotações

Anotações Automáticas

• Emoções: ~80-85% precisão (usando modelo pré-treinado)
• Eventos não-verbais: ~70% precisão (detector baseado em regras)
• Metadados de áudio: ~95% precisão

Melhorar Qualidade

1. Execute validação manual (script 7)
2. Faça fine-tuning com VERBO/emoUERJ (quando disponíveis)
3. Ajuste thresholds de detecção de eventos

🚀 Upload para HuggingFace

Após gerar o dataset final:

# Login no HuggingFace
huggingface-cli login

# Upload do dataset
cd data/annotated
huggingface-cli upload username/orpheus-ptbr-annotated .

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça fork do projeto
2. Crie uma branch para sua feature
3. Faça commit das mudanças
4. Abra um Pull Request

📝 Citação

Se usar este pipeline, por favor cite:

@misc{orpheus_ptbr_pipeline,
  title={Orpheus TTS Portuguese BR Annotation Pipeline},
  author={Pipeline de Anotação Orpheus PT-BR},
  year={2025},
  publisher={GitHub},
  url={https://github.com/username/orpheus-ptbr-annotation-pipeline}
}

📄 Licença

MIT License

🔗 Links Úteis

• Orpheus TTS GitHub
• Documentação Orpheus TTS
• VERBO Dataset
• CORAA Dataset
• Montreal Forced Aligner

❓ FAQ

P: O pipeline funciona com outros datasets?

R: Sim! Modifique o parâmetro --dataset no script 1 para usar qualquer dataset do HuggingFace.

P: Preciso dos datasets VERBO e emoUERJ?

R: Não são obrigatórios. O pipeline usa um modelo pré-treinado que já funciona bem para português brasileiro.

P: Quanto tempo leva para processar 118k amostras?

R: Depende do hardware. Com GPU: ~2-4 horas. Sem GPU: ~8-12 horas.

P: Posso usar CPU apenas?

R: Sim, mas será mais lento. Os modelos funcionam em CPU.

📧 Contato

Para dúvidas ou sugestões, abra uma issue no repositório.

---

Desenvolvido com ❤️ para a comunidade de TTS em Português Brasileiro