mmpSearch/readme.md

# 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.

---

## 🛠️ Á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.