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

• Web Crawler automatizado com auditoria de hardware.
• Processamento de arquivos LMMS de forma headless (renderização de áudio em servidor sem interface gráfica).
• Gestão de usuários (Login, Registro, Perfis e painel Admin).
• Identificação automática de samples externos faltantes no upload de projetos.
• Criar, salvar (externamente) e carregar projetos (do PC ou do servidor).
• Utilizar metrônomo, criar e excluir patterns.
• Alternar entre patterns em tempo real.
• Controle de volume e pan por pattern, por instrumento e global.
• Alterar quantidade/formato de compassos e BPM.
• Salas online e colaboração em tempo real (MMPCreator).
  • Botões de modo global e local para controle do editor de samples.
• Exibição de notificações de alterações em tempo real.

---

📋 TODO (Próximos Passos)

• Validar projetos MMP antes de aceitar uploads:
  • Verificar se os samples são nativos
  • Corrigir caminhos dos samples (evitar problemas de execução)
    • Para downloads dos zip de projetos;
    • Para enviar projetos para a plataforma;
    • Reconhecer os caminhos atualizados no MMPCreator;
    • Fazer com que os caminhos atualizados permaneçam após cada build.
• Permitir envio de samples gravados com microfone:
  • Executar e recortar antes de salvar no servidor
  • 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.