JotaChina/mmpSearch
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
57af93ea60f6412d347a3dc515839e0385c08af7
mmpSearch/readme.md
T

9.3 KiB
Executable File
Raw Blame History

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 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: Utiliza BeautifulSoup4 para extração de links e gera relatórios de performance em CSV.

2. Pipeline ETL e Motor de Renderização

A conversão dos arquivos nativos em artefatos web é orquestrada pelo script pipeline_etl.sh, executando o processamento em lotes:

  1. Extração e Renderização (handler/main.py): Invoca o LMMS em modo offscreen para gerar áudio e converte o XML .mmp em JSON/YAML.
  2. Análise e Inteligência Artificial: Utiliza a biblioteca Essentia (Tensorflow) para extração de características acústicas e classificação de áudio.

📦 Ecossistema Python e Dependências (venv)

O ambiente virtual (venv) contém as bibliotecas necessárias para o ciclo de vida do dado. As principais dependências instaladas são:

Web & API Framework

  • Flask (v3.1.2): Engine principal da API.
  • Flask-SocketIO: Suporte a comunicação bi-direcional via WebSockets.
  • Gunicorn: Servidor HTTP WSGI para produção.
  • Flask-Admin & WTForms: Interface de gerenciamento e validação de formulários.

Segurança e Persistência

  • SQLAlchemy (v2.0): ORM para manipulação do banco users.db.
  • Flask-Bcrypt & Cryptography: Hashing de senhas e camadas de criptografia.

Processamento e Ciência de Dados

  • Essentia-Tensorflow: Biblioteca avançada para análise de áudio e music information retrieval (MIR).
  • NumPy: Suporte para arrays multidimensionais e cálculos matemáticos pesados.
  • PyYAML: Geração de metadados para integração com o Jekyll.

Utilidades e Monitoramento

  • Psutil: Monitoramento de hardware para controle de processos paralelos.
  • Watchdog: Monitoramento de eventos no sistema de arquivos.
  • tqdm: Barras de progresso para tarefas de longa duração no terminal.

⚙️ Serviços de Hospedagem (Produção)

A infraestrutura é mantida via systemd para garantir alta disponibilidade.

API de Upload e Processamento (Gunicorn)

  • Serviço: upload_mmpSearch.service
  • Porta: 33002
  • Timeout: 300s (Essencial para o tempo de renderização do LMMS)

Backend de Colaboração (NodeJS)

  • Serviço: backend-MMPCreator.service
  • Porta: 33001
  • Tecnologia: Sincronização via Socket.io com SSL nativo.

🔐 Manutenção do certificado HTTPS do mmpCreator

O site é atendido pelo Traefik na porta 443, enquanto o backend de colaboração atende diretamente por HTTPS na porta 33001. O backend utiliza os arquivos /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem e privkey.pem e carrega o certificado ao iniciar. Portanto, renovar o certificado exige reiniciar o backend para carregar a nova versão.

Uma página que abre normalmente, mas não conecta ao servidor em tempo real, pode indicar certificado vencido na porta 33001. O aviso de Ad Blocker exibido pelo frontend é genérico e não confirma a causa.

1. Verificar certificado e serviço

Execute no servidor Linux:

sudo openssl x509 \
  -in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
  -noout -dates

sudo certbot certificates
sudo systemctl status backend-MMPCreator.service --no-pager
sudo ss -ltnp 'sport = :80'
sudo grep -nE 'authenticator|installer|pre_hook|post_hook' \
  /etc/letsencrypt/renewal/alice.ufsj.edu.br.conf

notAfter informa a data de expiração, em GMT/UTC. Um serviço active (running) ainda pode apresentar um certificado expirado.

2. Renovar com Certbot standalone e Traefik

Na configuração diagnosticada, o Certbot usa authenticator = standalone, e o container traefik ocupa a porta 80. Nesse cenário, é necessário parar temporariamente o Traefik para liberar a porta durante a validação. Este procedimento interrompe o acesso aos sites atendidos pelo proxy; execute em uma janela de manutenção. Ele só se aplica enquanto essa configuração permanecer em uso.

O certificado inclui sete domínios. Todos precisam estar acessíveis para a validação HTTP do Certbot. Se o teste falhar, corrija o erro informado antes de tentar a renovação real.

Execute o bloco completo em Bash. O trap tenta iniciar novamente o Traefik ao sair do bloco, inclusive se algum comando falhar:

(
  set -e
  trap 'sudo docker start traefik' EXIT

  sudo docker stop traefik
  sudo certbot renew --cert-name alice.ufsj.edu.br --dry-run
  sudo certbot renew --cert-name alice.ufsj.edu.br
)

O --dry-run apenas testa a renovação; o comando seguinte renova efetivamente o certificado. Confira a retomada do proxy e a nova validade:

sudo docker ps --filter name=traefik
sudo openssl x509 \
  -in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
  -noout -dates

Se o Traefik não estiver em execução, retome-o com sudo docker start traefik. Se notAfter continuar vencido, consulte a saída do Certbot e /var/log/letsencrypt/letsencrypt.log.

3. Reiniciar o backend e testar a conexão

Após uma renovação bem-sucedida, confirme que o certificado no disco não está vencido antes de reiniciar. O reinício desconecta temporariamente as salas:

sudo openssl x509 \
  -in /etc/letsencrypt/live/alice.ufsj.edu.br/fullchain.pem \
  -noout -checkend 0 && \
  sudo systemctl restart backend-MMPCreator.service

sudo systemctl status backend-MMPCreator.service --no-pager
sudo journalctl -u backend-MMPCreator.service -n 80 --no-pager

curl -v --max-time 10 \
  'https://alice.ufsj.edu.br:33001/socket.io/?EIO=4&transport=polling'

O teste deve responder sem erro TLS, com um handshake Socket.IO iniciado por 0{"sid":...}. Depois, recarregue o mmpCreator e teste a criação e a entrada em uma sala. Não utilize curl -k para validar a correção: essa opção ignora os erros de certificado.

🛠️ Área de Desenvolvimento (Execução Manual)

  1. Ative o ambiente virtual: source venv/bin/activate

  2. Execução do Pipeline ETL completo: cd scripts && ./pipeline_etl.sh

  3. Inicialização de Manifestos: cd scripts/creations && python generateManifest.py

✅ Funcionalidades 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.
Reference in new issue View Git Blame Copy Permalink