Manual de Funcionalidades TKMusic TVBOX

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

1.1 O que é

O TKMusic transforma uma TV box (ou tablet) em uma jukebox/karaokê:

• toca músicas, vídeos e karaokês gravados em pendrive/HD externo;
• opcionalmente toca vídeos do YouTube;
• 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 com animações.

1.2 Estrutura da tela principal

A tela é dividida em três faixas fixas:

Rodapé sempre presente: mesmo sem mídia tocando, o rodapé aparece com o logo do estúdio e os textos institucionais. Com mídia, mostra capa, título, álbum, tempo e barra de progresso.

Alternância do rodapé: a cada ciclo, o rodapé fica 30 segundos mostrando a mídia TOCANDO AGORA e 10 segundos mostrando a PRÓXIMA NA FILA (capa, título e álbum do próximo item). Enquanto mostra a próxima, no lugar do relógio aparece a etiqueta PRÓXIMA NA FILA.

O rodapé não é escondido quando se entra nas Configurações — cabeçalho e rodapé são ocultados apenas na tela de Configurações (ver 1.5).

1.3 Cabeçalho em detalhe

• PESQUISAR: abre o modal de pesquisa (Capítulo 2).
• FILA (N): abre a Lista de Espera em modal (Capítulo 3). O número N é a quantidade de mídias em espera, sem contar a que está tocando. Com N = 0 o botão fica desabilitado (não recebe foco nem toque).
• CONFIG: abre as Configurações (com senha, se configurada).
• Pill de créditos: mostra o saldo (LIVRE no modo Livre, ou o número).
• NA FILA (X): pill apenas informativa que aparece no lugar dos botões quando eles estão ocultos pela configuração "Ocultar botões do cabeçalho".
• CAPAS...: indicador amarelo com spinner que aparece ao lado do título enquanto as capas dos álbuns estão sendo carregadas.
• Controles multimídia (quando ligados nas Configurações): botões Play/Pause e Próxima, exibidos somente quando há mídia do usuário tocando (não aparecem para a mídia grátis nem para vídeo do YouTube).

Bloqueio de foco: com qualquer modal aberto, os botões do cabeçalho ficam não focáveis, para o controle remoto não "vazar" para trás do modal.

1.4 Navegação com o controle remoto

• Setas: movem o foco entre álbuns, botões, listas e abas.
• OK / ENTER: seleciona/confirma.
• BACK / ESC / VOLTAR: fecha o modal atual; sem modal, abre a confirmação de saída ("TEM CERTEZA DE QUE DESEJA SAIR?").
• Tecla esquerda (←): fecha os modais de pesquisa, letras, gêneros, faixas, fila e resultados de pesquisa.
• Toque na tela: funciona em todas as telas (tablet/box com touch).

Segurar OK por 3 segundos e soltar abre a tela de pesquisa (PESQUISAR POR:) em vez de acionar o item focado. Soltar antes de 3 s executa a ação normal.

1.5 Cabeçalho e rodapé nas Configurações

Ao entrar nas Configurações, o cabeçalho e o rodapé são ocultados para dar área à tela de ajustes. Ao voltar, ambos reaparecem.

Além disso, abrir as Configurações para a mídia que está tocando: a mídia é removida da fila e a reprodução para. Ao sair das Configurações, a fila volta a andar (a próxima mídia começa), inclusive com a espera do cantor quando for karaokê.

1.6 Avisos rápidos (modais de mensagem)

As mensagens curtas aparecem no topo da tela (logo abaixo do cabeçalho), num card preto translúcido com borda laranja:

• Favor inserir créditos! — quando o saldo é zero e a mídia é paga. Este aviso tem fundo vermelho.
• Mídia requer N créditos. — quando há saldo, mas insuficiente para o custo da mídia. Também com fundo vermelho.
• CRÉDITO INSERIDO / SALDO: N — confirmação de pulso, com card próprio, exibido por 3 segundos, acima de todos os outros modais. Sai também quando o vídeo está em tela cheia, com a Espera do Cantor, com a Nota do karaokê ou com a tela "Tocando Agora" aberta.
• VOLUME (NN%) — barra de volume, por 3 segundos.

A largura desses cards acompanha o tamanho do texto (mínimo e máximo definidos), e as fontes escalam conforme a resolução da tela (720p, 1080p, 4K).

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

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

• A home mostra todos os álbuns do catálogo (gênero "TODOS").
• A tela de gênero mostra apenas os álbuns daquele gênero e exibe o nome do gênero em uma linha compacta no topo (sem botão "Voltar" — use BACK).
• O cabeçalho mostra a posição do cursor: ÁLBUM X/Y.

Dois modos de exibição (Configurações → SISTEMA → Comportamento tela principal):

• GRADE (padrão): grade adaptativa.
• LISTA: uma única linha horizontal, com cards maiores; navegação apenas com esquerda/direita.

Card de álbum: capa (ou imagem "sem capa"), nome em até 2 linhas (altura fixa, com rolagem tipo marquee quando selecionado), número de faixas e uma linha divisória. Quando selecionado, o card ganha fundo laranja, borda destacada e o título em laranja/negrito. Álbuns de karaokê exibem um selo de microfone no canto superior direito da capa.

O cursor sempre começa no primeiro álbum ao entrar/trocar de gênero. Ao fechar um modal, o cursor volta ao álbum que estava selecionado.

2.2 Modal PESQUISAR (BrowseModal)

Aberto pela tecla PESQUISAR, pelo botão do cabeçalho ou segurando OK por 3 s.

Título: PESQUISAR POR:

Botões (na ordem):

1. POR LETRAS
2. GÊNEROS
3. PESQUISA AVANÇADA (oculto se a opção "Permitir pesquisa avançada" = NÃO)
4. FECHAR

No modo YouTube (tela do YouTube aberta), o primeiro item passa a ser PESQUISAR NO YOUTUBE, e "POR LETRAS" e "PESQUISA AVANÇADA" ficam ocultos.

O modal fecha sozinho após 10 segundos sem interação.

2.3 POR LETRAS

• Título POR LETRAS, subtítulo SELECIONE O PRIMEIRO CARACTERE.
• Uma linha horizontal com os primeiros caracteres únicos dos álbuns do gênero em exibição (dígitos antes de letras: [1][3][A]...).
• Setas esquerda/direita percorrem os caracteres; cima/baixo levam ao botão FECHAR; OK seleciona; BACK, tecla PESQUISAR, FECHAR e esquerda fecham.
• Ao escolher um caractere, o app vai para o primeiro álbum que começa com ele. Se esse álbum estiver longe na lista, aparece o card LOCALIZANDO LETRA "X"... / AGUARDE... durante a rolagem.
• Fecha sozinho após 10 s de inatividade.

2.4 GÊNEROS

• Título GÊNEROS, subtítulo SELECIONE O GÊNERO PARA NAVEGAR.
• Itens: TODOS, KARAOKÊ (se existir gênero de karaokê no catálogo), YOUTUBE (se "Reproduzir vídeo do YouTube" = SIM), os gêneros ativos e FECHAR no final.
• Escolher TODOS volta para a home com todos os álbuns.
• Navegação por foco real: as setas andam item a item e a lista rola o mínimo necessário (sem "saltar" para o topo). Esquerda, BACK, FECHAR e toque fora fecham. Fecha sozinho após 10 s.

2.5 Pesquisa avançada

Passo 1 — digitação (modal PESQUISA DE MÍDIAS):

• Campo de texto com foco automático e teclado na tela.
• Botões PESQUISAR e FECHAR.
• Campo vazio: aviso "Digite o que deseja pesquisar."
• Fecha sozinho após 60 s sem interação; BACK, FECHAR, ESC e tecla PESQUISAR também fecham.

Passo 2 — resultados:

• Título RESULTADOS DA PESQUISA e a linha N RESULTADOS ENCONTRADOS PELO TERMO: "termo" (singular: "1 RESULTADO...").
• Se houver gênero selecionado, aparece SOMENTE NO GÊNERO: NOME — a pesquisa é filtrada pelo gênero em exibição.
• Ao navegar pelos resultados, um painel mostra a capa e o nome do álbum da mídia focada.
• OK enfileira a mídia (consome créditos e mostra a posição na fila).
• Quando não há resultados, aparece o botão NOVA PESQUISA (focado), que reabre a digitação.
• Botão FECHAR, dica amarela "USE A TECLA DA ESQUERDA PARA FECHAR." e auto-fechamento em 30 s.

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

• Abre ao selecionar um álbum. Título com o nome do álbum.
• Lista as faixas em CAIXA ALTA, cada uma com ícone do tipo (mic/áudio/vídeo/YouTube).
• OK enfileira a faixa escolhida.
• Botão FECHAR com a dica "Pressione tecla Esquerda para fechar." embaixo.
• Fecha sozinho após 10 s sem interação. Rolagem da lista e teclas reiniciam o contador. Toque fora do card fecha.
• Segurar OK por 3 segundos na última faixa do primeiro álbum da tela limpa toda a fila e mostra "Todas as midias removidas!" (ver Capítulo 9).

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. Se já houver mídia, ela aguarda na Lista de Espera.

Mídia repetida: a mesma mídia não pode estar duas vezes na lista de espera. A mídia que está tocando agora não conta como duplicada — se o usuário escolher de novo a faixa em reprodução, ela entra na fila normalmente.

3.2 Lista de Espera (modal FILA)

• Abre pelo botão FILA (N) do cabeçalho ou pela tecla EXIBIR LISTA DE ESPERA (padrão L).
• Título LISTA DE ESPERA (N).
• Mostra apenas as próximas mídias (a que está tocando não aparece).
• Cada item mostra ícone do tipo, número, título e álbum.
• Botão Remover devolve o crédito ao saldo e cancela o contador de "desfazer" quando é o último item.
• Fecha: BACK, tecla esquerda, botão FECHAR ou 10 s sem interação.
• Com a fila sem próximas mídias (N = 0), o botão e a tecla ficam bloqueados.

3.3 Contador de remover (desfazer)

Quando a mídia é enfileirada e vai para a espera, aparece um contador na tela com o tempo para desfazer. Se o usuário escolher outra mídia antes do tempo terminar, o contador reinicia do valor cheio (corrigindo a última selecionada).

O contador não aparece quando a mídia começa a tocar imediatamente (nada tocando, ou demo interrompida por "tocar imediatamente"), porque não há o que desfazer na fila.

3.4 Reprodução

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

• inicia em miniatura no canto inferior direito;
• vai para tela cheia automaticamente após o tempo configurado (MÍDIAS → Vídeo → "Vídeo tela cheia em (segundos)", padrão 10 s, mínimo 3);
• qualquer interação volta para miniatura e reinicia a contagem;
• com o vídeo em tela cheia, um cabeçalho sobreposto aparece em ciclo: 30 s oculto → 20 s visível, com capa, título, álbum, tempo e barra (ou a etiqueta PRÓXIMA NA FILA);
• enquanto o vídeo é preparado, aparece CARREGANDO VIDEO... sobre a miniatura;
• o vídeo não entra em tela cheia antes de começar a tocar de verdade.

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

Mini: o vídeo pequeno flutua sobre o conteúdo (não reserva espaço) e respeita a altura do rodapé.

3.5 Controles

• Tocar/Pausar e Próxima podem ser exibidos no cabeçalho (opção "Usar controles multimídia").
• Próxima fica desabilitado quando não há outra mídia na fila.
• A tecla FECHAR/Parar (padrão F) para a mídia do usuário e avança para a próxima. Ela não fecha modais nem equivale ao BACK.
• Ao sair do app (HOME), a mídia do usuário pausa e, ao voltar, retoma na mesma posição. A mídia grátis para e não retoma. Nada toca em segundo plano.
• Se o usuário pausou manualmente, ao voltar continua pausado (respeita a escolha).

3.6 Mídia com problema

Se o arquivo não abrir (inexistente, tamanho zero, corrompido ou travado por mais de 10 s), o app:

1. tenta o player nativo do Android (quando a opção está ligada);
2. se falhar, 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."
• Falha de rede (YouTube): "Sem conexão com a Internet." (mais "Seu crédito foi devolvido." no modo Pago).

3.7 Preview da fila

A cada 30 segundos de inatividade na tela principal, aparece um modal pequeno LISTA DE ESPERA (N) com as 5 próximas mídias e, no rodapé, "E MAIS N NA FILA" quando houver mais. Ele fecha sozinho em 10 s ou em qualquer interação. Pode ser desligado em Configurações → SISTEMA → "Exibir modal da lista de espera a cada 30 segundos".

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

Todos os requisitos:

• "Tocar mídia grátis" = SIM;
• app em primeiro plano;
• catálogo 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;
• depois de esperar o intervalo configurado.

Intervalo = "A cada (minutos)". Padrão 20 minutos. Com o valor 0, o intervalo vira 4 segundos — comportamento "Média Player", descrito na tela: "Coloque 0 para usar como Média Player."

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 como mídia grátis.

4.4 Duração

• "Tocar até o final" = SIM (padrão): toca a mídia inteira.
• "Tocar até o final" = NÃO: para após "Duração (segundos)". O campo "Duração (segundos)" fica desabilitado quando a opção é SIM.

4.5 Interrupção

• A demo é interrompida pela tecla FECHAR/Parar.
• Se "Interromper mídia grátis com qualquer tecla" = SIM, qualquer tecla também interrompe.

4.6 Mídia do usuário durante a demo

"Interromper a mídia grátis para tocar mídia do usuário imediatamente":

• SIM (padrão): a demo para na hora e a mídia escolhida toca.
• NÃO: a demo continua até o fim e a mídia escolhida aguarda na fila.

Ao terminar a demo (naturalmente ou interrompida), se houver mídia na fila ela começa a tocar. Quando a fila esvazia, o contador da demo volta a correr e a próxima demo entra sozinha.

4.7 Destaque do álbum da demo

"Destacar álbum ao tocar mídia grátis" (padrão NÃO):

• SIM: ao começar a demo, o cursor vai para o card do álbum sorteado (sem abrir o modal de faixas). Se o álbum estiver longe na lista, aparece o card LOCALIZANDO ÁLBUM... durante a rolagem.
• Se houver qualquer modal aberto no instante em que a demo começa, o destaque é ignorado.

4.8 Demo na proteção de tela

Com a proteção de tela ativa e uma demo de áudio tocando:

• a proteção entra 5 s depois do início da demo;
• exibe a capa do álbum da demo flutuando (ping-pong) por cima do título;
• ao ser fechada pelo usuário, reaparece após 30 s enquanto a demo durar;
• quando a demo termina, a proteção se fecha sozinha;
• demo de vídeo não dispara esse modo.

Capítulo 5 — Karaokê

5.1 Como o app reconhece um karaokê

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

5.2 Espera do Cantor

Antes de tocar qualquer karaokê, abre o modal ESPERA DO CANTOR, em tela cheia, com:

• imagem de fundo;
• nome do álbum e música (em caixa alta);
• "É 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 "Fechar tela de espera automaticamente" = SIM, fecha sozinho em 6 s e mostra "INICIANDO KARAOKÊ EM: NN".

Som de espera: se "Som de espera do cantor" = SIM, toca o áudio chama_cantor.

Bloqueio: com a espera aberta, todas as teclas são bloqueadas, exceto: créditos (W/E e B), volume (J/H e volume do controle) e as teclas de fechar. A tela de trás não fica navegável.

5.3 Nota do karaokê

Ao terminar naturalmente um karaokê:

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 "Pontuação mínima para nota" e 100. Ex.: mínimo 40 → sorteia de 40 a 100.

Jingles por faixa (iguais aos do projeto desktop):

Sem nota: se o usuário parar/pular a mídia (tecla FECHAR ou botão "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).

5.4 Alternar gênero de karaokê (tecla K)

Configurações → KARAOKÊ → "Gênero alternar para karaokê".

• A tecla ALTERNAR KARAOKE (padrão K) alterna a tela entre o gênero de karaokê configurado e TODOS.
• A tela KARAOKÊ mostra a mensagem "A TECLA K SERÁ USADA PARA ALTERNAR", com a tecla realmente mapeada.
• Com NÃO ALTERNAR, a tecla não faz nada.
• Com o modo karaokê numérico ligado, a tecla K fecha o teclado e vai para TODOS; voltando, abre o gênero karaokê já com o teclado.

5.5 Modo karaokê numérico

Ativa em Configurações → KARAOKÊ → "Ativar modo para karaokê numérico".

Requisito: existir pelo menos um gênero de karaokê no catálogo (senão o botão fica desabilitado, com explicação na tela).

Como funciona:

• a tela de álbuns é substituída por um teclado numérico (na home e nas telas de gênero — não na tela do YouTube);
• o cliente digita o código da faixa;
• enquanto digita, o app consulta o código e mostra o nome da mídia encontrada (com capa e orientação "MÍDIA ENCONTRADA · SELECIONE O BOTÃO ESCOLHER");
• código inexistente mostra "Karaokê não encontrado." já durante a digitação;
• CORRIGIR (D) apaga um dígito; o botão virtual Del faz o mesmo;
• ESCOLHER enfileira a mídia (consome crédito e mostra a posição).

Dois tamanhos de teclado:

O teclado pequeno é translúcido para não esconder a letra do karaokê, não escurece a tela e mostra o título "Digite o código da música" rolando quando não couber.

Ao escolher com sucesso, o teclado fecha.

Durante a reprodução, o teclado fica oculto; ele só reabre quando: - uma nova tecla é aceita pelo fluxo de reabertura; ou - o usuário toca na tela (modo numérico ativo e mídia tocando).

Após a nota, se não houver mídia na fila, o teclado grande reabre sozinho. A nota aparece na frente do teclado (o teclado é fechado assim que a nota abre).

Opção "Usar ENTER/OK para escolher" (padrão NÃO):

• SIM: as setas não navegam no teclado virtual e ENTER/OK executa direto a ação ESCOLHER; o destaque da tecla desaparece. Indicado para teclado físico ou controle simples. O clique/toque nas teclas continua funcionando.
• NÃO: comportamento padrão (setas navegam, OK aciona a tecla destacada).

Exclusividade com outras opções:

• ligar o modo numérico força "Gênero alternar para karaokê" = NÃO ALTERNAR e "Retornar para TODOS após 30 s" = NÃO;
• ativar "Retornar para TODOS após 30 s" desliga o modo numérico (com aviso).

5.6 Catálogo de códigos de karaokê

O app monta internamente 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.

Capítulo 6 — YouTube

6.1 Ativação

Configurações → YOUTUBE → "Reproduzir vídeo do YouTube" (padrão NÃO).

Ao ativar, o app verifica:

1. conexão com a Internet (rede local);
2. resposta do servidor de pesquisa (ping.php), com timeout de 5 s.

Durante a verificação o item mostra "VERIFICANDO..." e fica bloqueado. Se falhar, o modo não é ativado e aparece um aviso:

• "Sem conexão com a Internet. Não é possível ativar."
• "Sem resposta do servidor do YouTube. Verifique a conexão e tente novamente."

Desativar é sempre permitido, sem checagem.

6.2 Acesso à tela

Com o YouTube ativo:

• o modal de GÊNEROS ganha o item YOUTUBE (logo após TODOS);
• a tecla ALTERNAR YOUTUBE (padrão Y) alterna entre a tela do YouTube e a home.

6.3 Pesquisa

• A tela mostra YOUTUBE {termo pesquisado} e, abaixo, VÍDEOS DE ATÉ X MINUTOS.
• Botão PESQUISAR NO YOUTUBE (primeiro item do modal PESQUISAR) abre o campo de pesquisa, já preenchido com o último termo, cursor no fim.
• Resultados ordenados por relevância, até 50 vídeos por página, com filtro de duração: só entram vídeos com duração maior que 0 e até "Tempo máximo do vídeo (minutos)" (padrão 5, mínimo 2).
• O botão CARREGAR MAIS busca a próxima página e acrescenta os vídeos, sem recarregar a lista.
• Cada card mostra a miniatura, o título em caixa alta e DURAÇÃO: MM:SS.
• Ao mudar a pesquisa, o cursor vai para o primeiro vídeo.

6.4 Reprodução

• O vídeo do YouTube entra na fila como mídia do tipo vídeo, consumindo créditos por reprodução no YouTube (padrão 1).
• Segue o mesmo fluxo de vídeo: miniatura → tela cheia após o tempo configurado.
• Os controles multimídia do cabeçalho não aparecem para o YouTube.
• O ícone do YouTube aparece nas listas de espera.
• A capa (miniatura) do vídeo aparece no rodapé e no cabeçalho do vídeo.
• Sem Internet ou com o vídeo indisponível: aviso "Sem conexão com a Internet." e devolução do crédito no modo Pago.

6.5 Falhas de rede

Sem Internet ou sem resposta do servidor:

• na tela do YouTube: "Sem conexão com a Internet." ou "Sem resposta do servidor do YouTube. Tente novamente.";
• no CARREGAR MAIS: aviso pontual e a paginação é preservada, permitindo tentar de novo de onde parou.

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

7.1 Modos de operação

• Modo Pago (padrão de fábrica): cada mídia consome créditos.
• Modo Livre: nada é consumido; as teclas de crédito apenas avisam "Sistema no modo livre de créditos. Não é necessário inserir créditos." e o PIX fica indisponível.

A troca é feita em Configurações → CRÉDITOS → "Mudar para LIVRE/PAGO".

7.2 Inserir créditos

Cada pulso insere "Créditos por pulso" (padrão 2). O som de crédito pode ser ligado/desligado ("Tocar som ao inserir créditos", padrão SIM).

7.3 Custo por tipo de mídia

Configurações → CRÉDITOS → "Custo por faixa:"

Se o saldo não for suficiente:

• saldo zero → "Favor inserir créditos!" (fundo vermelho);
• saldo maior que zero → "Mídia requer N créditos." (fundo vermelho).

Mídia com defeito devolve exatamente o custo consumido.

7.4 Pagamento por PIX (créditos)

Pela tecla Q o modal PAGAMENTO PIX abre (somente com PIX ativo e fora do modo Livre).

1. Cada toque na tecla soma "Valor por crédito" ao valor e "Número créditos para inserir" aos créditos ("PRESSIONE NOVAMENTE PARA SOMAR.").
2. Após 3 s sem tecla, o QR Code é gerado.
3. O QR aparece num tamanho limitado (para caber junto com valor, créditos e contagem).
4. Contagem "EXPIRA EM NN SEGUNDOS" conforme "Tempo para pagamento (segundos)" (padrão 120).
5. A cada 5 s o app consulta o status do pagamento.
6. Aprovado: insere os créditos, registra a venda e mostra "PAGAMENTO APROVADO - N CRÉDITO(S) INSERIDO(S)".
7. Rejeitado: "OS DADOS FORAM REJEITADOS PELO SERVIDOR." e fecha.
8. Sem Internet durante a consulta: o modal não fecha nem perde o QR; mostra "SEM CONEXÃO - TENTANDO NOVAMENTE..." e segue tentando.

Pagamento aprovado com o app fechado: o app guarda o pagamento pendente e, ao abrir (ou a cada 5 minutos), confirma no servidor e credita/libera o registro automaticamente. Pagamentos já processados não são aplicados duas vezes.

7.5 Controle de vendas (teclas)

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

• Saldo: créditos na máquina;
• Créditos vendidos: total de pulsos já contabilizados;
• 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: confirma, grava um registro no relatório e zera os créditos vendidos (o saldo da máquina não muda);
• RELATÓRIO DE VENDAS: tabela com créditos, valor, comissão do bar, a receber, data e hora; permite LIMPAR RELATÓRIOS;
• EXPORTAR PARA PDF: gera o PDF e abre o gerenciador de arquivos do sistema para o usuário escolher onde salvar (o app não grava direto em pendrive).

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

7.6 Controle de vendas por PIX

Card Controle de Vendas por PIX, independente do controle por teclas:

• Créditos vendidos (PIX);
• Valor = créditos × valor do crédito ÷ créditos por pulso;
• Valor Creditado = valor × (100 − taxa do MP)/100;
• Valor a pagar para o estabelecimento (NN%) = valor creditado × comissão do bar / 100.

Botões ACERTAR PAGAMENTO (grava relatório e zera os vendidos PIX) e RELATÓRIO DE VENDAS (créditos, valor, taxa, comissão, a pagar, data, hora; com LIMPAR RELATÓRIOS).

7.7 Configurar o PIX

Botão Configurar pagamento PIX:

LIMPAR TOKEN apaga o token, exibe "vazio" e desativa o PIX.

No Modo Livre, o PIX não pode ser ativado: aparece a mensagem "O PIX não pode ser ativado no Modo Livre. Mude para o Modo Pago na aba Créditos."

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

8.1 O que é

O catálogo é o índice de gêneros, álbuns e faixas gerado a partir de uma pasta do aparelho (pendrive/HD). O app não varre tudo a cada abertura: ele usa o catálogo salvo no banco.

8.2 Configurar a pasta

Configurações → CATÁLOGO → Escolher pasta.

Abre o navegador de pastas do app (começa em /storage ou na pasta atual). A pasta escolhida é gravada como pasta raiz da mídia.

Observação: em aparelhos Android 10 o app usa o modo de armazenamento legado para conseguir listar pendrives. Em Android 11+ pode ser necessário conceder acesso a todos os arquivos.

8.3 Gerar catálogo

Botão Gerar catálogo:

1. apaga o catálogo anterior (antes de começar a varrer);
2. varre a pasta e mostra "Escaneando pastas..." com o nome da pasta atual e "Pastas escaneadas: N";
3. grava os álbuns em lote, mostrando "Gravando novo catálogo..." e "Álbuns salvos: N de TOTAL";
4. ao concluir, mostra "Catálogo gerado com sucesso!" e volta para a tela principal.

Atenção: gerar novamente descarta movimentações manuais de álbuns entre gêneros e qualquer ajuste feito pelo botão [+].

8.4 Limpar catálogo

Botão Limpar catálogo: apaga gêneros, álbuns e faixas do banco e mostra "Catálogo limpo". A pasta configurada é mantida.

8.5 Verificação na abertura

Ao abrir o app:

• se houver catálogo salvo no banco, a navegação é liberada na hora;
• se não houver catálogo e a pasta não existir, aparece "VERIFICANDO CATÁLOGO DE MÍDIAS" com contagem de até 30 s;
• após esse tempo, mostra "Catálogo de Mídias não encontrado!" e bloqueia os álbuns (o botão CONFIG continua acessível);
• a verificação continua em segundo plano (a cada 5 s): quando a pasta aparecer, a navegação é liberada sozinha;
• com catálogo salvo mas pasta raiz vazia (por exemplo, após limpar as preferências), o app redescobre a raiz sozinho a partir dos caminhos já gravados no catálogo.

8.6 Gêneros

Configurações → GÊNEROS → card Gêneros do catálogo.

Cada linha de gênero tem:

NOVO GÊNERO: cria um gênero só com o nome ("SALVAR") ou com uma pasta escolhida ("SALVAR E ESCANEAR", que adiciona os álbuns encontrados).

Mover álbuns ([+]):

• busca em todo o catálogo (mínimo 2 letras);
• marca/desmarca álbuns com OK (o marcador é um check desenhado);
• álbuns que já pertencem ao gênero entram já marcados;
• FECHAR aplica a movimentação e mostra "N ÁLBUM(S) MOVIDO(S) PARA ESTE GÊNERO".

Configuração de Inicialização (abaixo da lista):

• INICIAR O PROGRAMA NO GÊNERO: escolhe o gênero aberto ao iniciar (TODOS, YOUTUBE quando ativo, ou um gênero cadastrado);
• RETORNAR PARA O GÊNERO TODOS APÓS 30 SEGUNDOS (padrão NÃO): com SIM, depois de 30 s sem interação em uma tela de gênero ou do YouTube, o app volta para TODOS. Qualquer interação reinicia a contagem; modal aberto pausa a contagem.

8.7 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.
• YouTube: endereço iniciado por https://www.youtube.com/watch.
• Capas: imagens chamadas capa, cover ou folder na pasta do álbum.

Capítulo 9 — Teclas configuráveis e atalhos

9.1 Tela TECLADO

Configurações → TECLADO. Cada linha mostra a função, a tecla atual e o botão REMAPEAR.

• Ao remapear, o app captura a próxima tecla pressionada.
• Tecla já usada em outra função: mostra "Tecla já utilizada em \"...\"!" e não altera.
• O botão Cancelar interrompe a captura.

9.2 Funções e teclas padrão

As funções de navegação (setas/OK) não são remapeáveis.

9.3 Teclas fixas do aparelho

• BACK / ESC / VOLTAR: fecha o modal atual; sem modal, pede confirmação de saída.
• VOLUME_UP / VOLUME_DOWN do controle: ajustam o volume do app (±1%), igual às teclas J/H.

9.4 Volume

• Cada toque ajusta 1%.
• O valor fica entre 0 e o Volume máximo configurado.
• O modal VOLUME (NN%) aparece por 3 segundos e fica sempre no topo, inclusive sobre a Espera do Cantor, a Nota, o PIX e os créditos.
• Segurar a tecla repete o ajuste.
• O volume inicial é aplicado ao abrir o programa; voltar do segundo plano não reinicia o volume.
• O app espelha o volume no volume de mídia do sistema, para o player nativo e os vídeos ficarem no mesmo nível.

9.5 Atalhos especiais (easter eggs)

Os easter eggs exigem a opção "Apagar lista de mídias na tela principal" = SIM.

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

As abas são roláveis na horizontal. Ao focar o primeiro item de um módulo, a tela rola de volta ao topo, mostrando o título da seção.

Todos os textos da tela são exibidos em CAIXA ALTA; campos de texto são gravados em caixa alta (exceto a senha, que preserva maiúsculas/minúsculas).

Campos numéricos não aceitam confirmação vazia: mostram "INFORME UM VALOR." e mantêm o valor anterior. Campos de texto em branco continuam permitidos, salvo quando indicado.

10.1 CATÁLOGO

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

10.2 CRÉDITOS

Cartões, nesta ordem:

1. Créditos — modo do sistema (LIVRE/PAGO, exibido abaixo dos botões), Inserir Créditos Grátis, Zerar créditos, Mudar para LIVRE/PAGO.
2. Ajustes — valor do pulso, créditos por pulso, comissão do bar.
3. Controle de Vendas.
4. Controle de Vendas por PIX.
5. Custo por faixa: — karaokê, vídeo, YouTube, música.

10.3 GÊNEROS

• NOVO GÊNERO.
• Gêneros do catálogo (EDITAR, [+], Excluir, MOSTRAR).
• Configuração de Inicialização (gênero inicial, retorno para TODOS).

10.4 MÍDIAS

Mídia grátis:

• Tocar mídia grátis;
• A cada (minutos) — 0 = modo Média Player (4 s);
• Tocar até o final;
• Duração (segundos) — desabilitado com "Tocar até o final" = SIM;
• Interromper mídia grátis com qualquer tecla;
• Não tocar karaokê como grátis;
• Interromper a mídia grátis para tocar mídia do usuário imediatamente;
• Destacar álbum ao tocar mídia grátis.

Com "Tocar mídia grátis" = NÃO, todos os itens abaixo do switch ficam ocultos.

Comportamento / Lista de espera:

• Tempo para corrigir a mídia;
• Permitir remover da lista;
• Apagar lista de mídias na tela principal;
• Tempo para remover mídia;
• Botão Remover todas as mídias na fila, com a dica de que o atalho é segurar CORRIGIR 10 s no 2º álbum.

Vídeo:

• Aspect ratio (PADRÃO / 4:3 / 16:9);
• Vídeo tela cheia em (segundos);
• Usar o tempo real das mídias;
• Tentar com o player nativo do Android se o vídeo não abrir;
• Diagnóstico de vídeo (log detalhado).

Controle Multimídia:

• Usar controles multimídia.

10.5 KARAOKÊ

• Pontuação: exibir pontuação, pontuação mínima para nota.
• Modo karaokê: gênero alternar para karaokê (com a mensagem da tecla).
• Karaoke Numérico: ativar modo numérico, usar ENTER/OK para escolher. O botão de ativar fica desabilitado se não existir gênero de karaokê.
• Som: som de espera do cantor, fechar tela de espera automaticamente.
• Acesso ao catálogo de códigos e exportação em PDF.

10.6 YOUTUBE

• Reproduzir vídeo do YouTube (com verificação de Internet e servidor).
• Tempo máximo do vídeo (minutos) (padrão 5, mínimo 2).
• Texto informativo: "1 CRÉDITO EQUIVALE A UM VÍDEO DE (X) MINUTOS. OBRIGADO."

10.7 SISTEMA

Regras:

• Volume inicial nunca pode ser maior que o Volume máximo.
• Se o máximo for reduzido abaixo do inicial, o máximo é ajustado para igual ao inicial (com aviso).
• Todos os percentuais são limitados a 100; não há valores negativos.
• Modo noturno: dentro da janela, o volume máximo efetivo passa a ser o menor entre "Volume máximo" e o limite noturno. O app só reduz o volume sozinho; fora da janela volta a valer o máximo normal.
• Nivelamento de áudio: atua nas mídias (música, vídeo, YouTube), não nos efeitos. Perfis:

O player nativo (usado em vídeos que o player principal não abre) não passa pelo nivelador.

10.8 TECLADO

Ver Capítulo 9.

10.9 SOBRE

Card Registro / Licença (ver Capítulo 11) com:

• Nome registro (obrigatório para registrar; desabilitado quando já registrado);
• Versão, dispositivo, ponto, status, equipamento, Android ID, Install ID;
• Código de licença e data do registro (quando registrado);
• VALOR DO PROGRAMA (consultado no servidor; oculto quando registrado);
• REGISTRAR CÓPIA;
• RECUPERAR LICENÇA;
• Estado do envio do registro ao servidor.

Capítulo 11 — Licença, registro e versão de avaliação

11.1 Versão de avaliação

• Ao instalar, o programa funciona por 180 minutos de uso real.
• O tempo só conta com o app aberto: desligar a TV box, ir para o HOME ou deixar em segundo plano não consome a avaliação.
• Os minutos restantes aparecem no cabeçalho: "Avaliação Gratuita - Tempo Restante: HH:MM".
• Ao esgotar, o app mostra FIM DA VERSÃO DE AVALIAÇÃO e bloqueia o uso.

11.2 Registrar a cópia

1. Abra Configurações → SOBRE.
2. Preencha Nome registro (obrigatório).
3. Confira o VALOR DO PROGRAMA exibido (consultado no servidor).
4. Toque em REGISTRAR CÓPIA.
5. O app gera o QR Code do PIX do registro e mostra a contagem EXPIRA EM NN SEGUNDOS (90 s).
6. Pague pelo aplicativo do banco.
7. Ao aprovar, o app mostra "PAGAMENTO APROVADO - REGISTRO LIBERADO!" e grava a licença.

Sem Nome registro: "INFORME O NOME DE REGISTRO ANTES DE PAGAR." e nada acontece.

Sem valor/chave de pagamento: avisos pedindo para verificar a Internet ou aguardar a consulta.

11.3 Gravação no servidor

Após o pagamento aprovado, o app envia os dados do registro para o servidor (Android ID, dispositivo, Install ID, código de licença, valor, nome e id da compra).

• Sucesso: "REGISTRO GRAVADO NO SERVIDOR."
• Falha: "REGISTRO PENDENTE NO SERVIDOR. TENTARÁ NOVAMENTE A CADA 5 MINUTOS." — o app tenta de novo até conseguir, inclusive após reiniciar.

11.4 Recuperar licença

Se o aparelho já possui licença no servidor, a aba SOBRE avisa: "VOCÊ JÁ POSSUI UMA LICENÇA PARA ESTE DISPOSITIVO. CLIQUE EM RECUPERAR LICENÇA PARA ATIVAR O PROGRAMA."

Ao tocar em RECUPERAR LICENÇA e concluir, aparece "LICENÇA RECUPERADA COM SUCESSO." (uma única vez).

Depois de registrado, o app não consulta mais o valor do programa e esconde essa linha.

Capítulo 12 — Proteção de tela e tela "Tocando Agora"

12.1 Proteção de tela

Configurações → SISTEMA → card Proteção de tela.

• Ativar proteção de tela (padrão SIM).
• Tempo para entrar a proteção (minutos) — padrão 1 minuto.
• Seu texto (até 50 caracteres) — texto flutuante exibido na proteção; preserva maiúsculas/minúsculas como digitado.

Com a proteção desativada, os dois itens acima ficam ocultos.

Comportamento:

• entra após o tempo configurado sem interação e sem mídia tocando;
• não entra com a Espera do Cantor, a Nota do karaokê ou o PIX (créditos ou registro) abertos;
• sai com qualquer tecla ou toque;
• visual: fundo animado com partículas, logos em ping-pong (logo TKMusic e logo Estúdio Multimídia, com troca aleatória nas batidas de borda), textos centrais e o texto flutuante configurado, que também anda em ping-pong e troca de cor a cada batida;
• em modo demo de áudio: capa do álbum flutuando por cima (Capítulo 4).

12.2 Tela "Tocando Agora"

Com uma música tocando (não vídeo, não karaokê, não YouTube, não demo), na tela principal e sem modais, após 5 segundos sem interação abre a tela Tocando Agora, com:

• logo TKMusic e slogan;
• capa grande com borda amarela;
• bloco "TOCANDO AGORA" com álbum, música, barra de progresso e tempos;
• card PRÓXIMA MÚSICA (capa, álbum e título);
• rodapé com FILA: NN MÍDIAS e CRÉDITOS: NN (ou LIVRE).

Ela fecha com qualquer tecla (exceto volume e créditos) ou com um toque — e o toque que fecha não aciona o que está atrás (bloqueio de 0,6 s).

Liga/desliga em Configurações → SISTEMA → Exibir tela Tocando Agora (padrão SIM, aplicada somente a músicas).

Capítulo 13 — Robustez do player, correções automáticas e diagnóstico

13.1 Por que existem esses recursos

Arquivos antigos de pendrive costumam ter cabeçalhos inconsistentes e formatos que nem todo aparelho decodifica. O app foi preparado para tocar mesmo assim e, quando não for possível, avisar e devolver o crédito.

13.2 Tempo real das mídias

Opção: MÍDias → Vídeo → Usar o tempo real das mídias (padrão SIM).

• O app compara a duração informada pelo container com a duração lida pelo sistema (MediaMetadataRetriever).
• A correção só é aplicada quando a diferença é ≥ 3 s e ≥ 3 % — um arquivo correto nunca é alterado.
• Se o container diz mais que o real (ex.: AVI marcando 14:25 para um vídeo de 5:42), o app mostra o tempo real e encerra no fim de verdade.
• Se o container diz menos que o real, o fim continua sendo comandado pelo player (nada é cortado).
• Vale para todos os formatos, não só AVI.

13.3 Fallback para o player nativo

Opção: Tentar com o player nativo do Android se o vídeo não abrir (padrão SIM).

O player principal (Media3/ExoPlayer) é usado sempre. O player nativo (MediaPlayer do Android) entra quando:

1. o vídeo não gera trilha de vídeo;
2. o vídeo não fica pronto em 10 s;
3. ocorre erro de reprodução;
4. o vídeo encerra "sem reproduzir" (parado perto de 0 s, sem trilha de vídeo, dentro de 30 s).

Se o nativo também falhar, o app devolve o crédito e avisa.

Com o nativo ativo, o volume é espelhado no volume de mídia do sistema, porque nessa ROM (TV box Amlogic) o MediaPlayer ignora o volume próprio.

13.4 Retomada de posição

• Mídia do usuário: pausa ao sair e retoma na posição.
• Vídeos: ao retomar, o app reprepara o vídeo na posição salva, para a imagem voltar a andar (não fica congelada no último quadro).
• No player nativo, a posição é aplicada quando o arquivo fica pronto.
• A demo não salva posição e não retoma.

13.5 Diagnóstico de vídeo

Opção: Diagnóstico de vídeo (log detalhado) (padrão NÃO).

Quando ligado, grava um log com informações de carregamento, trilhas, decoders, tamanho de vídeo, primeiro quadro, frames perdidos, travamentos, erros e amostras a cada 2 s. Serve para diagnosticar arquivos problemáticos — não altera a reprodução.

13.6 Nivelamento de áudio

Ver Capítulo 10 (SISTEMA). Resumo: equaliza o volume entre as mídias em tempo real, com três intensidades, e não atua nos efeitos sonoros nem no player nativo.

13.7 Limitações conhecidas

• Vídeos MPEG-PS (.mpg) dependem do player nativo em aparelhos sem decoder MPEG-1.
• Arquivos com cabeçalho realmente contraditório podem exigir a correção de tempo real (13.2); a correção definitiva é regerar o arquivo na origem.
• O nivelamento não atua no player nativo.
• O CDN do YouTube pode bloquear redes de datacenter (funciona em redes residenciais/operadora).

Apêndice A — Tabela de mensagens do sistema

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

Apêndice C — Glossário