Name: yanghhu/ai-voiceover
Author: Community

AI 음성 해설(AI Voiceover)

voiceover CLI(ai-voiceover-studio 패키지, Python 3.9+)를 사용하여 내레이션을 생성합니다.

설정 확인

voiceover --version — 없으면: pip install -e "<repo>[edge]" ([edge] = 무료 음성, [yaml] = voices.yaml).
voiceover doctor --json을 실행하고 fail로 보고된 항목을 수정하세요(절대로 키를 출력하지 않습니다).
엔진: 키가 없으면 무료 edge 엔진이 사용됩니다(인터넷 필요, 계정 불필요). MIRAGEA_API_KEY를 설정하면 기본 엔진이 Miragea로 전환됩니다(음성 복제, 표현력 좋은 모델 지원). OPENAI_API_KEY를 설정하면 --provider openai를 사용할 수 있습니다. 사용자에게 채팅에 키를 붙여넣도록 요청하지 말고, 절대 키를 에코하지 말며, 파일에 작성하지 마세요.
MP3 출력과 비디오에는 ffmpeg가 필요합니다(자막 내장(burned captions)을 위해 libass 필요).

스크립트 준비(Markdown 또는 TXT). 한 줄 또는 문단마다 하나의 화자 태그를 사용합니다:
```
[NARRATOR]: 시작하는 대사.
태그 없는 줄은 현재 화자의 대사가 계속됩니다.

[ALEX](tags=excited, speed=1.1): 다른 등장인물.
[pause 1]
```
제목, HTML 주석, 코드 블록, 표는 무시됩니다.
음성 선택(선택 사항). 음성 파일(voices file)이 없으면 각 화자마다 자동으로 다른 음성이 할당되며, 스크립트의 언어에 따라 선택됩니다. 음성을 선택하려면: voiceover voices --json (Edge 음성의 경우 --provider edge --filter en-GB를 추가하면 en-GB-SoniaNeural 같은 음성을 볼 수 있습니다. Miragea의 경우 voice_id = 배우 ID). 동일한 이름의 음성이 두 개 있으면 사용자에게 어떤 것을 사용할지 물어보세요. Miragea에서는 음성이 공개 참조 오디오 URL과 정확한 대본(reference_text)이 될 수도 있습니다. 사용자가 소유하거나 사용 권한이 있는 음성만 복제하세요.

사용자가 음성을 선택한 경우 voices.json 작성(키는 대문자):

{"NARRATOR": {"actor_id": "en-US-AndrewNeural"}, "ALEX": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}

드라이 런(오프라인, 화자와 타이밍 검증): voiceover script script.md -o out/ --dry-run --json
생성: voiceover script script.md [--voices voices.json] -o out/ --json 출력 파일: out/voiceover.mp3, out/voiceover.srt, out/manifest.json, out/segments/.
저장된 경로와 길이를 보고하세요. 명령이 종료 코드 0으로 종료되지 않으면 성공이라고 말하지 마세요.

한 줄: voiceover say "텍스트" [--voice <음성 ID|https://ref.wav>] [--ref-text "..."] [--lang en] -o line.mp3
페이스리스 비디오: voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] 자막은 기본적으로 영상에 내장(burn)됩니다. 세그먼트당 하나의 이미지를 사용하면 슬라이드 타이밍을 정확하게 지정할 수 있으며, --images 옵션이 없으면 그라데이션 배경이 사용됩니다. Shorts용으로는 --size 1080x1920 --style bold를 사용하세요.
음성 인식을 통한 자막(타이밍 대신, Miragea): --subtitles recognize 추가(API 호출 한 번 추가).
대기 시간 초과 후 작업 재개: voiceover task <task_id> --wait -o out.mp3

같은 명령을 다시 실행해도 안전합니다. 변경되지 않은 세그먼트는 캐시에서 가져오고 원격 요청은 멱등성 키를 사용합니다. 사용자가 새 테이크를 원할 때만 --fresh를 사용하세요.
대기 시간 초과 시, 보고된 task_id를 유지하고 voiceover task로 재개하세요. 재제출하지 마세요.
종료 코드: 0 정상, 1 제공자 작업 실패, 2 사용법/설정/API 오류. --json과 함께 사용하면 오류는 {"error": {"code", "message", "http_status", "retryable"}, "task_id"?} 형식입니다.
401: 키 거부 → 사용자가 키 변수를 확인합니다. 403: 계정에 API 액세스 권한이 없습니다. 429: 할당량/속도 제한 → 대기, 반복하지 마세요. 400: 텍스트/음성/속도/태그를 수정하세요.
proxy_unsupported (edge): 명령에 VOICEOVER_EDGE_PROXY를 설정하거나 HTTPS_PROXY를 해제하세요.
언어: Edge는 75개 언어를 지원합니다. Miragea는 중국어, 영어, 일본어, 한국어, 독일어, 프랑스어, 러시아어, 포르투갈어, 스페인어, 이탈리아어를 지원합니다(음성 복제 포함).