EdgeSpeak 가라오케
단일 EdgeSpeak 전사 요청으로 가라오케 자막을 만듭니다. 번들로 제공되는 제로 의존성 Node.js 스크립트를 사용하여 결정론적 ASS 생성, 실제 프레임 스타일 미리보기 및 FFmpeg 렌더링을 수행합니다.
사용자가 스타일을 선택하도록 하세요
소스 경로, 출력 위치 및 ASS, 하드 자막 또는 둘 다를 원하는지 수집합니다. 스타일은 사용자가 보고 동의하지 않을 수 있는 유일한 결정이므로 기본적으로 사용자의 결정으로 간주합니다.
- 명시적: 명명된 프리셋 또는 재정의를 따릅니다. 사용 가능한 프리셋은
classic,minimal,boxed,high-contrast입니다. - 자동: 사용자가 실제로 결정을 위임하는 경우에만 사용합니다 ("네가 골라줘", "아무거나", "그냥 빨리 해줘", "기본값 사용"). 아래 표에서 선택하고 차단하지 않고 계속 진행합니다.
- 미리보기 후 질문 — 사용자가 스타일 선호도를 밝히지 않은 경우의 기본값입니다. 실제 소스 프레임에 모든 프리셋을 렌더링하고, 런타임의 이미지 보기 기능으로 PNG를 표시한 후 하나의 간결한 질문을 합니다. 터미널은 경로와 설명을 나열할 수 있지만, ANSI 텍스트는 충실한 시각적 미리보기가 아닙니다.
침묵은 위임이 아닙니다. 스타일에 대해 언급하지 않은 사용자는 일반적으로 옵션을 보지 못한 것이지 건너뛰기로 결정한 것이 아닙니다. 질문하는 것은 짧은 교환 한 번이면 됩니다. 잘못 추측하면 전체 비디오를 다시 렌더링해야 하며, 하드 자막의 경우 이는 비용이 많이 드는 경로입니다.
이중 언어 출력의 경우 어떤 언어가 위에 위치할지는 동일한 종류의 보이는 선택입니다. 두 번 묻지 말고 그 하나의 질문에 포함시키세요.
미리보기를 렌더링했으면 반드시 보여주세요. --preview-media는 실행할 때마다 네 가지 프리셋을 모두 렌더링하므로, 명령이 완료되는 즉시 전체 비교가 이미 디스크에 존재합니다. 하나의 PNG만 열고 조용히 선택한 후 승자만 보고하면 사용자가 볼 권리가 있었던 절충안을 숨기는 것입니다.
자동 모드의 경우 — 그리고 미리보기와 함께 제공되는 권장 사항을 시드하기 위해 — 대표적인 소스 프레임을 검사하고 다음 기본값을 사용합니다:
| 영상 유형 | 프리셋 |
|---|---|
| 일반 풍경 또는 혼합 콘텐츠 | classic |
| 깨끗하고 대체로 어두운 배경 | minimal |
| 복잡하고 밝거나 슬라이드/화면 녹화 | boxed |
| 세로/모바일 또는 지속적으로 어려운 배경 | high-contrast |
소스 전반에 걸쳐 밝기가 변동하는 경우 — 같은 비디오에 어두운 장면과 밝은 장면이 있는 경우 — 단일 프레임으로 결정을 내릴 수 없습니다. 대비되는 두 타임스탬프에서 미리보기를 렌더링하고 둘을 비교하세요. 밝은 프레임에서 승리한 프리셋이 어두운 프레임에서는 보이지 않을 수 있기 때문입니다.
현재 요청 지침이 우선합니다. 존재하는 경우 .edgespeak-skills/edgespeak-karaoke/EXTEND.md에서 선택적 환경 설정을 읽은 다음 ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md에서 읽습니다. 프로젝트 환경 설정이 사용자 환경 설정보다 우선합니다. 유용한 환경 설정에는 프리셋, 글꼴, 글꼴 크기, ASS 색상, 여백, 출력 형식 및 품질이 포함됩니다.
한 번에 전사 및 정렬
-
소스가 존재하는지 확인하고
ffprobe로 지속 시간, 해상도 및 컨테이너를 검사합니다. -
edgespeak_transcribe_file을 한 번 호출합니다:{ "path": "/절대/경로/소스-미디어", "timestamps": "word", "start_margin": 0, "end_margin": 0 }사용자가 다른 자막 길이를 요청하는 경우에만
min_chars/max_chars를 추가합니다. 사용자가 모델을 지명하는 경우에만model을 추가합니다. 지역성이 중요한 경우edgespeak_list_models를 검사하고 동의 없이 원격 모델을 선택하지 마세요. -
성공적인 단어 타임스탬프 전사 후에
edgespeak_align을 호출하지 마세요. 이 요청은 이미 EdgeSpeak의 인라인 로컬 강제 정렬 경로를 실행하고segments[].words[]를 반환합니다. -
긴 MCP 응답의 경우
artifact_json_path를 사용하세요. 인라인 응답의 경우result객체를 JSON으로 저장합니다. 변환기는 직접 전사 JSON 또는result가 포함된 래퍼를 모두 허용합니다. -
모든 시간이 지정된 세그먼트에서 비어 있지 않은 단어 타이밍을 요구합니다. 단어 타이밍을 임의로 만들거나 조용히 세그먼트 타이밍으로 대체하지 마세요.
사용자가 외부 최종 대본을 제공했거나 ASR 텍스트를 실질적으로 편집한 경우에만 edgespeak_align을 사용하세요. 정렬은 최종 단어 시퀀스를 사용해야 하며, 편집 후 오래된 타임스탬프를 유지하지 마세요.
텍스트를 배치할 수 없는 정렬은 빈 결과가 아닌 오류입니다: edgespeak_align은 isError: true와 함께 JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}}를 반환하고 단어가 없습니다(CLI는 동일한 코드와 객체를 error: alignment_failed: 또는 error: alignment_search_budget_exceeded:로 시작하는 stderr 줄에 출력하고 0이 아닌 종료 코드로 종료합니다). alignment 객체에서만 결정합니다:
alignment.retry_recommended: true→"search_effort": "extended"(CLI:--search-effort extended)를 사용하여edgespeak_align을 한 번 더 호출합니다. 더 넓게 검색하고 느리게 실행되며 추가 메모리를 사용합니다. 사용자에게 알릴 때alignment.estimated_extra_bytes를 인용하세요.- 그렇지 않거나
alignment_search_budget_exceeded인 경우 동일한 호출을 재시도하지 마세요. 대본이 이 미디어와 일치하는지 확인하거나 더 짧은 클립을 정렬하세요. 전체 코드 및 필드 목록은edgespeak-align을 참조하세요.
실패한 정렬에서 가라오케 큐를 만들지 마세요: 균등하게 간격이 지정된 단어, 세그먼트 타이밍 폴백, 편집 전 대본에서 가져온 타이밍 모두 금지합니다.
요구 사항
- 번들 스크립트에는 Node.js 18 이상이 필요합니다.
libass로 빌드된 FFmpeg와ffprobe— PATH에 있어야 하는 별도의 실행 파일입니다. 모든 미리보기와 모든 번은ass필터를 거치므로 libass 없는 FFmpeg는 선택한 프리셋에 관계없이No such filter: 'ass'오류로 실패합니다. MP4/MOV/MKV/TS로 번하려면 추가로libx264가 필요합니다. WebM은libvpx와libopus가 필요합니다. Homebrew 및 주요 배포판 패키지에는 이 모든 것이 포함되어 있습니다.- 전사를 위한
edgespeak-cli(또는 EdgeSpeak 앱)는 macOS Apple Silicon, Linux x86_64 및 Windows x64에서 실행됩니다. Windows에서는 CLI를 제공하는 EdgeSpeak 데스크톱 앱을 설치하세요. macOS 및 Linux에서는 사용자에게 https://edgespeak.com/docs/cli#install의 독립 실행형 설치 프로그램을 안내하세요(데스크톱 앱 필요 없음, Linux에서는 NVIDIA GPU를 자동 감지하고 CUDA 지원 런타임을 설치합니다). 사용자가 설치 프로그램을 실행합니다. 직접 실행하지 마세요. 머리말의minCliVersion은 이 스킬이 작성된 가장 오래된 CLI입니다.edgespeak-cli --version이 더 오래되었거나--help에서 문서화된 플래그가 누락된 경우edgespeak-cli update를 실행하세요.
누락된 종속성으로 인해 실행이 실패하면 재시도하는 대신 어떤 검사가 실패했는지 보고하세요:
node --version # v18+
ffprobe -version # ffmpeg와 함께 존재해야 함
ffmpeg -filters | grep -w ass # ASS 렌더러(libass)
ffmpeg -encoders | grep -w libx264 # H.264 출력
ASS 생성 및 미리보기
선택한 프리셋을 생성합니다:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /output/source.karaoke.ass \
--style classic \
--title "소스 제목"
선택지를 제시하려면 실제 소스의 활성 큐 하나에 모든 프리셋을 렌더링합니다. 이것은 특별한 경우가 아닌 기본 경로이며, 생성하는 모든 PNG는 표시되어야 합니다:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /output/source.karaoke.ass \
--style classic \
--preview-media /path/to/source-video \
--preview-dir /output/source.karaoke-previews
다른 프레임이 더 대표적인 경우 --preview-at <초>를 사용하고, 소스가 밝은 장면과 어두운 장면을 혼합하는 경우 다른 타임스탬프로 두 번 실행합니다. --list-styles로 프리셋을 나열합니다. --font, --font-size, --margin-v, --primary, --secondary, --outline, --back으로 미세 조정합니다. ASS 색상은 &HAABBGGRR을 사용합니다. 스크립트는 EdgeSpeak 세그먼트 경계를 유지하고 정렬된 지속 시간/갭만 \kf / \k 태그에 매핑합니다.
단어 사이의 간격은 단어당 공백이 아닌 큐 자체의 text에서 비롯됩니다. 강제 정렬은 구두점을 뒤따르는 단어에 첨부하므로 모든 words[] 항목은 text의 하위 문자열이며 위치는 앞으로만 이동합니다. 생성기는 text를 한 번 순회하며 두 단어 사이에 실제로 있는 것을 재사용합니다. 이것이 high-performance를 하이픈으로 유지하고(정렬이 high와 performance로 분할하며 하이픈은 어느 쪽에도 속하지 않음) CJK를 本地转录 대신 本 地 转 录으로 렌더링하는 것을 방지합니다. 단어를 text에서 찾을 수 없는 경우 생성기는 추측하는 대신 단일 공백으로 폴백합니다.
이중 언어 가라오케
대본이 모든 세그먼트에 translation을 가지고 있는 경우 — edgespeak-translate가 작성하는 내용 — 생성기는 큐당 두 줄을 내보내며 추가 플래그가 필요하지 않습니다:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.zh.json \
-o /output/source.karaoke.ass --style boxed
두 줄은 \N으로 구분된 하나의 Dialogue 이벤트에 있으므로 ASS는 공유 여백에서 단일 블록으로 쌓습니다. 두 개의 별도 이벤트는 각각 해당 여백에 고정되어 겹칩니다.
--layout translation-top(기본값)은 번역을 소스 위에 배치합니다.source-top은 이를 뒤집어 소스 언어로 따라 읽는 시청자를 위한 것입니다. **위쪽 줄은 프리셋 크기로 렌더링되고 아래쪽 줄은 72%**로 렌더링되므로 어느 쪽이든 눈이 기본 언어에 먼저 닿습니다.--layout source-only는 번역을 무시하고 단일 언어 파일을 생성합니다.- 소스 줄만 스윕합니다. 단어 타이밍은 소스 오디오를 설명하므로 번역에는
\k태그가 없습니다. 전체 큐에 대해 일반 채우기를 유지합니다. 큐 지속 시간을 번역의 문자에 분배하는 것은 임의로 생성된 타이밍이 될 것입니다. 추가하지 마세요. 실제 대상 언어 단어 타이밍을 원하면 음성 합성 스킬(설치된 경우)로 번역을 음성화하고 해당 오디오를 정렬하세요.
글꼴은 선택 사항이 아닙니다 — 두 줄 모두
libass는 브라우저처럼 글리프당 글꼴을 대체하지 않습니다. 라틴 스타일 글꼴의 CJK 텍스트는 빈 상자로 렌더링됩니다. 조용히, 번 전체를 통틀어서. 모든 프리셋에는 라틴 글꼴이 포함되어 있으므로 생성기는 프리셋을 상속하는 대신 스크립트로 선택합니다. 이는 소스 줄에도 적용되며 번역뿐만이 아닙니다. --font 없이 중국어 대본은 그렇지 않으면 상자 행으로 번될 것입니다.
- 스크립트는 줄 자체의 텍스트에서 감지되고
fc-match :lang=<태그>를 통해 일치되며 단일 ASCII 패밀리 별칭을 사용합니다(별칭 목록은 쉼표로 구분된 ASS 스타일 행을 깨뜨립니다). --font <이름>(소스) 및--translation-font <이름>(번역)이 이를 재정의하며,fc-list에서 해당 글꼴이 감지된 언어를 지원하지 않는다고 표시하면 거부됩니다. 다른 라틴 글꼴을 선택하여 오류를 우회하지 마세요.fc-list :lang=zh-cn family로 스크립트를 다루는 글꼴을 확인하세요.- 라틴 텍스트는 프리셋 글꼴을 그대로 유지합니다. 프리셋이 스크립트를 다루지 못할 때만 교체가 발생합니다.
- fontconfig 없이 자동 선택은 큰 오류를 내며 실패합니다. 글꼴을 명시적으로 전달하세요. 실행은 적용 여부를 확인할 수 없을 때
source_font_verified: false/translation_font_verified: false를 보고하므로 글꼴이 괜찮다고 주장하지 말고 그 주의 사항을 보고하세요. - 소스가 라틴 문자가 아닌 경우 실행은
source_font/source_script를 보고합니다.
부분적으로 번역된 대본은 완전히 거부됩니다. 이는 번역 단계가 조기에 중단되었음을 의미하며, 나머지 부분에 대해 소스 전용 큐를 내보내면 미완성 파일을 완성된 것으로 전달하는 것입니다.
하드 자막 번
소스에 비디오가 있고 사용자가 하드 자막을 원하는 경우:
node <skill-dir>/scripts/render-hardsub.mjs \
/path/to/source-video \
/output/source.karaoke.ass
기본 --format source는 실용적일 때 소스 컨테이너를 유지합니다:
- MP4/M4V/MOV -> 동일한 확장자, H.264/AAC.
- MKV -> H.264 및 복사된 오디오가 포함된 MKV.
- WebM -> VP9/Opus가 포함된 WebM.
- TS/M2TS -> 동일한 확장자, H.264/AAC.
- 지원되지 않거나 모호한 소스 확장자 ->
container_fallback: true로 보고되는 MKV 폴백.
하드 자막은 항상 비디오 재인코딩이 필요합니다. 컨테이너를 유지한다고 해서 소스 비디오 코덱을 복사하는 것은 아닙니다. 사용자가 다른 전달 형식을 요청하는 경우에만 --format mp4|mov|mkv|webm 또는 명시적인 -o를 사용하세요. 승인 없이 --overwrite를 사용하지 마세요.
소스 비트레이트 일치
고정 품질로 재인코딩하면 소스의 비트레이트를 무시하며 그 차이는 클 수 있습니다. CRF 21로 번을 1.5Mbps의 가벼운 AV1 파일에 적용하면 4.2Mbps H.264 복사본이 생성됩니다. 소스 비트레이트의 2.8배, 거의 3배의 파일 크기로 눈에 띄는 이득이 없습니다. 따라서 스크립트는 소스를 프로빙하고 비트레이트에서 -maxrate / -bufsize 상한을 도출하며, 출력 코덱이 덜 효율적인 정도(비슷한 품질을 위해 H.264는 AV1 비트레이트의 약 1.6배 필요)에 따라 조정됩니다. 품질은 여전히 CRF에서 제공됩니다. 상한은 소스를 초과하는 것을 방지할 뿐입니다.
이것은 x264 대상에 대해 자동입니다. .webm 프로필이 일정 품질 모드에 대해 -b:v 0을 고정하므로 VP9/WebM은 그대로 둡니다. 보고서에는 source_video_bitrate, video_bitrate 및 bitrate_cap 결정이 포함됩니다. 결과를 보고할 때 처음 두 개를 비교하세요.
사용자가 특정 비트레이트 또는 품질 수준을 요청하는 경우에만 재정의하세요:
--crf <n>은 품질 대상을 설정합니다(낮을수록 좋으며 H.264의 기본값은 21).--maxrate <비트레이트>는 도출된 상한을 대체합니다(예:--maxrate 4M).--maxrate none은 캡을 완전히 비활성화하고 일반 CRF 동작을 복원합니다.
비트레이트는 또한 파일 크기를 위한 레버입니다. 사용자가 출력 크기에 반대하는 경우 변경을 제안하기 전에 소스 비트레이트와 출력 비트레이트를 인용하고, 평면 일러스트레이션이나 화면 녹화 영상은 실사 영화보다 훨씬 더 강하게 압축된다는 점을 기억하세요. 자막 텍스트 자체는 CRF 28에서도 선명하게 유지되므로 결코 제약이 아닙니다.
CLI 폴백
MCP가 작업을 수행할 수 없을 때마다 edgespeak-cli로 폴백하세요. MCP 서버 자체가 가동 중이지만 도구가 실패하는 경우를 포함합니다. 가장 일반적인 경우: 데스크톱 앱이 실행되고 있지 않아 모든 EdgeSpeak MCP 도구가 runtime_error: could not reach gateway를 반환합니다. 이것은 손상된 설치가 아니며 재시도할 대상이 아닙니다. 장기 실행 MCP 서버는 의도적으로 자체 엔진을 시작하지 않습니다(상주 서버는 ...