118 lines
6.7 KiB
Markdown
Executable File
118 lines
6.7 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 (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.
|
|
|
|
---
|
|
|
|
## ⚙️ Serviços de Hospedagem (Produção)
|
|
|
|
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.
|
|
|
|
### Servidor de Upload, Autenticação e Build (Flask/Gunicorn)
|
|
|
|
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`
|
|
|
|
### Backend de Colaboração (NodeJS)
|
|
|
|
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`
|
|
- **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.
|
|
|
|
---
|
|
|
|
## 🛠️ Área de Desenvolvimento (Execução Manual)
|
|
|
|
Para testes ou execuções manuais, o site está sendo desenvolvido em um ambiente virtual Python (`venv`).
|
|
|
|
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] 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.
|