Communitygithub.com

majiayu000/claude-skill-registry

Transcrição e tradução de fala para texto via API de Áudio da OpenAI – modelos, formatos de resposta, timestamps, prompts, streaming, fragmentação e diarização.

O que é claude-skill-registry?

Esta skill fornece padrões e orientações para usar a API de Áudio da OpenAI para transcrição de fala para texto e tradução de áudio não-inglês para inglês. Ela cobre a seleção de modelos (whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize), formatos de resposta (json, texto, srt, vtt, verbose_json, diarized_json), obtenção de timestamps em nível de palavra e segmento, prompting para melhorar a precisão de vocabulário e estilo, fragmentação de arquivos de áudio grandes (>25 MB), transcrição em streaming e identificação de falantes (diarização). A skill é útil para desenvolvedores que precisam transcrever reuniões, entrevistas, podcasts, notas de voz ou gerar legendas, escolhendo o modelo e parâmetros corretos para cada caso de uso. É compatível com plataformas que utilizam a API da OpenAI, como aplicações Node.js com a biblioteca openai. A documentação em SKILL.md fornece um guia rápido, matriz de capacidades dos modelos, exemplos de código (TypeScript), uma árvore de decisão para seleção de modelo/formato/transcrição vs tradução, e uma lista de bandeiras vermelhas com erros comuns a evitar.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/ai-llm/api-ai-openai-whisper

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Padrões OpenAI Whisper

Guia Rápido: Use client.audio.transcriptions.create() para fala para texto e client.audio.translations.create() para áudio não-inglês para texto em inglês. Escolha gpt-4o-transcribe para maior precisão, gpt-4o-mini-transcribe para economia de custos, whisper-1 para timestamps/SRT/VTT, ou gpt-4o-transcribe-diarize para identificação de falantes. Os arquivos devem ter menos de 25 MB – fragmente arquivos maiores. Use prompt para guiar vocabulário e estilo. Streaming está disponível via stream: true para saída progressiva nos modelos gpt-4o-transcribe.


<critical_requirements>

CRÍTICO: Antes de Usar Esta Skill

Todo código deve seguir as convenções do projeto em CLAUDE.md (kebab-case, exports nomeados, ordenação de imports, import type, constantes nomeadas)

(Você DEVE escolher o modelo correto para o caso de uso – gpt-4o-transcribe para precisão, whisper-1 para timestamps/saída SRT/VTT, gpt-4o-transcribe-diarize para rótulos de falantes)

(Você DEVE fragmentar arquivos de áudio maiores que 25 MB antes de enviar para a API – a API rejeita arquivos que excedem este limite)

(Você DEVE passar response_format: "verbose_json" ao usar timestamp_granularities – timestamps só funcionam com este formato no whisper-1)

(Você DEVE definir chunking_strategy: "auto" ao usar gpt-4o-transcribe-diarize com áudio com mais de 30 segundos – a API exige isso)

</critical_requirements>


Detecção automática: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json

Quando usar:

  • Transcrever arquivos de áudio (reuniões, entrevistas, podcasts, notas de voz) para texto
  • Traduzir áudio não-inglês para texto em inglês
  • Gerar legendas no formato SRT ou VTT a partir de áudio
  • Obter timestamps em nível de palavra ou segmento para edição de vídeo
  • Identificar falantes em áudio com múltiplos falantes (diarização)
  • Transcrever em streaming de forma progressiva enquanto o modelo processa o áudio

Principais padrões abordados:

  • Seleção de modelo (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
  • Formatos de resposta (json, text, srt, vtt, verbose_json, diarized_json)
  • Timestamps (nível de palavra, nível de segmento) e geração de legendas
  • Prompting para vocabulário, siglas e estilo
  • Fragmentação de arquivos grandes (> 25 MB) com preservação de contexto
  • Transcrição em streaming com stream: true
  • Tradução para inglês via audio.translations.create()
  • Diarização de falantes com referências a falantes

Quando NÃO usar:

  • Texto para fala (TTS) – use a API TTS da OpenAI (client.audio.speech.create())
  • Conversas de voz bidirecionais em tempo real – use a API Realtime da OpenAI
  • Transcrição com provedores que não sejam OpenAI – use um SDK de fala agnóstico a provedores

Índice de Exemplos


Filosofia

A API de Áudio da OpenAI fornece transcrição de fala para texto e tradução através de vários modelos otimizados para diferentes necessidades. A API é simples – você envia um arquivo de áudio e recebe texto de volta – mas escolher o modelo, formato de resposta e parâmetros corretos é crítico para obter resultados de qualidade.

Princípios fundamentais:

  1. A seleção do modelo importa – gpt-4o-transcribe produz a maior precisão com menores taxas de alucinação. whisper-1 é o único modelo que suporta SRT/VTT/verbose_json com timestamps. gpt-4o-transcribe-diarize adiciona identificação de falantes.
  2. O tamanho do arquivo é a principal restrição – o limite de 25 MB significa que você deve fragmentar áudios longos. Divida nos limites das frases para preservar o contexto.
  3. O prompting melhora a precisão – O parâmetro prompt guia vocabulário, siglas e estilo de formatação. Ele não dá instruções – fornece contexto que o modelo utiliza para correspondência.
  4. O formato de resposta determina os recursos disponíveis – Timestamps exigem verbose_json no whisper-1. Diarização exige diarized_json. SRT/VTT estão disponíveis apenas no whisper-1.

Quando usar a API de Áudio:

  • Você precisa de transcrição precisa de arquivos de áudio gravados
  • Você precisa de legendas (SRT/VTT) a partir de áudio
  • Você precisa identificar quem está falando em uma conversa
  • Você precisa traduzir fala não-inglesa para texto em inglês

Quando NÃO usar:

  • Chat de voz em tempo real – use a API Realtime
  • Texto para fala – use client.audio.speech.create()
  • Você precisa de transcrição em um idioma de destino que não seja inglês (a tradução só gera inglês)

Padrões Principais

Padrão 1: Transcrição Básica

Envie um arquivo de áudio e receba o texto de volta. O modelo detecta automaticamente o idioma.

const transcription = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: createReadStream(audioPath),
});

Use gpt-4o-transcribe para maior precisão. Não use whisper-1 com verbose_json quando você só precisa de texto simples – isso adiciona sobrecarga e tem taxas de alucinação mais altas. Veja core.md para exemplos completos.


Padrão 2: Seleção de Modelo

Cada modelo tem capacidades e trade-offs distintos.

O que você precisa?
+-- Maior precisão, texto simples -> gpt-4o-transcribe
+-- Custo-eficiente, texto simples -> gpt-4o-mini-transcribe
+-- Timestamps (palavra/segmento) -> whisper-1 (verbose_json)
+-- Legendas SRT ou VTT -> whisper-1 (formato srt/vtt)
+-- Identificação de falantes -> gpt-4o-transcribe-diarize
+-- Saída em streaming -> gpt-4o-transcribe ou gpt-4o-mini-transcribe

Matriz de Capacidades dos Modelos

Funcionalidadewhisper-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
Formatos de respostajson, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
Timestampspalavra + segmentoNãoNãoNão
StreamingNãoSimSimNão
Suporte a promptSim (224 tokens)SimSimNão
LogprobsNãoSimSimNão
Rótulos de falantesNãoNãoNãoSim
Parâmetro de idiomaSimSimSimSim

Padrão 3: Prompting para Vocabulário e Estilo

O parâmetro prompt fornece contexto – não instruções. Ele guia a grafia de nomes, siglas e estilo de formatação. Não o use para dar instruções como "por favor, transcreva com cuidado" – ele corresponde ao estilo e contexto do vocabulário.

const VOCABULARY_PROMPT = "Kubernetes, kubectl, etcd, NGINX, gRPC, PostgreSQL";

const transcription = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: createReadStream(audioPath),
  prompt: VOCABULARY_PROMPT,
});

Casos de uso: Siglas/nomes próprios, preservar contexto entre fragmentos (passar o final da transcrição anterior), manter palavras de preenchimento, orientação de estilo de escrita. Veja core.md para exemplos detalhados de vocabulário.


Padrão 4: Fragmentação de Arquivos Grandes

Arquivos de áudio que excedem 25 MB devem ser divididos antes da transcrição. Divida nos limites das frases (ex.: via ffmpeg) para preservar o contexto. Passe o final da transcrição anterior como prompt para continuidade entre fragmentos.

const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// Dividir com ffmpeg: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Em seguida, transcrever sequencialmente, passando o contexto anterior via prompt

Veja core.md para a implementação completa de fragmentação com validação de tamanho e preservação de contexto.


Padrão 5: Transcrição em Streaming

Transcreva resultados parciais em streaming enquanto o modelo processa o áudio. Apenas gpt-4o-transcribe e gpt-4o-mini-transcribe suportam stream: true. Escute eventos transcript.text.delta para saída progressiva e transcript.text.done para conclusão. NÃO use stream: true com whisper-1 – não é suportado.

const stream = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: createReadStream(audioPath),
  stream: true,
});
for await (const event of stream) {
  if (event.type === "transcript.text.delta") process.stdout.write(event.delta);
}

Veja core.md para exemplos completos de streaming e logprobs.


Padrão 6: Tradução para Inglês

Traduza áudio não-inglês para texto em inglês. Apenas whisper-1 é suportado via audio.translations.create(). Para transcrição no mesmo idioma, use audio.transcriptions.create(). A tradução só gera inglês – não há como traduzir para outros idiomas.

const translation = await client.audio.translations.create({
  model: "whisper-1",
  file: createReadStream(audioPath),
});

Veja core.md para exemplos completos de tradução, incluindo prompting de vocabulário.


Padrão 7: Diarização de Falantes

Identifique quem está falando em áudio com múltiplos falantes. Use gpt-4o-transcribe-diarize com response_format: "diarized_json" e chunking_strategy: "auto" (obrigatório para áudio > 30s). A diarização não suporta prompt, logprobs ou timestamp_granularities.

const transcription = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe-diarize",
  file: createReadStream(audioPath),
  response_format: "diarized_json",
  chunking_strategy: "auto",
});

Opcionalmente, forneça known_speaker_names e known_speaker_references (clipes de áudio de 2 a 10 segundos como URLs de dados) para mapear segmentos para falantes conhecidos (até 4). Veja core.md para exemplos completos de diarização.


<decision_framework>

Estrutura de Decisão

Qual Modelo Escolher

O que você precisa da transcrição?
+-- Apenas texto (maior precisão) -> gpt-4o-transcribe
+-- Apenas texto (sensível a custo) -> gpt-4o-mini-transcribe
+-- Timestamps de palavra/segmento -> whisper-1 (verbose_json)
+-- Arquivos de legenda SRT ou VTT -> whisper-1 (srt ou vtt)
+-- Identificação de falantes -> gpt-4o-transcribe-diarize
+-- Saída progressiva/streaming -> gpt-4o-transcribe (stream: true)

Qual Formato de Resposta Usar

Qual saída você precisa?
+-- String de texto simples -> "text"
+-- JSON com campo text -> "json" (padrão)
+-- Legendas para vídeo -> "srt" ou "vtt" (apenas whisper-1)
+-- Timestamps (palavra/segmento) -> "verbose_json" (apenas whisper-1)
+-- Segmentos com rótulos de falantes -> "diarized_json" (apenas gpt-4o-transcribe-diarize)

Transcrição vs Tradução

O áudio está em inglês?
+-- SIM -> Use audio.transcriptions.create()
+-- NÃO -> Você quer a saída no idioma original?
    +-- SIM -> Use audio.transcriptions.create() (detecta automaticamente o idioma)
    +-- NÃO (quer inglês) -> Use audio.translations.create() (apenas whisper-1)

</decision_framework>


<red_flags>

BANDEIRAS VERMELHAS

Problemas de Alta Prioridade:

  • Usar timestamp_granularities sem response_format: "verbose_json" no whisper-1 (ignorado silenciosamente)
  • Enviar arquivos maiores que 25 MB (API retorna erro)
  • Usar gpt-4o-transcribe-diarize sem chunking_strategy em áudio > 30 segundos (API retorna erro)
  • Usar stream: true com whisper-1 (não suportado)

Problemas de Média Prioridade:

  • Usar whisper-1 quando gpt-4o-transcribe produziria maior precisão (whisper-1 tem taxas de alucinação mais altas)
  • Não passar o parâmetro language quando você conhece o idioma (a detecção automática pode estar errada para áudio curto ou ruidoso)
  • Usar audio.translations.create() quando você deseja transcrição no mesmo idioma (a tradução sempre gera inglês)
  • Dividir o áudio no meio de uma frase ao fragmentar (perde contexto nos limites)

Erros Comuns:

  • Tratar o parâmetro prompt como uma instrução ("por favor, transcreva com cuidado") – ele é contexto para correspondência de vocabulário e estilo
  • Usar gpt-4o-transcribe quando você precisa de saída SRT/VTT – apenas whisper-1 suporta esses formatos
  • Esperar que gpt-4o-transcribe-diarize suporte prompts ou logprobs (não suporta)
  • Usar o endpoint de tradução para áudio em inglês (ele só traduz não-inglês para inglês)
  • Não fornecer contexto do fragmento anterior ao transcrever arquivos divididos (reduz a precisão nos limites)

Pegadinhas e Casos Extremos:

  • O parâmetro prompt é limitado a aproximadamente 224 tokens no whisper-1. Prompts mais longos são truncados.
  • whisper-1 pode alucinar texto para segmentos de áudio silenciosos ou quase silenciosos. Use no_speech_prob do verbose_json para detectar isso.
  • gpt-4o-transcribe e gpt-4o-mini-transcribe suportam apenas os formatos de resposta json e text – não srt, vtt ou verbose_json.
  • O parâmetro language usa códigos ISO 639-1 (ex.: "en", "fr", "ja"). Definir isso melhora a precisão para áudio curto.
  • Formatos de arquivo suportados: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Outros formatos devem ser convertidos primeiro.
  • gpt-4o-transcribe-diarize rotula falantes como "A", "B", "C" a menos que você forneça known_speaker_names e known_speaker_references com clipes de áudio curtos.
  • O endpoint de tradução suporta apenas whisper-1 e só gera inglês – não há como traduzir para outros idiomas através desta API.
  • A transcrição em streaming emite eventos transcript.text.delta com uma propriedade de string delta, além de um evento final transcript.text.done.

</red_flags>


<critical_reminders>

LEMBRETES CRÍTICOS

**

...

[truncado para tradução]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Habilidades Relacionadas