vstoos/vlog-film

Filme de vlog

Converta uma pasta com as gravações do usuário em um filme finalizado para o YouTube e, em seguida, itere com base nas anotações do usuário até que ele fique satisfeito. O pipeline foi construído em "Despedida do Yaris" (24 min, fala em ucraniano, iPhone + Sony dash-cam); references/example_yaris.py é o arquivo de projeto completo desse filme, o melhor guia de como é uma edição finalizada.

Antes de começar

• Configuração. <skill>/config.json contém os caminhos da máquina (ffmpeg, melt, Python com WhisperX, modelo de placas, pasta de músicas, codificador, idioma da fala). Se estiver faltando, ou se um script falhar por falta de uma ferramenta, execute python <skill>/setup/setup.py (apenas verificação) e mostre ao usuário o que está faltando; com a aprovação dele, execute python <skill>/setup/setup.py --install. Execute cada script abaixo com o Python do config.json ("python"), pois é onde WhisperX e torch estão instalados.
• O usuário. Se <skill>/user.md existir, leia-o: ele diz quem é o usuário, em qual idioma responder e suas preferências permanentes. Sem ele: responda no idioma do usuário, mantenha as respostas curtas, nomeie os tempos do filme como mm:ss para qualquer coisa que ele deva olhar.
• Nos comandos abaixo, $K é <skill>/scripts e python é o Python configurado.

Estrutura do projeto

As gravações permanecem onde o usuário as colocou; o mp4 final, a descrição do YouTube, a miniatura e as legendas também vão para lá, pois é onde o usuário procura. Os arquivos de trabalho vão para uma pasta de projeto (por exemplo, C:/Dados/<nome>-video/):

<nome>-video/
  project.py        caminhos, EDL, HOOK, música, enquadramento, make_stills()   (copiar references/project_template.py)
  transcripts/      <clip>.json de transcribe_all.py
  film/             inserções renderizadas, <clip>_blur.mov, <nome>.mlt, <nome>.mp4
  film_check/       folhas de contato, wavs de teste, quadros de verificação (rascunho)
  edit_notes.md     as notas de revisão do usuário e o que foi feito sobre cada uma
  subs/, thumbnail/, route/

Fluxo de trabalho

1. Inventário

1. python $K/scan_meta.py <footage> film_check/meta.json: tempo, duração, GPS de cada arquivo. Ordenados por tempo, esta é a ordem da história.
2. Olhe antes de decidir: python $K/contact_sheet.py <out.png> 6 <clips...> para clipes, uma folha lado a lado para fotos; visualize as imagens você mesmo. Anote clipes em modo retrato (rotação -90/90), clipes que mostram placas de veículos, arquivos da dash-cam, gravações de tela. Eventos da Tesla dash-cam / Sentry das datas da viagem: references/teslacam.md (encontrando o incidente, cor via teslacam_grade.py).
3. python $K/transcribe_all.py <footage> transcripts: transcrição com temporização por palavra do WhisperX de cada clipe com fala (retomável, idioma da configuração). Leia todos; eles são a matéria-prima da história.

2. História e EDL

Proponha a estrutura ao usuário em algumas linhas antes de construir: o teaser, as partes, quais fotos, mapas ou imagens estáticas ilustram qual fala. Forma típica:

• Teaser (HOOK): 4 a 6 frases curtas e fortes de toda a viagem, cada uma um pensamento completo.
• Cartão de título sobre a filmagem da estrada, depois blocos de fala separados por inserções de estrada de 4 a 10 s sob música.
• Inserções onde a fala se refere a algo: o recibo quando o combustível é mencionado, o suporte de inspeção quando a inspeção é mencionada, um mapa da rota no início de cada trecho.
• Fotos sobre a voz (b-roll, capturas de tela do celular, legendas enquanto o falante continua falando): coloque-as sobre o clipe de fala com burn_in.py, antes do filmkit (ele mostra um clipe de fala apenas enquanto ele fala). Uma foto em modo retrato (captura de tela, clipe vertical, foto retrato) fica na altura total do quadro no lado livre do rosto do falante, encontrado por detecção facial, para que o rosto permaneça visível; o relógio e os botões do celular preenchem a parte superior e inferior de qualquer maneira. Uma foto paisagem cobre o quadro.
• As inserções de estrada devem mostrar o que a história precisa naquele ponto (a rampa de entrada no posto de gasolina antes de "nós paramos", o estacionamento do aeroporto antes da cena no aeroporto), não apenas qualquer rodovia: olhe uma folha de contato do clipe de estrada no momento certo.
• Cartão final: 20 s sobre a filmagem da estrada, texto na parte superior, o meio livre para os blocos de tela final do YouTube; um link de referência aqui, se o usuário tiver um.

Escreva project.py a partir de references/project_template.py; os tipos de itens EDL, legendas, chaves de música e opções por clipe estão documentados lá. Os intervalos de fala vêm dos tempos da transcrição.

3. Construir e renderizar

python $K/blur_plates.py <footage> <project>/film [--faces] IMG_0089 ...   # placas; --faces: pessoas também
python $K/burn_in.py film/IMG_0089_blur.mov film/IMG_0089_over.mov spec.json   # fotos sobre a fala, se houver
python $K/filmkit.py <project>/project.py                        # renderiza inserções, escreve film/<nome>.mlt
python $K/render_final.py <project>/film <nome> <footage>/<Nome>_HLG.mp4   # longo: execute em segundo plano

Antes de um trabalho pesado de GPU (renderização, WhisperX, dublagem), execute nvidia-smi: os números das placas mudam entre sessões e diferem entre ferramentas, e outros trabalhos podem estar usando uma placa (references/lessons.md, "GPUs e codificadores de hardware"). filmkit.py --no-media apenas reescreve o .mlt (segundos). A renderização exibe volume, duração, tags de codec/HDR e uma contagem de quadros verdes: espere cerca de -14 LUFS, Main 10, arib-std-b67, bt2020, 0 verdes.

4. Verificar antes de dizer ao usuário que está pronto

Ouça com WhisperX em vez de confiar na EDL: para cada corte novo ou alterado, corte os mesmos segundos do mp4 finalizado e transcreva-os (python $K/transcribe_window.py <wav> <offset>). Transcrições de primeira passagem geralmente estão erradas sobre onde uma frase termina, especialmente com números, então cortes feitos a partir delas cortam o final ("não 144, mas 147" perdeu "mas 147"). Também meça o volume das seções vizinhas (ffmpeg -ss A -t N -i film.mp4 -af ebur128 -f null -) e olhe um quadro de cada nova inserção. As outras armadilhas e suas correções: references/lessons.md.

5. Rodadas de revisão

O usuário assiste e envia notas com os tempos do filme. Para cada nota:

1. python $K/timeline.py film/<nome>.mlt 12:22 nomeia o clipe e o segundo de origem.
2. Verifique a origem (transcreva uma janela, meça o volume, olhe os quadros). Diga ao usuário o que realmente está lá, citando as palavras originais; a memória dele às vezes difere da gravação.
3. Altere a EDL e registre em edit_notes.md (tempo do filme, clipe e segundos, o que foi dito, alteração).

Enquanto o usuário ainda está assistindo, colete notas e não reconstrua: uma única construção no final evita renderizações longas. Quando ele disser para construir, reconstrua uma vez, verifique cada ponto alterado como na etapa 4, atualize os capítulos.

6. Entregáveis

references/youtube.md: descrição com capítulos (timeline.py), miniatura (make_thumb.py), legendas (make_subs.py no filme finalizado, corrigidas manualmente, depois traduzidas pista por pista, além dos textos na tela traduzidos como suas próprias pistas com onscreen_subs.py), dublagem automática do YouTube. O usuário pode assistir às renderizações em um telefone através de python $K/media_server.py --port 8765 <footage> <project>/film (LAN / VPN apenas; somente leitura; também em github.com/vstoos/media-server).

7. Faixas de áudio dubladas

Para um idioma que o usuário deseja ouvir, não ler: references/dubbing.md. A voz é Higgs TTS 3 (padrão desde 06.11.2026) com a referência salva do usuário naquele idioma (C:/Dados/voices, passe -); toda descrição de filme com uma faixa Higgs credita "Boson AI's Higgs Audio". As legendas passam por dub.py gen, dub_check.py captura as falhas do modelo take a take, dub_regen.py substitui o que falhou, e dub.py mix constrói a faixa e imprime o que ouvir. Corrija a pronúncia em say.json. A narração para gravações sem fala (clipes da dash-cam) segue o mesmo caminho em ucraniano, escrito como legendas. Não considere uma dublagem limpa apenas pelas verificações: o ouvido do usuário é a etapa final.

Privacidade

Placas: o usuário não desfoca o tráfego comum (Polônia; a caixa flutuante estraga as tomadas de estrada). Desfoque uma placa apenas onde o clipe mostra uma possível violação daquele motorista ou uma quase colisão, para que o filme não possa alimentar uma reclamação contra uma pessoa; as inserções de estrada vão como estão via CLIP_SRC no projeto. Desfoque os rostos de funcionários, transeuntes e crianças (blur_plates.py --faces; verifique os quadros, reflexos na pintura do carro podem enganar); inicie os mapas de rota em um local público, nunca na casa do usuário; não coloque rostos de outras pessoas (crianças acima de tudo) em miniaturas, a menos que seja solicitado.

Arquivos de referência

• references/project_template.py: arquivo de projeto anotado para copiar; sintaxe EDL.
• references/example_yaris.py: o filme Yaris finalizado, todos os recursos em uso.
• references/lessons.md: HDR, áudio, armadilhas de corte e enquadramento, com as correções que funcionaram.
• references/teslacam.md: clipes da Tesla dash-cam / Sentry (HW3): encontrando o incidente em um evento salvo e a correção de cor (scripts/teslacam_grade.py).
• references/youtube.md: descrição, capítulos, miniatura, legendas, dublagem, tela final.
• references/dubbing.md: faixas de áudio próprias na voz clonada do usuário e verificações automáticas de falhas.
• references/example_make_route.py: mapa de rota animado (tiles Sentinel-2 + estradas OSRM) do filme Yaris; adapte suas constantes (limites, cidades, pins, trechos) para uma nova viagem.