wizz-method 1.12.0 → 1.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -198,6 +198,12 @@ areas:
         # sistema específica (é um app desktop autocontido que expõe um
         # endpoint MCP local) — nada de concreto pra checar sem inventar um
         # requisito que o registry não afirma.
+      - id: ctc-align
+        when: "Timestamps palavra a palavra CONFIÁVEIS de narração TTS (texto conhecido): sincronizar legenda, corte de cena, animação e elemento gráfico com a fala. Fonte única de timing em vídeo — substitui timestamps do Whisper e estimativa manual. Skill da lib: ctc-align (instalação + helper align.py + regras de âncora monotônica e duração mínima). Roda em CPU, sem CUDA."
+        platform: [darwin, linux]
+        check: "test -x ./tools/ctc-align/.venv/bin/ctc-forced-aligner"
+        install: 'mkdir -p tools/ctc-align && uv venv --python 3.12 tools/ctc-align/.venv && uv pip install --python tools/ctc-align/.venv/bin/python "git+https://github.com/MahmoudAshraf97/ctc-forced-aligner.git"'
+        verify: "command -v ffmpeg >/dev/null 2>&1 && command -v uv >/dev/null 2>&1"
     references:
       - "references/premium-agency-rules.md (regras $150k-tier, importadas por impeccable/huashu no modo high-end)"
 

package/src/skills-lib/ctc-align/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ctc-align
+description: Timestamps palavra a palavra confiáveis para narração TTS via alinhamento forçado (ctc-forced-aligner + âncora nos silêncios reais). Usar SEMPRE antes de definir tempo de legenda, corte de cena, animação ou elemento sincronizado com fala em qualquer vídeo (HyperFrames ou outro editor). Substitui o Whisper como fonte de timing quando o texto do roteiro é conhecido. Gatilhos - sincronizar legenda, timing de cena, alinhar áudio e texto, palavra a palavra, forced alignment, legenda karaokê, corrigir sync de vídeo.
+---
+
+# ctc-align — timing de fala como fonte única de verdade
+
+## Quando usar
+
+Sempre que um vídeo tiver narração cujo TEXTO é conhecido (roteiro de TTS, VSL,
+explainer) e for preciso decidir QUANDO algo aparece: legenda, corte de cena,
+animação, texto na tela.
+
+**Regra do método: nunca estimar tempo à mão e nunca confiar no timestamp do Whisper.**
+O Whisper adivinha as palavras e deriva (medido: até 6s); interpolação proporcional
+entre silêncios desloca palavras para o bloco vizinho. O alinhamento CTC recebe o texto
+exato e só procura onde cada palavra está: precisão de dezenas de ms.
+
+## Instalação (uma vez por projeto)
+
+    mkdir -p tools/ctc-align && cd tools/ctc-align
+    uv venv --python 3.12 .venv
+    uv pip install --python .venv/bin/python "git+https://github.com/MahmoudAshraf97/ctc-forced-aligner.git"
+
+Copiar o `scripts/align.py` desta skill para `tools/ctc-align/align.py`.
+Roda em CPU (Mac ARM ok, sem CUDA). Primeiro uso baixa o modelo MMS (~1GB).
+
+## Uso
+
+1. Gerar um .txt com o roteiro EXATO que o TTS falou (texto corrido; se o TTS falou
+   diferente do escrito, usar o que foi FALADO).
+2. Rodar:
+
+    tools/ctc-align/.venv/bin/python tools/ctc-align/align.py narracao.mp3 roteiro.txt transcript.json
+
+Saída: JSON [{"text","start","end","score"}] por palavra, bordas já encostadas nos
+silêncios reais (silencedetect embutido). Score perto de 0 = confiável; o helper avisa
+palavras com score < -1.0 (conferir de ouvido).
+
+## Como converter em tempos de cena/legenda
+
+- Legenda: usar start/end da palavra direto.
+- Corte de cena/elemento: âncora = start da PRIMEIRA palavra da frase que o elemento
+  ilustra. Buscar a palavra de forma MONOTÔNICA (cada âncora procurada a partir da
+  anterior), nunca busca global — palavra repetida ("10", "bónus") pega ocorrência errada.
+- Duração mínima de cena: 1,2s; se a frase for mais curta, empurrar a próxima cena
+  dentro da própria frase dela.
+- Nada aparece antes de ser mencionado; nada continua depois que o assunto mudou.
+
+## QA obrigatório antes do render
+
+Nenhuma palavra pode sobrepor o miolo de um silêncio real, e cada fim de frase do
+roteiro deve terminar num silêncio. Medir isso, não o desvio de âncoras que o próprio
+método criou. Áudio concatenado de blocos: alinhar bloco a bloco ou conferir fronteiras.
+
+## Limitações honestas
+
+- Precisa do texto exato; não transcreve. Áudio sem roteiro: transcrever com Whisper,
+  revisar o texto à mão e SÓ ENTÃO alinhar com este fluxo.
+- Acentos exigem a flag --romanize (o helper já passa).

package/src/skills-lib/ctc-align/scripts/align.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""align.py — timestamps palavra a palavra CONFIÁVEIS para narração TTS.
+
+Uso:
+    .venv/bin/python align.py <audio.mp3> <texto.txt> [saida.json]
+
+1. Roda o ctc-forced-aligner (MMS/CTC) com o TEXTO EXATO do roteiro.
+2. Encosta as bordas das palavras nos silêncios reais (ffmpeg silencedetect):
+   palavra que termina dentro de um silêncio termina onde o silêncio começa;
+   palavra que começa dentro de um silêncio começa onde o silêncio termina.
+3. Grava JSON [{"text","start","end","score"}].
+"""
+import json, re, subprocess, sys, os
+
+def silencios(audio, noise="-35dB", dur=0.30):
+    out = subprocess.run(["ffmpeg","-hide_banner","-i",audio,
+        "-af",f"silencedetect=noise={noise}:d={dur}","-f","null","-"],
+        capture_output=True, text=True).stderr
+    starts = [float(x) for x in re.findall(r"silence_start: ([\d.]+)", out)]
+    ends   = [float(x) for x in re.findall(r"silence_end: ([\d.]+)", out)]
+    return list(zip(starts, ends))
+
+def alinhar(audio, texto_path):
+    here = os.path.dirname(os.path.abspath(__file__))
+    cli = os.path.join(here, ".venv", "bin", "ctc-forced-aligner")
+    r = subprocess.run([cli, "--audio_path", audio, "--text_path", texto_path,
+        "--language", "por", "--split_size", "word", "--romanize",
+        "--device", "cpu"], capture_output=True, text=True)
+    saida = os.path.splitext(audio)[0] + ".json"
+    if not os.path.exists(saida):
+        sys.exit(f"aligner falhou:\n{r.stderr[-1500:]}")
+    d = json.load(open(saida))
+    segs = d if isinstance(d, list) else d["segments"]
+    for ext in (".json", ".txt"):
+        p = os.path.splitext(audio)[0] + ext
+        if os.path.exists(p): os.remove(p)
+    return segs
+
+def encostar(segs, sils):
+    novo = []
+    for w in segs:
+        s, e = w["start"], w["end"]
+        for ss, se in sils:
+            if ss <= s <= se: s = se
+            if ss <= e <= se: e = ss
+            if s < ss and e > se: e = ss
+        if e <= s: e = s + 0.05
+        novo.append({"text": w["text"], "start": round(s,3), "end": round(e,3),
+                     "score": round(w.get("score",0),4)})
+    return novo
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        sys.exit(__doc__)
+    audio, texto = sys.argv[1], sys.argv[2]
+    destino = sys.argv[3] if len(sys.argv) > 3 else os.path.splitext(audio)[0] + ".alinhado.json"
+    segs = alinhar(audio, texto)
+    sils = silencios(audio)
+    novo = encostar(segs, sils)
+    json.dump(novo, open(destino,"w",encoding="utf-8"), ensure_ascii=False, indent=1)
+    ruins = [w for w in novo if w["score"] < -1.0]
+    print(f"{len(novo)} palavras -> {destino} | {len(sils)} silencios usados como ancora")
+    if ruins:
+        print(f"atencao: {len(ruins)} palavras com score baixo (conferir): " +
+              ", ".join(f"{w['text']}@{w['start']:.1f}" for w in ruins[:8]))