Repository navigation
Description
Search existing issues
- I have searched the existing issues
Describe the bug
Caption placement is bound to the footage rect (the screen layer), not to the output frame. That was a defensible default back when the caption layer piggybacked on annotations, but it is the wrong space for subtitles, and it produces three distinct, user-visible problems.
1. Captions live inside the footage, so padding/background drags them around
Captions are turned into synthetic text annotation regions:
https://github.com/getopenscreen/openscreen/blob/main/src/lib/ai-edition/captions/cues.ts#L242-L268
and annotation regions are explicitly defined as fractions of the screen layer, not the frame — src/native/sceneDescription.ts:102-106:
Coordinate space, which the renderer must match exactly:
x/y/w/hare fractions of the SCREEN layer's rect, not of the output frame — the web overlay is handedlayout.screenRectas its container.
Since padding shrinks screenRect (computeCompositeLayout; see the ~0.8 ratio asserted in src/lib/compositeLayout.test.ts:347), turning padding up moves the captions inward and scales them down along with the video. The caption band never uses the padded/background area — which is exactly the region a user adds padding in order to have. The whole point of a padded layout is that there is now room outside the footage; captions should be free to sit there.
This affects preview and export identically, since both consume the same regions.
2. There is no horizontal offset at all
The band's x is hardcoded to centre — src/lib/ai-edition/captions/settings.ts:178-193:
return {
x: (100 - width) / 2,
y: clamp(anchorY + settings.offsetY, 0, 100 - height),
width,
height,
};textAlign only aligns text inside the always-centred band, so the effective horizontal position is a function of width, which is a blunt instrument: to shift text left you have to widen the band and left-align, which also changes wrapping. There is no offsetX counterpart to offsetY.
3. offsetY cannot reach the top or bottom, and most of its slider range is dead
The band is a fixed 22% of the (already shrunken) screen rect, and the text is vertically centred inside it — see crates/compositor/src/text_macos.rs:285 ("centrage vertical"). Combined with the clamp(…, 0, 100 - height) above, the text centre can never get closer than ~11% of the screen-rect height to the edge — and that is 11% of the footage, before padding pushes it further in still.
Worse, the slider advertises −45…+45 (CaptionsPane.tsx:466-475) but the clamp silently eats most of it:
| Anchor | anchorY |
Effective offsetY range |
Dead range |
|---|---|---|---|
top |
3 | 0 … +45 | −45 … −3 (48% of the slider) |
middle |
39 | −39 … +39 | both ends |
bottom |
75 | −45 … +3 | +3 … +45 (47% of the slider) |
So at the default bottom anchor, nearly half the slider travel does nothing at all — the handle moves and the captions don't.
Docs mismatch: website/docs/captions.md:42 describes the offset and band width as being "as a % of the frame", and settings.ts:45-48 says "% of frame height" / "% of frame width". Neither is true today — they are percentages of the screen rect. Whichever way this is fixed, one of the two needs to change.
Expected behavior
Caption placement should be frame-relative, not footage-relative:
- The caption band is positioned against the output frame, so padding, background, and rounded corners do not move or resize captions. Captions may sit over the padded/background area — that is a legitimate and common subtitle layout.
- Captions stay put when the user changes padding, exactly as they already stay put when the content zooms underneath them.
- Vertical offset can reach the true edges. At the
bottomanchor with max offset, the caption text should sit flush against the bottom of the frame (modulo a small safe margin); same fortop. The full slider range should map to a real change — no dead travel. - A horizontal offset exists, symmetric with the vertical one, letting the user push captions to the very left or right of the frame.
textAlignstays what it is: alignment of text within the band.
To Reproduce
- Open a project with a recording and enable captions (inspector → Captions → Show captions).
- Note where the caption sits.
- Go to the layout/appearance settings and raise padding (or enable a background).
- The captions shrink and move inward with the footage instead of holding their position in the frame.
- Back in Captions → Position, set the anchor to Bottom and drag Vertical offset to +45%.
- The captions stop moving well before the bottom of the frame — and stop responding to the slider entirely past roughly +3%.
- Try to move the captions toward the left or right edge: there is no control for it. The only lever is Width, which also changes line wrapping.
Additional context
Relevant code:
src/lib/ai-edition/captions/settings.ts:73-193—CAPTION_BAND_HEIGHT_PCT,CAPTION_EDGE_MARGIN_PCT,captionBandRect()(the anchor + clamp + hardcoded centring)src/lib/ai-edition/captions/cues.ts:242-268—captionCuesToTextRegions(), where the band becomes an annotation regionsrc/native/sceneDescription.ts:95-138and:483-499—SceneAnnotationcoordinate space, and where captions join the annotation listsrc/components/ai-edition/CaptionsPane.tsx:443-486— the Position controlscrates/compositor/src/text_macos.rs:285— vertical centring inside the band
Implementation note: the fix is not just swapping the divisor. Captions ride the annotation pipeline precisely so preview and export share one text path, and annotations are correctly screen-rect-relative (they're authored against the visible video). So captions need their own coordinate space flag on the way through — a frame-relative region — rather than a change to how all annotations are projected. The band-height-plus-vertical-centring scheme also needs rethinking if the text is to reach an edge: anchoring the text box to the band edge, or sizing the band to the text, would both work where clamping a fat centred band does not.
Docs to update alongside: website/docs/captions.md and technical-documentation/architecture/transcription-and-captions.md:500-545.
Activity
fix(compositor): stop Linux annotations zooming with the content
feat(compositor): honour a per-annotation coordinate space
feat(captions): give the inspector a horizontal offset, and honest sl…
docs(captions): describe the frame as the box captions are measured a…
test(captions): pin the sliders to the range the band can actually reach
fix(captions): re-clamp offsets on patch, and unambiguous Turkish labels
test(captions): cover the two fields that reach the offset range indi…
feat(captions): measure the caption band against the frame, not the f…
feat(compositor): honour a per-annotation coordinate space
feat(captions): give the inspector a horizontal offset, and honest sl…
docs(captions): describe the frame as the box captions are measured a…
test(captions): pin the sliders to the range the band can actually reach
fix(captions): re-clamp offsets on patch, and unambiguous Turkish labels
test(captions): cover the two fields that reach the offset range indi…
2 remaining items
feat(compositor): honour a per-annotation coordinate space
feat(captions): give the inspector a horizontal offset, and honest sl…
docs(captions): describe the frame as the box captions are measured a…
test(captions): pin the sliders to the range the band can actually reach
fix(captions): re-clamp offsets on patch, and unambiguous Turkish labels
test(captions): cover the two fields that reach the offset range indi…
github-actions commentedon Aug 20, 2026
Fixed by #399 and merged into
main.This change is assigned to the
Next Releaserelease milestone and is not necessarily available in the latest downloadable desktop release yet. It is currently marked asstatus: pending releaseuntil a packaged release containing it is published.fix(captions): position presets you can click, sliders that reach the…
fix(captions): position presets you can click, sliders that reach the…
feat(captions): draw the anchor line and the column while the pane is…