コマンドラインから YouTube にファイルをエクスポート
Google のオープンソース Python ライブラリを使って、完成した動画を端末からアップロードできます。以下の CLI はローカルファイルとメタデータ JSON を選択し、チャンネルの認可を求め、YouTube がアップロードを受け付けた後に動画の ID を返します。動画は非公開に保ち、チャンネル登録者への通知を無効にします。
YouTube API の重要な制限
この例は、同じマシン上で Bash とブラウザーを使い、Linux から対話的にアップロードするためのものです。UTF-8 のファイル名を持つ、空でない 64 MiB 以下のローカル MP4 を受け付けます。ファイルは完成済みで再生できる必要があります。スクリプトは内容の検証やトランスコードを行いません。認可と転送を含めた全体の制限時間は五分のため、上限未満のファイルでも、接続が遅いと失敗する場合があります。
アップロードが受け付けられても、処理はまだ必要です。CLI が要求するのは、挿入を許可する
youtube.upload
のみです。非公開動画の確認や API 経由での削除に必要な、より広い権限は要求しません。その後、選択したチャンネルの YouTube Studio で返された ID を確認し、処理が完了してから動画を使用してください。
Google Cloud でプロジェクトの現在のアップロード割り当てを確認してください。YouTube はアップロードを個別の割り当て枠で集計します。コマンドの間に待機時間を入れても、1 日の割り当ては回復しません。この処理設定では、プロジェクトやアカウントのデフォルトにかかわらず、非公開を明示的に要求します。
Python ライブラリのインストール
venv と pip が利用できる、インストール済みの
CPython 3.14 インタープリターを使用してください。テスト済みのインタープリターは 3.14.8 です。新規インストールでは、Python のダウンロードページから、保守中の 3.14 系の最新セキュリティパッチを使用してください。Python 3.15 のほうが新しいものの、この手順のテスト対象は 3.14 です。Google API クライアントも
3.14 をサポート対象として明記しています。
新しい youtube-cli ディレクトリを作成したい親ディレクトリから実行してください。サブシェルを使うため、現在のディレクトリとシェルオプションは変更されません。既存のディレクトリは拒否されます。インストールに失敗した場合は、別の新しい場所を選ぶ前に、エラーと作成途中のディレクトリを確認してください。これらのコマンドは既存のファイルを削除しません。
(
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
)
これらはテスト済みのパッケージバージョンです。Google クライアントは修正のための保守が行われており、YouTube のディスカバリーベースの API を提供します。以下の小さな Requests トランスポートでは、再試行の動作を明示しています。失敗した挿入を、別の挿入として自動的にやり直すことはありません。
デスクトップ用 OAuth の設定
対象の YouTube チャンネルを所有する Google アカウントを使用してください。Google のデスクトップ用 OAuth の設定手順に従います。
- Google Cloud Consoleでプロジェクトを選択し、YouTube Data API v3 を有効にします。
- アプリの同意情報と対象ユーザーを設定します。テスト中の外部アプリでは、使用する Google アカウントをテストユーザーとして追加します。
- アプリケーションの種類を Desktop app にして OAuth クライアントを作成します。JSON を
youtube-cli/client_secrets.jsonとしてダウンロードし、バージョン管理に含めないでください。 - YouTube のアカウント詳細設定で対象チャンネルの ID を確認します。以下のコマンドでは、その
UC…ID を使用してください。@exampleのようなハンドルはチャンネル ID ではありません。
プログラムはランダムなループバックポートと PKCE を使用します。実行ごとに新たな同意を要求し、トークンキャッシュを保存せず、挿入前にチャンネルの確認を求めます。Google の認可フローで対象のチャンネルを選択し、該当する場合は正しいブランドアカウントも選択してください。ID を入力してもチャンネルは選択されません。アップロード先は認可したアカウントによって決まります。返されたチャンネル ID は挿入後に検証します。不一致は失敗として扱いますが、その時点ですでに別のチャンネルに非公開動画が作成されている場合があります。
動画メタデータの管理
タイトルと説明を置き換え、youtube-cli/metadata.json として保存してください。madeForKids は実際の視聴者に合わせて設定します。メタデータとして指定できるのは、この四つのキーのみです。未知のキーは拒否されます。公開設定と通知は、サイドカーファイルやツールのデフォルトから引き継がず、プログラム内で固定します。
{
"title": "My command-line upload",
"description": "A completed local video.\nUploaded privately for review.",
"tags": ["demo", "command-line"],
"madeForKids": false
}
アップローダーの保存と実行
プログラム全体を youtube-cli/upload.py として保存してください。ファイルを読み取るだけで、ファイル自体やメタデータのサイドカーファイルは変更しません。挿入開始後のネットワークエラーは、結果が不確かなものとして扱います。応答メタデータの検証前に、返された ID を stderr に出力するため、不一致を調査できます。認可 URL とコールバックは非公開のログイン処理の一部なので、端末の記録を共有しないでください。
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)
完成したファイルを ./video.mp4 に配置し、YOUR_CHANNEL_ID を記録したチャンネル ID に置き換えてください。インストールコマンドと同じ親ディレクトリから実行します。
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
出力された認可リンクをローカルブラウザーで開いてください。三分以内に同意を完了し、端末のプロンプトで選択したチャンネルの ID を入力します。成功時の stdout 出力は、ネイティブの id、一致する channelId、"status": "accepted_processing_unchecked" を含む JSON のみです。終了コードがゼロ以外の場合、ID がない場合、メタデータが一致しない場合は失敗です。プログラムはアップロードの受領記録をローカルに書き込まないため、端末を閉じる前に ID を控えてください。
追加ファイルのアップロード
複数の動画では、明示的に指定したファイルと対応するメタデータファイルの組ごとに、同じコマンドを一回ずつ実行します。空白やシェルの特殊文字を含むパスは引用符で囲み、先頭がハイフンのファイル名には ./ を付けてください。プログラムは glob によるファイル探索や、ファイル名からのタイトル生成を行いません。呼び出しごとにブラウザーでの新たな同意とチャンネルの確認が必要です。最初の失敗で停止し、次の挿入を開始する前に結果を調査してください。
アップロード自動化の組み込み
動画を生成する処理から、完成した MP4 を閉じた後にこの CLI を呼び出せますが、認可には引き続き対話操作が必要です。無人実行用のスケジューラーではありません。更新トークンの保持や、ジョブと ID を永続的に記録する仕組みの追加には、別途設計が必要です。特に、このコマンドを再試行ループで実行しないでください。最終応答を受信できなかった場合、コマンドが失敗を返しても、YouTube に動画が残ることがあります。この例では、再開可能セッションの URL を永続化せず、プロセス終了後の復元も行いません。
よくある問題のトラブルシューティング
転送の制限
64 MiB はこの例の上限であり、YouTube プラットフォームの上限ではありません。Requests トランスポートはリクエストごとに十秒の接続タイムアウトと 30 秒の読み取りタイムアウトを使い、それとは別に、同意と転送を含むプロセス全体に五分のアラームを設けています。帯域幅を制限する機能はありません。挿入開始後にタイムアウトした場合は、何もアップロードされていない証拠とはみなさず、チャンネルを確認してください。
認証の問題
デスクトップ用の認証情報を使用し、ループバックのコールバックがリスナーに届くように、コマンドを実行するマシンでブラウザーを使ってください。同意が拒否された場合は、アプリの対象ユーザー、テストユーザーのアクセス権、有効な API を確認してください。CLI は意図的にトークンキャッシュを再利用しません。付与されたスコープが youtube.upload と完全に一致しなければ拒否します。要求する権限を広げるのではなく、この限定的なワークフロー専用のデスクトップクライアントを使用してください。
ネットワークと API のエラー
ローカルでの検証は同意前に行います。まずファイルパスとメタデータの型を確認してください。挿入開始のメッセージが出た後にネットワークや API のエラーが発生した場合は、選択したチャンネルの YouTube Studio で調査が必要です。返された ID が出力されていれば、その ID をそのまま使ってください。処理の失敗と転送の受け付けは別の状態です。API では、これらの状態を動画リソースで説明しています。新たなアップロードを送信するか判断する前に、原因を解消してください。
