KARALHOKÊ.FUN
Voltar pro Hub Admin

Manual Oficial do Sistema

Aprenda a operar todas as ferramentas, scripts, fluxos e manutenções do Karalhokê.fun (Multivox Engine).

1. Visão Geral (A Arquitetura)

O Karalhokê.fun (Multivox) funciona distribuído em várias "peças" para garantir que o show ao vivo não seja interrompido caso algum serviço fique sobrecarregado. Entender como as peças se comunicam é o passo zero.

graph TD A[Player Lite
Celular do Cliente] <-->|Pesquisa/Pede Fila| B(Firestore
Banco Rápido) C[TV Player
Telão no Palco] <-->|Lê a Fila Viva| B D[Gestão Master
Seu Painel Admin] -->|Altera Dados| B D -.->|Envia Áudio/Letras| E[(Cloudflare R2
Super Nuvem)] E ==o|Transmite Música a Jato| C E ==o|Envia Arquivos Cache| A
  • Firestore (Firebase): O cérebro ultrarrápido. Guarda em milissegundos quem pediu qual música, quem está na vez e quais erros o sistema tem.
  • Cloudflare R2 (Storage): O servidor "musculoso". Guarda e compartilha de forma incrivelmente barata e sem taxas todos os MP3, Instrumentais isolados e arquivos pesados.
  • Inteligência Artificial (Modal): Servidores terceirizados invisíveis que se conectam durante a sua tela de Upload Wizard para isolar os vocais da música.

2. Player Lite e TV Player (Front-End Público)

Os seus clientes ou cantores interagem nativamente por vias que não pedem senhas de dono.

Player Lite (No Bolso)

Aplicativo que os clientes abrem lendo um QR Code no balcão. Ele serve como o seu garçom de karaokê digital. Funções dele:

  • Possui catálogo completo off-line e com fotos.
  • Permite solicitar músicas colocando nome direto na fila do firebase.
  • Módulo Reports: Ali mesmo eles têm um botão de Sinalizar Problemas para reportar pra você faixas com erros de letra, áudio ausente ou etc.
  • Widget de Suporte: Um botão flutuante permite que o usuário inicie um chat de atendimento em tempo real com os administradores.

TV Player (No Palco)

O projetor. Ele foi desenhado para agir sozinho (Autônomo):

  • Escuta ininterruptamente as adições à fila no banco de dados.
  • Ao chegar na vez, faz download antecipado do áudio MP3 original e a letra Sincronizada (LRC).
  • Anima as letras para cantar (Engine do LetrasToca) e ao finalizar apaga a pessoa da fila e avisa a próxima.

3. Fluxo de Novas Músicas (Upload Wizard AI)

Como enriquecer sua base de faixas. Abandonamos as pastas confusas de Windows antigo. Tudo passa pela nuvem em um formato Mágico Assistido.

sequenceDiagram participante Você (Admin) participante Wizard participante IA (Isolador) participante Bibliotecas Web Você (Admin)->>Wizard: Fornece Link do YouTube Wizard->>IA (Isolador): "Corta a voz pra mim?" (Demucs) IA (Isolador)-->>Wizard: Retorna o MP3 Purificado Wizard->>Bibliotecas Web: Pesquisa Letras .LRC Prontas (Vagalume...) Você (Admin)->>Wizard: Revisa nome, artista e capa... e clica em Salvar!
Importante: Se uma letra pronta não for encontrada na base do LRCLib, você poderá salvá-la vazia e buscar pelo texto em formato de prosa depois, editando posteriormente na "Gestão de Catálogo" e convertendo via Multivox.
Atalho Desconectado: Tem o Playback em MP3 numa pasta do PC já pronto? O painel respeita isso! Pule todo o "Step 1" da IA de baixar YouTube, e simplesmente arraste seu arquivo MP3 em cima dos campos na Etapa 2 de formulário.

4. Gestão de Catálogo & Sincronização Assíncrona

Essa é a interface de planilhas. Tudo pode ser editado. Porém preste atenção em como os clientes veem as coisas.

A regra de ouro: O Catálogo Offline Celular

Para evitar picos de fatura astronômicos no seu Firebase caso 1.000 pessoas fiquem rolando a aba de "Músicas" no celular e pesquisando no Google a noite inteira, nós bloqueamos esse banco.

O seu celular sempre baixa um arquivo congelado e extremamente leve chamado catalog.json em um único pedido.

  1. Você abre o Gestão de Catálogo, clica num lapisinho e altera `Evidencias` para `Evidências (Versão de Bar)`. E clica Salvar.
  2. O painel na hora escreve essa linha nova no banco Firebase Mestre.
  3. No mesmo exato segundo silensionamente, o seu painel lê o firebase todo de cima abaixo para pegar os 90 mil sons.
  4. Cria um pacote TXT compacto com o novo nome das Evidências incluso, e empurra pra fora substituindo o `catalog.json` antigo no servidor CDN da Cloudflare R2.
  5. Em 2 segundos, o celular dos seus clientes faz uma varredura transparente para recarregar o JSON de fundo e passa a ver o novo nome atualizado. Total de custo da busca: quase zero centavos.

5. Multivox Studio (Regra Mestre de TAGS)

Como faz as falas duplas e marcações na pista? As TV's que você opera, suportam leitura de avatares múltiplos se programadas.

As tags são colocadas sempre APÓS a leitura de timestamp milissecundal.

[00:15.50][V:1] Dizem que eu sou louco
[00:18.20][V:1] Por eu ter um gosto assim

[00:22.00][V:2] Gostar de quem não gosta de mim
[00:26.50][Todos] Jogue suas mãos para o céu!

Ao abrir a janela do Lápis na sua base de catálogo, a segunda coluna abriga seus controles de Multivox Studio para que o computador insira essas tags para você perfeitamente dentro da timeline sem errar as caixas [xx:xx].

6. Sistema Inteligente de Reportes

O celular tem inteligência para colher erros e mandar direto para seu hub. Existem fluxos de correção definidos para isso.

flowchart LR A((Cantor Frustrado)) -->|Aciona Sinalizador| B[Player Lite] B -->|Lê Dispositivo e Envia| C(Banco Reports) C -->|Seta Tag Vermelha| D[Gestão Catálogo]

Quando algo dá problema na TV, funciona assim:

  • Geração do Problema: O usuário escolhe que foi letra, ou áudio estragado e comenta. O sistema embala isso junto com a versão do Windows e Chrome dele pra te ajudar com diagnósticos em massa.
  • No seu Painel (Catálogo Rápido): A faixa passa a estampar a etiqueta ⚠️ REPORTADO na fileira.
  • Editando a Dor: Ao abrir o lápis de edição em cima da música, uma caixa enorme salmão mostrará todas as reclamações anexas na música simultaneamente.
  • Aba de Resolvidos: Clicando no lado em "OK, Resolver" e escrevendo um memorando, ele vai limpo para a área mestra de Gestão de Reportes arquivado. O símbolo vermelho da faixa some pro público instantaneamente.

7. Central de Manutenção (Emergências e Bloqueio Global)

Dentro do HUB (A tela inicial do seu dashboard com 6 grandes cartões), se rolar a página pra baixo baterá na "Manutenção do Sistema". Todos esses botões exigem confirmação de segurança nativa. São eles:

Habilitar Manutenção Global: Esta é a sua chave primária de força bruta. Acionar isso causará um "Lockdown" em 100% dos celulares. Usuários logados verão uma "Porta de Aço" informando reparos, e usuários novos não conseguirão nem passar da portaria (cadastro bloqueiado).

Use isso sempre que precisar deletar Coleções inteiras do banco de dados, reconstruir indexes, ou parar o mundo pra atualizar um código gigante sem ninguém mexer no site no meio da transação.
  • Resetar TV Players Ativos: Força um "Refresh" agressivo pela API remota nas telas gigantes de palco. Elas perdem a conexão em branco e em 2 segundos voltam. Perfil recomendado se o Chromecast lá da ponta estiver esquisito e você quer acordar ele lá do seu escritório sem controles remotos.

8. Monitoramento de Infraestrutura e Saúde

O Karalhokê.fun utiliza uma arquitetura baseada em microsserviços e computação em nuvem. A Central de Saúde permite a auditoria em tempo real da conectividade e do tempo de resposta de cada componente vital do ecossistema.

8.1 Componentes e Indicadores

Firebase Firestore (Banco de Dados):

  • O que esperar: Latência (Ping) entre 50ms e 200ms em conexões estáveis. Status "ONLINE".
  • Mensagens fora do esperado: Latências superiores a 800ms ou status "OFFLINE".
  • Ação corretiva: Verifique a estabilidade da conexão de internet local. Caso o problema persista, consulte o Dashboard de Status do Google Cloud.

Cloudflare R2 (Armazenamento e CDN):

  • O que esperar: Latência (Ping) entre 30ms e 150ms para entrega de arquivos via rede de borda (CDN). Status "ONLINE".
  • Mensagens fora do esperado: Status "OFFLINE" ou "TIMEOUT".
  • Ação corretiva: Verifique se o domínio de mídia não está bloqueado por firewalls locais ou se há interrupções informadas nos serviços de borda da Cloudflare.

Download Engine (server.py):

  • O que esperar: Status "ATIVO" e conexão "CONECTADO" na porta 7000.
  • Mensagens fora do esperado: Status "OFFLINE" ou "DESLIGADO".
  • Ação corretiva: Este componente reside na máquina local do administrador. Caso esteja desligado, as funcionalidades de download não operarão. Certifique-se de que o terminal executando python server.py no diretório karalhoke-downloader está ativo e sem erros de execução.

Modal AI Engine (Processamento Python):

  • O que esperar: Status "ESTÁVEL".
  • Mensagens fora do esperado: Falhas recorrentes ignoradas no log de processamento.
  • Ação corretiva: Diferente dos demais, este serviço é acionado sob demanda. Verifique o seu saldo e as quotas de execução no painel da Modal caso o isolamento de vocais interrompa seu fluxo de trabalho repentinamente.
Nota sobre Diagnóstico: Os testes de ping são realizados do navegador do administrador para as APIs de destino. Divergências nos indicadores podem refletir congestionamento na rede local ou restrições de proxy, e não necessariamente uma queda no serviço global.

9. Central de Suporte e Tickets Em Tempo Real

O ecossistema Karalhokê possui um hub integrado de Atendimento ao Cliente. Funciona como um chat corporativo, eliminando a necessidade de os clientes entrarem em contato via WhatsApp para relatar problemas técnicos de conta, financeiro ou solicitar novos recursos.

Como Funciona Para o Cliente:

  • Widget Global: Em diferentes telas principais do sistema (Como Catálogo, Player e Painel de Perfil), o usuário enxerga um "Botão Flutuante" roxo de fones de ouvido.
  • Chat Nativo e Seguro: Ao clicar, uma aba de conversas desliza sem precisar que ele saia da tela. Essa janela identifica o Firebase local e o "log de sessão". Eles apenas conversam sabendo que você, administrador, verá.

Como Funciona Para a Gestão:

Os administradores utilizam o painel exclusivo /admin/support. Ele propõe três visões analíticas:

  1. Fila de Triagem Recente: Toda vez que um usuário manda a primeira mensagem, ela sobe para o topo da lista. Isso emite um alerta instantâneo. Em vez de rochas inertes, essa lista é vida real; mostra o último trecho enviado e o relógio em contagem de espera.
  2. Caixa de Entrada: Fica na barra lateral, categorizando as conversas por prioridade (buscável). Permite filtrar por tickets antigos e acessar o histórico mesmo se o painel for recarregado.
  3. Área de Bate-Papo: É onde você digita. A grande vantagem é que ela não é estática. A caixa tem rastreio do atendente (Auditoria) - se você "Admin Carlos" responder, vai sair a tag "Admin Carlos".
stateDiagram-v2 [*] --> Aberto Aberto --> Aguardando_Cliente : Admin pede info Aberto --> Urgente : Requer infraestrutura Aguardando_Cliente --> Resolvido : Dúvida sanada Aberto --> Resolvido : Finalizado e fechado Resolvido --> Aberto : Cliente manda nova msg
Controle de Status (O Dropdown Superior): Você pode trocar o status (Em Aberto, Urgente, Aguardando Cliente, Resolvido) a qualquer momento pelo seletor acima do Chat. Mudanças como "Esperando Cliente" ou "Urgente" disparam silenciosamente alertas em contexto corporativo no próprio chat para seu usuário se sentir ouvido.

10. Gestão e Criação de Salas (Vincular TV)

O Karalhokê Ultra utiliza um sistema de pareamento entre dispositivos para que o celular funcione como um controle remoto da TV (ou tela de projeção).

10.1 Como Instanciar uma Nova Sala

As salas não são criadas "no vácuo"; elas são vinculadas a um dispositivo de exibição (Host). O processo de criação segue este fluxo:

graph LR A[TV / Projetor] -->|Gera PIN 6 dígitos| B(Firestore: rooms) C[Celular / Controle] -->|Digita PIN| D{Validação} D -->|Sucesso| B B -->|Sync Realtime| E[Fila Sincronizada]

Passo a Passo:

  1. Abertura do Host (TV): O administrador (ou usuário VIP) abre a interface de TV (/tv/sala.html). O sistema gera automaticamente um PIN de 6 dígitos aleatório.
  2. Vinculação do Controle (Celular): No Dashboard do celular, o usuário clica em "Vincular TV" (ou lê o QR Code na tela da TV).
  3. Pareamento: Ao digitar o PIN correto, o Firestore vincula o ID do usuário ao activeRoomPin no documento do perfil e seta o status da sala como active.
Nota sobre o PIN: Embora sistemas legados usem 4 dígitos, o Karalhokê Ultra Premium utiliza exclusivamente 6 dígitos numéricos para garantir maior segurança contra acessos acidentais de outras salas.

10.2 O Fluxo de Fila (Queue)

Uma vez vinculado, o botão "CANTAR" no catálogo do celular passa a oferecer a opção "MANDAR PARA TV". Ao ser acionado:

  • A música é injetada na subcoleção rooms/{PIN}/queue.
  • A TV, que está com um listener ativo nesta coleção, detecta a entrada e gerencia a reprodução.
  • O Host pode gerenciar essa fila (pular, pausar ou remover) através do card de "Host" que aparece no seu Dashboard após a vinculação.