Communitygithub.com

muyunxue/인물-회피-자막-킷

MMD 댄스 영상에서 인물을 가리지 않는 자막 레이아웃을 생성합니다. 프레임별로 댄서의 경계 상자를 측정하고, 큐별로 합집합을 계산한 후, 안전한 측면/상단 열에 텍스트를 배치하며, 모든 프레임에서 겹침이 0임을 검증합니다. 자막이 인물을 가릴 때 이 스킬을 로드하세요.

인물-회피-자막-킷란 무엇인가요?

이 스킬은 MMD 댄스 영상에서 캐릭터(인물)를 가리지 않는 자막 레이아웃을 자동으로 생성하는 AI 에이전트 도구입니다. 배경 차분(background subtraction)을 통해 프레임별로 캐릭터의 경계 상자(bounding box)를 빠르게 추정하고, 가사 구간(큐) 내에서 캐릭터 움직임을 고려한 합집합 영역을 계산합니다. 이후 텍스트를 좌우 측면 열 또는 상하단 모서리에 배치하고, 축소된 해상도(640×270)에서 모든 프레임에 대해 문자 상자와 캐릭터 마스크의 겹침을 픽셀 단위로 검증하여 완전히 겹침이 없음을 보장합니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 코딩 어시스턴트와 함께 사용하도록 설계되었으며, Windows PowerShell 환경에서 Python 스크립트(`avoid_side2.py`)를 실행하여 ASS 자막 파일과 렌더링 영상을 생성합니다. 주요 기능으로는 '완전히 가리지 않음'(겹침 0%)과 '가급적 가리지 않음'(날개/배경 겹침 허용) 두 가지 모드를 지원하며, 사용자가 '자막이 인물을 가리지 않게' 또는 '완전히 피하기' 등의 요청을 할 때 적합합니다. 이 스킬은 특히 날개가 넓거나 몸이 큰 캐릭터가 있는 MMD 댄스 영상에서 유용하며, 기존 고정 하단 레이아웃이 인물을 7~12% 가리는 문제를 해결합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/muyunxue/dance-mmd-subtitle-kit/tree/HEAD/skills/avoid-subtitles

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

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

문서

인물 회피 자막 (완전/가급적 가리지 않음)

0. 두 가지 목표 구분

  • "완전히 가리지 않음": 각 문자 상자와 모든 프레임의 인물 마스크 간 교집합 = 0. 단점은 문자를 양쪽/상단 좁은 열에만 배치할 수 있고, 글자 크기가 제한됨.
  • "가급적 가리지 않음": 날개 가장자리/배경과의 겹침은 허용하지만, 얼굴과 몸통은 반드시 깨끗해야 함. 큰 글자 스타일(S4/S6 등)을 계속 사용할 수 있으며, 근접 샷 프레임만 확인.

이 스킬은 기본적으로 "완전히 가리지 않음" 을 수행하며 검증 가능한 데이터를 제공합니다. 사용자가 "화려한/큰 글자/아트 폰트"를 요청하면 후자일 가능성이 높습니다.

1. 핵심 알고리즘 (빠른 버전: bbox만 사용)

더 이상 픽셀 단위 정밀 매트를 계산하지 않고, 인물의 경계 상자(bounding box) 만 필요로 하며, 1/4 해상도로 계산하여 매우 빠릅니다:

  1. 배경판 bg_half.npy (1280×540, subject-color-grade의 2.1/3.1 참조).
  2. 각 프레임을 640×270으로 축소하고 배경판과 차분 계산: d = |frame-bg|.max(axis=2), 임계값 38 (낮은 임계값은 LOVE 조명/광점을 포함시킴).
  3. MaxFilter(5) 팽창 → 최대 연결 성분(BFS, 640×270에서 매우 빠름) → bbox 추출 후 ×4 하여 전체 해상도로 복원.
  4. 가사 문장 창(window) 내에서 각 프레임의 bbox를 합집합(한 문장 내에서 인물이 움직이므로 문장 전체의 가장 넓은 범위 사용)하여 각 문장에 대해 bounds = (left,right,top,bottom)를 얻음.
  5. 레이아웃: 텍스트 열을 left-50 왼쪽 / right+50 오른쪽 / 상단 / 하단에 배치; 사용 가능한 너비에 따라 글자 크기 축소.
  6. 프레임별 재검증: 각 문자 상자를 640×270으로 매핑하고 각 프레임의 마스크와 교집합을 계산하여 worst hit 보고; 0이 아니면 전체 글자 크기를 줄여 다시 검증, 0이 될 때까지 반복.

2. 바로 재사용 가능한 구현

字幕\build\avoid_side2.py (권장, 전체 버전: pass1 bbox 측정 → layout → verify → 렌더링 → 키프레임):

$py='C:\Users\35530\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe'
& $py '字幕\build\avoid_side2.py'

이 스크립트는 고정된 구버전(0001-4956)의 15.4초 구간을 처리합니다. 다른 구간/다른 영상으로 변경하려면 다음 상수를 수정하세요:

  • SRC / OUT / T0,T1
  • CUES (각 문장의 시작/끝, 구간 기준)
  • EL 내의 글자 크기/위치 후보 (L/R 열, y, fs)
  • LEFT_MARGIN/오른쪽 사용 가능 너비 로직 산출물: NEON_avoid_15s.ass + 렌더링 영상 + 키프레임 표. 구버전 (합성 데모): avoid_demo.py, avoid_debug.py, avoid_layout.py (점유 핫스팟 이미지 分析_占位与选位.jpg).

3. 본 프로젝트 실측 데이터 (구버전 영상 0:51–1:06.4)

  • 고정 하단 레이아웃: 6/6 문장이 인물과 겹침, 인물 영역 가림률 7%–12%.
  • 측면 열 회피: 0/6 문장이 인물과 겹침, 단일 문장 가림률 ≤0.2%; 프레임별 재검증 0 픽셀.
  • 각 문장의 사용 가능한 측면 열 (구버전, 전체 2560 너비): 왼쪽 열 약 0–500px, 오른쪽 열 약 2100–2560px, 문장마다 다르므로 반드시 실시간 계산해야 함.
  • 인물이 화면 중앙에 있고 날개를 펼칠 때 너비 점유율 약 48%–82%; 근접/클로즈업 샷에서는 거의 화면을 가득 채움 → 클로즈업 프레임에서는 문자를 상하단 모서리에만 배치 가능.

4. 레이아웃 전략 (인물을 가리지 않으면서도 보기 좋게)

  • 주 가사는 왼쪽 열, 보조 단어는 오른쪽 열에 배치하여 "좌우 대창" 느낌을 연출;
  • 상단에는 긴 문장(MAKING EVERYBODY GO 등)을 배치하고, 하단에는 작은 글자/등간격 정보만 남김;
  • 각 문장에는 하나의 "시각적 주인공"만 두고 나머지 단어는 작게 처리하여 전체 문장이 커서 측면 열에 들어가지 않도록 방지;
  • 문자 상자 추정은 보수적으로: ASCII 너비 ≈ fs×0.66, CJK ≈ fs×1.06; 10–14px 패딩 유지.

5. 검증 체크리스트

  • 각 문장 창의 bbox가 날개 끝/머리 위를 누락하지 않았는지 확인 (分析_占用区域.jpg 참조)
  • 프레임별 재검증 worst hit = 0 (스크립트가 출력함)
  • 3–4프레임을 샘플링하여: 문자가 가장자리에 너무 가깝거나 잘리는지, 새끼손가락/날개를 가리는지 확인
  • 근접/클로즈업 프레임은 별도로 샘플 확인
  • "가급적 가리지 않음" 모드를 허용할 경우, 날개가 가려진 프레임을 기록 (허용 가능)

6. 알려진 문제점

  • 배경의 LOL 조명/광점이 프레임 차분에서 오탐될 수 있음 → 임계값 38 + 최대 연결 성분으로 일반적으로 제거 가능; 그래도 안 되면 공간 사전 정보 추가 (인물은 중앙에 위치).
  • 인물의 그림자가 인물로 잘못 탐지될 수 있음 (bbox가 커짐) → 회피에는 안전함 (그림자도 피하게 되지만 측면 열이 더 좁아짐).
  • 필터 MaxFilter는 640×270에서 전체 해상도 기준 약 8px 외곽 확장에 해당하므로, 재검증 시 추가 패딩을 넣지 마십시오.
  • 새 영상/새 카메라 위치로 변경할 경우, 모든 bounds를 다시 계산해야 하며 기존 영상 숫자를 재사용할 수 없습니다.

Individual skills in this repo

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

muyunxue/dance-mmd-subtitle-kit

Hard rules, templates, ffmpeg commands and failure diagnosis for authoring ASS/SSA subtitles and burning them with libass on this machine. Load this before writing any ASS file, when a burn "succeeds" but no text appears, when text is misplaced/too big, when \p1 drawings are offset, or when you need the transparent-overlay export recipe. Contains the exact pitfalls hit in this project (timestamp format, style colour trailing ampersand, fontsdir, drawing anchor, chained \t, Permanent Marker sizing).

muyunxue/dance-mmd-subtitle-kit

End-to-end recipe for making subtitles for the MMD dance videos in this workspace (字幕/ project) — probe the source, pick a segment, map LRC cues, choose a style, build ASS, burn, verify, and deliver. Load this when starting or resuming any subtitle task (静态稿/5s小样/30s小样/全片/透明叠加层), when a render "succeeded" but the video has no text, or when you need this project's paths, font list, cue sheet and acceptance criteria.

muyunxue/dance-mmd-subtitle-kit

Design and deliver subtitle style mockups and animated comparison samples for the MMD/K-pop dance videos — S1–S6 style catalogue (Y2K chrome, minimal kinetic, glitch, mix&match editorial, graphic emphasis, hand-marker), PIL/numpy effect recipes, font list, contact-sheet/comparison video conventions, and the parallel-subagent workflow used for S4 vs S6. Load this when asked 出几个静态帧方案/参考女团PV字幕/做个小样/对比几个风格, or when choosing a visual direction before building a full-length subtitle track.

muyunxue/dance-mmd-subtitle-kit

Subject-aware colour grading for the MMD dance videos in this workspace — make the dancer stand out (background dim/cool/desat, subject lift/warm/sharpen/bloom) using either a soft stage-light ellipse or a hard character matte, with ffmpeg recipes, measured parameter sets and known failure modes (cast-shadow matte contamination, banding, truncated sources). Load this when asked to 调色/突出人物/压背景/统一色调, or when a graded clip shows weird bright blobs around the dancer.

관련 스킬