FILE_READING subtitle validation rule

Lists what CueNorm reports while reading a file, before any profile rule: format errors, skipped cues and features it cannot keep.

What it checks

CueNorm reads each format tolerantly: a file that is odd but usable is read, and every anomaly is reported instead of being silently fixed or dropped. Only a file that cannot be used at all is refused. These checks apply to every file, whatever the profile.

How it is measured

Each code below has a severity:

fatal: the file cannot be used and is not processed (exit code 3 on the command line);
error: part of the file could not be read (a cue was skipped, a header is missing);
warning: the file was read, but something was ignored, assumed or approximated;
info: a normal situation worth knowing, nothing lost.

Any format

Code	Severity	Meaning
`FILE_FORMAT_MISMATCH`	fatal	The content is in another format than the file extension says (see its page).
`NO_SUBTITLES_READ`	fatal	The file has content but no subtitle could be read (see its page).
`INPUT_TOO_LARGE`	fatal	The file is larger than the accepted size.
`TOO_MANY_SUBTITLES`	fatal	The file holds more subtitles than accepted.
`ENCODING_ASSUMED`	warning	The text is not UTF-8; a legacy encoding (CP1250, common for Polish) was assumed. State the encoding to be sure.
`ENCODING_UNDECODABLE`	warning	The text is neither UTF-8 nor CP1250; undecodable bytes may be corrupted.
`BLANK_LINES_IGNORED`	warning	Blank lines at the start or end of subtitles were ignored (one report for the file).
`SOURCE_LANGUAGE_OVERRIDDEN`	info	The language you stated replaces the one the file declares.

SRT

Code	Severity	Meaning
`SRT_INVALID_TIMING`	error	A block has no valid `start --> end` timing line; the cue was skipped.
`SRT_NONSTANDARD_TIMING_SEPARATOR`	warning	A dot is used before the milliseconds instead of a comma; read anyway.
`SRT_UNSUPPORTED_INLINE_TAG`	warning	Inline tags other than italic, bold, underline and font colour were removed, text kept.

ASS / SSA

Code	Severity	Meaning
`ASS_MISSING_FORMAT`	error	Dialogue lines come before the `Format:` line of the `[Events]` section and cannot be read.
`ASS_MALFORMED_DIALOGUE`	error	A Dialogue line has fewer fields than `Format:` declares; the cue was skipped.
`ASS_INVALID_TIMING`	error	A Dialogue line has an invalid start or end time; the cue was skipped.
`ASS_EMPTY_SUBTITLE`	warning	A Dialogue line has no visible text; the cue was skipped.
`ASS_UNKNOWN_STYLE`	warning	A Dialogue line names a style that is not defined; default styling applied.
`ASS_UNSUPPORTED_FEATURE`	warning	Override tags CueNorm does not keep (karaoke, transforms, drawings, clips…) were removed.

EBU-STL

Code	Severity	Meaning
`STL_TRUNCATED_GSI`	fatal	The file is shorter than the 1024-byte header (GSI block).
`STL_UNKNOWN_DFC`	warning	The disk format code is neither `STL25.01` nor `STL30.01`; 25 fps assumed.
`STL_UNSUPPORTED_CCT`	warning	The character code table is not 00 (Latin, ISO 6937); the text was decoded as Latin anyway.
`STL_GSI_COUNT_MISMATCH`	warning	The header's block or subtitle count differs from what the file holds.
`STL_GSI_METADATA_IGNORED`	warning	A header text field (title, reference…) has a malformed value and was ignored.
`STL_TRAILING_BYTES`	warning	Bytes after the last complete 128-byte TTI block were ignored.
`STL_RESERVED_EBN`	warning	A TTI block with a reserved extension block number was ignored.
`STL_UNTERMINATED_SUBTITLE`	warning	The last subtitle's extension blocks are not closed (no EBN FFh).
`STL_MISSING_TERMINATOR`	warning	Text fields do not end with the 8Fh terminator the standard requires.
`STL_UNMAPPED_CHARACTER`	warning	Bytes with no character in the code table were replaced by `?`.
`STL_GRAPHICS_MODE_IGNORED`	warning	A row uses teletext mosaic graphics; it was not read as text.
`STL_CUMULATIVE_IGNORED`	warning	Cumulative subtitles (built up line by line) were read as ordinary, overlapping subtitles.
`STL_EMPTY_SUBTITLE_SKIPPED`	info	Subtitles with no text (synchronisation markers) were skipped.
`STL_SUBTITLE_ZERO_SKIPPED`	info	The "subtitle zero" (programme identity before the programme start, not broadcast) was skipped.

TTML, EBU-TT, EBU-TT-D, IMSC, iTT, SMPTE-TT

Code	Severity	Meaning
`TTML_INVALID_XML`	fatal	The file is not well-formed XML.
`TTML_INVALID_ROOT`	fatal	The root element is not `tt`.
`TTML_DOCTYPE_FORBIDDEN`	fatal	The document has a DOCTYPE declaration, refused for security.
`TTML_INVALID_TIMING`	warning	A paragraph has a missing or invalid begin or end time and was skipped.
`TTML_EMPTY_SUBTITLE`	warning	A paragraph has no text and was skipped.
`TTML_NESTED_TIMING`	warning	A parent element limits the time of its children; the children keep their own times.
`TTML_UNSUPPORTED_TIME_BASE`	warning	Drop-frame timecodes are not supported; times were read as media times.
`TTML_INVALID_LANGUAGE`	warning	`xml:lang` is not a language tag and was ignored.
`TTML_METADATA_IGNORED`	warning	A programme metadata value (title, reference…) is malformed and was ignored.

WebVTT

Code	Severity	Meaning
`VTT_MISSING_HEADER`	error	The file does not start with `WEBVTT`; cues were read anyway.
`VTT_INVALID_TIMING`	error	A cue has no valid timing line; it was skipped.
`VTT_EMPTY_SUBTITLE`	warning	A cue has no text.
`VTT_UNSUPPORTED_BLOCK`	warning	`STYLE` or `REGION` blocks are not supported and were ignored.
`VTT_SETTING_DROPPED`	warning	Cue settings with no equivalent (size, exact position…) were dropped.
`VTT_UNSUPPORTED_TAG`	warning	Tags other than italic, bold, underline and colour classes were removed, text kept.
`VTT_LEGACY_SETTING_VALUE`	warning	Cue settings use values from an early WebVTT draft; read as their current equivalents.

Example

An SRT file whose third block reads 3 / 00:00:07 --> 00:00:09 / Hello is reported as SRT_INVALID_TIMING: Invalid timing line: "00:00:07 --> 00:00:09". Cue skipped. The other subtitles are read and judged as usual.

How to fix

For a fatal code, fix the file itself: right format and extension, complete file, well-formed XML.
For an error, correct the cue in the authoring tool: a skipped cue is missing from any conversion.
A warning tells you what was assumed or dropped; check that it does not matter for the destination (for example, state the encoding with --input-encoding when ENCODING_ASSUMED guessed wrong).

FILE_READING