hyperframes 0.8.216 → 0.8.218

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/dist/{add-2RWN7JAI.js → add-6TACQX2U.js} +14 -14
  2. package/dist/{agentPromptGenerator-RVE5RWTH.js → agentPromptGenerator-2OHH7TQF.js} +8 -8
  3. package/dist/{animatedGifPrep-I32BS5HI.js → animatedGifPrep-3TCOKQRQ.js} +8 -8
  4. package/dist/api.js +19 -19
  5. package/dist/{asset-YLZ5UGVE.js → asset-XGF7DP6H.js} +2 -2
  6. package/dist/{assetCataloger-B4KOZO3V.js → assetCataloger-23H37VZ5.js} +9 -9
  7. package/dist/{audio-VUOJ7MOJ.js → audio-IIU2JTO2.js} +19 -19
  8. package/dist/{auth-3UL65CN7.js → auth-YXS6A6HO.js} +8 -7
  9. package/dist/{autoUpdate-FEK5AHLP.js → autoUpdate-25S52Q5S.js} +3 -3
  10. package/dist/{backgroundChecks-VJSQ3REH.js → backgroundChecks-I7EVP7FG.js} +4 -4
  11. package/dist/backgroundChecksWorker.js +4 -4
  12. package/dist/{batchRender-NC6SUDYN.js → batchRender-ESAPNTE3.js} +4 -4
  13. package/dist/{beats-KSUZ23LE.js → beats-STUURUTE.js} +13 -13
  14. package/dist/{benchmark-TRVQ7EPQ.js → benchmark-APCKXZV4.js} +11 -11
  15. package/dist/{browser-3LJ3SLQ4.js → browser-24AXY6XT.js} +6 -6
  16. package/dist/{bundleWithLocalizedFonts-Y7VGIRFK.js → bundleWithLocalizedFonts-D5DHHE3J.js} +2 -2
  17. package/dist/{capture-NC5OO4D2.js → capture-6DJ63B7N.js} +3 -3
  18. package/dist/{capture-NT2SOO5J.js → capture-CPDVGCHU.js} +16 -16
  19. package/dist/{captureCompositionFrame-PAJRNURH.js → captureCompositionFrame-UQWCB4GS.js} +13 -13
  20. package/dist/{catalog-BOGZ2BQD.js → catalog-Q23ML47J.js} +14 -14
  21. package/dist/{catch-up-FGF5SAEW.js → catch-up-RS3QCE4R.js} +7 -7
  22. package/dist/{check-IG6NIMSC.js → check-CTCEOX24.js} +40 -40
  23. package/dist/{checkAudio-6B2FKTIU.js → checkAudio-SINGW2W7.js} +12 -12
  24. package/dist/{checkBrowser-D6MZRCTH.js → checkBrowser-PDM2H472.js} +34 -34
  25. package/dist/{chunk-UGQFQDSV.js → chunk-35JKCWYI.js} +1 -1
  26. package/dist/{chunk-I3VXWMQW.js → chunk-3MTNYVWM.js} +5 -5
  27. package/dist/{chunk-3S2WWGJJ.js → chunk-3O6TQMFR.js} +3 -3
  28. package/dist/{chunk-MYHAS5U2.js → chunk-3VIICMJF.js} +1 -1
  29. package/dist/{chunk-IVRKWQTX.js → chunk-4I7KQWZS.js} +1 -1
  30. package/dist/{chunk-JFFQWMNE.js → chunk-4OWVRHSV.js} +5 -5
  31. package/dist/{chunk-URUUGFZD.js → chunk-4RHUYKVK.js} +3 -3
  32. package/dist/{chunk-RIGQABEL.js → chunk-562GRMWD.js} +1 -1
  33. package/dist/{chunk-MU66MHZB.js → chunk-576ATOOU.js} +2 -2
  34. package/dist/{chunk-OWU2BURB.js → chunk-5JMHTBGN.js} +2 -2
  35. package/dist/{chunk-KYXBPFI7.js → chunk-5UIODBMI.js} +8 -5
  36. package/dist/{chunk-SBBYMUWY.js → chunk-67YDBMLK.js} +1 -1
  37. package/dist/{chunk-5XTOAZMR.js → chunk-A5MVD5IH.js} +1 -1
  38. package/dist/{chunk-DYHAZFK3.js → chunk-AU7VGKCP.js} +1 -1
  39. package/dist/{chunk-VAS6HQX3.js → chunk-BIROA7JM.js} +32 -3
  40. package/dist/{chunk-ZCHULPJZ.js → chunk-BLBMPEBX.js} +6 -0
  41. package/dist/{chunk-TQSKEMSL.js → chunk-BMM6KPEK.js} +3 -3
  42. package/dist/{chunk-FUSUFW2L.js → chunk-BRYOYBO5.js} +1 -1
  43. package/dist/{chunk-RN7RQBW3.js → chunk-BT5UT4XT.js} +2 -2
  44. package/dist/{chunk-CX4TSC7T.js → chunk-BWP7C7WY.js} +38 -27
  45. package/dist/{chunk-3AOXAXTA.js → chunk-C2G23WQQ.js} +1 -1
  46. package/dist/{chunk-MKL6JGDL.js → chunk-CPLOVCBR.js} +56 -20
  47. package/dist/{chunk-4MWUMT3T.js → chunk-DFLWN6Y3.js} +2 -2
  48. package/dist/{chunk-RH5Y75UX.js → chunk-DOZGTBDV.js} +2 -2
  49. package/dist/{chunk-RKS7GO4O.js → chunk-DWMI7CKI.js} +1 -1
  50. package/dist/{chunk-GHROWWUN.js → chunk-DWTFLQ3P.js} +33 -6
  51. package/dist/{chunk-ACAU2AK2.js → chunk-FQUPVW7G.js} +4 -4
  52. package/dist/{chunk-4EEVTNDU.js → chunk-G2E2DHH2.js} +3 -3
  53. package/dist/{chunk-OFJTXNRS.js → chunk-GEOYME4I.js} +3 -3
  54. package/dist/{chunk-6LQL2BVD.js → chunk-GHWV6PIS.js} +1 -1
  55. package/dist/{chunk-BTYR7Y3Z.js → chunk-H6LEUSAT.js} +2 -2
  56. package/dist/{chunk-RXQU3QM4.js → chunk-HOTGBCX7.js} +9 -9
  57. package/dist/{chunk-NWYJZAPP.js → chunk-HTBHG63K.js} +1 -1
  58. package/dist/{chunk-DFA5GTRJ.js → chunk-IEC36WFL.js} +1 -1
  59. package/dist/{chunk-2JV6FKNZ.js → chunk-ILCIWNPQ.js} +3 -3
  60. package/dist/{chunk-7VZEOCUY.js → chunk-J74ZUXVU.js} +1 -1
  61. package/dist/{chunk-MO6DJMZP.js → chunk-JH2AO4ZW.js} +2 -2
  62. package/dist/{chunk-4YIKQM4K.js → chunk-K5GGTJJV.js} +1 -1
  63. package/dist/{chunk-EB44YMQO.js → chunk-KUQOUWJ4.js} +3 -3
  64. package/dist/{chunk-7P76YIVS.js → chunk-LBZVTVG6.js} +1 -1
  65. package/dist/{chunk-BHWXSO6T.js → chunk-LGMRZWJS.js} +9 -3
  66. package/dist/{chunk-JOZQFSOV.js → chunk-LJB2PF6K.js} +1 -1
  67. package/dist/{chunk-ZRK7ZEWI.js → chunk-LYK7IGH4.js} +3 -3
  68. package/dist/{chunk-UVXIJYZY.js → chunk-MESSJFK3.js} +249 -298
  69. package/dist/{chunk-JF3RF6GS.js → chunk-MHZB6QSC.js} +1 -1
  70. package/dist/{chunk-6HJUC2VX.js → chunk-NEPGYMT3.js} +2 -2
  71. package/dist/{chunk-CBCZBHGK.js → chunk-NHXGFQWQ.js} +2 -2
  72. package/dist/{chunk-Z4W7ND2L.js → chunk-P34BNDC3.js} +6 -6
  73. package/dist/{chunk-SPFTXNKQ.js → chunk-P5ANVBAG.js} +16 -15
  74. package/dist/{chunk-GTKUQUZ6.js → chunk-RYBFHEMZ.js} +1 -1
  75. package/dist/{chunk-557ZJMFI.js → chunk-SFBFRIKF.js} +2 -2
  76. package/dist/{chunk-43USF7JF.js → chunk-SJYWAEKF.js} +9 -9
  77. package/dist/{chunk-ROUK3OL2.js → chunk-SVJAW3N3.js} +7 -7
  78. package/dist/{chunk-VDFY4FE5.js → chunk-SZMW32YW.js} +9 -9
  79. package/dist/{chunk-7RPXLY6U.js → chunk-TCV7N2UY.js} +1 -1
  80. package/dist/{chunk-634HSJ3J.js → chunk-TK7THLRO.js} +10 -3
  81. package/dist/{chunk-LGZP4IR2.js → chunk-U2EUCTYQ.js} +4 -4
  82. package/dist/{chunk-KBTXAUCZ.js → chunk-UWV753SJ.js} +1 -1
  83. package/dist/chunk-VLA6UJGH.js +139 -0
  84. package/dist/{chunk-U54ZBLTF.js → chunk-VLMPZRZC.js} +2 -2
  85. package/dist/{chunk-Q3OKLJ34.js → chunk-VMTLGFAP.js} +2 -2
  86. package/dist/{chunk-BYHG2T5X.js → chunk-VP5KECBU.js} +2 -2
  87. package/dist/{chunk-USQTLRSD.js → chunk-VTLIN7XN.js} +2 -2
  88. package/dist/{chunk-TBEU55KU.js → chunk-WHISG7MU.js} +1 -1
  89. package/dist/{chunk-YT4DR2UT.js → chunk-WSAGYFYU.js} +7 -7
  90. package/dist/{chunk-UIETUYFT.js → chunk-WUABYDXU.js} +1 -1
  91. package/dist/{chunk-UJEEURID.js → chunk-X4SGGGSG.js} +13 -13
  92. package/dist/{chunk-VPA5YKEY.js → chunk-XC2DA2IA.js} +2 -2
  93. package/dist/{chunk-QETCWXRM.js → chunk-XKG4VTT5.js} +4 -4
  94. package/dist/{chunk-PNE2Y42T.js → chunk-YATFRFNH.js} +1 -1
  95. package/dist/{chunk-EJTVBW42.js → chunk-YBW7HTJK.js} +2 -2
  96. package/dist/{chunk-PPMLF76Z.js → chunk-YSTBSLWY.js} +1 -1
  97. package/dist/{chunk-VZENYSX7.js → chunk-YXZ56JUN.js} +44 -33
  98. package/dist/{chunk-OPLEWQHF.js → chunk-Z5N3BHCQ.js} +1 -1
  99. package/dist/{chunk-QGMRSNG5.js → chunk-ZJNN53CS.js} +4 -3
  100. package/dist/{clean-WPLBDRSW.js → clean-MMKLFZD6.js} +19 -19
  101. package/dist/cli.js +57 -66
  102. package/dist/{cloud-VMSG2SJB.js → cloud-PYPEVKTI.js} +4 -4
  103. package/dist/{cloudrun-AXB4G6X2.js → cloudrun-5XEDIP77.js} +5 -5
  104. package/dist/commands/layout-audit.browser.js +7 -1
  105. package/dist/{compare-NVW3E74E.js → compare-5FYV3HXW.js} +31 -31
  106. package/dist/{compiler-GHX7QLHL.js → compiler-DVUV3DGB.js} +4 -4
  107. package/dist/{component-ZQAP7CBI.js → component-6WPGKSED.js} +3 -3
  108. package/dist/{compositions-FKHNCB6H.js → compositions-KF7WTF4B.js} +14 -14
  109. package/dist/{delete-XYC7FN6A.js → delete-KZFID7WD.js} +7 -7
  110. package/dist/{deploy-DOJS666X.js → deploy-JU22XTWD.js} +1 -1
  111. package/dist/{dist-3Q2DNDSR.js → dist-VNOJCTQR.js} +3 -3
  112. package/dist/{dist-KXFW5H5Q.js → dist-XXBCSQYF.js} +2 -2
  113. package/dist/{doctor-7CUFMW3Y.js → doctor-PI6KAIR5.js} +13 -13
  114. package/dist/{dotEnv-RPHCAUBZ.js → dotEnv-BGFXSQOA.js} +7 -5
  115. package/dist/{events-K7HUJ4DO.js → events-DE5M7353.js} +4 -4
  116. package/dist/{events-KGXVDZV7.js → events-GTCDNRHF.js} +6 -6
  117. package/dist/{feedback-F7WLYJGJ.js → feedback-WBXTSD7V.js} +26 -14
  118. package/dist/{ffmpeg-ZFHN4YZ2.js → ffmpeg-32BKO53L.js} +8 -8
  119. package/dist/{figma-7QKRKT5Q.js → figma-4EX6IU6D.js} +3 -3
  120. package/dist/fontLocalizeCli.js +11 -11
  121. package/dist/{get-XKPYG6IC.js → get-IDFMBDVJ.js} +7 -7
  122. package/dist/{gpuPolicy-A74BROG6.js → gpuPolicy-XALYIHRC.js} +8 -8
  123. package/dist/{grade-compare-7SR62TE5.js → grade-compare-IR6C2BDN.js} +32 -32
  124. package/dist/{heifImagePrep-XTCBHE3B.js → heifImagePrep-UT4MVMZK.js} +9 -9
  125. package/dist/{help-B7CXC4J5.js → help-LNFTZ33U.js} +1 -1
  126. package/dist/{history-3INEHHZ4.js → history-CVMBLNPB.js} +9 -9
  127. package/dist/hyperframe.manifest.json +1 -1
  128. package/dist/hyperframe.runtime.iife.js +26 -26
  129. package/dist/hyperframes-player.global.js +1 -1
  130. package/dist/{info-J3U63EFT.js → info-ZR6NR7MT.js} +10 -10
  131. package/dist/{init-2IEXXRG2.js → init-3H4OWHAC.js} +31 -31
  132. package/dist/{inspect-IRJABR66.js → inspect-DQB42FQJ.js} +32 -32
  133. package/dist/{installer-6JLQM6OJ.js → installer-OFIDWMYR.js} +5 -5
  134. package/dist/{keyframes-G2TSKZRL.js → keyframes-U74BN76I.js} +9 -9
  135. package/dist/{lambda-QFFFCFK3.js → lambda-UPISIKLU.js} +12 -12
  136. package/dist/{layout-INRUYIDJ.js → layout-JCWBIDXF.js} +32 -32
  137. package/dist/{lint-BHPBD7Z3.js → lint-EELAY2XS.js} +11 -11
  138. package/dist/{lintProject-SZIPPOJR.js → lintProject-I4XPWIQZ.js} +2 -2
  139. package/dist/{list-BGL5PH6J.js → list-MDRTOKTA.js} +7 -7
  140. package/dist/{localPage-MLFDX4Y6.js → localPage-BRAEGIND.js} +8 -8
  141. package/dist/{login-ABDL65L6.js → login-SOWERHQ6.js} +9 -8
  142. package/dist/{logout-CXGSSQ4Q.js → logout-6VFJ7WMW.js} +4 -4
  143. package/dist/{manager-DEKPCPWH.js → manager-PZ3USUXJ.js} +9 -9
  144. package/dist/{media-treatment-BQDTCBIT.js → media-treatment-A4CYTZKY.js} +16 -16
  145. package/dist/{media-use-ZRHFRO46.js → media-use-ZNTB7W6N.js} +85 -10
  146. package/dist/{models-SJIA5QDV.js → models-3LT54WBS.js} +12 -12
  147. package/dist/{motionShot-46J3W5UJ.js → motionShot-QLD2PDVI.js} +16 -16
  148. package/dist/{normalize-audio-UXAJSQKI.js → normalize-audio-HMYHPUV4.js} +12 -12
  149. package/dist/{open-DHRYP3N3.js → open-CYR6L7BV.js} +14 -14
  150. package/dist/{parakeetRunner-WKMM4TYU.js → parakeetRunner-52GLM62X.js} +14 -14
  151. package/dist/{pipeline-EIVKRUX2.js → pipeline-KZW5KLBK.js} +11 -11
  152. package/dist/{play-J5A7KHNF.js → play-KSX3VWZ5.js} +23 -23
  153. package/dist/{preflight-GKIQIXFQ.js → preflight-YJZS7QKG.js} +9 -9
  154. package/dist/{present-ZDXILGQJ.js → present-4Q3DIPFX.js} +19 -19
  155. package/dist/{preview-A2MLHZFF.js → preview-XAKLHB7C.js} +21 -21
  156. package/dist/{producer-NYWYRG4X.js → producer-Q46KBQS7.js} +1 -1
  157. package/dist/{projectConfig-DY6FHC7A.js → projectConfig-I6QNMRVV.js} +7 -7
  158. package/dist/{publication-N4WHPZOW.js → publication-JET7ZBWG.js} +3 -3
  159. package/dist/{publish-26W6VDND.js → publish-ZGW46SKV.js} +16 -16
  160. package/dist/{refresh-VJ4FQVH2.js → refresh-I6ITGHKL.js} +5 -4
  161. package/dist/{remove-background-JYUB75RB.js → remove-background-ENOMPCPD.js} +12 -12
  162. package/dist/{render-YPI6CDRS.js → render-33TSTTN7.js} +6 -6
  163. package/dist/{render-AQH2VMHO.js → render-5W2OBXKB.js} +82 -38
  164. package/dist/{render-JZWO3VX3.js → render-MS2SUV7X.js} +23 -23
  165. package/dist/{render-batch-GR2Y3F2S.js → render-batch-SDDZ3LM7.js} +6 -6
  166. package/dist/renderSetupWorker.js +2 -2
  167. package/dist/{resolver-LTLSX6DR.js → resolver-VLOUQ7I6.js} +5 -5
  168. package/dist/{sherpa-2DJ33LQP.js → sherpa-BWAZ26Z4.js} +13 -13
  169. package/dist/skills/hyperframes-cli/references/cloud.md +4 -4
  170. package/dist/skills/media-use/SKILL.md +3 -1
  171. package/dist/skills/media-use/audio/references/bgm.md +1 -1
  172. package/dist/skills/media-use/audio/references/requirements.md +9 -9
  173. package/dist/skills/media-use/audio/references/tts.md +11 -11
  174. package/dist/skills/media-use/audio/scripts/gemini-pipeline.test.mjs +1 -1
  175. package/dist/skills/media-use/audio/scripts/heygen-tts.mjs +1 -1
  176. package/dist/skills/media-use/audio/scripts/lib/audio-meta.test.mjs +1 -1
  177. package/dist/skills/media-use/audio/scripts/lib/heygen.mjs +23 -7
  178. package/dist/skills/media-use/audio/scripts/lib/heygen.test.mjs +68 -10
  179. package/dist/skills/media-use/audio/scripts/lib/tts.mjs +1 -1
  180. package/dist/skills/media-use/audio/scripts/lib/tts.test.mjs +2 -2
  181. package/dist/skills/media-use/references/operations.md +11 -9
  182. package/dist/skills/media-use/references/setup-providers.md +30 -30
  183. package/dist/skills/media-use/scripts/lib/heygen-cli.mjs +2 -2
  184. package/dist/skills/media-use/scripts/lib/telemetry.mjs +2 -1
  185. package/dist/skills/media-use/scripts/lib/telemetry.test.mjs +49 -4
  186. package/dist/{skills-OF7XMPKX.js → skills-MSNOVAV2.js} +8 -8
  187. package/dist/{skillsUpdateCheck-E3HPT4PS.js → skillsUpdateCheck-KNXASTIY.js} +4 -4
  188. package/dist/{snapshot-6F5XK22M.js → snapshot-UVDTIQFA.js} +39 -42
  189. package/dist/{src-JUJFZ6GC.js → src-AA5O4QMT.js} +7 -7
  190. package/dist/{src-UNN3TXHH.js → src-ZMJBQF2Y.js} +12 -10
  191. package/dist/{staticProjectServer-DLSH7DHS.js → staticProjectServer-MVGWIOTX.js} +19 -19
  192. package/dist/{status-TJFZFDGS.js → status-63BKLDVW.js} +40 -11
  193. package/dist/studio/assets/{hyperframes-player-D38lr2hR.js → hyperframes-player-C6V-KPv8.js} +1 -1
  194. package/dist/studio/assets/{index-C-DCQ7nQ.js → index-BLgjf320.js} +108 -108
  195. package/dist/studio/assets/{index-CJ28BLvq.js → index-C_LGrLz-.js} +1 -1
  196. package/dist/studio/index.html +1 -1
  197. package/dist/{studio-api-5YATSN7H.js → studio-api-SW5MW272.js} +11 -11
  198. package/dist/{studioServer-O3FSLOUF.js → studioServer-SXYAQVII.js} +51 -51
  199. package/dist/{telemetry-MMCJ2ORL.js → telemetry-3JM3MQK2.js} +6 -6
  200. package/dist/{telemetry-CY7V7FIN.js → telemetry-QHYJJAJU.js} +1 -1
  201. package/dist/{timeline-ZBJTZK6E.js → timeline-G6MHJ4MV.js} +21 -21
  202. package/dist/{tokens-JFYRYRDK.js → tokens-ROE4XPZP.js} +2 -2
  203. package/dist/{transcribe-QUMMQM34.js → transcribe-EINIBALD.js} +12 -12
  204. package/dist/{transcribe-UVQQ3OMR.js → transcribe-RGWPXLJ3.js} +20 -20
  205. package/dist/{updateCheck-VMMBGLTI.js → updateCheck-4RS5TICZ.js} +3 -3
  206. package/dist/{upgrade-4VYNPIFQ.js → upgrade-7ULCD6M6.js} +3 -3
  207. package/dist/{urlDownloader-EAPV3CZL.js → urlDownloader-KQOGUGS6.js} +7 -7
  208. package/dist/{validate-JJG6Q6IH.js → validate-QXQ3WRA4.js} +26 -26
  209. package/dist/{video-7MJZ7IYL.js → video-DDKGIJLL.js} +9 -9
  210. package/dist/warmCheck.js +40 -40
  211. package/package.json +1 -1
  212. package/dist/chunk-4WEWHZZO.js +0 -24
@@ -4,21 +4,21 @@
4
4
 
5
5
  Run `npx hyperframes auth status` to see what's configured and which engines a workflow will use (see the skill's **Preflight** section). Keys resolve in this order — **first match wins**:
6
6
 
7
- | Provider | Resolution order (first non-empty wins) | Local deps when used |
8
- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
9
- | **HeyGen** (TTS + BGM retrieval) | `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; `$HEYGEN_CONFIG_DIR` overrides the dir; written by `hyperframes auth login`) | none (REST) |
10
- | **ElevenLabs** (TTS fallback) | `$ELEVENLABS_API_KEY` | `pip install elevenlabs` |
11
- | **Lyria** (BGM fallback) | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY` | `pip install google-genai` |
12
- | **Kokoro** (TTS, no key) | always — final voice fallback | `pip install kokoro-onnx soundfile` |
13
- | **MusicGen** (BGM, no key) | always — final music fallback | `pip install transformers torch soundfile numpy` |
7
+ | Provider | Resolution order (first non-empty wins) | Local deps when used |
8
+ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
9
+ | **HeyGen** (TTS + BGM retrieval) | `$HEYGEN_ACCESS_TOKEN` → `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.hyperframes/credentials` (`$HYPERFRAMES_CONFIG_DIR` overrides the root; dev uses `dev/`) | none (REST) |
10
+ | **ElevenLabs** (TTS fallback) | `$ELEVENLABS_API_KEY` | `pip install elevenlabs` |
11
+ | **Lyria** (BGM fallback) | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY` | `pip install google-genai` |
12
+ | **Kokoro** (TTS, no key) | always — final voice fallback | `pip install kokoro-onnx soundfile` |
13
+ | **MusicGen** (BGM, no key) | always — final music fallback | `pip install transformers torch soundfile numpy` |
14
14
 
15
- `hyperframes auth login` (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo `.env`. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; both are tagged with `X-HeyGen-Source: cli`. OAuth CLI users can consume the web-plan free allowance for HeyGen TTS (10 min/month); API keys follow the normal API billing path. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — `hyperframes auth status` and `hyperframes doctor` both report whether those local deps are installed.
15
+ `hyperframes auth login` (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo `.env`. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; only OAuth is tagged with `X-HeyGen-Source: cli`. The server decides HyperFrames eligibility and charges; API keys use API billing. An expired or foreign OAuth session requires refresh/sign-in and never selects a saved API key. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — `hyperframes auth status` and `hyperframes doctor` both report whether those local deps are installed.
16
16
 
17
17
  ## Model caches & system dependencies
18
18
 
19
19
  Each command downloads its own model on first run and caches it under `~/.cache/hyperframes/`:
20
20
 
21
- - **TTS (HeyGen)** — no local deps; needs a HeyGen credential + `ffmpeg` on PATH (to transcode the mp3 response to `.wav`). Credential resolves like the CLI: `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; run `npx hyperframes auth login`). An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; both include `X-HeyGen-Source: cli` so the backend can apply CLI OAuth free usage.
21
+ - **TTS (HeyGen)** — no local deps; needs a HeyGen credential + `ffmpeg` on PATH (to transcode the mp3 response to `.wav`). Credential resolves like the CLI: the priority above; run `npx hyperframes auth login` for its isolated OAuth store. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; only OAuth includes `X-HeyGen-Source: cli`; the server selects billing from the verified credential.
22
22
  - **TTS (ElevenLabs)** — same as HeyGen: API key + `ffmpeg`.
23
23
  - **TTS (Kokoro)** — Kokoro-82M (~311 MB) + voices (~27 MB) in `tts/`. Requires Python 3.8+ with `kokoro-onnx` and `soundfile` (`pip install kokoro-onnx soundfile`). Non-English text also needs `espeak-ng` system-wide.
24
24
  - **BGM (Lyria)** — needs `$GEMINI_API_KEY` or `$GOOGLE_API_KEY` + `pip install google-genai`. No local model cache.
@@ -40,11 +40,11 @@ Gemini is an explicit alternative to the automatic provider order below. A
40
40
  request to use Gemini already chooses the provider; do not redirect that user
41
41
  to HeyGen sign-in. Read the Gemini section for its credential requirement.
42
42
 
43
- | Order | Provider | Env trigger | Voice IDs | Word timestamps | Audio format |
44
- | ----- | ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------- |
45
- | 1 | HeyGen (Starfish) | `$HEYGEN_ACCESS_TOKEN` / `$HEYGEN_API_KEY` / `~/.heygen/credentials` | UUIDs from `GET /v3/voices?engine=starfish`, or your cloned voice ids (`heygen-voice.mjs`) | **Yes** (`word_timestamps[]` in response) | mp3 → wav via ffmpeg |
46
- | 2 | ElevenLabs | `$ELEVENLABS_API_KEY` | UUIDs from elevenlabs.io dashboard | No | mp3 → wav via ffmpeg |
47
- | 3 | Kokoro-82M | always (local fallback) | `am_michael`, `af_heart`, … (54 voices) | No | wav direct |
43
+ | Order | Provider | Env trigger | Voice IDs | Word timestamps | Audio format |
44
+ | ----- | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------- |
45
+ | 1 | HeyGen (Starfish) | `$HEYGEN_ACCESS_TOKEN` / `$HEYGEN_API_KEY` / `~/.hyperframes/credentials` | UUIDs from `GET /v3/voices?engine=starfish`, or your cloned voice ids (`heygen-voice.mjs`) | **Yes** (`word_timestamps[]` in response) | mp3 → wav via ffmpeg |
46
+ | 2 | ElevenLabs | `$ELEVENLABS_API_KEY` | UUIDs from elevenlabs.io dashboard | No | mp3 → wav via ffmpeg |
47
+ | 3 | Kokoro-82M | always (local fallback) | `am_michael`, `af_heart`, … (54 voices) | No | wav direct |
48
48
 
49
49
  ```bash
50
50
  # Local Kokoro CLI
@@ -61,12 +61,12 @@ no CLI provider plumbing:
61
61
  The script resolves a HeyGen credential the same way the CLI does — first source
62
62
  wins: a host-injected OAuth `$HEYGEN_ACCESS_TOKEN` → `$HEYGEN_API_KEY` →
63
63
  `$HYPERFRAMES_API_KEY` → a project `.env` (auto-loaded,
64
- walks up ≤5 dirs) → `~/.heygen/credentials` (shared with heygen-cli;
65
- `$HEYGEN_CONFIG_DIR` overrides the dir). An OAuth login is sent as
66
- `Authorization: Bearer`; an API key as `X-Api-Key`; both include
67
- `X-HeyGen-Source: cli`. OAuth CLI users can consume the web-plan free allowance
68
- (10 min/month) before paid usage; API keys follow normal API billing. If the
69
- only credential is an expired OAuth token it stops with a hint to run
64
+ walks up ≤5 dirs) → `~/.hyperframes/credentials` (isolated from heygen-cli;
65
+ `$HYPERFRAMES_CONFIG_DIR` overrides the root; `HYPERFRAMES_ENV=dev` uses `dev/`). An OAuth login is sent as
66
+ `Authorization: Bearer`; an API key as `X-Api-Key`; only OAuth includes
67
+ `X-HeyGen-Source: cli`. The server decides HyperFrames eligibility and charges;
68
+ explicit API keys use API billing. An expired or foreign OAuth session stops
69
+ rather than selecting a saved API key, with a hint to run
70
70
  `npx hyperframes auth refresh`.
71
71
 
72
72
  ```bash
@@ -90,7 +90,7 @@ fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JS
90
90
  encoding: "utf8",
91
91
  env: {
92
92
  ...process.env,
93
- HEYGEN_CONFIG_DIR: config,
93
+ HYPERFRAMES_CONFIG_DIR: config,
94
94
  HEYGEN_API_KEY: "",
95
95
  HYPERFRAMES_API_KEY: "",
96
96
  GEMINI_API_KEY: "fixture-key",
@@ -13,7 +13,7 @@
13
13
  //
14
14
  // Flags: -o/--output (.wav → ffmpeg transcode; .mp3 → raw bytes), --words,
15
15
  // --voice (starfish id), --speed, --lang, --list.
16
- // Requires: $HEYGEN_API_KEY / OAuth ~/.heygen credentials and ffmpeg for .wav output.
16
+ // Requires: $HEYGEN_API_KEY / OAuth ~/.hyperframes credentials and ffmpeg for .wav output.
17
17
 
18
18
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
19
19
  import { dirname, resolve } from "node:path";
@@ -124,7 +124,7 @@ test("CLI partial run retains unselected voices, BGM and SFX", (t) => {
124
124
  encoding: "utf8",
125
125
  env: {
126
126
  ...process.env,
127
- HEYGEN_CONFIG_DIR: dir,
127
+ HYPERFRAMES_CONFIG_DIR: dir,
128
128
  HEYGEN_API_KEY: "",
129
129
  HYPERFRAMES_API_KEY: "",
130
130
  },
@@ -3,8 +3,8 @@ import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
3
3
  // pipeline. The credential resolver matches the hyperframes CLI auth: first
4
4
  // usable source wins — a host gateway ($HEYGEN_API_BASE with its own
5
5
  // $HEYGEN_API_KEY) → a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
6
- // $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
7
- // credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
6
+ // $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.hyperframes/
7
+ // credentials (OAuth never falls back to an API key; $HYPERFRAMES_CONFIG_DIR
8
8
  // overrides the dir). $HEYGEN_API_BASE moves every request to that host, as it
9
9
  // does for the heygen CLI; plain HTTP needs $HEYGEN_ALLOW_HTTP=1, as there.
10
10
  // Vendored so the skill ships standalone. Pure node.
@@ -20,7 +20,8 @@ export const HEYGEN_BASE = "https://api.heygen.com/v3";
20
20
  // in the clear, so it needs $HEYGEN_ALLOW_HTTP=1, the heygen CLI's own rule.
21
21
  export function heygenBase() {
22
22
  const host = process.env.HEYGEN_API_BASE?.trim().replace(/\/+$/, "");
23
- if (!host) return HEYGEN_BASE;
23
+ if (!host)
24
+ return process.env.HYPERFRAMES_ENV === "dev" ? "https://api.dev.heygen.com/v3" : HEYGEN_BASE;
24
25
  if (host.startsWith("http://") && process.env.HEYGEN_ALLOW_HTTP !== "1")
25
26
  throw new Error(
26
27
  `HEYGEN_API_BASE (${host}) uses HTTP, which sends the key in plaintext. Set HEYGEN_ALLOW_HTTP=1 to allow it.`,
@@ -104,7 +105,7 @@ export function heygenCredential() {
104
105
  }
105
106
 
106
107
  // heygenCredential's answer, or { unreadable: { file, code } } when the credentials path exists but cannot be read
107
- // (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
108
+ // (a folder, a locked ~/.hyperframes), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
108
109
  // Read without checking first, so the file cannot change between a check and the read.
109
110
  function resolveCredential() {
110
111
  const gatewayKey = hostGatewayKey();
@@ -116,7 +117,8 @@ function resolveCredential() {
116
117
  const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
117
118
  if (envKey) return { headers: { "X-Api-Key": envKey } };
118
119
 
119
- const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
120
+ const root = process.env.HYPERFRAMES_CONFIG_DIR || join(homedir(), ".hyperframes");
121
+ const file = join(root, ...(process.env.HYPERFRAMES_ENV === "dev" ? ["dev"] : []), "credentials");
120
122
  let raw;
121
123
  try {
122
124
  raw = readFileSync(file, "utf8").trim();
@@ -136,9 +138,23 @@ function resolveCredential() {
136
138
  }
137
139
  const oauth = cred.oauth;
138
140
  if (oauth?.access_token) {
141
+ const expectedClient =
142
+ process.env.HYPERFRAMES_OAUTH_CLIENT_ID ||
143
+ (process.env.HYPERFRAMES_ENV === "dev"
144
+ ? "9QoaiwCZov9O0cAkC4OZbR4p"
145
+ : "Zg3LF4FCLoeJoGs2YqMtZ17g");
146
+ const expectedTokenEndpoint =
147
+ process.env.HYPERFRAMES_OAUTH_TOKEN_URL ||
148
+ `https://api2.${process.env.HYPERFRAMES_ENV === "dev" ? "dev." : ""}heygen.com/v1/oauth/token`;
149
+ if (
150
+ !expectedClient ||
151
+ oauth.client_id !== expectedClient ||
152
+ oauth.token_endpoint !== expectedTokenEndpoint
153
+ )
154
+ return { expired: true };
139
155
  const expired = oauth.expires_at && new Date(oauth.expires_at).getTime() - 60_000 < Date.now();
140
156
  if (!expired) return { headers: { Authorization: `Bearer ${oauth.access_token}` } };
141
- if (!cred.api_key) return { expired: true };
157
+ return { expired: true };
142
158
  }
143
159
  if (cred.api_key) return { headers: { "X-Api-Key": cred.api_key } };
144
160
  return null;
@@ -176,7 +192,7 @@ export function heygenAuthHeaders() {
176
192
  "HeyGen OAuth token expired — run `npx hyperframes auth refresh` (or `npx hyperframes auth login`)",
177
193
  );
178
194
  throw new Error(
179
- "no HeyGen credentials — set $HEYGEN_API_KEY, or run `npx hyperframes auth login` (writes ~/.heygen/credentials)",
195
+ "no HyperFrames credentials — set $HEYGEN_API_KEY, or run `npx hyperframes auth login` (writes ~/.hyperframes/credentials)",
180
196
  );
181
197
  }
182
198
 
@@ -17,7 +17,10 @@ const HEYGEN_ENV = [
17
17
  "HEYGEN_ACCESS_TOKEN",
18
18
  "HEYGEN_API_KEY",
19
19
  "HYPERFRAMES_API_KEY",
20
- "HEYGEN_CONFIG_DIR",
20
+ "HYPERFRAMES_CONFIG_DIR",
21
+ "HYPERFRAMES_ENV",
22
+ "HYPERFRAMES_OAUTH_CLIENT_ID",
23
+ "HYPERFRAMES_OAUTH_TOKEN_URL",
21
24
  "HEYGEN_API_BASE",
22
25
  "HEYGEN_ALLOW_HTTP",
23
26
  ];
@@ -61,11 +64,13 @@ test("heygenAuthHeaders tags OAuth requests as CLI traffic and with the media-us
61
64
  withCleanHeygenEnv(() => {
62
65
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
63
66
  try {
64
- process.env.HEYGEN_CONFIG_DIR = dir;
67
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
65
68
  writeFileSync(
66
69
  join(dir, "credentials"),
67
70
  JSON.stringify({
68
71
  oauth: {
72
+ client_id: "Zg3LF4FCLoeJoGs2YqMtZ17g",
73
+ token_endpoint: "https://api2.heygen.com/v1/oauth/token",
69
74
  access_token: "at_test",
70
75
  expires_at: "2099-01-01T00:00:00Z",
71
76
  },
@@ -82,6 +87,31 @@ test("heygenAuthHeaders tags OAuth requests as CLI traffic and with the media-us
82
87
  });
83
88
  });
84
89
 
90
+ test("development audio uses the development client and isolated store", () => {
91
+ withCleanHeygenEnv(() => {
92
+ const dir = mkdtempSync(join(tmpdir(), "hf-dev-cred-"));
93
+ try {
94
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
95
+ process.env.HYPERFRAMES_ENV = "dev";
96
+ mkdirSync(join(dir, "dev"));
97
+ writeFileSync(
98
+ join(dir, "dev", "credentials"),
99
+ JSON.stringify({
100
+ oauth: {
101
+ access_token: "dev-at",
102
+ client_id: "9QoaiwCZov9O0cAkC4OZbR4p",
103
+ token_endpoint: "https://api2.dev.heygen.com/v1/oauth/token",
104
+ },
105
+ }),
106
+ );
107
+ assert.equal(heygenBase(), "https://api.dev.heygen.com/v3");
108
+ assert.equal(heygenAuthHeaders().Authorization, "Bearer dev-at");
109
+ } finally {
110
+ rmSync(dir, { recursive: true, force: true });
111
+ }
112
+ });
113
+ });
114
+
85
115
  test("a host-injected HEYGEN_ACCESS_TOKEN wins over an API key and is treated as OAuth", () => {
86
116
  withCleanHeygenEnv(() => {
87
117
  process.env.HEYGEN_ACCESS_TOKEN = "at_host";
@@ -106,11 +136,13 @@ test("heygenAuthMethod returns oauth for a live OAuth credential", () => {
106
136
  withCleanHeygenEnv(() => {
107
137
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
108
138
  try {
109
- process.env.HEYGEN_CONFIG_DIR = dir;
139
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
110
140
  writeFileSync(
111
141
  join(dir, "credentials"),
112
142
  JSON.stringify({
113
143
  oauth: {
144
+ client_id: "Zg3LF4FCLoeJoGs2YqMtZ17g",
145
+ token_endpoint: "https://api2.heygen.com/v1/oauth/token",
114
146
  access_token: "at_test",
115
147
  expires_at: "2099-01-01T00:00:00Z",
116
148
  },
@@ -127,7 +159,7 @@ test("heygenAuthMethod returns null with no credential at all", () => {
127
159
  withCleanHeygenEnv(() => {
128
160
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
129
161
  try {
130
- process.env.HEYGEN_CONFIG_DIR = dir; // no credentials file written
162
+ process.env.HYPERFRAMES_CONFIG_DIR = dir; // no credentials file written
131
163
  assert.equal(heygenAuthMethod(), null);
132
164
  } finally {
133
165
  rmSync(dir, { recursive: true, force: true });
@@ -135,6 +167,32 @@ test("heygenAuthMethod returns null with no credential at all", () => {
135
167
  });
136
168
  });
137
169
 
170
+ test("an expired or foreign OAuth login never falls back to a saved API wallet", () => {
171
+ withCleanHeygenEnv(() => {
172
+ const dir = mkdtempSync(join(tmpdir(), "hf-auth-payer-"));
173
+ try {
174
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
175
+ const credential = {
176
+ api_key: "other-wallet",
177
+ oauth: {
178
+ client_id: "Zg3LF4FCLoeJoGs2YqMtZ17g",
179
+ token_endpoint: "https://api2.heygen.com/v1/oauth/token",
180
+ access_token: "expired",
181
+ expires_at: "2000-01-01T00:00:00Z",
182
+ },
183
+ };
184
+ writeFileSync(join(dir, "credentials"), JSON.stringify(credential));
185
+ assert.deepEqual(heygenCredential(), { expired: true });
186
+ credential.oauth.expires_at = "2099-01-01T00:00:00Z";
187
+ credential.oauth.client_id = "shared-heygen-client";
188
+ writeFileSync(join(dir, "credentials"), JSON.stringify(credential));
189
+ assert.deepEqual(heygenCredential(), { expired: true });
190
+ } finally {
191
+ rmSync(dir, { recursive: true, force: true });
192
+ }
193
+ });
194
+ });
195
+
138
196
  test("loadEnvFromDir skips a .env folder and loads the .env file above it", () => {
139
197
  const root = mkdtempSync(join(tmpdir(), "heygen-env-"));
140
198
  const project = join(root, "project");
@@ -175,7 +233,7 @@ test("heygenAuthMethod returns null when the credentials path is a folder", () =
175
233
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
176
234
  try {
177
235
  mkdirSync(join(dir, "credentials"));
178
- process.env.HEYGEN_CONFIG_DIR = dir;
236
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
179
237
  assert.equal(heygenAuthMethod(), null);
180
238
  } finally {
181
239
  rmSync(dir, { recursive: true, force: true });
@@ -188,7 +246,7 @@ test("heygenAuthMethod returns null when the credentials path is a symlink loop"
188
246
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
189
247
  try {
190
248
  symlinkSync(join(dir, "credentials"), join(dir, "credentials"));
191
- process.env.HEYGEN_CONFIG_DIR = dir;
249
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
192
250
  assert.equal(heygenAuthMethod(), null);
193
251
  } finally {
194
252
  rmSync(dir, { recursive: true, force: true });
@@ -200,8 +258,8 @@ test("heygenAuthHeaders says to fix an unreadable credentials path, and to log i
200
258
  withCleanHeygenEnv(() => {
201
259
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
202
260
  try {
203
- process.env.HEYGEN_CONFIG_DIR = dir;
204
- assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
261
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
262
+ assert.throws(() => heygenAuthHeaders(), /no HyperFrames credentials/);
205
263
  mkdirSync(join(dir, "credentials"));
206
264
  assert.equal(heygenCredential(), null);
207
265
  assert.throws(
@@ -276,12 +334,12 @@ test("a base that isn't HeyGen's gets no stored or host OAuth credential, only a
276
334
  withCleanHeygenEnv(() => {
277
335
  const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
278
336
  try {
279
- process.env.HEYGEN_CONFIG_DIR = dir;
337
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
280
338
  writeFileSync(join(dir, "credentials"), JSON.stringify({ api_key: "hg_stored" }));
281
339
  process.env.HEYGEN_ACCESS_TOKEN = "at_host";
282
340
  process.env.HEYGEN_API_BASE = "https://proxy.example.com";
283
341
  assert.equal(heygenCredential(), null);
284
- assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
342
+ assert.throws(() => heygenAuthHeaders(), /no HyperFrames credentials/);
285
343
  // HeyGen's own hosts keep every credential source.
286
344
  process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com";
287
345
  assert.equal(heygenAuthMethod(), "oauth");
@@ -2,7 +2,7 @@ import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
2
2
  // tts.mjs — multi-provider TTS for the media audio engine. The provider chain,
3
3
  // auto-detected from env, is the one documented in ../SKILL.md:
4
4
  //
5
- // 1. HeyGen (Starfish) — $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen.
5
+ // 1. HeyGen (Starfish) — $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.hyperframes.
6
6
  // Direct v3 REST (NOT `hyperframes tts`, which in the published build is
7
7
  // Kokoro-only and silently ignores a HeyGen key). Returns word_timestamps
8
8
  // in the same call, so no separate transcribe pass.
@@ -209,7 +209,7 @@ test(
209
209
  );
210
210
 
211
211
  test("pickProvider heygen with an unreadable credentials path says to fix that path", () => {
212
- const saved = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY", "HEYGEN_CONFIG_DIR"].map((k) => [
212
+ const saved = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY", "HYPERFRAMES_CONFIG_DIR"].map((k) => [
213
213
  k,
214
214
  process.env[k],
215
215
  ]);
@@ -217,7 +217,7 @@ test("pickProvider heygen with an unreadable credentials path says to fix that p
217
217
  try {
218
218
  delete process.env.HEYGEN_API_KEY;
219
219
  delete process.env.HYPERFRAMES_API_KEY;
220
- process.env.HEYGEN_CONFIG_DIR = dir;
220
+ process.env.HYPERFRAMES_CONFIG_DIR = dir;
221
221
  mkdirSync(join(dir, "credentials"));
222
222
  assert.throws(() => pickProvider("heygen"), /fix or remove that path/);
223
223
  } finally {
@@ -6,8 +6,11 @@ command. Instead it points you at the right local tool (decision OP1). Run the
6
6
  tool, then register the output with `resolve --from <output> --type <type>` so the
7
7
  result lands in the ledger and the global cache like any other asset.
8
8
 
9
- All tools below are local and free. ffmpeg is assumed present (it backs the
10
- engine already).
9
+ The ffmpeg and local-model operations below run locally. Direct `heygen` recipes
10
+ use the HeyGen CLI's own login and HeyGen/API billing; they do not inherit a
11
+ HyperFrames subscription. Use those recipes only when that separate payer was
12
+ selected. `hyperframes media-use resolve` uses the HyperFrames-selected credential.
13
+ ffmpeg is assumed present (it backs the engine already).
11
14
 
12
15
  ## Cut / trim: keep a slice
13
16
 
@@ -238,21 +241,19 @@ GENERATES. Two paths, best-for-the-machine picked automatically:
238
241
  ## Generate: video (`resolve --type video`, HeyGen avatar first)
239
242
 
240
243
  `resolve --type video "<intent>"` is the default path. It generates a
241
- script-driven HeyGen avatar video first (the free-usage allowance — OAuth
242
- sessions ride the web-plan free avatar-video quota where eligible, API keys
243
- follow normal API billing), falling back to local generative LTX only when
244
+ script-driven HeyGen avatar video first using the HyperFrames-selected credential
245
+ (the server decides eligibility and charges; explicit API keys use API billing), falling back to local generative LTX only when
244
246
  HeyGen is unavailable, uncredentialed, or `--local-only` is passed. The two
245
247
  are non-substitutable outputs (a real presenter vs. a generic generative
246
248
  clip), so treat the fallback as "HeyGen wasn't reachable," not "upgrade the
247
249
  quality":
248
250
 
249
- - **HeyGen avatar video (default, free for new API users):**
251
+ - **HeyGen avatar video (default):**
250
252
  The CLI-bundled provider shells the
251
253
  `heygen` CLI — never the raw API — auto-picking a public avatar and a
252
254
  starfish voice (override with `--avatar-id`/`--voice-id`, threaded through
253
255
  as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,
254
- the provider prints an onboarding recommendation (avatar video is free for
255
- new API users — sign in) to stderr and falls through to LTX instead of
256
+ the provider prints a HyperFrames sign-in recommendation to stderr and falls through to LTX instead of
256
257
  hard-failing.
257
258
  - **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`
258
259
  ladder bundled in the HyperFrames CLI. Generative clips
@@ -268,7 +269,8 @@ Read-only discovery (`avatar list`, `voice list`) doesn't need it.
268
269
  For structured bodies `resolve --type video` doesn't expose yet (a specific
269
270
  `avatar_id`/`voice_id` combination beyond the ctx overrides, or a
270
271
  pre-recorded `audio_url` instead of a script), the raw `heygen video create`
271
- recipe below remains the escape hatch:
272
+ recipe below remains the escape hatch. This direct command uses the separate
273
+ HeyGen CLI credential and HeyGen/API billing, not the HyperFrames subscription:
272
274
 
273
275
  ```bash
274
276
  # discover an avatar + a starfish voice, then create + wait
@@ -1,15 +1,15 @@
1
1
  # Setup and providers — install, auth, RAM ladders, forcing a provider
2
2
 
3
- ## Setup — install heygen first (free-usage path)
3
+ ## Setup — install the helper and sign in to HyperFrames
4
4
 
5
5
  Install the HeyGen CLI through its [verified release instructions](https://developers.heygen.com/cli), then run:
6
6
 
7
7
  ```bash
8
- heygen update # free usage needs the OAuth-capable CLI (v0.3.0+)
9
- heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
8
+ heygen update # requires v0.3.0+
9
+ npx hyperframes auth login # dedicated HyperFrames OAuth session
10
10
  ```
11
11
 
12
- This unlocks the FREE path for bgm/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
12
+ HyperFrames owns the OAuth session in `~/.hyperframes/credentials` and supplies an access-only temporary credential to the HeyGen helper. Signing into `heygen` separately does not configure this path. The server decides subscription eligibility, free allowances and charges; an explicit API key uses API billing. **media-use requires heygen >= v0.3.0 uniformly.** Verify setup with:
13
13
 
14
14
  ```bash
15
15
  npx hyperframes media-use resolve --doctor
@@ -30,25 +30,25 @@ message (for example "add a key in Settings > Account") as written.
30
30
 
31
31
  ## Providers
32
32
 
33
- media-use holds no keys; every external tool owns its auth. Generation is
34
- centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
35
- before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects from
33
+ HyperFrames selects the credential for its HeyGen media helpers. Install
34
+ `heygen` and sign in with `hyperframes auth login` before resolving
35
+ bgm/sfx/image/icon/voice/avatar-video; music and sound effects from
36
36
  a host app's own tools need none of it. Local tools are opt-in
37
37
  alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
38
38
  transcription, and LTX for local video generation. `resolve` spec-checks
39
39
  AVAILABLE RAM for those local ladders inside the CLI (the image tiers are listed
40
40
  in `references/operations.md`).
41
41
 
42
- | Type | Provider / path |
43
- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
- | bgm | heygen catalog free-usage path; a host app's own music tools come first |
45
- | sfx | Openverse (CC0 / CC BY, no account), bundled library offline; a host app's own sound tools come first |
46
- | image | heygen search free-usage path; optional local mflux; codex `image_gen` upsell |
47
- | voice | heygen tts free-usage path; optional local **Kokoro** (free, on-device) |
48
- | icon | heygen asset search free-usage path |
49
- | logo | theSVG (thesvg.org), then GitHub org avatar, then domain favicon (all free) |
50
- | grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback |
51
- | video | heygen avatar video free-usage path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
42
+ | Type | Provider / path |
43
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
+ | bgm | heygen catalog HyperFrames-authenticated path; a host app's own music tools come first |
45
+ | sfx | Openverse (CC0 / CC BY, no account), bundled library offline; a host app's own sound tools come first |
46
+ | image | heygen search HyperFrames-authenticated path; optional local mflux; codex `image_gen` upsell |
47
+ | voice | heygen tts HyperFrames-authenticated path; optional local **Kokoro** (free, on-device) |
48
+ | icon | heygen asset search HyperFrames-authenticated path |
49
+ | logo | theSVG (thesvg.org), then GitHub org avatar, then domain favicon (all free) |
50
+ | grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback |
51
+ | video | heygen avatar video HyperFrames-authenticated path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
52
52
 
53
53
  Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
54
54
  private, offline once cached). The `codex` CLI remains the ChatGPT-sub image
@@ -58,31 +58,31 @@ allowance) so an agent-initiated `resolve --type video` confirms first.
58
58
 
59
59
  To force a specific generator (e.g. a user says "make this image with codex"),
60
60
  pass `--provider codex`: it pins resolution to that provider and skips the
61
- free-usage default. See `references/operations.md` for the RAM ladders and
61
+ default provider. See `references/operations.md` for the RAM ladders and
62
62
  provider recipes.
63
63
 
64
- `--local-only` skips every network provider, including the free HeyGen ones,
64
+ `--local-only` skips every network provider, including HeyGen,
65
65
  leaving the project + global cache and any installed local provider. For
66
66
  HeyGen-only types, that means no fresh resolve.
67
67
 
68
68
  ## CLI tools used (what to run, and how to enable each)
69
69
 
70
70
  `resolve` auto-cascades; each provider shells one CLI. HeyGen is the
71
- free-usage path for bgm/image/icon catalog search, TTS (voice), and avatar
72
- video, so those capabilities need `heygen` installed and authenticated. Local
71
+ HyperFrames-authenticated path for bgm/image/icon catalog search, TTS (voice), and avatar
72
+ video, so those capabilities need `heygen` installed and a HyperFrames login. Local
73
73
  tools are OPT-IN alternatives where they exist; install one to unlock its free,
74
74
  private, on-device path instead of or ahead of HeyGen for that type. Only
75
75
  `ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
76
76
 
77
- | Tool | Serves | Install |
78
- | ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
80
- | `heygen` | catalog (bgm/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0) |
81
- | `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
82
- | `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
83
- | `parakeet-mlx` | local transcription (default ASR, best) on Apple Silicon | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
84
- | `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
85
- | `npx hyperframes` | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
77
+ | Tool | Serves | Install |
78
+ | ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
+ | `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
80
+ | `heygen` | catalog (bgm/image/icon) + TTS (voice) + avatar video — the HyperFrames-authenticated path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `npx hyperframes auth login` (helper needs >= v0.3.0) |
81
+ | `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
82
+ | `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
83
+ | `parakeet-mlx` | local transcription (default ASR, best) on Apple Silicon | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
84
+ | `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
85
+ | `npx hyperframes` | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
86
86
 
87
87
  The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
88
88
  the CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider
@@ -10,8 +10,8 @@ export const HEYGEN_MIN_VERSION = "0.3.0";
10
10
  // installer text out of the runtime module; the docs are the safer source of
11
11
  // truth for platform-specific setup.
12
12
  export const HEYGEN_INSTALL_COMMAND =
13
- "Install the CLI from https://developers.heygen.com/cli, then run: heygen auth login --oauth";
14
- export const HEYGEN_AUTH_COMMAND = "heygen auth login --oauth";
13
+ "Install the CLI from https://developers.heygen.com/cli, then run: hyperframes auth login";
14
+ export const HEYGEN_AUTH_COMMAND = "hyperframes auth login";
15
15
  export const HEYGEN_UPDATE_COMMAND = "heygen update";
16
16
  export const HEYGEN_CLIENT_SOURCE_ARGV = ["--headers", "X-HeyGen-Client-Source: media-use"];
17
17
 
@@ -143,7 +143,8 @@ export function heygenUserId(username) {
143
143
  // casing never splits one person). `heygen_username` is the cross-project join
144
144
  // column for the Snowflake event table.
145
145
  function heygenAccount() {
146
- const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
146
+ const root = process.env.HYPERFRAMES_CONFIG_DIR || join(homedir(), ".hyperframes");
147
+ const file = join(root, ...(process.env.HYPERFRAMES_ENV === "dev" ? ["dev"] : []), "credentials");
147
148
  try {
148
149
  if (!existsSync(file)) return null;
149
150
  const raw = readFileSync(file, "utf8").trim();