---
name: "lecture-recording-captions"
description: "밤밤의 강연·라이브·기수 세션 녹화본(줌 클라우드·디스코드·맥 화면기록)을 자막판 영상으로 만들고 배포할 때 읽을 것. 어절 하이라이트 자막, 슬라이드별 타이틀 카드, 핵심 영역 확대, 주아체 일러스트, 얼굴 PIP, 질의응답 웹캠 레이아웃, 엔드카드에서 유튜브 업로드·디스코드 공지·7일 만료까지 한 파이프라인. \"녹화본 자막 달아줘\", \"강의 영상 편집해서 올려줘\", \"녹화본 디스코드에 업데이트해줘\", \"라이브 자막판 파이프라인\" 요청을 처리한다."
---

> **이 스킬이 시스템에 하는 일 (설치 전 확인)**
>
> - 로컬에서 `ffmpeg`과 음성 인식 모델을 돌립니다. CPU·디스크를 많이 씁니다.
> - 녹화 파일을 읽고 자막·영상 파일을 새로 만듭니다. **원본은 수정하지 않습니다.**
> - 유튜브 업로드 단계는 별도 인증이 필요하고, 기본값은 업로드하지 않는 것입니다.

# 강의 녹화본 자막판

결과물: 1920x1080 30fps mp4 하나. 1부(슬라이드 발표) + 2부(질의응답 웹캠) + 엔드카드. 겟백 팔레트(#0d0d0d / 라임 #D4F000 / 퍼플 #7B2FFF), 자막 나눔고딕 ExtraBold, 타이틀·일러스트 배달의민족 주아체(`assets/fonts/BMJUA_ttf.ttf`, 상업 사용 가능, 엔드카드에 출처 표기).

무거운 단계(전사·교정·렌더)는 전부 맥미니에서 돌린다(`macmini-offload` 스킬). 맥북에서는 크롭·축소 전처리만 videotoolbox로 한다.

## 먼저 정할 것 — 판매용인가 기수 공유용인가

두 경로가 갈린다. **소스 화면이 슬라이드로 고정되어 있는지** 먼저 본다(0단계 콘택트시트).

| | 판매용 풀 파이프라인 | 기수 공유용 경량 |
|---|---|---|
| 소스 조건 | 발표 내내 슬라이드 고정 | 화면이 슬라이드·브라우저·웹캠으로 계속 바뀜 |
| 포함 | 자막 + 타이틀카드 + 확대 + 일러스트 + PIP | **자막 + 엔드카드만** |
| 걸리는 시간 | 반나절 이상 | 2~3시간 |

기수 세션 녹화본은 보통 **줌 창 전체를 녹화**해서 맥 메뉴바·독·디스코드 사이드바가 다 찍힌다. 이런 소스에 슬라이드 구간표를 만들면 타이틀카드가 엉뚱한 화면에 뜨고 확대가 엉뚱한 데를 잡는다. **`runs`를 통짜 하나(`[[0, 끝, 1]]`)로 두고 `titles`·`zoom`·`illustrations`를 빈 객체로 두면** 자막과 엔드카드만 적용된다. 이 조합은 2026-09-07 7기 OT에서 실측됐다.

손실 없이 빠지는 것과 아닌 것을 구분한다. 자막은 복습 가치가 크므로 반드시 넣고, 타이틀카드·확대는 화면이 고정된 소스에서만 값을 한다.

## 절차

### 0. 소스 파악과 싱크
1. 영상 소스와 음성 소스를 분리해 적는다. 맥 화면기록은 오디오가 없다.
2. 두 파일을 10분 간격으로 샘플링해 콘택트시트로 본다. 슬라이드가 언제 끝나는지, 화면공유가 언제 꺼지는지, 웹캠 타일이 어디 있는지, 참가자 이름·채팅이 어디 찍히는지 표시한다.
3. 오프셋은 "슬라이드 제목을 읽는 발화"와 그 슬라이드의 등장 시각으로 두 군데 이상 맞춰 확정한다. 이후 모든 시각은 **음성(전사) 타임라인**으로 통일한다.
4. 실제 발화 끝은 볼륨 측정으로 확인한다. 전사가 "하하하"만 찍혀도 말이 이어지고 있을 수 있다.

### 1. 전처리 (맥북, videotoolbox)
필요 구간만 잘라 뽑는다. 원본은 보내지 않는다.
- `base.mp4` 슬라이드 크롭 → 1920x1080 30fps, `-c:v h264_videotoolbox -b:v 3500k`
- `face1.mp4` 발표 중 얼굴 타일 크롭(원본 해상도 유지)
- `bam2.mp4` 질의응답 웹캠 타일 크롭 → 1440x810
- `audio.m4a` 음성 `-vn -c:a copy`
- 마지막 슬라이드 PNG를 1920x1080으로 `s18.png`처럼 준비(공유 해제 구간 덮기용)
`ssh localhost`로 nohup 실행하고, 중단할 땐 `pkill -f '[p]rep.sh'` 형식으로.

### 2. 전사 (맥미니)

**줌 클라우드 녹화본이면 전사·교정 단계를 통째로 건너뛸 수 있다.** 줌이 `audio_transcript.transcript`(WEBVTT)를 같이 주고, 한국어 품질이 whisper 못지않다(2026-09-07 실측: 830큐, 밤밤 발화 정확). 절차는 `references/zoom-cloud-source.md` 참고.

1. `scripts/vtt_to_segs.py <transcript> segs_final.json` — WEBVTT → 세그먼트(긴 발화는 문장 단위로 분할)
2. 고유명사 교정 — 줌 전사도 브랜드명은 틀린다("갯배/겟배" → "겟백", "칠 기" → "7기"). 정규식 치환으로 한 번에 고친다.
3. `scripts/add_words.py segs_final.json` — **필수.** `make_video.py`는 어절 하이라이트를 위해 `s['words']`를 요구하는데 줌 전사는 문장 단위라 없다. 글자 수 비례로 어절 시간을 배분한다. 이걸 건너뛰면 `KeyError: 'words'`로 죽는다.

줌 녹화본이 없거나 품질이 나쁘면 기존 경로로 간다 — `scripts/transcribe_chunks.sh <audio> <outdir> "<고유명사 목록>"` → 10분 청크, 단어 타임스탬프. 그다음 `scripts/collect_tr.py <outdir>/tr <work>` → `segs_new.json` + 교정용 `chunks2/`. 10분당 글자 수가 고르지 않으면 환각이니 그 청크만 다시 돌린다.

### 3. 교정 (맥미니)
`assets/fix_prompt.txt`를 작업 폴더에 복사하고 고유명사 사전을 이번 강연에 맞게 고친 뒤 `scripts/fix_run.sh <work>`. 끝나면 `scripts/apply_fix.py <work>` → `segs_final.json`.

### 4. 슬라이드 구간표
`scripts/slide_runs.py base.mp4 <slides_dir> runs.json`으로 초안을 만들고, **반드시 프레임을 뽑아 눈으로 대조**해 손으로 고친다. 어두운 슬라이드끼리, 스크롤 중인 프레임은 자주 틀린다. 슬라이드를 앞뒤로 넘긴 구간은 정착한 시각을 시작으로 잡는다.

### 5. 일러스트
개념 5~6개만. `scripts/illust_card.py --out 두갈래.png --title "..." --line "1. ..." --line "2. ..." --warn "..." --note "..."`. 만든 뒤 콘택트시트로 글리프 누락(①·→)과 금지 표현을 확인한다.

### 6. 설정과 조립
`references/example-config.json`을 복사해 채운다. 핵심 필드:
- `phase1.runs` [[시작,끝,슬라이드번호]], `titles` {번호: [키커, 제목]}, `zoom` {번호: [지연, 길이, 배율, fx, fy]} (fx·fy는 팬 범위 내 비율, 0=왼쪽·위 끝), `illustrations` {번호: [지연, 길이, 파일]}, `face.valid_from`, `freeze.from`
- `phase2.cam_until`(웹캠 소스가 끝나는 시각), `tail`(그 뒤를 잇는 다른 소스), `cover.until`(공유 해제 중 참가자 정보가 찍히는 구간을 마지막 슬라이드로 덮음), `card_at`, `tag`
- `ffmpeg`는 맥미니에서 `/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg`
`python3 scripts/make_video.py config.json` → `sub1/2/3.ass`, `render.sh`. 먼저 `render.sh`의 1부 명령을 `-t 60`으로 줄여 시험 렌더하고 프레임을 본 뒤 전체를 `run.sh start`로 돌린다. 1부와 2부는 별도 명령이라 문제 있는 쪽만 다시 뽑으면 된다.

### 7. 검수 (건너뛰지 말 것)
최종본에서 다음 시각의 프레임을 뽑아 콘택트시트로 본다: 각 슬라이드 타이틀 카드 직후, 각 확대 구간 중간, 각 일러스트 표시 중, 1부→2부 경계 ±3초, 웹캠 등장 시점, 마지막 페이드, 엔드카드. 확인 항목:
- 참가자 이름·아바타·채팅이 한 프레임도 없는가
- 확대가 콘텐츠를 자르지 않는가
- 자막이 슬라이드 하단 글과 겹쳐도 읽히는가(반투명 띠)
- 얼굴 PIP가 검은 화면이 아닌가(`valid_from` 이전 구간)
- 총 길이가 의도한 값인가(`-loop` 입력 때문에 무한 렌더가 된 적 있음)

### 8. 전달
`scp`로 artifacts에 가져오고(1.5GB ≈ 5분), 콘택트시트 한 장과 함께 구성·길이·바꾼 점을 보고한다. 자동 전사라 오타가 남을 수 있음을 밝히고, 시각을 알려주면 그 줄만 고쳐 다시 뽑을 수 있다고 말한다. config와 `segs_final.json`은 프로젝트 폴더에 보관한다.

### 9. 배포 — 유튜브 + 디스코드 (기수 세션일 때)

기수 녹화본은 **디스코드에 파일을 올리지 않는다**(8MB 제한). 유튜브 unlisted로 올리고 링크만 건다.

1. **유튜브 업로드** — 맥미니 `~/Projects/getback/pipeline/youtube_uploader.py`의 `upload_video(path, title, desc, tags)`. 기본값이 `unlisted`다. 인증은 통합 토큰 `~/.config/get100/google_token.json`(`scripts/google_auth.py`). 718MB ≈ 1분.
2. **디스코드 공지** — 포럼 `#겟백-세션-녹화본`(id `<DISCORD_ID>`)에 **밤냥이 봇 명의로** `POST /channels/{forum}/threads`. 양식과 기준은 `references/discord-recording-post.md`.
3. **7일 만료는 자동** — 봇의 `recording_expiry.py`가 1시간마다 포럼을 훑어 본문에 `🗓 시청 기한: ~MM/DD`를 붙이고, 기한이 지나면 유튜브 링크를 지운다. **봇이 쓴 글에만 적용된다** — 밤밤 계정으로 올리면 안 붙는다. 기한은 `EXPIRY_DAYS` 상수(2026-09-08부터 7일). 나중에 다시 열려면 본문에 링크를 다시 넣으면 된다.

## 판단 기준
- 말투·톤 지시는 `memory/USER.md`의 밤밤 금지 표현을 일러스트 문구에도 그대로 적용한다("이 아니라", "자리" 등).
- 확대는 슬라이드당 한 번, 8~20초 뒤 시작, 12초 유지. 일러스트는 확대와 시간이 겹치지 않게.
- 2부에서 상대(호스트)가 말할 때도 밤밤 웹캠을 유지한다. 화자 분리는 하지 않는다.

`references/pitfalls.md`에 실측에서 걸린 함정을 정리해 두었다. 막히면 먼저 그 파일을 본다.