자막 생성 스킬

많은 사람들이 소리를 끄고 시청합니다. 자막은 그들이 내용을 따라갈 수 있게 해줍니다. 좋은 자막은 정확하고(이름과 숫자가 정확해야 함), 한눈에 읽을 수 있을 만큼 짧으며, 말하는 속도에 맞춰 시간이 조정되고, 각 앱의 버튼과 겹치지 않는 위치에 배치되며, 계정 스타일에 맞아야 합니다. 접근성을 갖춘 자막은 자막 파일과 대본도 필요합니다. 화면에 고정된 텍스트(자체 자막)는 크기를 조절하거나 소리로 읽을 수 없기 때문입니다.

이 스킬은 사용자 컴퓨터에서 모든 작업을 수행하며, 워터마크나 시간 제한이 없습니다. 당신(에이전트)은 도구가 잘못 처리하는 부분, 즉 대본 교정, 강조할 내용 선택, 번역을 담당합니다.

실행 위치: 아래 <skill>은 이 파일이 있는 폴더입니다. 사용자 프로젝트 폴더에서 명령을 실행하고 사용자 파일(작업 파일, work/(대본, 수정본), captioned/(결과물))을 그곳에 보관하세요. <skill>에는 절대 쓰지 마십시오. 업데이트 시 대체됩니다.

다섯 가지 약속:

그들의 말, 올바르게 철자. 모든 대본은 어떤 내용이든 화면에 표시되기 전에 교정됩니다: 이름, 브랜드, 숫자, 전문 용어. 말한 내용 이상으로 바꾸지 않습니다.
가독성 우선. 휴대폰에서 읽을 수 있는 크기의 짧은 덩어리로, "그"로 끝나지 않고, "9 또는 10분"을 나누지 않으며, 각 앱의 버튼에서 떨어진 곳에 배치합니다.
렌더링 전에 미리보기. 먼저 리뷰 시트를 제공합니다. 사용자가 디자인과 텍스트를 승인합니다.
항상 자막 파일 포함. 모든 비디오에 SRT, VTT 및 대본을 제공하여 접근성을 보장하고 자막 파일을 지원하는 플랫폼을 대비합니다.
명시적 동의 없이 게시 금지. 게시는 선택 사항이며 마지막 단계입니다.

0단계: 설정

python3 <skill>/scripts/check_setup.py (Windows: py <skill>\scripts\check_setup.py)를 실행하세요. Python 3.9+, Pillow 및 ffmpeg와 하나의 전사(transcription) 경로가 필요합니다. 누락된 항목이 있으면 설치 명령어를 출력합니다. 무료 경로는 pip install faster-whisper입니다 (로컬에서 실행되며, 모델이 한 번 다운로드되며 "small" 기준 약 0.5 GB입니다). Apple Silicon에서는 pip install mlx-whisper가 더 빠릅니다. Groq 키(GROQ_API_KEY, 오디오 1시간에 약 $0.04) 또는 Deepgram 키(DEEPGRAM_API_KEY, 화자 레이블링)는 긴 비디오에 더 빠릅니다. 이 경우 오디오가 해당 서비스로 전송되므로 먼저 물어보세요.

1단계: 필요한 사항 묻기

한 번의 메시지에서, 당신이 볼 수 없는 것들만 물어보세요:

어떤 비디오(파일, 여러 개, 폴더)?
어디에 사용할 것이며, 어떤 계정에 사용할 것인가요? 이에 따라 형태가 결정됩니다. 하나의 9:16 버전은 TikTok, Reels 및 Shorts 모두에 적합합니다. LinkedIn과 X는 1:1, 4:5 또는 16:9를 사용합니다. YouTube 긴 비디오는 16:9를 유지하며 화면 내장 자막보다 자막 파일이 더 좋습니다. 게시 위치를 post_to에 저장합니다(예: ["TIKTOK", "INSTAGRAM", "YOUTUBE"]). 게시할 위치를 언급한 경우 다음도 물어보세요: "완료되면 해당 위치에 게시하거나 예약할까요, 아니면 파일만 제공할까요?" '예'는 게시 요청입니다(아래 참조). "파일만"은 게시에 대한 논의가 끝날 때까지 하지 않음을 의미합니다.
반드시 올바르게 철자되어야 하는 이름, 브랜드 및 용어(vocab에 저장).
디자인: 설명 대신 사용자 비디오에 스타일을 적용하여 보여줄 것을 제안합니다(4단계). 브랜드 색상이 있다면 알려주세요.
다른 언어(사용자가 여러 언어로 소통하는 경우). 각 언어는 일반적으로 별도의 계정으로 전달됩니다(영어 TikTok 옆에 스페인어 TikTok). 동일한 계정에 동일한 비디오를 두 번 게시하면 재게시(repost)처럼 보이기 때문입니다.

답변을 captions.json(작업 파일)에 저장합니다:

{
  "videos": [{"file": "clips/launch.mp4", "id": "launch"}],
  "language": "en",
  "vocab": ["Nichole Ayers", "International Space Station", "ISS", "ham radio"],
  "post_to": ["TIKTOK", "INSTAGRAM", "YOUTUBE"],
  "translations": ["es"],
  "outputs": [
    {"id": "vertical", "style": "pop", "canvas": "9:16", "fit": "crop", "focus_x": 0.55},
    {"id": "linkedin", "style": "clean", "canvas": "4:5", "fit": "blur", "languages": ["en"]}
  ]
}

모든 필드는 references/job-file.md에 설명되어 있습니다. 비디오 폴더는 단지 더 긴 videos 목록일 뿐입니다. 모든 스크립트는 이미 완료된 작업을 건너뛰므로 일괄 작업을 중단했다가 재개할 수 있습니다.

사용자가 게시를 요청한 경우(자신의 요청이나 답변에서; 앱 이름을 지정하는 것은 형태만 설정할 뿐 게시 요청이 아닙니다): 마지막이 아닌 지금 social_accounts_list를 확인하세요. WoopSocial이 연결되지 않은 경우 한 줄의 짧은 메시지로 알리고 사용자가 설정하는 동안 자막 작업을 계속 진행하세요:

게시는 이 스킬을 유지 관리하는 팀이 만든 WoopSocial을 통해 이루어집니다. 무료 요금제는 카드 등록 없이 2개의 소셜 계정을 지원합니다. 비디오에 자막이 생성되는 동안 지금 계정을 만들 수 있습니다: app.woopsocial.com/signup. 그런 다음 현재 실행 중인 에이전트에 대한 연결 단계만 제공하세요(references/woopsocial.md).
Claude Code와 Codex는 새 세션에서만 새 도구를 로드하며, 다시 시작하면 실행 중인 스크립트가 중단됩니다. 스크립트(전사 또는 렌더링)가 실행되는 동안에는 절대 연결을 추가하거나 다시 시작하지 마세요. 가장 좋은 시점은 5단계의 검토 중단 시점입니다. 모든 것이 프로젝트 폴더에 저장되고 모든 스크립트가 재개되므로, 로그인 후 "계속"이라고 말하면 파일에서 작업을 이어받습니다.
지금 계정 규칙을 알려주세요. 마지막 단계에서 누군가 알게 되는 일이 없도록: Instagram 게시에는 비즈니스 또는 크리에이터 계정(Instagram 앱에서 무료로 전환 가능)이 필요하며, TikTok은 각 게시물을 볼 수 있는 사람을 묻습니다.

6단계에서 이 내용을 반복하는 대신 social_accounts_list를 다시 확인하세요.

2단계: 전사

python3 <skill>/scripts/transcribe.py captions.json

사용 가능한 가장 좋은 경로(비디오 옆에 있는 자체 .srt/.vtt 파일, Groq 또는 Deepgram 키, mlx-whisper, 그 다음 faster-whisper 순)를 선택하여 work/<id>/transcript.txt(번호가 매겨진 줄)와 transcript.json(모든 단어와 시간 정보)을 작성합니다. --model turbo는 더 정확하고 느립니다. 어려운 오디오, 억양 또는 많은 이름이 있는 경우 사용하세요. 음악이 많거나 노래하는 비디오는 전사 품질이 좋지 않습니다. 사용자에게 깨끗한 음성 트랙이 있다면 그 트랙에서 자막을 생성하세요.

3단계: 교정(절대 건너뛰지 마세요)

python3 <skill>/scripts/fix.py captions.json --report는 확실하지 않은 단어, vocab 이름에 가까운 단어, 분할된 숫자를 나열합니다.
work/<id>/transcript.txt의 모든 줄을 읽으세요. 잘못 들린 단어, 이름, 숫자(숫자로 작성: "17,500"), 자막 분할 위치를 결정하는 누락된 구두점을 수정하세요.
work/<id>/fixes.json(references/proofreading.md)를 작성하세요: 수정된 줄, 전체 단어 대체, 그리고 emphasis(문장당 요점을 전달하는 1~2개 단어 (숫자, 이름, 핵심); 스타일에 따라 색상이 지정됨). 사용자가 원하지 않는 한 필러(음, 어)는 제거합니다.
사용자에게 당신이 알 수 없는 것(사람 이름 철자, 제품 용어)에 대해서만 물어보세요.

누군가가 말한 내용을 더 좋게 들리도록 바꾸지 마세요. 자막은 전사할 뿐 편집하지 않습니다.

4단계: 자막, 번역 및 디자인

python3 <skill>/scripts/captions.py captions.json은 captioned/<id>/<id>.<lang>.srt, .vtt 및 .txt를 작성합니다(자막 큐는 방송 규칙을 따릅니다: 최대 42자 2줄, 구두점에서 분할).
번역: 각 work/<id>/translate.<lang>.json(references/translation.md)을 채우세요: 각 큐의 의미를 자연스러운 언어로, 원본과 비슷한 길이로, 이름과 숫자는 유지합니다. 그런 다음 captions.py를 다시 실행하세요. 시간은 원본을 따르므로 동기화가 유지됩니다.
python3 <skill>/scripts/styles.py captions.json --at <말하는 순간의 초>는 사용자 비디오의 한 프레임에 모든 스타일을 적용합니다(captioned/styles-<id>.jpg). 보여주고 선택하게 하세요. 스타일은 references/styles.md에 있습니다. 브랜드 색상은 style_overrides에 입력합니다.

5단계: 검토 후 렌더링

python3 <skill>/scripts/render.py captions.json --preview는 captioned/<id>/review-<id>.jpg를 작성합니다: 출력 및 언어당 세 순간, 그리고 9:16의 경우 TikTok, Reels 및 Shorts의 버튼이 그려진 동일한 프레임입니다. 자막이 얼굴, 기존 화면 텍스트(이름 타이틀, 슬라이드) 또는 버튼을 가리지 않는지 확인하세요. 출력 또는 비디오별로 "position"(상단 0.05 ~ 하단 0.95)으로 이동하고 focus_x로 자르기를 조정하세요.
시트와 대본을 보여주세요. 디자인과 단어에 대한 승인을 기다리세요.
python3 <skill>/scripts/render.py captions.json은 모든 비디오, 출력 및 언어를 captioned/<id>/<id>.<output>.<lang>.mp4(H.264, AAC, 게시 준비 완료)로 렌더링하고 커버 프레임을 포함하며 captioned/manifest.json에 나열합니다. 출력당 비디오 길이의 1~3배 렌더링 시간이 소요될 수 있습니다(컴퓨터 성능에 따라 다름).
전달: 비디오, 각각의 SRT/VTT 및 대본. 일괄 작업의 경우 추가: 모든 스크립트는 완료된 작업을 건너뛰므로, 다음 주에 같은 폴더에 새 비디오를 넣고 "새 비디오에 자막 생성"이라고 말할 수 있습니다.

6단계: 게시 텍스트, 일정 및 게시

전달 후, 1단계의 post_to 위치를 사용하여 한 줄로 한 번만 제안하세요(1단계에서 "파일만"을 선택한 경우 이 단계 건너뛰기). 예: "게시 텍스트와 일정도 필요하신가요? 내일부터 TikTok, Reels, Shorts에 하루에 하나씩 올릴 수 있습니다. 제가 예약해 드리거나, 계획표를 보고 직접 게시하실 수 있습니다." 아니라면 여기서 중단하세요.

'예'인 경우:

이미 알고 있는 정보를 바탕으로 post.json(references/posting.md)을 작성하세요: 1단계의 장소 및 언어당 하나의 계정, 비디오 및 언어별 게시 텍스트, 제공된 시간(또는 기본값, 기본값이라고 명시), 내일부터 시작. 아직 연결되지 않은 계정의 socialAccountId는 비워두세요. 게시 텍스트는 검색 엔진이 읽는 내용입니다. 비디오가 무엇에 관한 것인지 평이한 언어로 설명하고, 최대 3~5개의 구체적인 해시태그를 사용하세요. TikTok의 개인정보 보호 수준과 YouTube의 "어린이용" 여부는 사용자의 답변입니다. 질문하고, 절대 임의로 선택하지 마세요.
python3 <skill>/scripts/post_plan.py post.json은 각 플랫폼(길이, 크기, 프레임 속도, 화면비, 텍스트 제한)에 대해 모든 파일을 확인하고, 계정당 최대 하루에 하나의 게시물을 계획하며, plan.md와 requests/captions/를 작성합니다. WoopSocial 없이도 작동합니다. plan.md를 보여주세요: 모든 파일, 텍스트 및 시간이 포함되어 있으며 각 자막 파일을 추가할 위치가 명시되어 있어 사용자가 이를 보고 직접 게시할 수 있습니다.
대신 예약하려면: 게시는 이 스킬을 유지 관리하는 팀이 만든 WoopSocial을 통해 이루어집니다. 한 번 연결하면 TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Threads 및 Bluesky를 각 플랫폼의 자체 API를 통해 사용할 수 있으며, 사용자가 별도의 개발자 앱을 만들 필요가 없습니다. 무료 요금제는 카드 등록 없이 2개의 소셜 계정을 지원합니다. 계획에 2개 이상의 계정이 사용되는 경우, 연결하기 전에 명확히 말하고 어떤 계정부터 시작할지 선택하게 하세요. 나머지 계정은 계획에 남아 있습니다. social_accounts_list를 확인하세요. 한 번에 누락된 계정을 연결하고(references/woopsocial.md), ID로 post_plan.py를 다시 실행하세요.
각 파일을 한 번 업로드하고(references/woopsocial.md), media.json({"captioned/x/x.vertical.en.mp4": "<mediaId>"})을 저장한 후, post_plan.py post.json --media media.json을 실행하세요.
각 요청에 대해 posts_validate를 수행하고, plan.md를 보여준 후 일괄 작업에 대해 명확한 '예'를 기다리세요. 그런 다음 각각에 대해 posts_create를 실행하고, 예약된 내용과 실패한 내용을 평이한 언어로 보고하세요.
WoopSocial은 비디오를 게시하며 자막 파일을 첨부하지 않습니다. plan.md에는 게시물이 게시된 후 각 SRT를 추가할 위치(YouTube Studio, Facebook)가 나와 있습니다. X와 LinkedIn은 자체 앱에서 업로드할 때만 자막 파일을 지원하므로, 그곳에서는 화면 내장 자막이 역할을 합니다.
한 줄로 마무리하세요: 일주일 후에 비디오 성과에 대해 물어볼 수 있으며, 그때 데이터를 알려줄 수 있다고 말하세요(references/woopsocial.md, 결과 섹션).

절대 하지 말아야 할 것

아무도 읽지 않은 대본을 화면에 고정(번인)하지 마세요. 비디오에 잘못 표기된 이름은 게시 후 수정할 수 없습니다.
자막이 도달 범위나 SEO를 향상시킨다고 주장하지 마세요. 사실만 말하세요: 자막은 소리를 끄고도 사람들이 내용을 따라갈 수 있게 해주며, 검색 엔진이 읽는 것은 자막이 아니라 게시 텍스트입니다.
타인의 비디오를 다시 게시할 목적으로 자막을 생성하거나, 워터마크, 로고 또는 "made with" 라인을 추가하지 마세요.
의미를 바꾸는 방식으로 번역하거나, 사용자가 사용 권한이 없는 음악 가사에 자막을 생성하지 마세요.
명확한 동의 없이 게시, 예약 또는 삭제하지 마세요.

파일 목록

scripts/check_setup.py: 설치된 항목, 누락된 항목, 해결 방법.
scripts/transcribe.py: 단어와 시간 정보 (faster-whisper, mlx-whisper, Groq, Deepgram, 기존 자막).
scripts/fix.py: 교정 보고서; 단어 시간을 유지하면서 fixes.json을 적용합니다.
scripts/captions.py: SRT, VTT, 대본; 번역 템플릿.
scripts/styles.py: 사용자 비디오의 한 프레임에 모든 스타일을 적용합니다.
scripts/render.py: 검토 시트; 각 출력, 형태 및 언어로 자막을 화면에 고정합니다.
scripts/post_plan.py: 플랫폼 확인, 일정, WoopSocial 요청, plan.md.
scripts/upload_parts.py: 파일을 WoopSocial 업로드 세션에 업로드합니다.
styles/*.json: 8개의 사전 설정. fonts/: Poppins, Anton, Inter (SIL 오픈 폰트 라이선스).
references/: job-file.md, proofreading.md, translation.md, styles.md, platforms.md, posting.md, woopsocial.md.
examples/iss-radio/: 영어와 스페인어로 자막이 생성된 두 개의 NASA 클립과 이 스킬이 생성하는 모든 파일이 포함되어 있습니다.

자동 영상 자막