Communitygithub.com

EdgeSpeak Karaoke (자막 & 하드서브)

EdgeSpeak 한 번의 요청과 단어 수준 강제 정렬을 사용하여 단어 강조 가라오케 ASS 자막(선택적으로 번역된 두 번째 줄 포함 이중 언어)을 생성하고, 로컬 동영상에 하드코딩합니다.

EdgeSpeak Karaoke (자막 & 하드서브)란 무엇인가요?

이 스킬은 EdgeSpeak의 단어 수준 타임스탬프가 포함된 전사 결과를 활용하여, 각 단어가 강조되는 가라오케 스타일의 ASS(Advanced SubStation Alpha) 자막 파일을 생성합니다. 사용자는 `classic`, `minimal`, `boxed`, `high-contrast` 등 다양한 스타일 프리셋 중에서 선택할 수 있으며, 미리보기를 통해 실제 동영상 프레임에 스타일이 어떻게 적용될지 확인한 후 결정할 수 있습니다. 또한, 각 세그먼트에 번역이 포함된 전사 데이터를 사용하면 원본 언어와 번역 언어가 함께 표시되는 이중 언어 자막을 만들 수 있습니다. 최종적으로 생성된 ASS 자막을 FFmpeg를 사용하여 동영상에 하드코딩(영구적으로 입히기)할 수 있으며, 이 과정에서 원본 동영상의 비트레이트를 분석하여 적절한 품질을 유지합니다. 이 스킬은 macOS Apple Silicon, Linux x86_64, Windows x64에서 실행되는 EdgeSpeak CLI와 Node.js 18+, FFmpeg(libass 포함) 환경에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/tree/HEAD/skills/edgespeak-karaoke

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

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

문서

EdgeSpeak Karaoke

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 색상, 여백, 출력 형식 및 품질이 포함됩니다.

한 번에 전사 및 정렬

  1. 소스가 존재하는지 확인하고 ffprobe로 지속 시간, 해상도 및 컨테이너를 검사합니다.

  2. edgespeak_transcribe_file을 한 번 호출합니다:

    {
      "path": "/절대/경로/소스-미디어",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    min_chars / max_chars는 사용자가 다른 자막 길이를 요청하는 경우에만 추가하세요. model은 사용자가 모델 이름을 지정하는 경우에만 추가하세요. 지역성이 중요한 경우 edgespeak_list_models를 검사하고 동의 없이 원격 모델을 선택하지 마세요.

  3. 단어 타임스탬프가 있는 전사가 성공한 후에는 edgespeak_align을 호출하지 마세요. 이 요청은 이미 EdgeSpeak의 인라인 로컬 강제 정렬 경로를 실행하고 segments[].words[]를 반환합니다.

  4. 긴 MCP 응답의 경우 artifact_json_path를 사용하세요. 인라인 응답의 경우 result 객체를 JSON으로 저장하세요. 변환기는 직접 전사 JSON 또는 result로 래핑된 JSON을 모두 허용합니다.

  5. 모든 시간이 지정된 세그먼트에는 비어 있지 않은 단어 타이밍이 필요합니다. 단어 타이밍을 임의로 만들거나 자동으로 세그먼트 타이밍으로 대체하지 마세요.

edgespeak_align은 사용자가 외부 최종 전사본을 제공하거나 ASR 텍스트를 실질적으로 편집한 경우에만 사용하세요. 정렬은 최종 단어 시퀀스를 사용해야 하며, 편집 후에는 오래된 타임스탬프를 절대 유지하지 마세요.

요구 사항

  • 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에서는 EdgeSpeak 데스크탑 앱을 설치하세요(CLI가 함께 제공됨). macOS 및 Linux에서는 curl -fsSL https://edgespeak.com/install.sh | sh를 사용하세요(자체 포함, 데스크탑 앱 불필요, 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 "Source 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 <seconds>를 사용하고, 소스에 밝은 장면과 어두운 장면이 섞여 있는 경우 다른 타임스탬프로 두 번 실행하세요. 프리셋을 나열하려면 --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 태그가 없습니다. 전체 큐에 대해 일반 채우기를 유지합니다. 큐 지속 시간을 번역의 문자에 분배하는 것은 임의로 만든 타이밍입니다. 추가하지 마세요. 실제 대상 언어 단어 타이밍이 필요하면 edgespeak-broadcast로 합성하고 해당 오디오를 정렬하세요.

글꼴은 선택 사항이 아닙니다 — 두 줄 모두

libass는 브라우저처럼 글리프별로 글꼴을 대체하지 않습니다. 라틴 스타일 글꼴의 CJK 텍스트는 버닝 전체를 통해 자동으로 빈 상자로 렌더링됩니다. 모든 프리셋에는 라틴 글꼴이 포함되어 있으므로 생성기는 프리셋의 글꼴을 상속하는 대신 스크립트별로 선택합니다. 이는 번역 줄뿐만 아니라 소스 줄에도 적용됩니다. --font가 없는 중국어 전사본은 그렇지 않으면 상자 행으로 버닝됩니다.

  • 스크립트는 줄 자체 텍스트에서 감지되고 fc-match :lang=<tag>를 통해 일치되며, 단일 ASCII 패밀리 별칭을 사용합니다(별칭 목록은 쉼표로 구분된 ASS 스타일 행을 깨뜨림).
  • --font <name>(소스) 및 --translation-font <name>(번역)은 이를 재정의하며, 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와 함께 동일한 확장자.
  • 지원되지 않거나 모호한 소스 확장자 -> MKV 대체, container_fallback: true로 보고됨.

하드 자막은 항상 비디오 재인코딩이 필요합니다. 컨테이너를 보존한다고 해서 소스 비디오 코덱을 복사하는 것은 아닙니다. 사용자가 다른 전달 형식을 요청하는 경우에만 --format mp4|mov|mkv|webm 또는 명시적인 -o를 사용하세요. 승인을 받은 경우에만 --overwrite를 사용하세요.

소스 비트레이트 일치

고정 품질로 재인코딩하면 소스가 전송한 비트레이트를 무시하며, 그 차이는 클 수 있습니다. CRF 21로 버닝하여 1.5 Mbps AV1 파일에 넣으면 4.2 Mbps H.264 복사본이 생성됩니다 — 소스 비트레이트의 2.8배, 파일 크기의 거의 3배이며 눈에 띄는 이점은 없습니다. 따라서 스크립트는 소스를 검사하고 비트레이트에서 -maxrate / -bufsize 상한을 도출하며, 출력 코덱이 얼마나 덜 효율적인지에 따라 크기를 조정합니다(H.264는 비슷한 품질을 위해 AV1 비트레이트의 약 1.6배가 필요함). 품질은 여전히 CRF에서 나옵니다. 상한은 CRF가 소스 비트레이트를 초과하는 것을 막을 뿐입니다.

이것은 x264 대상에 대해 자동으로 수행됩니다. VP9/WebM은 .webm 프로필이 고정 품질 모드를 위해 -b:v 0을 고정하므로 수정되지 않습니다. 보고서에는 source_video_bitrate, video_bitrate 및 bitrate_cap 결정이 포함됩니다. 결과를 보고할 때 처음 두 개를 비교하세요.

사용자가 특정 비트레이트 또는 품질 수준을 요청하는 경우에만 재정의하세요:

  • --crf <n>은 품질 목표를 설정합니다(낮을수록 좋으며, H.264의 기본값은 21).
  • --maxrate <rate>는 파생된 상한을 대체합니다. 예: --maxrate 4M.
  • --maxrate none은 상한을 완전히 비활성화하고 일반 CRF 동작으로 되돌립니다.

비트레이트는 파일 크기를 위한 레버이기도 합니다. 사용자가 출력 크기에 이의를 제기하는 경우, 변경을 제안하기 전에 소스 비트레이트와 출력 비트레이트를 인용하고, 평평한 일러스트레이션이나 화면 녹화 영상은 라이브 액션보다 훨씬 더 압축이 잘 된다는 점을 기억하세요. 자막 텍스트 자체는 CRF 28에서도 선명하게 유지되므로 제약 요소가 아닙니다.

CLI 대체

MCP가 작업을 수행할 수 없을 때마다 — MCP 서버 자체는 실행 중이지만 그 도구가 실패하는 경우를 포함하여 edgespeak-cli로 대체하세요. 가장 흔한 경우: 데스크탑 앱이 실행 중이 아니므로 모든 EdgeSpeak MCP 도구가 runtime_error: could not reach gateway를 반환합니다. 이것은 설치가 손상된 것이 아니며 재시도해야 할 사항이 아닙니다. 오래 실행되는 MCP 서버는 의도적으로 자체 엔진을 시작하지 않습니다(엔진을 보유한 상주 서버는 사용자가 다음에 여는 앱과 충돌합니다). CLI에는 그러한 제약이 없습니다. 자체적으로 온디바이스 엔진을 시작합니다. 따라서 모든 EdgeSpeak MCP 도구의 could not reach gateway를 "지금 CLI를 사용하라"로 처리하고, 보고해야 할 실패로 처리하지 마세요.

edgespeak-cli 명령을 찾을 수 없는 경우, Windows x64에서는 EdgeSpeak 데스크탑 앱을 설치하고, macOS Apple Silicon 및 Linux x86_64에서는 curl -fsSL https://edgespeak.com/install.sh | sh를 사용하세요(자체 포함, 데스크탑 앱 불필요, Linux에서는 CUDA 자동 감지됨).

edgespeak-cli transcribe /path/to/source-media -o /output/transcript.json \
  --start-margin 0 --end-margin 0

CLI 전사 JSON에는 이미 segments[].words[]가 포함되어 있습니다. 동일한 transcribe 명령이 방금 생성한 텍스트에 대해 edgespeak-cli align을 실행하지 마세요. 번들된 스크립트(--overwrite 없이 기존 출력을 대체하는 것을 거부함)와 달리, edgespeak-cli -o는 기존 파일을 조용히 덮어씁니다. 전사본 경로가 이미 존재하는 경우 덮어쓰기 전에 사용자에게 확인하거나 새 경로를 선택하세요.

검증 및 보고

  • MCP 및 FFmpeg에 현실적인 wall-clock 예산을 부여하고, 정상적인 무음 처리를 방해하지 마세요.
  • start_margin 및 end_margin의 기본값은 0입니다. 전사 중에 추가 오디오가 필요한 경우(예: 장면 경계에서 단어가 잘리는 경우) 사용자에게 동의를 구하세요.
  • 생성된 모든 자막 파일에 대해 유효성 검사를 실행하세요: 비어 있지 않은 자막 수, ","가 없는 단어 타이밍

관련 스킬