6.2 KiB
Documentação Técnica: Arquitetura e Implementação do MMPSearch & MMPCreator
- Visão Geral da Arquitetura O sistema foi projetado para resolver o desafio de catalogar, processar e permitir a colaboração em projetos musicais (formato LMMS) na web. A solução adota uma Arquitetura Híbrida Dinâmica-Estática:
Entrada (Dinâmica): Uma API em Flask gerencia uploads, autenticação e validação de arquivos.
Processamento (Batch/Background): Scripts Python executam a renderização de áudio e extração de dados XML em segundo plano.
Saída (Estática): Os dados processados alimentam um gerador Jekyll, resultando em uma interface leve, segura e de baixo custo computacional para o usuário final.
Colaboração (Tempo Real): Um microsserviço Node.js independente gerencia a edição via WebSockets.
- O Fluxo de Ingestão (Backend) O ponto de entrada é o script upload_server.py. Ele atua como o "porteiro" do sistema, garantindo que apenas dados válidos entrem no pipeline.
Sanitização de Arquivos: Utiliza-se a função slugify para normalizar nomes de arquivos, removendo acentos e caracteres especiais para garantir compatibilidade com URLs (ex: Ação.mmp torna-se acao.mmp).
Tratamento de Compressão (.mmpz): O sistema detecta nativamente arquivos comprimidos. Ao receber um .mmpz, ele aciona o binário do LMMS (lmms --dump) para descompactar o XML, permitindo a leitura dos dados internos sem corromper o projeto original.
Banco de Dados: A persistência de usuários e metadados de propriedade é feita via SQLite e SQLAlchemy, mantendo uma relação leve entre o arquivo físico e seu proprietário (User <-> Project).
- Motor de Processamento e Renderização Headless A funcionalidade mais crítica para a dissertação é a capacidade de gerar áudio em um servidor sem monitor (headless). Isso é gerenciado pelo script main.py.
Ambiente Offscreen: O script configura a variável de ambiente QT_QPA_PLATFORM="offscreen". Isso engana o LMMS (que é uma aplicação gráfica Qt), permitindo que ele rode via linha de comando dentro do servidor Linux.
Renderização CLI: O áudio é gerado invocando o comando: lmms -r <input.mmp> -o <output.wav> -f wav.
Paralelismo: Utiliza-se a biblioteca multiprocessing para criar um pool de workers, permitindo que múltiplos projetos sejam renderizados simultaneamente, otimizando o uso da CPU.
- Geração de Manifestos e Dados Estáticos Para desacoplar o banco de dados da interface pública, o sistema utiliza o script generate_manifest.py.
Indexação: O script varre os diretórios de mídia (samples, mmp, wav) e gera arquivos JSON e YAML.
Integração com Jekyll: Estes arquivos YAML são salvos diretamente na pasta _data do Jekyll, servindo como fonte de verdade para a geração das páginas HTML estáticas.
- Engenharia de Dados: Parsing XML A "inteligência" musical do sistema reside no file_parser.py, que traduz o XML do LMMS para objetos JSON manipuláveis.
Tipagem de Trilhas: O parser identifica e separa trilhas baseando-se no atributo type:
Type 0: Instrumentos e Sintetizadores.
Type 1: Beat/Bassline Editor (extrai padrões rítmicos).
Type 2: Samples de Áudio.
Type 5/6: Automação.
Fallback Genérico: Implementa um padrão de projeto Strategy com fallback. Se não houver um parser específico para um plugin (ex: tripleoscillator), a função extract_generic_attributes varre o XML e converte todos os atributos encontrados, garantindo compatibilidade futura.
- Integridade e Verificação de Dependências Para evitar a "tela azul" de arquivos faltando, o dependency_checker.py executa uma auditoria antes da publicação.
Inventário do Servidor: Cria um índice de todos os arquivos de áudio existentes no disco.
Heurística de Recuperação:
HEALTHY: O caminho no XML bate com o servidor.
RECOVERED: O caminho original (ex: C:/Users/...) não existe, mas o sistema encontrou o arquivo pelo nome e remapeou o link automaticamente.
BROKEN: Arquivo inexistente; o sistema marca para alerta.
- Frontend: Visualização e Sequenciador A interface (projetos.html) demonstra como dados complexos podem ser visualizados sem JavaScript pesado.
Sequenciador CSS: A grade de bateria (Step Sequencer) é renderizada usando lógica de template Liquid e CSS puro. O template itera sobre o array de steps ({% for step in patterns %}) e aplica classes de cor condicionalmente.
Interatividade Híbrida:
Web Audio API: Scripts JS (InstrumentFactory) leem os dados extraídos pelo parser para tocar prévias dos sintetizadores no navegador.
Modais: Uso de iframe para carregar o editor completo (MMPCreator) em uma camada sobreposta.
- Orquestração de Serviços (Systemd) A estabilidade em produção é garantida pelo gerenciador de serviços do Linux.
Serviço de Processamento (mmpsearch.service):
Gerencia o Gunicorn/Flask.
Timeout: Configurado para 300 segundos (5 minutos) para suportar o tempo de renderização de áudio pesado sem derrubar a conexão.
Workers: 3 processos simultâneos.
Serviço de Colaboração (backend-MMPCreator.service):
Gerencia o Node.js.
Reinício Automático: Diretiva Restart=always garante alta disponibilidade para sessões em tempo real.
- Segurança e Permissões A infraestrutura segue o princípio de menor privilégio necessário para operação web.
Usuário www-data: Ambos os serviços rodam sob este usuário, padrão para servidores web.
Gestão de SSL: O serviço Node.js consome diretamente os certificados do Let's Encrypt (fullchain.pem, privkey.pem) via variáveis de ambiente, permitindo conexões seguras (WSS - WebSockets Secure).
Permissões de Escrita: O sistema possui permissão explícita para escrever nas pastas de assets e src_mmpSearch, essencial para o funcionamento do gerador estático Jekyll.
- Fluxo de Implantação (Resumo) Para fins de documentação na dissertação, o ciclo de vida de um projeto na plataforma é:
Upload: Usuário envia .mmpz via API Flask (Porta 33002).
Trigger: Flask salva o arquivo e dispara a thread de processamento.
Processamento: Python descompacta o projeto, renderiza o .wav (Headless LMMS) e extrai o .json.
Build: Python invoca bundle exec jekyll build para regenerar o HTML.
Serviço: Nginx serve o novo HTML estático; Node.js aguarda conexões para edição colaborativa.