Communitygithub.com

VoxFlowSkill — Hub

사용자가 텍스트를 소리내어 읽어주기(TTS), VoxFlow 음성 검색, AI 이야기 샘플 듣기, VoxFlow 설치/인증/할당량 설정 등을 원할 때 사용하는 진입점 음성 도구 키트입니다. 팟캐스트는 voxflow:podcast, 짧은 영상/AI 클립은 voxflow:video, 기사-카드 릴(Slice)은 voxflow:slice, 공유 가능한 카드 이미지 또는 내레이션 카드 영상은 voxflow:card, 자막/더빙/자막 번역은 voxflow:transcribe를 사용하세요.

VoxFlowSkill — Hub란 무엇인가요?

VoxFlow Skill — Hub는 개발자와 AI 에이전트가 텍스트를 음성으로 변환(TTS)하는 핵심 기능을 제공하는 음성 도구 키트입니다. 40개 이상의 언어, 200개 이상의 음성을 지원하며, 간단한 명령어로 음성 합성, 긴 문서 낭독, AI 이야기 생성 등을 수행할 수 있습니다. 이 스킬은 설치 및 인증, 음성 검색, 기본 TTS, 낭독, 이야기, 음성 복제, 할당량 확인 등 모든 VoxFlow 작업의 진입점 역할을 합니다. CLI 도구(voxflow)를 통해 npm으로 설치하며, Node.js 20.19.0 이상 또는 22.12.0 이상이 필요합니다. 음성 합성 전에는 항상 `voxflow voices` 명령으로 음성을 검색해야 하며, 복제 음성은 `voxflow voices --mine`으로 조회합니다. 팟캐스트, 짧은 영상, 자막 등 특화 작업은 각각 전용 하위 스킬(voxflow:podcast, voxflow:video, voxflow:slice, voxflow:card, voxflow:transcribe)로 전환하여 사용합니다. CLI 버전이 오래된 경우 자동 업그레이드 신호를 감지하여 즉시 업그레이드해야 기능이 정상 작동합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VoxFlowStudio/skills/tree/HEAD/skills/hub

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

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

문서

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-T8m4WxP7Chenwen (원어민 영어 여성)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-R2s4N9qJvoxflow voices의 모든 음성 ID
--format <fmt>pcmpcm (WAV), wav, mp3
--speed <n>1.00.5 – 2.0
--volume <n>1.00.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로 합성합니다.

오디오 동화책 (有声绘本)

  1. 6페이지 분량의 아동 이야기를 작성합니다.
  2. 각 페이지에 대해 인라인 SVG 일러스트레이션(400×300)을 생성합니다.
  3. voxflow say "page text" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3
  4. mp3 파일을 읽고, base64로 인코딩하여 HTML에 인라인으로 포함시킵니다.
  5. 페이지별 오디오 재생 버튼이 있는 단일 자체 포함 HTML 파일을 출력합니다.
  6. 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 일일 보고서 오디오

  1. git log --oneline --since="1 day ago"
  2. 에이전트가 요약합니다.
  3. voxflow say "today's summary..." -o /tmp/daily.mp3

모의 인터뷰

  1. 에이전트가 주제에 대한 3개의 인터뷰 질문을 생성합니다.
  2. 각 질문에 대해: voxflow say "question N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3
  3. 순차적으로 재생합니다.

사전 요구 사항

  • 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로 참조해야 하거나 레지스트리가 아직 공개되지 않았을 수 있습니다.

규칙

  1. 사용 전에 음성 검색 — 음성 ID를 절대 추측하지 마세요. 항상 voxflow voices를 먼저 실행하세요.
  2. 할당량 확인 — 팟캐스트(~5K), picstory(~3K) 또는 배치 작업 전: voxflow status.
  3. 합성 후 자동 재생: open output.mp3 (macOS) / xdg-open (Linux).
  4. 토큰이나 비밀을 로그에 절대 출력하지 마세요.
  5. 명령어가 실패하면, 재시도 전에 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 로드.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

VoxFlowStudio/skills

Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces a narrated MP4 video from those cards via `voxflow card render` (per-card TTS + FFmpeg static-image clips with optional subtitle bar / intro+outro cards / BGM mix). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast.

VoxFlowStudio/skills

Use when the user wants to turn a long article / note / report into a vertical 1080×1920 card video — VoxFlow Slice. 13 themes — paper-slide (纸面), editorial-mag (编辑刊), bold-poster (大字海报), notion-card (Notion 卡), brutalist (粗野), glass-dark (玻璃夜), editorial-stencil (编辑·海报), broadsheet (财经刊), blueprint (蓝晒图), daisy-pastel (雏菊), showa-catalog (昭和目录), photo-feature (摄影刊), atmospheric (深夜刊). Triggers — Slice / slice video / 切片视频 / 文章转视频 / 知识卡片视频 / 抖音知识号 / 小红书图文转视频 / 知乎长文转视频 / 公众号转视频 / PaperSlide / paperslide / paper-slide (legacy name).

VoxFlowStudio/skills

Use when the user wants AI-generated short-form video — knowledge cards (picstory / 小红书 / TikTok / Reels), narrated explainers, presentations, AI clips, or slides — covering picstory, present, slides, explain, and image generation. For article-to-card reels (Slice — 13 themes including paper-slide), use voxflow:slice. For shareable HTML/CSS card images or narrated card MP4 videos (`voxflow card render`) use voxflow:card.

관련 스킬