VSS Summarize (Resumo de Vídeo)

O que VSS Summarize (Resumo de Vídeo) faz?

Execute o pipeline de sumarização através do Gerenciador de Pipeline. Chame a própria API documentada e relate apenas respostas observadas. Os endpoints usam o prefixo /manager do nginx. Quando as ferramentas MCP vss_* estiverem conectadas, vss_summarize_video cobre o mesmo trabalho; esta skill é a rota REST.

Defina HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}.

Contrato de resposta quando o VSS não está acessível

O usuário pode estar longe da implantação, $HOST pode recusar conexões, ou uma pré-condição pode falhar (por exemplo, o modo de resumo está desabilitado ou o vídeo nomeado está ausente). Em qualquer um desses casos não pare e não invente respostas. Relate o bloqueador observado e, em seguida, responda com a sequência completa e exata de chamadas que o usuário pode executar após corrigi-lo: caminhos completos dos endpoints, corpos de requisição/campos de formulário, o campo que cada etapa carrega da resposta anterior e a condição que indica que uma etapa está concluída. Não abrevie ou omita o fluxo de resumo solicitado apenas porque ele não pôde ser executado. Indique claramente quais comandos não foram executados. Nunca termine a resposta perguntando se deseja executá-los.

Configuração do ambiente (execute primeiro)

Esta skill utiliza o aplicativo Video Search & Summarization através de seus arquivos de código-fonte reais, portanto, o aplicativo VSS deve estar presente e você deve executar comandos a partir de sua raiz. Faça isso antes de qualquer outra coisa, e funciona independentemente de o código-fonte VSS já estar ou não no seu espaço de trabalho.

Execute o bootstrap incluído. Ele resolve a raiz do aplicativo nesta ordem e a imprime como a única linha na saída padrão:

1. Subir a partir do diretório atual procurando por uma raiz do aplicativo VSS - um diretório que contenha todos os três marcadores setup.sh, docker/ e pipeline-manager/.
2. Perguntar ao git pelo repositório atual (git rev-parse --show-toplevel) e verificar se ele contém sample-applications/video-search-and-summarization, ou se é ele próprio uma raiz do aplicativo VSS. Isso permite que seu próprio clone - ou um fork - funcione sem alterações.
3. Reutilizar um checkout que um bootstrap anterior já colocou em ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries.

Se alguma dessas opções for bem-sucedida, esse checkout é reutilizado e NENHUM clone é realizado. Apenas quando todas as três falharem é que ele clona - e então apenas um checkout raso (--depth 1), single-branch, esparso de apenas sample-applications/video-search-and-summarization da branch main:

# SKILL_DIR é o diretório DESTA skill (mostrado a você quando a skill é carregada);
# no repositório, é .github/skills/vss-summarize-video. Funciona da mesma forma se a skill estiver instalada de forma independente.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

Todo comando abaixo assume que o diretório de trabalho é este APP_ROOT. Para usar um fork/branch ou reutilizar um diretório de checkout específico, substitua VSS_REPO_URL, VSS_REPO_BRANCH ou VSS_CLONE_DIR antes de executá-lo. O bootstrap se recusa a sobrescrever um destino de clone não VSS existente.

Pré-condições

1. Backend íntegro e resumo habilitado - teste primeiro; se não estiver, use a skill vss-troubleshoot ou vss-deploy instalada pelo nome:

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
   

2. Um videoId para resumir - envie um com POST /manager/videos (multipart, campo video), que retorna { "videoId": "…" }. Ou liste os existentes - observe que a resposta é um objeto { "videos": [...] }, não um array simples, e name é um hash gerado (o nome real do arquivo está em url / dataStore.fileName):

   curl -s -X POST "$HOST/manager/videos" -F "video=@/caminho/para/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. Iniciar o pipeline de resumo

POST /manager/summary. O corpo tem campos obrigatórios; a ausência de qualquer um deles (title, sampling.* ou evam.evamPipeline) retorna 400. Consulte references/summary-request.md para obter o esquema completo, substituições de prompt e opções de áudio.

Requisição mínima válida:

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Análise da doca de carga",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

Restrição de amostragem: o Gerenciador de Pipeline impõe multiFrame == frameOverlap + samplingFrame. Com frameOverlap: 0, defina multiFrame == samplingFrame. Discrepância → 400 "Multi frame mismatch". evamPipeline é um dos object_detection | video_ingestion.

Para resumir apenas parte de um clipe, adicione os opcionais sampling.videoStart e sampling.videoEnd (segundos) - por exemplo, os primeiros dez minutos seriam "videoStart": 0, "videoEnd": 600.

2. Consultar até a conclusão

O summaryPipelineId retornado é o stateId. GET /manager/summary/{stateId} não possui campos status/progress de nível superior (apenas /raw os possui) - o progresso reside em campos por etapa:

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # string, "complete" quando fragmentado
  frames:   .frameSummaryStatus,     # objeto COUNTS: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # string: "na" → "inProgress" → "complete"  ← sinal real de conclusão
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ A conclusão é videoSummaryStatus == "complete", NÃO summary não vazio. O texto final do summary é transmitido incrementalmente enquanto videoSummaryStatus ainda está "inProgress", portanto, consultar "summary length > 0" retorna um resultado truncado, no meio da frase. Sempre bloqueie em videoSummaryStatus. Com produceFinalSummary: false não há etapa final - bloqueie em frameSummaryStatus.inProgress == 0.

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

A sumarização é lenta (VLM por fragmento + LLM map-reduce) - minutos, não segundos.

3. Recuperar o resumo

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # resumo final map-reduce
# As legendas por fragmento estão em .frameSummaries[] (cada: frameKey, status, summary).
# NÃO estão em .chunks[] - esses apenas carregam {chunkId, duration, audioTranscripts}:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # tudo (áudio, quadros, status, …)

Apresente o texto final do resumo; ofereça os detalhes por fragmento se for útil. Áudio sem fala resulta em um audioTranscriptSummary que informa isso - não é um erro.

Trilha de auditoria da resposta final

Os argumentos da ferramenta podem não estar visíveis para o usuário ou avaliador. A resposta final deve, portanto, relatar o resultado do bootstrap: o APP_ROOT resolvido, se um checkout existente foi reutilizado sem clonagem, e que os comandos foram executados após mudar para essa raiz do aplicativo. Informe também que uma falha total do bootstrap recai em um checkout raso (--depth 1), single-branch e esparso apenas do aplicativo VSS a partir da branch main. Relate os valores observados de /manager/health e da funcionalidade de resumo.

Para o fluxo de trabalho de resumo, nomeie cada operação pública do Gerenciador usada (método e caminho /manager/...), os campos importantes da requisição, a resposta observada e o repasse de summaryPipelineId para STATE_ID. Quando uma pré-condição bloquear a execução, separe claramente as sondagens observadas dos comandos não executados e ainda mostre a exata requisição válida, condição de conclusão e etapa de recuperação sem inventar ids ou conteúdo de resumo.

Gerenciar

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # listar todos
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # excluir um