@maccesar/aiskills 1.21.1 → 1.23.0

package/skills/technical-demo-videos/references/youtube-publishing.md

@@ -0,0 +1,126 @@
+# Automated YouTube publishing
+
+Read this only when the user wants to automate YouTube upload or post-upload configuration.
+
+## Official capability and boundary
+
+Google does not provide a general-purpose official `youtube` CLI for this workflow. Use the official YouTube Data API v3, preferably through Google's supported client libraries. The reusable `scripts/youtube_publish.py` wrapper covers:
+
+1. `videos.insert`: resumable video upload plus title, description, tags, category, language, privacy, audience declaration, embedding, license, and optional schedule.
+2. `playlistItems.insert`: add the returned video ID to one explicitly supplied playlist ID.
+3. `captions.insert`: upload the timed SRT as a named language track.
+   For a corrected SRT on an existing video, `captions.update` replaces the
+   media of the exact track recorded in the upload receipt.
+4. `thumbnails.set`: upload an optional custom PNG or JPEG.
+
+YouTube Studio settings that are not exposed by these resources still require manual configuration. Do not promise automation for an undocumented Studio control.
+
+## One-time account setup
+
+The user must perform or authorize these steps:
+
+1. Create or select a Google Cloud project.
+2. Enable YouTube Data API v3.
+3. Create an OAuth 2.0 client for a Desktop application and download its client-secret JSON.
+4. Complete the browser consent flow on the first executed upload.
+5. Identify the expected YouTube channel ID. The upload script verifies that the OAuth token exposes this exact channel before any mutation.
+6. Choose either one exact playlist ID or explicitly choose no playlist. List or resolve playlists only after OAuth; never infer an ID from a playlist name.
+
+When the channel or playlist IDs are unknown, inspect the authenticated account without uploading:
+
+```bash
+python3 scripts/youtube_publish.py --inspect-account \
+  --client-secrets /secure/path/client_secret.json \
+  --token /secure/path/youtube-token.json
+```
+
+Present the returned channel IDs/titles and playlist IDs/titles to the user. Account inspection is read-only, but starting OAuth or accessing an external account still requires authorization. Do not select a channel or playlist on the user's behalf.
+
+Use the `https://www.googleapis.com/auth/youtube.force-ssl` scope when one workflow must upload video, manage playlists, and upload captions. Store the refresh token outside the source repository with owner-only permissions. Never commit the client-secret JSON, token, or upload receipt containing private operational data.
+
+API projects created after July 28, 2020 that have not passed YouTube's compliance audit can upload only private videos. Treat that as a platform restriction, not a script failure.
+
+## Safe publication contract
+
+- Before generating the manifest, obtain approval for the expected channel, playlist or explicit no-playlist choice, privacy/schedule, captions, and thumbnail.
+- Generate `production/<slug>-youtube-upload.json` from those approved decisions.
+- Use paths relative to the manifest. The video and SRT normally point one directory upward to the episode root.
+- Keep `privacyStatus` as `private` by default.
+- A public, unlisted, or scheduled publication requires explicit user authorization and the script's `--allow-public` switch.
+- Run without `--execute` first. Dry-run validates files and prints the expected channel, explicit playlist choice, privacy/schedule, captions, thumbnail, hashes, intended mutations, and a confirmation token without authenticating or calling YouTube.
+- Present that dry run and wait for separate upload authorization. Pass its exact token through `--confirm-plan`; any file or metadata change invalidates it and requires a new dry run.
+- After OAuth and before any mutation, compare the authenticated channel with `expectedChannelId` and verify that any selected playlist exists on that channel. Abort on a mismatch.
+- On execution, write `production/<slug>-youtube-upload-receipt.json` immediately after `videos.insert`, then update it after playlist, caption, and thumbnail operations. A retry reuses the recorded video ID and skips completed stages.
+- Verify the returned video ID, URL, playlist insertion, caption-track ID, processing state, and intended privacy status before declaring publication complete.
+- Do not delete or replace an existing YouTube video automatically. Stop and request direction when metadata or file hashes disagree with an existing receipt.
+
+## Manifest shape
+
+```json
+{
+  "schemaVersion": 1,
+  "videoFile": "../03-semantic-final.mp4",
+  "captionsFile": "../03-semantic-subtitles-en.srt",
+  "thumbnailFile": null,
+  "title": "Example title",
+  "description": "Example description",
+  "tags": ["Example Product", "Technical Tutorial"],
+  "categoryId": "28",
+  "defaultLanguage": "en",
+  "expectedChannelId": "UC_EXACT_CHANNEL_ID",
+  "privacyStatus": "private",
+  "selfDeclaredMadeForKids": false,
+  "embeddable": true,
+  "license": "youtube",
+  "publishAt": null,
+  "playlistId": null,
+  "caption": {
+    "language": "en",
+    "name": "English",
+    "isDraft": false
+  }
+}
+```
+
+`categoryId` `28` is Science & Technology. Keep the ID configurable rather than deriving it from prose.
+`playlistId: null` is an explicit decision to leave the video out of playlists; omitting the field is invalid. All target fields remain user/project data, never skill defaults.
+
+## Usage
+
+Dry run requires only Python:
+
+```bash
+python3 scripts/youtube_publish.py production/<slug>-youtube-upload.json
+```
+
+Copy the printed `confirmationToken` only after the user approves that exact dry-run summary.
+
+Account inspection and real execution additionally need Google's official Python clients:
+
+```bash
+python3 -m pip install google-api-python-client google-auth-oauthlib google-auth-httplib2
+python3 scripts/youtube_publish.py production/<slug>-youtube-upload.json \
+  --client-secrets /secure/path/client_secret.json \
+  --token /secure/path/youtube-token.json \
+  --confirm-plan CONFIRMATION_TOKEN_FROM_APPROVED_DRY_RUN \
+  --execute
+```
+
+To replace an already uploaded caption track without deleting or duplicating
+the video, repeat the command with `--replace-captions`. This requires the
+existing receipt and its exact `captionId`.
+
+Add `--allow-public` only after the user approves `unlisted`, `public`, or `publishAt`. Do not use that flag for the normal private-first review workflow.
+
+## Official references
+
+- Video upload: https://developers.google.com/youtube/v3/docs/videos/insert
+- Official Python upload guide: https://developers.google.com/youtube/v3/guides/uploading_a_video
+- Authenticated channel lookup: https://developers.google.com/youtube/v3/docs/channels/list
+- Authenticated playlist lookup: https://developers.google.com/youtube/v3/docs/playlists/list
+- Playlist insertion: https://developers.google.com/youtube/v3/docs/playlistItems/insert
+- Caption upload: https://developers.google.com/youtube/v3/docs/captions/insert
+- Caption replacement: https://developers.google.com/youtube/v3/docs/captions/update
+- Custom thumbnail: https://developers.google.com/youtube/v3/docs/thumbnails/set
+- OAuth for installed apps: https://developers.google.com/youtube/v3/guides/auth/installed-apps
+- Quotas: https://developers.google.com/youtube/v3/determine_quota_cost

package/skills/technical-demo-videos/scripts/events_to_cues.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Convert timestamped recording events into a narration cue skeleton."""
+
+import argparse
+import json
+from pathlib import Path
+
+
+def load_events(path):
+  payload = json.loads(path.read_text())
+  events = payload.get('events') if isinstance(payload, dict) else payload
+  if not isinstance(events, list) or not events:
+    raise SystemExit('event log must contain a non-empty event array')
+  return payload, events
+
+
+def main():
+  parser = argparse.ArgumentParser()
+  parser.add_argument('events_json', type=Path)
+  parser.add_argument('output_json', type=Path)
+  args = parser.parse_args()
+
+  payload, events = load_events(args.events_json)
+  if args.output_json.exists():
+    raise SystemExit(f'refusing to overwrite: {args.output_json}')
+
+  previous = None
+  for event in events:
+    if not isinstance(event, dict) or 'name' not in event or 'timestamp_ms' not in event:
+      raise SystemExit('each event must contain name and timestamp_ms')
+    current = event['timestamp_ms']
+    if not isinstance(current, (int, float)):
+      raise SystemExit('timestamp_ms values must be numeric and ordered')
+    if previous is not None and current < previous:
+      raise SystemExit('timestamp_ms values must be numeric and ordered')
+    previous = current
+
+  starts = [event for event in events if event['name'] == 'recording_started']
+  if len(starts) != 1:
+    raise SystemExit('event log must contain exactly one recording_started event')
+  stops = [event for event in events if event['name'] == 'recording_stopped']
+  if len(stops) != 1:
+    raise SystemExit('event log must contain exactly one recording_stopped event')
+
+  start_index = events.index(starts[0])
+  stop_index = events.index(stops[0])
+  if stop_index <= start_index:
+    raise SystemExit('recording_stopped must follow recording_started')
+
+  captured_events = events[start_index:stop_index + 1]
+  origin = starts[0]['timestamp_ms']
+  normalized = []
+  for event in captured_events:
+    current = event['timestamp_ms']
+    normalized.append({
+      'event': event['name'],
+      'at': round((current - origin) / 1000, 3),
+      **({'path': event['path']} if 'path' in event else {})
+    })
+
+  stop = normalized[-1]['at']
+  visual = [
+    event for event in normalized
+    if event['event'] not in {'recording_started', 'recording_stopped'}
+  ]
+  cues = []
+  for index, event in enumerate(visual):
+    end = visual[index + 1]['at'] if index + 1 < len(visual) else stop
+    cues.append({
+      'id': index + 1,
+      'event': event['event'],
+      'start': event['at'],
+      'end': end,
+      'text': ''
+    })
+
+  result = {
+    'source_events': str(args.events_json),
+    'duration': stop,
+    'events': normalized,
+    'cues': cues
+  }
+  if isinstance(payload, dict) and payload.get('demo'):
+    result['demo'] = payload['demo']
+  args.output_json.write_text(json.dumps(result, indent=2) + '\n')
+
+
+if __name__ == '__main__':
+  main()

package/skills/technical-demo-videos/scripts/normalize_youtube_master.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+
+"""Create and verify a stable YouTube upload master from an approved edit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+
+
+STANDARD_BITRATES = {
+  2160: {
+    'standard': ('35M', 35_000_000),
+    'high': ('53M', 53_000_000)
+  },
+  1440: {
+    'standard': ('16M', 16_000_000),
+    'high': ('24M', 24_000_000)
+  },
+  1080: {
+    'standard': ('8M', 8_000_000),
+    'high': ('12M', 12_000_000)
+  },
+  720: {
+    'standard': ('5M', 5_000_000),
+    'high': ('7.5M', 7_500_000)
+  },
+  480: {
+    'standard': ('2.5M', 2_500_000),
+    'high': ('4M', 4_000_000)
+  },
+  360: {
+    'standard': ('1M', 1_000_000),
+    'high': ('1.5M', 1_500_000)
+  }
+}
+
+
+def parse_args():
+  parser = argparse.ArgumentParser()
+  parser.add_argument('input', type=Path)
+  parser.add_argument('output', type=Path)
+  parser.add_argument('--fps', type=int, default=30)
+  parser.add_argument('--video-bitrate')
+  return parser.parse_args()
+
+
+def probe(path):
+  result = subprocess.run([
+    'ffprobe', '-v', 'error', '-show_streams', '-show_format',
+    '-of', 'json', str(path)
+  ], check=True, capture_output=True, text=True)
+  return json.loads(result.stdout)
+
+
+def stream(payload, kind):
+  selected = next(
+    (item for item in payload['streams'] if item.get('codec_type') == kind),
+    None
+  )
+  if selected is None:
+    raise RuntimeError(f'{kind} stream is required')
+  return selected
+
+
+def parse_bitrate(value):
+  suffixes = {'K': 1_000, 'M': 1_000_000}
+  suffix = value[-1].upper()
+  if suffix in suffixes:
+    return int(float(value[:-1]) * suffixes[suffix])
+  return int(value)
+
+
+def default_bitrate(height, fps):
+  frame_rate_class = 'high' if fps >= 48 else 'standard'
+  for threshold, values in STANDARD_BITRATES.items():
+    if height >= threshold:
+      return values[frame_rate_class]
+  return (
+    ('1.5M', 1_500_000) if frame_rate_class == 'high'
+    else ('1M', 1_000_000)
+  )
+
+
+def has_faststart(path):
+  with path.open('rb') as handle:
+    header = handle.read(min(path.stat().st_size, 16 * 1024 * 1024))
+  moov = header.find(b'moov')
+  mdat = header.find(b'mdat')
+  return moov >= 0 and mdat >= 0 and moov < mdat
+
+
+def validate_master(path, expected_width, expected_height, fps, bitrate):
+  payload = probe(path)
+  video = stream(payload, 'video')
+  audio = stream(payload, 'audio')
+  errors = []
+  if (video.get('width'), video.get('height')) != (
+    expected_width, expected_height
+  ):
+    errors.append('resolution changed during normalization')
+  if video.get('codec_name') != 'h264' or video.get('profile') != 'High':
+    errors.append('video must be H.264 High Profile')
+  if video.get('pix_fmt') != 'yuv420p':
+    errors.append('video pixel format must be yuv420p')
+  if any(video.get(key) != 'bt709' for key in (
+    'color_space', 'color_transfer', 'color_primaries'
+  )):
+    errors.append('video color metadata must be BT.709')
+  actual_fps = Fraction(video['avg_frame_rate'])
+  if actual_fps != fps:
+    errors.append(f'video frame rate must be constant {fps} FPS')
+  actual_bitrate = int(video.get('bit_rate', 0))
+  if actual_bitrate < round(bitrate * 0.85):
+    errors.append(
+      f'video bitrate {actual_bitrate} is below the quality floor {bitrate}'
+    )
+  if audio.get('codec_name') != 'aac':
+    errors.append('audio codec must be AAC')
+  if int(audio.get('sample_rate', 0)) != 48_000:
+    errors.append('audio sample rate must be 48 kHz')
+  if int(audio.get('channels', 0)) != 2:
+    errors.append('audio must be stereo')
+  if 'mp4' not in payload['format'].get('format_name', ''):
+    errors.append('container must be MP4')
+  if not has_faststart(path):
+    errors.append('MP4 moov atom must precede media data for fast start')
+  if errors:
+    raise RuntimeError('; '.join(errors))
+  return {
+    'width': video['width'],
+    'height': video['height'],
+    'fps': float(actual_fps),
+    'videoBitrate': actual_bitrate,
+    'videoCodec': video['codec_name'],
+    'videoProfile': video['profile'],
+    'pixelFormat': video['pix_fmt'],
+    'color': 'bt709',
+    'audioCodec': audio['codec_name'],
+    'audioSampleRate': int(audio['sample_rate']),
+    'fastStart': True
+  }
+
+
+def main():
+  args = parse_args()
+  source = args.input.resolve()
+  output = args.output.resolve()
+  if not source.is_file():
+    raise RuntimeError(f'input not found: {source}')
+  if output.exists():
+    raise RuntimeError(f'refusing to overwrite: {output}')
+  if output.suffix.lower() != '.mp4':
+    raise RuntimeError('output must use an .mp4 extension')
+  if args.fps not in {24, 25, 30, 48, 50, 60}:
+    raise RuntimeError('fps must be one of 24, 25, 30, 48, 50, or 60')
+  for tool in ('ffmpeg', 'ffprobe'):
+    if shutil.which(tool) is None:
+      raise RuntimeError(f'missing required tool: {tool}')
+
+  source_payload = probe(source)
+  source_video = stream(source_payload, 'video')
+  width = int(source_video['width'])
+  height = int(source_video['height'])
+  bitrate_text, bitrate = default_bitrate(height, args.fps)
+  if args.video_bitrate:
+    bitrate_text = args.video_bitrate
+    bitrate = parse_bitrate(bitrate_text)
+  gop = max(1, round(args.fps / 2))
+  temporary = output.with_name(f'.{output.stem}.encoding.mp4')
+  temporary.unlink(missing_ok=True)
+
+  command = [
+    'ffmpeg', '-hide_banner', '-y', '-i', str(source),
+    '-map', '0:v:0', '-map', '0:a:0?',
+    '-vf', f'fps={args.fps},format=yuv420p',
+    '-fps_mode', 'cfr', '-c:v', 'libx264', '-preset', 'fast',
+    '-profile:v', 'high', '-b:v', bitrate_text,
+    '-g', str(gop), '-keyint_min', str(gop), '-sc_threshold', '0',
+    '-bf', '2',
+    '-x264-params', (
+      'force-cfr=1:colorprim=bt709:transfer=bt709:colormatrix=bt709'
+    ),
+    '-color_primaries', 'bt709', '-color_trc', 'bt709',
+    '-colorspace', 'bt709',
+    '-c:a', 'aac', '-b:a', '384k', '-ar', '48000', '-ac', '2',
+    '-movflags', '+faststart', str(temporary)
+  ]
+  try:
+    subprocess.run(command, check=True)
+    report = validate_master(
+      temporary, width, height, args.fps, bitrate
+    )
+    temporary.replace(output)
+  finally:
+    temporary.unlink(missing_ok=True)
+  print(json.dumps({'output': str(output), **report}, indent=2))
+
+
+if __name__ == '__main__':
+  try:
+    main()
+  except (OSError, RuntimeError, ValueError, subprocess.CalledProcessError) as exc:
+    print(f'error: {exc}', file=sys.stderr)
+    raise SystemExit(1)