VoxFlow Skill — Hub
voxflow upgrade 자체가 Unknown command 오류가 나면(CLI가 1.12.0보다 오래된 경우), npm i -g voxflow@latest && voxflow skills install --all로 대체하세요. 이것이 최초 부트스트랩의 유일한 방법입니다.
이 규칙은 협상 불가입니다: 오래된 CLI는 사용자가 기대하는 기능(예: 복제 음성 목록)을 조용히 비활성화합니다. 먼저 업그레이드하고, 그 다음에 작업하세요.
VoxFlow는 40개 이상의 언어, 200개 이상의 음성으로 텍스트를 음성으로 변환하며, 전체 오디오/비디오 파이프라인을 제공합니다. 이 스킬은 진입점입니다: 설치, 인증, 음성 검색, 그리고 간단한 say / narrate / story 워크플로우.
특화된 작업은 다음으로 전환하세요:
- 팟캐스트(다중 화자 대화) →
voxflow:podcast - 짧은 영상 / AI 클립 / 지식 카드(
picstory,present,slides,explain) →voxflow:video - 기사 → 세로형 카드 영상 (Slice) — 13개 테마(paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), 웹 앱 + Remotion →
voxflow:slice - 공유 가능한 카드 이미지 및 내레이션 카드 영상(HTML/CSS + Playwright 내보내기, 필요시
voxflow card render로 내레이션 MP4) →voxflow:card - 자막, 자막 번역, 더빙, 요약, 게시(
asr,asr-jobs,translate,dub,video-translate,summarize,publish) →voxflow:transcribe
설치 및 로그인
한 번 설치하고, 다시는 사용자에게 묻지 마세요:
npm install -g voxflow
voxflow login # 브라우저 열림 — Google 또는 이메일 OTP
토큰은 ~/.config/voxflow/token.json에 캐시됩니다. CI에서는 VOXFLOW_TOKEN을 설정하세요.
인증
voxflow login # 브라우저 기반, 일회성
voxflow status # 내 정보 + 남은 할당량
voxflow logout
음성 검색 — 합성 전에 항상 수행
음성 ID를 추측하지 마세요. 먼저 검색하세요.
voxflow voices --lang zh --gender female
voxflow voices --lang en
voxflow voices --search "narrator"
voxflow voices --all
공개 카탈로그는 로그인이 필요 없습니다. 출력에는 음성 ID, 언어, 성별, 간단한 설명이 포함됩니다.
사용자의 복제 음성 목록 보기
사용자가 "用我的克隆声音 / use my cloned voice / 用我之前克隆的"과 같이 말할 때, 공개 voxflow voices 카탈로그에는 복제 음성이 포함되지 않습니다 — 인증된 엔드포인트를 조회해야 합니다:
voxflow voices --mine
복제된 음성 ID, 이름, 길이, 생성 시간을 출력합니다(로그인 필요). 사용자에게 복제 음성이 없다고 결론짓기 전에 항상 실행하세요 — 웹 UI의 "我的声音" 탭과 --mine만이 유일한 진실 공급원입니다.
인기 음성 ID (적절한 기본값)
| ID | 스타일 | 언어 |
|---|---|---|
v-female-R2s4N9qJ | 온화한 누나 (gentle female) | zh |
v-male-s5NqE0rZ | 자연스러운 남성 (natural male) | zh |
v-male-Bk7vD3xP | 위엄 있는 총수 (authoritative male) | zh |
v-female-m1KpW7zE | 새침한 선배 (sassy female) | zh |
v-female-T8m4WxP7 | Chenwen (원어민 영어 여성) | en |
음성 복제 (clone)
로컬 오디오 파일(30초 이상, wav/mp3)에서 음성을 복제합니다. 모든 명령어에서 사용할 수 있는 영구 음성 ID를 반환합니다.
voxflow clone --input recording.wav --name "My Voice"
# → Voice cloned successfully!
# → Voice ID: My_Voice_xxxxx_01
파일이 없으면? 브라우저 기반 녹음을 위한 웹 UI가 열립니다:
voxflow clone
# → Opens https://www.voxflow.studio/app#voice-clone
| 플래그 | 기본값 | 설명 |
|---|---|---|
--input <file> | (없음) | 복제할 오디오 파일. 없으면 웹 UI 열림 |
--name <name> | 파일명 | 사람이 읽을 수 있는 음성 이름 (1-50자) |
팁:
- 조용한 방, 보통 말하기 속도, 배경 음악 없음 → 최상의 결과
- 60초가 최적; 최소 30초
- "연기"하지 마세요 — 방송 목소리보다 자연스러운 말투가 더 잘 복제됩니다
복제 후, 음성 ID를 어디서든 사용하세요: --voice <id>
텍스트 음성 변환 (say / synthesize)
기본 명령어. 한 조각 → 하나의 오디오 파일.
voxflow say "你好世界" -o hello.mp3
voxflow say "Hello world" --voice v-female-T8m4WxP7 -o greeting.mp3
voxflow say "慢速朗读" --speed 0.8 -o slow.mp3
voxflow say "高质量音频" --format wav -o output.wav
| 플래그 | 기본값 | 범위 / 값 |
|---|---|---|
--voice <id> | v-female-R2s4N9qJ | voxflow voices의 모든 음성 ID |
--format <fmt> | pcm | pcm (WAV), wav, mp3 |
--speed <n> | 1.0 | 0.5 – 2.0 |
--volume <n> | 1.0 | 0.1 – 2.0 |
--pitch <n> | 0 | -12 – 12 |
--output <path> | 자동 이름 지정 | 모든 쓰기 가능한 경로 |
합성 후 자동 재생: open output.mp3 (macOS).
긴 텍스트 (narrate)
문서나 긴 문자열을 문장으로 분할하고, 각각 합성한 후 하나의 파일로 연결합니다.
voxflow narrate --input article.txt -o narration.wav
voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
voxflow narrate --text "第一段。第二段。第三段。" -o paragraphs.mp3
echo "Hello world" | voxflow narrate -o hello.wav
적합한 대상: 긴 문서, 기사, README 파일, 이메일 뉴스레터.
Markdown은 자동으로 제거됩니다(제목, 링크, 코드 블록 등) — 미리 정리할 필요 없습니다.
AI 이야기 (story)
LLM이 주제에 대한 짧은 이야기를 작성한 후, 낭독합니다.
voxflow story "一只会飞的小猫" -o story.mp3
voxflow story "space adventure" --lang en -o adventure.wav
적합한 대상: 취침 이야기, 콘텐츠 샘플, 데모.
할당량
무료 티어: 월 10,000 할당량 (매월 초기화). 초대 보너스 풀은 만료되지 않습니다.
| 작업 | 비용 |
|---|---|
TTS 호출 1회 (say) | ~50 |
narrate | 세그먼트당 ~50 |
story (짧음) | ~350-1000 |
podcast (중간) | ~2,800 (2K 스크립트 + ~16 × 50 TTS) |
picstory 5장면 | ~2,850 |
비용이 많이 드는 작업 전에 항상 확인하세요:
voxflow status
일반적인 시나리오
"把这段话念出来"
voxflow say "사용자가 입력한 텍스트" -o /tmp/out.mp3 && open /tmp/out.mp3
"用温柔女声读这个文件"
voxflow voices --lang zh --gender female
voxflow narrate --input file.txt --voice v-female-R2s4N9qJ -o /tmp/narration.mp3
"讲个睡前故事"
voxflow story "작은 여우의 별 씨앗" --lang zh -o /tmp/bedtime.mp3 && open /tmp/bedtime.mp3
"다국어 낭독"
voxflow voices --lang en --gender female # 영어 음성 선택
voxflow voices --lang ja --gender female # 일본어 음성 선택
voxflow say "English text" --voice <en_id> -o /tmp/en.mp3
voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3
창의적인 워크플로우 (TTS와 에이전트의 글쓰기 결합)
에이전트가 먼저 콘텐츠를 작성한 후, 각 부분을 say 또는 narrate로 합성합니다.
오디오 동화책 (有声绘本)
- 6페이지 분량의 아동 이야기를 작성합니다.
- 각 페이지에 대해 인라인 SVG 일러스트레이션(400×300)을 생성합니다.
voxflow say "page text" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3- mp3 파일을 읽고, base64로 인코딩하여 HTML에 인라인으로 포함시킵니다.
- 페이지별 오디오 재생 버튼이 있는 단일 자체 포함 HTML 파일을 출력합니다.
open /tmp/storybook.html
기사 → 오디오 브리핑
# 에이전트가 URL을 가져와 요약한 후:
voxflow say "summary text" --voice v-male-s5NqE0rZ -o /tmp/briefing.mp3
문서 낭독
voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3
Git 일일 보고서 오디오
git log --oneline --since="1 day ago"- 에이전트가 요약합니다.
voxflow say "today's summary..." -o /tmp/daily.mp3
모의 인터뷰
- 에이전트가 주제에 대한 3개의 인터뷰 질문을 생성합니다.
- 각 질문에 대해:
voxflow say "question N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3 - 순차적으로 재생합니다.
사전 요구 사항
- Node.js
^20.19.0 || >=22.12.0 - voxflow CLI ≥ 1.12.0 (
voxflow voices --mine사용 시 — 사용자의 복제 음성 목록 표시) - ffmpeg — 비디오 관련 명령어에만 필요 (
voxflow:video,voxflow:transcribe참조) - 로그인 — API 호출에 필요:
voxflow login
자동 업그레이드 신호 작동 방식
CLI 자체가 npm에 더 새로운 버전이 있을 때 stderr에 <voxflow-hint type="cli-outdated" ...>를 출력합니다. 스킬 상단의 <CRITICAL-AUTO-UPGRADE> 규칙이 이미 수행할 작업을 다루고 있습니다 — 이 섹션은 태그가 어떻게 생겼는지에 대한 참고 자료입니다:
<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />
24시간에 최대 한 번만 출력됩니다(~/.config/voxflow/update-check.json에 캐시됨). 확인을 원하지 않는 사용자를 위해 비활성화: VOXFLOW_NO_UPDATE_CHECK=1 (또는 업계 표준 환경 변수 NO_UPDATE_NOTIFIER=1).
또한 사용자가 알려진 구버전을 사용 중이고 비용이 많이 드는 작업을 시작하기 전에 확인하려면 voxflow upgrade --check로 명시적으로 확인할 수 있습니다(부작용 없음).
피드백 및 지원 (AI가 자동으로 수행 가능)
voxflow 명령어가 실패하거나 사용자가 문제를 보고하도록 요청할 때, AI 에이전트가 직접 이슈를 등록해야 합니다 — 사용자에게 수동으로 하도록 요청하지 마세요.
AI 워크플로우
# 직접 제출 — 브라우저, TTY 필요 없음.
# `gh` CLI를 사용 가능하면 사용 (직접 GitHub 이슈 생성).
# gh가 설치되지 않은 경우 미리 채워진 URL을 출력하는 것으로 대체.
voxflow feedback --bug \
--title "asr crashes on 2-hour wav files" \
--body "Error: timeout after 30s\n\nCommand: voxflow asr long.wav\nExpected: transcript\nActual: Fatal error: request timeout"
# stdout → 생성된 GitHub 이슈 URL (또는 gh가 설치되지 않은 경우 미리 채워진 URL)
시스템 정보(CLI 버전, OS, Node)는 본문에 자동으로 추가됩니다.
플래그
| 플래그 | 설명 |
|---|---|
--bug / --feature / --general | 이슈 유형 |
--title <text> | 제목 — 비대화형 모드 활성화 |
--body <text> | 설명 본문 |
--print-url | 제출 대신 URL 출력 강제 (gh를 사용할 수 있어도) |
사용자 시작 (대화형)
voxflow feedback # 대화형 프롬프트 → gh 또는 브라우저를 통해 제출
voxflow feedback --bug # 유형 프롬프트 건너뛰고, 나머지는 대화형
자동으로 제출해야 하는 경우
- CLI 명령어가 치명적/예상치 못한 오류로 종료됨 → 버그 제출 제안
- 사용자가 "这个不好用" / "report this" / "提个 issue"라고 말함 →
--title과 함께 호출하여 직접 제출
타사 음성 또는 템플릿 설치 (add)
voxflow add <recipe-name> # 음성 프리셋 또는 파이프라인 템플릿 설치
voxflow add --list # 사용 가능한 레시피 탐색
voxflow add chico/my-recipe --force # 사용자 정의 작성자 네임스페이스에서 설치
사용자가 특정 이름의 레시피(예: dub-anime-jp-zh)를 설치하도록 요청할 때 사용하세요. 레지스트리는 현재 제한적입니다 — --list가 404를 반환하면, 레시피를 전체 URL로 참조해야 하거나 레지스트리가 아직 공개되지 않았을 수 있습니다.
규칙
- 사용 전에 음성 검색 — 음성 ID를 절대 추측하지 마세요. 항상
voxflow voices를 먼저 실행하세요. - 할당량 확인 — 팟캐스트(~5K), picstory(~3K) 또는 배치 작업 전:
voxflow status. - 합성 후 자동 재생:
open output.mp3(macOS) /xdg-open(Linux). - 토큰이나 비밀을 로그에 절대 출력하지 마세요.
- 명령어가 실패하면, 재시도 전에
voxflow <cmd> --help로 플래그를 확인하세요.
스킬 전환 시기
- 사용자가 "podcast" / "对话" / "多人对谈"이라고 말함 →
voxflow:podcast로드. - 사용자가 "short video" / "知识卡片" / "小红书" / "TikTok" / "AI clip" / "render"라고 말함 →
voxflow:video로드. - 사용자가 "Slice" / "切片视频" / "文章转视频" / "PaperSlide" / "paperslide" / "paper-slide" (레거시) / "纸面手绘风" / "文章转知识短视频" / "知乎长文转视频" / "公众号转视频"이라고 말함 →
voxflow:slice로드. - 사용자가 "transcribe" / "字幕" / "dub" / "translate this video" / "SRT"라고 말함 →
voxflow:transcribe로드.