🎬 clipkly

clipkly es una herramienta CLI para developers, creadores técnicos y equipos de contenido que quieren extraer los mejores momentos de un video horizontal o vertical sin perder tiempo.

Le das un .json con los momentos clave (puedes generarlos desde los subtítulos), y te devuelve:

• Clips recortados con precisión quirúrgica (gracias a FFmpeg)

• Un archivo .xlsx con metadatos listos para planificar publicaciones

• Una estructura de carpetas clara para organizar horizontal vs. vertical

• Limpieza de video: elimina segmentos no deseados (intros, charlas off-topic, problemas técnicos) y genera un video limpio con solo el contenido principal

¿Usas Twitch, YouTube o TikTok? ¿Subes contenido técnico, educativo o de comunidad? Entonces clipkly es tu nuevo asistente para postproducción.

🚀 Instalación

pip install clipkly

Para usar extracción de subtítulos con Whisper en CPU:

pip install "clipkly[srt]"

Para aceleración por GPU (NVIDIA CUDA con cuBLAS y cuDNN incluidos):

pip install "clipkly[gpu]"

Para soporte de Model Context Protocol (MCP) en clientes de IA (Codex, Kiro, Claude Desktop, Cursor, etc.):

pip install "clipkly[mcp]"

⚡ Comandos disponibles

clipkly funciona con subcomandos del CLI y el ejecutable del servidor MCP:

🎬 clipkly clips — Generar clips

Extrae clips de un video a partir de un JSON con timecodes.

Uso básico

clipkly clips --vertical video_v.mp4 --offset 403.025 --json clips.json

También puedes incluir la versión horizontal:

clipkly clips --horizontal video_h.mp4 --vertical video_v.mp4 --offset 403.025

Resultado

Se generarán clips automáticamente en:

clips/
├── horizontal/    ← Clips del video horizontal (sin offset)
├── vertical/      ← Clips del video vertical (con offset)
└── estado_clips.xlsx  ← Metadatos editoriales en Excel

Formato del archivo clips.json

[
  {
    "start": "01:46:31.760",
    "end": "01:47:17.199",
    "slug": "titulo_del_clip",
    "titulo": "Título optimizado para SEO",
    "descripcion": "Descripción breve del contenido",
    "feeling": "emocion o tono del clip",
    "category": "categoría del clip"
  }
]

Argumentos

Integridad editorial y notas de uso

• Slugs opcionales: Si un elemento en clips.json no define slug (o es null, vacío o solo espacios), Clipkly genera automáticamente un identificador determinista y estable derivado de sus timecodes (por ejemplo clip_014631_014717), evitando colisiones o fallos de tipo.
• Filtros vacíos: Si aplicas un filtro por --filter o --duracion que no coincide con ningún clip, Clipkly no creará carpetas vacías ni modificará estado_clips.xlsx, preservando el histórico editorial previo.
• Precedencia de datos editoriales: Si editas manualmente celdas en estado_clips.xlsx (estado, fecha_publicacion, tags, ia_notes, platform_fit, used_in_publication, etc.), dichas modificaciones se conservan al volver a ejecutar el proceso, prevaleciendo sobre el JSON entrante.

🧹 clipkly clean — Limpiar video

Remueve segmentos no deseados de un video (intros, charlas off-topic, problemas técnicos) y genera un video limpio con solo el contenido principal.

Uso básico

clipkly clean --video stream.mp4 --json cortes.json

Preview (solo reporte, sin procesar)

clipkly clean --video stream.mp4 --json cortes.json --preview

Salida de ejemplo:

🧹 LIMPIEZA DE VIDEO — Reporte
============================================================
📹 Video fuente:       stream.mp4
⏱️  Duración total:     02:10:45.000
✂️  Cortes a remover:   2
🗑️  Duración removida:  00:13:05.000
✅ Duración final:     01:57:40.000
📊 Contenido conservado: 89.9%

🗑️  Segmentos REMOVIDOS:
   1. [00:00:00 → 00:11:30] (00:11:30.000) — Intro musical, problemas técnicos...
   2. [00:36:45 → 00:38:20] (00:01:35.000) — Charla off-topic...

✅ Segmentos CONSERVADOS:
   1. [00:11:30.000 → 00:36:45.000] (00:25:15.000)
   2. [00:38:20.000 → 02:10:45.000] (01:32:25.000)

Opciones avanzadas

# Salida personalizada
clipkly clean --video stream.mp4 --json cortes.json -o video_final.mp4

# Margen de 2 segundos extra en cada corte
clipkly clean --video stream.mp4 --json cortes.json --margin 2

# Fundido de entrada y salida (fade in/out) de 0.5 segundos entre transiciones
clipkly clean --video stream.mp4 --json cortes.json --fade 0.5

# Dry run (ver comandos ffmpeg sin ejecutar)
clipkly clean --video stream.mp4 --json cortes.json --dry-run

Formato del archivo cortes.json

{
  "cortes_sugeridos": [
    {
      "inicio": "00:00:00",
      "final": "00:11:30",
      "razon": "Intro musical, espera, configuración de problemas técnicos."
    },
    {
      "inicio": "00:36:45",
      "final": "00:38:20",
      "razon": "Charla off-topic no relacionada con el tema principal."
    }
  ]
}

Argumentos

🔄 clipkly sync — Sincronización automática de videos

Determina automáticamente el desfase temporal (offset) entre dos grabaciones (horizontal de referencia y vertical) que comparten una señal de audio, utilizando correlación cruzada de alta precisión.

Uso básico

clipkly sync --horizontal video_h.mp4 --vertical video_v.mp4

Salida esperada

🔄 SINCRONIZACIÓN DE VIDEO — Reporte
============================================================
📹 Referencia (H): video_h.mp4
📱 Objetivo (V):   video_v.mp4
------------------------------------------------------------
⏱️  Offset vertical: +12.500s (+12.500 segundos)
📊 Confianza:       🟢 Alta
📝 Diagnóstico:     Sincronización detectada con alta confianza.
============================================================

📋 Comando sugerido para generar clips (listo para copiar):
clipkly clips --horizontal "video_h.mp4" --vertical "video_v.mp4" --offset 12.5 --json clips.json

Argumentos

🧩 Argumentos globales

📝 clipkly srt — Extraer subtitulos .srt

Genera un archivo SRT desde un video (por ejemplo .mp4) usando faster-whisper.

Uso basico

clipkly srt --video stream.mp4

Esto genera por defecto stream.srt en la misma carpeta del video.

Ejemplos

# Forzar idioma espanol
clipkly srt --video stream.mp4 --language es

# Deteccion automatica de idioma
clipkly srt --video stream.mp4 --language auto

# Elegir modelo y salida personalizada
clipkly srt --video stream.mp4 --model medium -o subtitulos.srt

# CPU optimizado (default recomendado en Windows)
clipkly srt --video stream.mp4 --device cpu --compute-type int8

# Activar VAD para reducir bloques de silencio
clipkly srt --video stream.mp4 --vad-filter

Argumentos

🚀 Aceleración por GPU (CUDA) y Solución de Problemas

Clipkly soporta inferencia acelerada por GPU mediante faster-whisper (backend CTranslate2).

• --device auto (por defecto): Si hay una GPU NVIDIA visible, utiliza CUDA con precisión float16. Si las bibliotecas CUDA no están presentes o fallan, realiza fallback automático e informado a CPU (int8), registrando el motivo en consola y en el resultado.
• --device cuda: Solicita GPU de forma estricta. Si la GPU o sus bibliotecas no están disponibles, no hace fallback silencioso y reporta un diagnóstico con las acciones sugeridas.
• --device cpu: Inferencia exclusiva en CPU utilizando int8 optimizado.

Requisitos para GPU en Windows

Si utilizas Windows y deseas transcribir con --device cuda, asegúrate de tener una GPU NVIDIA con controladores actualizados y las bibliotecas cuBLAS y cuDNN en tu entorno:

pip install nvidia-cublas-cu12 nvidia-cudnn-cu12

O instala el NVIDIA CUDA Toolkit v12 y añade su directorio bin a tu variable de entorno PATH.

🤖 Agent Plugin & Kiro Power (clipkly-content-producer)

Clipkly incluye un Agent Plugin compatible con Agent Plugins Specification v1.0, instalable como un Kiro Power para potenciar agentes de IA con capacidades editoriales y orquestación del CLI.

Componentes incluidos:

• plugin.json: Manifiesto del plugin en la raíz del repositorio.
• Skill clipkly-content-producer (skills/clipkly-content-producer/):
  • Rúbrica editorial (claridad, valor, gancho, coherencia, relevancia, duración).
  • Guía de tipologías de momentos (tips, explicaciones técnicas, debates, anécdotas, humor).
  • Preservación de timestamps absolutos, análisis de transcripciones largas con solapamiento y deduplicación.
  • Generación de clips.json 100% compatible con los esquemas de Clipkly.
• Custom Agent clipkly-producer (.kiro/agents/clipkly-producer.md):
  • Agente especializado en producción audiovisual para Kiro.
  • Detecta archivos disponibles, analiza transcripciones con la skill y prepara propuestas editoriales estructuradas.
  • Seguridad garantizada: siempre solicita confirmación explícita del usuario antes de ejecutar operaciones que generen o modifiquen videos con FFmpeg.

📦 Instalación como Kiro Power

Desde un repositorio o carpeta local

En Kiro, puedes añadir el Power apuntando al directorio raíz del proyecto:

1. Abre el panel de Powers en Kiro.
2. Selecciona Install Power from Local Directory (o importa desde el repositorio de GitHub: https://github.com/judlup/clipkly).
3. Kiro detectará automáticamente el archivo plugin.json y registrará la skill clipkly-content-producer.

Activación del Custom Agent en Kiro

Para utilizar el agente especializado clipkly-producer:

1. Asegúrate de tener el archivo .kiro/agents/clipkly-producer.md en tu espacio de trabajo o cópialo a tu configuración de agentes de Kiro (~/.kiro/agents/).
2. Selecciona el agente clipkly-producer en el selector de agentes de Kiro.
3. Pídele al agente que analice tu video o transcripción:

   "Analiza la transcripción mi_stream.srt, propón los 5 mejores clips para TikTok/Reels y prepara el clips.json."

🔌 Clipkly MCP Server (clipkly-mcp)

Clipkly incluye un servidor local compatible con Model Context Protocol (MCP), permitiendo que agentes y clientes de IA (Codex, Kiro, Claude Desktop, Cursor, etc.) descubran y ejecuten las herramientas audiovisuales de Clipkly mediante contratos estructurados sobre stdio.

🛠️ Herramientas MCP expuestas:

🩺 Diagnóstico del sistema (--check)

Para verificar que tu entorno cuenta con todas las dependencias necesarias (Python, MCP SDK, FFmpeg, FFprobe, GPU/Whisper):

clipkly-mcp --check

⚡ Ejecución directa sin instalación local (uvx)

Puedes ejecutar el servidor MCP directamente desde PyPI usando uvx:

uvx --from "clipkly[mcp]" clipkly-mcp

🤖 Configuración en OpenAI Codex CLI

Para registrar y habilitar Clipkly en Codex:

codex mcp add clipkly -- uvx --from "clipkly[mcp]" clipkly-mcp

🧩 Integración en Kiro vía Agent Plugins (mcp.json)

Clipkly incluye el manifiesto mcp.json en la raíz del repositorio, conforme a la especificación Agent Plugins v1.0:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "clipkly": {
      "type": "stdio",
      "command": "clipkly-mcp"
    }
  }
}

Al instalar el plugin en Kiro o clientes compatibles, el servidor MCP queda disponible automáticamente como herramientas nativas para tus agentes de IA.

🐍 Uso programático desde Python

Clipkly expone funciones directamente importables:

from clipkly import procesar_clips, limpiar_video, extraer_srt, sincronizar_videos

# 1. Sincronizar grabaciones automáticamente por audio
res_sync = sincronizar_videos(
    video_h="horizontal.mp4",
    video_v="vertical.mp4",
)
offset_calculado = res_sync["offset"] if res_sync["offset"] is not None else 0.0
print(f"Offset detectado: {offset_calculado}s (Confianza: {res_sync['confianza']})")

# 2. Generar subtítulos
info_srt = extraer_srt(
    video="mi_video.mp4",
    model="small",
    device="auto", # auto-detecta cuda o cpu
)
print("Dispositivo utilizado:", info_srt["effective_device"])

# 3. Cortar clips
resultado_clips = procesar_clips(
    archivo_json="clips.json",
    video_h="horizontal.mp4",
    video_v="vertical.mp4",
    offset=offset_calculado,
    accurate=True, # corte preciso por fotograma
)

# 4. Limpiar video
resultado_limpieza = limpiar_video(
    archivo_json="cortes.json",
    video="stream.mp4",
)

Requisitos del sistema

• Python >= 3.9
• ffmpeg disponible en PATH
• Dependencias opcionales de transcripción: pip install "clipkly[srt]"

🧾 Excel generado

🙌 Créditos

Este proyecto fue creado por Julian Dario Luna Patiño, ingeniero de software, arquitecto de soluciones en la nube y creador de contenido en TryCatch.tv.

clipkly nació como una herramienta práctica para automatizar la creación de clips a partir de transmisiones en vivo, especialmente útil para quienes trabajan con contenido en plataformas como YouTube, TikTok e Instagram.

📫 Contacto: judlup@trycatch.tv

✨ Dedicado con cariño a Nikol Daniela ❤️