Transcrição do YouTube (via DeepAPI, fallback yt-dlp)

Quando Usar

• Use quando o usuário pedir uma transcrição do YouTube, legendas, legendas ocultas ou extração de conteúdo falado.
• Use quando o DeepAPI ou um fallback local puderem buscar a transcrição com segurança.

Busque a transcrição de um vídeo do YouTube e salve um arquivo bruto limpo .txt. O caminho principal é o DeepAPI POST /v1/scrape/youtube/transcript. Ele é executado no lado do servidor, evitando a marcação de bot por IP local que assola o yt-dlp.

Local de Salvamento

• Se o usuário estiver em um projeto/diretório de trabalho real → salve lá.
• Caso contrário (nenhum diretório fornecido, ou o diretório atual não faz sentido) → salve em ~/Downloads.
• Sempre nomeie o arquivo Channel_Title com espaços substituídos por _ (por exemplo, David_Ondrej_title_of_video.txt). Se os metadados não estiverem disponíveis, use o ID do vídeo como fallback.

Caminho Principal — DeepAPI

DEEPAPI_API_KEY deve estar presente no ambiente. Não leia arquivos de inicialização do shell ou imprima segredos:

test -n "$DEEPAPI_API_KEY" || { echo "DEEPAPI_API_KEY is not set"; exit 1; }
BASE=${DEEPAPI_API_BASE_URL:-https://deepapi.co}

Execute o scrape (mantenha a Chave de Idempotência; retentativas devem reutilizar a MESMA):

IDK=$(uuidgen)
curl -s --max-time 120 "$BASE/v1/scrape/youtube/transcript" \
  -H "Authorization: Bearer $DEEPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDK" \
  -d '{"url": "VIDEO_URL", "maxCostUsd": "0.05", "waitForFinishSecs": 60}' \
  > /tmp/yt_transcript.json

• Vídeos não em inglês: adicione "language": "de" (etc.) ao corpo.
• status: running → espere next.afterSecs, então curl "$BASE$(jq -r '.next.path' /tmp/yt_transcript.json)" -H "Authorization: Bearer $KEY" até succeeded ou failed.

Extraia o texto e salve-o:

jq -r '.status' /tmp/yt_transcript.json                # succeeded | running | failed
jq -r '.output[0].text' /tmp/yt_transcript.json > "$OUT/$NAME.txt"
jq -r '.debitMicrousd' /tmp/yt_transcript.json         # cost (50000 = $0.05)

.output[0].segments também tem segmentos com tempo (startSecs, durationSecs, text) se o usuário quiser os carimbos de data/hora. output vazio = o vídeo não tem legendas; reporte, não tente novamente.

Para o nome do arquivo Channel_Title, obtenha os metadados com um rápido yt-dlp --print "%(channel)s|%(title)s" --skip-download "URL"; se falhar, use o ID do vídeo.

Quando usar o yt-dlp como fallback

• DEEPAPI_API_KEY ausente no ambiente.
• HTTP 402 insufficient_credits (diga ao usuário para recarregar em deepapi.co/credits primeiro; use o fallback apenas se estiverem indisponíveis).
• Requisição do DeepAPI failed duas vezes.

Informe o usuário sempre que usar um fallback — um fallback significa que o produto perdeu um caso de uso real.

Caminho de Fallback — yt-dlp (local)

OUT="$(pwd)"            # or ~/Downloads if cwd makes no sense
META=$(yt-dlp --print "%(channel)s|%(title)s" --skip-download "URL")
NAME=$(echo "$META" | tr '| ' '__' | tr -cd '[:alnum:]_.-')   # "Channel_Title", spaces -> _, strip unsafe chars
yt-dlp --skip-download --write-subs --write-auto-subs \
  --sub-langs "en.*" --sub-format json3 \
  -o "$OUT/$NAME.%(ext)s" "URL"

• Fallback channel → uploader → uploader_id se channel for nulo.
• --skip-download = apenas legendas. --write-subs + --write-auto-subs = manual primeiro, automático como fallback.
• Sempre use json3, nunca VTT/SRT — VTT automático repete cada linha duas vezes (legendas rolantes).

Achate json3 → texto bruto:

python3 - "$OUT" <<'PY'
import json, html, re, glob, sys, pathlib
f = glob.glob(sys.argv[1] + "/*.json3")
if not f: sys.exit("no json3 file")
data = json.load(open(f[0], encoding="utf-8"))
parts = ["".join(s.get("utf8","") for s in e.get("segs") or []) for e in data.get("events", [])]
txt = re.sub(r"\s+", " ", html.unescape(" ".join(p.strip() for p in parts if p.strip()))).strip()
out = pathlib.Path(f[0]).with_suffix(".txt")
out.write_text(txt, encoding="utf-8"); print(out)
PY

Tratamento de falha do yt-dlp

• Não em inglês / idioma desconhecido: execute yt-dlp --list-subs "URL" primeiro, depois defina --sub-langs.
• yt-dlp mais recente pode precisar de deno no PATH para extração do YouTube.
• Na primeira falha: execute yt-dlp -U uma vez, tente novamente uma vez, depois pare.
• 429 / "Faça login para confirmar que você não é um bot" = IP marcado. PARE — NÃO tente novamente em loop (piora).
• Nunca use fallback para baixar áudio para Whisper, a menos que o usuário peça explicitamente.

Saída

Relate o caminho salvo; imprima o texto se for curto. Se o DeepAPI foi usado, também relate o custo em dólares.

Limitações

…