Tracking: drop Hyperframes `workers: 1` workaround once heygen-com/hyperframes#334 ships

[kiyeonjeon21]

Why

We currently force workers: 1 everywhere we invoke the Hyperframes producer because auto-worker mode times out on trivial image-only compositions. This is a workaround for an upstream bug, not the desired behavior.

State of code (2026-04-29)

workers: 1 is hard-coded as the default in 5 places:

• packages/cli/src/pipeline/renderers/hyperframes.ts:38 — workers: options.workers ?? 1
• packages/cli/src/commands/_shared/scene-render.ts:132 — workers: opts.workers ?? 1
• packages/cli/src/tools/manifest/scene.ts:316 — manifest documents "Default 1"
• packages/cli/src/commands/scene.ts:1141 — validator allows 1-16
• packages/cli/src/commands/_shared/scene-render.test.ts:47 — test expects workers: 1

This was the right call given upstream behavior — sequential renders complete (~9s) where auto-mode times out (~45s) on videoCount: 0 compositions. Documented in docs/upstream/hyperframes-auto-worker-timeout.md.

Upstream

Filed: heygen-com/hyperframes#334 — "producer@0.4.4: auto-worker mode times out on trivial image-only compositions"

Suggested upstream fixes:

1. Auto-worker should detect videoCount === 0 and fall back to workers: 1
2. Tune the auto-worker parallel timeout
3. Document workers: 1 as safe default

What this issue tracks

• Watch producer@0.4.4: auto-worker mode times out on trivial image-only compositions heygen-com/hyperframes#334 for resolution
• When upstream ships the fix in a new @hyperframes/producer release:
  • Bump dependency
  • Drop the ?? 1 defaults at the 5 sites above (let upstream auto-mode decide)
  • Keep --workers <n> as an override for power users
  • Update docs/upstream/hyperframes-auto-worker-timeout.md (or remove it)
  • Update test expectations

Reference

• Upstream: producer@0.4.4: auto-worker mode times out on trivial image-only compositions heygen-com/hyperframes#334
• Local discovery doc: docs/upstream/hyperframes-auto-worker-timeout.md
• Workaround landed in: 634ef1d

[kiyeonjeon21]

Maintainer note: this is no longer blocked on the upstream issue.

heygen-com/hyperframes#334 is closed as fixed, and this repo currently resolves @hyperframes/producer to 0.4.10, which is newer than the upstream fix version mentioned there (0.4.6). The remaining work is local cleanup and verification.

Before closing this, we should do a small PR that:

• verifies auto-worker rendering on a trivial image-only composition and at least one normal scene project
• removes or relaxes the hardcoded workers: 1 defaults where appropriate
• keeps --workers <n> as an explicit override
• updates CLI help / manifest text that currently says default 1
• updates tests that assert workers: 1

So the issue is still valid, but its status has changed from “wait for upstream” to “remove the local workaround now that upstream is fixed”.