snip — Corte e Reorganização de Vídeos
Corta vídeos em segmentos, reordena-os e exporta com uma taxa de quadros especificada. Útil para criar compilações de melhores momentos, reorganizar cenas ou alterar o ritmo do vídeo.
O diretório da skill (onde este SKILL.md reside) é referido como $SKILL_DIR abaixo.
Quando Usar
Use esta skill quando o usuário quiser:
- Cortar um vídeo em segmentos específicos
- Reorganizar segmentos de vídeo em uma ordem diferente
- Remover seções indesejadas de um vídeo
- Alterar a taxa de quadros de saída (cortes por segundo)
- Detectar automaticamente segmentos de fala para cortes naturais (prioritário)
- Detectar automaticamente mudanças de cena como fallback
Configuração (apenas na primeira execução)
cd "$SKILL_DIR" && uv sync
Fluxo de Trabalho do Agente
1. Pergunte ao usuário
Antes de cortar o(s) vídeo(s), preciso saber:
📹 Vídeo(s) de origem
Liste os arquivos de vídeo e suas localizações
✂️ Segmentos a cortar
Para cada segmento, especifique:
- source: nome do arquivo
- start: tempo inicial em segundos (ex.: 0.0, 5.5)
- end: tempo final em segundos (ex.: 2.0, 10.0)
Exemplo 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}
]
🎬 FPS de saída (opcional)
Padrão: 30 fps
Opções comuns: 24, 30, 60
📁 Diretórios de entrada / saída (padrão: ./input e ./output)
Aguarde a resposta do usuário antes de prosseguir.
2. Determinar Estratégia de Corte
Ordem de Prioridade:
- Segmentos explícitos — Se o usuário fornecer horários de início/fim específicos, use-os
- Transcrição de áudio — Se
transcription.enabled: true(padrão), procure ou gere transcrição e corte nos limites dos segmentos de fala - Detecção adaptativa de cena — Fallback se a transcrição não estiver disponível ou falhar
Transcrição de Áudio (Método Principal)
A skill tentará primeiro usar transcrição de áudio para obter segmentos de fala com timestamp do vídeo. Isso produz cortes mais naturais alinhados com o conteúdo falado.
🤖 Modo de Transcrição de Áudio (PRIORITÁRIO)
O cortador irá:
1. Procurar por um JSON de transcrição existente em output_dir (ex.: video_transcription.json)
2. Se não encontrado, executar a transcrição de áudio automaticamente
3. Cortar o vídeo nos limites dos segmentos de fala
⚙️ Configuração:
- transcription.enabled: true (padrão)
- fallback_to_adaptive: true (padrão) — usar detecção de cena se a transcrição falhar
- min_segment_duration: duração mínima por segmento (padrão: 1.0)
- max_segment_duration: duração máxima por segmento (padrão: 30.0)
Exemplo de config:
{
"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
}
}
Detecção Adaptativa de Cena (Fallback)
Se a transcrição estiver desabilitada ou falhar, a skill recorre à detecção visual de cenas:
🎬 Detecção Adaptativa de Cena (FALLBACK)
Detecta automaticamente mudanças de cena no seu vídeo para criar cortes.
Isso evita conteúdo chato e repetitivo, cortando em transições naturais.
⚙️ Modo de detecção:
- adaptive — Melhor para iluminação variável/mudanças graduais [padrão]
- content — Melhor para cortes de cena rápidos e claros
- threshold — Melhor para detecção de fade in/out
📏 Filtros de duração de cena:
- min_scene_duration: duração mínima por cena (padrão: 1.0)
- max_scene_duration: duração máxima por cena (padrão: 10.0)
🎛️ Avançado (opcional):
- threshold: limite de diferença de pixel para modo content (padrão: 27.0)
- adaptive_threshold: limite de proporção para modo adaptive (padrão: 3.0)
- window_width: quadros para média (padrão: 2)
- min_scene_len: quadros mínimos antes do corte (padrão: 15)
- min_content_val: mudança mínima de conteúdo (padrão: 15.0)
Exemplo de config com fallback de detecção automática:
{
"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
Escreva ou atualize $SKILL_DIR/config.json com base nas escolhas do usuário.
4. Executar
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
5. Relatar Resultados
Informe ao usuário o caminho do arquivo de saída, duração e FPS. Mencione qual método foi usado (baseado em transcrição ou detecção de cena).
Referência de Configuração
| Chave | Valores | Padrão | Descrição |
|---|---|---|---|
input_dir | caminho | ./input | Pasta contendo vídeos de entrada |
output_dir | caminho | ./output | Pasta de destino |
segments | array | (obrigatório) | Lista de definições de segmento |
output_fps | inteiro | 30 | Taxa de quadros de saída |
Definição de Segmento
| Chave | Tipo | Descrição |
|---|---|---|
source | string | Nome do arquivo em input_dir |
start | float | Tempo inicial em segundos |
end | float | Tempo final em segundos |
Transcrição (Método Prioritário)
| Chave | Valores | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | true | Ativar corte baseado em transcrição |
fallback_to_adaptive | boolean | true | Usar detecção de cena se a transcrição falhar |
min_segment_duration | float | 1.0 | Ignorar segmentos mais curtos que isso (segundos) |
max_segment_duration | float | 30.0 | Ignorar segmentos mais longos que isso (segundos) |
Detecção Automática (Fallback)
| Chave | Valores | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | false | Ativar detecção automática de cena (apenas fallback) |
mode | adaptive, content, threshold | adaptive | Algoritmo de detecção |
min_scene_duration | float | 1.0 | Ignorar cenas mais curtas que isso (segundos) |
max_scene_duration | float | 10.0 | Ignorar cenas mais longas que isso (segundos) |
threshold | float | 27.0 | Limite de diferença de pixel para modo content/threshold |
adaptive_threshold | float | 3.0 | Limite de proporção para modo adaptive |
window_width | int | 2 | Quadros para média antes/depois |
min_scene_len | int | 15 | Quadros mínimos antes de um corte |
min_content_val | float | 15.0 | Mudança mínima de conteúdo |
Modos de Detecção (Fallback)
- adaptive (padrão): Melhor para vídeos com iluminação variável ou transições graduais
- content: Melhor para vídeos com cortes de cena nítidos e claros
- threshold: Melhor para detectar transições de fade in/out
Invocações Comuns
# Configuração padrão (usa transcrição se disponível, fallback para adaptive)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
# Forçar detecção adaptativa de cena (pular transcrição)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json --no-transcription
# Diretórios personalizados
cd "$SKILL_DIR" && uv run python scripts/cutter.py \
--input /caminho/para/videos --output /caminho/para/saida
Saída
Cada configuração produz um output.mp4 em output_dir contendo os segmentos concatenados.
O áudio é preservado dos segmentos de vídeo originais.
Tratamento de Erros
- Nenhum segmento definido → mensagem de erro, sai
- Tempos de segmento inválidos → erro claro com formato esperado
- Vídeo de origem não encontrado → erro com arquivo não encontrado
- Falha na transcrição → fallback para adaptive se habilitado, senão erro
- Erros em segmentos individuais → registrados; outros segmentos continuam