corrigindo upload

readme.md

@@ -1,113 +1,100 @@
 # 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.
 
-## 🏗️ Arquitetura do Sistema
+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.
 
-O sistema é um ecossistema completo para submissão, processamento e colaboração em projetos musicais (LMMS), estruturado nos seguintes pilares:
+_The mainstream only exists because the underground created the scene._
-
-1. **Banco de Dados e Autenticação (Flask / SQLite):** Gestão segura de usuários (Bcrypt, Flask-Login), controle de propriedade de projetos e samples, além de um painel de administração (`Flask-Admin`).
-2. **Motor de Renderização Headless (Python):** Processamento assíncrono via biblioteca `multiprocessing`. Utiliza o binário do LMMS em modo `offscreen` para extrair dados do XML (`.mmp` / `.mmpz`) e exportar o áudio gerado nativamente no servidor.
-3. **MMPSearch (Catálogo Front-end):** Biblioteca estática gerada via Jekyll a partir de arquivos JSON/YAML, focada em leveza, indexação e busca de projetos com renderização via Web Audio API.
-4. **MMPCreator (Colaboração em Tempo Real):** Sequenciador interativo hospedado em Node.js. Utiliza WebSockets para sincronizar edições simultâneas (áudio e MIDI) entre múltiplos usuários em salas virtuais.
 
 ---
 
-## 🛠️ Área de Desenvolvimento
+## 🏗️ Arquitetura e Engenharia de Dados
 
-O site está sendo desenvolvido em um ambiente virtual Python (`venv`). Para executá-lo corretamente, ative o ambiente com o comando:
+O sistema é um ecossistema completo para mineração, submissão, processamento e colaboração em projetos musicais (LMMS), estruturado nos seguintes pilares:
 
-`source venv/bin/activate`
+### 1. Web Crawler (Mineração de Dados)
 
-Isso garante que todas as dependências do projeto sejam utilizadas corretamente.
+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 (limitado a 4 workers) 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:** Os arquivos baixados têm seus nomes sanitizados (slugify) e o processo gera um arquivo de auditoria (`audit_crawler.csv`) registrando tamanho, velocidade e status de cada download.
+
+### 2. Pipeline ETL e Motor de Renderização
+
+A conversão dos arquivos nativos em artefatos web é orquestrada pelo script `pipeline_etl.sh`, que executa três etapas sequenciais:
+
+1. **Extração e Renderização (`handler/main.py`):** O script utiliza a biblioteca `multiprocessing` e processa os projetos em lotes. Ele invoca o binário do LMMS em modo `offscreen` (Headless) para exportar o áudio gerado nativamente em `.ogg` e converte a estrutura do `.mmp` em dicionários de dados (JSON/YAML).
+2. **Análise de Áudio (`classificacao/analise_audio.py`):** Processamento das características sonoras.
+3. **Classificação Mestre (`classificacao/classificacao_mestre.py`):** Organização final e indexação para o frontend.
+
+### 3. MMPSearch (Catálogo Estático Frontend)
+
+Biblioteca gerada via Jekyll a partir dos arquivos JSON/YAML exportados pelo Pipeline ETL, focada em leveza, indexação e busca de projetos, com renderização de áudio via Web Audio API.
+
+### 4. MMPCreator (Colaboração em Tempo Real)
+
+Sequenciador interativo. Utiliza WebSockets para sincronizar edições simultâneas (áudio e MIDI) entre múltiplos usuários em salas virtuais.
 
 ---
 
-## 📚 Discretização da informação
+## ⚙️ Serviços de Hospedagem (Produção)
 
-- Para que a biblioteca de samples do `MMPCreator` seja inicializada, é necessário:
+A infraestrutura em produção é orquestrada por gerenciadores de serviço do Linux (`systemd`), garantindo que a API e o servidor de WebSockets estejam sempre no ar.
-  - `cd scripts/creations`
-  - `python generateManifest.py`
 
-- Para que os projetos sejam indexados e as informações sejam geradas corretamente no `MMPSearch` é necessário:
+### Servidor de Upload, Autenticação e Build (Flask/Gunicorn)
-  - `cd scripts/handler`
-  - `python main.py`
 
-Dessa forma, os arquivos de manifesto serão gerados, contendo as informações de cada projeto e seus parâmetros individuais. Além disso, os parâmetros de instrumentos também são capturados. A grande mágica está ai, pois contendo as informações de diversos projetos é possível efetuar buscas dentre estes, em diversas categorias. 
+Serviço responsável por receber arquivos, gerenciar a sessão dos usuários (SQLite, Bcrypt, Flask-Login) e automatizar o build do site via threads em segundo plano.
 
----
+- **Serviço:** `/etc/systemd/system/upload_mmpSearch.service`
+- **Tecnologia:** Gunicorn servindo a aplicação Flask (`upload_server:app`).
+- **Configuração:** Roda com o usuário `www-data`. Utiliza 3 _workers_ e possui um timeout estendido de 300 segundos, o que é vital para não derrubar a conexão durante renderizações pesadas de áudio.
+- **Acesso da API:** `http://0.0.0.0:33002`
 
-## 📤 Servidor de Upload, Samples e Build (Flask)
+### Backend de Colaboração (NodeJS)
 
-O servidor `upload_server.py` atua como a API central do sistema. Ele recebe arquivos, gerencia a sessão dos usuários (Login/Registro) e automatiza a reconstrução da plataforma.
+Hospeda a lógica de WebSockets responsável por gerenciar as salas e a colaboração online do editor MMPCreator em tempo real.
-
-- **Framework:** Flask
-- **Banco de Dados:** SQLite (com SQLAlchemy)
-- **Automação de Build:** Uso de Threads em segundo plano (Background Tasks) acionadas via rotas HTTP.
-
-### Funcionamento:
-
-Sempre que um novo upload (Projeto ou Sample) é processado via API:
-1. O arquivo é sanitizado e validado.
-2. O sistema verifica a dependência de samples externos no XML.
-3. Os manifestos (`samples-manifest.json`, metadados de projetos) são atualizados em tempo real no servidor.
-4. Uma thread secundária segura (com Lock) dispara o comando `bundle exec jekyll build`, reconstruindo o frontend estático do MMPSearch para refletir a submissão imediatamente.
-
-### Acesso da API:
-
-- `http://127.0.0.1:33002`
-
-> ⚠️ **Importante:** A estabilidade da reconstrução em produção depende do caminho absoluto do binário Ruby e do pacote Bundle configurados no script (`upload_server.py`).
-
----
-
-## 💻 Backend para controle das salas online (Colaboração)
-
-Um serviço systemd foi criado para hospedar o backend de um servidor em nodeJS responsável por gerenciar as salas e a colaboração online do MMPCreator:
 
 - **Serviço:** `/etc/systemd/system/backend-MMPCreator.service`
-- **Nome do serviço:** `backend-MMPCreator.service`
+- **Tecnologia:** NodeJS (`server.js`).
-- **Frequência:** Tempo integral
+- **Configuração de Segurança:** Roda sob o usuário `www-data` e possui acesso direto aos certificados Let's Encrypt via variáveis de ambiente (`SSL_FULLCHAIN` e `SSL_PRIVKEY`). Essa abordagem elimina a necessidade do Apache atuar como proxy reverso, facilitando a comunicação direta e segura via `wss://` e `https://`.
-- **Tecnologia utilizada:** NodeJS (Socket.io)
+- **Comportamento:** Configurado com `Restart=always` para garantir alta disponibilidade.
 
-### Funcionalidade:
+---
 
-- Seu intuíto é deixar o backend online em tempo integral, possibilitando a utilização da plataforma em qualquer momento.
+## 🛠️ Área de Desenvolvimento (Execução Manual)
-- Para isso foi necessário inserir meu usuário no grupo de "ssl-cert" para acesso aos certificados (Let's Encrypt).
-  - Essa abordagem foi escolhida, pois a "não" utilização do apache traz algumas variáveis a mais para a implementação de um proxy reverso para a comunicação segura via `wss://` e `https://` nas salas de colaboração.
 
-### Acesso:
+Para testes ou execuções manuais, o site está sendo desenvolvido em um ambiente virtual Python (`venv`).
 
-- `http://127.0.0.1:33001`
+1. Ative o ambiente:
+   `source venv/bin/activate`
+
+2. Para inicializar a biblioteca de samples do MMPCreator:
+   `cd scripts/creations && python generateManifest.py`
+
+3. Para forçar a indexação e execução manual do pipeline ETL:
+   `cd scripts && ./pipeline_etl.sh`
 
 ---
 
 ## ✅ Funcionalidades Já Implementadas
 
-- [x] Criar projetos
+- [x] Web Crawler automatizado com auditoria de hardware.
-- [x] Carregar projetos (do PC ou do servidor)
+- [x] Processamento de arquivos LMMS de forma _headless_ (renderização de áudio em servidor sem interface gráfica).
-- [x] Salvar projetos (externamente)
+- [x] Gestão de usuários (Login, Registro, Perfis e painel Admin).
-- [x] Editar projetos existentes (sem alterar o original)
-- [x] Utilizar metrônomo
-- [x] Criar e excluir patterns
-- [x] Alternar entre patterns em tempo real
-- [x] Controle de volume e pan por pattern e por instrumento
-- [x] Controle de volume e pan global
-- [x] Alterar quantidade e formato de compassos
-- [x] Alterar BPM
-- [x] Exibir duração da pattern via timer
-- [x] Salas online e colaboração em tempo real
-  - [x] Botões de modo global e local para controle do editor de samples (controla play/pause/stop, loop e janela de loop)
-- [x] Exibição de notificações em alterações nos projetos em tempo real
-- [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)
 
-### 🛠️ Funcionalidades
-
 - [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)
@@ -122,26 +109,9 @@ Um serviço systemd foi criado para hospedar o backend de um servidor em nodeJS
 - [ ] 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:
+- [ ] Corrigir sistema de notas do projeto (Incluir rastros da plataforma e metadados de autor).
-  - [ ] Incluir rastros da plataforma MMPCreator
+- [ ] Criar atalhos de teclado (Barra de espaço para play/pause, `+` e `-` para patterns).
-  - [ ] Informações de autor e metadados
+- [ ] Permitir alteração de nome de samples (⚠️ pode gerar duplicatas).
-- [ ] Criar atalhos de teclado:
+- [ ] Verificar duplicidade de samples e projetos por nome.
-  - [ ] Barra de espaço para play/pause
+- [ ] Resetar valores de botões via scroll do mouse.
-  - [ ] `+` e `-` para alternar entre patterns
+- [ ] Ao salvar projeto: Escolher nome e permitir escolha entre download ou salvar no servidor.
-- [ ] 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:
-  - [ ] Permitir escolha entre download ou salvar no servidor
-  - [ ] Escolher nome do projeto
-
-
-ALICE MMPSearch
-
-This is a repository with the purpose of creating a site using Jekyll to serve as a LMMS Beat File Library.
-
-The intuitive is to be able to collect information from the files by indexing it and allows search with the most diverse filters.
-
-It is part of the master's research in Computer Science at the Federal University of São João del Rei, focused on independent underground music production and the use of open source technologies.
-
-The mainstream only exists because the underground created the scene.