Communitygithub.com

AcTR 앱

z-ai-web-dev-sdk를 사용하여 특화된 비디오 이해 기능을 구현합니다. 사용자가 비디오 콘텐츠를 분석하고, 동작 및 시간적 시퀀스를 이해하며, 비디오 프레임에서 정보를 추출하고, 비디오 장면을 설명하거나 비디오 기반 AI 분석을 수행해야 할 때 이 스킬을 사용하세요. MP4, AVI, MOV 및 기타 일반적인 비디오 포맷에 최적화되어 있습니다.

AcTR 앱란 무엇인가요?

이 스킬은 AI 모델이 비디오 콘텐츠를 분석, 설명 및 정보를 추출할 수 있도록 z-ai-web-dev-sdk 패키지를 활용한 특화된 비디오 이해 기능을 제공합니다. 동작 감지, 시간적 시퀀스 분석, 장면 전환 감지, 이벤트 추출, 비디오 요약 등 포괄적인 비디오 분석을 지원합니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼과 호환되며, CLI 도구와 SDK 방식 모두를 지원합니다. CLI는 빠른 일회성 분석이나 간단한 자동화에 적합하고, SDK는 다중 턴 대화, 복잡한 파이프라인, 프로덕션 애플리케이션에 권장됩니다. 내부적으로는 createVision API를 통해 비디오 URL을 처리하며, MP4, AVI, MOV, WebM, MKV, FLV 등 주요 비디오 포맷을 지원합니다. 사용자는 비디오 장면 이해, 동작 감지, 타임라인 추출, 콘텐츠 분류, 품질 평가, 콘텐츠 모더레이션, 스포츠 분석 등 다양한 고급 사용 사례를 구현할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/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 <경로>: 선택 사항 - 출력 파일 경로 (JSON 형식)
  • --stream: 선택 사항 - 실시간으로 응답 스트리밍

지원되는 비디오 포맷

  • MP4 (.mp4) - 가장 널리 지원되는 포맷
  • AVI (.avi) - Audio Video Interleave
  • MOV (.mov) - QuickTime 포맷
  • WebM (.webm) - 웹 최적화 포맷
  • MKV (.mkv) - Matroska 포맷
  • FLV (.flv) - Flash Video 포맷

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;
}

Individual skills in this repo

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

관련 스킬