Exporter des fichiers vers YouTube en ligne de commande
Vous pouvez envoyer une vidéo terminée depuis votre terminal avec les bibliothèques Python open source de Google. La CLI ci-dessous sélectionne un fichier local et des métadonnées JSON, vous invite à autoriser une chaîne et renvoie l’identifiant de la vidéo après acceptation de l’envoi par YouTube. Elle garde les vidéos privées et désactive les notifications aux abonnés.
Limites importantes de l’API YouTube
Cet exemple prévoit un envoi supervisé depuis Linux avec Bash et un navigateur sur la même machine. Il accepte un MP4 local non vide de 64 MiB maximum, avec un nom de fichier en UTF-8. Le fichier doit déjà être terminé et lisible ; le script ne valide ni ne transcode son contenu. Le délai total est de cinq minutes, autorisation et transfert compris : même un fichier inférieur à cette limite peut donc échouer avec une connexion lente.
Un envoi accepté doit encore être traité. La CLI demande uniquement
youtube.upload,
qui permet l’insertion. Elle ne demande pas les droits plus étendus nécessaires pour consulter les
vidéos privées ou les supprimer via l’API. Vérifiez ensuite l’identifiant renvoyé dans YouTube
Studio pour la chaîne sélectionnée et attendez la fin du traitement avant d’utiliser la vidéo.
Vérifiez le quota d’envoi actuel de votre projet dans Google Cloud. YouTube comptabilise les envois dans un quota distinct. Un délai entre les commandes ne renouvelle pas un quota quotidien. Cette configuration demande explicitement une visibilité privée, quels que soient les paramètres par défaut du projet ou du compte.
Installer les bibliothèques Python
Utilisez un interpréteur CPython 3.14 installé avec venv et pip disponibles.
L’interpréteur testé est la version 3.14.8 ; pour une nouvelle installation, utilisez le correctif de
sécurité actuel de la branche 3.14 maintenue, depuis les
téléchargements Python. Python 3.15 est plus récent, mais le
périmètre testé de ce guide est la version 3.14, que le
client API Google indique explicitement prendre en charge.
Exécutez ceci depuis le répertoire parent où vous souhaitez créer un répertoire
youtube-cli. Le sous-shell conserve votre répertoire courant et les options du
shell. Un répertoire existant est refusé. Si l’installation échoue, examinez l’erreur et le
répertoire partiel avant de choisir un nouvel emplacement ; les commandes ne suppriment pas les
fichiers existants.
(
set -eu
command -v python3.14 >/dev/null
mkdir youtube-cli
python3.14 -m venv youtube-cli/.venv
youtube-cli/.venv/bin/python -m pip --isolated install \
google-api-python-client==2.201.0 google-auth-oauthlib==1.5.0 \
google-auth==2.62.1 httplib2==0.32.1 requests==2.34.2
)
Ces versions de paquets ont été testées. Le client Google reçoit des correctifs et fournit l’API YouTube fondée sur la découverte. La petite couche de transport Requests ci-dessous rend le comportement des nouvelles tentatives explicite : une insertion échouée n’est jamais relancée automatiquement comme une autre insertion.
Configurer OAuth pour une application de bureau
Utilisez un compte Google propriétaire de la chaîne YouTube visée. Suivez la configuration OAuth pour une application de bureau de Google :
- Sélectionnez votre projet dans la Google Cloud Console et activez YouTube Data API v3.
- Configurez les informations de consentement et l’audience de l’application. Pour une application externe en phase de test, ajoutez votre compte Google comme utilisateur test.
- Créez un client OAuth avec le type d’application Desktop app.
Téléchargez son JSON sous le nom
youtube-cli/client_secrets.json. Ne l’incluez pas dans le contrôle de version. - Recherchez l’identifiant de la chaîne visée dans les
paramètres avancés du compte YouTube.
Utilisez cet identifiant
UC…dans la commande ci-dessous. Un nom d’utilisateur tel que@examplen’est pas un identifiant de chaîne.
Le programme utilise un port de bouclage aléatoire et PKCE. Il demande un nouveau consentement à chaque exécution, ne stocke aucun cache de jetons et vous demande de confirmer la chaîne avant toute insertion. Choisissez la chaîne visée pendant le parcours d’autorisation Google, y compris le bon compte de marque, le cas échéant. Saisir un identifiant ne sélectionne pas une chaîne : le compte autorisé détermine la destination. L’identifiant de chaîne renvoyé est vérifié après l’insertion ; une différence constitue un échec, mais une vidéo privée peut déjà avoir été créée dans l’autre chaîne.
Gestion des métadonnées vidéo
Enregistrez ceci sous le nom youtube-cli/metadata.json, en remplaçant le titre et la description.
Définissez madeForKids en fonction de votre audience réelle. Ces quatre clés
constituent l’interface complète des métadonnées ; les clés inconnues sont refusées. La
confidentialité et les notifications sont fixées dans le programme plutôt qu’héritées d’un fichier
annexe ou d’un paramètre par défaut d’un outil.
{
"title": "My command-line upload",
"description": "A completed local video.\nUploaded privately for review.",
"tags": ["demo", "command-line"],
"madeForKids": false
}
Enregistrer et exécuter l’outil de téléversement
Enregistrez le programme complet sous le nom youtube-cli/upload.py. Il lit le fichier sans
le modifier, ni modifier le fichier annexe de métadonnées. Les erreurs réseau après le début de
l’insertion sont traitées comme des résultats incertains. Le programme affiche l’identifiant
renvoyé sur stderr avant de vérifier les métadonnées de la réponse, afin que vous puissiez examiner
une éventuelle différence. Évitez les enregistrements partagés du terminal : l’URL d’autorisation
et le rappel font partie d’une connexion privée.
import argparse
import contextlib
import json
import logging
import os
import re
import signal
import stat
import sys
from urllib.parse import urlsplit
import httplib2
import requests
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.http import MediaIoBaseUpload
from requests.adapters import HTTPAdapter
UPLOAD_SCOPE = 'https://www.googleapis.com/auth/youtube.upload'
MAX_BYTES = 64 * 1024 * 1024
class UserError(Exception):
pass
def stop_at_deadline(*_):
raise UserError('The five-minute deadline expired')
class UploadTransport:
def __init__(self, credentials):
self.session = requests.Session()
self.session.trust_env = False
self.session.mount('https://', HTTPAdapter(max_retries=0))
credentials.apply(self.session.headers)
def request(self, uri, method='GET', body=None, headers=None, **_):
target = urlsplit(uri)
if (target.scheme != 'https' or target.hostname not in
('www.googleapis.com', 'youtube.googleapis.com') or
target.username is not None or target.port not in (None, 443)):
raise UserError('Unexpected upload destination')
response = self.session.request(
method, uri, data=body, headers=headers,
timeout=(10, 30), allow_redirects=False)
if 300 <= response.status_code < 400 and response.status_code != 308:
raise UserError('Upload redirect refused')
return (httplib2.Response(dict(response.headers,
status=str(response.status_code))),
response.content)
def close(self):
self.session.close()
class TimedFlow(InstalledAppFlow):
def fetch_token(self, **kwargs):
return super().fetch_token(timeout=(10, 30), **kwargs)
def authorize(config):
installed = config.get('installed', {})
if (installed.get('auth_uri') != 'https://accounts.google.com/o/oauth2/auth' or
installed.get('token_uri') != 'https://oauth2.googleapis.com/token'):
raise UserError('Use the downloaded Desktop client JSON')
flow = TimedFlow.from_client_config(
config, scopes=[UPLOAD_SCOPE], autogenerate_code_verifier=True)
flow.oauth2session.trust_env = False
flow.oauth2session.mount('https://', HTTPAdapter(max_retries=0))
def refuse_token_redirect(url, headers, request_kwargs):
return url, headers, dict(request_kwargs, allow_redirects=False)
flow.oauth2session.register_compliance_hook('access_token_request', refuse_token_redirect)
try:
if flow.oauth2session.token:
raise UserError('Expected a fresh authorization flow')
with contextlib.redirect_stdout(sys.stderr):
credentials = flow.run_local_server(
host='127.0.0.1', port=0, open_browser=False, timeout_seconds=180,
prompt='consent select_account', include_granted_scopes='false',
access_type='online')
with requests.Session() as check:
check.trust_env = False
response = check.get('https://oauth2.googleapis.com/tokeninfo',
params={'access_token': credentials.token},
timeout=(10, 30), allow_redirects=False)
if response.status_code != 200:
raise UserError('Could not check the new grant')
info = response.json()
if (info.get('aud') != installed['client_id'] or
set(info.get('scope', '').split()) != {UPLOAD_SCOPE} or
int(info.get('expires_in', 0)) < 600):
raise UserError('The new grant must be upload-only and unexpired')
return credentials
finally:
flow.oauth2session.close()
def read_metadata(filename):
with open(filename, encoding='utf-8') as source:
metadata = json.load(source)
if not isinstance(metadata, dict) or set(metadata) != {
'title', 'description', 'tags', 'madeForKids'}:
raise UserError('Metadata needs title, description, tags, and madeForKids only')
title, description, tags = (metadata[key] for key in ('title', 'description', 'tags'))
if not isinstance(title, str) or not title.strip() or len(title) > 100:
raise UserError('Title must contain 1–100 characters')
if not isinstance(description, str) or not isinstance(tags, list) or not all(
isinstance(tag, str) for tag in tags):
raise UserError('Description must be text and tags must be a list of strings')
if type(metadata['madeForKids']) is not bool:
raise UserError('madeForKids must be a JSON boolean')
return {'snippet': {'title': title, 'description': description, 'tags': tags},
'status': {'privacyStatus': 'private',
'selfDeclaredMadeForKids': metadata['madeForKids']}}
def main():
parser = argparse.ArgumentParser(description='Upload one private MP4; no automatic retry')
parser.add_argument('--file', required=True)
parser.add_argument('--metadata', required=True)
parser.add_argument('--channel-id', required=True)
parser.add_argument('--client-secrets', required=True,
help='Desktop JSON filename, or - for one private JSON line on stdin')
args = parser.parse_args()
if not re.fullmatch(r'UC[A-Za-z0-9_-]{22}', args.channel_id):
raise UserError('Expected a UC channel ID')
for filename in (args.file, args.metadata, args.client_secrets):
os.fsencode(filename).decode('utf-8', errors='strict')
body = read_metadata(args.metadata)
with open(args.file, 'rb') as media:
details = os.fstat(media.fileno())
if (not stat.S_ISREG(details.st_mode) or not 0 < details.st_size <= MAX_BYTES or
not args.file.lower().endswith('.mp4')):
raise UserError('Use a completed, nonempty MP4 of at most 64 MiB')
if args.client_secrets == '-':
config = json.loads(sys.stdin.readline())
else:
with open(args.client_secrets, encoding='utf-8') as source:
config = json.load(source)
credentials = authorize(config)
print(f'Confirm the channel selected in your browser: {args.channel_id}', file=sys.stderr)
print('Type that channel ID to insert the private video:', file=sys.stderr, flush=True)
if sys.stdin.readline().strip() != args.channel_id:
raise UserError('Channel confirmation did not match; no insert attempted')
transport = UploadTransport(credentials)
try:
youtube = build('youtube', 'v3', http=transport,
static_discovery=True, cache_discovery=False)
request = youtube.videos().insert(
part='snippet,status', body=body, notifySubscribers=False,
media_body=MediaIoBaseUpload(media, mimetype='video/mp4',
chunksize=8 * 1024 * 1024, resumable=True))
print('Insert starting; inspect the channel before retrying any failure.',
file=sys.stderr, flush=True)
result = None
while result is None:
_, result = request.next_chunk(num_retries=0)
video_id = result.get('id')
if not isinstance(video_id, str) or not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
raise UserError('YouTube did not return a native video ID')
print(f'Returned video ID: {video_id}', file=sys.stderr, flush=True)
if (result.get('snippet', {}).get('channelId') != args.channel_id or
result.get('snippet', {}).get('title') != body['snippet']['title'] or
result.get('status', {}).get('privacyStatus') != 'private'):
raise UserError('Returned metadata did not match; inspect the returned ID')
print(json.dumps({'id': video_id, 'channelId': args.channel_id,
'status': 'accepted_processing_unchecked'}), flush=True)
finally:
transport.close()
if __name__ == '__main__':
logging.disable(logging.CRITICAL)
signal.signal(signal.SIGALRM, stop_at_deadline)
signal.alarm(300)
try:
main()
except (Exception, KeyboardInterrupt) as error:
if isinstance(error, UserError):
print(str(error), file=sys.stderr)
print('Upload not confirmed. If insertion started, the video may exist. '
'Inspect your channel in YouTube Studio before another upload. '
'Check local files, metadata, authorization, and quota.', file=sys.stderr)
sys.exit(1)
finally:
signal.alarm(0)
Placez votre fichier terminé dans ./video.mp4 et remplacez
YOUR_CHANNEL_ID par l’identifiant de chaîne que vous avez noté. Exécutez ceci depuis
le même répertoire parent que la commande d’installation :
youtube-cli/.venv/bin/python youtube-cli/upload.py \
--file './video.mp4' \
--metadata youtube-cli/metadata.json \
--client-secrets youtube-cli/client_secrets.json \
--channel-id YOUR_CHANNEL_ID
Ouvrez le lien d’autorisation affiché dans votre navigateur local. Donnez votre consentement dans
les trois minutes, puis saisissez l’identifiant de la chaîne sélectionnée à l’invite du terminal.
En cas de succès, le seul résultat sur stdout est du JSON contenant un
id natif, le channelId correspondant et
"status": "accepted_processing_unchecked". Un code de sortie non nul, un identifiant manquant ou des métadonnées
non concordantes constituent un échec. Conservez l’identifiant avant de quitter votre terminal ;
le programme n’écrit aucun reçu d’envoi local.
Envoyer des fichiers supplémentaires
Pour plusieurs vidéos, exécutez la même commande une fois par fichier explicitement indiqué, avec
son fichier de métadonnées correspondant. Gardez les chemins entre guillemets, y compris les
espaces et les caractères de ponctuation du shell ; préfixez un nom de fichier commençant par un
trait d’union avec ./. Le programme ne recherche pas les fichiers par
motifs glob et ne déduit pas les titres des noms de fichiers. Chaque appel exige un nouveau
consentement dans le navigateur et une confirmation de la chaîne. Arrêtez-vous au premier échec et
examinez son résultat avant de lancer une autre insertion.
Intégration automatisée de l’envoi
Un programme producteur peut appeler cette CLI après avoir fermé un MP4 terminé, mais l’autorisation reste interactive. Ce n’est pas un planificateur sans supervision. Conserver des jetons d’actualisation et ajouter un registre persistant des tâches et identifiants nécessiterait une conception distincte. En particulier, n’encapsulez pas cette commande dans une boucle de nouvelles tentatives : perdre la réponse finale peut laisser une vidéo sur YouTube même si la commande signale un échec. Cet exemple ne conserve pas l’URL d’une session de transfert reprenable et ne la récupère pas après la fin du processus.
Résoudre les problèmes courants
Limites de transfert
Le plafond de 64 MiB est la limite de cet exemple, pas le maximum de la plateforme YouTube. La couche de transport Requests utilise des délais d’expiration de dix secondes pour la connexion et de 30 secondes pour la lecture de chaque requête, avec une alarme distincte de cinq minutes pour le processus, couvrant le consentement et le transfert. Elle n’a aucun limiteur de bande passante. Si le délai expire après le début de l’insertion, examinez la chaîne plutôt que de considérer cette expiration comme une preuve qu’aucun fichier n’a été envoyé.
Problèmes d’authentification
Utilisez les informations d’authentification d’une application de bureau et gardez le navigateur
sur la machine qui exécute la commande pour que son rappel de bouclage puisse atteindre le
processus à l’écoute. Si le consentement est refusé, vérifiez l’audience de l’application, l’accès
des utilisateurs test et l’API activée. La CLI ne réutilise délibérément aucun cache de jetons.
Toute portée accordée qui n’est pas exactement youtube.upload est refusée ;
utilisez un client dédié aux applications de bureau pour ce flux de travail restreint plutôt que
d’élargir les autorisations demandées.
Erreurs réseau et API
La validation locale a lieu avant le consentement. Vérifiez d’abord le chemin du fichier et les types des métadonnées. Après le message de démarrage de l’insertion, une erreur réseau ou API nécessite une vérification dans YouTube Studio pour la chaîne sélectionnée. Si un identifiant renvoyé a été affiché, utilisez cet identifiant exact. L’échec du traitement est distinct de l’acceptation du transfert ; l’API décrit ces états dans la ressource vidéo. Corrigez la cause avant de décider s’il faut soumettre un nouvel envoi.
Vous préférez ne pas l’exécuter vous-même ?
Transloadit encode des vidéos via une seule API, sans serveurs FFmpeg à gérer.
