clipkly 0.1.7

Automatiza la creación de clips impactantes desde tus transmisiones. clipkly convierte JSONs con timecodes en cortes precisos listos para redes sociales, exportando también un Excel con metadatos editoriales. Perfecto para devs que crean, editan y publican contenido.

🎬 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 extraccion de subtitulos con Whisper:

pip install "clipkly[srt]"

---

⚡ Comandos disponibles

clipkly funciona con subcomandos:

Comando	Descripción
clipkly clips	Genera clips desde un video usando un JSON de timecodes
clipkly clean	Limpia un video removiendo segmentos no deseados
clipkly srt	Extrae subtitulos .srt desde un MP4 con faster-whisper

---

🎬 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

Argumento	Descripción
--horizontal	Ruta al archivo horizontal (opcional)
--vertical	Ruta al archivo vertical (opcional)
--json	Ruta al archivo JSON con los clips (default: clips.json)
--offset	Desfase (en segundos) aplicado al video vertical
--offset-h	Desfase (en segundos) aplicado al video horizontal
--filter	Filtrar por categoría (inspiracional, educativo, etc)
--duracion	Filtrar por duración: muy_corto, ideal, largo, muy_largo
--dry-run	Muestra lo que se haría sin ejecutar FFmpeg
--out-dir	Directorio de salida para los clips (default: clips/)
--zip	Comprime los clips en un archivo ZIP al finalizar

---

🧹 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

# Crossfade de 0.5 segundos entre segmentos
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

Argumento	Descripción
--video	Ruta al video fuente (requerido)
--json	Archivo JSON con cortes_sugeridos (requerido)
--output/-o	Ruta del video de salida (default: <nombre>_limpio.mp4)
--margin	Segundos de margen extra en cada corte (amplía los cortes)
--fade	Segundos de crossfade entre segmentos (0 = sin fade)
--dry-run	Solo mostrar los comandos FFmpeg sin ejecutar
--preview	Solo generar reporte sin procesar el video

---

🧩 Argumentos globales

Argumento	Descripción
--version / -v	Muestra la versión instalada
--help / -h	Muestra la ayuda de uso

---

📝 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

Argumento	Descripción
--video	Ruta al archivo fuente (requerido)
--output / -o	Ruta del .srt de salida (default: <video>.srt)
--model	Modelo Whisper (tiny, base, small, medium, large-v3)
--language	Idioma (es, en, etc.) o auto
--device	Dispositivo: auto, cpu, cuda
--compute-type	Precision de inferencia (ej: int8, float16)
--beam-size	Beam size para decodificacion
--vad-filter	Activa Voice Activity Detection
--word-timestamps	Habilita timestamps por palabra durante inferencia

Requisitos

• ffmpeg disponible en PATH
• Dependencia Whisper instalada via 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: [e-mail]

✨ Dedicado con cariño a Nikol Daniela ❤️