SubtitleConfig
Which subtitle track to pick, when to show its cues, and how large to draw them.
Read by the session core: track selection uses the language preferences and the forced rule, cue timing applies delay, and the platform rasterizer receives fontScale. Decoded cues are held for the session and pruned on flush.
Constructors
Properties
Match an ASS script's colours to the video the way its YCbCr Matrix header asks (#499), so a sign coloured to blend into the picture blends in here too. Typesetters pick such colours from a frame decoded with one matrix, and the header names it; a script with no header is an old VSFilter one, which counts as BT.601 at studio range. Each colour goes from RGB to YCbCr with the header's matrix and range, and back to RGB with the video's, as XySubFilter does and as libass recommends. None keeps the colours as they are, and so do RGB video and HDR video. Both the typesetting engine and the Kotlin tier follow it. False draws every colour as authored, for an application that wants exactly those.
With no language preference matched, select the container's default-flagged subtitle track, or its first one, rather than none. On, because a viewer who opens subtitled media expects to see the subtitles; a player wanting mpv's stricter no-preference-no-subtitles behaviour turns this off.
Select a forced-subtitles track automatically: one in a preferred language when the audio language is not preferred, and otherwise one matching the audio's own language, which is the audience a forced track is authored for. The choice is made again whenever the audio changes, until a subtitle is chosen by hand (#506).
Shift every cue by this much. Positive shows cues later. At most KitePlayer.DELAY_MAX either way.
The encoding an external subtitle file is read in when it has no byte-order mark and is not UTF-8, in place of a guess from its bytes (#515). Null guesses.
Fonts handed to the typesetting engine on top of what the platform and the media supply. Ignored by the Kotlin tier, which uses the platform's own font system.
Draw only the pictures an image subtitle track marks as forced (#513), as mpv's sub-forced-events-only does. A Blu-ray or DVD track often holds the full subtitles and a few forced captions together, and this shows a viewer only the captions for the lines in another language and the signs. A track the container flags as forced counts as forced whole, and a text track has no such mark, so both draw as ever. Applies to both subtitle slots, and KitePlayer.setForcedPicturesOnly changes it while playing.
While no subtitle is selected, draw the forced pictures of the Blu-ray or DVD subtitle track in the audio's language, as a disc player does with subtitles off (#513). The track is not selected by this: Tracks.selectedSubtitle stays null, and the choice follows the audio. Selecting any subtitle, a secondary one included, ends it; turning subtitles off brings it back. Off by default, so subtitles off draws nothing.
What happens to the notes that subtitles for deaf and hard-of-hearing viewers carry, such as [DOOR SLAMS], (laughs), JOHN: and lines of ♪ music (#493). HearingImpairedNotes.Keep shows them as authored. The setting reads SubRip, WebVTT, MP4 and other text tracks, from the container or from a file; ASS signs, typesetting and karaoke are left alone.
Select a subtitle track automatically when one matches these languages, best first, given as ISO 639 codes or BCP 47 tags.
A second subtitle track to select at each open, for a viewer who reads two (#494): a text track in the first of these languages that has one, other than the primary track, as mpv's secondary-slang picks it. Languages match as preferredLanguages do. Empty, the default, selects none, and an application can still choose one with selectSecondarySubtitle.
Where the second subtitle track sits. See SecondarySubtitlePlacement.
The viewer's style override, applied over every authored style. Null changes nothing.
Route ASS and SSA tracks through an installed typesetting engine when one is present. Adding kiteplayer-libass installs one; the standard entry points include it. False keeps the Kotlin dialogue tier for every track, which draws styles but not animated typesetting. With no engine installed this changes nothing.
What the player chooses by itself when the audio is in one of preferredLanguages, a language the viewer reads and so understands (#506), as mpv's subs-with-matching-audio. MatchingAudioSubtitles.All chooses as ever, so a viewer who prefers English subtitles keeps them under English audio, which is mpv's default too. A viewer who wants subtitles only for what they do not understand asks for MatchingAudioSubtitles.ForcedOnly, and gets the signs and foreign lines a forced track carries and no more. The choice is made again at each audio change, and a subtitle chosen by hand is never held back.