hyperframes

1#!/usr/bin/env bash2# HyperFrames setup for Hermes.3#4# Verifies Node >= 22 and FFmpeg, installs the `hyperframes` CLI globally,5# pre-caches `chrome-headless-shell`, and runs `hyperframes doctor`.6#7# Pins `hyperframes@>=0.4.2` so the OpenClaw/Chromium-147 fix from8# https://github.com/heygen-com/hyperframes/issues/294 (commit 4c72ba4)9# is always present — the engine auto-detects `HeadlessExperimental.beginFrame`10# support and falls back to screenshot capture otherwise.11#12# Idempotent: safe to re-run.13 14set -euo pipefail15 16MIN_NODE_MAJOR=2217MIN_HYPERFRAMES_VERSION="0.4.2"18 19red()    { printf '\033[31m%s\033[0m\n' "$*"; }20green()  { printf '\033[32m%s\033[0m\n' "$*"; }21yellow() { printf '\033[33m%s\033[0m\n' "$*"; }22bold()   { printf '\033[1m%s\033[0m\n' "$*"; }23 24bold "==> HyperFrames setup"25 26# --- 1. Node.js --------------------------------------------------------------27 28if ! command -v node >/dev/null 2>&1; then29  red "✗ Node.js is not installed."30  echo "   Install Node.js >= ${MIN_NODE_MAJOR} (nvm, Homebrew, or your package manager) and re-run."31  exit 132fi33 34node_version="$(node --version | sed 's/^v//')"35node_major="$(echo "$node_version" | cut -d. -f1)"36if [ "$node_major" -lt "$MIN_NODE_MAJOR" ]; then37  red "✗ Node.js ${node_version} is too old. HyperFrames requires Node.js >= ${MIN_NODE_MAJOR}."38  echo "   Upgrade with 'nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}' or your package manager."39  exit 140fi41green "✓ Node.js ${node_version}"42 43# --- 2. FFmpeg ---------------------------------------------------------------44 45if ! command -v ffmpeg >/dev/null 2>&1; then46  red "✗ FFmpeg is not installed."47  case "$(uname -s)" in48    Linux*)   echo "   sudo apt-get install -y ffmpeg   # Debian/Ubuntu"49              echo "   sudo dnf install -y ffmpeg       # Fedora/RHEL";;50    Darwin*)  echo "   brew install ffmpeg";;51    MINGW*|MSYS*|CYGWIN*) echo "   winget install Gyan.FFmpeg";;52    *)        echo "   See https://ffmpeg.org/download.html";;53  esac54  exit 155fi56green "✓ FFmpeg $(ffmpeg -version 2>&1 | head -1 | awk '{print $3}')"57 58# --- 3. npm ------------------------------------------------------------------59 60if ! command -v npm >/dev/null 2>&1; then61  red "✗ npm is not installed (should ship with Node.js)."62  exit 163fi64 65# --- 4. Install / upgrade hyperframes CLI -----------------------------------66 67bold "==> Installing hyperframes CLI (>= ${MIN_HYPERFRAMES_VERSION})"68 69current_hyperframes=""70if command -v hyperframes >/dev/null 2>&1; then71  current_hyperframes="$(hyperframes --version 2>/dev/null | tail -1 | sed 's/^v//')"72fi73 74if [ -n "$current_hyperframes" ]; then75  yellow "   Found hyperframes ${current_hyperframes}"76fi77 78# Always install/upgrade to >= MIN version.79# Using 'latest' so we pick up any newer auto-detect/capture fixes.80if ! npm install -g "hyperframes@latest" >/dev/null 2>&1; then81  red "✗ npm install -g hyperframes@latest failed."82  echo "   Try: sudo npm install -g hyperframes@latest"83  echo "   Or use a user-scoped npm prefix: npm config set prefix ~/.npm-global && export PATH=\"\$HOME/.npm-global/bin:\$PATH\""84  exit 185fi86 87installed_version="$(hyperframes --version 2>/dev/null | tail -1 | sed 's/^v//')"88green "✓ hyperframes ${installed_version} installed globally"89 90# Sanity-check minimum version.91version_ge() {92  # version_ge A B  →  true if A >= B93  [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -1)" = "$2" ]94}95if ! version_ge "$installed_version" "$MIN_HYPERFRAMES_VERSION"; then96  red "✗ hyperframes ${installed_version} is below required minimum ${MIN_HYPERFRAMES_VERSION}."97  echo "   Try 'npm install -g hyperframes@latest' or 'sudo npm install -g hyperframes@latest'."98  exit 199fi100 101# --- 5. Pre-cache chrome-headless-shell --------------------------------------102#103# Chromium 147+ removed HeadlessExperimental.beginFrame. System Chrome (e.g.104# /usr/bin/google-chrome) can't render with the fast path, so the engine105# auto-detects and falls back to screenshot mode — but BeginFrame mode is106# faster and produces higher-quality output. Install chrome-headless-shell107# up front so the engine picks it over system Chrome.108 109bold "==> Pre-caching chrome-headless-shell (for best render quality)"110 111if ! npx --yes puppeteer browsers install chrome-headless-shell >/dev/null 2>&1; then112  yellow "⚠ Could not pre-install chrome-headless-shell."113  yellow "  Rendering will still work via screenshot-mode fallback (slower)."114  yellow "  If you hit HeadlessExperimental.beginFrame errors:"115  yellow "     export PRODUCER_FORCE_SCREENSHOT=true"116  yellow "  See references/troubleshooting.md."117else118  green "✓ chrome-headless-shell installed"119fi120 121# --- 6. Doctor ---------------------------------------------------------------122 123bold "==> Running hyperframes doctor"124 125if hyperframes doctor; then126  green "✓ HyperFrames is ready"127  echo128  echo "   Scaffold a project:   npx hyperframes init my-video"129  echo "   Preview:              npx hyperframes preview"130  echo "   Render:               npx hyperframes render"131else132  yellow "⚠ hyperframes doctor reported issues."133  yellow "  See references/troubleshooting.md or re-run 'hyperframes doctor'."134  exit 1135fi136