Legacy subtitle overlay filters

Legacy ass and subtitles video filters obtain a script through their own resource path and render it into CPU video frames; native subtitle-stream filters expose a different graph boundary.

The familiar FFmpeg subtitles and ass filters are video filters that render a script over incoming picture frames. Their script-reading path is part of the filter's own initialization. “Legacy” here distinguishes that interface from Emby's later native subtitle-stream filtering design; it does not mean the established filters are unusable.

Who owns the subtitle input?

Interface in the examined Emby source Inputs visible to the filter graph Subtitle acquisition
ass Video frames The filter reads an ASS script
subtitles Video frames The filter opens a resource, selects/decodes subtitle content and prepares a libass track
overlaytextsubs Video frames and native subtitle frames A subtitle branch supplies decoded text events
overlaygraphicsubs Video frames and native subtitle frames A subtitle branch supplies decoded graphics

The first two still combine timed text with video. The difference is where selection, decoding and resource ownership enter the graph.

For example, selecting one subtitle track from a media file and passing its events down a native branch keeps that selection in the ordinary demux/decode path. A filter that opens a resource independently needs its own correct resource and stream selection.

A script includes more than dialogue strings

The renderer needs a valid script header, style definitions, event timings and fonts. In the examined subtitles path, the filter can also recover font attachments from the opened media resource. An external script can instead rely on available font-provider resources.

A font directory or attachment is useful only if the requested face resolves at the active renderer. The font attachment article explains the difference between carrying a font file and actually selecting its face.

The renderer evaluates the script at the video frame's presentation time and blends its generated images into that frame. It is therefore a CPU video-processing boundary in this implementation, even if video decoding and encoding elsewhere use hardware.

Script time must meet picture time

Suppose a script cue is at 12.5–15.0 seconds in the original programme. If a video branch rebases a trimmed excerpt to zero, the script and video no longer share the same time origin unless the route also establishes the corresponding mapping. Reading the right words from the right file does not repair that clock relationship.

Seeking also requires a valid presentation state at the destination. A native subtitle branch and a separately initialized script can obtain that state by different mechanisms. Their output should be assessed using cue intervals, presentation time and recovered state, rather than assuming that every resource is reread identically.

These interfaces are verified in the public 5.1-emby_2023_06_25_u1 source archive. Classic pipelines show the script-owning route; subtitle filtering pipelines develop the separate native branch.

See Also

References