@maccesar/aiskills 1.22.0 → 1.24.0

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)

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

@@ -0,0 +1,427 @@
+#!/usr/bin/env python3
+"""Reusable primitives copied into an approved technical-video package."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from statistics import median
+
+
+DEFAULT_VSCODE_PROFILE = {
+  'logical_display': (1920, 1080),
+  'minimum_window_size': (1850, 1000),
+  'auxiliary_panel_key_code': 19,
+  'terminal_open_delay': 1.5,
+  'terminal_drag_x': 645,
+  'terminal_target_y': 720,
+  'terminal_search_y': (90, 950)
+}
+
+SWIFT_DRAG_SOURCE = r'''
+import CoreGraphics
+import Foundation
+
+guard CommandLine.arguments.count == 5,
+      let startX = Double(CommandLine.arguments[1]),
+      let startY = Double(CommandLine.arguments[2]),
+      let endX = Double(CommandLine.arguments[3]),
+      let endY = Double(CommandLine.arguments[4]) else {
+  exit(2)
+}
+
+let start = CGPoint(x: startX, y: startY)
+let end = CGPoint(x: endX, y: endY)
+CGEvent(mouseEventSource: nil, mouseType: .mouseMoved,
+        mouseCursorPosition: start, mouseButton: .left)?.post(tap: .cghidEventTap)
+usleep(100_000)
+CGEvent(mouseEventSource: nil, mouseType: .leftMouseDown,
+        mouseCursorPosition: start, mouseButton: .left)?.post(tap: .cghidEventTap)
+for step in 1...20 {
+  let progress = Double(step) / 20.0
+  let point = CGPoint(
+    x: startX + ((endX - startX) * progress),
+    y: startY + ((endY - startY) * progress)
+  )
+  CGEvent(mouseEventSource: nil, mouseType: .leftMouseDragged,
+          mouseCursorPosition: point, mouseButton: .left)?.post(tap: .cghidEventTap)
+  usleep(15_000)
+}
+CGEvent(mouseEventSource: nil, mouseType: .leftMouseUp,
+        mouseCursorPosition: end, mouseButton: .left)?.post(tap: .cghidEventTap)
+'''
+
+
+class MacVsCodeRecording:
+  def __init__(
+    self, source_project, output_video, output_events, slug,
+    copies_root=None, display_number=1
+  ):
+    self.source_project = Path(source_project).resolve()
+    self.output_video = Path(output_video).resolve()
+    self.output_events = Path(output_events).resolve()
+    self.slug = slug
+    configured_root = copies_root or os.environ.get('TECHNICAL_DEMO_COPIES_ROOT')
+    self.copies_root = Path(configured_root).expanduser().resolve() if configured_root else Path.home() / 'TechnicalDemos'
+    self.display_number = int(display_number)
+    self.temp_root = None
+    self.project = None
+    self.window_slug = None
+    self.capture = None
+    self.drag_helper = None
+    self.events = []
+
+  @staticmethod
+  def _apple_string(value):
+    return str(value).replace('\\', '\\\\').replace('"', '\\"')
+
+  def preflight(self, required_files=(), forbidden_files=()):
+    for tool in (
+      'code', 'magick', 'osascript', 'screencapture', 'swift', 'swiftc'
+    ):
+      if shutil.which(tool) is None:
+        raise RuntimeError(f'missing required tool: {tool}')
+    if not self.source_project.is_dir():
+      raise RuntimeError(f'project not found: {self.source_project}')
+    missing = [path for path in required_files if not (self.source_project / path).exists()]
+    if missing:
+      raise RuntimeError('missing project files: ' + ', '.join(missing))
+    present = [path for path in forbidden_files if (self.source_project / path).exists()]
+    if present:
+      raise RuntimeError('source already contains generated files: ' + ', '.join(present))
+    for artifact in (self.output_video, self.output_events):
+      if artifact.exists():
+        raise RuntimeError(f'refusing to overwrite: {artifact}')
+
+  @staticmethod
+  def logical_display_size():
+    source = (
+      'import AppKit; '
+      'let f = NSScreen.main!.frame; '
+      'print(Int(f.width), Int(f.height))'
+    )
+    result = subprocess.run(
+      ['swift', '-e', source], check=True, capture_output=True, text=True
+    )
+    width, height = result.stdout.strip().split()
+    return int(width), int(height)
+
+  def create_copy(self):
+    copies_root = self.copies_root
+    copies_root.mkdir(parents=True, exist_ok=True)
+    if not copies_root.is_dir():
+      raise RuntimeError(f'recording copies folder not found: {copies_root}')
+    self.temp_root = Path(tempfile.mkdtemp(prefix=f'{self.slug}-recording.'))
+    self.project = Path(tempfile.mkdtemp(prefix=f'{self.slug}.', dir=copies_root))
+    self.window_slug = self.project.name
+    shutil.copytree(self.source_project, self.project, dirs_exist_ok=True)
+    self.drag_helper = self.temp_root / 'drag'
+    subprocess.run(
+      ['swiftc', '-o', str(self.drag_helper), '-'],
+      input=SWIFT_DRAG_SOURCE, check=True, capture_output=True, text=True
+    )
+    return self.project
+
+  def open_vscode(self):
+    subprocess.run(['code', '-n', str(self.project)], check=True)
+
+  def targeted(self, body, capture_output=False):
+    slug = self._apple_string(self.window_slug)
+    script = f'''
+set slug to "{slug}"
+tell application "System Events"
+  tell process "Code"
+    set targetWindow to missing value
+    repeat with candidateWindow in windows
+      if name of candidateWindow contains slug then
+        set targetWindow to candidateWindow
+        exit repeat
+      end if
+    end repeat
+    if targetWindow is missing value then error "Target window not found: " & slug
+    perform action "AXRaise" of targetWindow
+    set frontmost to true
+    delay 0.15
+    if name of front window does not contain slug then error "Wrong front window"
+    {body}
+  end tell
+end tell
+'''
+    result = subprocess.run(
+      ['osascript', '-e', script], check=True,
+      capture_output=capture_output, text=True
+    )
+    return result.stdout.strip() if capture_output else ''
+
+  def wait_for_window(self, timeout=30):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+      try:
+        self.targeted('return name of front window', True)
+        return
+      except subprocess.CalledProcessError:
+        time.sleep(0.4)
+    raise RuntimeError('VS Code window did not appear')
+
+  def assert_window_size(self, minimum_size):
+    raw_size = self.targeted(
+      'set s to size of front window\n'
+      'return (item 1 of s as text) & "," & (item 2 of s as text)',
+      True
+    )
+    width, height = [int(value) for value in raw_size.split(',')]
+    if width < minimum_size[0] or height < minimum_size[1]:
+      raise RuntimeError(
+        f'VS Code window is {width}x{height}; minimum is '
+        f'{minimum_size[0]}x{minimum_size[1]}'
+      )
+
+  def window_geometry(self):
+    raw_geometry = self.targeted(
+      'set p to position of front window\n'
+      'set s to size of front window\n'
+      'return (item 1 of p as text) & "," & '
+      '(item 2 of p as text) & "," & '
+      '(item 1 of s as text) & "," & (item 2 of s as text)',
+      True
+    )
+    return tuple(int(value) for value in raw_geometry.split(','))
+
+  def open_terminal(self):
+    self.targeted(
+      'click menu item "New Terminal" of menu 1 of '
+      'menu bar item "Terminal" of menu bar 1'
+    )
+
+  def drag(self, start, end):
+    self.targeted('return name of front window', True)
+    subprocess.run([
+      str(self.drag_helper), str(start[0]), str(start[1]),
+      str(end[0]), str(end[1])
+    ], check=True)
+
+  @staticmethod
+  def _column_pixels(image_path, x, height):
+    result = subprocess.run([
+      'magick', str(image_path), '-crop', f'1x{height}+{x}+0',
+      '-depth', '8', 'txt:-'
+    ], check=True, capture_output=True, text=True)
+    pattern = re.compile(r'^0,(\d+): \((\d+),(\d+),(\d+)')
+    pixels = []
+    for line in result.stdout.splitlines():
+      match = pattern.match(line)
+      if match:
+        pixels.append(tuple(int(value) for value in match.groups()[1:]))
+    if len(pixels) != height:
+      raise RuntimeError(
+        f'could not read screenshot column at x={x}: '
+        f'expected {height} pixels, found {len(pixels)}'
+      )
+    return pixels
+
+  @staticmethod
+  def _average_color(pixels, start, end):
+    count = end - start
+    return tuple(
+      sum(pixels[index][channel] for index in range(start, end)) / count
+      for channel in range(3)
+    )
+
+  def detect_terminal_divider(self, screenshot_path, search_range):
+    window_x, window_y, window_width, window_height = self.window_geometry()
+    dimensions = subprocess.run([
+      'magick', 'identify', '-format', '%w,%h', str(screenshot_path)
+    ], check=True, capture_output=True, text=True).stdout.strip()
+    image_width, image_height = [int(value) for value in dimensions.split(',')]
+    logical_width, logical_height = self.logical_display_size()
+    scale_x = image_width / logical_width
+    scale_y = image_height / logical_height
+    if abs(scale_x - scale_y) > 0.01:
+      raise RuntimeError('display screenshot has inconsistent pixel scaling')
+    scale = scale_x
+
+    logical_xs = [
+      window_x + round(window_width * fraction)
+      for fraction in (0.20, 0.35, 0.55)
+    ]
+    columns = [
+      self._column_pixels(
+        screenshot_path, round(logical_x * scale), image_height
+      )
+      for logical_x in logical_xs
+    ]
+    first_y = max(window_y + search_range[0], window_y + 80)
+    last_y = min(
+      window_y + search_range[1], window_y + window_height - 100
+    )
+    start = max(round(first_y * scale), 16)
+    end = min(round(last_y * scale), image_height - 16)
+
+    best = None
+    for y in range(start, end):
+      column_scores = []
+      for pixels in columns:
+        above = self._average_color(pixels, y - 12, y - 4)
+        below = self._average_color(pixels, y + 4, y + 12)
+        distance = sum(
+          (above[channel] - below[channel]) ** 2
+          for channel in range(3)
+        ) ** 0.5
+        column_scores.append(distance)
+      score = median(column_scores)
+      if min(column_scores) < score * 0.6:
+        continue
+      if best is None or score > best[0]:
+        best = (score, y)
+
+    if best is None or best[0] < 6:
+      raise RuntimeError(
+        'could not locate the horizontal terminal divider with confidence'
+      )
+    return round(best[1] / scale)
+
+  def resize_terminal_panel(self, x, target_y, search_range=(90, 950)):
+    if self.temp_root is None:
+      raise RuntimeError('disposable project has not been created')
+    before = self.temp_root / 'terminal-before.png'
+    after = self.temp_root / 'terminal-after.png'
+    self.targeted('return name of front window', True)
+    subprocess.run([
+      '/usr/sbin/screencapture', '-x', f'-D{self.display_number}', str(before)
+    ], check=True)
+    handle_offset = 5
+    start_y = (
+      self.detect_terminal_divider(before, search_range) + handle_offset
+    )
+    if abs(start_y - target_y) > 4:
+      self.drag((x, start_y), (x, target_y))
+      time.sleep(0.5)
+    subprocess.run([
+      '/usr/sbin/screencapture', '-x', f'-D{self.display_number}', str(after)
+    ], check=True)
+    actual_y = (
+      self.detect_terminal_divider(after, search_range) + handle_offset
+    )
+    if abs(actual_y - target_y) > 8:
+      raise RuntimeError(
+        f'terminal divider verification failed: expected y={target_y}, '
+        f'found y={actual_y} (started at y={start_y})'
+      )
+    before.unlink(missing_ok=True)
+    after.unlink(missing_ok=True)
+    return start_y, actual_y
+
+  def prepare_default_vscode(self, profile=None):
+    selected = profile or DEFAULT_VSCODE_PROFILE
+    if self.logical_display_size() != tuple(selected['logical_display']):
+      raise RuntimeError('logical display does not match the accepted profile')
+    self.create_copy()
+    self.open_vscode()
+    self.wait_for_window()
+    self.assert_window_size(selected['minimum_window_size'])
+    auxiliary_panel_key_code = selected.get('auxiliary_panel_key_code')
+    if auxiliary_panel_key_code is not None:
+      self.hotkey(auxiliary_panel_key_code)
+      time.sleep(0.4)
+    self.open_terminal()
+    time.sleep(selected.get('terminal_open_delay', 1.5))
+    self.resize_terminal_panel(
+      selected['terminal_drag_x'], selected['terminal_target_y'],
+      selected['terminal_search_y']
+    )
+    time.sleep(0.4)
+
+  def quick_open(self, relative_path):
+    path = self._apple_string(relative_path)
+    self.targeted(f'''
+keystroke "p" using command down
+delay 0.25
+set savedClipboard to missing value
+try
+  set savedClipboard to the clipboard as record
+end try
+set the clipboard to "{path}"
+keystroke "v" using command down
+delay 0.2
+key code 36
+if savedClipboard is not missing value then set the clipboard to savedClipboard
+''')
+
+  def hotkey(self, key_code, modifiers='command down'):
+    self.targeted(f'key code {key_code} using {modifiers}')
+
+  def type_text(self, text, character_delay=0.045):
+    safe = self._apple_string(text)
+    self.targeted(f'''
+repeat with currentCharacter in characters of "{safe}"
+  keystroke currentCharacter
+  delay {character_delay}
+end repeat
+''')
+
+  def wait_for_files(self, relative_paths, timeout=60):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+      if all((self.project / path).exists() for path in relative_paths):
+        return
+      time.sleep(0.2)
+    missing = [path for path in relative_paths if not (self.project / path).exists()]
+    raise RuntimeError('timed out waiting for: ' + ', '.join(missing))
+
+  def mark(self, name, **details):
+    self.events.append({
+      'name': name,
+      'timestamp_ms': round(time.monotonic() * 1000),
+      **details
+    })
+
+  def start_capture(self):
+    self.output_video.parent.mkdir(parents=True, exist_ok=True)
+    self.capture = subprocess.Popen([
+      '/usr/sbin/screencapture', '-v', f'-D{self.display_number}', '-k', str(self.output_video)
+    ])
+    self.mark('recording_started')
+
+  def stop_capture(self):
+    if self.capture is None:
+      return
+    if self.capture.poll() is None:
+      self.capture.send_signal(signal.SIGINT)
+    code = self.capture.wait(timeout=30)
+    self.capture = None
+    if code != 0 or not self.output_video.is_file():
+      raise RuntimeError(f'screen capture failed with exit code {code}')
+    self.mark('recording_stopped')
+
+  def write_events(self, metadata=None):
+    payload = {'schema_version': 1, **(metadata or {}), 'events': self.events}
+    self.output_events.write_text(json.dumps(payload, indent=2) + '\n')
+
+  def cleanup(self):
+    if self.capture is not None:
+      try:
+        self.stop_capture()
+      except Exception:
+        if self.capture is not None:
+          self.capture.kill()
+          self.capture.wait()
+          self.capture = None
+    if self.window_slug:
+      try:
+        self.targeted('keystroke "w" using {command down, shift down}')
+      except Exception:
+        pass
+    if self.project:
+      time.sleep(0.8)
+      shutil.rmtree(self.project, ignore_errors=True)
+      time.sleep(0.4)
+      shutil.rmtree(self.project, ignore_errors=True)
+    if self.temp_root:
+      shutil.rmtree(self.temp_root, ignore_errors=True)