# Guia do Utilizador do Omni Describer

Dando voz ao mundo visual com IA.

Tudo começou com o meu amor pelo cinema. Quando percebi quantos detalhes nas minhas cenas favoritas se perdiam sem uma boa descrição áudio, surgiu uma ideia: "Bem, não poderia a IA facilitar isto para nós?" Sonhei com uma ferramenta que não só gerasse descrições, mas que também desse controlo total ao utilizador. Após meses de trabalho intenso, inúmeros testes e a superação de muitos obstáculos técnicos, desenvolvi o Omni Describer como o produto desse sonho.

## Índice

- O que significa o nome?
- Requisitos do Sistema
- Primeiros Passos: Configurar as Chaves API
- Início Rápido: Gerar a Primeira Descrição
- Funcionalidades Principais
  - O Leitor de Vídeo Descrito
  - Editar Descrições: O Poder de Refinar
  - Gerir Presets de Prompt
  - Perguntar Mais Sobre a Cena
  - Explorador de Cena
  - Exportar o Seu Trabalho
- Um Mergulho Profundo nas Configurações
- Dicas e Truques para os Melhores Resultados
- Perguntas Frequentes (FAQ)
- Atalhos de Teclado
- Agradecimentos, Contactos e Colaboradores

## O que significa o nome?

O "Omni" no nome vem do latim, significando "tudo" ou "todas as coisas". Escolhi este nome porque não queria que a ferramenta servisse apenas para um propósito. Sim, o Omni Describer visa principalmente tornar os media acessíveis a pessoas cegas e com deficiência visual, criando descrições áudio. Contudo, o seu propósito não se limita a isso.

É também uma ferramenta de exploração. Um crítico de cinema, um estudante, um artista, ou qualquer pessoa curiosa sobre detalhes visuais pode usar funcionalidades como o "Explorador de Cena" ou o "Perguntar Mais" para mergulhar nas camadas de um vídeo como nunca antes. O Omni Describer é uma janela para ver o mundo através dos "olhos" da IA e compreendê-lo de forma diferente. Em suma, é "um descritor para tudo, para todos".

## Requisitos do Sistema

Para obter o melhor desempenho do Omni Describer, recomendo cumprir os seguintes requisitos mínimos de sistema:

- Sistema Operativo: Windows 10 ou superior (64 bits).
- Memória (RAM): Pelo menos 4 GB de RAM.
- Armazenamento: Pelo menos 500 MB de espaço livre para a aplicação e ficheiros temporários.
- Ligação à Internet: É necessária uma ligação ativa à internet para conectar aos serviços de IA (Google Gemini, OpenAI) e descarregar vídeos.
- Leitor de Ecrã: Para acessibilidade total, recomenda-se um leitor de ecrã como JAWS, NVDA ou Windows Narrator.

## Primeiros Passos: Configurar as Chaves API

O Omni Describer usa serviços de IA baseados na cloud para analisar e gerar descrições áudio. Por isso, precisa de introduzir as suas próprias chaves API antes de começar.

1. Abrir Configurações: Vá ao menu Ficheiro e selecione Configurações... (ou pressione Ctrl + ,).
2. Separador Configurações de IA:
   - Chave API Gemini: Esta é obrigatória para análise de vídeo. Cole a sua chave no campo "Chave API Gemini:". Pode obter uma chave gratuita em Google AI Studio.
   - Chave API OpenAI (para TTS): Necessária para conversão de texto em fala de alta qualidade. Cole a sua chave neste campo. Pode usar as vozes incorporadas do Windows sem esta chave, mas recomenda-se a OpenAI para melhores resultados. Pode obter uma chave na Plataforma OpenAI.
3. Guardar: Clique em Aplicar ou OK para guardar as configurações. Está pronto a usar!

Armazenamento Seguro: As suas chaves API são encriptadas e armazenadas com segurança no seu computador, no ficheiro de configurações da aplicação. Nunca são enviadas para outro local, exceto para conectar diretamente aos respetivos serviços de IA.

## Início Rápido: Gerar a Primeira Descrição

Vamos começar! Basta seguir estes passos simples:

1. Escolher um Vídeo: Clique num botão como "Ficheiro de Vídeo Local" na janela principal ou selecione a fonte do vídeo no menu Ficheiro.
2. Selecionar um Prompt (Opcional): O menu suspenso lista instruções pré-definidas que orientam a IA. Para o primeiro teste, deixar em "(Nenhum Preset Selecionado)" é uma boa escolha.
3. Iniciar o Processamento: A aplicação começará a analisar o vídeo. Pode acompanhar o progresso no "Registo de Estado" na parte inferior da janela. Isto pode levar alguns minutos, dependendo da duração do vídeo.

Quando o processo terminar, o Leitor de Vídeo Descrito abrir-se-á automaticamente, e poderá começar a desfrutar do seu vídeo descrito!

## Funcionalidades Principais

### O Leitor de Vídeo Descrito

Este é o seu cinema pessoal descrito. À medida que o vídeo avança, o seu leitor de ecrã instalado (como JAWS ou NVDA) irá ler as descrições áudio geradas nos momentos certos.

- Controlo de Reprodução: Use os botões de Reproduzir/Pausar, Retroceder/Avançar ou o cursor para navegar no vídeo.
- Área de Descrição Atual: Pode seguir o texto da descrição ativa nesta área.
- Editar e Refinar: Clique no botão "Editar Descrições..." para abrir um editor poderoso com controlo total sobre o seu projeto.
- Uso de Tokens da IA: Esta área mostra quantos "tokens" da IA foram usados, ajudando a controlar o uso da API.

### Editar Descrições: O Poder de Refinar

A IA fornece um ótimo ponto de partida, mas a qualidade real vem do refinamento. O botão "Editar Descrições..." no leitor abre um editor poderoso que lhe dá controlo total sobre cada aspecto do seu projeto.

- Selecionar e Modificar: Escolha qualquer descrição da lista suspensa no topo para carregar os seus detalhes no editor.
- Ajustar Marcas Temporais: Edite diretamente os campos `Hora de Início` e `Hora de Fim`. Ao mudar a hora de início, a hora de fim ajusta-se automaticamente para manter a duração da descrição. Todos os tempos são validados para garantir que estão dentro do vídeo.
- Reescrever Texto: Edite livremente o texto da descrição na caixa principal para melhorar a clareza, adicionar detalhes ou corrigir erros.
- Adicionar Novas Descrições: Clique em "Adicionar Novo..." para abrir um diálogo simples onde pode criar uma nova descrição do zero, definindo tempo e texto.
- Eliminar Descrições: Selecione uma descrição e clique em "Eliminar" para removê-la permanentemente.

Guarde o Seu Trabalho: As alterações feitas no editor (adicionar, eliminar, modificar) são aplicadas instantaneamente à sessão atual. Quando terminar, clique em "Fechar" para voltar ao leitor. A lista atualizada será usada na reprodução e nas exportações seguintes.

### Gerir Presets de Prompt

Os prompts são instruções poderosas que determinam no que a IA deve focar. Ao mudar o prompt, pode obter descrições em estilos muito diferentes.

- Selecionar um Preset: Antes de processar um vídeo, escolha um preset no menu suspenso na janela principal.
- Gerir Presets: Vá a Ficheiro -> Gerir Presets de Prompt.... Aqui pode Adicionar, Editar ou Eliminar os seus próprios prompts personalizados. Ideal para guardar instruções usadas frequentemente.
- Específico por Idioma: Os seus presets são guardados separadamente para cada idioma que selecionar nas Configurações.

### Perguntar Mais Sobre a Cena

Já quis saber o que uma personagem está a segurar ou o que diz uma placa ao fundo? Esta funcionalidade deixa-o perguntar qualquer coisa sobre a cena.

1. Pausa o vídeo no momento que tem interesse.
2. Clique no botão Perguntar Mais....
3. Escreva a sua pergunta no campo "A Sua Nova Pergunta:" (ex.: "De que cor é o chapéu da mulher?" ou "O que está escrito na parede?").
4. Selecione quantos segundos de vídeo a IA deve analisar à volta do tempo atual.
5. Clique em "Enviar Pergunta". A resposta da IA aparecerá na área "Histórico da Conversa".

### Explorador de Cena

O Explorador de Cena é uma forma interativa de compreender o layout espacial de uma cena. Coloca-o numa sala virtual que pode navegar com o teclado.

1. Pausa o vídeo numa cena que quer explorar em detalhe.
2. Clique no botão Explorar Cena..., depois em "Analisar Cena".

Está agora no Explorador de Cena. Use o teclado para explorar:

- Teclas de Seta: Mova a sua posição virtual numa grelha.
- D: Dá uma descrição detalhada da disposição geral da cena.
- L: Anuncia uma lista de todos os objetos na cena.
- Shift + L: Alterna para "Modo Saltar" para selecionar um objeto e ir diretamente até ele.
- Enter: Obtenha uma descrição detalhada do objeto mais próximo.
- Escape: Fecha o Explorador de Cena.

### Exportar o Seu Trabalho

Quando estiver satisfeito com as suas descrições, pode exportá-las a partir da Janela do Leitor em diferentes formatos:

- Exportar para .TXT: Um ficheiro de texto simples com marcas de tempo.
- Exportar para .SRT: Um ficheiro de legendas padrão que pode usar em leitores de vídeo como o VLC.
- Exportar Áudio (MP3): Esta é talvez a funcionalidade mais empolgante. Vocaliza as suas descrições com a voz que selecionou nas Definições (SAPI5 ou OpenAI), mistura-a com o áudio original do vídeo e baixa automaticamente o som de fundo durante as descrições para criar um ficheiro MP3 que pode ouvir em qualquer lugar.

## Um Mergulho Profundo nas Configurações

A janela Configurações (Ctrl + ,) oferece controlo detalhado sobre o comportamento da aplicação.

### Separador Geral

- Permitir que descrições interrompam a fala atual: Se selecionado, uma nova descrição começará a ser falada imediatamente, mesmo que a anterior ainda não tenha terminado. Desmarque para deixar cada descrição terminar antes da próxima começar. Útil para cenas muito rápidas.

### Separador Configurações de IA

- Taxa de Frames para Análise IA: Determina quantos frames por segundo do vídeo são enviados para a IA. Um valor baixo (ex.: 5 FPS) pode reduzir custos da API e evitar limites de processamento, mas pode fazer a IA perder ações muito rápidas.
- Ativar Divisão de Vídeo: Para vídeos longos (mais de 10-15 minutos), a IA pode ficar sem capacidade de processamento. Esta funcionalidade divide automaticamente o vídeo em partes menores, analisa-as sequencialmente e junta os resultados. Altamente recomendada para conteúdos longos.
- Desativar Filtros de Segurança (Usar com cautela): Esta opção pode permitir que a IA processe conteúdos que normalmente marcaria como sensíveis. Contudo, isto não é uma sobreposição absoluta. A saída está sempre sujeita às políticas de segurança do fornecedor de IA. Lembre-se que é responsável pelo uso desta funcionalidade.

### Separador Saída de Áudio

- Mecanismo Texto-para-Fala:
  - SAPI5 (Incorporado no Windows): Usa vozes que vêm com o Windows ou que tenha instalado. Não requer chave API adicional. A app pode usar vozes modernas 64-bit e vozes antigas 32-bit. Se tiver vozes antigas favoritas de sistemas anteriores, selecionando "SAPI5 (32-bit Voices)" poderá usá-las.
  - OpenAI TTS (Alta Qualidade): Produz vozes mais naturais e fluídas. Usar esta opção requer conta OpenAI paga e chave API. Pode criar e gerir presets de voz personalizados para OpenAI.

## Dicas e Truques para os Melhores Resultados

Criar boas descrições áudio é uma arte. Embora a IA seja uma assistente eficaz, obterá melhores resultados quando a orientar corretamente.

### O Poder dos Prompts: As Notas do Seu Diretor

A aplicação tem um conjunto de regras fundamentais que ensina à IA (como não falar sobre diálogos). Pense na área Preset de Prompt na tela principal como o local onde fornece as suas notas de diretor para aquele vídeo específico. Uma boa nota ajuda a IA a focar num estilo ou detalhe particular.
Dica: O Prompt "Focar em Nomes"
Num vídeo com muitos personagens, pode criar um prompt personalizado para priorizar o reconhecimento de nomes: `A sua prioridade máxima neste vídeo é identificar e usar os nomes corretos das personagens assim que forem mencionados.`
Dica: O Prompt "Descrever a Atmosfera"
Para filmes visualmente ricos, guie a IA para focar no ambiente: `Concentre-se em descrever o cenário, a atmosfera e os detalhes ambientais. Mencione a iluminação, cores e o humor geral da cena.`

#### O Que Evitar nos Prompts

Evite instruções que contradigam os princípios fundamentais da IA (descrever apenas o visual, não falar sobre diálogos). Dar uma instrução errada pode causar resultados pobres.

- Prompt Mau: `"Diz-me tudo o que acontece."` É demasiado vago e pode levar a descrições de detalhes irrelevantes.
- Prompt Mau: `"Diz-me o que as personagens estão a dizer."` Isto violará a regra de "apenas visual".

Em suma: Use os prompts para orientar o foco da IA, não para alterar as regras fundamentais de uma boa descrição áudio.

## Perguntas Frequentes (FAQ)

P: As minhas chaves API não funcionam. O que devo fazer?
R: Primeiro, verifique se copiou a chave completa corretamente. Para a OpenAI, certifique-se de que tem um método de pagamento configurado, pois o serviço TTS não é gratuito. Para Gemini, verifique se a API está ativada no seu projeto Google Cloud.

P: O processo falhou com um erro "MAX_TOKENS". O que significa?
R: Significa que o seu vídeo é demasiado longo ou complexo para a IA processar numa única passagem. É um limite de capacidade, não um erro de conteúdo. A melhor solução é ir a Configurações -> Configurações de IA e ativar "Divisão de Vídeo". Isso dividirá o vídeo em partes menores para a IA.

P: A IA não gerou descrições devido a "Filtros de Segurança". O que posso fazer?
R: Este é um problema conhecido em que o sistema de segurança da IA pode ser demasiado cauteloso. Tem algumas opções: 1) Vá a Configurações -> Configurações de IA e ative "Desativar Filtros de Segurança" (muitas vezes ajuda). 2) Se não funcionar, tente reduzir a "Taxa de Frames para Análise IA". 3) Em último caso, pode usar a configuração "Substituição do Modelo Gemini" e introduzir `gemini-2.5-pro`. Este modelo é mais poderoso, pode lidar melhor com conteúdos sensíveis, mas é mais lento e pode ser mais caro se estiver numa API paga.

P: Algumas das minhas vozes antigas desapareceram da lista SAPI5. Para onde foram?
R: Os sistemas modernos Windows são 64-bit, mas muitas vozes clássicas e queridas eram 32-bit. Em Configurações, no separador "Saída de Áudio", verá opções separadas para "SAPI5 (64-bit)" e "SAPI5 (32-bit)". Para aceder às vozes antigas, basta escolher o motor 32-bit.

P: Porque é que a geração de descrições demora tanto?
R: O tempo depende da duração do vídeo, da sua velocidade de internet (para o upload para a IA), da taxa de frames selecionada e da carga atual dos serviços de IA. Usar "Divisão de Vídeo" é muito recomendado para vídeos longos.

## Atalhos de Teclado

- Ctrl + O: Abrir Vídeo Local
- Ctrl + U: Abrir a partir de URL Direto
- Ctrl + Y: Abrir a partir do YouTube
- Ctrl + ,: Abrir Configurações
- F1: Ver Ajuda

## Agradecimentos, Contactos e Colaboradores

Muito obrigado por usar o Omni Describer! Esta aplicação reflete o meu desejo de tornar os media visuais mais acessíveis e agradáveis para todos. Ter utilizadores como você a usar esta ferramenta e a fornecer feedback é a maior motivação para continuar a desenvolvê-la.

### Feedback e Suporte

Tem alguma pergunta, um relatório de erro ou uma ideia para uma nova funcionalidade? Gostaria muito de ouvir! A melhor forma de me contactar é por email. O seu feedback é inestimável para tornar o Omni Describer ainda melhor.

- Email: info@audioses.com
- Website: audioses.com