신경 음성 나레이션
경로:
${CLAUDE_PLUGIN_ROOT}는 이 플러그인의 루트입니다. 변수가 정의되지 않은 경우, 루트는 이 스킬의 "Base directory"보다 두 폴더 위에 있습니다(<raiz>/skills/<skill>). 스킬이~/.claude/skills에 복사된 경우${CLAUDE_PLUGIN_ROOT}/skills대신~/.claude/skills를 사용하세요.
스크립트: ${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py. pip install edge-tts와
인터넷이 필요합니다: 텍스트는 Microsoft의 음성 서비스(무료, 키 불필요)로 전송됩니다.
사용자가 외부로 보내고 싶지 않은 내용은 대본에 넣지 마세요.
사용법
N=${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py
python $N <pasta> # audio/cena01.mp3 ... + cena01.json (단어 시간)
python $N <pasta> --mostrar # 발음 교체가 적용된 텍스트 표시 (생성하지 않음)
python $N <pasta> --so 3 7 # 장면 3과 7만 다시 생성
python $N <pasta> --tempos 3 # " 2.41s chave" ... 애니메이션 동기화용
python $N <pasta> --voz pt-BR-FranciscaNeural --rate +0%
python $N --vozes # 포르투갈어 음성 목록 표시
입력: <pasta>/roteiro.json, 문자열 리스트 (장면당 한 마디). 음성과 속도는
video.json ("voz", "rate")에 저장할 수 있습니다. 기본값: pt-BR-AntonioNeural, +8%.
단일 발화 (인트로, 알림, 메시지, 음성 테스트), 폴더나 대본 없음:
python $N --texto "안녕하세요! 오늘 주제는 Docker입니다." --saida C:/tmp/vinheta.mp3
python $N --texto "..." --saida C:/tmp/f.mp3 --voz pt-BR-FranciscaNeural --rate +0%
기본 발음 맵도 여기에 적용됩니다. 여러 개의 단일 발화는 roteiro.json이 있는 폴더를 사용하는 것이 좋습니다: 발화당 하나의 MP3가 생성됩니다.
유용한 PT-BR 음성: pt-BR-AntonioNeural (남성, 영상용), pt-BR-FranciscaNeural (여성),
pt-BR-ThalitaMultilingualNeural (여성, 영어 용어 처리에 더 좋음). 전체 목록: --vozes.
포르투갈(pt-PT-...) 및 다른 언어의 음성도 있습니다.
말하기 위한 글쓰기
대본은 기계가 읽습니다. 쓰는 대로가 아니라 말하는 대로 작성하세요:
| 화면 / 문서에서 | 대본에서 |
|---|---|
| 1995 | mil novecentos e noventa e cinco |
| porta 22 | porta vinte e dois |
| SCP, AWS (철자된 약어) | S C P, A W S (글자 분리) |
git push -u origin main | git push, traço u, origin main |
feat/login | feat barra login |
.gitignore, .env | ponto gitignore, ponto env |
~/.ssh/known_hosts | o arquivo known hosts |
<, >, = | menos de, mais de, igual a |
- 짧은 문장. 쉼표는 쉼이 됩니다: 리듬을 주기 위해 사용하세요 ("Conexão, troca de chaves, e autenticação.").
- 대화체 어조: "bora entender", "sabe aquela...?", "e o melhor:", "resumindo:".
- 장면당 25–45 단어 (+8%에서 10–16초).
- 괄호와 대시는 피하세요: 음성이 처리하는 방법을 모릅니다.
영어 용어 발음
PT-BR 음성은 영어를 포르투갈어로 읽습니다. 교정은 용어를 올바르게 들리는 표기로 바꾸는 것입니다. 오디오에만 적용됩니다 (대본과 화면은 원래 단어를 유지).
- ~70개의 개발 용어가 포함된 기본 맵:
scripts/pronuncia_base.json(git, commit, push, GitHub, branch, Docker, deploy, API, JSON, frontend, Python, npm...). - 프로젝트 용어:
<pasta>/pronuncia.json, 동일한 형식. 기본 맵을 덮어씁니다. 기본 맵의 교체를 비활성화하려면 용어를 자기 자신으로 매핑하세요:{"status": "status"}. - 교체는 전체 단어 단위로 이루어지며, 대소문자를 구분하지 않으며, 더 긴 용어가 먼저 교체됩니다 ("Pull Request"가 "pull"보다 먼저).
올바른 표기 찾는 방법:
- 브라질 사람이 큰 소리로 읽는 방식으로 쓰되, 강세 음절에 악센트를 표시하세요: commit → "comít", push → "púch", GitHub → "guít-râb", release → "rilís", cache → "kéch".
- 하이픈을 사용하여 부분을 구분하세요: "és-és-êitch" (SSH), "ci-él-ái" (CLI).
- 해당 장면만 생성하고(
--so N), 듣고 조정하세요. 사용자가 잘못 들렸다고 말하면 프로젝트의pronuncia.json에서 수정하세요. 일반적인 개발 용어라면pronuncia_base.json에도 추가하여 다음 영상에서 자동으로 수정되도록 하세요.
애니메이션과 동기화
각 audio/cenaNN.json에는 [{"t": 2.41, "palavra": "chave"}, ...]가 포함되어 있으며,
단위는 장면 시작부터의 초입니다. 이 t (또는 0.2초 전)를 단어를 나타내는 요소의
등장 시간으로 사용하세요. 단어는 이미 교체된 표기("comít")로 표시되는데, 이는 정상입니다.
일반적인 문제
| 증상 | 원인 / 해결책 |
|---|---|
No module named edge_tts | python -m pip install edge-tts |
| 연결 오류 / 403 | 인터넷 없음, 또는 Microsoft가 변경: pip install -U edge-tts |
| 음성이 너무 빠르거나 느림 | --rate +0% (느리게) 또는 +15% (빠르게) |
| 용어가 잘못 읽힘 | pronuncia.json (위 참조) |
| 장면이 너무 김 (> 20초) | 발화를 두 장면으로 나누기 |