# 🎬 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** ❤️
