Communitygithub.com

웹 임베드 비디오 최적화

기존 영상을 웹사이트의 히어로/배경/루프 영상으로 최적화하고 임베드합니다. 파일이 너무 크거나, 자동 재생이 안 되거나(Mobile/Safari), 코덱 오류가 발생하거나, 화질이 부드러울 때 사용합니다.

웹 임베드 비디오 최적화란 무엇인가요?

이 스킬은 기존에 보유한 화면 녹화, 휴대폰 내보내기, HEVC 렌더링 등의 소스 클립을 웹에 안전하게 재생할 수 있는 H.264 포맷으로 변환하고, 로딩 속도를 높이며 레티나 해상도에 대응하도록 최적화한 후 웹사이트에 임베드합니다. 주요 기능으로는 레티나 인식 크기 조정(scaling)과 적절한 CRF 값을 통한 대역폭 절약, 빠른 시작을 위한 faststart 적용, 그리고 Safari를 포함한 모든 브라우저에서의 호환성을 보장하는 yuv420p 픽셀 포맷 설정 등이 있습니다. Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 작동하며, `ffprobe`로 비디오 정보를 진단하고 `ffmpeg`로 트랜스코딩한 후 HTML `<video>` 태그로 임베드하는 일련의 과정을 자동화합니다. 이 스킬은 영상 자체를 생성하거나 편집하는 것이 아니라, 이미 존재하는 영상을 웹 환경에 최적화하여 배포하는 것에 특화되어 있으며, 완료 후 실제 재생 여부를 확인하는 검증 단계를 포함합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ever-just/agentskills/tree/HEAD/skills/web-embed-video-optimization

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

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

미리보기

스킬 README에서

문서

웹 임베드 비디오 최적화은(는) 무엇을 하나요?

소스 클립(화면 녹화, 휴대폰 내보내기, HEVC 렌더링)을 빠르고, 선명하며, 안정적으로 자동 재생되는 히어로/배경/루프 영상으로 변환하고 임베드합니다. 일반적으로 큰 효과를 볼 수 있습니다. 레티나 인식 H.264를 적절한 CRF로 인코딩하면 1080p 화면 녹화 파일을 눈에 띄는 손실 없이 약 8MB에서 1.5MB로 줄이고, 자동 재생 및 코덱 문제를 해결합니다.

영상 생성 또는 애니메이션이 필요하다면 대신 [[remotion]] / [[moviepy]] / [[motion-canvas]]를 사용하세요. 이 스킬은 이미 보유한 영상을 최적화합니다.

사용 시기

  • 웹사이트에 히어로, 배경, 또는 루핑 데모 영상을 추가/교체할 때.
  • 영상이 너무 무겁거나, 자동 재생이 안 되거나(모바일/Safari), 코덱 오류가 발생하거나, 화질이 부드럽게 보일 때.

레시피

1. 먼저 진단

ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,width,height,r_frame_rate,duration,pix_fmt,profile \
  -of default=noprint_wrappers=1 in.mp4
ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 in.mp4   # 오디오?
# faststart 확인: 'moov'가 'mdat'보다 앞에 있는가? (moov가 끝에 있으면 느린 시작)

2. 트랜스코딩 (웹 안전 + 레티나 인식)

ffmpeg -y -i in.mp4 -vf "scale=1600:-2" \
  -c:v libx264 -profile:v high -pix_fmt yuv420p -crf 23 -preset slow \
  -movflags +faststart -an -r 30 out.mp4
  • -pix_fmt yuv420p — Safari/광범위한 호환성에 필수 (yuv444/422는 재생 안 됨).
  • -movflags +faststart — moov 아톰을 앞쪽으로 이동시켜 파일을 완전히 다운로드하기 전에 재생을 시작할 수 있게 합니다. 이 옵션이 없으면 자동 재생 히어로 영상이 느린 링크에서 지연됩니다.
  • -an — 오디오 제거; 음소거된 배경 루프에는 오디오가 필요하지 않습니다 (파일 크기 감소).
  • scale=1600:-2 — 네이티브 1080p/4K가 아닌 CSS 표시 너비의 약 2배로 인코딩합니다. ≤820px 프레임에서 1600px은 레티나 선명도를 제공하면서 훨씬 가볍습니다. -2는 높이를 짝수로 유지합니다 (H.264 요구 사항).
  • -crf 23 -preset slow — 고품질, 좋은 압축률. 화면/UI 콘텐츠는 특히 잘 압축되며, 파일이 여전히 무거운 경우에만 CRF를 25–26으로 높이세요.

3. 포스터 프레임

ffmpeg -y -ss 3 -i in.mp4 -vframes 1 -vf "scale=1600:-2" -q:v 3 poster.jpg

빈 도입 프레임이 아닌 대표적인 순간(-ss)을 선택하세요.

4. 임베드

<video autoplay muted loop playsinline preload="auto" poster="/path/poster.jpg">
  <source src="/path/out.mp4" type="video/mp4"/>
</video>
  • muted + playsinline + autoplay 는 모두 모바일 자동 재생에 필요합니다.
  • 컨테이너 CSS: video{display:block;width:100%;height:auto}는 16:9 클립이 자체 높이를 설정하도록 합니다; overflow:hidden;border-radius가 있는 프레임으로 감싸세요.

5. 제공 (Odoo 테넌트)

공개 ir.attachment 로 저장하고 /web/content/<id> (영상) 및 /web/image/<id> (포스터)로 참조하세요. — [[everjust-website-customization]] 참조. 바이너리는 docker cp를 통해 전송합니다 (셸은 컨테이너 내부에서 실행). 새로운 첨부 파일 ID를 사용하고 뷰를 다시 지정하세요. 오래된 ID를 덮어쓰지 마십시오. 브라우저/CDN 캐시 문제를 피하기 위함입니다. 뷰 편집은 렌더링을 위해 컨테이너 재시작이 필요합니다.

확인 (필수)

[[cdp-render-verification]]으로 실제 재생 여부를 확인하세요. --autoplay-policy=no-user-gesture-required 옵션으로 Chrome을 실행한 후 <video> 요소를 읽습니다:

  • readyState === 4 (HAVE_ENOUGH_DATA), paused === false, 짧은 대기 후 currentTime > 0 (진행 중), 그리고 videoWidth/videoHeight가 인코딩과 일치해야 합니다.
  • 데스크탑과 모바일에서 확인하고, 페이지에 가로 오버플로가 없는지 확인하세요.

관련 항목

  • [[everjust-website-customization]] — Odoo 첨부 파일 + 뷰 임베드를 통한 제공.
  • [[cdp-render-verification]] — 재생 증명.
  • [[remotion]] / [[moviepy]] — 영상 생성/애니메이션 (반대 작업).

Individual skills in this repo

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

ever-just/agentskills

> Declarative animations for React. Springs, gestures, layout animations, and page transitions. GPU-accelerated, production-ready.

ever-just/agentskills

> Create animated logos, icons, and micro-interactions as lightweight Lottie JSON files. No After Effects needed — build animations entirely in code.

ever-just/agentskills

> A TypeScript library using generators to program animations with a real-time editor. Ideal for explainer videos, code walkthroughs, and educational content.

ever-just/agentskills

> Add animated subtitles and captions to Remotion videos from .SRT files. TikTok-style word-by-word highlights, karaoke effects, and more.

ever-just/agentskills

> Create videos programmatically using React components. The most mature framework for code-driven video production.

ever-just/agentskills

> Copy-paste video components for Remotion. Intros, text effects, transitions, and full scene templates. Like shadcn/ui but for video.

ever-just/agentskills

Extract actionable intelligence from video content across YouTube, Vimeo, and company websites. Video reveals what text sources cannot: facility scale, team composition, product demonstrations, signage, event attendance, and operational reality.

ever-just/agentskills

Full conversion audit for any homepage or landing page. Use when someone asks to "review my homepage," "audit my landing page," "why isn't my page converting," "check my website," or wants feedback on their marketing page. Requires URL or screenshot before proceeding.

ever-just/agentskills

Automatically fetch YouTube video transcripts, generate structured summaries, and send full transcripts to messaging platforms. Detects YouTube URLs and provides metadata, key insights, and downloadable transcripts.

관련 스킬