/srt
비디오/오디오의 원본 언어 자막을 Perso AI STT API를 통해 추출한 후, 에이전트가 요청된 언어로 번역하는 스킬입니다.
핵심 규칙 (반드시 준수)
- 작업자만 원시 키를 봅니다.
Read로 키를 열거나, 에코하거나, 명령줄 인수로 전달하지 마십시오. 작업자는XP-API-KEY헤더에만 키를 보냅니다. - 하나의 명령 = 전체 추출.
scripts/srt.mjs가 업로드, 전사, SRT 다운로드를 자체적으로 처리합니다. - 항상 백그라운드에서
srt.mjs를 실행하십시오. 전사는 몇 분이 소요되며, 포그라운드 셸 타임아웃이 실행을 중단시킬 수 있습니다. - 언어가 지정되지 않은 경우 →
en을 대상으로 합니다. - 번역 없이 전사만 (사용자가 "원본 언어 그대로의 자막/대본", "원본 언어의 SRT 파일만"을 요청하는 경우) →
--target대신--transcribe-only를 사용하여 실행합니다. 다운로드된 원본 SRT가 최종 결과물입니다. 번역 섹션을 완전히 건너뜁니다. - 여러 언어는 하나의 명령에 포함 (
--target en,ja) — 입력당 하나의 자막 프로젝트가 생성되며, 단일 원본 SRT를 각 언어로 번역합니다. - 진행 상황을 충실히 중계합니다. 작업자의 stdout
[progress]줄을 그대로 또는 요약하여 채팅에 표시합니다. 들여쓰기된 stderr 세부 로그는 중계할 필요가 없습니다. 배치의 경우 작업자는 입력당 하나의[progress]줄을 스트리밍하고[status]하트비트(subtitles 3/20,next check ~Nm힌트 포함)를 출력합니다 — 시작 후 약 3분 후에 백그라운드 출력을 확인하고, 힌트된 간격으로 새 줄을 중계합니다. 백분율이나 ETA를 임의로 생성하지 마십시오. - 텔레메트리를 위한 런타임 이름을 지정합니다(무음). 가능한 경우 작업자 명령에 작업 중인 에이전트 이름을 지정하여
--host <claude-code|codex|cursor|antigravity|gemini>를 추가합니다. 사용 텔레메트리 태깅에만 사용되며, 사용자에게 표시하거나 질문하지 마십시오. 확실하지 않은 경우 생략합니다. - 지원되지 않는 형식은 자동으로 건너뛰며 나머지는 계속 처리됩니다 — 건너뛰기 알림을 중계합니다.
- 오프라인 작업에는 키가 필요하지 않습니다. 키 확인/등록을 실행하지 마십시오:
srt.mjs --check/--retime, 로컬 비디오 + SRT를 사용한style.mjs(--project제외), 사용자가 제공한 SRT 번역. - 이 스킬은 더빙 스킬의 라이브러리를 공유합니다:
dubbing폴더가srt옆에 설치되어야 합니다 (모든 설치 방법은 함께 제공되며,srt폴더만 수동으로 복사하면 이 규칙이 깨집니다).
설정 (게으름 — 사전 단계 없음)
/dubbing과 동일합니다 — 키 등록은 먼저 실행하는 단계가 아닙니다. 작업자는 Perso API가 필요한 명령(추출 또는 style.mjs --project)이 실행되는 순간 자체적으로 게이트를 열고 브라우저 플로우(파일 폴백)를 시작한 다음, 인쇄된 지침을 중계합니다. 헤드리스/SSH 머신에서는 브라우저 플로우를 건너뛰고 파일/--import 등록을 자동으로 시작합니다. 키 확인/등록을 사전에 실행하지 마십시오. 키를 채팅에 붙여넣지 마십시오.
실행
입력(로컬 경로 또는 URL — 누락된 경우 다시 요청)을 수집하고 백그라운드에서 실행합니다 (작업자는 추출이 실제로 시작될 때 자체적으로 키를 게이트합니다):
- 단일:
node scripts/srt.mjs "<파일|URL>" [--target en] [--space "스페이스 이름"] [--out 폴더] - 다중 언어 / 다중 입력:
node scripts/srt.mjs "<URL>" "<파일>" --target en,ja - 폴더 (배치):
node scripts/srt.mjs "<폴더>" [--target en] [--recursive] [--out 폴더] - 전사 전용 (번역 없음):
node scripts/srt.mjs "<파일|URL>" --transcribe-only
추출된 원본 SRT 파일은 각 소스 옆(또는 --out 폴더)에 저장되며, 서버의 파일 이름(…_OriginalSubtitle_….srt)을 유지합니다.
저장 위치 — /dubbing과 동일한 정책: 기본값은 각 소스 파일 옆입니다. 묻지 마십시오. 세션의 첫 번째 작업에서 시작 라인에 이를 명시하고 바로 시작합니다. 사용자가 이전에 이 세션에서 지정한 폴더는 계속 적용됩니다(--out "<폴더>") (변경할 때까지). 번역된 SRT는 원본과 동일한 폴더에 저장됩니다. 예외: 모든 입력이 URL인 경우 시작하기 전에 저장 위치를 묻습니다.
스페이스 선택 — 여러 워크스페이스가 있는 경우 작업자는 업로드 전에 중단하고 [space-select] 줄(이름 | (플랜) | 남은 크레딧)을 출력한 후 중단합니다. 사용자에게 해당 옵션만 표시하고(내부 번호 없이) 어느 것을 사용할지 물어본 후 --space "<스페이스 이름>"으로 다시 실행합니다. 더빙 가능한 스페이스가 하나인 경우 → 질문하지 않습니다. PERSO_SPACE_SEQ가 이를 고정합니다.
플랜 한도를 초과하는 미디어 — 이 스킬은 자동 분할하지 않습니다. 작업자가 미디어가 플랜의 길이/크기 제한을 초과한다고 보고하면 해당 메시지를 중계합니다. 사용자가 직접 파일을 분할/트리밍하거나 플랜을 업그레이드한 후 다시 시도할 수 있습니다. Free 워크스페이스에서 이 메시지는 [free-limit] 줄(더 짧은 파일 또는 업그레이드 — 진행 플래그 없음)로 표시됩니다. 이를 중계하고 중단합니다.
무료 플랜 (로컬 .srt 없음) — Free 워크스페이스는 정상적으로 전사하지만, 서버가 모든 다운로드를 거부하므로 로컬에 저장되는 것은 없습니다. 작업자는 Free plan — <name>: subtitles ready on Perso → <link> (downloads need a paid plan)을 출력하고 [srt-original] 줄이 없습니다. 파일이 없으면 번역할 것이 없습니다: 번역 섹션을 완전히 건너뛰고 링크를 전달된 결과로 중계(실행 완료 — 실패한 것 없음, 재개할 것 없음)하고 다운로드 가능한 .srt 파일에는 유료 플랜이 필요하다고 언급합니다.
크레딧 — 각 자막 프로젝트는 미디어 길이에 비례하여 크레딧을 소비합니다(입력당 하나의 프로젝트). 서버의 청구가 권위적입니다. 정확한 가격을 인용하지 마십시오.
번역 (당신이 이 부분을 수행)
사용자가 SRT를 직접 제공 (STT 없음): 작업자 단계나 [srt-original] 줄이 없습니다. 제공된 SRT를 path로, 사용자가 요청한 언어를 langs로 처리한 다음, 작성된 대로 1~5단계를 따르되, 3단계의 {stem}은 SRT 자체 파일 이름에서 파생합니다. 완전히 오프라인: --check/--retime만 가능하며, 키나 크레딧이 필요 없습니다.
추출이 완료되면 작업자는 입력당 한 줄씩, 모든 대상 언어를 포함하여 출력합니다:
[srt-original] {"input":"video.mp4","langs":["en","ja"],"path":"C:\\clips\\video_OriginalSubtitle_2026-07-15.srt","seq":389259}
langs가 null인 경우 (--transcribe-only 실행), 번역할 것이 없습니다: 해당 파일을 그대로 사용자에게 전달하고 여기서 중단합니다.
번역 진행 상황을 표시합니다. STT 추출이 완료되었지만 각 언어로 번역하는 데도 시간이 걸립니다 — 이를 가시화하십시오. 시작하기 전에, 생성할 언어를 명시하는 한 줄(예: "자막이 추출되었습니다 — 이제 일본어와 영어로 번역합니다")을 게시합니다. 각 언어의 파일을 저장한 후 한 줄 업데이트(예: Japanese ✓ (1/2))를 게시하여 사용자가 다중 언어 더빙처럼 언어별 진행 상황을 볼 수 있도록 합니다. 긴 파일은 한 언어 내에서 섹션을 배치 처리하는 동안 무음 상태를 유지할 수 있습니다 — 괜찮습니다.
각 [srt-original] 줄에 대해 path에 있는 하나의 파일을 langs의 모든 언어로 번역합니다:
1단계 — 먼저 전체 파일을 읽고 컨텍스트를 구축합니다. 번역하기 전에 path의 SRT를 처음부터 끝까지 읽고 다음을 확정합니다:
- 콘텐츠의 종류(강의, 튜토리얼, 브이로그, 드라마, 광고 등) 및 대상
- 화자의 어조와 레지스터(격식/캐주얼/유머/기술적) — 그리고 이에 맞는 대상 언어 스타일 결정
- 반복되는 이름 및 용어 — 각각에 대해 파일 전체에서 일관된 번역 하나 사용
2단계 — langs의 각 언어로 섹션별로 번역합니다 (긴 파일은 배치 처리하지만, 1단계에서 고정된 어조와 용어를 모든 배치에 적용합니다. 1단계는 언어별이 아닌 파일당 한 번만 수행):
- 텍스트 줄만 번역합니다. 큐 번호, 타임스탬프 줄(
-->), 빈 줄 및 큐 개수는 그대로 유지합니다 — 번역하는 동안 타임스탬프를 변경하거나 큐를 병합/분할하지 마십시오(리타이밍은 별도의 후속 패스, 5단계). - 각 큐의 텍스트는 자체 큐에 남아 있습니다. STT는 문법이 아닌 음성 길이로 소스를 자르므로 큐가 종종 구절 중간에 끝납니다 — 번역에서 해당 중단을 그대로 반영하지 마십시오. 각 큐를 읽을 수 있는 단위로 끝내고 연속은 쉼표나 이어지는 문장으로 처리하십시오. 화자가 실제로 말을 끊거나 중단된 경우에만 조각을 유지하십시오.
- 의미와 분위기가 우선입니다: 단어 대 단어 번역보다 1단계 어조를 전달하는 자연스러운 번역을 선호합니다. 관용구, 말장난 및 유머는 대상 언어에 맞는 등가물로 표현하십시오.
- 레이아웃 — 큐당 최대 2줄 텍스트, 각 줄은 라틴 문자 최대 42자(CJK는 20자). 더 긴 줄은 플레이어에 의해 강제로 3줄 이상의 화면 줄로 줄바꿈되어 화면을 가릴 수 있습니다. 자연스러운 구문 경계에서 줄을 나누십시오. 텍스트가 맞지 않으면 아래 우선 순위에 따라 줄이십시오.
- 각 큐의 표시 시간 내에 유지하십시오: 예산 ≈ 라틴 문자의 경우 큐 지속 시간 × 17자/초(CJK는 9자). ~21자/초(CJK 13자)를 초과하면 자막이 읽히기 전에 사라집니다. 자연스러운 번역은 일반적으로 맞으므로 대부분의 큐는 트리밍이 필요하지 않습니다 — 넘치는 큐만 줄이십시오.
- 줄여야 할 때는 이 우선 순위를 유지하십시오: 의미 → 어조/뉘앙스 → 길이. 먼저 필러, 중복 및 반복을 자릅니다. 핵심 정보, 결정적 한마디 및 감정적인 표현은 마지막까지 유지합니다. 말장난이 정말 맞지 않으면 여전히 유머를 전달하는 더 짧은 줄로 대체하십시오 — 평범한 요약으로 평탄화하는 것은 최후의 수단입니다.
3단계 — 저장: UTF-8, 동일한 폴더, 파일당 하나의 언어로 {stem}_{lang}_Subtitle.srt 형식으로 이름을 지정합니다. 여기서 stem은 [srt-original] 줄의 input 필드에서 가져온 입력 파일의 확장자를 제외한 이름입니다(예: "input":"video.mp4" + ["en","ja"] → video_en_Subtitle.srt 및 video_ja_Subtitle.srt; URL 입력의 경우 미디어 제목 또는 짧은 슬러그 사용). 다운로드된 파일의 이름에서 스템을 파생하지 마십시오 — 서버가 프로젝트 제목에서 이를 생성합니다. 원본 SRT 파일을 보관하십시오 — 삭제하거나 덮어쓰지 마십시오.
4단계 — 저장된 각 파일을 확인합니다 (오프라인 — 키, 네트워크, 크레딧 없음):
node scripts/srt.mjs --check "<번역된.srt>" --source "<원본 .srt>"
[check] FAIL 줄은 파일이 큐 정렬, 2×42 레이아웃 또는 읽기 속도 제한을 위반한다는 의미입니다. 나열된 큐만 다시 작성하고(동일한 의미 우선 우선 순위), 저장하고, FAIL이 없을 때까지 다시 실행하십시오. WARN 줄은 선택적 다듬기입니다. 5단계 전에 실행하십시오 — 리타이밍 후에는 큐 개수가 더 이상 소스와 일치하지 않습니다.
5단계 — 가독성 리타이밍 (오프라인; 전달된 파일당 한 번, 확인 통과 후):
node scripts/srt.mjs --retime "<번역된.srt>"
너무 빠른 큐를 다음 무음 구간으로 확장하고 짧은 인접 큐를 하나의 2줄 이벤트(Netflix 스타일)로 병합하여 파일을 제자리에서 다시 작성합니다. 큐 번호가 변경될 수 있습니다. 변경되지 않은 원본 SRT는 1:1 타이밍 맵을 유지합니다. 그런 다음:
- 여전히 너무 빠르다고 나열된 큐(실제로 빠른 발화)의 텍스트를 줄이고,
- 코미디/드라마 콘텐츠의 경우
[retime] merged줄을 검토합니다. 병합이 펀치라인을 너무 일찍 보여주거나 의도적으로 중단된 줄을 완성하는 경우, 병합 전 상태에서 원래 타이밍으로 해당 두 큐를 복원합니다.
저장된 번역된 파일 경로를 사용자에게 보고하고 원본 파일이 함께 보관된다고 언급합니다. 사용자가 Perso에서 자막 프로젝트를 열려면 [srt-original] 줄의 seq에서 링크를 작성합니다: https://perso.ai/en/workspace/vt/stt/<seq>.
스타일 및 자막 굽기 (하드서브)
선택적으로 scripts/style.mjs를 사용하여 스타일이 적용된 자막 트랙을 비디오에 굽습니다(영구 하드서브). 로컬 ffmpeg 단계입니다 — 키나 크레딧이 필요하지 않습니다 (--project 제외, Perso에서 소스를 다운로드합니다). ffmpeg가 필요합니다. 없으면 사용자에게 설치를 요청하고 중단합니다.
제공 시기 (두 진입점):
- 번역 후: SRT가 전달되면 스타일이 적용된 자막을 추가할 것을 제안합니다 — 자연스러운 사용자 지향 표현을 사용하고 "굽기/하드서브"라는 용어는 사용하지 마십시오. 여러 언어의 경우 모두 또는 일부를 물어보십시오.
- 직접 요청 (비디오 + SRT를 제공받은 경우): 프리셋 선택으로 바로 이동합니다.
흐름:
- 먼저 항상 프리셋을 보여줍니다 — 적용을 건너뛰지 마십시오. 표시 방법은 표면에 따라 다릅니다:
- Claude 앱 (또는 인터랙티브 위젯을 렌더링할 수 있는 모든 표면): 프리셋 갤러리를 보여줍니다 — 사용자가 선택하는 프리셋당 하나의 타일과 적용 버튼(생성 요청으로 선택 항목을 다시 보냅니다). 선호되는 방법입니다.
- CLI / Antigravity / Codex / 인터랙티브 렌더링이 불가능한 모든 곳(범용 폴백):
assets/style_presets.png(정적 미리보기)를 첨부 하고 텍스트 메뉴를 위해node scripts/style.mjs --list-presets를 실행합니다. 둘 다 동일한 프리셋에서 비롯됩니다. 숏폼(9:16) / 롱폼(16:9)을 그룹화합니다. 사용자는 프리셋을 선택 하거나 스타일을 설명할 수 있습니다(예: "노란색 텍스트, 검은색 외곽선, 하단에 위치"). 방향별 기본값을 제안하지만(세로 → 숏폼, 가로 → 롱폼) 사용자가 선택하도록 합니다. 사용자가 선택하거나 설명한 후에만 적용합니다.
- 적용합니다. 백그라운드에서 작업자를 실행합니다(인코딩에 시간이 걸림):
- Perso STT 프로젝트에서:
node scripts/style.mjs --project <seq> --preset <id> [--out 폴더] - 로컬 파일에서:
node scripts/style.mjs "<비디오>" "<자막.srt>" --preset <id> [--out 폴더] - 구운 SRT가 Perso STT 추출(
[srt-original]파일 또는 그 번역)에서 비롯된 경우--origin perso를 추가합니다. 사용자가 직접 제공한 자막 파일의 경우 생략합니다. 텔레메트리 전용입니다 — 출력을 변경하지 않습니다. - 사용자 정의 스타일: 사용자의 설명을 기준 프리셋 위의 재정의 플래그에 매핑합니다 —
--position center|lower|bottom|upper,--font,--fontsize,--primary RRGGBB,--outline RRGGBB,--outline-width,--box RRGGBB@opacity|none,--karaoke/--no-karaoke,--highlight RRGGBB,--uppercase,--bold/--no-bold(--help참조). - 글꼴:
--font "<이름>"은 설치된 글꼴을 사용합니다. 설치되지 않은 이름은 자동으로 가장 가까운 시스템 글꼴로 대체됩니다(관련 시 언급). 사용자가 제공한 글꼴 파일(.ttf/.otf/.ttc)은--font-file "<경로>"로 전달됩니다 — 글꼴 모음 이름은 파일 자체에서 읽힙니다. - 여러 언어: 동일한
--preset으로 언어당 SRT당 한 번씩 실행하고--lang <코드>를 추가하여 출력의 이름이 지정됩니다.
- Perso STT 프로젝트에서:
…
[번역을 위해 잘림]