From 3c6489f2a02a34d71f94b60b780850f23854dec8 Mon Sep 17 00:00:00 2001 From: JotaChina Date: Sat, 4 Apr 2026 13:12:35 -0300 Subject: [PATCH] corrigindo upload --- readme.md | 164 ++++++++++++++++++++++-------------------------------- 1 file changed, 67 insertions(+), 97 deletions(-) diff --git a/readme.md b/readme.md index b8462bb0..ae10464a 100755 --- a/readme.md +++ b/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: - -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. +_The mainstream only exists because the underground created the scene._ --- -## 🛠️ Á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: - - `cd scripts/creations` - - `python generateManifest.py` +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. -- Para que os projetos sejam indexados e as informações sejam geradas corretamente no `MMPSearch` é necessário: - - `cd scripts/handler` - - `python main.py` +### Servidor de Upload, Autenticação e Build (Flask/Gunicorn) -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. - -- **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: +Hospeda a lógica de WebSockets responsável por gerenciar as salas e a colaboração online do editor MMPCreator em tempo real. - **Serviço:** `/etc/systemd/system/backend-MMPCreator.service` -- **Nome do serviço:** `backend-MMPCreator.service` -- **Frequência:** Tempo integral -- **Tecnologia utilizada:** NodeJS (Socket.io) +- **Tecnologia:** NodeJS (`server.js`). +- **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://`. +- **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. -- 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. +## 🛠️ Área de Desenvolvimento (Execução Manual) -### 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] Carregar projetos (do PC ou do servidor) -- [x] Salvar projetos (externamente) -- [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] 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) -### 🛠️ 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: - - [ ] Incluir rastros da plataforma MMPCreator - - [ ] Informações de autor e metadados -- [ ] Criar atalhos de teclado: - - [ ] Barra de espaço para play/pause - - [ ] `+` e `-` para alternar entre 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: - - [ ] 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. \ No newline at end of file +- [ ] 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.