Metadata-Version: 2.4
Name: clipkly
Version: 0.2.6
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: numpy
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 sync`   | Determina automáticamente el offset entre grabaciones mediante audio |
| `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 |

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

```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                           |
| `--overwrite`  | Autorizar sobrescritura del archivo de salida si ya existe           |

---

## 🔄 `clipkly sync` — Sincronización automática de videos

Determina automáticamente el desfase temporal (`offset`) entre dos grabaciones (horizontal de referencia y vertical) que comparten una señal de audio, utilizando correlación cruzada de alta precisión.

### Uso básico

```bash
clipkly sync --horizontal video_h.mp4 --vertical video_v.mp4
```

### Salida esperada

```text
🔄 SINCRONIZACIÓN DE VIDEO — Reporte
============================================================
📹 Referencia (H): video_h.mp4
📱 Objetivo (V):   video_v.mp4
------------------------------------------------------------
⏱️  Offset vertical: +12.500s (+12.500 segundos)
📊 Confianza:       🟢 Alta
📝 Diagnóstico:     Sincronización detectada con alta confianza.
============================================================

📋 Comando sugerido para generar clips (listo para copiar):
clipkly clips --horizontal "video_h.mp4" --vertical "video_v.mp4" --offset 12.5 --json clips.json
```

### Argumentos

| Argumento | Descripción |
|---|---|
| `--horizontal` | Ruta al video horizontal (referencia temporal) (**requerido**) |
| `--vertical` | Ruta al video vertical (**requerido**) |
| `--sample-rate` | Frecuencia de muestreo normalizada en Hz (default: `8000`) |
| `--max-duration` | Duración máxima en segundos a analizar (default: `180.0`) |
| `--window-duration` | Tamaño de ventana para comprobar consistencia (default: `60.0`) |

---

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

---

## 🤖 Agent Plugin & Kiro Power (`clipkly-content-producer`)

Clipkly incluye un **Agent Plugin compatible con Agent Plugins Specification v1.0**, instalable como un **Kiro Power** para potenciar agentes de IA con capacidades editoriales y orquestación del CLI.

### Componentes incluidos:
- **`plugin.json`**: Manifiesto del plugin en la raíz del repositorio.
- **Skill `clipkly-content-producer`** (`skills/clipkly-content-producer/`):
  - Rúbrica editorial (claridad, valor, gancho, coherencia, relevancia, duración).
  - Guía de tipologías de momentos (tips, explicaciones técnicas, debates, anécdotas, humor).
  - Preservación de timestamps absolutos, análisis de transcripciones largas con solapamiento y deduplicación.
  - Generación de `clips.json` 100% compatible con los esquemas de Clipkly.
- **Custom Agent `clipkly-producer`** (`.kiro/agents/clipkly-producer.md`):
  - Agente especializado en producción audiovisual para Kiro.
  - Detecta archivos disponibles, analiza transcripciones con la skill y prepara propuestas editoriales estructuradas.
  - **Seguridad garantizada**: siempre solicita confirmación explícita del usuario antes de ejecutar operaciones que generen o modifiquen videos con FFmpeg.

### 📦 Instalación como Kiro Power

#### Desde un repositorio o carpeta local
En Kiro, puedes añadir el Power apuntando al directorio raíz del proyecto:
1. Abre el panel de Powers en Kiro.
2. Selecciona **Install Power from Local Directory** (o importa desde el repositorio de GitHub: `https://github.com/judlup/clipkly`).
3. Kiro detectará automáticamente el archivo `plugin.json` y registrará la skill `clipkly-content-producer`.

#### Activación del Custom Agent en Kiro
Para utilizar el agente especializado `clipkly-producer`:
1. Asegúrate de tener el archivo `.kiro/agents/clipkly-producer.md` en tu espacio de trabajo o cópialo a tu configuración de agentes de Kiro (`~/.kiro/agents/`).
2. Selecciona el agente `clipkly-producer` en el selector de agentes de Kiro.
3. Pídele al agente que analice tu video o transcripción:
   > *"Analiza la transcripción `mi_stream.srt`, propón los 5 mejores clips para TikTok/Reels y prepara el `clips.json`."*

---

## 🐍 Uso programático desde Python

Clipkly expone funciones directamente importables:

```python
from clipkly import procesar_clips, limpiar_video, extraer_srt, sincronizar_videos

# 1. Sincronizar grabaciones automáticamente por audio
res_sync = sincronizar_videos(
    video_h="horizontal.mp4",
    video_v="vertical.mp4",
)
offset_calculado = res_sync["offset"] if res_sync["offset"] is not None else 0.0
print(f"Offset detectado: {offset_calculado}s (Confianza: {res_sync['confianza']})")

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

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

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