Seagey/edit-reel

릴 편집하기

모든 작업은 사용자의 Mac에서 실행됩니다. 유료 서비스는 없습니다. 실제 작업을 수행하는 스크립트는 리포지토리 루트의 scripts/edit.sh이며, 이 파일 옆에 있는 scripts/edit_reel.py를 호출합니다.

사용자는 기술에 익숙하지 않습니다. 짧고 간결한 평이한 한국어로 말하세요. 행동하기 전에 무엇을 할 것인지 말하고, 그 후에 어떤 일이 일어났는지 설명하세요.

목차

• 빠른 경로
• 동영상 가져오기
• 한 번 편집이 수행하는 작업
• 사용자가 변경을 요청할 수 있는 설정
• 전달하기 전 확인 사항
• 결과를 사용자에게 설명하기
• 문제 발생 시 대처
• 엄격한 규칙

빠른 경로

1. 설정이 완료되었는지 확인: scripts/setup.sh --check. NOT READY라고 표시되면 CLAUDE.md(온보딩)를 따르고, 설치를 임의로 시도하지 마세요.
2. 동영상 가져오기(아래 참조) 후 다음 실행:
   • 특정 파일: scripts/edit.sh "<동영상 경로>"
   • Inbox 폴더의 최신 N개: scripts/edit.sh --latest 3
3. 아래 확인 사항을 실행하고, 사진을 보고, 자막을 읽은 후 보고하세요.

3060초 클립은 Apple 칩 Mac에서 약 12분이 소요되며, 구형 Mac에서는 더 오래 걸립니다.

동영상 가져오기

다음 순서로 시도하며, 가장 먼저 성공하는 방법으로 중단합니다.

1. 사용자가 이름을 지정하거나 드래그한 파일. 원래 위치에서 사용하세요. 원본 파일을 절대 이동하거나 삭제하지 마세요.
2. Inbox 폴더. 사용자가 AirDrop으로 보내거나 리포지토리 폴더의 Inbox/에 넣은 파일.
3. iCloud 사진. iCloud가 설정된 경우에만(docs/ICLOUD.md). Apple ID 이메일은 config.json의 icloud_apple_id에 있습니다. scripts/icloud-fetch.sh <apple id> 30을 실행하세요.
   • 성공 시 ICLOUD_FETCH_OK를 출력합니다. 최신 동영상이 Inbox/에 다운로드됩니다.
   • 로그인이 만료된 경우(약 2개월 지속) 또는 설정되지 않은 경우 ICLOUD_FETCH_FAILED를 출력합니다. 직접 해결하지 말고 사용자에게 알리고 docs/ICLOUD.md의 "다시 로그인" 단계를 안내하세요. 사용자는 채팅이 아닌 자신의 터미널에서 비밀번호와 6자리 코드를 입력합니다.
   • "최신"은 가장 최근에 촬영된 것을 의미합니다. 방금 촬영한 동영상은 iCloud에 도달하는 데 몇 분이 걸릴 수 있으므로, 찾는 동영상이 없으면 알리고 1분 후 다시 시도하겠다고 제안하세요.
   • 편집 전에 최신 동영상의 길이를 나열하고(ffprobe로 길이 확인), 의도한 동영상을 확인하세요.
4. 모두 실패. 대체 방법 제안: AirDrop으로 Mac에 동영상을 보내거나 Inbox 폴더로 드래그하세요.

한 번 편집이 수행하는 작업

순서:

1. 음성 기반 컷. 오디오 음량을 기준으로 음성이 실제로 시작하고 끝나는 지점을 찾습니다(자막 시간 기반이 아님). 시작과 끝의 무음을 제거하고 긴 일시정지를 단축합니다. 컷은 가장 조용한 지점에 배치되며 각 이음새에는 15ms 페이드가 적용되어 단어가 잘리지 않습니다. 문장은 완전히 유지됩니다. 무음이 아닌 내용은 제거되지 않습니다.
2. 미러 확인. 전면 카메라 클립은 자주 미러링됩니다. 프레임 내 텍스트(간판, 화면, 옷)를 OCR로 정상과 반전 상태로 읽고, 실제 단어가 반전 상태에서 올바르게 읽히는 경우에만 동영상을 반전합니다. 눈으로 판단하지 않습니다. 읽을 수 있는 텍스트가 없으면 동영상을 그대로 두고 보고서에 그렇게 명시합니다.
3. 9:16 크롭 및 1080x1920으로 스케일링(가로 클립은 중앙으로 크롭).
4. 색보정. 몇 프레임을 측정하여 작은 노출, 대비, 채도 보정을 적용하며, 과도하게 보정되지 않도록 제한하고 전후 비교 시트를 제공합니다. HDR iPhone 클립은 먼저 표준 색상으로 매핑됩니다.
5. 스튜디오 음질. 잡음 제거, 음성 EQ, 디에서, 컴프레서, 리미터, 그리고 -14 LUFS 라우드니스 조정. 이는 측정을 통해 튜닝되었습니다. 귀로 판단: 거칠거나, 얇거나, 과도하게 처리된 것 같으면 audio.strength를 light로 낮추세요.
6. 자막. 정리된 오디오를 텍스트로 변환한 후 Pillow로 자막을 그립니다. 휴대폰 안전 영역 내(1080x1920 프레임 기준 x 90960, y 2501520)에 배치되어 버튼이나 앱 텍스트에 가려지지 않습니다. 활성 단어는 색상이 변경되고 테두리는 어둡게 유지됩니다. 단어 뒤에 색상 상자를 넣지 않습니다(얼굴 위에서 부드럽게 보임).
7. 출력. Edited/<이름>-edited.mp4 및 Edited/checks/<이름>/ 폴더 내: contact-sheet.jpg, colour-before-after.jpg, caption-frame.png, captions-words.txt, report.json.

사용자가 변경을 요청할 수 있는 설정

모든 설정은 리포지토리 루트의 config.json에 있습니다(config.default.json에서 생성되며, 원본은 편집하지 않음). 사용자는 파일을 직접 건드리지 않습니다. 평이한 말로 요청하면 변경하고, 다시 편집을 실행하여 보여줍니다. 전체 단어-설정 매핑: docs/STYLE.md.

예시:

• "자막 노란색으로"는 captions.highlight_color(활성 단어) 또는 captions.color(모든 단어)를 설정합니다. 불명확하면 어느 것인지 물어보세요.
• "자막 더 크게"는 captions.size를 약 12만큼 높입니다(기본 78). 결과가 안전 영역 내에 있도록 하세요. 스크립트가 inside_safe_zone을 보고합니다.
• "자막 위로 올려"는 captions.position을 middle 또는 upper로 설정합니다.
• "한 번에 한 단어씩"은 captions.style을 word로 설정합니다. "줄"로 다시 설정하려면 line으로 설정합니다.
• "자막 없음"은 captions.enabled를 false로 설정합니다.
• "색약하게"는 grade.strength를 0.2 낮춥니다. "색보정 안함"은 grade.enabled를 false로 설정합니다.
• "더 타이트하게 편집"은 cuts.tightness를 tight로 설정합니다. "여유 더 두기": gentle.
• "소리가 너무 인공적이야": audio.strength를 light로 설정합니다.
• "얼굴 더 가까이": framing.zoom 1.15(최대 합리적 값 1.4).
• 자막에 이름이 잘못 표시됨: vocabulary에 추가(리스너가 올바르게 인식하도록 도움)하고, 여전히 잘못 표시되면 replacements에 {"heard": "올바른 철자"} 형식으로 추가합니다.

변경 후 동일한 동영상에 대해 편집을 다시 실행하고 새 결과를 보여주세요. Edited/ 파일을 사용하며, 다시 실행하면 동일한 이름의 이전 편집 결과를 덮어씁니다.

전달하기 전 확인 사항

스크립트는 요약을 출력하고 report.json을 생성합니다. 그래도 직접 확인해야 합니다.

1. 숫자 확인. loudness_ok, start_ok, end_ok가 모두 true여야 합니다. 시작 무음은 0.45초 이하, 끝 무음은 0.75초 이하여야 합니다. 그렇지 않으면 알리고 --tightness tight로 다시 실행하세요.
2. 사진 확인 (Read 도구 사용): contact-sheet.jpg(얼굴이 프레임 안에 있는지, 사진이 자연스러운지, 자막이 화면 안에 있는지), colour-before-after.jpg(왼쪽 원본, 오른쪽 보정: 피부가 자연스럽고 오렌지색이나 회색이 아닌지, 흰색이 날아가지 않았는지, 검은색이 뭉개지지 않았는지), caption-frame.png(모든 단어를 크게 읽고, 배경과 대비되어 각 단어를 읽을 수 있는지 확인).
3. 자막 읽기. captions-words.txt를 여세요. 음성 인식이 이름이나 지역어(예: 브랜드명)를 잘못 인식할 수 있습니다. vocabulary와 replacements로 수정한 후 다시 실행하세요. 보고서의 caption_vs_sound_match 확인: 0.9 미만이면 문제가 있는 것이므로 조사하세요.
4. 미러 확인. report.json의 mirror 필드를 확인하세요. decision이 unknown이고 프레임에 텍스트(간판, 화면)가 있다면 프레임을 보고 텍스트가 올바르게 읽히는지 확인하세요. 거꾸로 보이면 framing.mirror_fix를 always로 설정하고 다시 실행하세요.
5. 무음 확인. 스크립트는 최종 믹스에 대해 silencedetect를 실행합니다. 이 용도로 자막 시간을 신뢰하지 마세요.

소리를 들을 수 없습니다. 솔직하게 말하세요: 소리는 측정되고 튜닝되었지만, 최종 판단은 사용자의 귀에 달려 있습니다.

결과를 사용자에게 설명하기

짧고 평이하게, 다음과 같은 형식으로:

• 파일 위치와 여는 방법(Finder, 릴 편집기 폴더 안의 Edited 폴더).
• 무엇이 잘렸는지("시작 부분 1.1초 무음 제거, 긴 일시정지 두 개 단축, 36초에서 33초로").
• 사진이 반전되었는지 여부와 이유.
• 현재 음량 측정값("약 -14, 인스타그램과 틱톡의 일반적인 수준").
• 자막: 글꼴, 색상, 변경한 단어.
• 수정하지 못한 사항과 변경을 위해 사용자가 말할 수 있는 내용.

그런 다음 무엇을 변경할지 물어보고, 위 설정 목록에서 한두 가지 아이디어를 제안하세요.

문제 발생 시 대처

• "음성이 감지되지 않음": 클립이 무음이거나 음악만 있는 경우입니다. 사용자에게 알리세요.
• 자막 위치 이상 또는 잘림: 보고서에서 inside_safe_zone을 확인하고 size를 낮추세요.
• 글꼴을 찾을 수 없음: 스크립트가 Arial Black으로 대체하고 메모를 출력합니다. 내장 글꼴 중 하나를 제안하거나(docs/STYLE.md), fonts.google.com에서 무료 글꼴(.ttf)을 다운로드하여 ~/.reel-editor/fonts/에 넣고 captions.font를 .ttf 없는 파일 이름으로 설정하세요.
• 설정 도구 누락: scripts/setup.sh를 실행하세요. Homebrew가 없으면 CLAUDE.md를 따르세요.
• 편집 시간이 매우 오래 걸림: 3분 이상의 4K 클립은 무겁습니다. 알리고 실행을 계속하세요.

엄격한 규칙

• 사용자의 원본 동영상을 절대 삭제하거나 변경하지 마세요.
• 채팅에서 비밀번호나 6자리 코드를 요청하거나 받지 마세요.
• 유료 서비스를 사용하지 말고, 사용자의 동영상을 어디에도 업로드하지 마세요. 모든 작업은 이 Mac에서 이루어지며, iCloud 다운로드만 예외입니다.
• 사용자가 요청하지 않는 한 스크롤 프롬프트나 "팔로우 미" 오버레이를 추가하지 마세요.
• 사용자가 말하지 않은 내용을 추가하지 마세요: 자막은 말한 내용만 표시합니다.