Metadata-Version: 2.4
Name: clipkly
Version: 0.2.3
Summary: 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.
Home-page: https://github.com/judlup/clipkly
Author: Julian Dario Luna Patiño
Author-email: judlup@trycatch.tv
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: openpyxl
Requires-Dist: pydantic>=2.0.0
Provides-Extra: srt
Requires-Dist: faster-whisper>=1.1.1; extra == "srt"
Provides-Extra: gpu
Requires-Dist: faster-whisper>=1.1.1; extra == "gpu"
Requires-Dist: nvidia-cublas-cu12; extra == "gpu"
Requires-Dist: nvidia-cudnn-cu12; extra == "gpu"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🎬 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
```

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

```bash
pip install "clipkly[srt]"
```

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

```bash
pip install "clipkly[gpu]"
```

---

## ⚡ 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

```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-v`       | Alias de `--offset` para video vertical                          |
| `--offset-h`       | Desfase (en segundos) aplicado al video horizontal               |
| `--accurate`       | Recodificar para corte preciso por fotograma (en vez de `-c copy`)|
| `--filter`         | Filtrar por categoría (inspiracional, educativo, etc)            |
| `--duracion`       | Filtrar por duración: `muy_corto`, `ideal`, `largo`, `muy_largo` |
| `--dry-run`        | Modo simulación: valida rangos y muestra comandos sin crear carpetas ni archivos en disco |
| `--out-dir`        | Directorio de salida para los clips (default: `clips/`)          |
| `--zip`            | Comprime exclusivamente los clips generados en la sesión actual y el Excel |

---

## 🧹 `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

# 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`

```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 fundido (fade in/out) entre transiciones (0 = sin fade)  |
| `--dry-run`    | Solo mostrar los comandos FFmpeg sin ejecutar ni crear archivos      |
| `--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

```bash
clipkly srt --video stream.mp4
```

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

### Ejemplos

```bash
# 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` (default: `auto`)                     |
| `--compute-type`     | Precisión (ej: `float16` en CUDA, `int8` en CPU; default: auto-detectado)|
| `--beam-size`        | Beam size para decodificacion                                             |
| `--vad-filter`       | Activa Voice Activity Detection                                           |
| `--word-timestamps`  | Habilita timestamps por palabra durante inferencia                        |

### 🚀 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:

```bash
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12
```

O instala el [NVIDIA CUDA Toolkit v12](https://developer.nvidia.com/cuda-downloads) y añade su directorio `bin` a tu variable de entorno `PATH`.

---

## 🐍 Uso programático desde Python

Clipkly expone funciones directamente importables:

```python
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](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** ❤️
