Communitygithub.com

AiCurv/ADBCommander

z-ai-web-dev-sdk를 사용하여 전문적인 동영상 이해 기능을 구현합니다. 사용자가 동영상 콘텐츠 분석, 모션 및 시간적 시퀀스 이해, 동영상 프레임에서 정보 추출, 동영상 장면 설명, 또는 동영상 기반 AI 분석이 필요할 때 이 스킬을 사용하세요. MP4, AVI, MOV 및 기타 일반 동영상 형식에 최적화되어 있습니다.

ADBCommander란 무엇인가요?

이 스킬은 z-ai-web-dev-sdk 패키지를 활용하여 AI 모델이 동영상 콘텐츠를 분석, 설명 및 정보를 추출할 수 있도록 하는 전문적인 동영상 이해 기능을 제공합니다. 장면 이해, 동작 감지, 시간적 시퀀스 분석, 이벤트 감지, 콘텐츠 요약, 장면 전환 감지, 객체 추적, 시청각 분석 등 포괄적인 동영상 분석 기능을 지원합니다. CLI를 통한 빠른 분석과 SDK를 통한 심층적인 대화형 분석을 모두 지원하며, 단일 동영상 분석, 멀티 턴 대화, 동영상 품질 평가, 콘텐츠 검열, 스포츠 분석 등 다양한 사용 사례에 대응할 수 있습니다. MP4, AVI, MOV, WebM, MKV, FLV 등 주요 동영상 형식을 지원하며, CDN 업로드, 키 프레임 변환, 인터벌 샘플링을 통한 최적화도 가능합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/video-understand

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

동영상 이해 스킬

이 스킬은 z-ai-web-dev-sdk 패키지를 사용하여 전문적인 동영상 이해 기능을 제공하며, AI 모델이 동영상 콘텐츠의 동작, 시간적 시퀀스 및 장면 변화를 분석, 설명 및 정보를 추출할 수 있도록 합니다.

스킬 경로

스킬 위치: {project_path}/skills/video-understand

이 스킬은 프로젝트의 위 경로에 있습니다.

참고 스크립트: 예제 테스트 스크립트는 {Skill Location}/scripts/ 디렉터리에서 빠른 테스트 및 참조를 위해 제공됩니다. 실제 예제는 {Skill Location}/scripts/video-understand.ts를 참조하세요.

개요

동영상 이해는 동영상 콘텐츠 분석에 특화되어 있으며, 다음과 같은 기능을 제공합니다.

  • 동영상 장면 이해 및 설명
  • 동작 및 움직임 감지
  • 시간적 시퀀스 분석
  • 동영상 내 이벤트 감지
  • 동영상 콘텐츠 요약
  • 장면 전환 감지
  • 프레임 간 사람 및 객체 추적
  • 시청각 콘텐츠 분석(해당되는 경우)

중요: z-ai-web-dev-sdk는 백엔드 코드에서만 사용해야 합니다. 클라이언트 측 코드에서는 절대 사용하지 마세요.

전제 조건

z-ai-web-dev-sdk 패키지는 이미 설치되어 있습니다. 아래 예제와 같이 가져와서 사용하세요.

CLI 사용법 (간단한 작업의 경우)

빠른 동영상 분석 작업의 경우 코드를 작성하는 대신 z-ai CLI를 사용할 수 있습니다. 간단한 동영상 설명, 테스트 또는 자동화에 이상적입니다.

기본 동영상 분석

# URL에서 동영상 분석
z-ai vision --prompt "이 동영상에서 무슨 일이 일어나는지 요약해 줘" --image "https://example.com/video.mp4"

# 참고: 동영상 URL에도 --image 플래그를 사용하세요
z-ai vision -p "주요 이벤트를 설명해 줘" -i "https://example.com/presentation.mp4"

로컬 동영상 분석

# 로컬 동영상 파일 분석
z-ai vision -p "이 동영상에는 어떤 활동이 표시되나요?" -i "./recording.mp4"

# 응답을 파일에 저장
z-ai vision -p "자세한 요약을 제공해 줘" -i "./meeting.mp4" -o summary.json

고급 동영상 분석

# 생각하기를 포함한 복잡한 장면 이해
z-ai vision \
  -p "이 동영상을 분석하여 다음을 식별하세요: 1) 주요 이벤트, 2) 사람들과 그들의 행동, 3) 주요 순간의 타임라인" \
  -i "./event.mp4" \
  --thinking \
  -o analysis.json

# 동작 감지
z-ai vision \
  -p "이 동영상에서 사람들이 수행한 모든 동작을 식별하세요" \
  -i "./sports.mp4" \
  --thinking

스트리밍 출력

# 동영상 분석 스트리밍
z-ai vision -p "이 동영상 콘텐츠를 설명해 줘" -i "./video.mp4" --stream

CLI 파라미터

  • --prompt, -p <text>: 필수 - 동영상에 대한 질문 또는 지시사항
  • --image, -i <URL 또는 경로>: 선택 사항 - 동영상 URL 또는 로컬 파일 경로(이름과 달리 동영상에서도 작동)
  • --thinking, -t: 선택 사항 - 복잡한 분석을 위한 사고 사슬 추론 활성화 (기본값: 비활성화)
  • --output, -o <path>: 선택 사항 - 출력 파일 경로 (JSON 형식)
  • --stream: 선택 사항 - 실시간으로 응답 스트리밍

지원되는 동영상 형식

  • MP4 (.mp4) - 가장 널리 지원되는 형식
  • AVI (.avi) - 오디오 비디오 인터리브
  • MOV (.mov) - QuickTime 형식
  • WebM (.webm) - 웹 최적화 형식
  • MKV (.mkv) - Matroska 형식
  • FLV (.flv) - Flash 비디오 형식

CLI 사용 시기 vs SDK 사용 시기

다음 경우 CLI 사용:

  • 빠른 동영상 요약
  • 일회성 동영상 분석
  • 동영상 이해 기능 테스트
  • 간단한 자동화 스크립트
  • 동영상 설명 생성

다음 경우 SDK 사용:

  • 동영상에 대한 다중 턴 대화
  • 복잡한 동영상 처리 파이프라인
  • 오류 처리가 필요한 프로덕션 애플리케이션
  • 동영상 처리 로직과의 맞춤형 통합
  • 맞춤형 워크플로를 사용한 배치 동영상 처리

권장 접근 방식

로컬 동영상의 성능과 안정성을 높이려면 다음을 고려하세요.

  1. 동영상을 CDN에 업로드하고 URL 사용
  2. 짧은 동영상의 경우 키 프레임을 이미지로 변환하여 더 빠르게 분석
  3. 긴 동영상의 경우 청크 분할 또는 간격 샘플링 고려

기본 동영상 이해 구현

단일 동영상 분석

import ZAI from 'z-ai-web-dev-sdk';

async function analyzeVideo(videoUrl, prompt) {
  const zai = await ZAI.create();

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: prompt
          },
          {
            type: 'video_url',
            video_url: {
              url: videoUrl
            }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

// 사용 예제
const summary = await analyzeVideo(
  'https://example.com/presentation.mp4',
  '이 동영상에서 제시된 핵심 요점을 요약해 줘'
);

const actionDetection = await analyzeVideo(
  'https://example.com/sports.mp4',
  '이 동영상에서 수행된 모든 운동 동작을 식별하고 설명해 줘'
);

동영상 장면 이해

import ZAI from 'z-ai-web-dev-sdk';

async function understandVideoScenes(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `이 동영상을 분석하여 다음을 제공하세요:
1. 동영상 콘텐츠의 전체 요약
2. 주요 장면 또는 세그먼트 (가능한 경우 대략적인 타임스탬프 포함)
3. 주요 인물 또는 캐릭터와 그들의 역할
4. 시간순으로 중요한 동작 또는 이벤트
5. 설정 및 환경 설명
6. 전반적인 분위기 또는 톤`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' } // 자세한 분석을 위해 활성화
  });

  return response.choices[0]?.message?.content;
}

// 사용
const sceneAnalysis = await understandVideoScenes(
  'https://example.com/documentary.mp4'
);

동작 및 움직임 감지

import ZAI from 'z-ai-web-dev-sdk';

async function detectActions(videoUrl, specificAction = null) {
  const zai = await ZAI.create();

  const prompt = specificAction
    ? `이 동영상에서 "${specificAction}"의 모든 인스턴스를 식별하세요. 각 인스턴스에 대해 언제 발생하는지와 어떻게 수행되는지에 대한 세부 정보를 제공하세요.`
    : '이 동영상에서 모든 중요한 동작과 움직임을 식별하고 설명하세요. 이를 수행하는 사람과 언제 발생하는지 포함하세요.';

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

// 사용
const runningActions = await detectActions(
  'https://example.com/sports.mp4',
  'running'
);

const allActions = await detectActions(
  'https://example.com/activity.mp4'
);

이벤트 타임라인 추출

import ZAI from 'z-ai-web-dev-sdk';

async function extractTimeline(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `이 동영상에서 이벤트에 대한 자세한 타임라인을 만드세요:
- 주요 순간과 전환 식별
- 대략적인 시간 (시작, 중간, 끝 또는 표시된 경우 특정 타임스탬프) 메모
- 각 주요 시점에서 발생하는 일 설명
- 이벤트 간의 원인 및 결과 관계 식별

시간순 목록으로 형식화하세요.`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

동영상 콘텐츠 분류

import ZAI from 'z-ai-web-dev-sdk';

async function classifyVideo(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `이 동영상 콘텐츠를 분류하세요:
1. 주요 카테고리 (예: 교육, 엔터테인먼트, 스포츠, 뉴스, 튜토리얼)
2. 하위 카테고리 또는 장르
3. 대상 청중
4. 콘텐츠 스타일 (전문적, 캐주얼, 다큐멘터리 등)
5. 주요 테마 또는 주제
6. 제안된 태그 (10-15개 키워드)

응답을 구조화된 JSON으로 형식화하세요.`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  const content = response.choices[0]?.message?.content;
  
  try {
    return JSON.parse(content);
  } catch (e) {
    return { rawResponse: content };
  }
}

고급 사용 사례

다중 턴 동영상 대화

import ZAI from 'z-ai-web-dev-sdk';

class VideoConversation {
  constructor() {
    this.messages = [];
  }

  async initialize() {
    this.zai = await ZAI.create();
  }

  async loadVideo(videoUrl, initialQuestion) {
    this.messages.push({
      role: 'user',
      content: [
        { type: 'text', text: initialQuestion },
        { type: 'video_url', video_url: { url: videoUrl } }
      ]
    });

    return this.getResponse();
  }

  async askFollowUp(question) {
    this.messages.push({
      role: 'user',
      content: [
        { type: 'text', text: question }
      ]
    });

    return this.getResponse();
  }

  async getResponse() {
    const response = await this.zai.chat.completions.createVision({
      messages: this.messages,
      thinking: { type: 'disabled' }
    });

    const assistantMessage = response.choices[0]?.message?.content;
    
    this.messages.push({
      role: 'assistant',
      content: assistantMessage
    });

    return assistantMessage;
  }
}

// 사용
const conversation = new VideoConversation();
await conversation.initialize();

const initial = await conversation.loadVideo(
  'https://example.com/lecture.mp4',
  '이 강의의 주요 주제는 무엇인가요?'
);

const followup1 = await conversation.askFollowUp(
  '언급된 핵심 개념을 설명해 주시겠어요?'
);

const followup2 = await conversation.askFollowUp(
  '이 개념을 설명하는 데 사용된 예시는 무엇인가요?'
);

동영상 품질 평가

import ZAI from 'z-ai-web-dev-sdk';

async function assessVideoQuality(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `이 동영상의 품질을 평가하세요:
1. 시각적 품질 (해상도, 선명도, 조명) - 1-10점
2. 오디오 품질 (오디오가 있는 경우) - 1-10점
3. 카메라 워크 (안정성, 프레이밍, 구성) - 1-10점
4. 제작 가치 (편집, 전환, 효과) - 1-10점
5. 콘텐츠 명확성 (메시지가 명확한가?) - 1-10점
6. 페이싱 (너무 빠름, 너무 느림, 적절함)
7. 기술적 문제 (아티팩트, 블러, 오디오 동기화 등)
8. 전체 평점 - 1-10점
9. 개선을 위한 구체적인 제안

각 기준에 대한 자세한 피드백을 제공하세요.`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

동영상 콘텐츠 검열

import ZAI from 'z-ai-web-dev-sdk';

async function moderateVideo(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `콘텐츠 검열을 위해 이 동영상을 검토하세요:
1. 부적절하거나 민감한 콘텐츠 확인
2. 잠재적인 안전 문제 식별
3. 일반적인 커뮤니티 가이드라인을 위반할 수 있는 콘텐츠 기록
4. 연령 적합성 평가
5. 보이는 저작권 자료 식별 (로고, 브랜드, 음악)
6. 전체 안전 등급: 안전 / 주의 / 검토 필요

식별된 우려 사항에 대한 구체적인 예를 제공하세요.`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

동영상 대본 생성 (시각적 설명)

import ZAI from 'z-ai-web-dev-sdk';

async function generateVisualTranscript(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `이 동영상의 상세한 시각적 대본을 생성하세요:
- 각 장면에서 무슨 일이 일어나는지 설명
- 화면에 나타나는 텍스트 기록
- 중요한 시각적 요소 설명
- 장면 변경 또는 전환 언급
- 사람들의 행동과 표정 설명 포함

시간 기반 내러티브로 형식화하세요 (예: "처음에...", "그 다음에...", "마지막으로...").`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

스포츠 동영상 분석

import ZAI from 'z-ai-web-dev-sdk';

async function analyzeSportsVideo(videoUrl, sport = null) {
  const zai = await ZAI.create();

  const prompt = sport
    ? `이 ${sport} 동영상을 자세히 분석하세요:
1. 선수와 그들의 포지션 식별
2. 주요 플레이와 전략 설명
3. 득점 이벤트 또는 중요한 순간 기록
4. 선수 성과 평가
5. 규칙 위반 또는 파울 식별
6. 경기의 페이스와 흐름 설명`
    : `이 스포츠 동영상을 분석하세요:
1. 플레이 중인 스포츠 식별
2. 주요 동작과 플레이 설명
3. 득점 또는 중요한 이벤트 기록
4. 선수 움직임과 전략 설명
5. 경기 또는 매치의 전체 평가`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

// 사용
const basketballAnalysis = await analyzeSportsVideo(
  'https://example.com/basketball-game.mp4',
  '농구'
);

const generalAnalysis = await analyzeSportsVideo(
  'https://example.com/sports-clip.mp4'
);

교육용 동영상 요약

import ZAI from 'z-ai-web-dev-sdk';

async function summarizeEducationalVideo(videoUrl, format = 'structured') {
  const zai = await ZAI.create();

  const prompt = format === 'structured'
    ? `이 교육용 동영상을 요약하세요:
1. 강의 제목 및 주제
2. 핵심 학습 목표 (2-3개)
3. 주요 개념 설명 (간결한 설명과 함께)
4. 사용된 예시 또는 데모
5. 주요 시사점 (3-5개 포인트)
6. 권장되는 후속 학습 주제

명확한 섹션과 불릿 포인트를 사용하여 구조화된 형식으로 응답하세요.`
    : `이 교육용 동영상의 간결한 한 단락 요약을 제공하세요. 핵심 포인트와 전반적인 교육적 가치에 초점을 맞추세요.`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

// 사용
const structuredSummary = await summarizeEducationalVideo(
  'https://example.com/coding-tutorial.mp4',
  'structured'
);

const conciseSummary = await summarizeEducationalVideo(
  'https://example.com/lecture.mp4',
  'concise'
);

오류 처리

import ZAI from 'z-ai-web-dev-sdk';

async function robustVideoAnalysis(videoUrl, prompt, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const zai = await ZAI.create();
      
      const response = await zai.chat.completions.createVision({
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: prompt },
              { type: 'video_url', video_url: { url: videoUrl } }
            ]
          }
        ],
        thinking: { type: 'disabled' }
      });

      if (!response.choices || response.choices.length === 0) {
        throw new Error('API로부터 응답 없음');
      }

      return response.choices[0]?.message?.content || '분석을 생성할 수 없음';
    } catch (error) {
      if (i === maxRetries - 1) {
        console.error(`모든 ${maxRetries}회 재시도 실패:`, error);
        return `분석 실패: ${error.message}`;
      }
      
      const backoffTime = Math.pow(2, i) * 1000; // 지수 백오프
      console.warn(`시도 ${i + 1} 실패, ${backoffTime}ms 후 재시도 중...`);
      await new Promise(resolve => setTimeout(resolve, backoffTime));
    }
  }
}

모범 사례

  1. 명확한 프롬프트: 정확한 분석을 얻기 위해 구체적이고 구조화된 프롬프트 제공
  2. 동영상 품질: 분석 정확도를 위해 좋은 품질의 동영상 사용
  3. 동영상 길이: 긴 동영상의 경우 요약 또는 타임라인 추출 사용
  4. 생각하기 사용: 복잡한 분석에는 활성화, 간단한 쿼리에는 비활성화
  5. 오류 처리: 프로덕션 앱의 경우 위의 재시도 예제 구현
  6. 비용 고려 사항: 처리 시간과 토큰 사용량에 따라 비용이 발생함을 인지
  7. 멀티 턴 분석: 동영상에 대해 심층적인 후속 질문을 할 기회가 있을 때 VideoConversation 클래스 사용
  8. 콘텐츠 검증: 모든 분석 결과를 생성된 출력으로 취급하고 중요 결정에 대해 검증

결론

Video Understanding Skill은 z-ai-web-dev-sdk를 통해 동영상 콘텐츠를 분석, 이해 및 설명하기 위한 포괄적인 기능을 제공합니다. 기본적인 동영상 설명부터 고급 스포츠 분석 및 교육용 콘텐츠 요약까지 광범위한 사용 사례를 지원합니다. 이 스킬을 AI 에이전트와 통합하면 동영상 콘텐츠를 이해하고 상호 작용하는 능력이 크게 향상되어 동영상 라이브러리의 자동화된 콘텐츠 분석, 콘텐츠 검열, 교육 도구, 스포츠 분석 플랫폼 등에 이상적입니다.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

AiCurv/ADBCommander

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

AiCurv/ADBCommander

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

AiCurv/ADBCommander

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

AiCurv/ADBCommander

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

AiCurv/ADBCommander

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

AiCurv/ADBCommander

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

AiCurv/ADBCommander

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

관련 스킬