From 6f90efd2bcec46bf97bd77cfe06273930878ed9c Mon Sep 17 00:00:00 2001 From: "hehihoho3@gmail.com" Date: Tue, 4 Aug 2026 12:38:36 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=BB=B7=EB=B3=84=20=EB=8C=93=EA=B8=80?= =?UTF-8?q?=20=EC=B6=94=EC=B2=9C=20=EA=B8=B0=EB=8A=A5=EC=9D=84=20ARCHITECT?= =?UTF-8?q?URE/SETUP=EC=97=90=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit recommend.py 모듈, 카드 배치가 자동 탭(card_cuts→_cards_by_cut)과 나머지 탭(_load_comment_cards 전체 균등)으로 갈린 이유, 그리고 서버가 카드 시간을 미리 확정하지 않는 이유(무음 제거 시 자막만 재매핑되고 카드가 혼자 어긋나는 것을 방지)를 문서에 남겨 나중에 이 설계를 실수로 되돌리는 것을 막는다. SETUP.md 문제 해결표에도 추천 실패 폴백 증상 두 건을 추가. Co-Authored-By: Claude Opus 5 (1M context) --- ARCHITECTURE.md | 13 +++++++++++++ SETUP.md | 2 ++ 2 files changed, 15 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index d81f564..6ded5f3 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -37,6 +37,7 @@ capcut2/ ├─ silence.py ffmpeg silencedetect → 발화 구간 ├─ transcribe.py faster-whisper(medium/int8/cpu) 단어 타임스탬프 ├─ correct.py Gemini 자막 글자 교정(시간 불변) — gemini-2.5-flash + ├─ recommend.py 컷별 댓글 추천(자동 탭) — 타임스탬프 우선 + Gemini 텍스트 추천 ├─ highlight.py 자막 청킹(cut_plan) 유틸 ├─ scene.py ffmpeg scene 필터 장면전환 감지·분할 ├─ media.py 프레임 PNG 생성, 흰밴드 감지, 오디오 추출 @@ -129,6 +130,8 @@ LLM이 만든 편집안 JSON을 **그대로** 사용. 무음컷·ASR **기본 JSON bottom 폴백. effect/제목/채널은 JSON 유지. ⚠ "remove_silence 후에 돌리면 remap 불필요"는 틀림 — 파일은 압축 안 되므로 cut_plan 매핑 필수. 6. **scene / 댓글카드 / draft**: 4-A와 동일(좌표도 공통 — §9). + 자동 탭에서 넘어온 경우 `process_paste(card_cuts=[...])`로 카드별 소속 컷을 + 받는다(§6 참고) — 붙여넣기 탭 직접 사용 시엔 생략(기존 전체 균등 배치). #### 붙여넣기 JSON 스키마 (LLM에게 시킬 형식) @@ -223,6 +226,16 @@ title_top 서브제목 / title_main 메인제목 / channel 출처 / effect 효 - `_load_comment_cards(folder, dur, interval=3.0)`: - 모든 파일명이 숫자로 시작 → 숫자순(1,2,10). 아니면 → **파일 생성시각(저장 순서)**. - png/jpg/jpeg/webp. 카드당 3초, 영상 길이 초과분은 생략. +- **배치 방식이 두 갈래**(정렬 자체는 `_card_paths()`로 공통): 자동 탭은 검토 화면에서 + 카드별 소속 컷 인덱스(`card_cuts`)를 보내고, `_cards_by_cut(paths, card_cuts, placements, dur)`가 + **그 컷 구간 안에서** 균등 배치한다(한 컷이 덜 차도 다음 컷 카드가 앞으로 밀리지 않음). + 파일/유튜브 탭·붙여넣기 탭 직접 사용은 컷 소속을 몰라 기존 `_load_comment_cards` 전체 균등 + 배치 그대로 쓴다. + - ⚠ **카드 시간은 서버가 미리 확정하지 않는다.** `/auto/build`는 "몇 번 컷 소속"만 넘기고, + 파이프라인이 컷 누적 위치(`placements`)로 시간을 계산한다. 무음 제거를 켜면 타임라인이 + 압축되는데(`timeline_dur = sum(keep)`), 서버가 시간을 미리 박아두면 자막만 재매핑되고 + 카드는 혼자 어긋나기 때문이다 — 카드도 자막과 **같은 `_remap_caps()`**로 재매핑된다 + (튜플 모양이 `(start, end, path)`로 같아서 가능). 이 순서를 뒤집지 말 것. - 렌더: comment 트랙에 **scale 0.89 / X 0**, 세로는 **윗변이 영상 바로 아래**에 오도록 카드마다 계산(§9). - 출처: 사용자가 h-lab(https://h-lab.tolag.shop/comment-cards)에서 실제 유튜브 댓글을 카드 PNG로 저장해 폴더에 넣음. (향후: h-lab API 연동해 완전 자동화 아이디어 있음) diff --git a/SETUP.md b/SETUP.md index eea49b3..7e947f7 100644 --- a/SETUP.md +++ b/SETUP.md @@ -280,6 +280,8 @@ yt-dlp --version | 드래프트 열면 영상이 흰띠·댓글 위로 삐짐 | CapCut 편집 중 render_index 꼬임 | 최신 `draft.py`는 오버레이/제목 트랙 자동 잠금으로 예방 | | **클립을 옮긴 뒤 확대하면 그 클립만 템플릿 밖으로 삐짐** | CapCut이 옮긴 클립에 렌더순서를 새로(맨 위로) 매김 — 잠금으로 못 막음 | **캡컷에서 그 프로젝트를 닫고** → 웹 UI 하단 **"🩹 레이어 수리"** → 드래프트 선택 → 실행 → 캡컷에서 다시 열기 | | **영상 중간에 초록 화면이 몇 초 나옴** | yt-dlp가 키프레임 아닌 위치에서 잘라 참조 프레임이 없음 | 최신 `youtube.py`가 컷마다 자동 검증→재다운로드→정밀 재컷. 로그에 `🩹` 표시. 예전에 받은 영상은 다시 만들어야 함 | +| 댓글이 엉뚱한 장면에 뜬다 | 컷별 추천이 실패해 기존 전체 균등 배치로 폴백 | 검토 화면 상단 경고 확인. Gemini 한도 초과면 잠시 뒤 재시도 | +| 컷 섹션이 안 보이고 ⭐ 하나만 뜬다 | 추천 실패 폴백 | 위와 동일. `프롬프트/댓글_추천.md`를 고쳤다면 `{cuts}` `{comments}` `{k}` 가 남아 있는지 확인 | | 콘솔에 한글 깨짐 | Windows cp949 | 표시만 깨짐. 로직·결과와 무관 | ---