clipkly 0.1.6
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.
Requires Python: >=3.7

# 🎬 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

```bash
pip install clipkly
```

---

## ⚡ 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 clips` — Generar clips

Extrae clips de un video a partir de un JSON con timecodes.

### Uso básico

```bash
clipkly clips --vertical video_v.mp4 --offset 403.025 --json clips.json
```

También puedes incluir la versión horizontal:

```bash
clipkly clips --horizontal video_h.mp4 --vertical video_v.mp4 --offset 403.025
```

### Resultado

Se generarán clips automáticamente en:

```css
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`

```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

```bash
clipkly clean --video stream.mp4 --json cortes.json
```

### Preview (solo reporte, sin procesar)

```bash
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

```bash
# 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`

```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             |

---

## 🧾 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](https://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](mailto:judlup@trycatch.tv)

✨ Dedicado con cariño a **Nikol Daniela** ❤️