ytstudio
ytstudio est un outil en ligne de commande qui encapsule les API officielles YouTube Data et Analytics. Il existe pour faire à grande échelle ce que l'interface web de YouTube Studio oblige à cliquer un par un : modifications de métadonnées en lot, téléversements groupés, analyses scriptées, modération de commentaires, contrôle de diffusions en direct et opérations sur les playlists.
Cette compétence vous apprend à le piloter. Elle est agnostique : chaque instruction est une commande shell.
Deux choses à savoir d'abord
Ces deux règles s'appliquent à presque toutes les commandes et évitent les erreurs les plus courantes :
- Demandez du JSON. Les commandes de lecture affichent un tableau lisible par défaut. Passez
-o json(alias de--output json) pour obtenir une sortie analysable. Certaines commandes supportent aussi-o csv. Les commandes d'authentification et de configuration (init,login,status) n'ont pas de mode JSON. - La plupart des mutations sont en dry-run par défaut. Les commandes avec
--execute(videos update/search-replace/upload,livestreams schedule/updateet les écritures de playlists) prévisualisent ce qu'elles feraient et ne changent rien jusqu'à ce que vous réexécutiez la même commande avec--execute. Prévisualisez toujours, montrez la prévisualisation à l'utilisateur si elle est conséquente, puis réexécutez avec--execute.
Certaines écritures s'exécutent immédiatement car elles n'ont pas de --execute : modération et réponses aux commentaires (comments publish, comments reject, comments reply) et transitions de diffusions en direct (livestreams start, livestreams stop). Considérez-les comme à haut risque : confirmez l'intention avant de les exécuter.
Traitez les opérations d'écriture comme coûteuses et plus ou moins irréversibles : elles consomment du quota API (voir Quota) et agissent sur une chaîne réelle et publique.
Prérequis
Installation
ytstudio est sur PyPI et nécessite Python 3.12+. Privilégiez une installation isolée :
uv tool install ytstudio-cli # recommandé
# ou : pipx install ytstudio-cli
# ou : pip install --user ytstudio-cli
Le CLI s'installe sous ytstudio ; yts est un alias court pour le même point d'entrée. Vérifiez avec ytstudio --version.
Configuration OAuth unique
L'utilisateur doit fournir son propre client OAuth Google (un client "Application de bureau" créé dans la console Google Cloud avec les API YouTube Data v3 et YouTube Analytics activées). Avec le fichier JSON de secrets client téléchargé :
ytstudio init --client-secrets chemin/vers/client_secret.json
ytstudio login # ouvre un navigateur pour autoriser
ytstudio status # confirme la chaîne authentifiée
Sur une machine sans interface graphique, utilisez ytstudio login --headless : il affiche une URL à ouvrir dans n'importe quel navigateur, puis collez l'URL de redirection vers 127.0.0.1 qui a échoué.
Si ytstudio login échoue avec access_denied :
- Connectez-vous avec le compte Google propriétaire de la chaîne.
- Si l'application OAuth est toujours en "Test", ajoutez ce compte dans Google Cloud Console -> APIs & Services -> Écran de consentement OAuth -> Utilisateurs de test.
- Cliquez sur l'avertissement "Google n'a pas vérifié cette application" via Avancé -> Continuer.
- Approuvez tous les champs (lecture seule) demandés ; ne fermez pas l'onglet avant qu'il n'indique un succès.
Les identifiants sont stockés sous ~/.config/ytstudio-cli/ accessible uniquement par le propriétaire. Cette étape est unique par chaîne ; ne la relancez pas sauf si l'authentification est effectivement cassée.
Si ytstudio status rapporte qu'aucune chaîne n'est authentifiée, arrêtez-vous et demandez à l'utilisateur de terminer la configuration OAuth ; vous ne pouvez pas effectuer le consentement navigateur à sa place.
Chaînes multiples (profils)
Une installation peut contenir plusieurs chaînes, chacune étant un profil nommé. Les commandes agissent sur le profil actif sauf indication contraire :
ytstudio profile list # le profil actif est marqué
ytstudio profile use travail # change de profil actif
YTSTUDIO_PROFILE=travail ytstudio videos list # substitution pour une commande (script)
Utilisez la variable d'environnement YTSTUDIO_PROFILE=<nom> dans vos scripts pour ne jamais modifier la mauvaise chaîne en vous basant sur un état global.
Groupes de commandes
Voici le minimum nécessaire pour opérer chaque domaine. Pour la liste complète des drapeaux d'une commande, lisez references/reference.md à la demande plutôt que de deviner - ou exécutez ytstudio <groupe> <commande> --help.
videos - le cas d'usage principal
ytstudio videos list -n 100 -o json # téléversements récents, analysables
ytstudio videos list --scheduled # uniquement les publications futures
ytstudio videos show <id-video> -o json # métadonnées complètes d'une vidéo
ytstudio videos categories # identifiants de catégories assignables lors du téléversement
# Modification d'une seule vidéo (dry-run, puis --execute)
ytstudio videos update <id-video> --title "Nouveau titre"
ytstudio videos update <id-video> --tags un,deux,trois --execute
# Recherche-remplacement en masse sur toute la chaîne (dry-run, puis --execute)
ytstudio videos search-replace -s "2024" -r "2025" -f title
ytstudio videos search-replace -s 'saison \d' -r 'saison X' -f title --regex --execute
search-replace nécessite -s/--search, -r/--replace et -f/--field (title ou description) ; --limit limite le nombre de correspondances traitées (par défaut 10). Prévisualisez le dry-run, confirmez que l'ensemble des correspondances est celui voulu par l'utilisateur, puis ajoutez --execute.
videos upload - téléversement en lot à partir de fichiers YAML
ytstudio videos upload <chemin> associe chaque fichier vidéo à un fichier YAML compagnon du même nom, valide le tout et téléverse. Dry-run par défaut. Consultez assets/upload-sidecar.example.yaml pour le schéma du fichier sidecar (title, description, privacy, tags, category_id (obligatoire), langues, made_for_kids, publish_at optionnel).
ytstudio videos upload ./boîte_envoi # valide + prévisualise
ytstudio videos upload ./boîte_envoi --execute --max 3 # téléverse, limité pour le quota
Les téléversements sont reprisables : après chaque succès, le fichier sidecar est mis à jour avec video_id et uploaded_at, donc une réexécution ne retente que les sidecars qui n'ont pas de video_id. Utilisez --max pour limiter une exécution car les téléversements sont gourmands en quota (~1600 unités chacun).
analytics - rapports (lecture seule)
ytstudio analytics overview -d 28 -o json # aperçu de la chaîne, 28 derniers jours
ytstudio analytics video <id-video> -o json # analytiques par vidéo
ytstudio analytics metrics # noms de métriques découvrables
ytstudio analytics dimensions # noms de dimensions découvrables
# Requête personnalisée directe vers le point de terminaison reports.query de l'API Analytics :
ytstudio analytics query -m vues,likes -d jour --days 7 -o json
ytstudio analytics query -m vues -d pays --sort -vues -n 10 -o json
ytstudio analytics query -m vues -d insightTrafficSourceType -f video==<id> -o json
analytics query nécessite -m/--metrics ; -d/--dimensions, -f/--filter (clé==valeur, répétable), --sort (préfixez par - pour décroissant), -n/--limit et la plage de dates (--days ou -s/-e début/fin) sont optionnels. En cas de doute sur l'existence d'une métrique ou dimension, listez-les d'abord avec analytics metrics / analytics dimensions plutôt que de deviner les noms.
Pour -d month (et -d week), le CLI ajuste -s/-e à la limite requise par l'API YouTube Analytics (premier du mois), donc --days et les dates arbitraires fonctionnent simplement. La plage est inclusive aux deux extrémités, donc le mois de fin est le dernier mois souhaité, pas le mois suivant.
# 12 mois, juin 2025 à mai 2026 :
ytstudio analytics query -m vues -d month -s 2025-06-01 -e 2026-05-01
comments - modération
ytstudio comments list --status retenu -o json # la file de modération
ytstudio comments list -v <id-video> -n 50 -o json
ytstudio comments publish <id-commentaire> [<id-commentaire> ...] # approuve les retenus ; s'exécute immédiatement
ytstudio comments reject <id-commentaire> --ban # rejette (+ bannissement optionnel) ; s'exécute immédiatement
ytstudio comments reply <id-commentaire> -t "Merci !" # s'exécute immédiatement
publish/reject prennent un ou plusieurs identifiants de commentaires et s'exécutent immédiatement (pas de dry-run --execute). reply publie également immédiatement. Confirmez d'abord les identifiants et le texte exacts des commentaires. --ban sur reject bannit également l'auteur - utilisez-le uniquement si l'utilisateur demande explicitement un bannissement.
livestreams - cycle de vie des diffusions
ytstudio livestreams list -s à_venir -o json
ytstudio livestreams show <id-diffusion> --ingest -o json # URL d'ingestion ; clé masquée
ytstudio livestreams schedule -t "Titre" --scheduled-start 2026-07-01T19:00:00+02:00 --execute
ytstudio livestreams start <id-diffusion> --to testing # s'exécute immédiatement ; ou --to live
ytstudio livestreams stop <id-diffusion> # s'exécute immédiatement
ytstudio livestreams update <id-diffusion> --privacy non_listée --execute
schedule/update sont en dry-run jusqu'à --execute, mais start/stop s'exécutent immédiatement. livestreams show --show-key révèle la clé de diffusion - traitez toute sortie de ce type comme un secret et ne l'affichez jamais dans les logs ou le chat. start --to live publie pour les spectateurs ; privilégiez --to testing sauf si l'utilisateur souhaite passer en direct immédiatement.
playlists - opérations en masse
ytstudio playlists list -o json
ytstudio playlists items <id-playlist> -o json
ytstudio playlists create -t "Titre" --privacy non_listée --execute
ytstudio playlists add <id-playlist> --from-search "sujet" -n 20 --execute # la recherche coûte 100 unités/appel
ytstudio playlists add <id-playlist> -v <id-vidéo> -v <id-vidéo> --execute
ytstudio playlists reorder <id-playlist> --by vues --order desc --execute
ytstudio playlists remove <id-playlist> -v <id-vidéo> --execute
ytstudio playlists delete <id-playlist> --execute -y # -y saute la confirmation
Toutes les écritures de playlists sont en dry-run jusqu'à --execute. delete demande également une confirmation sauf si -y/--yes est passé ; n'ajoutez -y que lors d'une exécution non interactive et que l'utilisateur a confirmé la suppression.
Sensibilisation aux quotas
L'API YouTube Data a un budget par défaut de 10 000 unités/jour par projet, qui se réinitialise à minuit heure du Pacifique. Coûts approximatifs :
| Opération | Coût |
|---|---|
| Lecture (liste/affichage vidéos, commentaires, playlists ; analytiques) | ~1 unité |
| Écriture (mise à jour vidéo, modération commentaire, insertion/réorganisation playlist, programmation diffusion) | ~50 unités |
Recherche (playlists add --from-search) | ~100 unités/appel |
Téléversement (videos upload) | ~1600 unités |
Avant de lancer une grande opération en masse (par ex. search-replace sur des centaines de vidéos, ou plusieurs téléversements), estimez le coût et avertissez l'utilisateur si cela pourrait épuiser le quota journalier. Une réponse quotaExceeded (HTTP 403) signifie que le budget est épuisé jusqu'à la prochaine réinitialisation ; les tâches longues (videos upload) s'arrêtent proprement et rapportent le nombre de succès pour pouvoir reprendre plus tard.
Workflow recommandé pour un agent
- Confirmez une fois la configuration avec
ytstudio status(etprofile listsi plusieurs chaînes peuvent être en jeu). Sélectionnez la chaîne avecYTSTUDIO_PROFILE=dans les scripts. - Rassemblez l'état avec des commandes de lecture utilisant
-o jsonet analysez le résultat. - Pour toute modification, exécutez d'abord la commande sans
--execute, inspectez la prévisualisation et présentez-la à l'utilisateur lorsque la modification est conséquente ou en masse. - Réexécutez la même commande avec
--executepour appliquer. - Surveillez le quota pour les opérations en masse et les téléversements.
Lorsqu'un drapeau ou un comportement n'est pas clair, consultez references/reference.md ou --help plutôt que de supposer.