snip — Corte y Reordenamiento de Videos
Corta videos en segmentos, los reordena y exporta a una velocidad de fotogramas específica. Útil para crear resúmenes destacados, reordenar escenas o cambiar el ritmo del video.
El directorio de la habilidad (donde reside este SKILL.md) se denomina $SKILL_DIR en adelante.
Cuándo Usarlo
Usa esta habilidad cuando el usuario desee:
- Cortar un video en segmentos específicos
- Reordenar segmentos de video en un orden diferente
- Eliminar secciones no deseadas de un video
- Cambiar la velocidad de fotogramas de salida (cortes por segundo)
- Detectar automáticamente segmentos de voz para cortes naturales (prioritario)
- Detectar automáticamente cambios de escena como respaldo
Configuración (solo la primera vez)
cd "$SKILL_DIR" && uv sync
Flujo de Trabajo del Agente
1. Preguntar al usuario
Antes de cortar el(los) video(s), necesito saber:
📹 Video(s) de origen
Enumera los archivos de video y sus ubicaciones
✂️ Segmentos a cortar
Para cada segmento, especifica:
- source: nombre del archivo
- start: tiempo de inicio en segundos (ej. 0.0, 5.5)
- end: tiempo de finalización en segundos (ej. 2.0, 10.0)
Ejemplo de segmentos:
[
{"source": "video.mp4", "start": 0.0, "end": 1.0},
{"source": "video.mp4", "start": 3.0, "end": 4.5},
{"source": "video.mp4", "start": 1.5, "end": 2.5}
]
🎬 Fotogramas por segundo de salida (opcional)
Por defecto: 30 fps
Opciones comunes: 24, 30, 60
📁 Directorios de entrada / salida (por defecto: ./input y ./output)
Espera la respuesta del usuario antes de continuar.
2. Determinar la Estrategia de Corte
Orden de prioridad:
- Segmentos explícitos — Si el usuario proporciona tiempos de inicio/fin específicos, úsalos
- Transcripción de audio — Si
transcription.enabled: true(por defecto), busca o genera transcripción y corta en los límites de los segmentos de voz - Detección adaptativa de escenas — Respaldo si la transcripción no está disponible o falla
Transcripción de Audio (Método Principal)
La habilidad primero intentará usar transcripción de audio para obtener segmentos de voz con marca de tiempo del video. Esto produce cortes más naturales alineados con el contenido hablado.
🤖 Modo de Transcripción de Audio (PRIORIDAD)
El cortador:
1. Buscará un JSON de transcripción existente en el directorio de salida (ej. video_transcription.json)
2. Si no lo encuentra, ejecutará la transcripción de audio automáticamente
3. Cortará el video en los límites de los segmentos de voz
⚙️ Configuración:
- transcription.enabled: true (por defecto)
- fallback_to_adaptive: true (por defecto) — usa detección de escenas si la transcripción falla
- min_segment_duration: duración mínima por segmento en segundos (por defecto: 1.0)
- max_segment_duration: duración máxima por segmento en segundos (por defecto: 30.0)
Ejemplo de configuración:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": true,
"fallback_to_adaptive": true,
"min_segment_duration": 1.0,
"max_segment_duration": 30.0
}
}
Detección Adaptativa de Escenas (Respaldo)
Si la transcripción está deshabilitada o falla, la habilidad recurre a la detección visual de escenas:
🎬 Detección Adaptativa de Escenas (RESPALDO)
Detecta automáticamente cambios de escena en tu video para crear cortes.
Esto evita contenido aburrido y repetitivo al cortar en transiciones naturales.
⚙️ Modo de detección:
- adaptive — Mejor para iluminación variable/cambios graduales [por defecto]
- content — Mejor para cortes de escena rápidos y claros
- threshold — Mejor para detección de fundidos de entrada/salida
📏 Filtros de duración de escena:
- min_scene_duration: duración mínima por escena en segundos (por defecto: 1.0)
- max_scene_duration: duración máxima por escena en segundos (por defecto: 10.0)
🎛️ Avanzado (opcional):
- threshold: umbral de diferencia de píxeles para modo content (por defecto: 27.0)
- adaptive_threshold: umbral de relación para modo adaptive (por defecto: 3.0)
- window_width: fotogramas a promediar (por defecto: 2)
- min_scene_len: fotogramas mínimos antes de un corte (por defecto: 15)
- min_content_val: cambio de contenido mínimo (por defecto: 15.0)
Ejemplo de configuración con detección automática de respaldo:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": false
},
"auto_detect": {
"enabled": true,
"mode": "adaptive",
"min_scene_duration": 1.0,
"max_scene_duration": 10.0
}
}
3. Editar config.json
Escribe o actualiza $SKILL_DIR/config.json según las elecciones del usuario.
4. Ejecutar
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
5. Informar resultados
Indica al usuario la ruta del archivo de salida, la duración y los FPS. Menciona qué método se utilizó (basado en transcripción o detección de escenas).
Referencia de Configuración
| Clave | Valores | Por defecto | Descripción |
|---|---|---|---|
input_dir | ruta | ./input | Carpeta que contiene los videos de entrada |
output_dir | ruta | ./output | Carpeta de destino |
segments | array | (obligatorio) | Lista de definiciones de segmentos |
output_fps | entero | 30 | Velocidad de fotogramas de salida |
Definición de Segmento
| Clave | Tipo | Descripción |
|---|---|---|
source | string | Nombre del archivo en input_dir |
start | float | Tiempo de inicio en segundos |
end | float | Tiempo de finalización en segundos |
Transcripción (Método Prioritario)
| Clave | Valores | Por defecto | Descripción |
|---|---|---|---|
enabled | boolean | true | Habilita el corte basado en transcripción |
fallback_to_adaptive | boolean | true | Usa detección de escenas si la transcripción falla |
min_segment_duration | float | 1.0 | Omite segmentos más cortos que esto (segundos) |
max_segment_duration | float | 30.0 | Omite segmentos más largos que esto (segundos) |
Detección Automática (Respaldo)
| Clave | Valores | Por defecto | Descripción |
|---|---|---|---|
enabled | boolean | false | Habilita la detección automática de escenas (solo respaldo) |
mode | adaptive, content, threshold | adaptive | Algoritmo de detección |
min_scene_duration | float | 1.0 | Omite escenas más cortas que esto (segundos) |
max_scene_duration | float | 10.0 | Omite escenas más largas que esto (segundos) |
threshold | float | 27.0 | Umbral de diferencia de píxeles para modo content/threshold |
adaptive_threshold | float | 3.0 | Umbral de relación para modo adaptive |
window_width | int | 2 | Fotogramas a promediar antes/después |
min_scene_len | int | 15 | Fotogramas mínimos antes de un corte |
min_content_val | float | 15.0 | Cambio de contenido mínimo |
Modos de Detección (Respaldo)
- adaptive (por defecto): Mejor para videos con iluminación variable o transiciones graduales
- content: Mejor para videos con cortes de escena nítidos y claros
- threshold: Mejor para detectar transiciones de fundido de entrada/salida
Invocaciones Comunes
# Configuración por defecto (usa transcripción si está disponible, recurre a adaptive)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
# Forzar detección adaptativa de escenas (saltar transcripción)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json --no-transcription
# Directorios personalizados
cd "$SKILL_DIR" && uv run python scripts/cutter.py \
--input /ruta/a/videos --output /ruta/a/salida
Salida
Cada configuración produce un output.mp4 en output_dir que contiene los segmentos concatenados.
El audio se conserva de los segmentos de video originales.
Manejo de Errores
- Sin segmentos definidos → mensaje de error, termina
- Tiempos de segmento no válidos → error claro con el formato esperado
- Video de origen no encontrado → error con archivo no encontrado
- Transcripción falla → recurre a adaptive si está habilitado, de lo contrario error
- Errores de segmentos individuales → se registran; otros segmentos continúan