🎬 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]"

⚡ Comandos disponibles

clipkly funciona con subcomandos:

🎬 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

🧩 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.

🐍 Uso programático desde Python

Clipkly expone funciones directamente importables:

from clipkly import procesar_clips, limpiar_video, extraer_srt

# 1. 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"])

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

# 3. 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 ❤️