Mídia Faren - Guia Completo de Instalação (Pacote ZIP / GitHub)

Este repositório foi preparado para rodar localmente no Windows sem depender de Git.

Você pode:

baixar ZIP do projeto,
descompactar,
executar executar.bat.

Ilustrações do projeto

Áudio de exemplo incluído (para teste imediato)

Este pacote já inclui um áudio real de sessão para quem quiser validar o fluxo completo sem preparar arquivos próprios:

Arquivo: Guia HTML (áudio de exemplo)
Fallback local do pacote: docs/index.html#audio-exemplo
Contexto: one-shot no cenário de The Witcher
Mesa: 3 jogadores
Sistema: DND 5e 2024

Use este arquivo para:

testar transcrição com marcação de tempo e falantes,
validar glossário e qualidade dos modelos,
gerar material para o passo de resumo no NotebookLM.

1) O que este pacote contém

app.py: servidor Flask da aplicação.
executar.bat: instalador/validador automático + inicialização.
mfaren/: backend principal (download, conversão, transcrição, filas, jobs).
static/ e templates/: frontend.
instalacao_de_resumo_de_sessao.html: guia visual com fluxo de resumo no NotebookLM.
MODELOS_DOWNLOAD.txt: links dos modelos + onde colocar cada arquivo.
SMOKE_TEST_10_MIN.md: checklist rápido para validar instalação em ~10 minutos.
requirements.manual.txt: referência de dependências para instalação manual.
tests/: testes automatizados (opcional para quem só vai usar).

Estrutura de runtime incluída vazia:

data/uploads/
data/transcribe_cache/
downloads/
logs/

2) Requisitos obrigatórios

Instale estes itens antes da primeira execução:

Python 3.11+ (3.13 também funciona)
- https://www.python.org/downloads/windows/
FFmpeg (build "full shared")
- https://www.gyan.dev/ffmpeg/builds/
Microsoft Visual C++ Redistributable (x64)
- https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist

Recomendado para melhor desempenho:

Driver NVIDIA atualizado (se usar GPU)
- https://www.nvidia.com/Download/index.aspx
CUDA Toolkit (opcional para validação manual da toolchain)
- https://developer.nvidia.com/cuda-downloads

Observações:

Internet é necessária na primeira execução (download de pacotes Python/modelos).
Reserve espaço livre em disco (ideal: 15 GB+ para operação confortável).

3) Instalação do zero (sem Git)

Baixe o ZIP do projeto.
Descompacte em uma pasta local (ex.: C:\midia-faren).
Abra a pasta e execute executar.bat.
Aguarde os passos de instalação/validação.
O navegador abrirá em: http://127.0.0.1:5000/.

Se o navegador não abrir automático, acesse manualmente a URL acima.

3.1) Fluxo GitHub (clonar, commitar e publicar)

Repositório oficial:

https://github.com/FarenRavirar/midia-faren/

Clonar o repositório

git clone https://github.com/FarenRavirar/midia-faren.git
cd midia-faren

Se você quiser trabalhar só no pacote de instalação:

cd instalacao\midia-faren

Commits e push (fluxo básico)

git status
git add .
git commit -m "chore: atualizacao da documentacao e instalacao"
git push origin main

Baixar ZIP sem Git

No GitHub, clique em:

Code -> Download ZIP

Publicar ZIP em Releases (recomendado)

Criar tag e enviar:

git tag -a v1.0.0 -m "release v1.0.0"
git push origin v1.0.0

No GitHub:
- Releases -> Draft a new release
- selecione a tag v1.0.0
- escreva título e notas
- anexe o ZIP do pacote (instalacao/midia-faren).
Para gerar ZIP localmente (PowerShell):

Compress-Archive -Path ".\instalacao\midia-faren\*" -DestinationPath ".\instalacao\midia-faren-v1.0.0.zip" -Force

4) O que o `executar.bat` faz

Cria/reutiliza o venv local: .venv_cuda
Instala/atualiza pacotes base:
- flask, requests, yt-dlp
Instala stack IA fixada (estável para este projeto):
- torch==2.8.0+cu128
- torchaudio==2.8.0+cu128
- faster-whisper==1.2.1
- whisperx==3.8.0
- ctranslate2==4.7.1
Remove torchcodec por instabilidade no Windows nesse stack.
Valida imports e sobe o Flask.

Flags úteis do `executar.bat`

--check: só valida ambiente, sem reinstalar.
--setup-env: força reinstalação das dependências.
--recreate-venv: recria o venv do zero.
--ffmpeg-path-on: injeta FFmpeg local no PATH da sessão.
--ffmpeg-path-auto: injeta só se não houver FFmpeg no PATH.
--ffmpeg-path-off: não injeta PATH (padrão).

Exemplo:

executar.bat --setup-env --recreate-venv --ffmpeg-path-auto

5) FFmpeg: como garantir detecção

A aplicação procura FFmpeg nesta ordem:

tools\ffmpeg\bin\ffmpeg.exe
C:\tools\ffmpeg\ffmpeg-7.1.1-full_build-shared\bin\ffmpeg.exe
ffmpeg no PATH

Para não ter erro:

opção A: instalar FFmpeg e adicionar no PATH;
opção B: colocar binário em tools\ffmpeg\bin dentro do projeto;
opção C: usar executar.bat --ffmpeg-path-auto.

Teste rápido:

ffmpeg -version

6) GPU vs CPU (comportamento real)

O projeto roda com e sem CUDA.
Com CUDA disponível: transcrição muito mais rápida.
Sem CUDA: funciona em modo CPU (mais lento).

Verificação rápida:

.venv_cuda\Scripts\python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"

7) Backends de transcrição

Disponíveis na UI:

whisper_cpp
faster_whisper (recomendado padrão)
whisperx

Recursos do pipeline:

chunking com overlap
checkpoint por chunk
retomada/reprocessamento de chunk
guardrails anti-loop
glossário/contexto persistente

8) Modelos (qualidade x velocidade)

tiny: muito rápido, qualidade baixa.
base: rápido, qualidade baixa/média.
small: equilíbrio para teste.
medium: qualidade boa com prazo.
large-v3: melhor qualidade, mais lento.
distil-large-v3: quase qualidade do large-v3 com mais velocidade.

Links oficiais dos modelos:

Arquivo dedicado de modelos (links + destino + checklist):

MODELOS_DOWNLOAD.txt

Onde cada modelo fica

faster_whisper / whisperx:
- não precisa copiar manualmente;
- baixa automaticamente na primeira execução;
- cache padrão em %USERPROFILE%\.cache\huggingface\hub.
whisper_cpp:
- baixar arquivos ggml-*.bin manualmente;
- copiar para transcriber\models\;
- nomes dos arquivos devem permanecer exatamente iguais.

9) Importante sobre `whisper_cpp` neste pacote GitHub

Para manter o repositório leve e compatível com limites do GitHub:

binários grandes e modelos .bin do whisper_cpp não estão incluídos neste pacote.

Impacto:

faster_whisper e whisperx continuam prontos para uso;
whisper_cpp pode exigir baixar binários/modelos separadamente se você quiser usar esse backend.

Se não quiser setup adicional, use:

backend faster_whisper ou whisperx.

Se quiser usar whisper_cpp, siga exatamente:

Abra MODELOS_DOWNLOAD.txt.
Baixe os modelos ggml-*.bin.
Copie os arquivos para transcriber\models\.
Na UI, selecione backend whisper_cpp e o modelo correspondente.

10) Fluxo recomendado: Craig -> Transcrição estruturada -> NotebookLM

Regra principal

Para resumo de sessão no NotebookLM, a fonte principal deve ser a transcrição em texto (TXT/SRT) com:

timestamps corretos;
separação por falantes/personagens (quando aplicável);
ordem cronológica preservada.

O arquivo de áudio mixado (M4A) pode ser usado como fonte complementar, mas não substitui a transcrição estruturada para esse objetivo.

Pipeline recomendado no projeto

Gere a transcrição completa no módulo Transcrição.
Confirme saída em .txt e .srt (com marcação temporal e falantes).
Revise trecho final para evitar cauda repetitiva/loop.
(Opcional) Gere M4A no módulo Conversor > Mixagem.
Acesse NotebookLM: https://notebooklm.google.com/
Crie notebook e envie primeiro o TXT/SRT.
Use o prompt de conto para gerar o resumo da sessão.

Guia visual e prompt:

instalacao_de_resumo_de_sessao.html

10.1) Passo a passo no NotebookLM

Acesse https://notebooklm.google.com/
Crie um novo notebook.
Adicione a transcrição (.txt ou .srt) como fonte principal.
Aguarde indexação da fonte.
(Opcional) adicione o M4A como fonte complementar.
Cole o prompt (seção 10.2) no chat do NotebookLM.
Idioma: Português (Brasil).

10.2) Prompt pronto (modelo genérico)

Gere um resumo da sessão de RPG baseada na transcrição "[nome da transcrição]" no cenário "[nome do cenário]".

Quero um texto em formato de conto narrado em primeira pessoa do plural ("nós"), como se um dos jogadores estivesse contando para amigos o que aconteceu.

Regras do resultado:
1) Não faça análise técnica da mesa.
2) Não foque em elogiar ou exaltar pessoas específicas.
3) Conte os acontecimentos da sessão com narrativa fluida e empolgante.

Estrutura esperada:
1) Abertura da sessão:
   - como nós chegamos;
   - contexto inicial do local;
   - quem eram os personagens presentes.

2) Desenvolvimento:
   - conflitos e tensões;
   - estratégias que nós tentamos;
   - decisões e indecisões;
   - reviravoltas, surpresas e consequências;
   - acontecimentos importantes em ordem clara.

3) Fechamento:
   - estado final do grupo;
   - perguntas em aberto;
   - gancho para continuação.

Diretriz de fidelidade:
- Use os nomes e fatos das fontes enviadas (transcrição com timestamps/falantes + notas de contexto), sem inventar fatos fora do material.
- Se algo estiver ambíguo, indique como possibilidade em vez de afirmar com certeza.

Final obrigatório (adapte ao contexto):
"Vamos ver aonde essa trama vai nos levar na próxima sessão."

10.3) Bloco de notas de contexto (para colar no NotebookLM)

[NOTAS DE CONTEXTO DA SESSAO]

Nome do audio: [nome do audio]
Nome do cenario: [nome do cenario]
Sistema: [sistema de RPG]
Resumo do contexto inicial: [contexto inicial da sessao]

Personagens de jogadores:
- Jogador: [nome do jogador 1]
  Personagem: [nome do personagem 1]
  Conceito: [raca/classe/profissao]
  Vinculo ou origem: [faccao/cidade/clan/grupo]
  Motivacao atual: [objetivo na sessao]

- Jogador: [nome do jogador 2]
  Personagem: [nome do personagem 2]
  Conceito: [raca/classe/profissao]
  Vinculo ou origem: [faccao/cidade/clan/grupo]
  Motivacao atual: [objetivo na sessao]

NPCs importantes:
- NPC: [nome do NPC 1]
  Papel na historia: [funcao]
  Relacao com o grupo: [como influencia o grupo]

- NPC: [nome do NPC 2]
  Papel na historia: [funcao]
  Relacao com o grupo: [como influencia o grupo]

Termos e nomes que nao devem ser corrigidos:
- [termo 1]
- [termo 2]
- [local 1]

Observacoes de pronuncia ou escrita:
- [nome dificil 1] -> [forma correta]
- [nome dificil 2] -> [forma correta]

11) Verificações pós-instalação

.venv_cuda\Scripts\python -c "import flask,requests,yt_dlp; print('core_ok')"
.venv_cuda\Scripts\python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.version.cuda)"
.venv_cuda\Scripts\python -c "import importlib.metadata as md; print(md.version('whisperx'), md.version('faster-whisper'), md.version('ctranslate2'))"

12) Troubleshooting rápido

`ffmpeg` não encontrado

Reinstale FFmpeg full shared.
Valide ffmpeg -version.
Use executar.bat --ffmpeg-path-auto.

Erro de dependência Python

Rode:

executar.bat --setup-env --recreate-venv

Transcrição lenta

Use modelo menor (small/medium).
Use backend faster_whisper.
Verifique se CUDA está ativo.

Loop/repetição no final

Ajuste chunk/overlap.
Revise glossário e contexto.
Use reprocessamento de chunk.

13) Publicação no GitHub

Esta pasta já está preparada para publicação:

.gitignore configurado para ignorar dados locais/caches.
sem caminhos pessoais hardcoded.
sem venv embutido.
sem binários gigantes de whisper_cpp.

14) Smoke test de 10 minutos

Use o checklist completo em:

SMOKE_TEST_10_MIN.md

Resumo rápido (aprovação):

App sobe e UI abre.
Conversão curta termina com sucesso.
Transcrição curta gera .txt + .srt.
Cancelamento funciona.
Sem erro crítico persistente no fim de logs/app.log.

15) Créditos

Desenvolvido por Paulo "Faren" Lima - Artifício RPG

https://artificiorpg.com/

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
data		data
docs		docs
downloads		downloads
logs		logs
mfaren		mfaren
static		static
templates		templates
tests		tests
transcriber		transcriber
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
MIGRATION_TRANSCRIBE.md		MIGRATION_TRANSCRIBE.md
MODELOS_DOWNLOAD.txt		MODELOS_DOWNLOAD.txt
PROMPT_NOVO_CHAT.md		PROMPT_NOVO_CHAT.md
README.md		README.md
SMOKE_TEST_10_MIN.md		SMOKE_TEST_10_MIN.md
TODO.md		TODO.md
app.py		app.py
executar.bat		executar.bat
instalacao_de_resumo_de_sessao.html		instalacao_de_resumo_de_sessao.html
requirements.manual.txt		requirements.manual.txt

Folders and files

Latest commit

History

Repository files navigation

Mídia Faren - Guia Completo de Instalação (Pacote ZIP / GitHub)

Ilustrações do projeto

Áudio de exemplo incluído (para teste imediato)

1) O que este pacote contém

2) Requisitos obrigatórios

3) Instalação do zero (sem Git)

3.1) Fluxo GitHub (clonar, commitar e publicar)

Clonar o repositório

Commits e push (fluxo básico)

Baixar ZIP sem Git

Publicar ZIP em Releases (recomendado)

4) O que o executar.bat faz

Flags úteis do executar.bat

5) FFmpeg: como garantir detecção

6) GPU vs CPU (comportamento real)

7) Backends de transcrição

8) Modelos (qualidade x velocidade)

Onde cada modelo fica

9) Importante sobre whisper_cpp neste pacote GitHub

10) Fluxo recomendado: Craig -> Transcrição estruturada -> NotebookLM

Regra principal

Pipeline recomendado no projeto

10.1) Passo a passo no NotebookLM

10.2) Prompt pronto (modelo genérico)

10.3) Bloco de notas de contexto (para colar no NotebookLM)

11) Verificações pós-instalação

12) Troubleshooting rápido

ffmpeg não encontrado

Erro de dependência Python

Transcrição lenta

Loop/repetição no final

13) Publicação no GitHub

14) Smoke test de 10 minutos

15) Créditos

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

4) O que o `executar.bat` faz

Flags úteis do `executar.bat`

9) Importante sobre `whisper_cpp` neste pacote GitHub

`ffmpeg` não encontrado

Packages