Skip to content

Commit 8e566e2

Browse files
docs: align render, fps and transcribe docs with the CLI
- docs/guides/rendering.mdx: default render quality is `looks` (CRF 16), not `standard`. - docs/packages/cli.mdx, render --help (render.ts): default --output is the timestamped `renders/<project>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>`. - skills/hyperframes-cli/references/preview-render.md: local --fps accepts 1-240 or a rational and defaults to the root data-fps, else 30; only lambda and cloudrun are limited to 24, 30, 60. - skills/hyperframes-cli/references/lint-validate-inspect.md: snapshot --range is documented as START,END like every other reference. - skills/media-use/references/audio.md, skills/media-use/audio/references/ transcribe.md, skills/hyperframes/references/captions.md: name the entry point for each transcription default (transcribe.mjs prefers Parakeet; `hyperframes transcribe` uses Parakeet when installed, else the small.en whisper model). - transcribe --model help text and docs/packages/cli.mdx: list `small` and `medium`, which the CLI already accepts. - skills-manifest.json: regenerated hashes for the three skills touched. — Jerrai
1 parent 579f73b commit 8e566e2

10 files changed

Lines changed: 15 additions & 15 deletions

File tree

‎docs/guides/rendering.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ browser already supports the source or you are diagnosing the proxy itself.
130130

131131
## Choose quality and frame rate
132132

133-
The default `standard` quality is the right choice for most finished work.
133+
The default `looks` quality (CRF 16) is the right choice for most finished work.
134134
MOV is an alpha-preserving editing intermediate and always uses the fixed
135135
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
136136
and are rejected for MOV; choose MP4 or WebM when you need those controls.

‎docs/packages/cli.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -306,7 +306,7 @@ npx hyperframes transcribe video.mp4 --to vtt
306306
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
307307
| `--dir, -d` | Project directory (default: current directory) |
308308
| `--engine, -e` | ASR engine: `auto` (default — Parakeet if installed and the language is one of its 25, else whisper), `parakeet` (fails if Parakeet is missing, broken, or lacks the `--language`), or `whisper`. Under `auto` or `parakeet`, a `--language` other than English runs whisper when it is installed, with a note, because Parakeet detects the language itself |
309-
| `--model, -m` | Whisper model (default `small.en`): `tiny.en`, `base.en`, `small.en`, `medium.en`, `large-v3` |
309+
| `--model, -m` | Whisper model (default `small.en`): `tiny.en`, `base.en`, `small.en`, `medium.en`, `small`, `medium`, `large-v3` |
310310
| `--language, -l` | Language code (`en`, `es`, `ja`, …). Whisper transcribes as this language; Parakeet detects the language itself, so it only takes a non-English `--language` when whisper is not installed. |
311311
| `--to` | Write an `srt` or `vtt` sidecar: from a transcript file it exports instead of importing; from audio or video it is written beside `transcript.json`, with cues for languages without spaces grouped, which exporting that `transcript.json` later may split differently |
312312
| `--output, -o` | Where the exported SRT/VTT goes |
@@ -1434,7 +1434,7 @@ The flags that come up most:
14341434

14351435
| Flag | Default | Description |
14361436
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
1437-
| `--output, -o` | `renders/<name>.mp4` | Output file path |
1437+
| `--output, -o` | `renders/<project>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>` | Output file path |
14381438
| `--composition, -c` | `index.html` | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
14391439
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, `png-sequence`, or `hls`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory; `hls` writes a VOD playlist directory. |
14401440
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |

‎packages/cli/src/commands/render.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ export default defineCommand({
159159
output: {
160160
type: "string",
161161
alias: "o",
162-
description: "Output path (default: renders/<name>.mp4)",
162+
description: "Output path (default: renders/<project>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>)",
163163
},
164164
fps: {
165165
type: "string",

‎packages/cli/src/commands/transcribe.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ export default defineCommand({
5656
},
5757
model: {
5858
type: "string",
59-
description: `Whisper model (default: ${DEFAULT_MODEL}). Options: tiny.en, base.en, small.en, medium.en, large-v3`,
59+
description: `Whisper model (default: ${DEFAULT_MODEL}). Options: tiny.en, base.en, small.en, medium.en, small, medium, large-v3`,
6060
alias: "m",
6161
},
6262
language: {

‎skills-manifest.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,19 @@
66
"files": 2
77
},
88
"hyperframes": {
9-
"hash": "7a5df5b496053c19",
9+
"hash": "b222ac5809fd2633",
1010
"files": 77
1111
},
1212
"hyperframes-cli": {
13-
"hash": "d69b5b51429367f9",
13+
"hash": "e66b5a2049c0b9f7",
1414
"files": 13
1515
},
1616
"hyperframes-registry": {
1717
"hash": "221af9e7fbffe732",
1818
"files": 13
1919
},
2020
"media-use": {
21-
"hash": "d93e5ec676b0d42b",
21+
"hash": "1082bd1c4e3f033b",
2222
"files": 116
2323
},
2424
"remotion-to-hyperframes": {

‎skills/hyperframes-cli/references/lint-validate-inspect.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,15 +111,15 @@ Drop a `*.motion.json` sidecar next to the composition (matching the html basena
111111
npx hyperframes snapshot # 5 key frames as PNG
112112
npx hyperframes snapshot ./my-project # specific project
113113
npx hyperframes snapshot --frames 10 # evenly-spaced N frames
114-
npx hyperframes snapshot --range 3:5 --frames 8 # 8 frames within root-timeline seconds 3–5
114+
npx hyperframes snapshot --range 3,5 --frames 8 # 8 frames within root-timeline seconds 3–5
115115
npx hyperframes snapshot --composition intro --frames 8 # 8 frames within this data-composition-id
116116
npx hyperframes snapshot --review # beat sheet, seam strips, phone sheet
117117
npx hyperframes snapshot --review --json # same, with paths and times as JSON
118118
```
119119

120120
Still PNGs. Each run writes `.hyperframes/artifacts/snapshots/<id>/` unless `--output` is set. `snapshot` is the standalone capture; `check --snapshots` is the gate.
121121

122-
One of `--at`, `--range START:END` (seconds), or `--composition <data-composition-id>` (not a CSS selector). `--frames` defaults to 5. Range and composition sample just before the end and add no extra end frame; `--at` adds one unless `--no-end`.
122+
One of `--at`, `--range START,END` (seconds), or `--composition <data-composition-id>` (not a CSS selector). `--frames` defaults to 5. Range and composition sample just before the end and add no extra end frame; `--at` adds one unless `--no-end`.
123123

124124
`--review` picks the frames that show a film over time. Scenes are the composition's top-level timed clips and sub-composition hosts, as `timeline` lists them (captions and audio excluded); `--composition` scopes to one. It writes `review-beats.jpg` (each scene at its start + 0.3 s and at its middle, and each timed `data-beat="name"` element at its start + 0.3 s, labelled with time and id), `review-seam-NN.jpg` (frames at −0.2, −0.1, 0, +0.1, +0.2 s around every cut) and `review-phone.jpg` (the beat frames 360 px wide, to judge legibility at phone size), beside the `beat-*.png` and `seam-*.png` stills. With fewer than two scenes the beats spread evenly. `--json` prints `{ok, outputDir, frames[{path,time,role,label}], contactSheets, review{window, scenes, beats, seams[{time,from,to,times,paths,sheet}], sheets, notes}}`.
125125

‎skills/hyperframes-cli/references/preview-render.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ npx hyperframes render --docker # byte-identical
120120
| `dir` (positional) | path | cwd | Project directory. Omit to use current working directory. |
121121
| `--composition`, `-c` | path to composition file | `index.html` | Render a specific composition file (e.g. `compositions/intro.html`) instead of the project's `index.html`. |
122122
| `--output`, `-o` | path | `renders/<project>_<ts>.<ext>` | Output path. Default is timestamped (`<project-name>_YYYY-MM-DD_HH-MM-SS.<ext>`). |
123-
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
123+
| `--fps` | 1–240, or a rational such as `30000/1001` | root `data-fps`, else 30 | 60fps doubles render time. `lambda` and `cloudrun` accept only 24, 30, 60 |
124124
| `--quality` | draft, looks, delivery, standard, high | looks | `looks` is CRF 16 on the standard preset. `delivery` is `high`. draft for iterating |
125125
| `--format` | mp4, webm, mov, gif, png-sequence, hls | mp4 | WebM/MOV render with transparency; gif for inline autoplay in GitHub PRs/READMEs/docs (two-pass palette encode, fps capped at 30 — prefer `--fps 15` — no audio, 1-bit transparency only, HDR falls back to SDR); png-sequence writes RGBA frames to a directory (AE/Nuke/Fusion ingest); hls writes an HLS VOD directory (master.m3u8 + video/audio playlists + MPEG-TS segments), SDR only, rejects `--gpu`, unavailable on lambda/cloudrun |
126126
| `--gif-loop` | 0-65535 | 0 | GIF loop count; `0` loops forever. Only with `--format gif`. |

‎skills/hyperframes/references/captions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Words and timings
44

55
- `npx hyperframes transcribe <file> --json` and a HeyGen voiceover (`/media-use`) give every word's start and end. Work from those as `[{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 }, …]`.
6-
- Local transcription defaults to `small.en`, which **translates** non-English speech into English. Pass the model: `npx hyperframes transcribe <file> --model small.en` for English, `--model small --language <code>` otherwise, `--model medium.en` for speech over music. It writes `assets/transcript.json` (its JSON names the path) and overwrites it on the next run; `--to srt` or `--to vtt` writes a sidecar.
6+
- `npx hyperframes transcribe` defaults to the `small.en` whisper model, which **translates** non-English speech into English. Pass the model: `npx hyperframes transcribe <file> --model small.en` for English, `--model small --language <code>` otherwise, `--model medium.en` for speech over music. It writes `assets/transcript.json` (its JSON names the path) and overwrites it on the next run; `--to srt` or `--to vtt` writes a sidecar.
77
- For Chinese, Japanese and other unspaced scripts, local transcription returns a whole sentence as one "word", sometimes in the other script (Traditional for Simplified speech). Split each segment's text into short phrases and spread its time across them by character count; check the characters against what is said.
88
- Whisper invents "Thank you." over silence and repeats lines over a silent tail: drop words that start inside a final silence (`silencedetect=noise=-35dB:d=0.6`; real speech sits around −16 to −26 dB).
99
- Never put two words in one timed entry, and match transcript words to caption words by position, not text, or a repeated word takes the wrong time.

‎skills/media-use/audio/references/transcribe.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Transcription
22

3-
Create normalized word-level timestamps. **Always specify `--model` explicitly** — the CLI default is `small.en`, which silently translates non-English audio into English.
3+
Create normalized word-level timestamps. **Always specify `--model` explicitly** — `npx hyperframes transcribe` uses `small.en` as its default whisper model, which silently translates non-English audio into English.
44

55
```bash
66
npx hyperframes transcribe audio.mp3 --model small.en # known English
@@ -19,7 +19,7 @@ npx hyperframes transcribe openai-response.json
1919
2. **Known non-English** → `--model small --language <iso-code>` (no `.en` suffix)
2020
3. **Unknown language** → `--model small` (whisper auto-detects)
2121

22-
**CLI default is `small.en`** — do not rely on it; always pass `--model` to make the choice explicit. `--language` also filters out non-target-language segments from mixed-language audio.
22+
**The CLI's default whisper model is `small.en`** — do not rely on it; always pass `--model` to make the choice explicit. `--language` also filters out non-target-language segments from mixed-language audio.
2323

2424
## Model Sizes
2525

‎skills/media-use/references/audio.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,4 @@ node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./
1717

1818
Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).
1919

20-
Transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`).
20+
Transcription through `scripts/transcribe.mjs` defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster), with whisper.cpp auto-fallback (see `references/operations.md`). `npx hyperframes transcribe` picks its own engine: Parakeet when installed, otherwise whisper with the `small.en` model by default.

0 commit comments

Comments
 (0)