206 lines
9.3 KiB
Markdown
Executable File
206 lines
9.3 KiB
Markdown
Executable File
# mmpCreator & MMPSearch - Documentação Técnica
|
|
|
|
ALICE MMPSearch é um repositório criado com o propósito de servir como uma Biblioteca de Projetos e Beats do LMMS, utilizando Jekyll. O intuito é coletar informações dos arquivos indexando-os e permitindo buscas com os mais diversos filtros.
|
|
|
|
Este projeto faz parte da pesquisa de mestrado em Ciência da Computação na Universidade Federal de São João del-Rei (UFSJ), focada na produção musical independente underground e no uso de tecnologias de código aberto.
|
|
|
|
_The mainstream only exists because the underground created the scene._
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitetura e Engenharia de Dados
|
|
|
|
O sistema é um ecossistema completo para mineração, submissão, processamento e colaboração em projetos musicais (LMMS), estruturado nos seguintes pilares:
|
|
|
|
### 1. Web Crawler (Mineração de Dados)
|
|
|
|
O script `crawler.py` atua como um bot de mineração para popular a base de dados da plataforma baixando projetos diretamente do repositório oficial (LMMS Sharing Platform - `lmms.io/lsp/`).
|
|
|
|
- **Segurança e Estabilidade:** O crawler é multiprocessado e possui um sistema de _throttle_ que pausa a execução caso a memória RAM livre do servidor caia abaixo de 500MB.
|
|
- **Sanitização e Auditoria:** Utiliza `BeautifulSoup4` para extração de links e gera relatórios de performance em CSV.
|
|
|
|
### 2. Pipeline ETL e Motor de Renderização
|
|
|
|
A conversão dos arquivos nativos em artefatos web é orquestrada pelo script `pipeline_etl.sh`, executando o processamento em lotes:
|
|
|
|
1. **Extração e Renderização (`handler/main.py`):** Invoca o LMMS em modo `offscreen` para gerar áudio e converte o XML `.mmp` em JSON/YAML.
|
|
2. **Análise e Inteligência Artificial:** Utiliza a biblioteca **Essentia (Tensorflow)** para extração de características acústicas e classificação de áudio.
|
|
|
|
---
|
|
|
|
## 📦 Ecossistema Python e Dependências (venv)
|
|
|
|
O ambiente virtual (`venv`) contém as bibliotecas necessárias para o ciclo de vida do dado. As principais dependências instaladas são:
|
|
|
|
### Web & API Framework
|
|
|
|
- **Flask (v3.1.2):** Engine principal da API.
|
|
- **Flask-SocketIO:** Suporte a comunicação bi-direcional via WebSockets.
|
|
- **Gunicorn:** Servidor HTTP WSGI para produção.
|
|
- **Flask-Admin & WTForms:** Interface de gerenciamento e validação de formulários.
|
|
|
|
### Segurança e Persistência
|
|
|
|
- **SQLAlchemy (v2.0):** ORM para manipulação do banco `users.db`.
|
|
- **Flask-Bcrypt & Cryptography:** Hashing de senhas e camadas de criptografia.
|
|
|
|
### Processamento e Ciência de Dados
|
|
|
|
- **Essentia-Tensorflow:** Biblioteca avançada para análise de áudio e music information retrieval (MIR).
|
|
- **NumPy:** Suporte para arrays multidimensionais e cálculos matemáticos pesados.
|
|
- **PyYAML:** Geração de metadados para integração com o Jekyll.
|
|
|
|
### Utilidades e Monitoramento
|
|
|
|
- **Psutil:** Monitoramento de hardware para controle de processos paralelos.
|
|
- **Watchdog:** Monitoramento de eventos no sistema de arquivos.
|
|
- **tqdm:** Barras de progresso para tarefas de longa duração no terminal.
|
|
|
|
---
|
|
|
|
## ⚙️ Serviços de Hospedagem (Produção)
|
|
|
|
A infraestrutura é mantida via `systemd` para garantir alta disponibilidade.
|
|
|
|
### API de Upload e Processamento (Gunicorn)
|
|
|
|
- **Serviço:** `upload_mmpSearch.service`
|
|
- **Porta:** 33002
|
|
- **Timeout:** 300s (Essencial para o tempo de renderização do LMMS)
|
|
|
|
### Backend de Colaboração (NodeJS)
|
|
|
|
- **Serviço:** `backend-MMPCreator.service`
|
|
- **Porta:** 33001
|
|
- **Tecnologia:** Sincronização via Socket.io com SSL nativo.
|
|
|
|
---
|
|
|
|
## 🔐 Manutenção do certificado HTTPS do mmpCreator
|
|
|
|
O site é atendido pelo Traefik na porta 443, enquanto o backend de colaboração atende diretamente por HTTPS na porta 33001. O backend utiliza os arquivos `/etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem` e `privkey.pem` e carrega o certificado ao iniciar. Portanto, renovar o certificado exige reiniciar o backend para carregar a nova versão.
|
|
|
|
Uma página que abre normalmente, mas não conecta ao servidor em tempo real, pode indicar certificado vencido na porta 33001. O aviso de Ad Blocker exibido pelo frontend é genérico e não confirma a causa.
|
|
|
|
### 1. Verificar certificado e serviço
|
|
|
|
Execute no servidor Linux:
|
|
|
|
```bash
|
|
sudo openssl x509 \
|
|
-in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
|
|
-noout -dates
|
|
|
|
sudo certbot certificates
|
|
sudo systemctl status backend-MMPCreator.service --no-pager
|
|
sudo ss -ltnp 'sport = :80'
|
|
sudo grep -nE 'authenticator|installer|pre_hook|post_hook' \
|
|
/etc/letsencrypt/renewal/alice.ufsj.edu.br.conf
|
|
```
|
|
|
|
`notAfter` informa a data de expiração, em GMT/UTC. Um serviço `active (running)` ainda pode apresentar um certificado expirado.
|
|
|
|
### 2. Renovar com Certbot standalone e Traefik
|
|
|
|
Na configuração diagnosticada, o Certbot usa `authenticator = standalone`, e o container `traefik` ocupa a porta 80. Nesse cenário, é necessário parar temporariamente o Traefik para liberar a porta durante a validação. Este procedimento interrompe o acesso aos sites atendidos pelo proxy; execute em uma janela de manutenção. Ele só se aplica enquanto essa configuração permanecer em uso.
|
|
|
|
O certificado inclui sete domínios. Todos precisam estar acessíveis para a validação HTTP do Certbot. Se o teste falhar, corrija o erro informado antes de tentar a renovação real.
|
|
|
|
Execute o bloco completo em Bash. O `trap` tenta iniciar novamente o Traefik ao sair do bloco, inclusive se algum comando falhar:
|
|
|
|
```bash
|
|
(
|
|
set -e
|
|
trap 'sudo docker start traefik' EXIT
|
|
|
|
sudo docker stop traefik
|
|
sudo certbot renew --cert-name alice.ufsj.edu.br --dry-run
|
|
sudo certbot renew --cert-name alice.ufsj.edu.br
|
|
)
|
|
```
|
|
|
|
O `--dry-run` apenas testa a renovação; o comando seguinte renova efetivamente o certificado. Confira a retomada do proxy e a nova validade:
|
|
|
|
```bash
|
|
sudo docker ps --filter name=traefik
|
|
sudo openssl x509 \
|
|
-in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
|
|
-noout -dates
|
|
```
|
|
|
|
Se o Traefik não estiver em execução, retome-o com `sudo docker start traefik`. Se `notAfter` continuar vencido, consulte a saída do Certbot e `/var/log/letsencrypt/letsencrypt.log`.
|
|
|
|
### 3. Reiniciar o backend e testar a conexão
|
|
|
|
Após uma renovação bem-sucedida, confirme que o certificado no disco não está vencido antes de reiniciar. O reinício desconecta temporariamente as salas:
|
|
|
|
```bash
|
|
sudo openssl x509 \
|
|
-in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
|
|
-noout -checkend 0 && \
|
|
sudo systemctl restart backend-MMPCreator.service
|
|
|
|
sudo systemctl status backend-MMPCreator.service --no-pager
|
|
sudo journalctl -u backend-MMPCreator.service -n 80 --no-pager
|
|
|
|
curl -v --max-time 10 \
|
|
'https://alice.ufsj.edu.br:33001/socket.io/?EIO=4&transport=polling'
|
|
```
|
|
|
|
O teste deve responder sem erro TLS, com um handshake Socket.IO iniciado por `0{"sid":...}`. Depois, recarregue o mmpCreator e teste a criação e a entrada em uma sala. Não utilize `curl -k` para validar a correção: essa opção ignora os erros de certificado.
|
|
|
|
---
|
|
|
|
## 🛠️ Área de Desenvolvimento (Execução Manual)
|
|
|
|
1. Ative o ambiente virtual:
|
|
`source venv/bin/activate`
|
|
|
|
2. Execução do Pipeline ETL completo:
|
|
`cd scripts && ./pipeline_etl.sh`
|
|
|
|
3. Inicialização de Manifestos:
|
|
`cd scripts/creations && python generateManifest.py`
|
|
|
|
---
|
|
|
|
## ✅ Funcionalidades Implementadas
|
|
|
|
- [x] Web Crawler automatizado com auditoria de hardware.
|
|
- [x] Processamento de arquivos LMMS de forma _headless_ (renderização de áudio em servidor sem interface gráfica).
|
|
- [x] Gestão de usuários (Login, Registro, Perfis e painel Admin).
|
|
- [x] Identificação automática de samples externos faltantes no upload de projetos.
|
|
- [x] Criar, salvar (externamente) e carregar projetos (do PC ou do servidor).
|
|
- [x] Utilizar metrônomo, criar e excluir patterns.
|
|
- [x] Alternar entre patterns em tempo real.
|
|
- [x] Controle de volume e pan por pattern, por instrumento e global.
|
|
- [x] Alterar quantidade/formato de compassos e BPM.
|
|
- [x] Salas online e colaboração em tempo real (MMPCreator).
|
|
- [x] Botões de modo global e local para controle do editor de samples.
|
|
- [x] Exibição de notificações de alterações em tempo real.
|
|
|
|
---
|
|
|
|
## 📋 TODO (Próximos Passos)
|
|
|
|
- [x] Validar projetos MMP antes de aceitar uploads:
|
|
- [x] Verificar se os samples são nativos
|
|
- [ ] Corrigir caminhos dos samples (evitar problemas de execução)
|
|
- [x] Para downloads dos zip de projetos;
|
|
- [x] Para enviar projetos para a plataforma;
|
|
- [ ] Reconhecer os caminhos atualizados no MMPCreator;
|
|
- [ ] Fazer com que os caminhos atualizados permaneçam após cada build.
|
|
- [x] Permitir envio de samples gravados com microfone:
|
|
- [ ] Executar e recortar antes de salvar no servidor
|
|
- [x] Gravar músicas diretamente na plataforma, mesmo sem mixagem
|
|
- [ ] Ativar/desativar samples em patterns
|
|
- [ ] Remover botões inúteis no controle de patterns
|
|
- [ ] Melhorar documentação do código
|
|
- [ ] Permitir alteração dos nomes das patterns (novos e existentes projetos)
|
|
- [ ] Corrigir sistema de notas do projeto (Incluir rastros da plataforma e metadados de autor).
|
|
- [ ] Criar atalhos de teclado (Barra de espaço para play/pause, `+` e `-` para patterns).
|
|
- [ ] Permitir alteração de nome de samples (⚠️ pode gerar duplicatas).
|
|
- [ ] Verificar duplicidade de samples e projetos por nome.
|
|
- [ ] Resetar valores de botões via scroll do mouse.
|
|
- [ ] Ao salvar projeto: Escolher nome e permitir escolha entre download ou salvar no servidor.
|