Communitygithub.com

Perso SRT 추출+번역 — 캡션 소스 패스

Perso AI STT로 영상/오디오/URL에서 SRT를 추출하고 타이밍을 유지한 채 번역. 무료 자막 경로로 더빙·하드번인 출고.

Perso SRT 추출+번역 — 캡션 소스 패스란 무엇인가요?

Video Localization 1단계(ASR/번역): perso-dubbing-plugin-srt. 영상/URL → 원문 SRT → 다국어 번역 SRT.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/perso-ai/perso-dubbing-plugin/tree/HEAD/skills/srt

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

/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를 제공받은 경우): 프리셋 선택으로 바로 이동합니다.

흐름:

  1. 먼저 항상 프리셋을 보여줍니다 — 적용을 건너뛰지 마십시오. 표시 방법은 표면에 따라 다릅니다:
    • Claude 앱 (또는 인터랙티브 위젯을 렌더링할 수 있는 모든 표면): 프리셋 갤러리를 보여줍니다 — 사용자가 선택하는 프리셋당 하나의 타일과 적용 버튼(생성 요청으로 선택 항목을 다시 보냅니다). 선호되는 방법입니다.
    • CLI / Antigravity / Codex / 인터랙티브 렌더링이 불가능한 모든 곳(범용 폴백): assets/style_presets.png(정적 미리보기)를 첨부 하고 텍스트 메뉴를 위해 node scripts/style.mjs --list-presets를 실행합니다. 둘 다 동일한 프리셋에서 비롯됩니다. 숏폼(9:16) / 롱폼(16:9)을 그룹화합니다. 사용자는 프리셋을 선택 하거나 스타일을 설명할 수 있습니다(예: "노란색 텍스트, 검은색 외곽선, 하단에 위치"). 방향별 기본값을 제안하지만(세로 → 숏폼, 가로 → 롱폼) 사용자가 선택하도록 합니다. 사용자가 선택하거나 설명한 후에만 적용합니다.
  2. 적용합니다. 백그라운드에서 작업자를 실행합니다(인코딩에 시간이 걸림):
    • 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 <코드>를 추가하여 출력의 이름이 지정됩니다.

…

[번역을 위해 잘림]

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

관련 스킬