@maccesar/aiskills 1.22.0 → 1.23.0

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

@@ -0,0 +1,36 @@
+# Publishing metadata handoff
+
+Read this after a final technical-demo video and external caption file exist, or when the user asks for social-platform metadata.
+
+## Deliverable
+
+Create one upload-ready `<slug>-publishing-metadata.md` in the episode root. The root then contains exactly three regular files:
+
+- `<slug>-final.mp4`
+- `<slug>-subtitles-<language>.srt`
+- `<slug>-publishing-metadata.md`
+
+Keep research notes and intermediate metadata drafts in `production/`, not in the episode root.
+
+## Required document sections
+
+1. **Shared identity:** final filenames, content/original-language setting, primary search phrase, supporting phrases, one-sentence summary, canonical project link, and cover/thumbnail text.
+2. **YouTube:** copy-ready title, description, hashtags, Studio tags, thumbnail copy, pinned comment, playlist/category/language/audience/caption settings, and whether chapters are useful.
+3. **TikTok:** copy-ready organic caption, focused hashtags, cover text, searchable phrases, accessibility setting, and a format warning when the supplied master is not 9:16.
+4. **Instagram Reels:** copy-ready caption, focused hashtags, cover text, searchable phrases, accessibility setting, and the same format warning when relevant.
+5. **Publishing checklist:** verify spelling, links, caption timing, public visibility, cover crop, safe zones, and platform preview before posting.
+
+## Writing rules
+
+- Match the video's language unless the user requests localized variants.
+- Preserve the project's subtitle typography convention independently from pronunciation text. Define a small lexicon in the production plan when product names, acronyms, commands, paths, or URLs need different written and spoken forms. Captions retain canonical spelling; voice-generator input uses only the pronunciation form approved for that provider.
+- Put the primary phrase naturally in the first title/description lines. Do not stuff keywords or paste ordinary tags into prose.
+- Keep hashtags directly relevant. For YouTube, use a small focused set; more than 60 hashtags are ignored. Studio tags mainly help with misspellings, so include product spelling variants there rather than bloating the description.
+- Treat platform-specific copy as separate even when the central message is shared. TikTok and Instagram organic posts use a caption rather than YouTube's separate title and long description.
+- Do not invent social handles, sponsorships, partnerships, locations, playlist IDs, or trending hashtags. Recommend checking current trends immediately before publishing.
+- Do not automatically crop or reframe a horizontal master. State that TikTok and Reels favor vertical 9:16 creative and offer a separate derivative when requested.
+- For short videos whose useful sections cannot meet YouTube chapter requirements, explicitly omit chapters rather than creating misleading timestamps.
+
+## Freshness and sources
+
+Platform behavior and limits are unstable. Browse current official platform documentation whenever generating or materially revising the metadata file. Prefer YouTube Help, TikTok Business/Creative Center, and Meta/Instagram Help or Meta for Business. Link the exact official pages used in a short Sources section inside the metadata document.

package/skills/technical-demo-videos/references/recording-workflow.md

@@ -0,0 +1,40 @@
+# macOS and VS Code recording workflow
+
+Use this reference only when the accepted plan will control VS Code or other Mac applications.
+
+## Preparation
+
+Keep preparation out of the capture unless it is part of the story. Open a uniquely identifiable project window, stabilize its size and position, arrange Explorer/editor/terminal panels, close unrelated tabs, and prepare simulators or devices before starting `screencapture`.
+
+Use [vscode-default-profile.md](vscode-default-profile.md) to define a baseline for the current workstation. Reuse an approved profile across projects instead of experimenting with panel commands or coordinates in each episode. Recalibrate only after a display, VS Code layout, keybinding, or global editor-association change.
+
+On VS Code, use full project-relative paths with Quick Open. Keep terminal commands readable and execute them from the project root without exposing temporary absolute paths. Prefer stable commands and accessibility selectors. When coordinates are unavoidable, store them as configurable logical-display values and validate display/window geometry first.
+
+Choose a dedicated, short copies directory before generating the recorder. Record that choice in the recipe or set `TECHNICAL_DEMO_COPIES_ROOT`; the reusable runtime otherwise uses `~/TechnicalDemos`. Place each disposable project directly beneath it with a short runtime slug such as `build-assets.a1b2c3`. Keep helpers and diagnostic screenshots in a separate system-temp directory. This makes printed absolute paths legible, keeps the Desktop clean, and lets `finally` remove only the current run's resources.
+
+A fresh disposable folder prevents stale project tabs and generated files, but it does not guarantee a fresh panel height: VS Code can inherit non-maximized panel geometry across windows. Detect and verify the actual divider position as described in [vscode-default-profile.md](vscode-default-profile.md); do not treat a hard-coded starting `y` coordinate as part of the profile.
+
+## Safe targeting
+
+Before every AppleScript or UI action block:
+
+1. find the window by the current run's unique slug;
+2. raise that exact window;
+3. make its owning process frontmost;
+4. re-read the front window title;
+5. abort unless it still contains the slug;
+6. only then send the intended action.
+
+Never assume activating an application preserves the correct window. Never paste a generated temporary slug into permanent source; create it at runtime.
+
+## Capture and events
+
+Use macOS `screencapture` for actual video, not a sequence of screenshots. Record `recording_started`, each visual transition, command submission/completion, relevant output, and `recording_stopped` with monotonic timestamps. Wait for observable completion such as a process exit, file creation, simulator state, or expected UI rather than an arbitrary long sleep.
+
+Stop capture cleanly before closing the demonstration window. Close the full project window afterward so the user can see that interaction is finished. Cleanup must target only resources created by the current run.
+
+Afterward, verify only that the expected media/log files exist and the temporary project is gone. Ask the user how the live take looked before spending time or tokens on screenshots, contact sheets, frame-by-frame review, transcription, or narration. Use deeper inspection only to investigate feedback or when the user asks for it.
+
+## User coordination
+
+Before capture, announce with `🎬` in a separate commentary update and ask the user not to touch input devices. Do not surface permission dialogs during the recording; preflight permissions before the announcement. If a permission or login prompt appears unexpectedly, reject the take, stop safely, and explain what must be prepared.

package/skills/technical-demo-videos/references/story-direction.md

@@ -0,0 +1,37 @@
+# Story and direction criteria
+
+Read this when turning a conversational brief into the written proposal or revising a take.
+
+## Build the visual argument
+
+A technical demonstration normally has four movements:
+
+1. **Context:** show the smallest amount of source material needed to understand the task.
+2. **Action:** type and execute the exact approved command or UI operation at a readable pace.
+3. **Proof:** show terminal completion and representative output that substantiates every promise.
+4. **Finish:** hold the clearest result long enough for comprehension and a clean edit.
+
+This is a decision framework, not a forced duration or marketing formula. Omit any movement the user's goal does not need.
+
+## Direct the screen
+
+- Start from a deliberately composed frame, not application-launch clutter.
+- Keep the pointer parked when it is not communicating something.
+- Make text, previews, terminal height, and simulator/device content legible at delivery resolution.
+- Prefer one decisive action over exploratory menu movement.
+- Show representative results rather than every file when repetition adds no proof. Show every platform or output family that narration explicitly claims.
+- Use an observable exit condition for builds and long-running commands. Avoid dramatic pauses or arbitrary sleeps.
+
+## Write for voice
+
+- Give the viewer information they cannot get merely by reading the screen.
+- Keep each line short enough for its measured visual interval.
+- Pronounce command names and symbols naturally for the selected voice service.
+- Preserve the user's approved spelling and pronunciation lexicon across every episode. Do not split an acronym into space-separated letters unless the user explicitly approved that rendering for the selected voice.
+- Do not synchronize final narration against estimated timing. In capture-first mode, exact wording follows the accepted capture and event log. In audio-first mode, approve the exact wording first, measure the returned audio, and use those measurements to lock the visual timing before capture.
+- Use normal punctuation and paragraph breaks for a conversational voice. Do not add synthetic pause tags unless the user explicitly asks for them.
+- Leave captions selectable unless the user asks for burned-in text.
+
+## Edit and review
+
+Reject a take when focus lands in the wrong control, text enters a source file, the command is obscured, proof is missing, a permission dialog appears, or dead time materially harms pacing. Correct the permanent recorder and create a new numbered take. Do not conceal a broken workflow with edits that misrepresent what happened.

package/skills/technical-demo-videos/references/vertical-social-video.md

@@ -0,0 +1,24 @@
+# Vertical and social-media derivatives
+
+Read this only when the user asks for a TikTok, YouTube Shorts, Instagram Reels, or other vertical/social deliverable.
+
+## Preserve a clean master
+
+Keep the approved horizontal capture and clean audio as source masters. Produce vertical framing, split-screen layouts, dynamic captions, and platform-specific safe areas as separate derivatives so one social format never damages the reusable master.
+
+## Choose the composition deliberately
+
+Prefer these approaches in order:
+
+1. record a native `9:16` composition when the workflow can be staged legibly in that space;
+2. build a deterministic split-screen composition for programming demos, such as code/terminal on one half and simulator, game, animation, narrator, or result on the other;
+3. reframe a horizontal master with explicit timed points of interest;
+4. use automatic subject tracking only when the visual target genuinely moves unpredictably.
+
+AI is useful but not inherently required. Deterministic crops can follow recorder events, cursor coordinates, editor focus, simulator bounds, or authored keyframes. AI becomes useful for face/object tracking, automatic highlight selection, transcription, word-level caption timing, speaker detection, and semantic layout decisions.
+
+## Captions and safe areas
+
+Dynamic word- or phrase-level captions are often burned into social derivatives because viewers may watch muted and platforms overlay their own controls. They must remain optional deliverables: keep the clean master and external SRT, then create a separately named captioned vertical version only when requested.
+
+Use the target platform's current resolution, duration, and safe-area rules at production time; verify those rules from official platform documentation because they can change.

package/skills/technical-demo-videos/references/vscode-default-profile.md

@@ -0,0 +1,49 @@
+# VS Code recording profile
+
+Use this reference to calibrate a workstation once, save the accepted values with the production package, and reuse them across projects and retakes. The numbers below are an example profile for a 4K display, not universal defaults.
+
+## Values the profile owns
+
+- capture display number and physical resolution;
+- logical display size and minimum VS Code window size;
+- whether an auxiliary panel must be hidden and the shortcut that does it;
+- whether Explorer remains visible and on which side;
+- whether Welcome is disabled before recording;
+- terminal divider detection range, drag coordinate, target height, and tolerance;
+- terminal focus shortcut after an editor takes focus;
+- file-preview associations needed by the demonstration.
+
+Keep these values in the declarative recipe or pass an equivalent profile to `prepare_default_vscode()`. Do not spread coordinates and shortcuts across project-specific action code.
+
+## Example 4K profile
+
+- Physical capture: 3840 × 2160.
+- Logical display: 1920 × 1080.
+- VS Code minimum: 1850 × 1000 logical points.
+- Terminal divider drag: logical `x=645` to `y=720`, verified within 8 points.
+- Terminal open delay: about 1.5 seconds before divider detection.
+- Main Explorer remains visible; unrelated auxiliary panels and Welcome are removed before capture.
+
+Recalibrate those values for a different display, scaling mode, VS Code layout, keybinding, or panel placement.
+
+## Integrated terminal preparation
+
+1. Open a uniquely identifiable disposable project in a new VS Code window.
+2. Apply the profile's panel state and close unrelated tabs before capture.
+3. Use `Terminal` → `New Terminal` after targeting that exact window.
+4. Wait for the panel to finish opening.
+5. Capture a temporary screenshot and detect the real horizontal divider across several columns. A fresh folder does not guarantee a fresh panel height.
+6. Drag the detected separator to the profile's target height.
+7. Capture the layout again and verify the divider is within the configured tolerance. Abort before recording if detection fails; never guess the starting coordinate.
+8. Store diagnostics under the run's temporary helper directory so cleanup removes them.
+9. Leave the terminal open when preparation finishes.
+
+Do not resize with repeated Command Palette steps: they are slower, visible, and dependent on unknown starting height. Do not send the terminal-focus shortcut immediately after creating the terminal because a toggle-style binding may close it. Use it later, after an editor or preview has taken focus and immediately before typing the command.
+
+## Preview behavior
+
+If a source format needs a visual preview, configure and preflight the VS Code association before capture. Open the file directly into that preview during the take. Do not expose the editor-selection menu or change a user setting inside the demonstrated project merely for recording.
+
+## Recording boundary
+
+All profile preparation happens before capture. The first recorded action belongs to the approved story. Save a newly accepted profile instead of rediscovering the same coordinates during every episode.

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

@@ -0,0 +1,42 @@
+# YouTube master quality gate
+
+Read this before promoting an approved edit to `<slug>-final.mp4` or creating
+its YouTube upload manifest.
+
+An MP4 can report 3840×2160 and still be a poor delivery master. Do not treat
+resolution or successful muxing as sufficient. A stream-copied synchronization
+preview remains a preview.
+
+For horizontal 4K screen demonstrations using an approved capture profile, create
+the final upload master with:
+
+- MP4, H.264 High Profile, progressive, yuv420p;
+- 3840×2160 with no baked-in letterboxing;
+- constant 30 FPS unless the approved content genuinely needs its native 60 FPS;
+- BT.709 primaries, transfer, and matrix metadata;
+- AAC stereo audio at 48 kHz and 384 kbps;
+- the moov atom at the front (`faststart`);
+- a deliberate variable bitrate. The bundled helper uses the lower edge of
+  YouTube's current SDR upload ranges: 35 Mbps for 4K at 24–30 FPS and 53 Mbps
+  for 4K at 48–60 FPS. It also selects the documented standard/high-frame-rate
+  defaults for 1440p, 1080p, and 720p.
+
+These bitrate and codec recommendations can change. Before creating a delivery
+master, verify them against YouTube's current official
+[recommended upload encoding settings](https://support.google.com/youtube/answer/1722171).
+If the published range changed, pass its lower bound with `--video-bitrate` and
+record the source and chosen value in the production plan.
+
+Run:
+
+```bash
+python3 scripts/normalize_youtube_master.py APPROVED_EDIT.mp4 FINAL.mp4
+```
+
+The tool refuses to overwrite the output and verifies resolution, CFR, codec,
+profile, pixel format, BT.709, audio, container, and bitrate before completing.
+Do not create an upload manifest when this gate fails.
+
+After upload, keep the video private until the intended high-resolution
+representations are actually available. YouTube chooses the playback codecs;
+the upload API cannot request AVC, VP9, or AV1 and offers no reprocess action.

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)