비디오 오버레이 정리 (Video Overlay Cleanup)

저장소: https://github.com/hyuuuliu/video-overlay-cleanup-skill

개요

이 스킬을 사용하면 원본 비디오나 화면 녹화에서 눈에 띄는 오버레이를 줄여 더 깔끔한 버전으로 만들 수 있습니다.

이 스킬은 워크플로우 스킬로, 마법처럼 원본을 완벽하게 복원한다는 주장이 아닙니다. 다음 경우에 가장 적합합니다:

안정적인 위치에 고정된 오버레이
알려진 마스크가 있는 짧은 배너 또는 떠 있는 UI
편집 또는 재배포를 위한 화면 녹화 정리
Gemini Nano Banana 2를 위한 프레임별 복원 작업 준비

이 스킬은 작업을 비디오 정리 또는 오버레이 제거로 간주해야 하며, 숨겨진 내용이 반드시 사실적으로 복원된다고 보장해서는 안 됩니다.

제공자 지원

이 버전은 생성적 프레임 복원을 위해 하나의 실제 모델 제공자를 지원합니다:

Gemini Nano Banana 2 (Gemini 이미지 생성 및 편집 API 사용)

gemini-nano-banana 모드를 사용하기 전에 사용자가 API 키를 설정해야 합니다:

export GEMINI_API_KEY='your_api_key_here'

선택적 모델 재정의:

export GEMINI_MODEL='gemini-3.1-flash-image-preview'
export GEMINI_IMAGE_SIZE='1K'

런타임 요구 사항

스킬 설치 또는 검토 시 다음 사항을 명시적으로 선언하세요:

필수 바이너리:
- bash
- ffmpeg
- ffprobe
- python3
Gemini 모드에 필요한 자격 증명:
- GEMINI_API_KEY
선택적 Gemini 환경 변수:
- GEMINI_MODEL
- GEMINI_IMAGE_SIZE
Gemini 모드에 필요한 Python 패키지:
- google-genai
- Pillow

사용자가 Gemini 경로를 원할 경우 references/gemini-provider.md를 참조하세요.

가장 적합한 요청

사용자가 다음 중 하나를 요청할 때 이 스킬을 사용하세요:

동영상에서 상태 표시줄, 상단 바, 하단 바, 자막 스트립, 워터마크, 플로팅 컨트롤 제거
재사용 또는 클리핑 전에 휴대폰 화면 녹화 정리
동영상을 프레임으로 분할, 마스크 영역 복원 후 재구성
반복 가능한 FFmpeg 파이프라인을 사용한 비디오 오버레이 제거
Gemini Nano Banana 2를 사용하여 마스킹된 오버레이 영역을 프레임별로 복원
알려진 오버레이 영역에 대한 마스크 또는 영역 사양 생성

기본 전략

작동 가능한 가장 가벼운 경로를 선택하세요:

고정 오버레이, 안정적인 영역: 생성된 마스크와 removelogo를 사용하여 ffmpeg 사용
고정 영역이지만 removelogo 품질이 충분하지 않은 경우: 프레임 추출 후 마스킹된 영역에 Gemini Nano Banana 2 실행
동적 오버레이: 프레임 추출, 마스크 생성 또는 전파, Gemini Nano Banana 2 실행 후 비디오 재구성

고정 영역이나 결정론적 방법으로 충분할 때 전체 프레임 생성적 편집을 기본값으로 사용하지 마세요.

워크플로우

1. 오버레이 분류

다음 중 해당하는 경우를 결정하세요:

fixed-edge-overlay: 상단 상태 표시줄, 하단 탐색 바, 자막 스트립, 모서리 로고
fixed-box-overlay: 한 영역에 고정된 워터마크 또는 플로팅 위젯
dynamic-overlay: 알림 배너, 움직이는 스티커, 일시적인 플로팅 컨트롤
unknown: 사용자가 마스크 정의에 필요한 충분한 세부 정보를 아직 제공하지 않음

오버레이 위치가 불명확하면, 필요한 가장 작은 세부 정보를 묻거나 합리적인 첫 번째 마스크를 제안하고 초안임을 표시하세요.

2. 경로 선택

fixed-edge-overlay 또는 fixed-box-overlay의 경우 내장 스크립트를 선호하세요:

scripts/make_mask.py
scripts/clean_video.sh --mode removelogo

Gemini 기반 워크플로우의 경우 다음을 사용하세요:

scripts/clean_video.sh --mode gemini-nano-banana
scripts/gemini_nano_banana_edit.py

저수준 또는 사용자 정의 제공자 워크플로우의 경우 다음을 사용하세요:

scripts/extract_frames.sh
scripts/restore_frames.py
scripts/rebuild_video.sh

종단 간 흐름은 references/pipeline.md를, 마스크 설계 지침은 references/mask-strategies.md를, Gemini 특정 동작은 references/gemini-provider.md를 참조하세요.

3. 마스크를 신중하게 구성하세요

마스크가 성공을 좌우합니다. 다음 규칙을 따르세요:

전체 프레임이 아닌 오버레이만 마스킹하세요
너무 큰 마스크보다 약간 빡빡한 마스크를 선호하세요
고정 막대의 경우 사전 설정 또는 백분율 기반 영역을 사용하세요
동적 오버레이의 경우 프레임 편집 범위를 국소적이고 명시적으로 유지하세요

이 스킬에서 사용하는 영역 형식은 x:y:w:h입니다. 각 값은 120과 같은 픽셀 또는 8%와 같은 백분율일 수 있습니다.

예시:

상단 7%: 0:0:100%:7%
하단 스트립: 0:92%:100%:8%
모서리 워터마크: 78%:3%:18%:12%

4. 정리 경로 실행

빠른 고정 오버레이 경로

오버레이가 한 곳에 고정되어 있을 때 사용하세요.

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode removelogo \
  --region '0:0:100%:7%'

사전 설정을 추가할 수도 있습니다:

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode removelogo \
  --preset iphone-status-bar

Gemini Nano Banana 2 경로

사용자가 마스킹된 프레임별 복원을 원할 때 사용하세요.

export GEMINI_API_KEY='your_api_key_here'

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --image-size 1K

선택적 모델 재정의:

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --model gemini-3.1-flash-image-preview \
  --image-size 2K

사용자 정의 프레임 편집 경로

사용자가 Gemini 대신 사용자 정의 편집기 명령을 명시적으로 원할 때만 사용하세요.

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode frame-edit \
  --region '0:0:100%:12%' \
  --editor-cmd 'my-editor --input {input} --mask {mask} --output {output}'

편집기 명령은 다음을 수신합니다:

{input}: 원본 프레임 경로
{mask}: 마스크 경로
{output}: 대상 프레임 경로
{index}: 0부터 시작하는 프레임 번호

5. 한계를 명시적으로 언급하세요

다음 중 하나가 해당될 때 항상 언급하세요:

숨겨진 콘텐츠가 어떤 프레임에서도 표시된 적이 없음
결과가 사실적 복원이 아닌 시각적 재구성임
오버레이가 동적이고 마스크가 근사치임
프레임별 편집에는 이 첫 번째 패스 이상의 시간적 안정화가 필요할 수 있음
Gemini는 특히 큰 마스킹 영역에서 프레임마다 약간씩 달라질 수 있음
Gemini 모드는 실행 중 프레임 수, 기본 비용 추정, 누적 토큰/지출 진행 상황을 보고함
Gemini 모드는 저장 시 원본 프레임의 마스크되지 않은 모든 픽셀을 보존하므로 마스킹된 영역만 모델 출력에서 채택됨

알려진 제한 사항

위험 설명을 간단히 유지하세요:

마스킹되거나 덮인 영역이 항상 안정적으로 복원되는 것은 아님
결과는 그럴듯한 시각적 정리이지, 보장된 진실 복원이 아님
Gemini 처리는 특히 긴 동영상이나 높은 프레임 수에서 비용이 많이 들 수 있음

현재 신뢰성 참고 사항

현재 Gemini 구현은 여러 안전 장치를 사용합니다:

처리 시작 전 예산 추정
처리 중 누적 토큰 및 지출 보고
프레임별 검증 및 재시도
일시적인 제공자 오류에 대한 요청 수준 재시도
원본 프레임의 마스크되지 않은 모든 픽셀을 유지하는 마스킹 합성

마지막 안전 장치는 중요합니다: 모델이 흰색 마스크 외부의 햄스터, 케이지 또는 기타 보이는 장면 콘텐츠를 편집하더라도 저장된 출력은 원본 마스크되지 않은 픽셀을 계속 유지합니다. 이는 시각적 안정성을 향상시키지만, 모든 유용한 편집은 제공된 마스크 내에서 이루어져야 함을 의미합니다.

출력 기대 사항

좋은 결과에는 다음이 포함됩니다:

정리된 비디오 경로
선택한 방법: removelogo, gemini-nano-banana 또는 frame-edit
사용된 정확한 마스크 또는 사전 설정
GEMINI_API_KEY가 필요했는지 여부
Gemini 모드가 처리할 계획이었던 프레임 수
Gemini 호출 시작 전 기본 예상 비용
처리 중 보고된 누적 토큰 및 지출 요약
사실감, 일관성 또는 잔여 아티팩트에 관한 중요한 주의 사항

유용한 경우 작업 디렉터리를 유지하여 사용자가 다음을 검사할 수 있도록 하세요:

추출된 프레임
생성된 마스크 파일
재구성된 중간 비디오
작업 매니페스트

품질 기준

야심 차지만 노이즈가 많은 편집보다 안정적이고 반복 가능한 정리를 선호하세요
프레임의 손대지 않은 부분을 편집하지 마세요
결정론적 FFmpeg 경로를 먼저 사용하세요
생성적 편집을 기본값이 아닌 대상 범위를 한정한 대체 수단으로 취급하세요
더 깔끔해 보임과 사실적으로 복원됨을 구분하세요
제공자 API 키가 필요할 때 사용자에게 알리세요

프롬프트 패턴

좋은 호출 예시:

"$video-overlay-cleanup을 사용하여 이 화면 녹화에서 상단 상태 표시줄을 제거해 줘."
"$video-overlay-cleanup을 Gemini Nano Banana 2와 함께 사용하여 이 비디오의 상단 배너를 정리해 줘."
"$video-overlay-cleanup을 사용하여 이 비디오를 프레임으로 분할하고, 떠 있는 오버레이를 정리한 다음 재구성해 줘."

구현 세부 사항을 보려면 다음을 로드하세요:

hyuuuliu/video-overlay-cleanup-skill

video-overlay-cleanup-skill란 무엇인가요?

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

문서