tach-nguoi

Hiệu ứng tách người (person cut-out effects)

사용자가 자신의 비디오에서 인물 주변에 효과를 적용할 수 있도록 도와줍니다. 많은 사용자가 베트남어 사용자입니다: 사용자가 베트남어로 작성하면 평범하고 구어체 베트남어로 답변하세요.

스크립트는 이 스킬의 scripts/ 폴더에 있습니다. 사용자 자신의 폴더에서 작업하는 동안 전체 경로(또는 스킬 폴더에서)로 실행하세요: 설정 파일과 모든 출력물은 스킬 폴더가 아닌 사용자 폴더에 저장됩니다.

요구 사항 및 제한 사항

설치 전에, 그리고 요청에 누락된 항목이 있을 때마다 사용자에게 알리세요. python scripts/tn.py check 명령어로 설치 상태를 확인할 수 있습니다.

• 필요: 유료 Claude 요금제(Claude Code 포함); ffmpeg; Python 3.10+ 및 numpy, opencv-python, pillow. 컷아웃에는 PyTorch(약 2-3 GB, 자체 Python 환경에 설치하는 것이 좋음)와 RVM 모델이 필요하며, PyTorch는 첫 번째 컷아웃 시 GitHub에서 한 번 다운로드합니다(약 15-100 MB).
• GPU: NVIDIA 카드가 강력히 권장됩니다. NVIDIA GPU 사용 시 컷아웃 속도는 약 35-50 fps입니다. CPU에서는 약 20-50배 느립니다(30초 클립이 10-20분 소요). 모든 효과는 GPU 유무와 관계없이 작동합니다.
• 속도 (테스트: RTX 4080): 스틸 이미지는 몇 초; 1080p 풀 렌더링은 텍스트 뒤 배치 및 클론 효과에서 18-27 fps, 프리즈 효과에서 9-19 fps(일회성 컷아웃 후 약 1-2분 소요).
• 테스트 OS: Windows 10 (모든 명령어). macOS: 아직 테스트되지 않음 (NVIDIA GPU 없으므로 컷아웃이 느림).
• 제한 사항: 한두 명의 인물과 머리 위/옆에 여유 공간이 있을 때 가장 잘 작동합니다. 타이트한 수직 클로즈업은 텍스트가 작아집니다. 빠른 움직임, 복잡한 배경의 머리카락, 투명한 물체는 가장자리가 거칠어질 수 있습니다. 클론 효과는 삼각대 또는 거의 고정된 카메라가 필요합니다. 두 테이크 클론은 동일한 위치에서 촬영된 두 테이크가 필요합니다.
• PyTorch 없이: PyTorch 없이는 어떤 효과도 실행할 수 없습니다 (모든 효과가 컷아웃을 필요로 함). 이 사실을 알리고 설치를 제안하세요 (먼저 물어보세요).
• 프라이버시: 모든 작업은 사용자 컴퓨터에서 실행됩니다. RVM 모델만 한 번 다운로드됩니다.

PyTorch 설치 (먼저 물어보고, 약 2-3 GB라고 알리세요)

다른 Python 도구에 영향을 주지 않도록 별도의 환경에서 설치하세요:

python -m venv tach-nguoi-env
tach-nguoi-env/Scripts/python -m pip install numpy opencv-python pillow      (macOS/Linux: tach-nguoi-env/bin/python)
tach-nguoi-env/Scripts/python -m pip install torch --index-url https://download.pytorch.org/whl/cu126   (NVIDIA GPU)
tach-nguoi-env/Scripts/python -m pip install torch                                                     (NVIDIA GPU 없음)

그런 다음 해당 Python으로 모든 tn.py 명령어를 실행하세요 (tach-nguoi-env/Scripts/python scripts/tn.py ...).

규칙 (항상)

1. 사용자의 원본 클립을 절대 변경하지 마세요. 원본을 읽기만 하고, 모든 결과물은 계획 파일 옆(또는 사용자가 지정한 위치)에 새 파일로 저장하세요. 어떤 것도 덮어쓰지 않습니다: 새 이름을 선택하세요.
2. 설치 전에 항상 물어보세요 (무엇을, 왜, 크기는, 정확한 명령어를 알리세요).
3. 먼저 스틸 이미지, 그 다음 저해상도 미리보기, 마지막으로 풀 렌더링을 진행하세요. 전체 렌더링에 시간을 투자하기 전에 스틸 이미지를 보여주고 검사 결과를 알리세요.
4. 스크립트가 출력하는 검사 결과(숨겨진 %, 대비, 읽을 수 없음 참고; 스틸 이미지 옆 checks.json에도 저장됨)를 읽고 각각을 한 문장으로 사용자에게 설명하세요. 프리즈 효과는 어떤 프레임에서 멈췄는지 출력합니다: 스틸 이미지를 확인하세요.

설정 (첫 번째에만)

첫 번째 효과 전에 python scripts/tn.py settings를 실행하세요. 아직 저장되지 않음이라고 표시되면 아래 설정 질문을 사용자 언어(베트남어 문구 제공)로 하나씩 물어보세요. 완료되지 않음이라고 표시되면 나열된 질문만 물어보세요. 각 질문에는 옵션 외에 두 가지 추가 선택사항이 있습니다:

• "Mình chưa chắc, giải thích giúp mình": 선택사항이 무엇을 바꾸는지 한두 문장으로 설명한 후 다시 질문하세요.
• "Cho mình xem hết để so sánh": python scripts/tn.py sample <종류> <클립 경로> --out <프로젝트>/tach-nguoi-mau/<종류>.mp4 --text "<비디오에서 가져온 단어>"를 실행하고, 파일을 보여준 후 다시 질문하세요. 실행 시간은 5-40초입니다 (알리세요). 사용자 자신의 클립을 저해상도로 사용하며, 모든 옵션을 나란히 레이블과 함께 표시합니다.

각 답변은 즉시 저장하세요: python scripts/tn.py settings set <키>=<값>. 답변은 사용자 프로젝트 폴더의 tach-nguoi.settings.json에 저장되므로, 사용자가 다시 요청하지 않는 한 설정이 다시 실행되지 않습니다 ("làm lại phần cài đặt" → tn.py settings reset, 그런 다음 다시 질문). 계획 파일은 여전히 단일 비디오에 대해 모든 설정을 재정의할 수 있습니다.

#	질문 (베트남어)	옵션 → 값	키	샘플 종류
1	Video của bạn đăng ở đâu nhiều nhất?	TikTok → tiktok · YouTube Shorts → shorts · Reels → reels · YouTube video ngang → youtube	platform	platform
2	Bạn thích kiểu chữ nào?	Chữ cao, gọn → cao · Chữ đậm → dam · Đậm vừa → dam-vua	font	font
3	Chữ màu gì?	Trắng → #ffffff · Vàng → #ffd400 · Đen → #111111 · Màu của kênh (hỏi mã màu)	color	color
4	Người che chữ tới mức nào?	Ít, chữ lúc nào cũng dễ đọc → light · Vừa → medium · Nhiều, kiểu trend → bold	cover	cover
5	Chữ hiện ra kiểu nào?	Trồi lên → rise · Bật ra → pop · Hiện từng chữ cái → letters · Hiện luôn → none	anim	anim
6	Lúc giới thiệu nhân vật, viền quanh người kiểu nào?	Viền trắng → white · Viền phát sáng → glow · Không viền → none	outline	outline
7	Màu điểm nhấn (vạch cạnh tên, dòng chức danh, hộp chữ truyện tranh)?	Vàng → #ffd400 · Màu của kênh (hỏi mã màu)	accent	(outline 표시)
8	Có thêm tiếng động không?	Có → on · Không → off	sfx	sfx (각 소리 재생)

"chưa chắc"에 대한 설명:

1. 각 앱은 화면의 일부를 가립니다 (오른쪽 버튼, 아래 설명). 텍스트와 이름표를 가려진 부분을 피해 배치합니다.
2. 키가 크고 간결한 글꼴은 가장 트렌디한 비디오처럼 보입니다. 두꺼운 글꼴은 작은 전화기 화면에서 읽기 쉽습니다.
3. 대비를 자동으로 확인합니다: 배경에서 텍스트를 읽기 어려우면 그림자와 흐림 효과를 추가하고 알립니다.
4. "Ít"은 머리가 텍스트에 살짝만 닿습니다. "Nhiều"는 머리가 단어 중간의 한두 글자를 완전히 가려 트렌디해 보이지만 읽기는 더 어렵습니다. 각 단어의 첫 글자와 마지막 글자는 항상 유지됩니다.
5. 텍스트가 처음 0.5초 동안 나타나는 방식일 뿐입니다.
6. 테두리는 비디오가 정지되었을 때 어두운 배경에서 사람이 더 잘 보이도록 돕습니다.
7. 모든 사운드는 완전히 새로 생성되며 저작권 문제가 없습니다.

클립 자체에서 알 수 있는 내용(모양, 길이)에 대해서는 묻지 마세요. 사용자가 "cứ làm đi" 또는 "mặc định"라고 말하면 python scripts/tn.py settings defaults(tiktok, cao, 흰색, medium, rise, white, 노란색 악센트, 사운드 켜짐)를 실행하고 계속 진행하세요.

명령어

모든 명령어는 패키지가 설치된 Python으로 실행하세요 (python scripts/tn.py check 참조).

python scripts/tn.py check                                   # 설치된 것, GPU, RVM 모델 확인
python scripts/tn.py behind plan.json --out out/clip.mp4 --stills    # 텍스트당 4개의 스틸 이미지 + 검사 (빠름)
python scripts/tn.py behind plan.json --out out/clip.mp4 --preview   # 절반 크기, 텍스트 범위만 -> out/clip.preview.mp4
python scripts/tn.py behind plan.json --out out/clip.mp4             # 풀 렌더링, 원본 오디오 유지

클립의 첫 번째 실행 시 전체 클립에서 사람을 컷아웃하고(RTX 4080에서 약 50fps) 출력물 옆 _tach-nguoi-work/에 캐시합니다.

계획 파일 (당신이 작성)

{"clip": "raw/my-clip.mp4",
 "items": [{"text": "Thành công", "start": 1.0, "end": 7.0,
            "font": "cao", "color": "#ffffff", "anim": "rise", "cover": "medium"}]}

• text: 베트남어도 괜찮습니다 (모든 입력 형식; 정규화됨). "upper": false로 설정하지 않으면 대문자로 표시됩니다. \n은 강제로 두 줄로 나눕니다. 그렇지 않으면 스크립트도 두 줄 레이아웃을 시도하고 더 나은 것을 유지합니다.
• start / end: 초 단위. 최소 0.5초.
• font: cao (키가 크고 좁은 글꼴, 클래식한 스타일), dam (굵은 글꼴), dam-vua (아주 굵은 글꼴) 또는 .ttf 파일 경로.
• anim: rise, pop, letters (한 글자씩), none. 모든 텍스트는 0.25초에 걸쳐 사라지고 3% 안쪽으로 밀려납니다 ("drift": 0은 이 기능을 끕니다).
• cover: 사람이 텍스트를 가릴 수 있는 정도. light (항상 읽기 쉬움), medium (기본값), bold (트렌디한 스타일).
• 선택 사항: x, y (0-1 중심, 수동 배치), width (프레임 너비 비율), shadow (0-1 광선; 대비 검사에서 자동 설정됨).

배치는 자동으로 이루어집니다: 텍스트가 머리 뒤에 위치하고 각 단어의 첫 글자와 마지막 글자가 보이도록 가장 큰 크기와 위치를 선택하며, 플랫폼의 안전 영역 내에 배치합니다(9:16은 상단 바, 오른쪽 버튼 및 하단 캡션 영역을 피함).

프리즈 프레임 효과

python scripts/tn.py freeze plan.json --out out/clip.mp4 --stills    # 프리즈당 주요 스틸 이미지 (빠름)
python scripts/tn.py freeze plan.json --out out/clip.mp4 --preview   # 절반 크기 -> out/clip.preview.mp4
python scripts/tn.py freeze plan.json --out out/clip.mp4             # 풀 렌더링

{"clip": "raw/my-clip.mp4",
 "items": [
  {"effect": "intro", "at": 2.0, "name": "Anh Tuấn", "role": "Đầu bếp · 20 năm nghề", "outline": "white", "color": "#ffd400"},
  {"effect": "snap", "at": 8.5},
  {"effect": "comic", "at": 13.2, "caption": "Ủa, thiệt hả?!"}
 ]}

• 비디오는 hold 초 동안 한 프레임에서 일시 정지한 후(기본값: 인트로 2.4, 스냅 1.6, 코믹 1.8) 계속 재생됩니다. 클립은 정지 시간만큼 길어집니다. 원본 사운드도 일시 정지되고 효과 자체 사운드가 재생됩니다 (처음부터 생성, 라이선스 불필요; "sfx": false로 끄고 "sfx_gain"으로 크기 조절).
• at은 소스 클립의 시간입니다. 스크립트는 ±0.25 s 내에서 가장 선명한 프레임에서 정지합니다(모션 블러 없음). "exact": true는 정확한 프레임을 유지합니다. 사람의 얼굴이 선명한 순간(이름이 불릴 때, 큰 반응, 포즈)을 선택하세요.
• intro: 배경이 어둡고 회색으로 변하고, 사람이 윤곽선(white, color의 glow 또는 none)과 함께 6% 앞으로 튀어나오며, 이름 카드가 사람 반대쪽에서 슬라이드 인됩니다. name은 대문자로, role은 color로 표시됩니다.
• snap: 흰색 플래시 + 셔터 소리, 프레임이 흐릿한 복사본 위에 기울어진 인쇄된 사진으로 축소됩니다.
• comic: 평평한 색상, 잉크 선, 하프톤 점, 사람 뒤에 깜빡이는 속도선, 선택적 caption 상자(color는 상자 색상 설정).

클론 (분신)

python scripts/tn.py clone plan.json --out out/clip.mp4 --stills | --preview | (full)

{"clip": "raw/walk.mp4",
 "items": [{"effect": "trail", "start": 6.3, "end": 13.0, "every": 0.8, "style": "fade", "fade": 0.6}]}

• trail (원테이크): 사람이 움직이는 동안 start와 end 사이에서 every 초마다 복사본이 남고 유지되며, 모든 복사본은 fade 초에 걸쳐 사라집니다. 움직이는 사람만 복사됩니다 (가만히 있는 사람은 그대로 둡니다). style: fade (오래된 복사본이 더 희미해짐), solid, ghost (반투명, 절반 회색). 각 복사본이 나타날 때 부드러운 플래시 사운드가 재생됩니다 (계획 상단의 "sfx": false로 끕니다).
• two (두 테이크, 한 사람이 두 역할): {"effect": "two", "second": "raw/take2.mp4", "start": 0, "end": 10, "b_start": 0, "mode": "overlay"}. overlay는 두 번째 테이크에서 사람을 컷아웃하여 첫 번째 테이크 위에 배치합니다 ("front": "a"는 교차 지점에서 첫 번째 테이크의 사람을 앞에 유지). split는 가장 빈 열을 따라 두 테이크를 부드러운 이음새와 함께 결합합니다.
• 둘 다 먼저 배경에 맞게 각 프레임을 정렬하므로 약간 흔들리는 카메라도 작동합니다 (명령어는 카메라 이동 거리를 출력합니다). 삼각대가 여전히 가장 좋습니다: 큰 움직임이 있는 이동, 패닝 또는 핸드헬드 카메라는 정렬되지 않습니다.

알려진 제한 사항

• 머리 위나 옆에 공간이 있을 때 가장 잘 작동합니다. 얼굴이 세로 프레임을 가득 채우는 타이트한 클로즈업에서는 텍스트가 머리 위에 작게 배치됩니다. 이 사실을 알리고 더 넓은 샷이나 cover: bold를 제안하세요.
• 전체 비디오 컷아웃에는 PyTorch와 RVM 모델(GPL-3.0, 사용자 컴퓨터에서 첫 사용 시 다운로드)이 필요합니다. NVIDIA GPU를 사용하면 빠릅니다.

예시 프롬프트

복사-붙여넣기 프롬프트 (더 많은 내용은 examples/prompts.md에 설명과 함께 있습니다):

• 한 줄 시작: "Làm chữ 'THÀNH CÔNG' sau lưng mình trong clip raw/clip.mp4." → 설정 질문 (처음), 가독성 검사와 함께 4개의 스틸 이미지, 그 다음 텍스트가 뒤에 있는 전체 클립.
• 상세 브리핑: "Clip raw/phong-van.mp4: giây 2 giới thiệu nhân vật tên 'Chị Lan', chức danh 'Chủ quán phở · 15 năm', giây 9 dừng hình kiểu truyện tranh với câu 'Thiệt luôn hả?!', giây 14 chụp ảnh dừng hình. Có tiếng động." → 이름 카드 인트로, 말풍선이 있는 코믹 프리즈, 사진 스냅이 포함된 하나의 렌더링. 각각 고유한 사운드가 있습니다.
• 텍스트 뒤, 트렌드 스타일: "Chữ 'ĐÀ LẠT' sau lưng mình, cho đầu che nhiều như trend, chữ vàng, hiện từng chữ cái."
• 클론: "Clip raw/di-bo.mp4 mình đi ngang qua: để lại bóng mình mỗi 0,8 giây rồi mờ dần." → 당신의 경로를 따라 복사본이 남겨지고 함께 사라집니다.
• 두 테이크: "Mình quay 2 lần cùng chỗ (raw/vai-a.mp4, raw/vai-b.mp4), ghép thành 2 người nói chuyện với nhau."
• 비교: "Cho mình xem các kiểu chữ để so sánh." → 자신의 클립에 대한 레이블이 지정된 나란히 비교.
• 수정 참고: "Chữ to hơn chút, dời lên trên, dừng hình lâu hơn 1 giây, bỏ tiếng chụp ảnh." → 해당 변경 사항만 적용; 새 스틸 이미지, 그런 다음 새 렌더링 (이전 것은 유지됨).

문제 발생 시

이 스킬은 Claude Code로 제작되었으므로 버그가 있을 수 있으며, 모든 컴퓨터는 다릅니다. 단계가 실패하거나 사용자가 결과가 잘못되었다고 말할 경우:

1. 베트남어로 명확히 설명하세요: 무엇이 실패했고 왜 실패했는지 한두 문장으로 설명하세요. 요청하지 않는 한 원시 스택 추적은 표시하지 마세요.
2. 이 스킬과 관련 스크립트 (scripts/tn.py 및 해당 효과의 tn_*.py 파일)를 읽으세요. 무언가 누락된 경우 python scripts/tn.py check를 실행하세요.
3. 수정하고 다시 실행하여 새 출력 파일을 작성하세요. 수정 중에도 사용자의 클립을 절대 건드리거나 덮어쓰지 마세요.
4. 원인이 이 스킬 자체에 있었다면 그 사실을 알리고 모두를 위해 수정될 수 있도록 보고를 제안하세요: https://github.com/thegentleminh/thegentleminh-skills/issues

일반적인 실패

• No module named 'torch': 명령어를 실행한 Python에 PyTorch가 설치되지 않았습니다. tach-nguoi-env 환경의 Python을 사용하세요.