Propósito
Esta habilidad automatiza la transcripción de audio a texto con salida Markdown profesional, extrayendo metadatos técnicos detallados (hablantes, marcas de tiempo, idioma, tamaño de archivo, duración) y generando actas de reuniones estructuradas y resúmenes ejecutivos. Utiliza Faster-Whisper o Whisper con configuración cero, funcionando universalmente en todos los proyectos sin rutas fijas ni claves API.
Inspirada en herramientas como Plaud, esta habilidad transforma grabaciones de audio sin procesar en documentación procesable, ideal para reuniones, entrevistas, conferencias y análisis de contenido.
Cuándo Usar
Invoca esta habilidad cuando:
- El usuario necesita transcribir archivos de audio/video a texto
- El usuario desea que se generen actas de reuniones automáticamente a partir de grabaciones
- El usuario requiere identificación de hablantes (diarización) en conversaciones
- El usuario necesita subtítulos (formatos SRT, VTT)
- El usuario desea resúmenes ejecutivos de contenido de audio extenso
- El usuario solicita variaciones de "transcribe este audio", "convierte audio a texto", "genera notas de reunión a partir de la grabación"
- El usuario tiene archivos de audio en formatos comunes (MP3, WAV, M4A, OGG, FLAC, WEBM)
Flujo de Trabajo
Paso 0: Descubrimiento (Detección Automática de Herramientas de Transcripción)
Objetivo: Identificar los motores de transcripción disponibles sin configuración del usuario.
Acciones:
Ejecutar comandos de detección para encontrar herramientas instaladas:
# Verificar Faster-Whisper (preferido - 4-5x más rápido)
if python3 -c "import faster_whisper" 2>/dev/null; then
TRANSCRIBER="faster-whisper"
echo "✅ Faster-Whisper detectado (optimizado)"
# Alternativa: Whisper original
elif python3 -c "import whisper" 2>/dev/null; then
TRANSCRIBER="whisper"
echo "✅ OpenAI Whisper detectado"
else
TRANSCRIBER="ninguno"
echo "⚠️ No se encontró herramienta de transcripción"
fi
# Verificar ffmpeg (conversión de formatos de audio)
if command -v ffmpeg &>/dev/null; then
echo "✅ ffmpeg disponible (conversión de formato habilitada)"
else
echo "ℹ️ ffmpeg no encontrado (soporte de formato limitado)"
fi
Si no se encuentra ningún transcriptor:
Ofrecer instalación automática usando el script proporcionado:
echo "⚠️ No se encontró herramienta de transcripción"
echo ""
echo "🔧 ¿Instalar dependencias automáticamente? (Recomendado)"
read -p "¿Ejecutar script de instalación? [S/n]: " AUTO_INSTALL
if [[ ! "$AUTO_INSTALL" =~ ^[Nn] ]]; then
# Obtener directorio de la habilidad (funciona tanto para instalaciones repo como enlazadas)
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Ejecutar script de instalación
if [[ -f "$SKILL_DIR/scripts/install-requirements.sh" ]]; then
bash "$SKILL_DIR/scripts/install-requirements.sh"
else
echo "❌ Script de instalación no encontrado"
echo ""
echo "📦 Instalación manual:"
echo " pip install faster-whisper # Recomendado"
echo " pip install openai-whisper # Alternativa"
echo " brew install ffmpeg # Opcional (macOS)"
exit 1
fi
# Verificar que la instalación fue exitosa
if python3 -c "import faster_whisper" 2>/dev/null || python3 -c "import whisper" 2>/dev/null; then
echo "✅ ¡Instalación exitosa! Procediendo con la transcripción..."
else
echo "❌ Instalación fallida. Por favor, instala manualmente."
exit 1
fi
else
echo ""
echo "📦 Se requiere instalación manual:"
echo ""
echo "Recomendado (más rápido):"
echo " pip install faster-whisper"
echo ""
echo "Alternativa (original):"
echo " pip install openai-whisper"
echo ""
echo "Opcional (conversión de formato):"
echo " brew install ffmpeg # macOS"
echo " apt install ffmpeg # Linux"
echo ""
exit 1
fi
Esto asegura que los usuarios puedan instalar dependencias con una confirmación, u optar por la instalación manual si lo prefieren.
Si se encuentra un transcriptor:
Proceder al Paso 0b (Detección de CLI).
Paso 1: Validar Archivo de Audio
Objetivo: Verificar que el archivo existe, comprobar el formato y extraer metadatos.
Acciones:
-
Aceptar ruta de archivo o URL del usuario:
- Archivo local:
meeting.mp3 - URL:
https://example.com/audio.mp3(descargar a directorio temporal)
- Archivo local:
-
Verificar que el archivo existe:
if [[ ! -f "$AUDIO_FILE" ]]; then
echo "❌ Archivo no encontrado: $AUDIO_FILE"
exit 1
fi
- Extraer metadatos usando ffprobe o utilidades de archivo:
# Obtener tamaño del archivo
FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)
# Obtener duración y formato usando ffprobe
DURATION=$(ffprobe -v error -show_entries format=duration \
-of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
FORMAT=$(ffprobe -v error -select_streams a:0 -show_entries \
stream=codec_name -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
# Convertir duración a HH:MM:SS
DURATION_HMS=$(date -u -r "$DURATION" +%H:%M:%S 2>/dev/null || echo "Desconocido")
- Verificar tamaño del archivo (advertir si es grande para APIs en la nube):
SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
if [[ $SIZE_MB -gt 25 ]]; then
echo "⚠️ Archivo grande ($FILE_SIZE) - el procesamiento puede tomar varios minutos"
fi
- Validar formato (soportados: MP3, WAV, M4A, OGG, FLAC, WEBM):
EXTENSION="${AUDIO_FILE##*.}"
SUPPORTED_FORMATS=("mp3" "wav" "m4a" "ogg" "flac" "webm" "mp4")
if [[ ! " ${SUPPORTED_FORMATS[@]} " =~ " ${EXTENSION,,} " ]]; then
echo "⚠️ Formato no soportado: $EXTENSION"
if command -v ffmpeg &>/dev/null; then
echo "🔄 Convirtiendo a WAV..."
ffmpeg -i "$AUDIO_FILE" -ar 16000 "${AUDIO_FILE%.*}.wav" -y
AUDIO_FILE="${AUDIO_FILE%.*}.wav"
else
echo "❌ Instala ffmpeg para convertir formatos: brew install ffmpeg"
exit 1
fi
fi
Paso 3: Generar Salida Markdown
Objetivo: Crear Markdown estructurado con metadatos, transcripción, actas de reunión y resumen.
Plantilla de Salida:
# Informe de Transcripción de Audio
## 📊 Metadatos
| Campo | Valor |
|-------|-------|
| **Nombre de Archivo** | {filename} |
| **Tamaño de Archivo** | {file_size} |
| **Duración** | {duration_hms} |
| **Idioma** | {language} ({language_code}) |
| **Fecha de Procesamiento** | {process_date} |
| **Hablantes Identificados** | {num_speakers} |
| **Motor de Transcripción** | {engine} (modelo: {model}) |
## 📋 Acta de Reunión
### Participantes
- {speaker_1}
- {speaker_2}
- ...
### Temas Discutidos
1. **{topic_1}** ({timestamp})
- {key_point_1}
- {key_point_2}
2. **{topic_2}** ({timestamp})
- {key_point_1}
### Decisiones Tomadas
- ✅ {decision_1}
- ✅ {decision_2}
### Elementos de Acción
- [ ] **{action_1}** - Asignado a: {speaker} - Fecha de vencimiento: {date_if_mentioned}
- [ ] **{action_2}** - Asignado a: {speaker}
*Generado por habilidad audio-transcriber v1.0.0*
*Motor de transcripción: {engine} | Tiempo de procesamiento: {elapsed_time}s*
Implementación:
Usar Python o bash con modelo de IA (Claude/GPT) para resumir inteligentemente:
def generate_meeting_minutes(segments):
"""Extraer temas, decisiones, elementos de acción de la transcripción."""
# Agrupar segmentos por tema (agrupación simple por marcas de tiempo)
topics = cluster_by_topic(segments)
# Identificar elementos de acción (palabras clave: "debería", "va a", "necesita", "acción")
action_items = extract_action_items(segments)
# Identificar decisiones (palabras clave: "decidió", "acordó", "aprobó")
decisions = extract_decisions(segments)
return {
"topics": topics,
"decisions": decisions,
"action_items": action_items
}
def generate_summary(segments, max_paragraphs=5):
"""Crear resumen ejecutivo usando IA (Claude/GPT vía API o modelo local)."""
full_text = " ".join([s["text"] for s in segments])
# Usar enfoque Cadena de Densidad (de marcos prompt-engineer)
summary_prompt = f"""
Resume la siguiente transcripción en {max_paragraphs} párrafos concisos.
Enfócate en temas clave, decisiones y elementos de acción.
Transcripción:
{full_text}
"""
# Llamar al modelo de IA (placeholder - el usuario puede integrar la API de Claude o usar un modelo local)
summary = call_ai_model(summary_prompt)
return summary
Nomenclatura de archivos de salida:
# v1.1.0: Usar marca de tiempo para evitar sobrescritura
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
TRANSCRIPT_FILE="transcript-${TIMESTAMP}.md"
ATA_FILE="ata-${TIMESTAMP}.md"
echo "$TRANSCRIPT_CONTENT" > "$TRANSCRIPT_FILE"
echo "✅ Transcript guardado: $TRANSCRIPT_FILE"
if [[ -n "$ATA_CONTENT" ]]; then
echo "$ATA_CONTENT" > "$ATA_FILE"
echo "✅ Ata guardada: $ATA_FILE"
fi
ESCENARIO A: El Usuario Proporcionó un Prompt Personalizado
Flujo de Trabajo:
-
Mostrar el prompt del usuario:
📝 Prompt proporcionado por el usuario: ┌──────────────────────────────────┐ │ [Vista previa del prompt del usuario] │ └──────────────────────────────────┘ -
Mejorar automáticamente con prompt-engineer (si está disponible):
🔧 Mejorando prompt con prompt-engineer... [Invoca: gh copilot -p "mejora este prompt: {user_prompt}"] -
Mostrar ambas versiones:
✨ Versión mejorada: ┌──────────────────────────────────┐ │ Rol: Eres un documentador... │ │ Instrucciones: Transforma... │ │ Pasos: 1) ... 2) ... │ │ Objetivo Final: ... │ └──────────────────────────────────┘ 📝 Versión original: ┌──────────────────────────────────┐ │ [Prompt original del usuario] │ └──────────────────────────────────┘ -
Preguntar cuál usar:
💡 ¿Usar versión mejorada? [s/n] (default: s): -
Procesar con el prompt seleccionado:
- Si "s": usar la versión mejorada
- Si "n": usar la original
Procesamiento con LLM (Ambos Escenarios)
Una vez finalizado el prompt:
from rich.progress import Progress, SpinnerColumn, TextColumn
def process_with_llm(transcript, prompt, cli_tool='claude'):
full_prompt = f"{prompt}\n\n---\n\nTranscripción:\n\n{transcript}"
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
transient=True
) as progress:
progress.add_task(
description=f"🤖 Procesando con {cli_tool}...",
total=None
)
if cli_tool == 'claude':
result = subprocess.run(
['claude', '-'],
input=full_prompt,
capture_output=True,
text=True,
timeout=300 # 5 minutos
)
elif cli_tool == 'gh-copilot':
result = subprocess.run(
['gh', 'copilot', 'suggest', '-t', 'shell', full_prompt],
capture_output=True,
text=True,
timeout=300
)
if result.returncode == 0:
return result.stdout.strip()
else:
return None
Salida de progreso:
🤖 Procesando con claude... ⠋
[Después de completar:]
✅ Acta generada exitosamente!
Salida Final
Éxito (ambos archivos):
💾 Guardando archivos...
✅ Archivos creados:
- transcript-20260203-023045.md (transcript puro)
- ata-20260203-023045.md (procesado con LLM)
🧹 Archivos temporales eliminados: metadata.json, transcription.json
✅ ¡Completado! Tiempo total: 3m 45s
Solo transcript (usuario rechazó LLM):
💾 Guardando archivos...
✅ Archivo creado:
- transcript-20260203-023045.md
ℹ️ Acta no generada (procesamiento LLM rechazado por el usuario)
🧹 Archivos temporales eliminados: metadata.json, transcription.json
✅ ¡Completado!
Paso 5: Mostrar Resumen de Resultados
Objetivo: Mostrar el estado de finalización y los siguientes pasos.
Salida:
echo ""
echo "✅ ¡Transcripción Completada!"
echo ""
echo "📊 Resultados:"
echo " Archivo: $OUTPUT_FILE"
echo " Idioma: $LANGUAGE"
echo " Duración: $DURATION_HMS"
echo " Hablantes: $NUM_SPEAKERS"
echo " Palabras: $WORD_COUNT"
echo " Tiempo de procesamiento: ${ELAPSED_TIME}s"
echo ""
echo "📝 Generado:"
echo " - $OUTPUT_FILE (Informe Markdown)"
[si formatos alternativos:]
echo " - ${OUTPUT_FILE%.*}.srt (Subtítulos)"
echo " - ${OUTPUT_FILE%.*}.json (Datos estructurados)"
echo ""
echo "🎯 Próximos pasos:"
echo " 1. Revisar actas de reunión y elementos de acción"
echo " 2. Compartir informe con los participantes"
echo " 3. Hacer seguimiento de los elementos de acción hasta su finalización"
Ejemplos de Uso
Ejemplo 1: Transcripción Básica
Entrada del Usuario:
copilot> transcribe audio a markdown: meeting-2026-02-02.mp3
Salida de la Habilidad:
✅ Faster-Whisper detectado (optimizado)
✅ ffmpeg disponible (conversión de formato habilitada)
📂 Archivo: meeting-2026-02-02.mp3
📊 Tamaño: 12.3 MB
⏱️ Duración: 00:45:32
🎙️ Procesando...
[████████████████████] 100%
✅ Idioma detectado: Portugués (pt-BR)
👥 Hablantes identificados: 4
📝 Generando salida Markdown...
✅ ¡Transcripción Completada!
📊 Resultados:
Archivo: meeting-2026-02-02.md
Idioma: pt-BR
Duración: 00:45:32
Hablantes: 4
Palabras: 6,842
Tiempo de procesamiento: 127s
📝 Generado:
- meeting-2026-02-02.md (Informe Markdown)
🎯 Próximos pasos:
1. Revisar actas de reunión y elementos de acción
2. Compartir informe con los participantes
3. Hacer seguimiento de los elementos de acción hasta su finalización
Ejemplo 3: Procesamiento por Lotes
Entrada del Usuario:
copilot> transcribe estos audios: recordings/*.mp3
Salida de la Habilidad:
📦 Modo lote: 5 archivos encontrados
1. team-standup.mp3
2. client-call.mp3
3. brainstorm-session.mp3
4. product-demo.mp3
5. retrospective.mp3
🎙️ Procesando lote...
[1/5] team-standup.mp3 ✅ (2m 34s)
[2/5] client-call.mp3 ✅ (15m 12s)
[3/5] brainstorm-session.mp3 ✅ (8m 47s)
[4/5] product-demo.mp3 ✅ (22m 03s)
[5/5] retrospective.mp3 ✅ (11m 28s)
✅ ¡Lote Completado!
📝 Generados 5 informes Markdown
⏱️ Tiempo total de procesamiento: 6m 15s
Ejemplo 5: Advertencia de Archivo Grande
Entrada del Usuario:
copilot> transcribe audio a markdown: conference-keynote.mp3
Salida de la Habilidad:
✅ Faster-Whisper detectado (optimizado)
📂 Archivo: conference-keynote.mp3
📊 Tamaño: 87.2 MB
⏱️ Duración: 02:15:47
⚠️ Archivo grande (87.2 MB) - el procesamiento puede tomar varios minutos
¿Continuar? [S/n]:
Usuario: S
🎙️ Procesando... (esto puede tomar 10-15 minutos)
[████░░░░░░░░░░░░░░░░] 20% - Tiempo estimado restante: 12m
Ejemplos Adicionales ([truncado para traducción])
Nota: Los ejemplos completos están disponibles en el documento original.
Instalación
# Clonar el repositorio
Dependencias
- faster-whisper o openai-whisper
- ffmpeg (opcional, para conversión de formatos)
Licencia
MIT