Manual de Funcionalidades TKMusic Linux

Capítulo 1 — Visão geral e operação básica

1.1 O que é

O TKMusic transforma um PC (ou Raspberry/TV box) em uma jukebox/karaokê:

• toca músicas, vídeos e karaokês gravados em HD/pendrive;
• controla créditos por faixa (modo Pago) ou libera tudo (modo Livre);
• permite venda de créditos por PIX;
• toca mídia grátis entre as escolhas do público;
• mostra nota ao final do karaokê;
• possui proteção de tela por slideshow, vinhetas e caça-prêmios;
• pode operar em dois monitores (uma tela para o operador, outra para o público);
• integra-se com um sistema de monitoramento online e com um app mobile de controle.

1.2 Estrutura da tela principal

A tela principal (TelaPrincipal) é uma janela Swing com:

• Grade de mídias (12 capas) no centro, com capa em destaque;
• Lista de mídias do álbum selecionado (ListMidias);
• Lista de espera (ListEspera) com as próximas mídias;
• Rodapé com a mídia tocando agora (capa, título, álbum, tempo, barra de progresso PBMidia);
• Cabeçalho com título, botões, saldo de créditos e indicador de carregamento de capas;
• Painéis de mensagem (avisos) e de caça-prêmios;
• QR Code de créditos quando aplicável;
• Dados do vídeo (LblDadosVideo, LblTempoDadosVideo) e painel de propaganda (PnlSuaPropaganda).

O cursor do mouse é ocultado (cursor 1×1 transparente) nas telas operacionais. O foco é mantido numa caixa de texto invisível (EdtGetKey) para capturar o teclado. A resolução suportada é maior que 1024×768, com ajuste automático de tamanho por percentual (porc, porcAltura).

1.3 Navegação com teclado

• Setas: movem o foco (cima/baixo/esquerda/direita).

As teclas de função são remapeáveis (Capítulo 8). Padrões: créditos em F1/F2, configurações em F9, pesquisar em F11, corrigir em F4, tocar/pausar em F5, escolher em F3, volume em Page Up/Page Down, fechar/parar em F12.

1.4 Avisos rápidos

Mensagens curtas aparecem conforme a ação (painéis de mensagem na tela principal). Há também o modal CRÉDITO INSERIDO / SALDO: N por 3 s.

Capítulo 2 — Navegação do catálogo

2.1 Tela de álbuns (home / gênero)

• A home mostra todos os álbuns (gênero "TODOS").
• A tela de gênero mostra apenas os álbuns daquele gênero.
• O cabeçalho mostra a posição do cursor (ÁLBUM X/Y quando aplicável).

Modos de exibição (Configurações → TEMAS):

• Grade padrão ou modo 4 capas (modo4Capas).
• Destacar seleção do álbum (padrão NÃO): fundo da seleção destacado.

2.2 Pesquisa por letras e por gêneros

• Pesquisar por letras: modal com botões A–Z (e dígitos) para saltar ao primeiro álbum que começa com o caractere. Timer para fechar automaticamente.
• Pesquisar por gêneros: modal com a lista de gêneros (TODOS, KARAOKÊ se existir, e os gêneros ativos). Navegação por foco real.

2.3 Pesquisa automática

Se pesquisarAutomaticamente = SIM, ao deixar o cursor sobre o texto da mídia por tempoPesquisarAutomaticamente segundos (padrão 5), a pesquisa é acionada automaticamente.

2.4 Pesquisa avançada

Tela PESQUISA AVANÇADA (TelaPesquisaAvancada) com teclado virtual (matriz de teclas) e resultados paginados. Pode ser ativada/desativada pela configuração ativarPesquisaAvancada (padrão SIM).

2.5 Navegação entre álbuns

• Setas esquerda/direita carregam o álbum, as capas, a lista de mídias e o destaque.
• Cima/baixo navegam na lista de mídias; o app auto-ajusta o tamanho da fonte do nome selecionado quando não cabe (versão 5.8.4).
• Ocultar CDs por palavras-chave: álbuns cujo nome contém as palavras configuradas em ocultar_cds.properties não aparecem.
• As mais tocadas: ranking por gênero, exibido quando mostrarAsMaisTocadas = SIM (oculta CDs ocultos).

2.6 Modal de faixas (mídias do álbum)

Abre ao selecionar um álbum. Lista as faixas em caixa alta com ícone do tipo (música/vídeo/karaokê). ENTER enfileira. Segurar a tecla escolher por 3 s na última faixa do primeiro álbum limpa toda a fila (easter egg, requer "Apagar lista de mídias na tela principal" = SIM) e avisa "Todas as midias removidas!".

Capítulo 3 — Reprodução, fila e lista de espera

3.1 Como uma mídia entra na fila

1. Usuário escolhe a faixa (modal de faixas, pesquisa ou teclado numérico).
2. O app verifica se há créditos suficientes para o custo daquele tipo.
3. Se houver, consome os créditos e coloca a mídia no fim da fila.
4. Aparece um aviso com a posição na fila.
5. Se nada estiver tocando, a mídia começa na hora.

Mídia repetida: configurável (podeMidiaRepetida, padrão SIM). Com NÃO, a mesma mídia não pode estar duas vezes na lista de espera.

3.2 Lista de espera

Tela/modal com as próximas mídias. Botão Remover devolve o crédito (exceto se cancelarSemRetornoCredito = SIM). A lista é persistida em CarregaListaDeEspera.

3.3 Contador de remover (desfazer)

Quando a mídia vai para a espera, há um tempo para corrigir (tempoRemoverMidia, padrão 20 s). Se apagarMidiaQqMomento = SIM, pode corrigir a qualquer momento.

3.4 Limpar a fila

• Remover a última da fila com a tecla corrigir (devolve crédito).
• Limpar toda a lista segurando a tecla corrigir (se limparListaEsperaSegCorrigir = SIM e modo livre) ou na posição 10 do CD (easter egg).
• Botão Remover todas as mídias na fila nas configurações.

3.5 Reprodução

Player: VLC embedded (uk.co.caprica.vlcj), suporte a todos os formatos, incluindo MKV.

Vídeo (.mp4, .avi, .mpeg, .mkv, .wmv, .mpg):

• inicia em miniatura no canto inferior direito;
• vai para tela cheia automaticamente após tempoVideoTelaCheia segundos (padrão 10, mínimo 3);
• qualquer interação volta para miniatura e reinicia a contagem;
• enquanto prepara, aparece CARREGANDO VIDEO...;
• o app conta o tempo da mídia com a barra de progresso (PBMidia) e exibe dados do vídeo (LblDadosVideo, LblTempoDadosVideo);
• aspect ratio configurável (idVideoAspectRatio, padrão 2 = PADRÃO/4:3/16:9);
• vídeos em tela verde corrigidos (versão 6.6.53);
• se tocarMidiaAutoAposParar = SIM, toca a próxima automaticamente ao parar; senão, exibe mensagem para iniciar.

Áudio: tela normal, com a capa do álbum no rodapé.

Dois monitores: se usarDualVideo = SIM, o vídeo também é exibido no segundo monitor (TelaDualVideo).

3.6 Controles

• Tocar/Pausar e Próxima podem ser exibidos (opção "Usar controles multimídia").
• A tecla FECHAR/Parar (F12) para a mídia do usuário e avança para a próxima. Não fecha modais nem equivale a ESC.
• Ao sair do app, a mídia do usuário pausa e, ao voltar, retoma na mesma posição (arquivo de mídia tocando para recuperação). A mídia grátis para e não retoma.
• Parar mídia segurando a tecla corrigir por alguns segundos (se a seleção estiver no CD 10) ou segurando a tecla parar.

3.7 Mídia com problema

Se o arquivo não abrir (inexistente, tamanho zero, corrompido), o app devolve o crédito exato da mídia e avança a fila.

Mensagens:

• Modo Pago: "Faixa com problema, seu crédito foi devolvido."
• Modo Livre: "Faixa com problema."

3.8 Recuperação ao reiniciar

O programa salva a mídia que estava tocando num arquivo e, ao reiniciar, pode retomar a reprodução (versão 6.6.57 corrigiu execução de karaokê nesse caso).

3.9 Prevenção de fechamento inesperado

O programa reabre automaticamente quando ocorre um erro e fecha inesperadamente (versão 5.17.3).

Capítulo 4 — Mídia grátis (demonstração)

4.1 O que é

Enquanto não há mídia do usuário na fila, o app toca, sozinho, uma mídia grátis sorteada do catálogo — para divulgar o conteúdo e manter a tela em uso.

Configurações → MÍDIAS → card Mídia grátis.

4.2 Quando a demo toca

Controlado por ControleMidiaGratis:

• tocarMidiaGratis = SIM (padrão NÃO);
• app em primeiro plano;
• sem varredura em andamento;
• tela atual não é Configurações nem Pesquisa;
• sem Espera do Cantor e sem Nota do karaokê;
• fila vazia e player ocioso;
• após esperar o intervalo configurado.

Intervalo = tempoMidiaGratis (minutos, padrão 4). tempoDaMidiaGratis (segundos, padrão 10) é a duração quando "Tocar até o final" = NÃO.

4.3 O que é sorteado

1. Sorteia um álbum do gênero em exibição (em "TODOS", sorteia de todos).
2. Sorteia uma faixa desse álbum.
3. Karaokê nunca é sorteado (naoTocarKaraokeGratis = SIM, padrão).

4.4 Duração

• tocarMidiaGratisAteOFinal = SIM (padrão): toca a mídia inteira.
• tocarMidiaGratisAteOFinal = NÃO: para após tempoDaMidiaGratis segundos.

4.5 Interrupção

• A demo é interrompida pela tecla FECHAR/Parar.
• Se interromperMidiaGratisQQTecla = SIM (padrão NÃO), qualquer tecla também interrompe.

Capítulo 5 — Karaokê

5.1 Como o app reconhece um karaokê

Arquivos de vídeo cuja pasta contém karaoke_tk são tratados como karaokê, além dos gêneros reconhecidos como "de karaokê".

5.2 Gênero de karaokê

Configurações → KARAOKÊ → generoKaraoke (padrão "KARAOKE"), arquivo KARAOKE.properties. Crédito por karaokê = creditoPorKaraoke (padrão 1).

5.3 Espera do Cantor

Antes de tocar qualquer karaokê, abre a tela ESPERA DO CANTOR (EsperaCantorKaraoke), em tela cheia, com:

• imagem de fundo;
• nome do álbum e música;
• "É SUA VEZ DE CANTAR!";
• instrução "PRESSIONE OK...";
• contagem quando o fechamento automático está ligado.

Como fecha: OK/ENTER, BACK, tecla FECHAR ou toque na tela. Com fecharAutomaticamenteTelaEsperaCantor = SIM (padrão), fecha sozinho em 6 s e mostra "INICIANDO KARAOKÊ EM: NN".

Som de espera: se tocarSomEsperaCantor = SIM (padrão), toca o áudio chama_cantor.

Bloqueio: com a espera aberta, as teclas são bloqueadas, exceto créditos, volume e as teclas de fechar.

5.4 Nota do karaokê

Ao terminar naturalmente um karaokê (NotaKaraoke):

1. o modal da nota abre com o número girando aleatoriamente (suspense);
2. toca o som de suspense (nota.wav);
3. ao terminar o som, a nota definitiva é revelada;
4. toca o jingle da faixa de pontuação;
5. o modal fecha sozinho 8 s depois da revelação.

Faixa da nota: sorteada entre pontuacaoMinima (padrão 40) e 100.

Jingles por faixa (iguais aos do projeto desktop):

Sem nota: se o usuário parar/pular a mídia (tecla FECHAR ou "Próxima"), a nota não é exibida. Fim natural, erro e fim do modo teste continuam exibindo.

Com a nota aberta, valem as mesmas regras de bloqueio da Espera (créditos, volume e fechar funcionam; o restante é bloqueado).

Se a nota não entra no Top 10, exibe a mensagem "OBRIGADO POR PARTICIPAR!" no lugar da posição (versão 6.7.48).

5.5 Alternar karaokê / jukebox

A tecla ALTERNAR KARAOKE (padrão K) alterna entre o modo karaokê e o modo jukebox, mudando o gênero. A troca é bloqueada enquanto uma mídia está tocando (mensagem ao usuário). Gera arquivos temporários durante a troca.

5.6 Modo "Somente Karaokê"

Configurações → KARAOKÊ → modoSomenteKaraoke (padrão NÃO). Quando ativo:

• o programa exibe apenas karaokês;
• usa a tela TelaSomenteKaraoke com 5 números (1–5) para escolha numérica;
• exibe música/álbum, créditos e lista "em espera";
• ao alternar para jukebox (tecla K), permite escolher músicas/vídeos.

5.7 Microfone

Configurações → KARAOKÊ permite:

• escolher a placa de som (idPlacaSom, padrão 0) e o dispositivo de microfone (microfoneNomeDispositivo, padrão "Mic Select");
• usar mic externo (usarMicExterno, padrão NÃO);
• volume do microfone (volumeMicrofone, padrão 50);
• volume mínimo do microfone (versão 5.10.0);
• manter microfone ligado fora do karaokê (desligarMicNaoKaraoke, padrão NÃO, ou seja, mantém ligado);
• botões LIGAR/DESLIGAR microfone para testes na tela de configuração;
• controle de volume do mic via teclas (M/N, padrão);
• comando sh para ligar/desligar o microfone (versão 5.4.10).

5.8 Catálogo de códigos de karaokê

O app monta a lista de códigos a partir do catálogo. Em Configurações → KARAOKÊ há acesso à consulta/pesquisa de códigos e à exportação em PDF dessa lista. Pode gerar o catálogo pelo código original do karaokê ou por código sequencial numérico (gerarCatalogoCodigoOriginalDoKaraoke).

5.9 Webcam / Tirar Foto

Após a nota do karaokê, se ativarTirarFoto = SIM (webcam.properties), abre a tela TIRAR FOTO para capturar a foto do cantor. A câmera é aberta com watchdog de 8 s para não travar. A tela é exibida sempre que a opção estiver marcada e a câmera disponível (versão 6.7.48).

Capítulo 6 — Créditos, PIX e controle de vendas

6.1 Modos de operação

• Modo Pago (padrão): cada mídia consome créditos.
• Modo Livre (modoLivre = SIM, padrão SIM no config atual): toca sem consumir créditos; as teclas de crédito avisam "Sistema no modo livre de créditos. Não é necessário inserir créditos." e o PIX fica indisponível.

Troca em Configurações → CRÉDITOS → "Mudar para LIVRE/PAGO".

6.2 Inserir créditos

Cada pulso insere creditosPorPulso (padrão 2) créditos, com valor valorDoPulso (padrão 1.0). Som de crédito ligável (tocarSomCreditos, padrão SIM). A inserção usa um temporizador para calcular os pulsos recebidos (versão 5.7.0).

Contadores: numeroPulsoInseridos, numeroGeralInicialPulsoInseridos, totalCreditosVendidos, totalGeralCreditosVendidos.

6.3 Custo por tipo de mídia

Configurações → CRÉDITOS → custo por faixa:

Sem créditos suficientes: saldo zero → "Favor inserir créditos!"; saldo > 0 → "Mídia requer N créditos.".

Valores diferenciados para retirada de créditos para músicas e vídeos (versão 5.15.0).

6.4 Comissão do bar

comissaoDoBar (padrão 30 %) aplicada no cálculo do "Valor a receber".

6.5 Pagamento por PIX (créditos)

Pela tecla Q abre o modal PAGAMENTO PIX (somente PIX ativo e modo Pago).

1. Cada toque soma valorCredito ao valor e numeroCreditosPorPix aos créditos ("PRESSIONE NOVAMENTE PARA SOMAR.").
2. Após 3 s sem tecla, o QR Code é gerado.
3. Contagem "EXPIRA EM NN SEGUNDOS" conforme tempoFecharPagamento (padrão 120).
4. A cada 5 s consulta o status do pagamento.
5. Aprovado: insere os créditos, registra a venda e mostra "PAGAMENTO APROVADO".
6. Rejeitado: "OS DADOS FORAM REJEITADOS PELO SERVIDOR." e fecha.
7. Sem Internet durante a consulta: o modal não fecha nem perde o QR; mostra "SEM CONEXÃO - TENTANDO NOVAMENTE..." e segue tentando.

Fechar a tela de pagamento por PIX com a tecla CORRIGIR ou VOLUME+ (versão 6.1.0). Pode ir adicionando valores a cada toque (versão 6.1.0).

Configuração do PIX (creditos_pix.properties): ativarPagamentoPix (padrão NÃO), valorCredito (1.0), numeroCreditosPorPix (2), taxaPix (1 %), tempoFecharPagamento (120), token, apiURL.

LIMPAR TOKEN apaga o token e desativa o PIX. No modo Livre, o PIX não pode ser ativado.

6.6 Controle de vendas (local)

Configurações → CRÉDITOS → Controle de Vendas:

• Saldo: créditos na máquina;
• Créditos vendidos: total de pulsos;
• Valor: créditos vendidos ÷ créditos por pulso × valor do pulso;
• Valor a receber: valor × (100 − comissão do bar)/100.

Botões: ACERTAR PAGAMENTO (grava registro e zera vendidos; o saldo da máquina não muda), RELATÓRIO DE VENDAS (tabela com LIMPAR RELATÓRIOS), EXPORTAR PARA PDF (abre o gerenciador de arquivos para escolher onde salvar).

Outros botões: Inserir Créditos Grátis (1 crédito, fora da contabilidade) e Zerar créditos (só o saldo).

6.7 Controle de vendas por PIX

Card independente: créditos vendidos (PIX), valor, valor creditado (taxa MP) e valor a pagar ao estabelecimento (comissão do bar). Botões ACERTAR PAGAMENTO e RELATÓRIO DE VENDAS (com LIMPAR RELATÓRIOS). Nova aba na sessão de créditos para exibir relatório de vendas totais (versão 6.5.0).

6.8 Recolher créditos

Tela RECOLHER CRÉDITOS (tecla C) exibe o total gerado na máquina desde o início, vendas PIX e permite recolher. Quando a máquina é zerada, os créditos não são apagados (versão 5.6.0). Melhor adaptação do texto na tela (versão 6.2.1). Exibe vendas PIX (versão 6.2.0). Bugfix no cálculo da comissão (versão 5.6.5) e no crédito inicial (versão 6.2.0).

Geração de QR code de relatório.

6.9 Créditos exibidos em R$

Para o cliente ID 25, os créditos são exibidos em R$ (versão 5.11.1).

Capítulo 7 — Catálogo de mídias

7.1 O que é

O catálogo é o índice de gêneros, álbuns e faixas gerado a partir de uma pasta do aparelho (HD/pendrive). O app usa o catálogo salvo em disco.

7.2 Configurar a pasta

Configurações → CATÁLOGO → Escolher pasta (começa em /storage ou na pasta atual). Gravada como pasta raiz da mídia (catalogo.properties: total=1, pos0=D:\MUSICAS).

7.3 Gerar catálogo

Botão Gerar catálogo (com barra de progresso PrgGerandoCatalogo):

1. apaga o catálogo anterior;
2. varre a pasta mostrando "Escaneando pastas..." e "Pastas escaneadas: N";
3. grava os álbuns em lote mostrando "Gravando novo catálogo..." e "Álbuns salvos: N de TOTAL";
4. ao concluir, "Catálogo gerado com sucesso!".

Gerar novamente descarta movimentações manuais de álbuns entre gêneros.

7.4 Limpar catálogo

Botão Limpar catálogo: apaga gêneros, álbuns e faixas. A pasta configurada é mantida.

7.5 Adicionar novos CDs

Tela ADICIONAR NOVOS CDS (AdicionarMidias) permite adicionar/remover CDs da máquina (copia de pastas de mídia, destaque de novos CDs por N dias numDiaMidiaDestaque=10). Possibilidade de apagar CDs da máquina pela interface (versão 5.11.0). Indica os que já possuem na máquina ("possui", versão 5.11.0).

7.6 Gêneros

Configurações → GÊNEROS:

• NOVO GÊNERO: cria com nome ou com pasta (SALVAR E ESCANEAR).
• Cada gênero: EDITAR, + (mover álbuns), Excluir, MOSTRAR: SIM/NÃO.
• Mover álbuns ([+]): busca em todo o catálogo (mínimo 2 letras); marca/desmarca com OK; FECHAR aplica; mostra "N ÁLBUM(S) MOVIDO(S) PARA ESTE GÊNERO".
• Configuração de Inicialização: gênero inicial, retorno para TODOS após 30 s.

7.7 Detecção de capas

ativaDetectarCapasCds (padrão NÃO): ativa a detecção de capas de CDs.

7.8 Como o app identifica as mídias

• Áudio: mp3, wav, wma.
• Vídeo: mp4, avi, mpeg, mkv, wmv, mpg.
• Arquivos iniciados por ._ (lixo do macOS) são ignorados.
• Karaokê: caminho contendo karaoke_tk.
• Capas: imagens chamadas capa, cover ou folder na pasta do álbum.
• Ocultar CDs: palavras-chave em ocultar_cds.properties.

7.9 Detecção de dispositivos externos

DetectaDispositivosExternos detecta inserção de USB/CDs externos e abre a caixa de adicionar CDs.

Capítulo 8 — Teclas configuráveis e atalhos

8.1 Tela TECLADO

Configurações → TECLADO (ConfigTeclado). Cada linha mostra função, tecla atual e REMAPEAR. Ao remapear, o app captura a próxima tecla pressionada. Tecla já usada em outra função: "Tecla já utilizada em ...!" e não altera. O botão Cancelar interrompe a captura.

8.2 Funções e teclas padrão

(De teclado.properties.)

Controle remoto mapeado (se usarControleRemoto): Enter = escolher, P = tocar, R/ESC = corrigir, S/Backspace = parar.

8.3 Volume

• Cada toque ajusta valorAumentarVolume % (padrão 5).
• O valor fica entre 0 e o Volume máximo (volumeMaximo, padrão 100).
• O modal VOLUME (NN%) aparece por 3 s.
• Segurar a tecla repete o ajuste.
• O volume inicial (volumeInicial, padrão 60) é aplicado ao abrir o programa; voltar do segundo plano não reinicia o volume.
• O app espelha o volume no mixer de mídia (volumeMixerPrincipal, padrão 150).

8.4 Atalhos especiais (easter eggs) - Apenas créditos livres

8.5 Cancelar sem retorno de crédito

cancelarSemRetornoCredito (padrão NÃO): se SIM, ao corrigir não devolve o crédito.

8.6 Fechar ao segurar parar

ativaFecharAoSegurarParar (padrão SIM): segurar a tecla parar fecha a mídia.

8.7 Atalhos padrão do programa (resumo)

Resumo dos atalhos padrão exibidos na página do TKMusic Linux. Todas as teclas são configuráveis em Configurações → TECLADO.

Capítulo 9 — Configurações — referência por módulo

Abas roláveis na horizontal. Todos os textos em CAIXA ALTA; campos numéricos não aceitam confirmação vazia ("INFORME UM VALOR.").

9.1 SENHA

Senha de acesso (5 teclas, padrão F5F5F5F5F5).

9.2 CATÁLOGO

• Pasta raiz da mídia: Escolher pasta.
• Ações: Gerar catálogo, Limpar catálogo.

9.3 ADD/REMOVER MÍDIAS

Adicionar/remover CDs da máquina, copiar pastas, destacar novos CDs.

9.4 GÊNEROS

NOVO GÊNERO; Gêneros do catálogo (EDITAR, +, Excluir, MOSTRAR); Configuração de Inicialização.

9.5 DIVERSOS

Configurações diversas (acessibilidade, temas, etc.).

9.6 KARAOKÊ

Ver Capítulo 5.

9.7 MÚSICAS/VÍDEOS

• Custo por faixa (karaokê, vídeo, música).
• Mídia grátis (ver Capítulo 4).
• Modo democracia (ver Capítulo 13).
• Lista de espera (tempo para corrigir, permitir remover, apagar lista na tela principal, tempo para remover mídia, botão remover todas, limpar lista ao segurar corrigir).
• Vídeo (aspect ratio, tempo vídeo tela cheia, usar tempo real).
• Prévia de mídia (ativaPreviaMidia).
• Ocultar CDs (palavras-chave).

9.8 CRÉDITOS

• Modo do sistema (LIVRE/PAGO), Inserir Créditos Grátis, Zerar créditos, Mudar para LIVRE/PAGO.
• Ajustes: valor do pulso, créditos por pulso, comissão do bar.
• Controle de Vendas (local e PIX).
• Custo por faixa.

9.9 CONFIGURAÇÕES GERAIS

• Teclado/Interface: temas, cores, fonte das listas, modo 4 capas, destacar seleção.
• Slideshow: ver Capítulo 11.
• Temas/Cores: ver 9.10.
• Sistema: nome do ponto, volume inicial/máximo, ajuste de volume, volume do mixer, detectar capas, integração online, controle mobile, usar dois monitores, usar dual video, pesquisa avançada, exibir apenas mensagens em ordem de espera.
• Integração online: ver Capítulo 16.

9.10 TEMAS E CORES

• Tema selecionado (temaSelecionado, padrão tema_01.png);
• Temas aleatórios (padrão NÃO);
• Modo 4 capas (padrão NÃO);
• Destacar seleção do álbum (padrão NÃO);
• Tamanho da fonte das listas (tamanhoFonteListas, padrão 20);
• Cores dos labels e listas (configuráveis).

9.11 PROPAGANDAS

Ver Capítulo 12.

9.12 CACA-PREMIO

Ver Capítulo 10.

9.13 SOBRE

Card de registro/licença: Nome registro, versão, dispositivo, ponto, status, equipamento, código de licença, data de registro, VALOR DO PROGRAMA, REGISTRAR CÓPIA, RECUPERAR LICENÇA, estado do envio.

Capítulo 10 — Caça-Prêmios

10.1 O que é

Sistema de prêmios sorteados conforme o acúmulo de créditos na máquina. Cada prêmio tem uma descrição, um valor (em créditos) para sair e um valor acumulado na máquina.

10.2 Configuração

Configurações → CACA-PREMIO:

• Ativar Caça-Prêmios (ativado, padrão NÃO).
• 6 prêmios com descrição (até 35 chars) e valor para sair (créditos).
• Tempo da tela de premiação (tempoTelaPremiacao, padrão 5 s).
• Nº de créditos grátis do prêmio (numeroCreditosGratisPremio, padrão 1).
• Centralizar Caça-Prêmio (centralizarCacaPremio, padrão SIM).
• Exibir somente quando o prêmio for sorteado (exibirSomenteQuandoPremioSair, padrão NÃO).
• Prêmios aleatórios: ativar (ativarPremiosAleatorios, padrão NÃO) e valor para sair (valorParaSairPremiosAleatorio, padrão 3).
• Foto do prêmio 4: pode adicionar uma imagem (copiada para a pasta de imagens dos prêmios) e apagar.
• Relatório de prêmios sorteados (tabela com LIMPAR).

Prêmios padrão:

10.3 Funcionamento

A cada inserção de créditos, o sistema acumula o valor na máquina. Quando o acumulado atinge o valor configurado de um prêmio, ele é sorteado e a tela de premiação (CacaPremios) é exibida por N segundos. Fechar com a tecla volume+.

Prêmios aleatórios usam valor separado. Atualização de valores na máquina ao recolher (versão 5.15.1). Bugfix na saída dos prêmios com vários créditos (versão 5.4.1).

Capítulo 11 — Slideshow

Configurações → SISTEMA/SLIDESHOW (slideshow.properties):

• Ativar slideshow (ativarSlide, padrão NÃO).
• Exibir em standby (exibirStandBy, padrão SIM).
• Tipo: imagem ou vídeo (tipoSlide, padrão v = vídeo).
• Tempo mudar imagem (tempoMudarImagem, padrão 5 s).
• Tempo iniciar slide (tempoIniciarSlide, padrão 5 s).
• Pasta de imagens do slideshow (com preview).

O slideshow (TelaSlideShow) exibe imagens/vídeos da pasta configurada e pode ser exibido em standby. Controlado por timer (TimerTelaSlideShow), que para ao pesquisar e inicia ao voltar. Bugfix de não aparecer (versão 5.17.50) e de aparecer em cima da Espera do Cantor/Nota (versão 5.17.54).

Capítulo 12 — Propagandas (vinhetas)

Configurações → PROPAGANDAS (propagandas.properties):

• Ativar vinheta (ativarVinheta, padrão NÃO).
• Sortear vinheta (sortearVinheta, padrão NÃO).
• Reproduzir a cada música (reproduzirCadaMusica, padrão NÃO).
• Selecionar vinheta (lista).
• Seu texto (até 50 chars, seuTexto) e Seu contato (até 50 chars, seuContato).
• Adicionar/remover arquivos de vinheta (áudio/vídeo).

A vinheta pode tocar antes de cada música ou ser sorteada. O texto/contato são exibidos no painel de propaganda (PnlSuaPropaganda). Controlado por TimerSuaPropaganda.

Capítulo 13 — Modo Democracia

Configurações → MÍDIAS → Modo Democracia (midias.properties):

• Ativar modo democracia (ativarModoDemocracia, padrão NÃO).
• Mídias por pessoa (midiaPorPessoaDemocracia, padrão 4): quantas mídias cada pessoa pode enfileirar.
• Tempo de espera (tempoEsperaModoDemocracia, padrão 1 min): tempo entre turnos.

Controlado por ControleModoDemocracia, que verifica se pode selecionar mídia e o limite por pessoa.

Capítulo 14 — Dois monitores e Dual Video

14.1 Dois monitores

Configurações → SISTEMA → "Usar dois monitores" (usarDualVideo, padrão NÃO). Com dois monitores, o programa pode exibir o catálogo no monitor do operador e a reprodução no monitor do público (moveJFrameToSecondMonitor).

14.2 Dual Video

Configurações → SISTEMA → "Usar Dual Video" (padrão NÃO). Permite exibir vídeo em dois lugares simultaneamente (TelaDualVideo, VLC embedded).

14.3 Tela "Somente Karaokê"

Quando o modo somente karaokê está ativo, as telas TelaSomenteKaraoke e TelaSomenteKaraokeTop são exibidas para o público, com a letra e a nota.

Capítulo 15 — Webcam, Tirar Foto e Ranking de Karaokê

15.1 Webcam / Tirar Foto

Configurações → KARAOKÊ → "Ativar WebCam" (ativarTirarFoto, padrão SIM, em webcam.properties). Após a nota do karaokê, abre a tela TIRAR FOTO (TirarFoto) para capturar a foto do cantor.

• A câmera é aberta com watchdog de 8 s para não travar (versão 6.7.49).
• A tela é exibida sempre que a opção estiver marcada e a câmera disponível (versão 6.7.48).
• Não desativa a opção automaticamente em caso de erro (versão 6.7.47).
• Fechamento sincronizado; logs de diagnóstico (resolução VGA/QVGA).
• Foto usada para o ranking do karaokê.

15.2 Ranking de Karaokê

Tela RANKING DE KARAOKÊ (TelaRankingKaraoke, tecla R) exibe o top de karaokê com pontuações e fotos. Controlado por RankingKaraokeFuncoes:

• grava pontuação/foto;
• ordena e exibe por tempo (tempoTelaRanking = 15 s, tempoExibirTelaRanking = 10 s);
• pode disparar mídia ao fechar.

Bugfix da tela preta (versão 5.16.5).

15.3 Tela "Tocando Agora"

Tela TOCANDO AGORA (TocandoAgora) exibe a mídia em reprodução em tela cheia (capa grande, título, álbum, barra de progresso, horário, próxima mídia, volume, controles de microfone/stop). Controlada por ControleTelaTocandoAgora. Bugfix da tecla corrigir não fechar (versão 5.5.2) e de não aparecer (versão 5.17.50).

Capítulo 16 — Integração online e controle remoto pelo app

16.1 Integração com sistema de monitoramento online

Configurações → SISTEMA → Integração online (integracao.properties):

• Ativar (ativo, padrão NÃO).
• ID do cliente (idClienteSinc, padrão 1).
• ID da jukebox (idJukeboxIntegracao, padrão 16).
• Código (codigoJukeboxIntegracao, padrão "001").
• Nome (nomeJukeboxIntegracao).
• URL da API (apiUrl).
• Tempo de sincronização (tempoSincronizacao, padrão 10 min).
• API Key (apiKeyIntegracao).

Quando ativo, o programa envia dados de hardware (IntegracaoDadosHardware) e vendas para o servidor de monitoramento (versão 6.7.46).

16.2 Controle remoto pelo app mobile

Configurações → SISTEMA → "Ativar controle mobile" (ativarControleMobile, padrão NÃO, em config.properties). Permite controlar a jukebox pelo aplicativo mobile (ControlarPeloApp, ControleFuncoesRemotas).

Capítulo 17 — Segurança, registro e versão de avaliação

17.1 Segurança

Seguranca: id do cliente, MAC, hash, versão demo, nome da empresa, número de série, registro. DadosSistema: coleta dados do sistema (Linux/Windows).

17.2 Registro

RegistrarCopia: gerar código para registro, importar registro, salvar. Configurações → SOBRE → card de registro/licença.

17.3 Versão de avaliação

ControleVersaoDemo controla a versão de avaliação (contador). A versão demo tem fim (FIM DA VERSÃO DE AVALIAÇÃO).

Capítulo 18 — Robustez, recuperação e diagnóstico

18.1 Recuperação de mídia ao reiniciar

O programa salva a mídia que estava tocando num arquivo (CarregaMidiaTocando) e, ao reiniciar, pode retomar a reprodução. Bugfix para execução de karaokê nesse caso (versão 6.6.57).

18.2 Backup de configurações

Realiza backup das configurações quando o programa é iniciado/zerado (versão 5.6.0).

18.3 Prevenção de fechamento inesperado

O programa reabre automaticamente quando ocorre um erro e fecha inesperadamente (versão 5.17.3).

18.4 Tratamento de exceções de Input Method

AwtExceptionHandler evita crashes de Input Method.

18.5 Logs

Logs em log/*.properties com timestamp (função funcoesGlobais.gravarLog).

18.6 WebCam watchdog

A tela de foto possui watchdog de 8 s para não travar o programa (versão 6.7.49).

Apêndice A — Tabela de mensagens do sistema

Apêndice B — Valores padrão de fábrica

(De config/*.properties e inicialização.)

Apêndice C — Glossário

• Álbum: pasta com mídias e (opcional) capa.
• Gênero: agrupamento de álbuns (ex.: TODOS, KARAOKÊ).
• Mídia grátis (demo): mídia tocada sozinha enquanto a fila está vazia.
• Lista de espera: próximas mídias a tocar.
• Espera do Cantor: tela cheia antes de um karaokê.
• Nota do karaokê: pontuação sorteada ao fim de um karaokê.
• Caça-Prêmios: sistema de prêmios por acúmulo de créditos.
• Vinheta: propaganda em áudio/vídeo tocada entre músicas.
• Slideshow: apresentação de imagens/vídeos em standby.
• Modo Democracia: controle de turnos na escolha de mídias.
• Dual Video / Dois monitores: exibição em dois monitores.
• WebCam / Tirar Foto: captura de foto do cantor após a nota.
• Integração online: envio de dados para o servidor de monitoramento.
• Modo Somente Karaokê: exibição apenas de karaokês com escolha numérica.