자막
이것은 하나의 작업이며, 흐름의 일부가 아닙니다. 사용자가 요청할 때만 수행합니다——편집 직후에도 가능하고, 편집 후 두 문장을 삭제한 뒤 다시 수행해도 됩니다.
전제 조건은 단 하나: 장부가 이미 존재해야 합니다. 편집 뒤에 있어서가 아니라, 장부가 없으면 어떤 문장이 남았는지, 각각 완성본의 몇 초에 위치하는지 알 수 없기 때문입니다.
필요 edit-list.json(장부), transcript.json(단어별 대본)
산출 subtitles.json
완료되면 멈추고, 사용자에게 다음 단계를 지시하지 않습니다.
먼저 비즈니스 Skill 단계별 계약을 읽고 실행하며, 판단 기준은 자막 교정 규칙을 따르고, 고유 명사 표기는 AI 용어 사전을 참조합니다.
누가 무엇을 결정하는가
이것이 이 단락의 기초이며, 나머지는 모두 여기서 도출됩니다.
음성 편집 「어떤 말을 남기고, 언제 보여줄지」를 결정 ← 시간의 유일한 진실
자막 「화면에 어떤 글자를 표시할지」를 결정 ← 표시의 유일한 진실
한 화면의 자막은 단어 ID 목록 + 표시 텍스트를 저장하며, 초 단위 시간을 저장하지 않습니다. 시간은 매번 장부에서 실시간으로 계산됩니다. 따라서 두 장부에는 두 번째 시간이 어긋날 수 없으며, 무효화되어도 화면 단위로 정확하게 파악할 수 있습니다: 「7번째, 12번째 화면의 단어가 잘렸습니다」라고 표시되며, 아무도 클릭할 수 없는 「자막이 만료되었을 수 있습니다」라는 메시지가 표시되지 않습니다.
자막이 자체 텍스트를 저장하는 것은 의도적입니다. 음성 인식은 「그가 말한 것」을, 자막은 「사람이 볼 것」을 담당합니다——구두점, 생략된 말버릇, 고유 명사의 공식 표기법은 원래 달라야 합니다. 하나의 문자열로 두 가지 작업을 강제하면 자막에 쉼표를 추가할 수 없게 됩니다.
0. 준비
먼저 확인 및 업데이트의 「준비 확인」을 실행——skills가
최신인지, Runtime이 호환되는지 확인합니다. 플러그인 루트도 여기서 찾습니다(이 문서의 명령어에서 <플러그인 루트>는
모두 그 문자 경로로 대체). 「준비 완료」인 경우에만 계속합니다. 「새 세션 필요」 또는 「중지」인 경우
해당 조치에 따라 실행합니다(「자체 제작 대체 UI 금지」 명령 포함). 비즈니스 Skill은 자체 환경 로직을 포함하지 않습니다.
준비 결과가 runtime.kind=desktop-managed인 경우, 데스크톱 앱에 이미 설치된 안정적인 CLI와
동일한 launchd/windows-task 서비스를 직접 재사용합니다. Electron 경로를 해석하거나, 종속성을 추가로 설치하거나,
두 번째 Runtime을 시작하지 마십시오.
1. 진입 조건 확인
node "<플러그인 루트>/scripts/ensure-running.cjs" --json
node "<플러그인 루트>/scripts/videocut-cli.cjs" inspect "<프로젝트 디렉토리>" --json
| 조건 | 불충족 시 |
|---|---|
edit-list.json이 존재하고 조각이 있음 | 장부가 없다고 명확히 말하고, 사용자에게 음성 편집을 요청하도록 안내합니다. 직접 편집하지 마십시오. |
transcript.json이 존재함 | 프로젝트가 준비되지 않았으므로 중단합니다. 직접 만들지 마십시오. |
source_cut.mp4의 존재 여부나 음성 인식을 확인하지 마십시오. 자막에는 둘 다 필요하지 않습니다——다음 절을 참조하십시오.
2. 글자 수정: 먼저 사전, 그 다음 원고
새로운 음성 인식이 필요하지 않습니다. 원래 단어별 대본에는 이미 타임스탬프가 포함되어 있으며, 장부는 어떤 부분이 남았는지 알고 있습니다—— 각 단어가 완성본의 몇 초에 위치하는지는 계산되며, 다시 듣는 것이 아닙니다:
단어가 원본의 몇 초에 있는지 음성 인식에 있음
어떤 부분이 남았는지 장부에 있음
단어가 완성본의 몇 초에 있는지 둘을 계산하면 나옴
ASR을 다시 보내는 것은 같은 내용을 다시 듣는 것일 뿐으로, 비용과 시간이 들고, 더 나쁜 결과를 가져옵니다——고유 명사를 다시 수정해야 합니다.
(transcript retranscribe는 이전 설계의 잔재로, 당시 자막이 편집된 비디오의 전사본에서 시간 축을 얻으려 했습니다.
자막이 단어 ID 앵커로 변경된 후 이 문제는 사라졌습니다. 자막을 만들 때 이것을 사용하지 마십시오.)
두 가지 다른 도구를 모두 사용해야 합니다.
# 사전: 이 화자의 고정 표기법, 증거 불필요
node "<플러그인 루트>/scripts/videocut-cli.cjs" transcript dictionary "<프로젝트 디렉토리>" --dictionary "<플러그인 루트>/references/ai-term-dictionary.md" --json
# 원고: 저자가 원고를 가지고 있을 때만 수행, 각 항목에 증거 필요
node "<플러그인 루트>/scripts/videocut-cli.cjs" transcript align "<프로젝트 디렉토리>" --script "<대본 파일>" --json
사전 항상 이렇게 씀 문맥을 보지 않고 직접 수정, 수정된 항목을 나열
원고 문맥이 일치할 때만 이렇게 씀 각 항목에 증거 필요, 일치하지 않으면 「확정 불가」를 보고하고 추측하지 않음
사전이 반드시 필요한 이유, 원고만으로는 부족한 이유: 음성 편집은 재녹음됩니다. 실제 프로젝트에서 같은 문장을 네 번 녹음했고, 「연결叉」「叉는」과 같은 문맥이 여러 번 나타나면 align은 「확정 불가」를 보고할 수밖에 없습니다—— 규칙에 따라 추측하지 않기 때문입니다. 이름을 잘못 쓰는 것이 잘못 듣는 것보다 더 나쁘기 때문입니다. 세 번의 「叉」 중 한 번만 수정할 수 있습니다. 사전에는 이 문제가 없습니다. 이 화자의 작업에서 「叉」는 반드시 「X」입니다.
사전은 하나만 있습니다. 플러그인 수준의 references/ai-term-dictionary.md에 있습니다. 사전은 음성 인식을 수정하며,
음성 편집과 자막은 동일한 음성 인식을 사용합니다. 이 스킬 아래에 또 다른 사전을 만들지 마십시오.
수정 후 해당 목록을 확인해야 합니다. 사전은 문맥을 보지 않으므로 잘못 수정할 수도 있습니다——예를 들어 화자가 실제로 말한 「Skills」(Claude Skills, 복수 고유 명사)를 「Skill」로 정규화할 수 있습니다. 잘못된 것을 발견하면 사전을 수정하고, 명령어 쪽에서 패치하지 마십시오.
transcript align은 보고만 하고 수정하지 않습니다. 제안을 적용하려면 corrections를 [{wordId, text}]로 변환한 후 실행하십시오:
node "<플러그인 루트>/scripts/videocut-cli.cjs" transcript correct "<프로젝트 디렉토리>" --file "<수정 파일>" --json
음성 인식을 수정한 후, 이 단어들을 참조하는 자막 화면은 동일한 단계에서 자동으로 수정되며, subtitles.updated를 반환합니다.
수정할 수 없는 경우(해당 행이 누군가에 의해 다시 작성된 경우) needsAttention에 포함되어 사용자에게 보고되며, 추측하지 않습니다.
사전에 없고, 원고에도 어떤 표기법이 올바른지 확인할 수 없는 경우, 추측하지 마십시오. 사용자에게 사전을 보완하도록 보고하십시오—— 사전에 추가하면 다음 비디오에서 자동으로 올바르게 됩니다. 한 번 추측해도 다음 번에 다시 추측해야 합니다.
3. 화면 분할
node "<플러그인 루트>/scripts/videocut-cli.cjs" subtitle build "<프로젝트 디렉토리>" --json
네 가지 규칙, 순서대로:
① 여기서 말이 삭제됨 삭제된 양쪽이 타임라인에서 인접하고, 의미상 전혀 관련이 없음.
삭제된 것이 「무음」인 경우는 해당되지 않음——문장 중간의 일시 정지를 잘라내는 것은 문장을 나눌 수 없음.
② 모든 구두점 화산이 제공한 것, 마침표와 쉼표 모두 포함——**음성 편집 분할과 동일한 세분성**,
양쪽이 같은 지점에서 나뉨. 구두점은 시간 증거보다 강력함: 화자는 두 문장을 연속해서 쉬지 않고 말할 수 있고,
한 문장 중간에 멈출 수도 있음.
③ 단락 경계 + 일시 정지 **이 단어에 구두점이 없는 경우에만 사용.** 「구두점이 없을 때 단락으로 문장이 끝났음을 추측」하는 것이며,
구두점이 있으면 ②와 쉼표 규칙이 적용됨——이들은 화면이 충분히 긴지 고려하지만, ③은 고려하지 않음.
(구두점이 있는 경계에서도 ③이 발동하면, 실제 프로젝트에서 40화면이 43화면으로 늘어나 더 많은 조각 화면이 생성됨)
④ 시청자가 긴 일시 정지를 들음 문장 내부를 나누려면 더 긴 무음이 필요함.
음성 편집과 자막은 동일한 구두점을 사용하며, 세분성도 동일함: 쉼표 하나 = 한 단락 / 한 화면.
조각(한두 글자)은 병합되지만, 마침표를 넘어 병합하지는 않음—— 「你看」은 새로운 문장의 시작이며, 이전 문장의 꼬리가 아니므로, 앞으로 병합하면 「…호출 Grok CLI你看」처럼 두 문장이 붙어버림.
빠르게 말하는 짧은 문장은 유지됨(실제 프로젝트에서 「매일 아침」「작업 실행」 각 0.6초). 화자가 실제로 그렇게 말한 것이므로 경고하지 않음. 쉼표 하나당 한 화면은 필연적으로 이러한 화면을 생성하며, 경고하면 정상적인 말하기에 대한 경고가 되어 경고를 무시하게 됨.
한 화면보다 긴 나머지는 균등하게 여러 화면으로 분할하며, 한 화면에 한 줄. 한두 글자의 조각이 생성되면, ②의 경계가 실제로 마침표가 아님을 의미하므로 조각을 이전 화면에 병합.
명령어는 네 가지 결과를 반환하며, 모두 확인해야 함:
stale 편집으로 변경된 화면——정확히 몇 번째 화면인지, 어떤 글자가 손실되었는지 표시
tooFast 글자가 너무 많아 읽을 시간이 부족함
transcriptMoved 음성 인식이 더 이상 원본이 아님
이미 자막이 있는 경우 —— 여기서 멈추고 질문해야 함
--replace를 추가하지 않으면 명령어가 직접 거부됩니다. 이것은 이 스킬에서 사용자 동의를 구해야 하는 유일한 경우입니다.
--replace는 사용자가 시간을 들여 만든 화면 분할과 표현을 덮어쓰며, 제품이 자체적으로 복구할 수 없기 때문입니다.
사용자가 몇 글자를 수정하려는 경우 build를 실행하지 마십시오. Studio에서 직접 수정하거나, 어떤 화면을 수정할지 알려주도록 하십시오.
사용자가 처음부터 다시 시작하려는 경우 확인 후에만 --replace를 추가하십시오.
4. 검토: Studio에서 화면별로 확인
node "<플러그인 루트>/scripts/videocut-cli.cjs" open "<프로젝트 디렉토리>" --json
열린 후 왼쪽 패널의 「자막」탭으로 전환합니다. 한 줄이 한 화면: 왼쪽에는 번호와 시간, 오른쪽에는 텍스트가 있으며, 클릭하여 직접 수정할 수 있습니다.
- Enter = 커서 위치에서 새 화면 시작
- 줄 맨 앞에서 Backspace = 이전 화면에 병합
- 오른쪽 패널 「매개변수 → 자막」의 네 가지 사전 설정 중 하나를 선택하여 전체 영화에 하나의 스타일 적용
- 화면에서 자막을 직접 볼 수 있으며, 위치와 글꼴 크기가 화면 비율과 일치——미리보기와 최종 출력은 동일한 수치 사용
검토 시 최소한 사용자에게 다음을 확인하도록 해야 함: 고유 명사가 올바른지, 글자가 누락되지 않았는지, 문장 구분이 자연스러운지, 한 화면에 머무는 시간이 읽기에 충분한지.
5. subtitles.json까지
이 단락이 완료되었습니다. 물리적 편집, 컷 편집, 애니메이션, 최종 출력 렌더링을 수행하지 않으며, 사용자에게 다음 단계를 촉구하지도 않습니다.
보고서는 분리하여 작성해야 함: Product 구조화된 readback은 API/readback PASS; 실제 동일 프로젝트 브라우저 프레임 검토만 visual frame PASS; 누구도 실제로 자막과 화면이 일치하는지 확인하지 않은 경우 일률적으로 human listening UNVERIFIED로 처리해야 하며, DOM, 스크린샷 또는 파일 탐지로 대체해서는 안 됩니다.
경계: 화면에 굽는 것은 이 단락의 작업이 아님
출력 방식은 화면에 굽는 것으로 결정되었으며, 화면은 내보내기 단계에서 그려집니다. 자막의 출력은 subtitles.json입니다——
그 안의 모든 치수는 화면의 백분율이며, 내보내기 시 출력 해상도에 따라 픽셀로 변환하면 됩니다. 양쪽 모두 동일한 수치를 사용합니다.
오늘 내보낸 mp4에는 자막이 없습니다. 해당 단계는 아직 수행되지 않았습니다. 보고서에 이 결과를 명확히 기재하고, 「자막이 준비되었습니다」라고만 말해서는 안 됩니다——사용자는 최종 결과물에 자막이 있다고 생각할 수 있습니다.
복구 및 실패
subtitles_exist: 이미 자막이 있습니다. 먼저 질문하고, 직접--replace하지 마십시오.revision_conflict: 다른 곳에서도 쓰고 있습니다. 다시 읽고, 자동으로 덮어쓰지 마십시오.- 사전에서 「N번째 줄을 읽을 수 없음」: 포맷이 잘못된 테이블 행입니다. 규칙은 테이블 행(
| 올바른 표기 | 흔한 오인식 |)만 인식하며, 산문과 목록은 무시됩니다. transcript correct에서 「must not change any word id, time or gap flag」: 글자 수정 제안에 시간을 변경하는 내용이 포함되어 있습니다. 글자 수정은 글자만 수정해야 합니다.runtime_unhealthy: 반복적으로 재설치하지 마십시오.- 어떤 실패도 「음성 인식 완료」를 「자막 준비 완료」로 말해서는 안 됩니다. ASR 결과물은 원자재이지, 최종 산출물이 아닙니다.