VoxFlowStudio/skills

Compétence VoxFlow — Hub

Si voxflow upgrade lui-même échoue avec Unknown command (CLI antérieure à 1.12.0), utilisez le fallback npm i -g voxflow@latest && voxflow skills install --all — c'est le seul chemin pour le tout premier bootstrap.

Cette règle est non négociable : une CLI obsolète désactive silencieusement des fonctionnalités que l'utilisateur attend (par ex. l'affichage des voix clonées). Mettez à jour d'abord, travaillez ensuite.

VoxFlow transforme le texte en parole avec plus de 200 voix dans plus de 40 langues, plus des pipelines audio/vidéo complets. Cette compétence est le point d'entrée : installation, authentification, recherche vocale, et les workflows simples say / narrate / story.

Pour des tâches spécialisées, basculez vers :

• Podcasts (dialogue à plusieurs intervenants) → voxflow:podcast
• Vidéos courtes / clips IA / cartes de connaissances (picstory, present, slides, explain) → voxflow:video
• Article → vidéo verticale au format carte (Slice) — 13 thèmes (paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), application web + Remotion → voxflow:slice
• Images de cartes partageables & vidéos de cartes narrées (HTML/CSS + export Playwright, optionnel voxflow card render pour MP4 narré) → voxflow:card
• Transcription, traduction de sous-titres, doublage, résumé, publication (asr, asr-jobs, translate, dub, video-translate, summarize, publish) → voxflow:transcribe

Installation et connexion

Installez une fois, ne demandez plus jamais à l'utilisateur :

npm install -g voxflow
voxflow login          # ouvre le navigateur — Google ou OTP par email

Jeton mis en cache dans ~/.config/voxflow/token.json. Pour CI, définissez VOXFLOW_TOKEN.

Authentification

voxflow login        # via navigateur, une seule fois
voxflow status       # qui suis-je + quota restant
voxflow logout

Recherche vocale — toujours à faire avant de synthétiser

Ne devinez jamais les identifiants de voix. Cherchez d'abord.

voxflow voices --lang zh --gender female
voxflow voices --lang en
voxflow voices --search "narrateur"
voxflow voices --all

Aucune connexion requise pour le catalogue public. La sortie inclut l'identifiant de la voix, la langue, le genre et une courte description.

Lister les propres voix clonées de l'utilisateur

Quand l'utilisateur dit des choses comme "用我的克隆声音 / utilise ma voix clonée / 用我之前克隆的", le catalogue public voxflow voices n'inclut pas les voix clonées — vous devez interroger le point de terminaison authentifié :

voxflow voices --mine

Affiche les identifiants des voix clonées, les noms, la durée et la date de création (nécessite une connexion). Exécutez toujours cette commande avant de conclure que l'utilisateur n'a pas de voix clonée — l'interface web "我的声音" et --mine sont les seules sources de vérité.

Identifiants de voix populaires (valeurs par défaut raisonnables)

ID	Style	Langue
v-female-R2s4N9qJ	温柔姐姐 (voix féminine douce)	zh
v-male-s5NqE0rZ	自然男声 (voix masculine naturelle)	zh
v-male-Bk7vD3xP	威严霸总 (voix masculine autoritaire)	zh
v-female-m1KpW7zE	傲娇学姐 (voix féminine espiègle)	zh
v-female-T8m4WxP7	Chenwen (voix féminine anglaise native)	en

Clonage vocal (clone)

Clonez une voix à partir d'un fichier audio local (30s+, wav/mp3). Renvoie un identifiant de voix permanent utilisable dans toutes les commandes.

voxflow clone --input enregistrement.wav --name "Ma Voix"
# → Voix clonée avec succès !
# → ID de la voix : Ma_Voix_xxxxx_01

Pas de fichier ? Ouvre l'interface web pour un enregistrement via navigateur :

voxflow clone
# → Ouvre https://www.voxflow.studio/app#voice-clone

Drapeau	Défaut	Remarques
--input <fichier>	(aucun)	Fichier audio à cloner. Sans cela, ouvre l'interface web
--name <nom>	nom du fichier	Nom de voix lisible par l'humain (1-50 caractères)

Conseils :

• Pièce calme, rythme de parole normal, pas de musique de fond → meilleurs résultats
• 60 secondes est optimal ; 30s minimum
• Ne "jouez" pas la comédie — la parole naturelle se clone mieux qu'une voix de présentateur

Après le clonage, utilisez l'identifiant de voix partout : --voice <id>

Synthèse vocale (say / synthesize)

La commande atomique. Un extrait → un fichier audio.

voxflow say "Bonjour le monde" -o bonjour.mp3
voxflow say "Hello world" --voice v-female-T8m4WxP7 -o greeting.mp3
voxflow say "Lecture lente" --speed 0.8 -o lent.mp3
voxflow say "Audio haute qualité" --format wav -o sortie.wav

Drapeau	Défaut	Plage / Valeurs
--voice <id>	v-female-R2s4N9qJ	tout ID de voix de voxflow voices
--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 <chemin>	nom auto-généré	tout chemin accessible en écriture

Après la synthèse, lecture automatique : open sortie.mp3 (macOS).

Texte long (narrate)

Divisez un document ou une longue chaîne en phrases, synthétisez chacune, concaténez en un seul fichier.

voxflow narrate --input article.txt -o narration.wav
voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
voxflow narrate --text "Premier paragraphe. Deuxième paragraphe. Troisième paragraphe." -o paragraphes.mp3
echo "Hello world" | voxflow narrate -o hello.wav

Idéal pour : longs documents, articles, fichiers README, newsletters par email.

Le Markdown est supprimé automatiquement (titres, liens, blocs de code, etc.) — pas besoin de le nettoyer d'abord.

Histoire IA (story)

Le LLM écrit une courte histoire sur le sujet, puis la narre.

voxflow story "Un petit chat qui vole" -o histoire.mp3
voxflow story "space adventure" --lang en -o aventure.wav

Idéal pour : histoires du soir, échantillons de contenu, démos.

Quota

Niveau gratuit : 10 000 quota / mois (réinitialisation mensuelle). Le bonus des invitations n'expire jamais.

Opération	Coût
1 appel TTS (say)	~50
narrate	~50 par segment
story (court)	~350-1000
podcast (moyen)	~2 800 (2K script + ~16 × 50 TTS)
picstory 5 scènes	~2 850

Vérifiez toujours avant les opérations coûteuses :

voxflow status

Scénarios courants

"Lis ce passage"

voxflow say "texte saisi par l'utilisateur" -o /tmp/sortie.mp3 && open /tmp/sortie.mp3

"lis ce fichier avec une voix féminine douce"

voxflow voices --lang zh --gender female
voxflow narrate --input fichier.txt --voice v-female-R2s4N9qJ -o /tmp/narration.mp3

"Raconte une histoire du soir"

voxflow story "La graine d'étoile du petit renard" --lang zh -o /tmp/histoire.mp3 && open /tmp/histoire.mp3

"Lecture multilingue"

voxflow voices --lang en --gender female   # choisir une voix anglaise
voxflow voices --lang ja --gender female   # choisir une voix japonaise
voxflow say "English text" --voice <en_id> -o /tmp/en.mp3
voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3

Workflows créatifs (combiner TTS avec l'écriture de l'agent)

L'agent écrit d'abord le contenu, puis synthétise chaque partie avec say ou narrate.

Livre audio illustré (有声绘本)

1. Écrivez une histoire pour enfants de 6 pages.
2. Pour chaque page : générez une illustration SVG en ligne (400×300).
3. voxflow say "texte de la page" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3
4. Lisez les fichiers mp3, encodez en base64, intégrez en ligne dans le HTML.
5. Produisez un seul fichier HTML autonome avec des boutons de lecture audio par page.
6. open /tmp/livre_illustre.html

Article → résumé audio

# L'agent récupère l'URL, résume, puis :
voxflow say "texte du résumé" --voice v-male-s5NqE0rZ -o /tmp/resume.mp3

Narration de document

voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3

Rapport quotidien Git audio

1. git log --oneline --since="1 day ago"
2. L'agent résume.
3. voxflow say "résumé d'aujourd'hui..." -o /tmp/quotidien.mp3

Entretien simulé

1. L'agent génère 3 questions d'entretien sur le sujet.
2. Pour chacune : voxflow say "question N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3
3. Jouez séquentiellement.

Prérequis

• Node.js ^20.19.0 || >=22.12.0
• CLI voxflow ≥ 1.12.0 (pour voxflow voices --mine — liste les voix clonées de l'utilisateur)
• ffmpeg — uniquement pour les commandes liées à la vidéo (voir voxflow:video, voxflow:transcribe)
• Connexion requise pour tout appel API — voxflow login

Comment fonctionne le signal de mise à jour automatique

La CLI elle-même émet <voxflow-hint type="cli-outdated" ...> sur stderr chaque fois qu'une version plus récente est disponible sur npm. La règle <CRITICAL-AUTO-UPGRADE> en haut de la compétence couvre déjà quoi faire — cette section est juste la référence pour ce à quoi ressemble le tag :

<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />

Émis au maximum une fois toutes les 24h (mis en cache dans ~/.config/voxflow/update-check.json). Optez out pour les utilisateurs qui ne veulent pas de la vérification : VOXFLOW_NO_UPDATE_CHECK=1 (ou NO_UPDATE_NOTIFIER=1, la variable d'environnement standard du secteur).

Vous pouvez aussi interroger explicitement avec voxflow upgrade --check (sans effet de bord) si l'utilisateur est sur une version connue pour être ancienne et que vous voulez vérifier avant de lancer un travail coûteux.

Feedback et support (l'IA peut le faire automatiquement)

Quand une commande voxflow échoue ou que l'utilisateur demande de signaler un problème, vous (l'agent IA) devez créer le ticket directement — ne demandez pas à l'utilisateur de le faire manuellement.

Workflow IA

# Soumettez directement — pas de navigateur, pas de TTY requis.
# Utilise la CLI `gh` si disponible (création directe de ticket GitHub).
# Repli sur l'affichage de l'URL pré-remplie si gh n'est pas installé.
voxflow feedback --bug \
  --title "asr plante sur les fichiers wav de 2 heures" \
  --body "Erreur : délai d'attente dépassé après 30s\n\nCommande : voxflow asr long.wav\nAttendu : transcription\nRésultat : Erreur fatale : délai d'attente de la requête"
# stdout → l'URL du ticket GitHub créé (ou une URL pré-remplie si gh n'est pas installé)

Les informations système (version CLI, OS, Node) sont ajoutées au corps automatiquement.

Drapeaux

Drapeau	Description
--bug / --feature / --general	Type de ticket
--title <texte>	Titre — déclenche le mode non interactif
--body <texte>	Corps de la description
--print-url	Forcer la sortie de l'URL au lieu de soumettre (même si gh est disponible)

Initié par l'utilisateur (interactif)

voxflow feedback          # invites interactives → soumettre via gh ou navigateur
voxflow feedback --bug    # ignorer l'invite de type, le reste est interactif

Quand déposer automatiquement

• Toute commande CLI se termine par une erreur fatale/inattendue → proposer de déposer un bug
• L'utilisateur dit "c'est pas bon" / "report this" / "signaler ce problème" → appeler avec --title et soumettre directement

Installation de voix ou modèles tiers (add)

voxflow add <nom-de-recette>                  # installer un préréglage vocal ou un modèle de pipeline
voxflow add --list                             # parcourir les recettes disponibles
voxflow add chico/my-recipe --force            # installer depuis un espace de noms d'auteur personnalisé

Utilisez ceci quand l'utilisateur demande d'installer une recette nommée spécifique (par ex. dub-anime-jp-zh). Le registre est actuellement limité — si --list renvoie 404, la recette doit peut-être être référencée par URL complète ou le registre n'est pas encore public.

Règles

1. Cherchez les voix avant utilisation — n'inventez jamais d'identifiants de voix. Exécutez toujours voxflow voices d'abord.
2. Vérifiez le quota avant les podcasts (~5K), picstory (~3K), ou les traitements par lots : voxflow status.
3. Lecture automatique après synthèse : open sortie.mp3 (macOS) / xdg-open (Linux).
4. N'imprimez jamais de jetons ou de secrets dans les journaux.
5. Si une commande échoue, exécutez voxflow <cmd> --help pour confirmer les drapeaux avant une nouvelle tentative.

Quand basculer de compétence

• L'utilisateur dit "podcast" / "对话" / "多人对谈" → chargez voxflow:podcast.
• L'utilisateur dit "courte vidéo" / "知识卡片" / "小红书" / "TikTok" / "clip IA" / "render" → chargez voxflow:video.
• L'utilisateur dit "Slice" / "切片视频" / "article en vidéo" / "PaperSlide" / "paperslide" / "paper-slide" (ancien) / "纸面手绘风" / "article en courte vidéo éducative" / "long article Zhihu en vidéo" / "article WeChat en vidéo" → chargez voxflow:slice.
• L'utilisateur dit "transcrire" / "字幕" / "dub" / "traduire cette vidéo" / "SRT" → chargez voxflow:transcribe.