114 lines
6.2 KiB
Markdown
114 lines
6.2 KiB
Markdown
Documentação Técnica: Arquitetura e Implementação do MMPSearch & MMPCreator
|
|
1. 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.
|
|
|
|
2. 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).
|
|
|
|
3. 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.
|
|
|
|
4. 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.
|
|
|
|
5. 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.
|
|
|
|
6. 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.
|
|
|
|
7. 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.
|
|
|
|
8. 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.
|
|
|
|
9. 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.
|
|
|
|
10. 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. |