video_translate/docs/plans/2026-03-19-upload-subtitle-defaults-design.md

Upload Subtitle Defaults Design

Goal: Let users set the initial subtitle position and subtitle size on the upload screen, with defaults matching the current editor behavior, and carry those values into the editor as the starting subtitle style.

Context

The upload screen currently collects the video file, trim range, and target language. The editor later applies a default subtitle style internally, which means users have no chance to define their preferred starting subtitle placement or text size before generation begins.

The user wants the upload page to support free adjustment of subtitle position and subtitle size, while keeping a sensible default identical to the current editor: subtitle text near the bottom of the video and a medium default size. The upload page should define the initial values only, and the editor should continue using them as the starting style.

Approaches Considered

Option A: Add preset-only controls on the upload screen

Offer fixed choices such as top / middle / bottom and small / medium / large.

Pros

• Smallest implementation
• Easy to understand quickly

Cons

• Does not satisfy the request for free adjustment
• Makes it harder for users to match personal subtitle habits

Option B: Add free controls with a lightweight preview

Expose a vertical position control and a size slider on the upload screen, preview the result with a sample subtitle card, and pass the chosen values into the editor.

Pros

• Matches the requested behavior
• Keeps upload-page controls focused on the two initial settings only
• Reuses the editor's existing subtitle style model

Cons

• Requires new state to flow from upload to editor
• Needs a preview so the controls feel meaningful

Recommendation

Use Option B. It gives users the flexibility they asked for without overloading the upload screen with full subtitle styling.

Architecture

Shared Style Data

Introduce a small shared shape for upload-time subtitle defaults:

• fontSize
• bottomOffsetPercent

This can be represented either as a new dedicated interface or as part of the existing subtitle text style model plus a position field. The important part is that the upload screen stores these values and the editor uses them as its initial defaults for every generated subtitle.

Upload Screen

Add a "Subtitle Defaults" card to the right settings column that includes:

• a preview frame with a sample subtitle
• a vertical range input for subtitle position
• a horizontal range input for subtitle size
• a reset button that restores the current editor defaults

The preview should be lightweight and not depend on the selected video file. It only needs to make the chosen position and size visible.

App State Flow

App will store the chosen upload defaults alongside:

• videoFile
• targetLanguage
• trimRange

When the upload is confirmed, UploadScreen passes the subtitle default settings up through onUpload(...). App then forwards them to EditorScreen.

Editor Initialization

EditorScreen will accept the upload-provided subtitle defaults and use them when normalizing generated subtitles. That ensures:

• all generated subtitles start with the chosen size
• the overlay initially appears at the chosen vertical position
• the existing editor style controls continue from those defaults

Interaction Details

Default Values

Match the current editor behavior:

• fontSize: 24
• bottomOffsetPercent: 10

These values must be used both as initial upload-screen state and as the reset target.

Position Control

Use a continuous slider representing distance from the bottom edge of the video preview. This is simpler and more reliable than drag-to-place in a small upload card.

Size Control

Use a continuous slider with a bounded range suitable for subtitle readability, for example 16 to 40 pixels.

Testing Strategy

Add tests that verify:

• upload-screen controls start from the same defaults as the editor
• changing upload-screen position and size is reflected in the upload preview
• confirming upload passes the selected subtitle defaults up to App
• editor initialization applies the upload defaults to the visible subtitle overlay

Rollout Notes

This change intentionally limits upload-time styling to size and vertical position. Full styling such as font family, color, stroke, and per-subtitle overrides remains the editor's responsibility.