KKcorps/lesson-film

Filmes de lição

Um filme de lição ensina um mecanismo bem o suficiente para que um novato possa explicá-lo de volta após uma única exibição. Cada imagem é desenhada por código, a voz do narrador é o relógio e a música toca nos intervalos que a voz deixa. Ele se baseia em code-film: essa habilidade gerencia o visual, a galeria, o gosto e as verificações de defeitos. Esta habilidade gerencia o ensino, as palavras, a voz, o ritmo, o final e o lado do YouTube.

O exemplo trabalhado é examples/parcel42-lesson/, uma lição de 130 s sobre como o upsert do Apache Pinot oculta linhas antigas. Kartik, o autor da habilidade, a chamou de "perfeita" após oito versões, e cada anotação ao longo do caminho está no arquivo de referência que a possui. Leia seu README para o método, nunca para o visual.

O núcleo: acompanhe o espectador

Um filme de lição é metade de uma conversa, e o espectador fornece a outra metade em silêncio. A cada segundo, eles têm três coisas:

• O que sabem. Apenas o que o filme mostrou e disse até agora, mais conhecimento cotidiano. Não o código-fonte, nem o que você leu para fazê-lo.
• O que estão perguntando. Cada imagem e cada afirmação levanta a próxima pergunta: "então o que acontece com o antigo?", "e se chegar atrasado?", "isso não desperdiça espaço?"
• O que acreditam. Um modelo do mecanismo construído apenas a partir do filme. Uma palavra errada instala um modelo errado. "Pinot nunca derruba a casa velha" ensinou que nada é removido, e então o filme mostrou a compactação removendo-o.

Fazer o filme é executar esse modelo segundo a segundo, pela voz e pela imagem juntas:

1. Responda à pergunta onde ela está. A carta atrasada vem logo após a regra, e "E as casas escuras?" logo após a consulta.
2. Deixe-os chegar antes de anunciar. A imagem mostra a evidência um instante antes de a voz nomeá-la. Um título, um rótulo ou um nome de capítulo nunca dá a resposta antes de a pergunta ser feita.
3. Nunca corte o fio. Uma linha que promete algo é dona da próxima imagem. Depois de "duas chaves viram", a próxima coisa na tela são as chaves.
4. Entregue cada palavra antes de usá-la. Cada termo na tela é dito em voz alta uma vez, onde a imagem o mostra, e nenhum chega à primeira linha. A coisa no mundo vem primeiro, e o termo é nomeado depois dela. Fora dessa linha de nomeação, uma frase permanece em um mundo: uma flor parou de crescer, nunca está "fechada". Um filme inteiro mostrou "segmento 7" em placas de rua sem nunca dizer segmento.
5. Ensine o mecanismo, não o código. Mostre um nome real apenas quando o espectador for pesquisá-lo (validDocIds), nunca um nome de função que apenas rotula a maquinaria.

Cada regra nas referências é uma dessas cinco aplicadas. Quando uma regra parece entrar em conflito com outra, ou nada cobre um caso, execute o modelo do espectador e ele decide.

Uma anotação nunca é sobre uma instância. Quando a pessoa para quem você faz o filme aponta para um momento, ela está apontando para um lugar onde o modelo quebrou. Encontre todos os outros lugares onde ele quebrou da mesma forma, corrija todos e relate a contagem. O "ritmo doloroso" de Kartik eram os preenchimentos e também os cliques e estalos. Suas letras faltantes eram qualquer evento cronometrado a partir de um quadro fixo, e é por isso que shiftcheck.py existe. Sua "frase errada" era toda palavra absoluta, e é por isso que scriptcheck.py as lista.

Configuração

Esta habilidade precisa que code-film esteja instalado ao lado dela, na mesma pasta de habilidades. Sua construção, portal, captura, costuras e verificações de som e sua caligrafia vêm de lá, e todos os scripts a encontram lá ou em $CODE_FILM.

Execute bash assets/setup.sh uma vez. Ele verifica o doctor do code-film, depois constrói um venv Python 3.12 em ~/.cache/lesson-film/venv com Kokoro, soundfile, faster-whisper e o modelo spaCy English, e verifica se o ffmpeg tem loudnorm.

Como é o bom resultado

• Um novato consegue recontá-lo. Suas duas frases correspondem à linha principal do cartão de intenção, com os termos reais nos lugares certos.
• Soa como uma pessoa explicando para você. Cada frase leva à próxima, e cada mudança de cena carrega a pergunta viva adiante. Leia o roteiro em voz alta sem as imagens. Se soar como uma lista de rótulos, não está pronto (reference/words.md).
• Respira. O espectador tem tempo para ver cada mudança antes da próxima. Kartik achou um corte de 64 s a 0,36 cortes por segundo "muito rápido". O corte aprovado tem 130 s a 0,16 cortes por segundo, com a voz em velocidade normal e respirações reais (reference/pace-and-ending.md).
• Cada afirmação é verdadeira e verificada. Escreva as afirmações em facts.md contra a fonte antes de qualquer desenho. A imagem mostra exatamente esse estado.
• A imagem muda na palavra. Cada coisa aparece no momento em que a voz a nomeia. Movimento e cor ficam apenas na parte sendo explicada (reference/teaching.md).
• Abre suavemente e termina devagar. Uma primeira linha que qualquer um pode absorver, com a imagem e a música já rodando, uma abertura a frio que termina na pergunta, depois um título de cerca de cinco segundos, como a Kurzgesagt faz. "O começo parece abrupto" foi a anotação de Kartik em um filme que abria com um personagem que o espectador não conhecia (reference/pace-and-ending.md).
• Termina, não para. Um resumo, um desfecho, uma linha de encerramento que responde à abertura, o acorde final, então imagem e som desaparecem juntos por vários segundos. "O final é abrupto" é a anotação para nunca mais receber.
• Os defeitos são zero. Sem flash, sem estalo, sem clipe, volume a -14 LUFS, cada palavra ouvida.

Estes são julgamentos, não regras. Quebre um quando o cartão disser por quê.

Fluxo de trabalho

Copie isto para suas anotações e relate cada linha ao terminá-la. Uma linha não pode ser marcada sem dizer como.

[ ] 0 referência  apenas se eles compartilharam uma. Um clipe, um quadro ou uma página HTML. Relate qual forma, o que ela faz, quais lacunas podem ser fechadas, e o que você aproveita e deixa.
[ ] 1 fatos      facts.md escrito contra a fonte. Relate as afirmações e onde cada uma foi verificada.
[ ] 2 intenção   assets/intent.md copiado para <peça>.intent.md, conclusão, sentimento, pergunta, palpite. Relate-os.
[ ] 3 galeria    reference/gallery.md do code-film, os dois ou três filmes mais próximos. Relate o que você aproveita e o que não copiará.
[ ] 4 esboços    três novas histórias, cada uma com um quadro de aparência finalizada desenhado com o kit (sketch.py), um deles um mundo habitável, nenhum tirado do exemplo ou de uma referência compartilhada. sketchcheck.py limpo de BLOCKs, então julgado contra a folha. Mostre-os. Relate a linha de cada história, as três respostas de julgamento e a escolha.
[ ] 5 palavras   o roteiro inteiro como um parágrafo em <peça>.chain.txt, depois cortado em linhas com seus "termos", "coisas" e "técnica". Antes do parágrafo, escreva a coisa de cada termo e o verbo do mundo para cada estado real que ele tem. scriptcheck.py limpo de BLOCKs. Relate esse mapa, o roteiro lido em voz alta uma vez, cada dobradiça, e uma decisão sobre cada REVISÃO.
[ ] 6 voz        <peça>.lines.json -> voice.py -> heard.py --write. Relate o comprimento, e cada palavra ouvida ou por que não.
[ ] 7 plano      cenas, cada uma vinculada às palavras que a mudam, e ao estado do mundo que compartilham. Relate o plano, com a coisa no mundo que mostra cada termo e o verbo do mundo para cada estado real.
[ ] 8 construção página de assets/template/. Cenas verificadas sozinhas em rascunho primeiro. Relate o que você redesenhou depois de olhar.
[ ] 9 som        <peça>.score.py de assets/score_template.py. Relate os acordes, a melodia nas lacunas e os sons do mundo.
[ ] 10 render    assets/build.sh. DRAFT=1 primeiro. Relate os números.
[ ] 11 verificar todas as três camadas abaixo. Relate cada uma.
[ ] 12 entregar  um novo arquivo a cada construção, nunca sobrescrever. O mestre para o YouTube, uma prévia pequena abaixo de 30 MB para enviar.

Os passos 1 a 5 são onde as lições são ganhas. O passo 5 em particular: escreva o roteiro como prosa primeiro, depois corte-o em linhas. Cortar primeiro é como um roteiro se torna uma pilha de legendas.

Verificar

Relate todas as três camadas na nota de entrega, separadamente.

• Bloco de defeitos. build.sh executa scriptcheck.py (cada termo dito, nenhum na primeira linha, vínculos que existem) e check.py e seamcheck.py do code-film, masteriza para -14 LUFS integrado com pico verdadeiro a -1,5 dBTP, e codifica para a especificação do YouTube (reference/youtube.md).
• A lição é medida. verify.py verifica o comprimento, ritmo e som do cartão. heard.py transcreve a voz e informa quais palavras não foram ouvidas e quanto o som está atrasado em relação aos tempos de referência. wordsync.py verifica se o movimento aumenta em cada palavra à qual a imagem está vinculada. shiftcheck.py renderiza o filme com a voz movida dois segundos depois e falha em qualquer cena que mude, que é como um evento cronometrado a partir de um quadro fixo aparece. captions.py escreve um SRT exato a partir das mesmas referências.
• O teste de observação é seu, depois da pessoa. Re conte como um novato. Nomeie cada quadro da folha de contato. Assista com o som desligado. Leia o roteiro em voz alta sem imagens. Julgue os últimos dez segundos sozinhos. Depois diga claramente o que você não verificou, como a voz de ouvido.

Quando ler o quê

Leia cada arquivo inteiro, com uma chamada por arquivo, e leia um arquivo novamente sozinho se a leitura disser que os tokens foram truncados. "Quando ler o quê" do code-film diz o que uma leitura em lote custa.

• Quando eles compartilham uma referência, leia reference/references.md do code-film. Ele cobre todas as três formas. Um clipe e um quadro são separados com ffmpeg. Uma página HTML, nossa ou deles, passa por assets/refpage.mjs do code-film, que observa a página desenhar e relata sua paleta, marcas, camadas e kit de áudio, e escreve um MP4 para que as verificações de clipe também sejam executadas nele.
• Antes dos fatos e do cartão de intenção, leia reference/teaching.md.
• Antes dos esboços, leia reference/sketches.md desta habilidade e a seção de História de reference/traps.md. Depois leia reference/story.md do code-film para "Escolha uma forma primeiro" e "O que persiste", e reference/traps-story.md do code-film.
• Antes de escrever uma única linha do roteiro, leia reference/words.md.
• Ao planejar a abertura ou o final, e ao definir a velocidade da voz, respirações e pausas, leia reference/pace-and-ending.md.
• Ao fazer ou corrigir a voz, leia reference/voice.md.
• Ao planejar cenas, dividi-las entre ajudantes ou construir a página, leia reference/film.md, e reference/moves.md do code-film, que gerencia os movimentos entre duas imagens.
• Ao fazer o som, leia reference/sound.md, e reference/sound.md do code-film para os instrumentos e reference/traps-sound.md.
• Antes do primeiro render e após qualquer anotação sobre um, leia reference/traps.md.
• Antes de publicar, leia reference/youtube.md.
• Quando uma regra precisa de sua fonte, ou alguém pergunta por que a habilidade faz algo, leia reference/research.md: as evidências, tamanhos de efeito e links.
• Para o visual, o gosto e o acabamento de impressão, leia gallery.md, taste.md e press.md do code-film, e traps-print.md antes de ajustar o acabamento.

Os arquivos

arquivo	o que é
assets/setup.sh	configuração única: o venv da voz e da audição, e as verificações
assets/intent.md	o cartão de intenção da lição, o cartão do code-film mais as linhas de ensino
assets/voice.py	fala <peça>.lines.json com Kokoro, coloca as linhas em uma grade de batidas, escreve a voz e as referências
assets/heard.py	transcreve a voz com Whisper, relata palavras ausentes e o atraso, --write armazena o atraso nas referências
assets/saytest.py	tenta reescritas de uma palavra que Kokoro diz errado, e diz qual o Whisper ouve corretamente
assets/captions.py, assets/wordsync.py	o SRT a partir das referências, e a verificação de que o movimento aumenta em cada palavra vinculada
assets/shiftcheck.py	a verificação de que cada cena é cronometrada a partir da voz, não de quadros fixos
assets/scriptcheck.py	a verificação do roteiro: termos ditos, nenhum na primeira linha, a coisa de cada termo dita antes do termo, vínculos que existem, e uma lista de palavras absolutas, palavras não ditas na tela e frases que misturam o mundo com o sistema real para ler
assets/sketchcheck.py, assets/barsheet.py	a verificação de esboço do code-film, executada com os quadros aprovados desta habilidade, a cidade do exemplo e o stub do modelo. E o script que reconstrói a folha de julgamento
assets/score_template.py	uma base por linha, a melodia nas lacunas, sons do mundo em mudanças de estado, uma redução de 16 dB sob a fala, o final que desaparece
assets/build.sh	página, portal, captura paralela, costuras, partitura, master -14 LUFS, codificação, legendas, folha de contato, todas as verificações
assets/template/	a página a copiar: assemble.py, film/kit.js (o ofício sem mundo: tinta, pontos, bordas, luz, caligrafia, o acabamento de impressão), film/core.js (relógio da voz, camadas, câmera, movimentos de mergulho e íris), film/main.js, film/SCENES.md, uma cena de exemplo que constrói um objeto substituto, e sketch.py com sketches/sketch.js para os três quadros de história
reference/stills/	quadros da lição aprovada, legendados, para as duas regras que a prosa sozinha não transmite: os momentos de abertura e encerramento, e uma imagem mudando em sua palavra. Também a folha de julgamento dos esboços sketch-bar.jpg, aberta apenas após seus próprios três existirem, e sent-back.jpg
examples/parcel42-lesson/	toda a fonte da lição aprovada, sua faixa de voz, um link para uma prévia do filme para assistir, seu README, folha de contato e miniaturas

A captura paralela vive no code-film (assets/capture-range.mjs, assets/capture-par.sh), porque qualquer filme longo precisa dela.

Alterando esta habilidade

Declare intenção e julgamento, e verifique o resultado contra a intenção. Uma nova lição que alguém aprove se torna um segundo exemplo, com uma linha neste arquivo sobre por que funciona. Uma lição aprendida vai para o único arquivo de referência que a possui, e todos os outros arquivos apontam para lá em uma linha.