비디오 분석

비디오 분석은 서버의 /api/llm/video/analyze에서 처리됩니다. 엔드포인트는 비디오 파일과 분석 매개변수가 포함된 멀티파트 폼 데이터를 수용합니다.

페이로드 필드

• video: 비디오 파일 (MP4, WebM, MOV)
• model: 분석을 위한 모델 식별자
• prompt: 선택적 커스텀 분석 프롬프트
• max_frames: 샘플링할 최대 프레임 수
• fps: 프레임 샘플링 속도

• H.264 또는 H.265 코덱이 있는 MP4
• VP8 또는 VP9 코덱이 있는 WebM
• 화면 녹화 도구의 MOV
• 최대 파일 크기: 100MB

프레임은 커버리지와 API 비용의 균형을 맞추기 위해 구성 가능한 간격으로 추출됩니다. 낮은 프레임 속도는 토큰 사용량을 줄이지만 빠른 변경을 놓칠 수 있습니다.

기본 속도는 초당 1프레임입니다. 상세한 UI 분석의 경우 2-3 FPS가 필요할 수 있습니다.

샘플링 매개변수

• fps: 추출할 초당 프레임 수 (0.5-5)
• max_frames: 최대 총 프레임 수 (10-100)
• start_time: 샘플링을 시작할 오프셋
• end_time: 샘플링을 중지할 오프셋

비디오 분석에는 비전 지원 모델이 필요합니다. 모델 식별자는 provider/model 형식을 따릅니다. 현재 google/* 모델만 네이티브 비디오 분석을 지원합니다.

Google Gemini 모델은 비디오를 네이티브로 처리할 수 있지만, 다른 비전 모델은 프레임별 이미지 분석이 필요합니다.

샘플링된 프레임은 분석 프롬프트와 함께 비전 모델로 전송됩니다. 모델은 UI 상태와 사용자 액션에 대한 구조화된 관찰을 생성합니다.

시스템 프롬프트는 모델이 녹화의 특정 측면에 집중하도록 안내합니다.

프롬프트 요소

• UI 인벤토리: 보이는 요소와 컨트롤 나열
• 액션 시퀀스: 사용자 액션을 순서대로 설명
• 오류 감지: 오류 상태와 메시지 식별
• 탐색 경로: 화면 전환 추적

• frame_observations: 프레임별 UI 설명
• action_timeline: 사용자 액션의 정렬된 목록
• error_summary: 관찰된 오류 또는 이슈
• context_summary: 고수준 워크플로우 설명

비디오 분석은 프레임 수와 해상도에 따라 토큰을 소비합니다. 각 프레임은 이미지 토큰으로 처리됩니다.

• tokens_sent: 프롬프트 + 이미지 토큰
• tokens_received: 분석 응답 토큰
• actual_cost: 모델 가격에서 계산됨

분석 결과는 task_type 'video_analysis'로 background_jobs 테이블에 저장됩니다. 응답에는 JSON 형식의 전체 분석이 포함됩니다.

결과는 작업 설명에 통합되거나 계획 워크플로우에서 직접 사용될 수 있습니다.

• server/src/handlers/proxy/video_handler.rs
• server/src/services/video_processor.rs
• desktop/src/components/video/VideoAnalyzer.tsx

비디오 분석 출력은 컨텍스트 인식 계획을 위해 작업 설명에 직접 피드될 수 있습니다.

context_summary는 구현 계획의 시작점으로 특히 유용합니다.