Click here to view the next lesson.

Capítulo 2: Comprensión y Generación de Audio con Whisper y GPT-4o

2.2 Transcripción y Traducción con la API de Whisper

La API de Whisper representa un avance significativo en la tecnología de reconocimiento y traducción automática del habla. Esta sección explora los aspectos fundamentales del trabajo con Whisper, incluyendo sus capacidades, métodos de implementación y aplicaciones prácticas. Examinaremos cómo utilizar efectivamente la API tanto para tareas de transcripción como de traducción, cubriendo todo desde la configuración básica hasta las características avanzadas.

Ya sea que estés construyendo aplicaciones para creadores de contenido, desarrollando herramientas educativas o creando soluciones de accesibilidad, entender la funcionalidad de Whisper es crucial. Recorreremos ejemplos detallados y mejores prácticas que demuestran cómo integrar esta poderosa herramienta en tus proyectos, mientras destacamos consideraciones importantes para un rendimiento óptimo.

A lo largo de esta sección, aprenderás no solo los detalles técnicos de implementación, sino también las consideraciones estratégicas para elegir formatos de respuesta apropiados y manejar varias entradas de audio. Este conocimiento te permitirá construir soluciones robustas y escalables para necesidades de procesamiento de audio.

2.2.1 ¿Qué es Whisper?

Whisper es el revolucionario modelo de reconocimiento automático del habla (ASR) de código abierto de OpenAI que representa un avance significativo en la tecnología de procesamiento de audio. Este sofisticado sistema sobresale en el manejo de diversas entradas de audio, capaz de procesar varios formatos de archivo incluyendo .mp3, .mp4, .wav, y .m4a. Lo que distingue a Whisper es su doble funcionalidad: no solo convierte el contenido hablado en transcripciones de texto altamente precisas, sino que también ofrece potentes capacidades de traducción, convirtiendo sin problemas contenido de audio no inglés en una salida fluida en inglés. La arquitectura robusta del modelo asegura alta precisión a través de diferentes acentos, estilos de habla y condiciones de ruido de fondo.

Whisper demuestra una versatilidad excepcional a través de numerosas aplicaciones:

Transcripciones de reuniones o podcasts

Convierte discusiones y presentaciones extensas en documentos de texto consultables y compartibles con notable precisión. Esta funcionalidad es particularmente valiosa para empresas y creadores de contenido que necesitan:

Archivar reuniones importantes para consultas futuras
Crear versiones accesibles de contenido de audio
Permitir búsquedas rápidas a través de horas de contenido grabado
Generar documentación escrita a partir de discusiones verbales
Apoyar requisitos de cumplimiento para el mantenimiento de registros

La alta tasa de precisión asegura que los términos técnicos, nombres propios y discusiones complejas se capturen correctamente mientras se mantiene el flujo natural de la conversación.

Ejemplo:

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/meeting_snippet.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt
current_location = "Houston, Texas, United States"
print(f"Running Whisper transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'meeting_snippet.mp3' with the actual filename.
audio_file_path = "meeting_snippet.mp3"

# --- Optional Parameters for potentially better accuracy ---
# Specify language (ISO-639-1 code) if known, otherwise Whisper auto-detects.
# Example: "en" for English, "es" for Spanish, "de" for German
known_language = "en" # Set to None to auto-detect

# Provide a prompt with context, names, or jargon expected in the audio.
# This helps Whisper recognize specific terms accurately.
transcription_prompt = "The discussion involves Project Phoenix, stakeholders like Dr. Evelyn Reed and ACME Corp, and technical terms such as multi-threaded processing and cloud-native architecture." # Set to None if no prompt needed

# --- Function to Transcribe Audio ---
def transcribe_audio(client, file_path, language=None, prompt=None):
    """
    Transcribes the given audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Check file size (optional but good practice)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            print("Consider splitting the file into smaller chunks.")
            # You might choose to exit here or attempt anyway
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        return None


    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Optional: Specify language
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the string
            transcription_text = response
            print("Transcription successful.")
            return transcription_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        # Provide hints for common errors
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (mp3, mp4, mpeg, mpga, m4a, wav, webm).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit. Please split the file.")
        return None
    except FileNotFoundError: # Already handled above, but good practice
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcription = transcribe_audio(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription:
        print("\n--- Transcription Result ---")
        print(transcription)
        print("----------------------------\n")

        # How this helps the use case:
        print("This plain text transcription can now be:")
        print("- Saved as a text document (.txt) for archiving.")
        print("- Indexed and searched easily for specific keywords or names.")
        print("- Used to generate meeting minutes or documentation.")
        print("- Copied into accessibility tools or documents.")
        print("- Stored for compliance record-keeping.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcription)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nTranscription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la transcripción de archivos de audio como grabaciones de reuniones o episodios de podcast utilizando la API Whisper de OpenAI. El objetivo es convertir el contenido hablado en texto preciso y consultable, atendiendo necesidades como el archivo, la accesibilidad y la documentación.
Requisitos previos: Requiere las bibliotecas openai y python-dotenv, una clave API de OpenAI configurada en un archivo .env, y un archivo de audio de muestra (meeting_snippet.mp3).
Requisitos del archivo de audio: El script destaca los formatos de audio compatibles (MP3, WAV, M4A, etc.) y el límite crucial de 25MB por solicitud de API. Incluye una advertencia y explicación de que los archivos más largos deben segmentarse antes del procesamiento, aunque el código en sí maneja un solo archivo dentro del límite.
Inicialización: Configura el cliente estándar OpenAI utilizando la clave API.
Función de transcripción (transcribe_audio):
- Toma los argumentos client, file_path, y los opcionales language y prompt.
- Incluye una verificación de existencia y tamaño del archivo.
- Abre el archivo de audio en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.transcriptions.create con:
  - model="whisper-1": Especifica el modelo conocido por su alta precisión.
  - file=audio_file: Pasa el objeto de archivo abierto.
  - language: Opcionalmente proporciona el código de idioma (por ejemplo, "en") para potencialmente mejorar la precisión si se conoce el idioma. Si es None, Whisper detecta automáticamente.
  - prompt: Opcionalmente proporciona palabras clave contextuales, nombres (como "Project Phoenix", "Dr. Evelyn Reed"), o jerga. Esto ayuda significativamente a Whisper a transcribir con precisión términos especializados que se encuentran frecuentemente en reuniones o podcasts técnicos, abordando directamente la necesidad de capturar correctamente discusiones complejas.
  - response_format="text": Solicita la salida directamente como una cadena de texto plano, ideal para uso inmediato en documentos, indexación de búsqueda, etc. Se podrían solicitar otros formatos como verbose_json (para marcas de tiempo) o srt/vtt (para subtítulos) si fuera necesario.
- Manejo de errores: Incluye bloques try...except para errores de API (proporcionando sugerencias para problemas comunes como tamaño o formato de archivo) y errores del sistema de archivos.
Salida y utilidad:
- Se imprime el texto de transcripción resultante.
- El código conecta explícitamente esta salida con los beneficios del caso de uso: crear archivos consultables, generar documentación, apoyar la accesibilidad y permitir el cumplimiento normativo.
- Incluye un paso opcional para guardar la transcripción directamente en un archivo .txt.

Este ejemplo proporciona una implementación práctica de Whisper para el caso de uso descrito, enfatizando las características de precisión (indicaciones, especificación de idioma) y explicando cómo la salida de texto facilita las tareas posteriores deseadas como búsqueda y archivo. Recuerda usar un archivo de audio real (dentro del límite de tamaño) para las pruebas.

Conversión de notas de voz

Transforma los mensajes de voz rápidos en notas de texto organizadas, facilitando la revisión y el archivo de pensamientos hablados. Esta funcionalidad es particularmente valiosa para:

Crear recordatorios rápidos y listas de tareas mientras se está en movimiento
Capturar ideas creativas o sesiones de lluvia de ideas sin interrumpir el flujo de pensamiento
Tomar notas durante trabajo de campo o visitas al sitio donde escribir es poco práctico
Documentar observaciones o hallazgos de investigación en tiempo real

El sistema mantiene el flujo natural del habla mientras organiza el contenido en texto claro y legible que puede ser fácilmente buscado, compartido o integrado en otros documentos.

Ejemplo:

Este script se centra en tomar un archivo de audio típico de nota de voz y convertirlo en texto consultable y utilizable, ideal para capturar ideas, recordatorios o notas de campo.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/voice_memo.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Miami, Florida, United States"
print(f"Running Whisper voice note transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local voice note audio file
# IMPORTANT: Replace 'voice_memo.m4a' with the actual filename.
audio_file_path = "voice_memo.mp3"

# --- Optional Parameters (Often not needed for simple voice notes) ---
# Language auto-detection is usually sufficient for voice notes.
known_language = None # Set to "en", "es", etc. if needed

# Prompt is useful if your notes contain specific jargon/names, otherwise leave as None.
transcription_prompt = None # Example: "Remember to mention Project Chimera and the client ZetaCorp."

# --- Function to Transcribe Voice Note ---
def transcribe_voice_note(client, file_path, language=None, prompt=None):
    """
    Transcribes the given voice note audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe voice note: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size (less likely to be an issue for voice notes)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None # Decide if you want to stop for large files
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        # Continue attempt even if size check fails
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending voice note to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Defaults to None (auto-detect)
                prompt=prompt,              # Defaults to None
                response_format="text"      # Request plain text output for easy use as notes
            )

            # The response object for "text" format is directly the string
            note_text = response
            print("Transcription successful.")
            return note_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (m4a, mp3, wav, etc.).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_note = transcribe_voice_note(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcribed_note:
        print("\n--- Transcribed Voice Note Text ---")
        print(transcribed_note)
        print("-----------------------------------\n")

        # How this helps the use case:
        print("This transcribed text from your voice note can be easily:")
        print("- Copied into reminder apps or to-do lists.")
        print("- Saved as a text file for archiving creative ideas or brainstorms.")
        print("- Searched later for specific keywords or topics.")
        print("- Shared via email or messaging apps.")
        print("- Integrated into reports or documentation (e.g., field notes).")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_note)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nVoice note transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para transcribir grabaciones de audio cortas como notas de voz y memorandos. Es ideal para capturar rápidamente pensamientos, ideas, recordatorios u observaciones de campo y convertirlos en texto fácilmente manejable.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y un archivo de audio de muestra de nota de voz (se admiten formatos comunes como .m4a, .mp3, .wav).
Manejo de archivos de audio: El script enfatiza que las notas de voz típicamente están muy por debajo del límite de 25MB de la API. Abre el archivo en modo de lectura binaria ("rb").
Inicialización: Configura el cliente OpenAI.
Función de transcripción (transcribe_voice_note):
- Similar a la función de transcripción de reuniones pero adaptada para notas de voz.
- Valores predeterminados: Establece language como None (detección automática) y prompt como None, ya que estos suelen ser suficientes para notas de voz típicas donde la jerga específica puede ser menos común. El usuario aún puede proporcionarlos si es necesario.
- Llamada a la API: Utiliza client.audio.transcriptions.create con model="whisper-1".
- response_format="text": Solicita explícitamente la salida en texto plano, que es el formato más práctico para notas – fácil de leer, buscar, copiar y compartir.
- Manejo de errores: Incluye bloques estándar try...except para errores de API y archivo.
Salida y utilidad:
- Imprime la transcripción de texto resultante.
- Conecta explícitamente la salida con los beneficios mencionados en la descripción del caso de uso: crear recordatorios/tareas pendientes, capturar ideas, documentar observaciones, permitir búsquedas y compartir.
- Incluye un paso opcional para guardar la nota transcrita en un archivo .txt.

Este ejemplo proporciona una implementación clara y práctica para convertir notas de voz a texto usando Whisper, destacando su conveniencia para capturar información en movimiento. Recuerda usar un archivo de audio real de nota de voz para las pruebas y actualizar la variable audio_file_path según corresponda.

Traducción de voz multilingüe

Elimina las barreras lingüísticas proporcionando traducciones precisas mientras preserva el contexto y significado original. Esta potente característica permite:

Comunicación en tiempo real superando barreras lingüísticas en reuniones y conferencias internacionales
Traducción de contenido educativo para audiencias globales manteniendo la integridad académica
Negociaciones comerciales interculturales con traducción precisa de términos técnicos y matices culturales
Traducción de documentación para organizaciones multinacionales con terminología consistente

El sistema puede detectar el idioma de origen automáticamente y proporciona traducciones que mantienen el tono original del hablante, la intención y el contexto profesional, haciéndolo invaluable para la colaboración global.

Ejemplo:

Este ejemplo toma un archivo de audio que contiene habla en un idioma distinto del inglés y lo traduce directamente a texto en inglés.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/spanish_speech.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Denver, Colorado, United States"
print(f"Running Whisper speech translation example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local non-English audio file
# IMPORTANT: Replace 'spanish_speech.mp3' with the actual filename.
audio_file_path = "spanish_speech.mp3"

# --- Optional Parameters ---
# Prompt can help guide recognition of specific names/terms in the SOURCE language
# before translation, potentially improving accuracy of the final English text.
translation_prompt = None # Example: "The discussion mentions La Sagrada Familia and Parc Güell."

# --- Function to Translate Speech to English ---
def translate_speech_to_english(client, file_path, prompt=None):
    """
    Translates speech from the given audio file into English using the Whisper API.
    The source language is automatically detected.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (non-English speech).
        prompt (str, optional): A text prompt to guide source language recognition. Defaults to None.

    Returns:
        str: The translated English text, or None if an error occurs.
    """
    print(f"\nAttempting to translate speech from audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Translation may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for translation to English...")

            # --- Make the API Call for Translation ---
            # Note: Using the 'translations' endpoint, not 'transcriptions'
            response = client.audio.translations.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text English output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the translated string
            translated_text = response
            print("Translation successful.")
            return translated_text

    except OpenAIError as e:
        print(f"OpenAI API Error during translation: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        # Whisper might error if it cannot detect speech or supported language
        elif "language could not be detected" in str(e).lower():
             print("Hint: Ensure the audio contains detectable speech in a supported language.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during translation: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    english_translation = translate_speech_to_english(
        client,
        audio_file_path,
        prompt=translation_prompt
    )

    if english_translation:
        print("\n--- Translated English Text ---")
        print(english_translation)
        print("-------------------------------\n")

        # How this helps the use case:
        print("This English translation enables:")
        print("- Understanding discussions from international meetings.")
        print("- Making educational content accessible to English-speaking audiences.")
        print("- Facilitating cross-cultural business communication.")
        print("- Creating English versions of documentation originally recorded in other languages.")
        print("- Quick communication across language barriers using voice input.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_translation_en.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(english_translation)
            print(f"Translation saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving translation to file: {e}")

    else:
        print("\nSpeech translation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la capacidad de la API de Whisper para realizar traducción de voz a texto, específicamente traduciendo audio de varios idiomas de origen directamente a texto en inglés. Esto aborda la necesidad de eliminar las barreras lingüísticas en escenarios de comunicación global.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y, fundamentalmente, un archivo de audio de muestra que contenga voz en un idioma que no sea inglés (por ejemplo, español, francés, alemán).
Punto final de API clave: Este ejemplo utiliza client.audio.translations.create, que es distinto del punto final transcriptions usado anteriormente. El punto final de translations está específicamente diseñado para generar texto en inglés.
Detección automática de idioma: Una característica clave destacada es que no es necesario especificar el idioma de origen del archivo de audio; Whisper lo detecta automáticamente antes de traducir al inglés.
Inicialización: Configura el cliente OpenAI.
Función de traducción (translate_speech_to_english):
- Toma el client, file_path, y un prompt opcional.
- Abre el archivo de audio no inglés en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.translations.create con:
  - model="whisper-1": El modelo estándar de Whisper.
  - file=audio_file: El objeto del archivo de audio.
  - prompt: Opcionalmente proporciona contexto (en el idioma de origen o inglés, frecuentemente ayuda con nombres/términos) para ayudar al reconocimiento preciso antes de la traducción, ayudando a preservar matices y términos técnicos.
  - response_format="text": Solicita salida de texto en inglés simple.
- Manejo de errores: Incluye bloques try...except, señalando posibles errores si no se detecta voz o un idioma compatible en el audio.
Salida y utilidad:
- Imprime el texto traducido al inglés resultante.
- Conecta explícitamente esta salida con los beneficios descritos en el caso de uso: permitir la comprensión en reuniones internacionales, traducir contenido educativo/empresarial para audiencias globales y facilitar la documentación y comunicación entre idiomas.
- Muestra cómo guardar opcionalmente la traducción al inglés en un archivo .txt.

Este ejemplo demuestra efectivamente la potente función de traducción de Whisper, haciéndolo invaluable para escenarios que requieren comunicación o comprensión de contenido entre diferentes idiomas. Recuerda usar un archivo de audio con voz que no esté en inglés para las pruebas y actualizar el audio_file_path según corresponda.

Herramientas de accesibilidad

Permite una mejor inclusión digital al proporcionar servicios de transcripción en tiempo real para usuarios con discapacidad auditiva, ofreciendo varios beneficios clave:

Permite a las personas sordas y con dificultades auditivas participar plenamente en contenido basado en audio
Proporciona acceso instantáneo a información hablada en entornos profesionales como reuniones y conferencias
Apoya entornos educativos haciendo accesibles las clases y discusiones para todos los estudiantes
Mejora el consumo de medios al permitir subtitulado preciso en tiempo real para videos y transmisiones en vivo

Ejemplo:

Este ejemplo se centra en utilizar el formato de salida verbose_json para obtener marcas de tiempo a nivel de segmento, que son esenciales para sincronizar texto con audio o video.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/lecture_snippet.mp3

import os
import json # To potentially parse the verbose_json output nicely
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Atlanta, Georgia, United States" # User location context
print(f"Running Whisper accessibility transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'lecture_snippet.mp3' with the actual filename.
audio_file_path = "lecture_snippet.mp3"

# --- Optional Parameters ---
# Specifying language is often good for accuracy in accessibility contexts
known_language = "en"

# Prompt can help with specific terminology in lectures or meetings
transcription_prompt = "The lecture discusses quantum entanglement, superposition, and Bell's theorem." # Set to None if not needed

# --- Function to Transcribe Audio with Timestamps ---
def transcribe_for_accessibility(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper, requesting timestamped output
    suitable for accessibility applications (e.g., captioning).

    Note on 'Real-time': This function processes a complete file. True real-time
    captioning requires capturing audio in chunks, sending each chunk to the API
    quickly, and displaying the results sequentially. This example generates the
    *type* of data needed for such applications from a pre-recorded file.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        dict: The parsed verbose_json response containing text and segments
              with timestamps, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe for accessibility: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for timestamped transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                # Request detailed JSON output including timestamps
                response_format="verbose_json",
                # Explicitly request segment-level timestamps
                timestamp_granularities=["segment"]
            )

            # The response object is already a Pydantic model behaving like a dict
            timestamped_data = response
            print("Timestamped transcription successful.")
            # You can access response.text, response.segments etc directly
            return timestamped_data

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Function to Format Timestamps ---
def format_timestamp(seconds):
    """Converts seconds to HH:MM:SS.fff format."""
    td = datetime.timedelta(seconds=seconds)
    total_milliseconds = int(td.total_seconds() * 1000)
    hours, remainder = divmod(total_milliseconds, 3600000)
    minutes, remainder = divmod(remainder, 60000)
    seconds, milliseconds = divmod(remainder, 1000)
    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"

# --- Main Execution ---
if __name__ == "__main__":
    transcription_data = transcribe_for_accessibility(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription_data:
        print("\n--- Full Transcription Text ---")
        # Access the full text directly from the response object
        print(transcription_data.text)
        print("-------------------------------\n")

        print("--- Transcription Segments with Timestamps ---")
        # Iterate through segments for timestamped data
        for segment in transcription_data.segments:
            start_time = format_timestamp(segment['start'])
            end_time = format_timestamp(segment['end'])
            segment_text = segment['text']
            print(f"[{start_time} --> {end_time}] {segment_text}")
        print("---------------------------------------------\n")

        # How this helps the use case:
        print("This timestamped data enables:")
        print("- Displaying captions synchronized with video or audio streams.")
        print("- Highlighting text in real-time as it's spoken in meetings or lectures.")
        print("- Creating accessible versions of educational/media content.")
        print("- Allowing users to navigate audio by clicking on text segments.")
        print("- Fuller participation for hearing-impaired individuals.")

        # Optional: Save the detailed JSON output
        output_json_file = os.path.splitext(audio_file_path)[0] + "_timestamps.json"
        try:
            # The response object can be converted to dict for JSON serialization
            with open(output_json_file, "w", encoding="utf-8") as f:
                 # Use .model_dump_json() for Pydantic V2 models from openai>=1.0.0
                 # or .dict() for older versions/models
                 try:
                      f.write(transcription_data.model_dump_json(indent=2))
                 except AttributeError:
                      # Fallback for older versions or different object types
                      import json
                      f.write(json.dumps(transcription_data, default=lambda o: o.__dict__, indent=2))

            print(f"Detailed timestamp data saved to '{output_json_file}'")
        except (IOError, TypeError, AttributeError) as e:
            print(f"Error saving timestamp data to JSON file: {e}")

    else:
        print("\nTranscription for accessibility failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para generar transcripciones altamente precisas con marcas de tiempo a nivel de segmento. Esta salida es crucial para aplicaciones de accesibilidad, permitiendo funciones como subtitulado en tiempo real, resaltado sincronizado de texto y transcripciones navegables para usuarios con dificultades auditivas.
Requisitos previos: Configuración estándar (openai, python-dotenv, clave API) y un archivo de audio (lecture_snippet.mp3).
Parámetros clave de la API:
- Endpoint: Utiliza client.audio.transcriptions.create.
- response_format="verbose_json": Esto es esencial. Solicita un objeto JSON detallado que contiene no solo el texto completo de la transcripción sino también una lista de segmentos, cada uno con tiempos de inicio/fin y el texto correspondiente.
- timestamp_granularities=["segment"]: Solicita explícitamente información de tiempo a nivel de segmento (aunque suele incluirse por defecto con verbose_json). Las marcas de tiempo a nivel de palabra también pueden solicitarse si es necesario (["word"]), pero los segmentos se utilizan típicamente para el subtitulado.
- language / prompt: Especificar el idioma (en) y proporcionar un prompt puede mejorar la precisión, lo cual es vital para la accesibilidad.
Consideración sobre "Tiempo Real": La explicación aclara que si bien este código procesa un archivo, la salida con marcas de tiempo que genera es lo que se necesita para aplicaciones en tiempo real. El subtitulado verdaderamente en vivo requeriría enviar fragmentos de audio a la API rápidamente.
Inicialización y Función (transcribe_for_accessibility): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando verbose_json.
Procesamiento de Salida:
- El código primero imprime el texto concatenado completo (transcription_data.text).
- Luego itera a través de la lista transcription_data.segments.
- Para cada segment, extrae el tiempo de start, tiempo de end, y text.
- Una función auxiliar (format_timestamp) convierte los tiempos (en segundos) a un formato estándar HH:MM:SS.fff.
- Imprime cada segmento con su información de tiempo (por ejemplo, [00:00:01.234 --> 00:00:05.678] Este es el texto del primer segmento.).
Relevancia del Caso de Uso: La salida muestra claramente cómo estos datos con marcas de tiempo permiten directamente los beneficios descritos: sincronización de texto con audio/video para subtítulos, permitiendo la participación en reuniones/conferencias, haciendo el contenido educativo accesible y mejorando el consumo de medios.
Guardado de Salida: Incluye una opción para guardar la respuesta completa verbose_json en un archivo para uso posterior o procesamiento más complejo. Maneja las posibles diferencias en la serialización del objeto de respuesta de la biblioteca openai.

Este ejemplo demuestra efectivamente cómo obtener los datos necesarios con marcas de tiempo de Whisper para impulsar varias funciones de accesibilidad, haciendo el contenido de audio más inclusivo. Recuerda usar un archivo de audio relevante para las pruebas.

Flujos de trabajo de subtitulado de video

Agiliza la creación de subtítulos precisos para contenido de video, admitiendo múltiples formatos de salida incluyendo SRT, WebVTT y otros formatos estándar de la industria. Esta capacidad es esencial para:

Creadores de contenido que necesitan hacer sus videos accesibles en múltiples plataformas
Empresas de radiodifusión que requieren subtítulos cerrados precisos para cumplimiento regulatorio
Instituciones educativas que crean contenido de video accesible para poblaciones estudiantiles diversas
Gestores de redes sociales que desean aumentar el engagement de videos mediante subtitulado automático

El sistema puede detectar automáticamente cambios de hablante, manejar la sincronización de tiempos y formatear subtítulos según las mejores prácticas de la industria, convirtiéndolo en una herramienta invaluable para flujos de trabajo de producción de video profesional.

Ejemplo:

Este ejemplo de código toma un archivo de audio (que típicamente extraerías primero de tu video) y usa Whisper para crear subtítulos con marcas de tiempo precisas en el formato estándar .srt.

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/video_audio.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Austin, Texas, United States" # User location context
print(f"Running Whisper caption generation (SRT) example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file (extracted from video)
# IMPORTANT: Replace 'video_audio.mp3' with the actual filename.
audio_file_path = "video_audio.mp3"

# --- Optional Parameters ---
# Specifying language can improve caption accuracy
known_language = "en"

# Prompt can help with names, brands, or specific terminology in the video
transcription_prompt = "The video features interviews with Dr. Anya Sharma about sustainable agriculture and mentions the company 'TerraGrow'." # Set to None if not needed

# --- Function to Generate SRT Captions ---
def generate_captions_srt(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper and returns captions in SRT format.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (extracted from video).
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The caption data in SRT format string, or None if an error occurs.
    """
    print(f"\nAttempting to generate SRT captions for: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for SRT caption generation...")

            # --- Make the API Call for Transcription ---
            # Request 'srt' format directly
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                response_format="srt" # Request SRT format output
                # Other options include "vtt"
            )

            # The response object for "srt" format is directly the SRT string
            srt_content = response
            print("SRT caption generation successful.")
            return srt_content

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    srt_captions = generate_captions_srt(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if srt_captions:
        # --- Save the SRT Content to a File ---
        output_srt_file = os.path.splitext(audio_file_path)[0] + ".srt"
        try:
            with open(output_srt_file, "w", encoding="utf-8") as f:
                f.write(srt_captions)
            print(f"\nSRT captions saved successfully to '{output_srt_file}'")

            # How this helps the use case:
            print("\nThis SRT file can be used to:")
            print("- Add closed captions or subtitles to video players (like YouTube, Vimeo, VLC).")
            print("- Import into video editing software for caption integration.")
            print("- Meet accessibility requirements and regulatory compliance (e.g., broadcasting).")
            print("- Improve video engagement on social media platforms.")
            print("- Make educational video content accessible to more students.")

        except IOError as e:
            print(f"Error saving SRT captions to file: {e}")

    else:
        print("\nSRT caption generation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra cómo usar la API de Whisper para agilizar los flujos de trabajo de subtitulado de video mediante la generación directa de archivos de subtítulos SRT (SubRip Text) en formato estándar de la industria a partir del audio.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv y la clave API. Es crucial que requiera un archivo de audio que se haya extraído del video objetivo. El script incluye una nota que explica este paso necesario de preprocesamiento.
Parámetro clave de API (response_format="srt"):
- El núcleo de este caso de uso es solicitar el formato srt directamente desde el endpoint client.audio.transcriptions.create.
- Esto indica a Whisper que formatee la salida según las especificaciones SRT, incluyendo numeración secuencial, marcas de tiempo de inicio/fin (por ejemplo, 00:00:20,000 --> 00:00:24,400), y el fragmento de texto correspondiente. La API maneja la sincronización de tiempos automáticamente. vtt (WebVTT) es otro formato común que se puede solicitar de manera similar.
Inicialización y Función (generate_captions_srt): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando específicamente el formato SRT. Los parámetros opcionales language y prompt pueden usarse para mejorar la precisión.
Manejo de Salida:
- La response de la llamada a la API (cuando response_format="srt") es directamente el contenido completo del archivo SRT como una única cadena de texto.
- El código luego guarda esta cadena directamente en un archivo con la extensión .srt.
Relevancia para el Caso de Uso:
- La explicación destaca cómo este archivo .srt generado sirve directamente a las necesidades de creadores de contenido, emisoras, educadores y gestores de redes sociales.
- Puede cargarse fácilmente en plataformas de video, importarse a software de edición o usarse para cumplir con estándares de accesibilidad y normativas. Simplifica significativamente el proceso tradicionalmente laborioso de creación manual de subtítulos.
Manejo de Errores: Incluye verificaciones estándar para errores de API y del sistema de archivos.

Este ejemplo proporciona una demostración altamente práctica del uso de Whisper para una tarea común de producción de video, mostrando cómo obtener subtítulos con marcas de tiempo precisas en un formato listo para usar. Recuerda que el primer paso esencial es extraer el audio del video que deseas subtitular.

💡 Consejo: Whisper funciona mejor cuando el audio es claro y admite archivos de entrada de hasta 25MB por solicitud.

2.2.2 Formatos de Respuesta que Puedes Usar

Ya sea que estés construyendo un servicio de transcripción simple o desarrollando un sistema complejo de subtitulado de video, entender estos formatos es crucial para implementar Whisper eficazmente en tus aplicaciones.

La flexibilidad de los formatos de respuesta de Whisper permite a los desarrolladores integrar sin problemas capacidades de transcripción y traducción en diferentes tipos de aplicaciones, desde salida de texto básica hasta canales de procesamiento más sofisticados basados en JSON. Cada formato sirve propósitos distintos y ofrece ventajas únicas según tu caso de uso.

Whisper admite múltiples formatos para tus necesidades:

2.2.3 Aplicaciones Prácticas de Whisper

La versatilidad de Whisper se extiende mucho más allá de la transcripción básica, ofreciendo numerosas aplicaciones prácticas en diferentes industrias y casos de uso. Desde la optimización de operaciones empresariales hasta la mejora de experiencias educativas, las capacidades de Whisper pueden aprovecharse de formas innovadoras para resolver desafíos del mundo real. Exploremos algunas de las aplicaciones más impactantes de esta tecnología y entendamos cómo pueden beneficiar a diferentes grupos de usuarios.

Estas aplicaciones demuestran cómo Whisper puede integrarse en varios flujos de trabajo para mejorar la eficiencia, accesibilidad y comunicación en diferentes sectores. Cada caso de uso muestra ventajas únicas e implementaciones potenciales que pueden transformar la manera en que manejamos el contenido de audio en contextos profesionales y personales.

Herramientas para Toma de Notas

Transforma contenido hablado en texto escrito automáticamente mediante el reconocimiento avanzado del habla, permitiendo una documentación rápida y precisa de las comunicaciones verbales. Esta tecnología sobresale en la captura de patrones naturales del habla, terminología técnica e interacciones entre múltiples hablantes, facilitando la documentación y revisión de clases, entrevistas y reuniones. El proceso de transcripción automatizada mantiene el contexto y la atribución del hablante mientras convierte el audio en formatos de texto fácilmente buscables y editables.

Esta herramienta es particularmente valiosa para:

Estudiantes que capturan notas detalladas de clase mientras mantienen su participación en las discusiones
Periodistas que documentan entrevistas y conferencias de prensa con citas precisas
Profesionales de negocios que mantienen registros exactos de reuniones con clientes y sesiones de lluvia de ideas en equipo
Investigadores que realizan y transcriben entrevistas cualitativas

Las notas automatizadas pueden mejorarse aún más con funciones como marcadores de tiempo, identificación de hablantes y resaltado de palabras clave, facilitando la navegación y referencia posterior a partes específicas de la discusión. Esto mejora dramáticamente la productividad al eliminar la necesidad de transcripción manual mientras asegura una documentación exhaustiva de conversaciones importantes.

Aplicaciones Multilingües
Permite la comunicación fluida a través de barreras lingüísticas mediante la conversión de palabras habladas de un idioma a otro en tiempo real. Esta potente capacidad permite la traducción instantánea de contenido hablado, compatible con más de 100 idiomas con alta precisión. El sistema puede detectar el idioma automáticamente y manejar varios acentos y dialectos, siendo particularmente valioso para:

Negocios Internacionales: Facilita la comunicación en tiempo real en reuniones multinacionales, negociaciones y presentaciones sin necesidad de intérpretes humanos
Viajes y Turismo: Permite a los viajeros comunicarse efectivamente con los locales, entender anuncios y navegar en entornos extranjeros
Educación Global: Apoya programas de aprendizaje a distancia e intercambios estudiantiles internacionales al eliminar las barreras del idioma
Servicio al Cliente: Permite a los equipos de soporte asistir a los clientes en su idioma preferido, mejorando la calidad del servicio y la satisfacción

La tecnología funciona en diferentes entornos de audio y puede manejar múltiples hablantes, haciéndola ideal para reuniones internacionales de negocios, aplicaciones de viaje, plataformas de comunicación global e intercambios interculturales.

Soluciones de Accesibilidad

Crea subtítulos y transcripciones en tiempo real para personas con discapacidad auditiva, asegurando un acceso equitativo al contenido de audio. Esta tecnología esencial sirve para múltiples propósitos de accesibilidad:

Subtitulado en Tiempo Real: Proporciona representación textual inmediata de palabras habladas durante eventos en vivo, reuniones y presentaciones
Transcripción Precisa: Genera registros escritos detallados del contenido de audio para referencia y estudio posterior
Soporte Multi-formato: Ofrece contenido en varios formatos incluyendo subtítulos cerrados, subtítulos y transcripciones descargables

Esta tecnología puede integrarse en:

Plataformas de Videoconferencia: Habilitando subtítulos en tiempo real durante reuniones virtuales y seminarios web
Plataformas Educativas: Apoyando a estudiantes con discapacidad auditiva tanto en entornos en línea como en aulas tradicionales
Reproductores Multimedia: Proporcionando subtítulos sincronizados para videos, podcasts y otros contenidos multimedia
Eventos en Vivo: Ofreciendo pantallas de texto en tiempo real durante conferencias, actuaciones y eventos de oratoria pública

Estas características de accesibilidad no solo apoyan a personas con discapacidad auditiva, sino que también benefician a:

Hablantes no nativos que prefieren leer mientras escuchan
Personas en entornos sensibles al sonido donde el audio no es práctico
Personas con aprendizaje visual que procesan mejor la información a través del texto
Organizaciones que buscan cumplir con regulaciones y estándares de accesibilidad

Mejora de Podcasts
Convierte contenido de audio en formatos de texto buscables mediante transcripción integral, permitiendo múltiples beneficios:

Descubrimiento de Contenido: Los oyentes pueden buscar fácilmente en las transcripciones de episodios para encontrar temas específicos, citas o discusiones de interés
Reutilización de Contenido: Los creadores pueden extraer citas clave y perspectivas para redes sociales, publicaciones de blog o boletines
Accesibilidad: Hace que el contenido esté disponible para audiencias con discapacidad auditiva y aquellos que prefieren leer
Beneficios SEO: Los motores de búsqueda pueden indexar el contenido completo de los episodios, mejorando la visibilidad y el tráfico orgánico
Participación Mejorada: Los lectores pueden explorar el contenido antes de escuchar, marcar secciones importantes y consultar material posteriormente
Perspectivas Analíticas: Analiza los términos más buscados y segmentos populares para informar la estrategia de contenido futura

Apoyo al Aprendizaje de Idiomas
Proporciona retroalimentación inmediata a los estudiantes de idiomas convirtiendo su práctica hablada en texto, permitiéndoles verificar pronunciación, gramática y uso de vocabulario. Esta tecnología crea una experiencia de aprendizaje interactiva y efectiva a través de varios mecanismos clave:

Retroalimentación de Pronunciación en Tiempo Real: Los estudiantes pueden comparar sus palabras habladas con el texto transcrito para identificar errores de pronunciación y áreas de mejora
Análisis Gramatical: El sistema puede resaltar estructuras gramaticales y posibles errores en el texto transcrito, ayudando a los estudiantes a entender sus errores
Mejora de Vocabulario: Los estudiantes pueden hacer seguimiento de su uso activo del vocabulario y recibir sugerencias para elecciones de palabras más variadas

La tecnología beneficia particularmente a:

Estudiantes autodidactas que practican independientemente
Profesores de idiomas que dan seguimiento al progreso de los estudiantes
Plataformas de aprendizaje de idiomas en línea que ofrecen práctica de habla
Participantes de intercambio de idiomas que desean verificar su comunicación

Cuando se integra con aplicaciones de aprendizaje de idiomas, esta función puede proporcionar sesiones de práctica estructuradas, seguimiento del progreso y retroalimentación personalizada que ayuda a los estudiantes a desarrollar confianza en sus habilidades de habla.

Ejemplo:

Este ejemplo toma un archivo de audio de un estudiante hablando un idioma objetivo específico y lo transcribe, proporcionando el texto de salida esencial necesario para la comparación de pronunciación, análisis gramatical o revisión de vocabulario.

Descarga el archivo de audio de muestra aquí: https://files.cuantum.tech/audio/language_practice_fr.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Orlando, Florida, United States" # User location context
print(f"Running Whisper language learning transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# --- Language Learning Specific Configuration ---

# Define the path to the language practice audio file
# IMPORTANT: Replace 'language_practice_fr.mp3' with the actual filename.
audio_file_path = "language_practice_fr.mp3"

# ** CRUCIAL: Specify the language being spoken in the audio file **
# Use the correct ISO-639-1 code (e.g., "en", "es", "fr", "de", "ja", "zh")
# This tells Whisper how to interpret the sounds.
target_language = "fr" # Example: French

# Optional: Provide context about the practice session (e.g., the expected phrase)
# This can help improve accuracy, especially for specific vocabulary or sentences.
practice_prompt = "The student is practicing ordering food at a French cafe, mentioning croissants and coffee." # Set to None if not needed

# --- Function to Transcribe Language Practice Audio ---
def transcribe_language_practice(client, file_path, language, prompt=None):
    """
    Transcribes audio of language practice using the Whisper API.
    Specifying the target language is crucial for this use case.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The ISO-639-1 code of the language being spoken.
        prompt (str, optional): A text prompt providing context. Defaults to None.

    Returns:
        str: The transcribed text in the target language, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe language practice ({language}) from: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    if not language:
        print("Error: Target language must be specified for language learning transcription.")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print(f"Sending audio ({language}) to Whisper API for transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language, # Pass the specified target language
                prompt=prompt,
                response_format="text" # Get plain text for easy comparison/analysis
            )

            # The response object for "text" format is directly the string
            practice_transcription = response
            print("Transcription successful.")
            return practice_transcription

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        elif "invalid language code" in str(e).lower():
             print(f"Hint: Check if '{language}' is a valid ISO-639-1 language code supported by Whisper.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_text = transcribe_language_practice(
        client,
        audio_file_path,
        language=target_language,
        prompt=practice_prompt
    )

    if transcribed_text:
        print("\n--- Transcribed Practice Text ---")
        print(f"(Language: {target_language})")
        print(transcribed_text)
        print("---------------------------------\n")

        # How this helps the use case:
        print("This transcription provides the basis for language learning feedback:")
        print("- **Pronunciation Check:** Learner compares their speech to the text, identifying discrepancies.")
        print("- **Grammar/Vocabulary Analysis:** This text can be compared against expected sentences or analyzed (potentially by another AI like GPT-4o, or specific tools) for grammatical correctness and vocabulary usage.")
        print("- **Progress Tracking:** Teachers or platforms can store transcriptions to monitor improvement over time.")
        print("- **Self-Correction:** Learners get immediate textual representation of their speech for review.")
        print("\nNote: Further analysis (grammar checking, pronunciation scoring, etc.) requires additional logic beyond this transcription step.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_text)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nLanguage practice transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper como herramienta de apoyo para el aprendizaje de idiomas. Transcribe grabaciones de audio de un estudiante hablando un idioma objetivo, proporcionando el texto de salida esencial necesario para varios mecanismos de retroalimentación.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API, y un archivo de audio que contenga la práctica hablada del estudiante en el idioma objetivo (por ejemplo, language_practice_fr.mp3).
Parámetro clave (language):
- A diferencia de la transcripción general donde la detección automática podría ser suficiente, para el aprendizaje de idiomas, especificar explícitamente el language que el estudiante está intentando hablar es crucial. Esto se establece usando la variable target_language (por ejemplo, "fr" para francés).
- Esto asegura que Whisper interprete el audio usando el modelo fonético y de vocabulario correcto, proporcionando una transcripción más precisa para la retroalimentación.
Prompt opcional: El parámetro prompt puede usarse para dar contexto a Whisper sobre la sesión de práctica (por ejemplo, la frase específica que se está practicando), lo que puede mejorar la precisión del reconocimiento.
Inicialización y Función (transcribe_language_practice): Configuración estándar del cliente. La función requiere el parámetro language y realiza la transcripción usando client.audio.transcriptions.create.
Salida (response_format="text"): Se solicita la salida en texto plano ya que es el formato más directo para que los estudiantes o sistemas comparen con el texto esperado, analicen la gramática o revisen el vocabulario.
Mecanismo de Retroalimentación (Nota Importante): La explicación establece claramente que este script solo proporciona la transcripción. La retroalimentación real (puntuación de pronunciación, corrección gramatical, sugerencias de vocabulario) requiere procesamiento adicional. Este texto transcrito sirve como entrada para esos pasos de análisis posteriores, que podrían involucrar verificaciones basadas en reglas, algoritmos de comparación, o incluso alimentar el texto a otro LLM como GPT-4o para su análisis.
Relevancia del Caso de Uso: La sección de salida explica cómo esta transcripción permite los beneficios descritos: permitiendo a los estudiantes verificar su pronunciación contra el texto, proporcionando material para análisis de gramática/vocabulario, facilitando el seguimiento del progreso y apoyando la autocorrección.

Este ejemplo proporciona un punto de partida práctico para integrar Whisper en aplicaciones de aprendizaje de idiomas, centrándose en generar los datos textuales básicos necesarios para bucles de retroalimentación efectivos. Recuerda usar un archivo de audio de alguien hablando el target_language especificado para las pruebas.

Resumen

En esta sección, aprendiste varios aspectos clave del procesamiento y comprensión de audio:

Transcribir lenguaje hablado a texto usando Whisper
- Convertir varios formatos de audio en transcripciones de texto precisas
- Manejar múltiples idiomas y acentos con alta precisión
- Procesar efectivamente tanto clips cortos como grabaciones largas
Traducir audio en idioma extranjero al inglés
- Convertir habla no inglesa directamente a texto en inglés
- Mantener el contexto y significado a través de las barreras del idioma
- Soportar procesamiento de contenido multilingüe
Elegir entre salidas de texto plano, JSON y subtítulos
- Seleccionar el formato más apropiado para tu caso de uso específico
- Generar subtítulos con marcas de tiempo precisas
- Estructurar datos en formato JSON legible por máquina
Aplicar estas herramientas en casos de uso del mundo real como accesibilidad, educación y creación de contenido
- Crear contenido accesible con transcripciones precisas
- Apoyar el aprendizaje de idiomas e iniciativas educativas
- Optimizar flujos de trabajo de producción de contenido

Whisper es increíblemente rápido, fácil de usar y funciona en varios idiomas, lo que lo convierte en una de las herramientas más valiosas en el ecosistema de OpenAI. Su versatilidad y precisión lo hacen adecuado tanto para usuarios individuales como para aplicaciones a escala empresarial, mientras que su naturaleza de código abierto permite implementaciones y modificaciones personalizadas para satisfacer necesidades específicas.

2.2 Transcripción y Traducción con la API de Whisper

2.2.1 ¿Qué es Whisper?

Whisper demuestra una versatilidad excepcional a través de numerosas aplicaciones:

Transcripciones de reuniones o podcasts

Archivar reuniones importantes para consultas futuras
Crear versiones accesibles de contenido de audio
Permitir búsquedas rápidas a través de horas de contenido grabado
Generar documentación escrita a partir de discusiones verbales
Apoyar requisitos de cumplimiento para el mantenimiento de registros

La alta tasa de precisión asegura que los términos técnicos, nombres propios y discusiones complejas se capturen correctamente mientras se mantiene el flujo natural de la conversación.

Ejemplo:

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/meeting_snippet.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt
current_location = "Houston, Texas, United States"
print(f"Running Whisper transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'meeting_snippet.mp3' with the actual filename.
audio_file_path = "meeting_snippet.mp3"

# --- Optional Parameters for potentially better accuracy ---
# Specify language (ISO-639-1 code) if known, otherwise Whisper auto-detects.
# Example: "en" for English, "es" for Spanish, "de" for German
known_language = "en" # Set to None to auto-detect

# Provide a prompt with context, names, or jargon expected in the audio.
# This helps Whisper recognize specific terms accurately.
transcription_prompt = "The discussion involves Project Phoenix, stakeholders like Dr. Evelyn Reed and ACME Corp, and technical terms such as multi-threaded processing and cloud-native architecture." # Set to None if no prompt needed

# --- Function to Transcribe Audio ---
def transcribe_audio(client, file_path, language=None, prompt=None):
    """
    Transcribes the given audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Check file size (optional but good practice)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            print("Consider splitting the file into smaller chunks.")
            # You might choose to exit here or attempt anyway
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        return None


    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Optional: Specify language
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the string
            transcription_text = response
            print("Transcription successful.")
            return transcription_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        # Provide hints for common errors
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (mp3, mp4, mpeg, mpga, m4a, wav, webm).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit. Please split the file.")
        return None
    except FileNotFoundError: # Already handled above, but good practice
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcription = transcribe_audio(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription:
        print("\n--- Transcription Result ---")
        print(transcription)
        print("----------------------------\n")

        # How this helps the use case:
        print("This plain text transcription can now be:")
        print("- Saved as a text document (.txt) for archiving.")
        print("- Indexed and searched easily for specific keywords or names.")
        print("- Used to generate meeting minutes or documentation.")
        print("- Copied into accessibility tools or documents.")
        print("- Stored for compliance record-keeping.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcription)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nTranscription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la transcripción de archivos de audio como grabaciones de reuniones o episodios de podcast utilizando la API Whisper de OpenAI. El objetivo es convertir el contenido hablado en texto preciso y consultable, atendiendo necesidades como el archivo, la accesibilidad y la documentación.
Requisitos previos: Requiere las bibliotecas openai y python-dotenv, una clave API de OpenAI configurada en un archivo .env, y un archivo de audio de muestra (meeting_snippet.mp3).
Requisitos del archivo de audio: El script destaca los formatos de audio compatibles (MP3, WAV, M4A, etc.) y el límite crucial de 25MB por solicitud de API. Incluye una advertencia y explicación de que los archivos más largos deben segmentarse antes del procesamiento, aunque el código en sí maneja un solo archivo dentro del límite.
Inicialización: Configura el cliente estándar OpenAI utilizando la clave API.
Función de transcripción (transcribe_audio):
- Toma los argumentos client, file_path, y los opcionales language y prompt.
- Incluye una verificación de existencia y tamaño del archivo.
- Abre el archivo de audio en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.transcriptions.create con:
  - model="whisper-1": Especifica el modelo conocido por su alta precisión.
  - file=audio_file: Pasa el objeto de archivo abierto.
  - language: Opcionalmente proporciona el código de idioma (por ejemplo, "en") para potencialmente mejorar la precisión si se conoce el idioma. Si es None, Whisper detecta automáticamente.
  - prompt: Opcionalmente proporciona palabras clave contextuales, nombres (como "Project Phoenix", "Dr. Evelyn Reed"), o jerga. Esto ayuda significativamente a Whisper a transcribir con precisión términos especializados que se encuentran frecuentemente en reuniones o podcasts técnicos, abordando directamente la necesidad de capturar correctamente discusiones complejas.
  - response_format="text": Solicita la salida directamente como una cadena de texto plano, ideal para uso inmediato en documentos, indexación de búsqueda, etc. Se podrían solicitar otros formatos como verbose_json (para marcas de tiempo) o srt/vtt (para subtítulos) si fuera necesario.
- Manejo de errores: Incluye bloques try...except para errores de API (proporcionando sugerencias para problemas comunes como tamaño o formato de archivo) y errores del sistema de archivos.
Salida y utilidad:
- Se imprime el texto de transcripción resultante.
- El código conecta explícitamente esta salida con los beneficios del caso de uso: crear archivos consultables, generar documentación, apoyar la accesibilidad y permitir el cumplimiento normativo.
- Incluye un paso opcional para guardar la transcripción directamente en un archivo .txt.

Conversión de notas de voz

Transforma los mensajes de voz rápidos en notas de texto organizadas, facilitando la revisión y el archivo de pensamientos hablados. Esta funcionalidad es particularmente valiosa para:

Crear recordatorios rápidos y listas de tareas mientras se está en movimiento
Capturar ideas creativas o sesiones de lluvia de ideas sin interrumpir el flujo de pensamiento
Tomar notas durante trabajo de campo o visitas al sitio donde escribir es poco práctico
Documentar observaciones o hallazgos de investigación en tiempo real

El sistema mantiene el flujo natural del habla mientras organiza el contenido en texto claro y legible que puede ser fácilmente buscado, compartido o integrado en otros documentos.

Ejemplo:

Este script se centra en tomar un archivo de audio típico de nota de voz y convertirlo en texto consultable y utilizable, ideal para capturar ideas, recordatorios o notas de campo.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/voice_memo.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Miami, Florida, United States"
print(f"Running Whisper voice note transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local voice note audio file
# IMPORTANT: Replace 'voice_memo.m4a' with the actual filename.
audio_file_path = "voice_memo.mp3"

# --- Optional Parameters (Often not needed for simple voice notes) ---
# Language auto-detection is usually sufficient for voice notes.
known_language = None # Set to "en", "es", etc. if needed

# Prompt is useful if your notes contain specific jargon/names, otherwise leave as None.
transcription_prompt = None # Example: "Remember to mention Project Chimera and the client ZetaCorp."

# --- Function to Transcribe Voice Note ---
def transcribe_voice_note(client, file_path, language=None, prompt=None):
    """
    Transcribes the given voice note audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe voice note: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size (less likely to be an issue for voice notes)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None # Decide if you want to stop for large files
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        # Continue attempt even if size check fails
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending voice note to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Defaults to None (auto-detect)
                prompt=prompt,              # Defaults to None
                response_format="text"      # Request plain text output for easy use as notes
            )

            # The response object for "text" format is directly the string
            note_text = response
            print("Transcription successful.")
            return note_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (m4a, mp3, wav, etc.).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_note = transcribe_voice_note(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcribed_note:
        print("\n--- Transcribed Voice Note Text ---")
        print(transcribed_note)
        print("-----------------------------------\n")

        # How this helps the use case:
        print("This transcribed text from your voice note can be easily:")
        print("- Copied into reminder apps or to-do lists.")
        print("- Saved as a text file for archiving creative ideas or brainstorms.")
        print("- Searched later for specific keywords or topics.")
        print("- Shared via email or messaging apps.")
        print("- Integrated into reports or documentation (e.g., field notes).")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_note)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nVoice note transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para transcribir grabaciones de audio cortas como notas de voz y memorandos. Es ideal para capturar rápidamente pensamientos, ideas, recordatorios u observaciones de campo y convertirlos en texto fácilmente manejable.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y un archivo de audio de muestra de nota de voz (se admiten formatos comunes como .m4a, .mp3, .wav).
Manejo de archivos de audio: El script enfatiza que las notas de voz típicamente están muy por debajo del límite de 25MB de la API. Abre el archivo en modo de lectura binaria ("rb").
Inicialización: Configura el cliente OpenAI.
Función de transcripción (transcribe_voice_note):
- Similar a la función de transcripción de reuniones pero adaptada para notas de voz.
- Valores predeterminados: Establece language como None (detección automática) y prompt como None, ya que estos suelen ser suficientes para notas de voz típicas donde la jerga específica puede ser menos común. El usuario aún puede proporcionarlos si es necesario.
- Llamada a la API: Utiliza client.audio.transcriptions.create con model="whisper-1".
- response_format="text": Solicita explícitamente la salida en texto plano, que es el formato más práctico para notas – fácil de leer, buscar, copiar y compartir.
- Manejo de errores: Incluye bloques estándar try...except para errores de API y archivo.
Salida y utilidad:
- Imprime la transcripción de texto resultante.
- Conecta explícitamente la salida con los beneficios mencionados en la descripción del caso de uso: crear recordatorios/tareas pendientes, capturar ideas, documentar observaciones, permitir búsquedas y compartir.
- Incluye un paso opcional para guardar la nota transcrita en un archivo .txt.

Traducción de voz multilingüe

Elimina las barreras lingüísticas proporcionando traducciones precisas mientras preserva el contexto y significado original. Esta potente característica permite:

Comunicación en tiempo real superando barreras lingüísticas en reuniones y conferencias internacionales
Traducción de contenido educativo para audiencias globales manteniendo la integridad académica
Negociaciones comerciales interculturales con traducción precisa de términos técnicos y matices culturales
Traducción de documentación para organizaciones multinacionales con terminología consistente

Ejemplo:

Este ejemplo toma un archivo de audio que contiene habla en un idioma distinto del inglés y lo traduce directamente a texto en inglés.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/spanish_speech.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Denver, Colorado, United States"
print(f"Running Whisper speech translation example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local non-English audio file
# IMPORTANT: Replace 'spanish_speech.mp3' with the actual filename.
audio_file_path = "spanish_speech.mp3"

# --- Optional Parameters ---
# Prompt can help guide recognition of specific names/terms in the SOURCE language
# before translation, potentially improving accuracy of the final English text.
translation_prompt = None # Example: "The discussion mentions La Sagrada Familia and Parc Güell."

# --- Function to Translate Speech to English ---
def translate_speech_to_english(client, file_path, prompt=None):
    """
    Translates speech from the given audio file into English using the Whisper API.
    The source language is automatically detected.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (non-English speech).
        prompt (str, optional): A text prompt to guide source language recognition. Defaults to None.

    Returns:
        str: The translated English text, or None if an error occurs.
    """
    print(f"\nAttempting to translate speech from audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Translation may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for translation to English...")

            # --- Make the API Call for Translation ---
            # Note: Using the 'translations' endpoint, not 'transcriptions'
            response = client.audio.translations.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text English output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the translated string
            translated_text = response
            print("Translation successful.")
            return translated_text

    except OpenAIError as e:
        print(f"OpenAI API Error during translation: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        # Whisper might error if it cannot detect speech or supported language
        elif "language could not be detected" in str(e).lower():
             print("Hint: Ensure the audio contains detectable speech in a supported language.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during translation: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    english_translation = translate_speech_to_english(
        client,
        audio_file_path,
        prompt=translation_prompt
    )

    if english_translation:
        print("\n--- Translated English Text ---")
        print(english_translation)
        print("-------------------------------\n")

        # How this helps the use case:
        print("This English translation enables:")
        print("- Understanding discussions from international meetings.")
        print("- Making educational content accessible to English-speaking audiences.")
        print("- Facilitating cross-cultural business communication.")
        print("- Creating English versions of documentation originally recorded in other languages.")
        print("- Quick communication across language barriers using voice input.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_translation_en.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(english_translation)
            print(f"Translation saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving translation to file: {e}")

    else:
        print("\nSpeech translation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la capacidad de la API de Whisper para realizar traducción de voz a texto, específicamente traduciendo audio de varios idiomas de origen directamente a texto en inglés. Esto aborda la necesidad de eliminar las barreras lingüísticas en escenarios de comunicación global.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y, fundamentalmente, un archivo de audio de muestra que contenga voz en un idioma que no sea inglés (por ejemplo, español, francés, alemán).
Punto final de API clave: Este ejemplo utiliza client.audio.translations.create, que es distinto del punto final transcriptions usado anteriormente. El punto final de translations está específicamente diseñado para generar texto en inglés.
Detección automática de idioma: Una característica clave destacada es que no es necesario especificar el idioma de origen del archivo de audio; Whisper lo detecta automáticamente antes de traducir al inglés.
Inicialización: Configura el cliente OpenAI.
Función de traducción (translate_speech_to_english):
- Toma el client, file_path, y un prompt opcional.
- Abre el archivo de audio no inglés en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.translations.create con:
  - model="whisper-1": El modelo estándar de Whisper.
  - file=audio_file: El objeto del archivo de audio.
  - prompt: Opcionalmente proporciona contexto (en el idioma de origen o inglés, frecuentemente ayuda con nombres/términos) para ayudar al reconocimiento preciso antes de la traducción, ayudando a preservar matices y términos técnicos.
  - response_format="text": Solicita salida de texto en inglés simple.
- Manejo de errores: Incluye bloques try...except, señalando posibles errores si no se detecta voz o un idioma compatible en el audio.
Salida y utilidad:
- Imprime el texto traducido al inglés resultante.
- Conecta explícitamente esta salida con los beneficios descritos en el caso de uso: permitir la comprensión en reuniones internacionales, traducir contenido educativo/empresarial para audiencias globales y facilitar la documentación y comunicación entre idiomas.
- Muestra cómo guardar opcionalmente la traducción al inglés en un archivo .txt.

Herramientas de accesibilidad

Permite una mejor inclusión digital al proporcionar servicios de transcripción en tiempo real para usuarios con discapacidad auditiva, ofreciendo varios beneficios clave:

Permite a las personas sordas y con dificultades auditivas participar plenamente en contenido basado en audio
Proporciona acceso instantáneo a información hablada en entornos profesionales como reuniones y conferencias
Apoya entornos educativos haciendo accesibles las clases y discusiones para todos los estudiantes
Mejora el consumo de medios al permitir subtitulado preciso en tiempo real para videos y transmisiones en vivo

Ejemplo:

Este ejemplo se centra en utilizar el formato de salida verbose_json para obtener marcas de tiempo a nivel de segmento, que son esenciales para sincronizar texto con audio o video.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/lecture_snippet.mp3

import os
import json # To potentially parse the verbose_json output nicely
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Atlanta, Georgia, United States" # User location context
print(f"Running Whisper accessibility transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'lecture_snippet.mp3' with the actual filename.
audio_file_path = "lecture_snippet.mp3"

# --- Optional Parameters ---
# Specifying language is often good for accuracy in accessibility contexts
known_language = "en"

# Prompt can help with specific terminology in lectures or meetings
transcription_prompt = "The lecture discusses quantum entanglement, superposition, and Bell's theorem." # Set to None if not needed

# --- Function to Transcribe Audio with Timestamps ---
def transcribe_for_accessibility(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper, requesting timestamped output
    suitable for accessibility applications (e.g., captioning).

    Note on 'Real-time': This function processes a complete file. True real-time
    captioning requires capturing audio in chunks, sending each chunk to the API
    quickly, and displaying the results sequentially. This example generates the
    *type* of data needed for such applications from a pre-recorded file.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        dict: The parsed verbose_json response containing text and segments
              with timestamps, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe for accessibility: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for timestamped transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                # Request detailed JSON output including timestamps
                response_format="verbose_json",
                # Explicitly request segment-level timestamps
                timestamp_granularities=["segment"]
            )

            # The response object is already a Pydantic model behaving like a dict
            timestamped_data = response
            print("Timestamped transcription successful.")
            # You can access response.text, response.segments etc directly
            return timestamped_data

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Function to Format Timestamps ---
def format_timestamp(seconds):
    """Converts seconds to HH:MM:SS.fff format."""
    td = datetime.timedelta(seconds=seconds)
    total_milliseconds = int(td.total_seconds() * 1000)
    hours, remainder = divmod(total_milliseconds, 3600000)
    minutes, remainder = divmod(remainder, 60000)
    seconds, milliseconds = divmod(remainder, 1000)
    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"

# --- Main Execution ---
if __name__ == "__main__":
    transcription_data = transcribe_for_accessibility(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription_data:
        print("\n--- Full Transcription Text ---")
        # Access the full text directly from the response object
        print(transcription_data.text)
        print("-------------------------------\n")

        print("--- Transcription Segments with Timestamps ---")
        # Iterate through segments for timestamped data
        for segment in transcription_data.segments:
            start_time = format_timestamp(segment['start'])
            end_time = format_timestamp(segment['end'])
            segment_text = segment['text']
            print(f"[{start_time} --> {end_time}] {segment_text}")
        print("---------------------------------------------\n")

        # How this helps the use case:
        print("This timestamped data enables:")
        print("- Displaying captions synchronized with video or audio streams.")
        print("- Highlighting text in real-time as it's spoken in meetings or lectures.")
        print("- Creating accessible versions of educational/media content.")
        print("- Allowing users to navigate audio by clicking on text segments.")
        print("- Fuller participation for hearing-impaired individuals.")

        # Optional: Save the detailed JSON output
        output_json_file = os.path.splitext(audio_file_path)[0] + "_timestamps.json"
        try:
            # The response object can be converted to dict for JSON serialization
            with open(output_json_file, "w", encoding="utf-8") as f:
                 # Use .model_dump_json() for Pydantic V2 models from openai>=1.0.0
                 # or .dict() for older versions/models
                 try:
                      f.write(transcription_data.model_dump_json(indent=2))
                 except AttributeError:
                      # Fallback for older versions or different object types
                      import json
                      f.write(json.dumps(transcription_data, default=lambda o: o.__dict__, indent=2))

            print(f"Detailed timestamp data saved to '{output_json_file}'")
        except (IOError, TypeError, AttributeError) as e:
            print(f"Error saving timestamp data to JSON file: {e}")

    else:
        print("\nTranscription for accessibility failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para generar transcripciones altamente precisas con marcas de tiempo a nivel de segmento. Esta salida es crucial para aplicaciones de accesibilidad, permitiendo funciones como subtitulado en tiempo real, resaltado sincronizado de texto y transcripciones navegables para usuarios con dificultades auditivas.
Requisitos previos: Configuración estándar (openai, python-dotenv, clave API) y un archivo de audio (lecture_snippet.mp3).
Parámetros clave de la API:
- Endpoint: Utiliza client.audio.transcriptions.create.
- response_format="verbose_json": Esto es esencial. Solicita un objeto JSON detallado que contiene no solo el texto completo de la transcripción sino también una lista de segmentos, cada uno con tiempos de inicio/fin y el texto correspondiente.
- timestamp_granularities=["segment"]: Solicita explícitamente información de tiempo a nivel de segmento (aunque suele incluirse por defecto con verbose_json). Las marcas de tiempo a nivel de palabra también pueden solicitarse si es necesario (["word"]), pero los segmentos se utilizan típicamente para el subtitulado.
- language / prompt: Especificar el idioma (en) y proporcionar un prompt puede mejorar la precisión, lo cual es vital para la accesibilidad.
Consideración sobre "Tiempo Real": La explicación aclara que si bien este código procesa un archivo, la salida con marcas de tiempo que genera es lo que se necesita para aplicaciones en tiempo real. El subtitulado verdaderamente en vivo requeriría enviar fragmentos de audio a la API rápidamente.
Inicialización y Función (transcribe_for_accessibility): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando verbose_json.
Procesamiento de Salida:
- El código primero imprime el texto concatenado completo (transcription_data.text).
- Luego itera a través de la lista transcription_data.segments.
- Para cada segment, extrae el tiempo de start, tiempo de end, y text.
- Una función auxiliar (format_timestamp) convierte los tiempos (en segundos) a un formato estándar HH:MM:SS.fff.
- Imprime cada segmento con su información de tiempo (por ejemplo, [00:00:01.234 --> 00:00:05.678] Este es el texto del primer segmento.).
Relevancia del Caso de Uso: La salida muestra claramente cómo estos datos con marcas de tiempo permiten directamente los beneficios descritos: sincronización de texto con audio/video para subtítulos, permitiendo la participación en reuniones/conferencias, haciendo el contenido educativo accesible y mejorando el consumo de medios.
Guardado de Salida: Incluye una opción para guardar la respuesta completa verbose_json en un archivo para uso posterior o procesamiento más complejo. Maneja las posibles diferencias en la serialización del objeto de respuesta de la biblioteca openai.

Flujos de trabajo de subtitulado de video

Creadores de contenido que necesitan hacer sus videos accesibles en múltiples plataformas
Empresas de radiodifusión que requieren subtítulos cerrados precisos para cumplimiento regulatorio
Instituciones educativas que crean contenido de video accesible para poblaciones estudiantiles diversas
Gestores de redes sociales que desean aumentar el engagement de videos mediante subtitulado automático

Ejemplo:

Este ejemplo de código toma un archivo de audio (que típicamente extraerías primero de tu video) y usa Whisper para crear subtítulos con marcas de tiempo precisas en el formato estándar .srt.

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/video_audio.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Austin, Texas, United States" # User location context
print(f"Running Whisper caption generation (SRT) example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file (extracted from video)
# IMPORTANT: Replace 'video_audio.mp3' with the actual filename.
audio_file_path = "video_audio.mp3"

# --- Optional Parameters ---
# Specifying language can improve caption accuracy
known_language = "en"

# Prompt can help with names, brands, or specific terminology in the video
transcription_prompt = "The video features interviews with Dr. Anya Sharma about sustainable agriculture and mentions the company 'TerraGrow'." # Set to None if not needed

# --- Function to Generate SRT Captions ---
def generate_captions_srt(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper and returns captions in SRT format.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (extracted from video).
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The caption data in SRT format string, or None if an error occurs.
    """
    print(f"\nAttempting to generate SRT captions for: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for SRT caption generation...")

            # --- Make the API Call for Transcription ---
            # Request 'srt' format directly
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                response_format="srt" # Request SRT format output
                # Other options include "vtt"
            )

            # The response object for "srt" format is directly the SRT string
            srt_content = response
            print("SRT caption generation successful.")
            return srt_content

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    srt_captions = generate_captions_srt(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if srt_captions:
        # --- Save the SRT Content to a File ---
        output_srt_file = os.path.splitext(audio_file_path)[0] + ".srt"
        try:
            with open(output_srt_file, "w", encoding="utf-8") as f:
                f.write(srt_captions)
            print(f"\nSRT captions saved successfully to '{output_srt_file}'")

            # How this helps the use case:
            print("\nThis SRT file can be used to:")
            print("- Add closed captions or subtitles to video players (like YouTube, Vimeo, VLC).")
            print("- Import into video editing software for caption integration.")
            print("- Meet accessibility requirements and regulatory compliance (e.g., broadcasting).")
            print("- Improve video engagement on social media platforms.")
            print("- Make educational video content accessible to more students.")

        except IOError as e:
            print(f"Error saving SRT captions to file: {e}")

    else:
        print("\nSRT caption generation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra cómo usar la API de Whisper para agilizar los flujos de trabajo de subtitulado de video mediante la generación directa de archivos de subtítulos SRT (SubRip Text) en formato estándar de la industria a partir del audio.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv y la clave API. Es crucial que requiera un archivo de audio que se haya extraído del video objetivo. El script incluye una nota que explica este paso necesario de preprocesamiento.
Parámetro clave de API (response_format="srt"):
- El núcleo de este caso de uso es solicitar el formato srt directamente desde el endpoint client.audio.transcriptions.create.
- Esto indica a Whisper que formatee la salida según las especificaciones SRT, incluyendo numeración secuencial, marcas de tiempo de inicio/fin (por ejemplo, 00:00:20,000 --> 00:00:24,400), y el fragmento de texto correspondiente. La API maneja la sincronización de tiempos automáticamente. vtt (WebVTT) es otro formato común que se puede solicitar de manera similar.
Inicialización y Función (generate_captions_srt): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando específicamente el formato SRT. Los parámetros opcionales language y prompt pueden usarse para mejorar la precisión.
Manejo de Salida:
- La response de la llamada a la API (cuando response_format="srt") es directamente el contenido completo del archivo SRT como una única cadena de texto.
- El código luego guarda esta cadena directamente en un archivo con la extensión .srt.
Relevancia para el Caso de Uso:
- La explicación destaca cómo este archivo .srt generado sirve directamente a las necesidades de creadores de contenido, emisoras, educadores y gestores de redes sociales.
- Puede cargarse fácilmente en plataformas de video, importarse a software de edición o usarse para cumplir con estándares de accesibilidad y normativas. Simplifica significativamente el proceso tradicionalmente laborioso de creación manual de subtítulos.
Manejo de Errores: Incluye verificaciones estándar para errores de API y del sistema de archivos.

💡 Consejo: Whisper funciona mejor cuando el audio es claro y admite archivos de entrada de hasta 25MB por solicitud.

2.2.2 Formatos de Respuesta que Puedes Usar

Whisper admite múltiples formatos para tus necesidades:

2.2.3 Aplicaciones Prácticas de Whisper

Herramientas para Toma de Notas

Esta herramienta es particularmente valiosa para:

Estudiantes que capturan notas detalladas de clase mientras mantienen su participación en las discusiones
Periodistas que documentan entrevistas y conferencias de prensa con citas precisas
Profesionales de negocios que mantienen registros exactos de reuniones con clientes y sesiones de lluvia de ideas en equipo
Investigadores que realizan y transcriben entrevistas cualitativas

Negocios Internacionales: Facilita la comunicación en tiempo real en reuniones multinacionales, negociaciones y presentaciones sin necesidad de intérpretes humanos
Viajes y Turismo: Permite a los viajeros comunicarse efectivamente con los locales, entender anuncios y navegar en entornos extranjeros
Educación Global: Apoya programas de aprendizaje a distancia e intercambios estudiantiles internacionales al eliminar las barreras del idioma
Servicio al Cliente: Permite a los equipos de soporte asistir a los clientes en su idioma preferido, mejorando la calidad del servicio y la satisfacción

Soluciones de Accesibilidad

Subtitulado en Tiempo Real: Proporciona representación textual inmediata de palabras habladas durante eventos en vivo, reuniones y presentaciones
Transcripción Precisa: Genera registros escritos detallados del contenido de audio para referencia y estudio posterior
Soporte Multi-formato: Ofrece contenido en varios formatos incluyendo subtítulos cerrados, subtítulos y transcripciones descargables

Esta tecnología puede integrarse en:

Plataformas de Videoconferencia: Habilitando subtítulos en tiempo real durante reuniones virtuales y seminarios web
Plataformas Educativas: Apoyando a estudiantes con discapacidad auditiva tanto en entornos en línea como en aulas tradicionales
Reproductores Multimedia: Proporcionando subtítulos sincronizados para videos, podcasts y otros contenidos multimedia
Eventos en Vivo: Ofreciendo pantallas de texto en tiempo real durante conferencias, actuaciones y eventos de oratoria pública

Estas características de accesibilidad no solo apoyan a personas con discapacidad auditiva, sino que también benefician a:

Hablantes no nativos que prefieren leer mientras escuchan
Personas en entornos sensibles al sonido donde el audio no es práctico
Personas con aprendizaje visual que procesan mejor la información a través del texto
Organizaciones que buscan cumplir con regulaciones y estándares de accesibilidad

Mejora de Podcasts
Convierte contenido de audio en formatos de texto buscables mediante transcripción integral, permitiendo múltiples beneficios:

Descubrimiento de Contenido: Los oyentes pueden buscar fácilmente en las transcripciones de episodios para encontrar temas específicos, citas o discusiones de interés
Reutilización de Contenido: Los creadores pueden extraer citas clave y perspectivas para redes sociales, publicaciones de blog o boletines
Accesibilidad: Hace que el contenido esté disponible para audiencias con discapacidad auditiva y aquellos que prefieren leer
Beneficios SEO: Los motores de búsqueda pueden indexar el contenido completo de los episodios, mejorando la visibilidad y el tráfico orgánico
Participación Mejorada: Los lectores pueden explorar el contenido antes de escuchar, marcar secciones importantes y consultar material posteriormente
Perspectivas Analíticas: Analiza los términos más buscados y segmentos populares para informar la estrategia de contenido futura

Retroalimentación de Pronunciación en Tiempo Real: Los estudiantes pueden comparar sus palabras habladas con el texto transcrito para identificar errores de pronunciación y áreas de mejora
Análisis Gramatical: El sistema puede resaltar estructuras gramaticales y posibles errores en el texto transcrito, ayudando a los estudiantes a entender sus errores
Mejora de Vocabulario: Los estudiantes pueden hacer seguimiento de su uso activo del vocabulario y recibir sugerencias para elecciones de palabras más variadas

La tecnología beneficia particularmente a:

Estudiantes autodidactas que practican independientemente
Profesores de idiomas que dan seguimiento al progreso de los estudiantes
Plataformas de aprendizaje de idiomas en línea que ofrecen práctica de habla
Participantes de intercambio de idiomas que desean verificar su comunicación

Ejemplo:

Descarga el archivo de audio de muestra aquí: https://files.cuantum.tech/audio/language_practice_fr.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Orlando, Florida, United States" # User location context
print(f"Running Whisper language learning transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# --- Language Learning Specific Configuration ---

# Define the path to the language practice audio file
# IMPORTANT: Replace 'language_practice_fr.mp3' with the actual filename.
audio_file_path = "language_practice_fr.mp3"

# ** CRUCIAL: Specify the language being spoken in the audio file **
# Use the correct ISO-639-1 code (e.g., "en", "es", "fr", "de", "ja", "zh")
# This tells Whisper how to interpret the sounds.
target_language = "fr" # Example: French

# Optional: Provide context about the practice session (e.g., the expected phrase)
# This can help improve accuracy, especially for specific vocabulary or sentences.
practice_prompt = "The student is practicing ordering food at a French cafe, mentioning croissants and coffee." # Set to None if not needed

# --- Function to Transcribe Language Practice Audio ---
def transcribe_language_practice(client, file_path, language, prompt=None):
    """
    Transcribes audio of language practice using the Whisper API.
    Specifying the target language is crucial for this use case.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The ISO-639-1 code of the language being spoken.
        prompt (str, optional): A text prompt providing context. Defaults to None.

    Returns:
        str: The transcribed text in the target language, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe language practice ({language}) from: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    if not language:
        print("Error: Target language must be specified for language learning transcription.")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print(f"Sending audio ({language}) to Whisper API for transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language, # Pass the specified target language
                prompt=prompt,
                response_format="text" # Get plain text for easy comparison/analysis
            )

            # The response object for "text" format is directly the string
            practice_transcription = response
            print("Transcription successful.")
            return practice_transcription

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        elif "invalid language code" in str(e).lower():
             print(f"Hint: Check if '{language}' is a valid ISO-639-1 language code supported by Whisper.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_text = transcribe_language_practice(
        client,
        audio_file_path,
        language=target_language,
        prompt=practice_prompt
    )

    if transcribed_text:
        print("\n--- Transcribed Practice Text ---")
        print(f"(Language: {target_language})")
        print(transcribed_text)
        print("---------------------------------\n")

        # How this helps the use case:
        print("This transcription provides the basis for language learning feedback:")
        print("- **Pronunciation Check:** Learner compares their speech to the text, identifying discrepancies.")
        print("- **Grammar/Vocabulary Analysis:** This text can be compared against expected sentences or analyzed (potentially by another AI like GPT-4o, or specific tools) for grammatical correctness and vocabulary usage.")
        print("- **Progress Tracking:** Teachers or platforms can store transcriptions to monitor improvement over time.")
        print("- **Self-Correction:** Learners get immediate textual representation of their speech for review.")
        print("\nNote: Further analysis (grammar checking, pronunciation scoring, etc.) requires additional logic beyond this transcription step.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_text)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nLanguage practice transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper como herramienta de apoyo para el aprendizaje de idiomas. Transcribe grabaciones de audio de un estudiante hablando un idioma objetivo, proporcionando el texto de salida esencial necesario para varios mecanismos de retroalimentación.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API, y un archivo de audio que contenga la práctica hablada del estudiante en el idioma objetivo (por ejemplo, language_practice_fr.mp3).
Parámetro clave (language):
- A diferencia de la transcripción general donde la detección automática podría ser suficiente, para el aprendizaje de idiomas, especificar explícitamente el language que el estudiante está intentando hablar es crucial. Esto se establece usando la variable target_language (por ejemplo, "fr" para francés).
- Esto asegura que Whisper interprete el audio usando el modelo fonético y de vocabulario correcto, proporcionando una transcripción más precisa para la retroalimentación.
Prompt opcional: El parámetro prompt puede usarse para dar contexto a Whisper sobre la sesión de práctica (por ejemplo, la frase específica que se está practicando), lo que puede mejorar la precisión del reconocimiento.
Inicialización y Función (transcribe_language_practice): Configuración estándar del cliente. La función requiere el parámetro language y realiza la transcripción usando client.audio.transcriptions.create.
Salida (response_format="text"): Se solicita la salida en texto plano ya que es el formato más directo para que los estudiantes o sistemas comparen con el texto esperado, analicen la gramática o revisen el vocabulario.
Mecanismo de Retroalimentación (Nota Importante): La explicación establece claramente que este script solo proporciona la transcripción. La retroalimentación real (puntuación de pronunciación, corrección gramatical, sugerencias de vocabulario) requiere procesamiento adicional. Este texto transcrito sirve como entrada para esos pasos de análisis posteriores, que podrían involucrar verificaciones basadas en reglas, algoritmos de comparación, o incluso alimentar el texto a otro LLM como GPT-4o para su análisis.
Relevancia del Caso de Uso: La sección de salida explica cómo esta transcripción permite los beneficios descritos: permitiendo a los estudiantes verificar su pronunciación contra el texto, proporcionando material para análisis de gramática/vocabulario, facilitando el seguimiento del progreso y apoyando la autocorrección.

Resumen

En esta sección, aprendiste varios aspectos clave del procesamiento y comprensión de audio:

Transcribir lenguaje hablado a texto usando Whisper
- Convertir varios formatos de audio en transcripciones de texto precisas
- Manejar múltiples idiomas y acentos con alta precisión
- Procesar efectivamente tanto clips cortos como grabaciones largas
Traducir audio en idioma extranjero al inglés
- Convertir habla no inglesa directamente a texto en inglés
- Mantener el contexto y significado a través de las barreras del idioma
- Soportar procesamiento de contenido multilingüe
Elegir entre salidas de texto plano, JSON y subtítulos
- Seleccionar el formato más apropiado para tu caso de uso específico
- Generar subtítulos con marcas de tiempo precisas
- Estructurar datos en formato JSON legible por máquina
Aplicar estas herramientas en casos de uso del mundo real como accesibilidad, educación y creación de contenido
- Crear contenido accesible con transcripciones precisas
- Apoyar el aprendizaje de idiomas e iniciativas educativas
- Optimizar flujos de trabajo de producción de contenido

2.2 Transcripción y Traducción con la API de Whisper

2.2.1 ¿Qué es Whisper?

Whisper demuestra una versatilidad excepcional a través de numerosas aplicaciones:

Transcripciones de reuniones o podcasts

Archivar reuniones importantes para consultas futuras
Crear versiones accesibles de contenido de audio
Permitir búsquedas rápidas a través de horas de contenido grabado
Generar documentación escrita a partir de discusiones verbales
Apoyar requisitos de cumplimiento para el mantenimiento de registros

La alta tasa de precisión asegura que los términos técnicos, nombres propios y discusiones complejas se capturen correctamente mientras se mantiene el flujo natural de la conversación.

Ejemplo:

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/meeting_snippet.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt
current_location = "Houston, Texas, United States"
print(f"Running Whisper transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'meeting_snippet.mp3' with the actual filename.
audio_file_path = "meeting_snippet.mp3"

# --- Optional Parameters for potentially better accuracy ---
# Specify language (ISO-639-1 code) if known, otherwise Whisper auto-detects.
# Example: "en" for English, "es" for Spanish, "de" for German
known_language = "en" # Set to None to auto-detect

# Provide a prompt with context, names, or jargon expected in the audio.
# This helps Whisper recognize specific terms accurately.
transcription_prompt = "The discussion involves Project Phoenix, stakeholders like Dr. Evelyn Reed and ACME Corp, and technical terms such as multi-threaded processing and cloud-native architecture." # Set to None if no prompt needed

# --- Function to Transcribe Audio ---
def transcribe_audio(client, file_path, language=None, prompt=None):
    """
    Transcribes the given audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Check file size (optional but good practice)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            print("Consider splitting the file into smaller chunks.")
            # You might choose to exit here or attempt anyway
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        return None


    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Optional: Specify language
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the string
            transcription_text = response
            print("Transcription successful.")
            return transcription_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        # Provide hints for common errors
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (mp3, mp4, mpeg, mpga, m4a, wav, webm).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit. Please split the file.")
        return None
    except FileNotFoundError: # Already handled above, but good practice
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcription = transcribe_audio(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription:
        print("\n--- Transcription Result ---")
        print(transcription)
        print("----------------------------\n")

        # How this helps the use case:
        print("This plain text transcription can now be:")
        print("- Saved as a text document (.txt) for archiving.")
        print("- Indexed and searched easily for specific keywords or names.")
        print("- Used to generate meeting minutes or documentation.")
        print("- Copied into accessibility tools or documents.")
        print("- Stored for compliance record-keeping.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcription)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nTranscription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la transcripción de archivos de audio como grabaciones de reuniones o episodios de podcast utilizando la API Whisper de OpenAI. El objetivo es convertir el contenido hablado en texto preciso y consultable, atendiendo necesidades como el archivo, la accesibilidad y la documentación.
Requisitos previos: Requiere las bibliotecas openai y python-dotenv, una clave API de OpenAI configurada en un archivo .env, y un archivo de audio de muestra (meeting_snippet.mp3).
Requisitos del archivo de audio: El script destaca los formatos de audio compatibles (MP3, WAV, M4A, etc.) y el límite crucial de 25MB por solicitud de API. Incluye una advertencia y explicación de que los archivos más largos deben segmentarse antes del procesamiento, aunque el código en sí maneja un solo archivo dentro del límite.
Inicialización: Configura el cliente estándar OpenAI utilizando la clave API.
Función de transcripción (transcribe_audio):
- Toma los argumentos client, file_path, y los opcionales language y prompt.
- Incluye una verificación de existencia y tamaño del archivo.
- Abre el archivo de audio en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.transcriptions.create con:
  - model="whisper-1": Especifica el modelo conocido por su alta precisión.
  - file=audio_file: Pasa el objeto de archivo abierto.
  - language: Opcionalmente proporciona el código de idioma (por ejemplo, "en") para potencialmente mejorar la precisión si se conoce el idioma. Si es None, Whisper detecta automáticamente.
  - prompt: Opcionalmente proporciona palabras clave contextuales, nombres (como "Project Phoenix", "Dr. Evelyn Reed"), o jerga. Esto ayuda significativamente a Whisper a transcribir con precisión términos especializados que se encuentran frecuentemente en reuniones o podcasts técnicos, abordando directamente la necesidad de capturar correctamente discusiones complejas.
  - response_format="text": Solicita la salida directamente como una cadena de texto plano, ideal para uso inmediato en documentos, indexación de búsqueda, etc. Se podrían solicitar otros formatos como verbose_json (para marcas de tiempo) o srt/vtt (para subtítulos) si fuera necesario.
- Manejo de errores: Incluye bloques try...except para errores de API (proporcionando sugerencias para problemas comunes como tamaño o formato de archivo) y errores del sistema de archivos.
Salida y utilidad:
- Se imprime el texto de transcripción resultante.
- El código conecta explícitamente esta salida con los beneficios del caso de uso: crear archivos consultables, generar documentación, apoyar la accesibilidad y permitir el cumplimiento normativo.
- Incluye un paso opcional para guardar la transcripción directamente en un archivo .txt.

Conversión de notas de voz

Transforma los mensajes de voz rápidos en notas de texto organizadas, facilitando la revisión y el archivo de pensamientos hablados. Esta funcionalidad es particularmente valiosa para:

Crear recordatorios rápidos y listas de tareas mientras se está en movimiento
Capturar ideas creativas o sesiones de lluvia de ideas sin interrumpir el flujo de pensamiento
Tomar notas durante trabajo de campo o visitas al sitio donde escribir es poco práctico
Documentar observaciones o hallazgos de investigación en tiempo real

El sistema mantiene el flujo natural del habla mientras organiza el contenido en texto claro y legible que puede ser fácilmente buscado, compartido o integrado en otros documentos.

Ejemplo:

Este script se centra en tomar un archivo de audio típico de nota de voz y convertirlo en texto consultable y utilizable, ideal para capturar ideas, recordatorios o notas de campo.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/voice_memo.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Miami, Florida, United States"
print(f"Running Whisper voice note transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local voice note audio file
# IMPORTANT: Replace 'voice_memo.m4a' with the actual filename.
audio_file_path = "voice_memo.mp3"

# --- Optional Parameters (Often not needed for simple voice notes) ---
# Language auto-detection is usually sufficient for voice notes.
known_language = None # Set to "en", "es", etc. if needed

# Prompt is useful if your notes contain specific jargon/names, otherwise leave as None.
transcription_prompt = None # Example: "Remember to mention Project Chimera and the client ZetaCorp."

# --- Function to Transcribe Voice Note ---
def transcribe_voice_note(client, file_path, language=None, prompt=None):
    """
    Transcribes the given voice note audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe voice note: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size (less likely to be an issue for voice notes)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None # Decide if you want to stop for large files
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        # Continue attempt even if size check fails
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending voice note to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Defaults to None (auto-detect)
                prompt=prompt,              # Defaults to None
                response_format="text"      # Request plain text output for easy use as notes
            )

            # The response object for "text" format is directly the string
            note_text = response
            print("Transcription successful.")
            return note_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (m4a, mp3, wav, etc.).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_note = transcribe_voice_note(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcribed_note:
        print("\n--- Transcribed Voice Note Text ---")
        print(transcribed_note)
        print("-----------------------------------\n")

        # How this helps the use case:
        print("This transcribed text from your voice note can be easily:")
        print("- Copied into reminder apps or to-do lists.")
        print("- Saved as a text file for archiving creative ideas or brainstorms.")
        print("- Searched later for specific keywords or topics.")
        print("- Shared via email or messaging apps.")
        print("- Integrated into reports or documentation (e.g., field notes).")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_note)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nVoice note transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para transcribir grabaciones de audio cortas como notas de voz y memorandos. Es ideal para capturar rápidamente pensamientos, ideas, recordatorios u observaciones de campo y convertirlos en texto fácilmente manejable.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y un archivo de audio de muestra de nota de voz (se admiten formatos comunes como .m4a, .mp3, .wav).
Manejo de archivos de audio: El script enfatiza que las notas de voz típicamente están muy por debajo del límite de 25MB de la API. Abre el archivo en modo de lectura binaria ("rb").
Inicialización: Configura el cliente OpenAI.
Función de transcripción (transcribe_voice_note):
- Similar a la función de transcripción de reuniones pero adaptada para notas de voz.
- Valores predeterminados: Establece language como None (detección automática) y prompt como None, ya que estos suelen ser suficientes para notas de voz típicas donde la jerga específica puede ser menos común. El usuario aún puede proporcionarlos si es necesario.
- Llamada a la API: Utiliza client.audio.transcriptions.create con model="whisper-1".
- response_format="text": Solicita explícitamente la salida en texto plano, que es el formato más práctico para notas – fácil de leer, buscar, copiar y compartir.
- Manejo de errores: Incluye bloques estándar try...except para errores de API y archivo.
Salida y utilidad:
- Imprime la transcripción de texto resultante.
- Conecta explícitamente la salida con los beneficios mencionados en la descripción del caso de uso: crear recordatorios/tareas pendientes, capturar ideas, documentar observaciones, permitir búsquedas y compartir.
- Incluye un paso opcional para guardar la nota transcrita en un archivo .txt.

Traducción de voz multilingüe

Elimina las barreras lingüísticas proporcionando traducciones precisas mientras preserva el contexto y significado original. Esta potente característica permite:

Comunicación en tiempo real superando barreras lingüísticas en reuniones y conferencias internacionales
Traducción de contenido educativo para audiencias globales manteniendo la integridad académica
Negociaciones comerciales interculturales con traducción precisa de términos técnicos y matices culturales
Traducción de documentación para organizaciones multinacionales con terminología consistente

Ejemplo:

Este ejemplo toma un archivo de audio que contiene habla en un idioma distinto del inglés y lo traduce directamente a texto en inglés.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/spanish_speech.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Denver, Colorado, United States"
print(f"Running Whisper speech translation example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local non-English audio file
# IMPORTANT: Replace 'spanish_speech.mp3' with the actual filename.
audio_file_path = "spanish_speech.mp3"

# --- Optional Parameters ---
# Prompt can help guide recognition of specific names/terms in the SOURCE language
# before translation, potentially improving accuracy of the final English text.
translation_prompt = None # Example: "The discussion mentions La Sagrada Familia and Parc Güell."

# --- Function to Translate Speech to English ---
def translate_speech_to_english(client, file_path, prompt=None):
    """
    Translates speech from the given audio file into English using the Whisper API.
    The source language is automatically detected.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (non-English speech).
        prompt (str, optional): A text prompt to guide source language recognition. Defaults to None.

    Returns:
        str: The translated English text, or None if an error occurs.
    """
    print(f"\nAttempting to translate speech from audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Translation may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for translation to English...")

            # --- Make the API Call for Translation ---
            # Note: Using the 'translations' endpoint, not 'transcriptions'
            response = client.audio.translations.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text English output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the translated string
            translated_text = response
            print("Translation successful.")
            return translated_text

    except OpenAIError as e:
        print(f"OpenAI API Error during translation: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        # Whisper might error if it cannot detect speech or supported language
        elif "language could not be detected" in str(e).lower():
             print("Hint: Ensure the audio contains detectable speech in a supported language.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during translation: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    english_translation = translate_speech_to_english(
        client,
        audio_file_path,
        prompt=translation_prompt
    )

    if english_translation:
        print("\n--- Translated English Text ---")
        print(english_translation)
        print("-------------------------------\n")

        # How this helps the use case:
        print("This English translation enables:")
        print("- Understanding discussions from international meetings.")
        print("- Making educational content accessible to English-speaking audiences.")
        print("- Facilitating cross-cultural business communication.")
        print("- Creating English versions of documentation originally recorded in other languages.")
        print("- Quick communication across language barriers using voice input.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_translation_en.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(english_translation)
            print(f"Translation saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving translation to file: {e}")

    else:
        print("\nSpeech translation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la capacidad de la API de Whisper para realizar traducción de voz a texto, específicamente traduciendo audio de varios idiomas de origen directamente a texto en inglés. Esto aborda la necesidad de eliminar las barreras lingüísticas en escenarios de comunicación global.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y, fundamentalmente, un archivo de audio de muestra que contenga voz en un idioma que no sea inglés (por ejemplo, español, francés, alemán).
Punto final de API clave: Este ejemplo utiliza client.audio.translations.create, que es distinto del punto final transcriptions usado anteriormente. El punto final de translations está específicamente diseñado para generar texto en inglés.
Detección automática de idioma: Una característica clave destacada es que no es necesario especificar el idioma de origen del archivo de audio; Whisper lo detecta automáticamente antes de traducir al inglés.
Inicialización: Configura el cliente OpenAI.
Función de traducción (translate_speech_to_english):
- Toma el client, file_path, y un prompt opcional.
- Abre el archivo de audio no inglés en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.translations.create con:
  - model="whisper-1": El modelo estándar de Whisper.
  - file=audio_file: El objeto del archivo de audio.
  - prompt: Opcionalmente proporciona contexto (en el idioma de origen o inglés, frecuentemente ayuda con nombres/términos) para ayudar al reconocimiento preciso antes de la traducción, ayudando a preservar matices y términos técnicos.
  - response_format="text": Solicita salida de texto en inglés simple.
- Manejo de errores: Incluye bloques try...except, señalando posibles errores si no se detecta voz o un idioma compatible en el audio.
Salida y utilidad:
- Imprime el texto traducido al inglés resultante.
- Conecta explícitamente esta salida con los beneficios descritos en el caso de uso: permitir la comprensión en reuniones internacionales, traducir contenido educativo/empresarial para audiencias globales y facilitar la documentación y comunicación entre idiomas.
- Muestra cómo guardar opcionalmente la traducción al inglés en un archivo .txt.

Herramientas de accesibilidad

Permite una mejor inclusión digital al proporcionar servicios de transcripción en tiempo real para usuarios con discapacidad auditiva, ofreciendo varios beneficios clave:

Permite a las personas sordas y con dificultades auditivas participar plenamente en contenido basado en audio
Proporciona acceso instantáneo a información hablada en entornos profesionales como reuniones y conferencias
Apoya entornos educativos haciendo accesibles las clases y discusiones para todos los estudiantes
Mejora el consumo de medios al permitir subtitulado preciso en tiempo real para videos y transmisiones en vivo

Ejemplo:

Este ejemplo se centra en utilizar el formato de salida verbose_json para obtener marcas de tiempo a nivel de segmento, que son esenciales para sincronizar texto con audio o video.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/lecture_snippet.mp3

import os
import json # To potentially parse the verbose_json output nicely
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Atlanta, Georgia, United States" # User location context
print(f"Running Whisper accessibility transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'lecture_snippet.mp3' with the actual filename.
audio_file_path = "lecture_snippet.mp3"

# --- Optional Parameters ---
# Specifying language is often good for accuracy in accessibility contexts
known_language = "en"

# Prompt can help with specific terminology in lectures or meetings
transcription_prompt = "The lecture discusses quantum entanglement, superposition, and Bell's theorem." # Set to None if not needed

# --- Function to Transcribe Audio with Timestamps ---
def transcribe_for_accessibility(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper, requesting timestamped output
    suitable for accessibility applications (e.g., captioning).

    Note on 'Real-time': This function processes a complete file. True real-time
    captioning requires capturing audio in chunks, sending each chunk to the API
    quickly, and displaying the results sequentially. This example generates the
    *type* of data needed for such applications from a pre-recorded file.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        dict: The parsed verbose_json response containing text and segments
              with timestamps, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe for accessibility: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for timestamped transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                # Request detailed JSON output including timestamps
                response_format="verbose_json",
                # Explicitly request segment-level timestamps
                timestamp_granularities=["segment"]
            )

            # The response object is already a Pydantic model behaving like a dict
            timestamped_data = response
            print("Timestamped transcription successful.")
            # You can access response.text, response.segments etc directly
            return timestamped_data

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Function to Format Timestamps ---
def format_timestamp(seconds):
    """Converts seconds to HH:MM:SS.fff format."""
    td = datetime.timedelta(seconds=seconds)
    total_milliseconds = int(td.total_seconds() * 1000)
    hours, remainder = divmod(total_milliseconds, 3600000)
    minutes, remainder = divmod(remainder, 60000)
    seconds, milliseconds = divmod(remainder, 1000)
    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"

# --- Main Execution ---
if __name__ == "__main__":
    transcription_data = transcribe_for_accessibility(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription_data:
        print("\n--- Full Transcription Text ---")
        # Access the full text directly from the response object
        print(transcription_data.text)
        print("-------------------------------\n")

        print("--- Transcription Segments with Timestamps ---")
        # Iterate through segments for timestamped data
        for segment in transcription_data.segments:
            start_time = format_timestamp(segment['start'])
            end_time = format_timestamp(segment['end'])
            segment_text = segment['text']
            print(f"[{start_time} --> {end_time}] {segment_text}")
        print("---------------------------------------------\n")

        # How this helps the use case:
        print("This timestamped data enables:")
        print("- Displaying captions synchronized with video or audio streams.")
        print("- Highlighting text in real-time as it's spoken in meetings or lectures.")
        print("- Creating accessible versions of educational/media content.")
        print("- Allowing users to navigate audio by clicking on text segments.")
        print("- Fuller participation for hearing-impaired individuals.")

        # Optional: Save the detailed JSON output
        output_json_file = os.path.splitext(audio_file_path)[0] + "_timestamps.json"
        try:
            # The response object can be converted to dict for JSON serialization
            with open(output_json_file, "w", encoding="utf-8") as f:
                 # Use .model_dump_json() for Pydantic V2 models from openai>=1.0.0
                 # or .dict() for older versions/models
                 try:
                      f.write(transcription_data.model_dump_json(indent=2))
                 except AttributeError:
                      # Fallback for older versions or different object types
                      import json
                      f.write(json.dumps(transcription_data, default=lambda o: o.__dict__, indent=2))

            print(f"Detailed timestamp data saved to '{output_json_file}'")
        except (IOError, TypeError, AttributeError) as e:
            print(f"Error saving timestamp data to JSON file: {e}")

    else:
        print("\nTranscription for accessibility failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para generar transcripciones altamente precisas con marcas de tiempo a nivel de segmento. Esta salida es crucial para aplicaciones de accesibilidad, permitiendo funciones como subtitulado en tiempo real, resaltado sincronizado de texto y transcripciones navegables para usuarios con dificultades auditivas.
Requisitos previos: Configuración estándar (openai, python-dotenv, clave API) y un archivo de audio (lecture_snippet.mp3).
Parámetros clave de la API:
- Endpoint: Utiliza client.audio.transcriptions.create.
- response_format="verbose_json": Esto es esencial. Solicita un objeto JSON detallado que contiene no solo el texto completo de la transcripción sino también una lista de segmentos, cada uno con tiempos de inicio/fin y el texto correspondiente.
- timestamp_granularities=["segment"]: Solicita explícitamente información de tiempo a nivel de segmento (aunque suele incluirse por defecto con verbose_json). Las marcas de tiempo a nivel de palabra también pueden solicitarse si es necesario (["word"]), pero los segmentos se utilizan típicamente para el subtitulado.
- language / prompt: Especificar el idioma (en) y proporcionar un prompt puede mejorar la precisión, lo cual es vital para la accesibilidad.
Consideración sobre "Tiempo Real": La explicación aclara que si bien este código procesa un archivo, la salida con marcas de tiempo que genera es lo que se necesita para aplicaciones en tiempo real. El subtitulado verdaderamente en vivo requeriría enviar fragmentos de audio a la API rápidamente.
Inicialización y Función (transcribe_for_accessibility): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando verbose_json.
Procesamiento de Salida:
- El código primero imprime el texto concatenado completo (transcription_data.text).
- Luego itera a través de la lista transcription_data.segments.
- Para cada segment, extrae el tiempo de start, tiempo de end, y text.
- Una función auxiliar (format_timestamp) convierte los tiempos (en segundos) a un formato estándar HH:MM:SS.fff.
- Imprime cada segmento con su información de tiempo (por ejemplo, [00:00:01.234 --> 00:00:05.678] Este es el texto del primer segmento.).
Relevancia del Caso de Uso: La salida muestra claramente cómo estos datos con marcas de tiempo permiten directamente los beneficios descritos: sincronización de texto con audio/video para subtítulos, permitiendo la participación en reuniones/conferencias, haciendo el contenido educativo accesible y mejorando el consumo de medios.
Guardado de Salida: Incluye una opción para guardar la respuesta completa verbose_json en un archivo para uso posterior o procesamiento más complejo. Maneja las posibles diferencias en la serialización del objeto de respuesta de la biblioteca openai.

Flujos de trabajo de subtitulado de video

Creadores de contenido que necesitan hacer sus videos accesibles en múltiples plataformas
Empresas de radiodifusión que requieren subtítulos cerrados precisos para cumplimiento regulatorio
Instituciones educativas que crean contenido de video accesible para poblaciones estudiantiles diversas
Gestores de redes sociales que desean aumentar el engagement de videos mediante subtitulado automático

Ejemplo:

Este ejemplo de código toma un archivo de audio (que típicamente extraerías primero de tu video) y usa Whisper para crear subtítulos con marcas de tiempo precisas en el formato estándar .srt.

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/video_audio.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Austin, Texas, United States" # User location context
print(f"Running Whisper caption generation (SRT) example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file (extracted from video)
# IMPORTANT: Replace 'video_audio.mp3' with the actual filename.
audio_file_path = "video_audio.mp3"

# --- Optional Parameters ---
# Specifying language can improve caption accuracy
known_language = "en"

# Prompt can help with names, brands, or specific terminology in the video
transcription_prompt = "The video features interviews with Dr. Anya Sharma about sustainable agriculture and mentions the company 'TerraGrow'." # Set to None if not needed

# --- Function to Generate SRT Captions ---
def generate_captions_srt(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper and returns captions in SRT format.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (extracted from video).
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The caption data in SRT format string, or None if an error occurs.
    """
    print(f"\nAttempting to generate SRT captions for: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for SRT caption generation...")

            # --- Make the API Call for Transcription ---
            # Request 'srt' format directly
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                response_format="srt" # Request SRT format output
                # Other options include "vtt"
            )

            # The response object for "srt" format is directly the SRT string
            srt_content = response
            print("SRT caption generation successful.")
            return srt_content

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    srt_captions = generate_captions_srt(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if srt_captions:
        # --- Save the SRT Content to a File ---
        output_srt_file = os.path.splitext(audio_file_path)[0] + ".srt"
        try:
            with open(output_srt_file, "w", encoding="utf-8") as f:
                f.write(srt_captions)
            print(f"\nSRT captions saved successfully to '{output_srt_file}'")

            # How this helps the use case:
            print("\nThis SRT file can be used to:")
            print("- Add closed captions or subtitles to video players (like YouTube, Vimeo, VLC).")
            print("- Import into video editing software for caption integration.")
            print("- Meet accessibility requirements and regulatory compliance (e.g., broadcasting).")
            print("- Improve video engagement on social media platforms.")
            print("- Make educational video content accessible to more students.")

        except IOError as e:
            print(f"Error saving SRT captions to file: {e}")

    else:
        print("\nSRT caption generation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra cómo usar la API de Whisper para agilizar los flujos de trabajo de subtitulado de video mediante la generación directa de archivos de subtítulos SRT (SubRip Text) en formato estándar de la industria a partir del audio.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv y la clave API. Es crucial que requiera un archivo de audio que se haya extraído del video objetivo. El script incluye una nota que explica este paso necesario de preprocesamiento.
Parámetro clave de API (response_format="srt"):
- El núcleo de este caso de uso es solicitar el formato srt directamente desde el endpoint client.audio.transcriptions.create.
- Esto indica a Whisper que formatee la salida según las especificaciones SRT, incluyendo numeración secuencial, marcas de tiempo de inicio/fin (por ejemplo, 00:00:20,000 --> 00:00:24,400), y el fragmento de texto correspondiente. La API maneja la sincronización de tiempos automáticamente. vtt (WebVTT) es otro formato común que se puede solicitar de manera similar.
Inicialización y Función (generate_captions_srt): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando específicamente el formato SRT. Los parámetros opcionales language y prompt pueden usarse para mejorar la precisión.
Manejo de Salida:
- La response de la llamada a la API (cuando response_format="srt") es directamente el contenido completo del archivo SRT como una única cadena de texto.
- El código luego guarda esta cadena directamente en un archivo con la extensión .srt.
Relevancia para el Caso de Uso:
- La explicación destaca cómo este archivo .srt generado sirve directamente a las necesidades de creadores de contenido, emisoras, educadores y gestores de redes sociales.
- Puede cargarse fácilmente en plataformas de video, importarse a software de edición o usarse para cumplir con estándares de accesibilidad y normativas. Simplifica significativamente el proceso tradicionalmente laborioso de creación manual de subtítulos.
Manejo de Errores: Incluye verificaciones estándar para errores de API y del sistema de archivos.

💡 Consejo: Whisper funciona mejor cuando el audio es claro y admite archivos de entrada de hasta 25MB por solicitud.

2.2.2 Formatos de Respuesta que Puedes Usar

Whisper admite múltiples formatos para tus necesidades:

2.2.3 Aplicaciones Prácticas de Whisper

Herramientas para Toma de Notas

Esta herramienta es particularmente valiosa para:

Estudiantes que capturan notas detalladas de clase mientras mantienen su participación en las discusiones
Periodistas que documentan entrevistas y conferencias de prensa con citas precisas
Profesionales de negocios que mantienen registros exactos de reuniones con clientes y sesiones de lluvia de ideas en equipo
Investigadores que realizan y transcriben entrevistas cualitativas

Negocios Internacionales: Facilita la comunicación en tiempo real en reuniones multinacionales, negociaciones y presentaciones sin necesidad de intérpretes humanos
Viajes y Turismo: Permite a los viajeros comunicarse efectivamente con los locales, entender anuncios y navegar en entornos extranjeros
Educación Global: Apoya programas de aprendizaje a distancia e intercambios estudiantiles internacionales al eliminar las barreras del idioma
Servicio al Cliente: Permite a los equipos de soporte asistir a los clientes en su idioma preferido, mejorando la calidad del servicio y la satisfacción

Soluciones de Accesibilidad

Subtitulado en Tiempo Real: Proporciona representación textual inmediata de palabras habladas durante eventos en vivo, reuniones y presentaciones
Transcripción Precisa: Genera registros escritos detallados del contenido de audio para referencia y estudio posterior
Soporte Multi-formato: Ofrece contenido en varios formatos incluyendo subtítulos cerrados, subtítulos y transcripciones descargables

Esta tecnología puede integrarse en:

Plataformas de Videoconferencia: Habilitando subtítulos en tiempo real durante reuniones virtuales y seminarios web
Plataformas Educativas: Apoyando a estudiantes con discapacidad auditiva tanto en entornos en línea como en aulas tradicionales
Reproductores Multimedia: Proporcionando subtítulos sincronizados para videos, podcasts y otros contenidos multimedia
Eventos en Vivo: Ofreciendo pantallas de texto en tiempo real durante conferencias, actuaciones y eventos de oratoria pública

Estas características de accesibilidad no solo apoyan a personas con discapacidad auditiva, sino que también benefician a:

Hablantes no nativos que prefieren leer mientras escuchan
Personas en entornos sensibles al sonido donde el audio no es práctico
Personas con aprendizaje visual que procesan mejor la información a través del texto
Organizaciones que buscan cumplir con regulaciones y estándares de accesibilidad

Mejora de Podcasts
Convierte contenido de audio en formatos de texto buscables mediante transcripción integral, permitiendo múltiples beneficios:

Descubrimiento de Contenido: Los oyentes pueden buscar fácilmente en las transcripciones de episodios para encontrar temas específicos, citas o discusiones de interés
Reutilización de Contenido: Los creadores pueden extraer citas clave y perspectivas para redes sociales, publicaciones de blog o boletines
Accesibilidad: Hace que el contenido esté disponible para audiencias con discapacidad auditiva y aquellos que prefieren leer
Beneficios SEO: Los motores de búsqueda pueden indexar el contenido completo de los episodios, mejorando la visibilidad y el tráfico orgánico
Participación Mejorada: Los lectores pueden explorar el contenido antes de escuchar, marcar secciones importantes y consultar material posteriormente
Perspectivas Analíticas: Analiza los términos más buscados y segmentos populares para informar la estrategia de contenido futura

Retroalimentación de Pronunciación en Tiempo Real: Los estudiantes pueden comparar sus palabras habladas con el texto transcrito para identificar errores de pronunciación y áreas de mejora
Análisis Gramatical: El sistema puede resaltar estructuras gramaticales y posibles errores en el texto transcrito, ayudando a los estudiantes a entender sus errores
Mejora de Vocabulario: Los estudiantes pueden hacer seguimiento de su uso activo del vocabulario y recibir sugerencias para elecciones de palabras más variadas

La tecnología beneficia particularmente a:

Estudiantes autodidactas que practican independientemente
Profesores de idiomas que dan seguimiento al progreso de los estudiantes
Plataformas de aprendizaje de idiomas en línea que ofrecen práctica de habla
Participantes de intercambio de idiomas que desean verificar su comunicación

Ejemplo:

Descarga el archivo de audio de muestra aquí: https://files.cuantum.tech/audio/language_practice_fr.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Orlando, Florida, United States" # User location context
print(f"Running Whisper language learning transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# --- Language Learning Specific Configuration ---

# Define the path to the language practice audio file
# IMPORTANT: Replace 'language_practice_fr.mp3' with the actual filename.
audio_file_path = "language_practice_fr.mp3"

# ** CRUCIAL: Specify the language being spoken in the audio file **
# Use the correct ISO-639-1 code (e.g., "en", "es", "fr", "de", "ja", "zh")
# This tells Whisper how to interpret the sounds.
target_language = "fr" # Example: French

# Optional: Provide context about the practice session (e.g., the expected phrase)
# This can help improve accuracy, especially for specific vocabulary or sentences.
practice_prompt = "The student is practicing ordering food at a French cafe, mentioning croissants and coffee." # Set to None if not needed

# --- Function to Transcribe Language Practice Audio ---
def transcribe_language_practice(client, file_path, language, prompt=None):
    """
    Transcribes audio of language practice using the Whisper API.
    Specifying the target language is crucial for this use case.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The ISO-639-1 code of the language being spoken.
        prompt (str, optional): A text prompt providing context. Defaults to None.

    Returns:
        str: The transcribed text in the target language, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe language practice ({language}) from: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    if not language:
        print("Error: Target language must be specified for language learning transcription.")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print(f"Sending audio ({language}) to Whisper API for transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language, # Pass the specified target language
                prompt=prompt,
                response_format="text" # Get plain text for easy comparison/analysis
            )

            # The response object for "text" format is directly the string
            practice_transcription = response
            print("Transcription successful.")
            return practice_transcription

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        elif "invalid language code" in str(e).lower():
             print(f"Hint: Check if '{language}' is a valid ISO-639-1 language code supported by Whisper.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_text = transcribe_language_practice(
        client,
        audio_file_path,
        language=target_language,
        prompt=practice_prompt
    )

    if transcribed_text:
        print("\n--- Transcribed Practice Text ---")
        print(f"(Language: {target_language})")
        print(transcribed_text)
        print("---------------------------------\n")

        # How this helps the use case:
        print("This transcription provides the basis for language learning feedback:")
        print("- **Pronunciation Check:** Learner compares their speech to the text, identifying discrepancies.")
        print("- **Grammar/Vocabulary Analysis:** This text can be compared against expected sentences or analyzed (potentially by another AI like GPT-4o, or specific tools) for grammatical correctness and vocabulary usage.")
        print("- **Progress Tracking:** Teachers or platforms can store transcriptions to monitor improvement over time.")
        print("- **Self-Correction:** Learners get immediate textual representation of their speech for review.")
        print("\nNote: Further analysis (grammar checking, pronunciation scoring, etc.) requires additional logic beyond this transcription step.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_text)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nLanguage practice transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper como herramienta de apoyo para el aprendizaje de idiomas. Transcribe grabaciones de audio de un estudiante hablando un idioma objetivo, proporcionando el texto de salida esencial necesario para varios mecanismos de retroalimentación.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API, y un archivo de audio que contenga la práctica hablada del estudiante en el idioma objetivo (por ejemplo, language_practice_fr.mp3).
Parámetro clave (language):
- A diferencia de la transcripción general donde la detección automática podría ser suficiente, para el aprendizaje de idiomas, especificar explícitamente el language que el estudiante está intentando hablar es crucial. Esto se establece usando la variable target_language (por ejemplo, "fr" para francés).
- Esto asegura que Whisper interprete el audio usando el modelo fonético y de vocabulario correcto, proporcionando una transcripción más precisa para la retroalimentación.
Prompt opcional: El parámetro prompt puede usarse para dar contexto a Whisper sobre la sesión de práctica (por ejemplo, la frase específica que se está practicando), lo que puede mejorar la precisión del reconocimiento.
Inicialización y Función (transcribe_language_practice): Configuración estándar del cliente. La función requiere el parámetro language y realiza la transcripción usando client.audio.transcriptions.create.
Salida (response_format="text"): Se solicita la salida en texto plano ya que es el formato más directo para que los estudiantes o sistemas comparen con el texto esperado, analicen la gramática o revisen el vocabulario.
Mecanismo de Retroalimentación (Nota Importante): La explicación establece claramente que este script solo proporciona la transcripción. La retroalimentación real (puntuación de pronunciación, corrección gramatical, sugerencias de vocabulario) requiere procesamiento adicional. Este texto transcrito sirve como entrada para esos pasos de análisis posteriores, que podrían involucrar verificaciones basadas en reglas, algoritmos de comparación, o incluso alimentar el texto a otro LLM como GPT-4o para su análisis.
Relevancia del Caso de Uso: La sección de salida explica cómo esta transcripción permite los beneficios descritos: permitiendo a los estudiantes verificar su pronunciación contra el texto, proporcionando material para análisis de gramática/vocabulario, facilitando el seguimiento del progreso y apoyando la autocorrección.

Resumen

En esta sección, aprendiste varios aspectos clave del procesamiento y comprensión de audio:

Transcribir lenguaje hablado a texto usando Whisper
- Convertir varios formatos de audio en transcripciones de texto precisas
- Manejar múltiples idiomas y acentos con alta precisión
- Procesar efectivamente tanto clips cortos como grabaciones largas
Traducir audio en idioma extranjero al inglés
- Convertir habla no inglesa directamente a texto en inglés
- Mantener el contexto y significado a través de las barreras del idioma
- Soportar procesamiento de contenido multilingüe
Elegir entre salidas de texto plano, JSON y subtítulos
- Seleccionar el formato más apropiado para tu caso de uso específico
- Generar subtítulos con marcas de tiempo precisas
- Estructurar datos en formato JSON legible por máquina
Aplicar estas herramientas en casos de uso del mundo real como accesibilidad, educación y creación de contenido
- Crear contenido accesible con transcripciones precisas
- Apoyar el aprendizaje de idiomas e iniciativas educativas
- Optimizar flujos de trabajo de producción de contenido

2.2 Transcripción y Traducción con la API de Whisper

2.2.1 ¿Qué es Whisper?

Whisper demuestra una versatilidad excepcional a través de numerosas aplicaciones:

Transcripciones de reuniones o podcasts

Archivar reuniones importantes para consultas futuras
Crear versiones accesibles de contenido de audio
Permitir búsquedas rápidas a través de horas de contenido grabado
Generar documentación escrita a partir de discusiones verbales
Apoyar requisitos de cumplimiento para el mantenimiento de registros

La alta tasa de precisión asegura que los términos técnicos, nombres propios y discusiones complejas se capturen correctamente mientras se mantiene el flujo natural de la conversación.

Ejemplo:

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/meeting_snippet.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt
current_location = "Houston, Texas, United States"
print(f"Running Whisper transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'meeting_snippet.mp3' with the actual filename.
audio_file_path = "meeting_snippet.mp3"

# --- Optional Parameters for potentially better accuracy ---
# Specify language (ISO-639-1 code) if known, otherwise Whisper auto-detects.
# Example: "en" for English, "es" for Spanish, "de" for German
known_language = "en" # Set to None to auto-detect

# Provide a prompt with context, names, or jargon expected in the audio.
# This helps Whisper recognize specific terms accurately.
transcription_prompt = "The discussion involves Project Phoenix, stakeholders like Dr. Evelyn Reed and ACME Corp, and technical terms such as multi-threaded processing and cloud-native architecture." # Set to None if no prompt needed

# --- Function to Transcribe Audio ---
def transcribe_audio(client, file_path, language=None, prompt=None):
    """
    Transcribes the given audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Check file size (optional but good practice)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            print("Consider splitting the file into smaller chunks.")
            # You might choose to exit here or attempt anyway
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        return None


    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Optional: Specify language
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the string
            transcription_text = response
            print("Transcription successful.")
            return transcription_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        # Provide hints for common errors
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (mp3, mp4, mpeg, mpga, m4a, wav, webm).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit. Please split the file.")
        return None
    except FileNotFoundError: # Already handled above, but good practice
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcription = transcribe_audio(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription:
        print("\n--- Transcription Result ---")
        print(transcription)
        print("----------------------------\n")

        # How this helps the use case:
        print("This plain text transcription can now be:")
        print("- Saved as a text document (.txt) for archiving.")
        print("- Indexed and searched easily for specific keywords or names.")
        print("- Used to generate meeting minutes or documentation.")
        print("- Copied into accessibility tools or documents.")
        print("- Stored for compliance record-keeping.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcription)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nTranscription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la transcripción de archivos de audio como grabaciones de reuniones o episodios de podcast utilizando la API Whisper de OpenAI. El objetivo es convertir el contenido hablado en texto preciso y consultable, atendiendo necesidades como el archivo, la accesibilidad y la documentación.
Requisitos previos: Requiere las bibliotecas openai y python-dotenv, una clave API de OpenAI configurada en un archivo .env, y un archivo de audio de muestra (meeting_snippet.mp3).
Requisitos del archivo de audio: El script destaca los formatos de audio compatibles (MP3, WAV, M4A, etc.) y el límite crucial de 25MB por solicitud de API. Incluye una advertencia y explicación de que los archivos más largos deben segmentarse antes del procesamiento, aunque el código en sí maneja un solo archivo dentro del límite.
Inicialización: Configura el cliente estándar OpenAI utilizando la clave API.
Función de transcripción (transcribe_audio):
- Toma los argumentos client, file_path, y los opcionales language y prompt.
- Incluye una verificación de existencia y tamaño del archivo.
- Abre el archivo de audio en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.transcriptions.create con:
  - model="whisper-1": Especifica el modelo conocido por su alta precisión.
  - file=audio_file: Pasa el objeto de archivo abierto.
  - language: Opcionalmente proporciona el código de idioma (por ejemplo, "en") para potencialmente mejorar la precisión si se conoce el idioma. Si es None, Whisper detecta automáticamente.
  - prompt: Opcionalmente proporciona palabras clave contextuales, nombres (como "Project Phoenix", "Dr. Evelyn Reed"), o jerga. Esto ayuda significativamente a Whisper a transcribir con precisión términos especializados que se encuentran frecuentemente en reuniones o podcasts técnicos, abordando directamente la necesidad de capturar correctamente discusiones complejas.
  - response_format="text": Solicita la salida directamente como una cadena de texto plano, ideal para uso inmediato en documentos, indexación de búsqueda, etc. Se podrían solicitar otros formatos como verbose_json (para marcas de tiempo) o srt/vtt (para subtítulos) si fuera necesario.
- Manejo de errores: Incluye bloques try...except para errores de API (proporcionando sugerencias para problemas comunes como tamaño o formato de archivo) y errores del sistema de archivos.
Salida y utilidad:
- Se imprime el texto de transcripción resultante.
- El código conecta explícitamente esta salida con los beneficios del caso de uso: crear archivos consultables, generar documentación, apoyar la accesibilidad y permitir el cumplimiento normativo.
- Incluye un paso opcional para guardar la transcripción directamente en un archivo .txt.

Conversión de notas de voz

Transforma los mensajes de voz rápidos en notas de texto organizadas, facilitando la revisión y el archivo de pensamientos hablados. Esta funcionalidad es particularmente valiosa para:

Crear recordatorios rápidos y listas de tareas mientras se está en movimiento
Capturar ideas creativas o sesiones de lluvia de ideas sin interrumpir el flujo de pensamiento
Tomar notas durante trabajo de campo o visitas al sitio donde escribir es poco práctico
Documentar observaciones o hallazgos de investigación en tiempo real

El sistema mantiene el flujo natural del habla mientras organiza el contenido en texto claro y legible que puede ser fácilmente buscado, compartido o integrado en otros documentos.

Ejemplo:

Este script se centra en tomar un archivo de audio típico de nota de voz y convertirlo en texto consultable y utilizable, ideal para capturar ideas, recordatorios o notas de campo.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/voice_memo.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Miami, Florida, United States"
print(f"Running Whisper voice note transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local voice note audio file
# IMPORTANT: Replace 'voice_memo.m4a' with the actual filename.
audio_file_path = "voice_memo.mp3"

# --- Optional Parameters (Often not needed for simple voice notes) ---
# Language auto-detection is usually sufficient for voice notes.
known_language = None # Set to "en", "es", etc. if needed

# Prompt is useful if your notes contain specific jargon/names, otherwise leave as None.
transcription_prompt = None # Example: "Remember to mention Project Chimera and the client ZetaCorp."

# --- Function to Transcribe Voice Note ---
def transcribe_voice_note(client, file_path, language=None, prompt=None):
    """
    Transcribes the given voice note audio file using the Whisper API.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str, optional): The language code (ISO-639-1). Defaults to None (auto-detect).
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The transcription text, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe voice note: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size (less likely to be an issue for voice notes)
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None # Decide if you want to stop for large files
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        # Continue attempt even if size check fails
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending voice note to Whisper API for transcription...")

            # --- Make the API Call ---
            response = client.audio.transcriptions.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                language=language,          # Defaults to None (auto-detect)
                prompt=prompt,              # Defaults to None
                response_format="text"      # Request plain text output for easy use as notes
            )

            # The response object for "text" format is directly the string
            note_text = response
            print("Transcription successful.")
            return note_text

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported (m4a, mp3, wav, etc.).")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_note = transcribe_voice_note(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcribed_note:
        print("\n--- Transcribed Voice Note Text ---")
        print(transcribed_note)
        print("-----------------------------------\n")

        # How this helps the use case:
        print("This transcribed text from your voice note can be easily:")
        print("- Copied into reminder apps or to-do lists.")
        print("- Saved as a text file for archiving creative ideas or brainstorms.")
        print("- Searched later for specific keywords or topics.")
        print("- Shared via email or messaging apps.")
        print("- Integrated into reports or documentation (e.g., field notes).")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_note)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nVoice note transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para transcribir grabaciones de audio cortas como notas de voz y memorandos. Es ideal para capturar rápidamente pensamientos, ideas, recordatorios u observaciones de campo y convertirlos en texto fácilmente manejable.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y un archivo de audio de muestra de nota de voz (se admiten formatos comunes como .m4a, .mp3, .wav).
Manejo de archivos de audio: El script enfatiza que las notas de voz típicamente están muy por debajo del límite de 25MB de la API. Abre el archivo en modo de lectura binaria ("rb").
Inicialización: Configura el cliente OpenAI.
Función de transcripción (transcribe_voice_note):
- Similar a la función de transcripción de reuniones pero adaptada para notas de voz.
- Valores predeterminados: Establece language como None (detección automática) y prompt como None, ya que estos suelen ser suficientes para notas de voz típicas donde la jerga específica puede ser menos común. El usuario aún puede proporcionarlos si es necesario.
- Llamada a la API: Utiliza client.audio.transcriptions.create con model="whisper-1".
- response_format="text": Solicita explícitamente la salida en texto plano, que es el formato más práctico para notas – fácil de leer, buscar, copiar y compartir.
- Manejo de errores: Incluye bloques estándar try...except para errores de API y archivo.
Salida y utilidad:
- Imprime la transcripción de texto resultante.
- Conecta explícitamente la salida con los beneficios mencionados en la descripción del caso de uso: crear recordatorios/tareas pendientes, capturar ideas, documentar observaciones, permitir búsquedas y compartir.
- Incluye un paso opcional para guardar la nota transcrita en un archivo .txt.

Traducción de voz multilingüe

Elimina las barreras lingüísticas proporcionando traducciones precisas mientras preserva el contexto y significado original. Esta potente característica permite:

Comunicación en tiempo real superando barreras lingüísticas en reuniones y conferencias internacionales
Traducción de contenido educativo para audiencias globales manteniendo la integridad académica
Negociaciones comerciales interculturales con traducción precisa de términos técnicos y matices culturales
Traducción de documentación para organizaciones multinacionales con terminología consistente

Ejemplo:

Este ejemplo toma un archivo de audio que contiene habla en un idioma distinto del inglés y lo traduce directamente a texto en inglés.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/spanish_speech.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Denver, Colorado, United States"
print(f"Running Whisper speech translation example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local non-English audio file
# IMPORTANT: Replace 'spanish_speech.mp3' with the actual filename.
audio_file_path = "spanish_speech.mp3"

# --- Optional Parameters ---
# Prompt can help guide recognition of specific names/terms in the SOURCE language
# before translation, potentially improving accuracy of the final English text.
translation_prompt = None # Example: "The discussion mentions La Sagrada Familia and Parc Güell."

# --- Function to Translate Speech to English ---
def translate_speech_to_english(client, file_path, prompt=None):
    """
    Translates speech from the given audio file into English using the Whisper API.
    The source language is automatically detected.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (non-English speech).
        prompt (str, optional): A text prompt to guide source language recognition. Defaults to None.

    Returns:
        str: The translated English text, or None if an error occurs.
    """
    print(f"\nAttempting to translate speech from audio file: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: Check file size
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Translation may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for translation to English...")

            # --- Make the API Call for Translation ---
            # Note: Using the 'translations' endpoint, not 'transcriptions'
            response = client.audio.translations.create(
                model="whisper-1",          # Specify the Whisper model
                file=audio_file,            # The audio file object
                prompt=prompt,              # Optional: Provide context prompt
                response_format="text"      # Request plain text English output
                                            # Other options: 'json', 'verbose_json', 'srt', 'vtt'
            )

            # The response object for "text" format is directly the translated string
            translated_text = response
            print("Translation successful.")
            return translated_text

    except OpenAIError as e:
        print(f"OpenAI API Error during translation: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        # Whisper might error if it cannot detect speech or supported language
        elif "language could not be detected" in str(e).lower():
             print("Hint: Ensure the audio contains detectable speech in a supported language.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during translation: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    english_translation = translate_speech_to_english(
        client,
        audio_file_path,
        prompt=translation_prompt
    )

    if english_translation:
        print("\n--- Translated English Text ---")
        print(english_translation)
        print("-------------------------------\n")

        # How this helps the use case:
        print("This English translation enables:")
        print("- Understanding discussions from international meetings.")
        print("- Making educational content accessible to English-speaking audiences.")
        print("- Facilitating cross-cultural business communication.")
        print("- Creating English versions of documentation originally recorded in other languages.")
        print("- Quick communication across language barriers using voice input.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_translation_en.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(english_translation)
            print(f"Translation saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving translation to file: {e}")

    else:
        print("\nSpeech translation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra la capacidad de la API de Whisper para realizar traducción de voz a texto, específicamente traduciendo audio de varios idiomas de origen directamente a texto en inglés. Esto aborda la necesidad de eliminar las barreras lingüísticas en escenarios de comunicación global.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API y, fundamentalmente, un archivo de audio de muestra que contenga voz en un idioma que no sea inglés (por ejemplo, español, francés, alemán).
Punto final de API clave: Este ejemplo utiliza client.audio.translations.create, que es distinto del punto final transcriptions usado anteriormente. El punto final de translations está específicamente diseñado para generar texto en inglés.
Detección automática de idioma: Una característica clave destacada es que no es necesario especificar el idioma de origen del archivo de audio; Whisper lo detecta automáticamente antes de traducir al inglés.
Inicialización: Configura el cliente OpenAI.
Función de traducción (translate_speech_to_english):
- Toma el client, file_path, y un prompt opcional.
- Abre el archivo de audio no inglés en modo de lectura binaria ("rb").
- Llamada a la API: Utiliza client.audio.translations.create con:
  - model="whisper-1": El modelo estándar de Whisper.
  - file=audio_file: El objeto del archivo de audio.
  - prompt: Opcionalmente proporciona contexto (en el idioma de origen o inglés, frecuentemente ayuda con nombres/términos) para ayudar al reconocimiento preciso antes de la traducción, ayudando a preservar matices y términos técnicos.
  - response_format="text": Solicita salida de texto en inglés simple.
- Manejo de errores: Incluye bloques try...except, señalando posibles errores si no se detecta voz o un idioma compatible en el audio.
Salida y utilidad:
- Imprime el texto traducido al inglés resultante.
- Conecta explícitamente esta salida con los beneficios descritos en el caso de uso: permitir la comprensión en reuniones internacionales, traducir contenido educativo/empresarial para audiencias globales y facilitar la documentación y comunicación entre idiomas.
- Muestra cómo guardar opcionalmente la traducción al inglés en un archivo .txt.

Herramientas de accesibilidad

Permite una mejor inclusión digital al proporcionar servicios de transcripción en tiempo real para usuarios con discapacidad auditiva, ofreciendo varios beneficios clave:

Permite a las personas sordas y con dificultades auditivas participar plenamente en contenido basado en audio
Proporciona acceso instantáneo a información hablada en entornos profesionales como reuniones y conferencias
Apoya entornos educativos haciendo accesibles las clases y discusiones para todos los estudiantes
Mejora el consumo de medios al permitir subtitulado preciso en tiempo real para videos y transmisiones en vivo

Ejemplo:

Este ejemplo se centra en utilizar el formato de salida verbose_json para obtener marcas de tiempo a nivel de segmento, que son esenciales para sincronizar texto con audio o video.

Descarga el audio de muestra aquí: https://files.cuantum.tech/audio/lecture_snippet.mp3

import os
import json # To potentially parse the verbose_json output nicely
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Atlanta, Georgia, United States" # User location context
print(f"Running Whisper accessibility transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file
# IMPORTANT: Replace 'lecture_snippet.mp3' with the actual filename.
audio_file_path = "lecture_snippet.mp3"

# --- Optional Parameters ---
# Specifying language is often good for accuracy in accessibility contexts
known_language = "en"

# Prompt can help with specific terminology in lectures or meetings
transcription_prompt = "The lecture discusses quantum entanglement, superposition, and Bell's theorem." # Set to None if not needed

# --- Function to Transcribe Audio with Timestamps ---
def transcribe_for_accessibility(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper, requesting timestamped output
    suitable for accessibility applications (e.g., captioning).

    Note on 'Real-time': This function processes a complete file. True real-time
    captioning requires capturing audio in chunks, sending each chunk to the API
    quickly, and displaying the results sequentially. This example generates the
    *type* of data needed for such applications from a pre-recorded file.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        dict: The parsed verbose_json response containing text and segments
              with timestamps, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe for accessibility: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for timestamped transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                # Request detailed JSON output including timestamps
                response_format="verbose_json",
                # Explicitly request segment-level timestamps
                timestamp_granularities=["segment"]
            )

            # The response object is already a Pydantic model behaving like a dict
            timestamped_data = response
            print("Timestamped transcription successful.")
            # You can access response.text, response.segments etc directly
            return timestamped_data

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Function to Format Timestamps ---
def format_timestamp(seconds):
    """Converts seconds to HH:MM:SS.fff format."""
    td = datetime.timedelta(seconds=seconds)
    total_milliseconds = int(td.total_seconds() * 1000)
    hours, remainder = divmod(total_milliseconds, 3600000)
    minutes, remainder = divmod(remainder, 60000)
    seconds, milliseconds = divmod(remainder, 1000)
    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"

# --- Main Execution ---
if __name__ == "__main__":
    transcription_data = transcribe_for_accessibility(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if transcription_data:
        print("\n--- Full Transcription Text ---")
        # Access the full text directly from the response object
        print(transcription_data.text)
        print("-------------------------------\n")

        print("--- Transcription Segments with Timestamps ---")
        # Iterate through segments for timestamped data
        for segment in transcription_data.segments:
            start_time = format_timestamp(segment['start'])
            end_time = format_timestamp(segment['end'])
            segment_text = segment['text']
            print(f"[{start_time} --> {end_time}] {segment_text}")
        print("---------------------------------------------\n")

        # How this helps the use case:
        print("This timestamped data enables:")
        print("- Displaying captions synchronized with video or audio streams.")
        print("- Highlighting text in real-time as it's spoken in meetings or lectures.")
        print("- Creating accessible versions of educational/media content.")
        print("- Allowing users to navigate audio by clicking on text segments.")
        print("- Fuller participation for hearing-impaired individuals.")

        # Optional: Save the detailed JSON output
        output_json_file = os.path.splitext(audio_file_path)[0] + "_timestamps.json"
        try:
            # The response object can be converted to dict for JSON serialization
            with open(output_json_file, "w", encoding="utf-8") as f:
                 # Use .model_dump_json() for Pydantic V2 models from openai>=1.0.0
                 # or .dict() for older versions/models
                 try:
                      f.write(transcription_data.model_dump_json(indent=2))
                 except AttributeError:
                      # Fallback for older versions or different object types
                      import json
                      f.write(json.dumps(transcription_data, default=lambda o: o.__dict__, indent=2))

            print(f"Detailed timestamp data saved to '{output_json_file}'")
        except (IOError, TypeError, AttributeError) as e:
            print(f"Error saving timestamp data to JSON file: {e}")

    else:
        print("\nTranscription for accessibility failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper para generar transcripciones altamente precisas con marcas de tiempo a nivel de segmento. Esta salida es crucial para aplicaciones de accesibilidad, permitiendo funciones como subtitulado en tiempo real, resaltado sincronizado de texto y transcripciones navegables para usuarios con dificultades auditivas.
Requisitos previos: Configuración estándar (openai, python-dotenv, clave API) y un archivo de audio (lecture_snippet.mp3).
Parámetros clave de la API:
- Endpoint: Utiliza client.audio.transcriptions.create.
- response_format="verbose_json": Esto es esencial. Solicita un objeto JSON detallado que contiene no solo el texto completo de la transcripción sino también una lista de segmentos, cada uno con tiempos de inicio/fin y el texto correspondiente.
- timestamp_granularities=["segment"]: Solicita explícitamente información de tiempo a nivel de segmento (aunque suele incluirse por defecto con verbose_json). Las marcas de tiempo a nivel de palabra también pueden solicitarse si es necesario (["word"]), pero los segmentos se utilizan típicamente para el subtitulado.
- language / prompt: Especificar el idioma (en) y proporcionar un prompt puede mejorar la precisión, lo cual es vital para la accesibilidad.
Consideración sobre "Tiempo Real": La explicación aclara que si bien este código procesa un archivo, la salida con marcas de tiempo que genera es lo que se necesita para aplicaciones en tiempo real. El subtitulado verdaderamente en vivo requeriría enviar fragmentos de audio a la API rápidamente.
Inicialización y Función (transcribe_for_accessibility): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando verbose_json.
Procesamiento de Salida:
- El código primero imprime el texto concatenado completo (transcription_data.text).
- Luego itera a través de la lista transcription_data.segments.
- Para cada segment, extrae el tiempo de start, tiempo de end, y text.
- Una función auxiliar (format_timestamp) convierte los tiempos (en segundos) a un formato estándar HH:MM:SS.fff.
- Imprime cada segmento con su información de tiempo (por ejemplo, [00:00:01.234 --> 00:00:05.678] Este es el texto del primer segmento.).
Relevancia del Caso de Uso: La salida muestra claramente cómo estos datos con marcas de tiempo permiten directamente los beneficios descritos: sincronización de texto con audio/video para subtítulos, permitiendo la participación en reuniones/conferencias, haciendo el contenido educativo accesible y mejorando el consumo de medios.
Guardado de Salida: Incluye una opción para guardar la respuesta completa verbose_json en un archivo para uso posterior o procesamiento más complejo. Maneja las posibles diferencias en la serialización del objeto de respuesta de la biblioteca openai.

Flujos de trabajo de subtitulado de video

Creadores de contenido que necesitan hacer sus videos accesibles en múltiples plataformas
Empresas de radiodifusión que requieren subtítulos cerrados precisos para cumplimiento regulatorio
Instituciones educativas que crean contenido de video accesible para poblaciones estudiantiles diversas
Gestores de redes sociales que desean aumentar el engagement de videos mediante subtitulado automático

Ejemplo:

Este ejemplo de código toma un archivo de audio (que típicamente extraerías primero de tu video) y usa Whisper para crear subtítulos con marcas de tiempo precisas en el formato estándar .srt.

Descarga la muestra de audio aquí: https://files.cuantum.tech/audio/video_audio.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Austin, Texas, United States" # User location context
print(f"Running Whisper caption generation (SRT) example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# Define the path to your local audio file (extracted from video)
# IMPORTANT: Replace 'video_audio.mp3' with the actual filename.
audio_file_path = "video_audio.mp3"

# --- Optional Parameters ---
# Specifying language can improve caption accuracy
known_language = "en"

# Prompt can help with names, brands, or specific terminology in the video
transcription_prompt = "The video features interviews with Dr. Anya Sharma about sustainable agriculture and mentions the company 'TerraGrow'." # Set to None if not needed

# --- Function to Generate SRT Captions ---
def generate_captions_srt(client, file_path, language="en", prompt=None):
    """
    Transcribes the audio file using Whisper and returns captions in SRT format.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file (extracted from video).
        language (str): The language code (ISO-639-1). Defaults to "en".
        prompt (str, optional): A text prompt to guide transcription. Defaults to None.

    Returns:
        str: The caption data in SRT format string, or None if an error occurs.
    """
    print(f"\nAttempting to generate SRT captions for: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
            # return None
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass # Continue attempt

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print("Sending audio file to Whisper API for SRT caption generation...")

            # --- Make the API Call for Transcription ---
            # Request 'srt' format directly
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language,
                prompt=prompt,
                response_format="srt" # Request SRT format output
                # Other options include "vtt"
            )

            # The response object for "srt" format is directly the SRT string
            srt_content = response
            print("SRT caption generation successful.")
            return srt_content

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    srt_captions = generate_captions_srt(
        client,
        audio_file_path,
        language=known_language,
        prompt=transcription_prompt
    )

    if srt_captions:
        # --- Save the SRT Content to a File ---
        output_srt_file = os.path.splitext(audio_file_path)[0] + ".srt"
        try:
            with open(output_srt_file, "w", encoding="utf-8") as f:
                f.write(srt_captions)
            print(f"\nSRT captions saved successfully to '{output_srt_file}'")

            # How this helps the use case:
            print("\nThis SRT file can be used to:")
            print("- Add closed captions or subtitles to video players (like YouTube, Vimeo, VLC).")
            print("- Import into video editing software for caption integration.")
            print("- Meet accessibility requirements and regulatory compliance (e.g., broadcasting).")
            print("- Improve video engagement on social media platforms.")
            print("- Make educational video content accessible to more students.")

        except IOError as e:
            print(f"Error saving SRT captions to file: {e}")

    else:
        print("\nSRT caption generation failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra cómo usar la API de Whisper para agilizar los flujos de trabajo de subtitulado de video mediante la generación directa de archivos de subtítulos SRT (SubRip Text) en formato estándar de la industria a partir del audio.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv y la clave API. Es crucial que requiera un archivo de audio que se haya extraído del video objetivo. El script incluye una nota que explica este paso necesario de preprocesamiento.
Parámetro clave de API (response_format="srt"):
- El núcleo de este caso de uso es solicitar el formato srt directamente desde el endpoint client.audio.transcriptions.create.
- Esto indica a Whisper que formatee la salida según las especificaciones SRT, incluyendo numeración secuencial, marcas de tiempo de inicio/fin (por ejemplo, 00:00:20,000 --> 00:00:24,400), y el fragmento de texto correspondiente. La API maneja la sincronización de tiempos automáticamente. vtt (WebVTT) es otro formato común que se puede solicitar de manera similar.
Inicialización y Función (generate_captions_srt): Configuración estándar del cliente. La función encapsula la llamada a la API solicitando específicamente el formato SRT. Los parámetros opcionales language y prompt pueden usarse para mejorar la precisión.
Manejo de Salida:
- La response de la llamada a la API (cuando response_format="srt") es directamente el contenido completo del archivo SRT como una única cadena de texto.
- El código luego guarda esta cadena directamente en un archivo con la extensión .srt.
Relevancia para el Caso de Uso:
- La explicación destaca cómo este archivo .srt generado sirve directamente a las necesidades de creadores de contenido, emisoras, educadores y gestores de redes sociales.
- Puede cargarse fácilmente en plataformas de video, importarse a software de edición o usarse para cumplir con estándares de accesibilidad y normativas. Simplifica significativamente el proceso tradicionalmente laborioso de creación manual de subtítulos.
Manejo de Errores: Incluye verificaciones estándar para errores de API y del sistema de archivos.

💡 Consejo: Whisper funciona mejor cuando el audio es claro y admite archivos de entrada de hasta 25MB por solicitud.

2.2.2 Formatos de Respuesta que Puedes Usar

Whisper admite múltiples formatos para tus necesidades:

2.2.3 Aplicaciones Prácticas de Whisper

Herramientas para Toma de Notas

Esta herramienta es particularmente valiosa para:

Estudiantes que capturan notas detalladas de clase mientras mantienen su participación en las discusiones
Periodistas que documentan entrevistas y conferencias de prensa con citas precisas
Profesionales de negocios que mantienen registros exactos de reuniones con clientes y sesiones de lluvia de ideas en equipo
Investigadores que realizan y transcriben entrevistas cualitativas

Negocios Internacionales: Facilita la comunicación en tiempo real en reuniones multinacionales, negociaciones y presentaciones sin necesidad de intérpretes humanos
Viajes y Turismo: Permite a los viajeros comunicarse efectivamente con los locales, entender anuncios y navegar en entornos extranjeros
Educación Global: Apoya programas de aprendizaje a distancia e intercambios estudiantiles internacionales al eliminar las barreras del idioma
Servicio al Cliente: Permite a los equipos de soporte asistir a los clientes en su idioma preferido, mejorando la calidad del servicio y la satisfacción

Soluciones de Accesibilidad

Subtitulado en Tiempo Real: Proporciona representación textual inmediata de palabras habladas durante eventos en vivo, reuniones y presentaciones
Transcripción Precisa: Genera registros escritos detallados del contenido de audio para referencia y estudio posterior
Soporte Multi-formato: Ofrece contenido en varios formatos incluyendo subtítulos cerrados, subtítulos y transcripciones descargables

Esta tecnología puede integrarse en:

Plataformas de Videoconferencia: Habilitando subtítulos en tiempo real durante reuniones virtuales y seminarios web
Plataformas Educativas: Apoyando a estudiantes con discapacidad auditiva tanto en entornos en línea como en aulas tradicionales
Reproductores Multimedia: Proporcionando subtítulos sincronizados para videos, podcasts y otros contenidos multimedia
Eventos en Vivo: Ofreciendo pantallas de texto en tiempo real durante conferencias, actuaciones y eventos de oratoria pública

Estas características de accesibilidad no solo apoyan a personas con discapacidad auditiva, sino que también benefician a:

Hablantes no nativos que prefieren leer mientras escuchan
Personas en entornos sensibles al sonido donde el audio no es práctico
Personas con aprendizaje visual que procesan mejor la información a través del texto
Organizaciones que buscan cumplir con regulaciones y estándares de accesibilidad

Mejora de Podcasts
Convierte contenido de audio en formatos de texto buscables mediante transcripción integral, permitiendo múltiples beneficios:

Descubrimiento de Contenido: Los oyentes pueden buscar fácilmente en las transcripciones de episodios para encontrar temas específicos, citas o discusiones de interés
Reutilización de Contenido: Los creadores pueden extraer citas clave y perspectivas para redes sociales, publicaciones de blog o boletines
Accesibilidad: Hace que el contenido esté disponible para audiencias con discapacidad auditiva y aquellos que prefieren leer
Beneficios SEO: Los motores de búsqueda pueden indexar el contenido completo de los episodios, mejorando la visibilidad y el tráfico orgánico
Participación Mejorada: Los lectores pueden explorar el contenido antes de escuchar, marcar secciones importantes y consultar material posteriormente
Perspectivas Analíticas: Analiza los términos más buscados y segmentos populares para informar la estrategia de contenido futura

Retroalimentación de Pronunciación en Tiempo Real: Los estudiantes pueden comparar sus palabras habladas con el texto transcrito para identificar errores de pronunciación y áreas de mejora
Análisis Gramatical: El sistema puede resaltar estructuras gramaticales y posibles errores en el texto transcrito, ayudando a los estudiantes a entender sus errores
Mejora de Vocabulario: Los estudiantes pueden hacer seguimiento de su uso activo del vocabulario y recibir sugerencias para elecciones de palabras más variadas

La tecnología beneficia particularmente a:

Estudiantes autodidactas que practican independientemente
Profesores de idiomas que dan seguimiento al progreso de los estudiantes
Plataformas de aprendizaje de idiomas en línea que ofrecen práctica de habla
Participantes de intercambio de idiomas que desean verificar su comunicación

Ejemplo:

Descarga el archivo de audio de muestra aquí: https://files.cuantum.tech/audio/language_practice_fr.mp3

import os
from openai import OpenAI, OpenAIError
from dotenv import load_dotenv
import datetime

# --- Configuration ---
# Load environment variables (especially OPENAI_API_KEY)
load_dotenv()

# Get the current date and location context
current_timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S %Z")
# Location context from user prompt history/context block
current_location = "Orlando, Florida, United States" # User location context
print(f"Running Whisper language learning transcription example at: {current_timestamp}")
print(f"Location Context: {current_location}")


# Initialize the OpenAI client
try:
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables. Please set it in your .env file or environment.")
    client = OpenAI(api_key=api_key)
    print("OpenAI client initialized.")
except ValueError as e:
    print(f"Configuration Error: {e}")
    exit()
except Exception as e:
    print(f"Error initializing OpenAI client: {e}")
    exit()

# --- Language Learning Specific Configuration ---

# Define the path to the language practice audio file
# IMPORTANT: Replace 'language_practice_fr.mp3' with the actual filename.
audio_file_path = "language_practice_fr.mp3"

# ** CRUCIAL: Specify the language being spoken in the audio file **
# Use the correct ISO-639-1 code (e.g., "en", "es", "fr", "de", "ja", "zh")
# This tells Whisper how to interpret the sounds.
target_language = "fr" # Example: French

# Optional: Provide context about the practice session (e.g., the expected phrase)
# This can help improve accuracy, especially for specific vocabulary or sentences.
practice_prompt = "The student is practicing ordering food at a French cafe, mentioning croissants and coffee." # Set to None if not needed

# --- Function to Transcribe Language Practice Audio ---
def transcribe_language_practice(client, file_path, language, prompt=None):
    """
    Transcribes audio of language practice using the Whisper API.
    Specifying the target language is crucial for this use case.

    Args:
        client: The initialized OpenAI client.
        file_path (str): The path to the audio file.
        language (str): The ISO-639-1 code of the language being spoken.
        prompt (str, optional): A text prompt providing context. Defaults to None.

    Returns:
        str: The transcribed text in the target language, or None if an error occurs.
    """
    print(f"\nAttempting to transcribe language practice ({language}) from: {file_path}")
    if not os.path.exists(file_path):
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    if not language:
        print("Error: Target language must be specified for language learning transcription.")
        return None

    # Optional: File size check
    try:
        file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
        print(f"File size: {file_size_mb:.2f} MB")
        if file_size_mb > 25:
            print("Warning: File size exceeds 25MB limit. Transcription may fail.")
    except OSError as e:
        print(f"Error accessing file properties: {e}")
        pass

    try:
        # Open the audio file in binary read mode
        with open(file_path, "rb") as audio_file:
            print(f"Sending audio ({language}) to Whisper API for transcription...")

            # --- Make the API Call for Transcription ---
            response = client.audio.transcriptions.create(
                model="whisper-1",
                file=audio_file,
                language=language, # Pass the specified target language
                prompt=prompt,
                response_format="text" # Get plain text for easy comparison/analysis
            )

            # The response object for "text" format is directly the string
            practice_transcription = response
            print("Transcription successful.")
            return practice_transcription

    except OpenAIError as e:
        print(f"OpenAI API Error during transcription: {e}")
        if "invalid_file_format" in str(e):
            print("Hint: Ensure the audio file format is supported.")
        elif "maximum file size" in str(e).lower():
            print("Hint: The audio file exceeds the 25MB size limit.")
        elif "invalid language code" in str(e).lower():
             print(f"Hint: Check if '{language}' is a valid ISO-639-1 language code supported by Whisper.")
        return None
    except FileNotFoundError:
        print(f"Error: Audio file not found at '{file_path}'")
        return None
    except Exception as e:
        print(f"An unexpected error occurred during transcription: {e}")
        return None

# --- Main Execution ---
if __name__ == "__main__":
    transcribed_text = transcribe_language_practice(
        client,
        audio_file_path,
        language=target_language,
        prompt=practice_prompt
    )

    if transcribed_text:
        print("\n--- Transcribed Practice Text ---")
        print(f"(Language: {target_language})")
        print(transcribed_text)
        print("---------------------------------\n")

        # How this helps the use case:
        print("This transcription provides the basis for language learning feedback:")
        print("- **Pronunciation Check:** Learner compares their speech to the text, identifying discrepancies.")
        print("- **Grammar/Vocabulary Analysis:** This text can be compared against expected sentences or analyzed (potentially by another AI like GPT-4o, or specific tools) for grammatical correctness and vocabulary usage.")
        print("- **Progress Tracking:** Teachers or platforms can store transcriptions to monitor improvement over time.")
        print("- **Self-Correction:** Learners get immediate textual representation of their speech for review.")
        print("\nNote: Further analysis (grammar checking, pronunciation scoring, etc.) requires additional logic beyond this transcription step.")

        # Optional: Save to a file
        output_txt_file = os.path.splitext(audio_file_path)[0] + "_transcription.txt"
        try:
            with open(output_txt_file, "w", encoding="utf-8") as f:
                f.write(transcribed_text)
            print(f"Transcription saved to '{output_txt_file}'")
        except IOError as e:
            print(f"Error saving transcription to file: {e}")

    else:
        print("\nLanguage practice transcription failed. Please check error messages above.")

Desglose del código:

Contexto: Este código demuestra el uso de la API de Whisper como herramienta de apoyo para el aprendizaje de idiomas. Transcribe grabaciones de audio de un estudiante hablando un idioma objetivo, proporcionando el texto de salida esencial necesario para varios mecanismos de retroalimentación.
Requisitos previos: Requiere la configuración estándar de openai y python-dotenv, clave API, y un archivo de audio que contenga la práctica hablada del estudiante en el idioma objetivo (por ejemplo, language_practice_fr.mp3).
Parámetro clave (language):
- A diferencia de la transcripción general donde la detección automática podría ser suficiente, para el aprendizaje de idiomas, especificar explícitamente el language que el estudiante está intentando hablar es crucial. Esto se establece usando la variable target_language (por ejemplo, "fr" para francés).
- Esto asegura que Whisper interprete el audio usando el modelo fonético y de vocabulario correcto, proporcionando una transcripción más precisa para la retroalimentación.
Prompt opcional: El parámetro prompt puede usarse para dar contexto a Whisper sobre la sesión de práctica (por ejemplo, la frase específica que se está practicando), lo que puede mejorar la precisión del reconocimiento.
Inicialización y Función (transcribe_language_practice): Configuración estándar del cliente. La función requiere el parámetro language y realiza la transcripción usando client.audio.transcriptions.create.
Salida (response_format="text"): Se solicita la salida en texto plano ya que es el formato más directo para que los estudiantes o sistemas comparen con el texto esperado, analicen la gramática o revisen el vocabulario.
Mecanismo de Retroalimentación (Nota Importante): La explicación establece claramente que este script solo proporciona la transcripción. La retroalimentación real (puntuación de pronunciación, corrección gramatical, sugerencias de vocabulario) requiere procesamiento adicional. Este texto transcrito sirve como entrada para esos pasos de análisis posteriores, que podrían involucrar verificaciones basadas en reglas, algoritmos de comparación, o incluso alimentar el texto a otro LLM como GPT-4o para su análisis.
Relevancia del Caso de Uso: La sección de salida explica cómo esta transcripción permite los beneficios descritos: permitiendo a los estudiantes verificar su pronunciación contra el texto, proporcionando material para análisis de gramática/vocabulario, facilitando el seguimiento del progreso y apoyando la autocorrección.

Resumen

En esta sección, aprendiste varios aspectos clave del procesamiento y comprensión de audio:

Transcribir lenguaje hablado a texto usando Whisper
- Convertir varios formatos de audio en transcripciones de texto precisas
- Manejar múltiples idiomas y acentos con alta precisión
- Procesar efectivamente tanto clips cortos como grabaciones largas
Traducir audio en idioma extranjero al inglés
- Convertir habla no inglesa directamente a texto en inglés
- Mantener el contexto y significado a través de las barreras del idioma
- Soportar procesamiento de contenido multilingüe
Elegir entre salidas de texto plano, JSON y subtítulos
- Seleccionar el formato más apropiado para tu caso de uso específico
- Generar subtítulos con marcas de tiempo precisas
- Estructurar datos en formato JSON legible por máquina
Aplicar estas herramientas en casos de uso del mundo real como accesibilidad, educación y creación de contenido
- Crear contenido accesible con transcripciones precisas
- Apoyar el aprendizaje de idiomas e iniciativas educativas
- Optimizar flujos de trabajo de producción de contenido

Compra este libro