Communitygithub.com

majiayu000/claude-skill-registry

Transcription et traduction de la parole en texte via l'API Audio OpenAI -- modèles, formats de réponse, horodatages, requêtes, streaming, découpage et diarisation

Qu'est-ce que claude-skill-registry ?

Cette compétence fournit un guide complet pour utiliser l'API Audio d'OpenAI afin de transcrire et traduire des fichiers audio. Elle couvre la sélection du modèle optimal (gpt-4o-transcribe pour la précision, whisper-1 pour les horodatages et sous-titres, gpt-4o-transcribe-diarize pour l'identification des locuteurs), la gestion des fichiers volumineux par découpage, l'utilisation des paramètres de requête pour améliorer la précision du vocabulaire, et le streaming pour un résultat progressif. Elle détaille les différents formats de réponse (json, texte, SRT, VTT, verbose_json, diarized_json) et leurs cas d'usage. La compétence met en garde contre les erreurs courantes comme l'oubli de découper les fichiers de plus de 25 Mo, et fournit un cadre de décision pour choisir le bon modèle et le bon format. Elle est destinée aux développeurs intégrant la transcription ou la traduction audio dans leurs applications, en particulier avec les SDK OpenAI.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Modèles OpenAI Whisper

Guide rapide : Utilisez client.audio.transcriptions.create() pour la transcription parole-texte et client.audio.translations.create() pour l'audio non-anglais vers le texte anglais. Choisissez gpt-4o-transcribe pour la plus haute précision, gpt-4o-mini-transcribe pour un bon rapport coût-efficacité, whisper-1 pour les horodatages/SRT/VTT, ou gpt-4o-transcribe-diarize pour l'identification des locuteurs. Les fichiers doivent faire moins de 25 Mo – découpez les fichiers plus volumineux. Utilisez prompt pour orienter le vocabulaire et le style. Le streaming est disponible via stream: true pour une sortie progressive sur les modèles gpt-4o-transcribe.


<exigences_critiques>

CRITIQUE : Avant d'utiliser cette compétence

Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports, import type, constantes nommées)

(Vous DEVEZ choisir le modèle approprié pour le cas d'usage – gpt-4o-transcribe pour la précision, whisper-1 pour les horodatages/sortie SRT/VTT, gpt-4o-transcribe-diarize pour les étiquettes de locuteurs)

(Vous DEVEZ découper les fichiers audio de plus de 25 Mo avant de les envoyer à l'API – l'API rejette les fichiers dépassant cette limite)

(Vous DEVEZ passer response_format: "verbose_json" lorsque vous utilisez timestamp_granularities – les horodatages ne fonctionnent qu'avec ce format sur whisper-1)

(Vous DEVEZ définir chunking_strategy: "auto" lorsque vous utilisez gpt-4o-transcribe-diarize avec un audio de plus de 30 secondes – l'API l'exige)

</exigences_critiques>


Détection automatique : Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, parole-texte, diarisation, diarized_json, timestamp_granularities, verbose_json

Quand l'utiliser :

  • Transcrire des fichiers audio (réunions, entretiens, podcasts, notes vocales) en texte
  • Traduire un audio non-anglais en texte anglais
  • Générer des sous-titres au format SRT ou VTT à partir d'un audio
  • Obtenir des horodatages au niveau du mot ou du segment pour le montage vidéo
  • Identifier les locuteurs dans un audio multipiste (diarisation)
  • Streamer les résultats de transcription progressivement au fur et à mesure que le modèle traite l'audio

Principaux modèles couverts :

  • Sélection du modèle (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
  • Formats de réponse (json, text, srt, vtt, verbose_json, diarized_json)
  • Horodatages (niveau mot, niveau segment) et génération de sous-titres
  • Requêtes pour le vocabulaire, les acronymes et le style
  • Découpage des fichiers volumineux (> 25 Mo) avec conservation du contexte
  • Streaming de la transcription avec stream: true
  • Traduction vers l'anglais via audio.translations.create()
  • Diarisation des locuteurs avec références aux locuteurs

Quand NE PAS l'utiliser :

  • Synthèse vocale (TTS) – utilisez l'API TTS d'OpenAI (client.audio.speech.create())
  • Conversations vocales bidirectionnelles en temps réel – utilisez l'API Realtime d'OpenAI
  • Transcription avec des fournisseurs autres qu'OpenAI – utilisez un SDK vocal indépendant du fournisseur

Index des exemples


Philosophie

L'API Audio d'OpenAI fournit la transcription et la traduction de la parole en texte via plusieurs modèles optimisés pour différents besoins. L'API est simple – vous envoyez un fichier audio et recevez du texte – mais choisir le bon modèle, le bon format de réponse et les bons paramètres est essentiel pour obtenir des résultats de qualité.

Principes fondamentaux :

  1. La sélection du modèle est importante – gpt-4o-transcribe produit la plus haute précision avec des taux d'hallucination plus faibles. whisper-1 est le seul modèle prenant en charge SRT/VTT/verbose_json avec horodatages. gpt-4o-transcribe-diarize ajoute l'identification des locuteurs.
  2. La taille du fichier est la contrainte principale – la limite de 25 Mo oblige à découper les audios plus longs. Coupez aux limites des phrases pour préserver le contexte.
  3. Les requêtes améliorent la précision – Le paramètre prompt oriente le vocabulaire, les acronymes et le formatage. Il ne donne pas d'instructions – il fournit un contexte que le modèle utilise pour correspondre.
  4. Le format de réponse détermine les fonctionnalités disponibles – Les horodatages nécessitent verbose_json sur whisper-1. La diarisation nécessite diarized_json. SRT/VTT sont uniquement disponibles sur whisper-1.

Quand utiliser l'API Audio :

  • Vous avez besoin d'une transcription précise de fichiers audio enregistrés
  • Vous avez besoin de sous-titres (SRT/VTT) à partir d'un audio
  • Vous avez besoin d'identifier qui parle dans une conversation
  • Vous avez besoin de traduire un discours non-anglais en texte anglais

Quand NE PAS l'utiliser :

  • Chat vocal en temps réel – utilisez plutôt l'API Realtime
  • Synthèse vocale – utilisez client.audio.speech.create()
  • Vous avez besoin d'une transcription dans une langue cible autre que l'anglais (la traduction ne produit que de l'anglais)

Modèles principaux

Modèle 1 : Transcription de base

Envoyez un fichier audio et recevez du texte en retour. Le modèle détecte automatiquement la langue.

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

Utilisez gpt-4o-transcribe pour la plus haute précision. N'utilisez pas whisper-1 avec verbose_json lorsque vous n'avez besoin que de texte brut – cela ajoute de la surcharge et a des taux d'hallucination plus élevés. Voir core.md pour des exemples complets.


Modèle 2 : Sélection du modèle

Chaque modèle a des capacités et des compromis distincts.

De quoi avez-vous besoin ?
+-- Plus haute précision, texte brut -> gpt-4o-transcribe
+-- Rentable, texte brut -> gpt-4o-mini-transcribe
+-- Horodatages (mot/segment) -> whisper-1 (verbose_json)
+-- Sous-titres SRT ou VTT -> whisper-1 (format srt/vtt)
+-- Identification des locuteurs -> gpt-4o-transcribe-diarize
+-- Sortie en streaming -> gpt-4o-transcribe ou gpt-4o-mini-transcribe

Matrice des capacités du modèle

Fonctionnalitéwhisper-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
Formats de réponsejson, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
Horodatagesmot + segmentNonNonNon
StreamingNonOuiOuiNon
Support des requêtesOui (224 jetons)OuiOuiNon
LogprobsNonOuiOuiNon
Étiquettes de locuteursNonNonNonOui
Paramètre de langueOuiOuiOuiOui

Modèle 3 : Requêtes pour le vocabulaire et le style

Le paramètre prompt fournit du contexte – pas des instructions. Il guide l'orthographe des noms, des acronymes et du formatage. Ne l'utilisez pas pour donner des instructions comme "veuillez transcrire soigneusement" – il correspond au contexte du style et du vocabulaire.

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,
});

Cas d'usage : Acronymes/noms propres, conservation du contexte entre les morceaux (passez la fin de la transcription précédente), maintien des mots de remplissage, guide de style d'écriture. Voir core.md pour des exemples détaillés de vocabulaire.


Modèle 4 : Découpage des fichiers volumineux

Les fichiers audio dépassant 25 Mo doivent être divisés avant la transcription. Coupez aux limites des phrases (par exemple, via ffmpeg) pour préserver le contexte. Passez la fin de la transcription précédente comme prompt pour la continuité entre les morceaux.

const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 Mo
// Découper avec ffmpeg : ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Puis transcrire séquentiellement, en passant le contexte précédent via prompt

Voir core.md pour l'implémentation complète du découpage avec validation de la taille et conservation du contexte.


Modèle 5 : Transcription en streaming

Obtenez des résultats de transcription partiels au fur et à mesure que le modèle traite l'audio. Seuls gpt-4o-transcribe et gpt-4o-mini-transcribe prennent en charge stream: true. Écoutez les événements transcript.text.delta pour une sortie progressive et transcript.text.done pour la fin. N'utilisez PAS stream: true avec whisper-1 – ce n'est pas pris en charge.

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);
}

Voir core.md pour des exemples complets de streaming et de logprobs.


Modèle 6 : Traduction vers l'anglais

Traduisez un audio non-anglais en texte anglais. Seul whisper-1 est pris en charge via audio.translations.create(). Pour une transcription dans la même langue, utilisez plutôt audio.transcriptions.create(). La traduction ne produit que de l'anglais – il n'y a aucun moyen de traduire vers d'autres langues.

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

Voir core.md pour des exemples complets de traduction, y compris les requêtes de vocabulaire.


Modèle 7 : Diarisation des locuteurs

Identifiez qui parle dans un audio multipiste. Utilisez gpt-4o-transcribe-diarize avec response_format: "diarized_json" et chunking_strategy: "auto" (obligatoire pour un audio > 30 s). La diarisation ne prend pas en charge 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",
});

Vous pouvez éventuellement fournir known_speaker_names et known_speaker_references (extraits audio de 2 à 10 secondes sous forme d'URL de données) pour mapper les segments à des locuteurs connus (jusqu'à 4). Voir core.md pour des exemples complets de diarisation.


<cadre_decisionnel>

Cadre décisionnel

Quel modèle choisir

De quoi avez-vous besoin pour la transcription ?
+-- Juste du texte (plus haute précision) -> gpt-4o-transcribe
+-- Juste du texte (sensible au coût) -> gpt-4o-mini-transcribe
+-- Horodatages mot/segment -> whisper-1 (verbose_json)
+-- Fichiers de sous-titres SRT ou VTT -> whisper-1 (srt ou vtt)
+-- Identification des locuteurs -> gpt-4o-transcribe-diarize
+-- Sortie progressive/streaming -> gpt-4o-transcribe (stream: true)

Quel format de réponse utiliser

De quelle sortie avez-vous besoin ?
+-- Chaîne de texte brut -> "text"
+-- JSON avec champ texte -> "json" (par défaut)
+-- Sous-titres pour vidéo -> "srt" ou "vtt" (whisper-1 uniquement)
+-- Horodatages (mot/segment) -> "verbose_json" (whisper-1 uniquement)
+-- Segments étiquetés par locuteur -> "diarized_json" (gpt-4o-transcribe-diarize uniquement)

Transcription vs Traduction

L'audio est-il en anglais ?
+-- OUI -> Utilisez audio.transcriptions.create()
+-- NON -> Voulez-vous la sortie dans la langue d'origine ?
    +-- OUI -> Utilisez audio.transcriptions.create() (détection automatique de la langue)
    +-- NON (voulez l'anglais) -> Utilisez audio.translations.create() (whisper-1 uniquement)

</cadre_decisionnel>


<drapeaux_rouges>

DRAPEAUX ROUGES

Problèmes de priorité élevée :

  • Utiliser timestamp_granularities sans response_format: "verbose_json" sur whisper-1 (ignoré silencieusement)
  • Envoyer des fichiers de plus de 25 Mo (l'API renvoie une erreur)
  • Utiliser gpt-4o-transcribe-diarize sans chunking_strategy sur un audio de plus de 30 secondes (l'API renvoie une erreur)
  • Utiliser stream: true avec whisper-1 (non supporté)

Problèmes de priorité moyenne :

  • Utiliser whisper-1 alors que gpt-4o-transcribe produirait une précision plus élevée (whisper-1 a des taux d'hallucination plus élevés)
  • Ne pas passer le paramètre language lorsque vous connaissez la langue (la détection automatique peut être erronée pour un audio court ou bruyant)
  • Utiliser audio.translations.create() alors que vous voulez une transcription dans la même langue (la traduction produit toujours de l'anglais)
  • Couper l'audio au milieu d'une phrase lors du découpage (perd le contexte aux limites)

Erreurs courantes :

  • Traiter le paramètre prompt comme une instruction ("veuillez transcrire soigneusement") – c'est du contexte pour la correspondance du vocabulaire et du style
  • Utiliser gpt-4o-transcribe lorsque vous avez besoin d'une sortie SRT/VTT – seul whisper-1 prend en charge ces formats
  • S'attendre à ce que gpt-4o-transcribe-diarize prenne en charge les requêtes ou les logprobs (ce n'est pas le cas)
  • Utiliser le point de terminaison de traduction pour un audio anglais (il ne traduit que du non-anglais vers l'anglais)
  • Ne pas fournir le contexte du morceau précédent lors de la transcription de fichiers divisés (réduit la précision aux limites)

Pièges et cas particuliers :

  • Le paramètre prompt est limité à environ 224 jetons sur whisper-1. Les requêtes plus longues sont tronquées.
  • whisper-1 peut halluciner du texte pour des segments audio silencieux ou quasi silencieux. Utilisez no_speech_prob de verbose_json pour le détecter.
  • gpt-4o-transcribe et gpt-4o-mini-transcribe ne prennent en charge que les formats de réponse json et text – pas srt, vtt, ou verbose_json.
  • Le paramètre language utilise les codes ISO 639-1 (par exemple, "en", "fr", "ja"). Le définir améliore la précision pour les audios courts.
  • Formats de fichier pris en charge : flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Les autres formats doivent d'abord être convertis.
  • gpt-4o-transcribe-diarize étiquette les locuteurs par "A", "B", "C" sauf si vous fournissez known_speaker_names et known_speaker_references avec de courts extraits audio.
  • Le point de terminaison de traduction ne prend en charge que whisper-1 et ne produit que de l'anglais – il n'y a aucun moyen de traduire vers d'autres langues via cette API.
  • La transcription en streaming émet des événements transcript.text.delta avec une propriété de chaîne delta, plus un événement final transcript.text.done.

</drapeaux_rouges>


<rappels_critiques>

RAPPELS CRITIQUES

**

…

[tronqué pour la traduction]

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.

Skills associés