ASS and SSA

Status: Frozen bounded stable profile retained in the published v1.2.0 release; historical v1.1.0 introduced the profile and published v1.0.0 has no ASS/SSA codec

On 2026-09-15, S023 ratified the bounded native contract for the scripted-format milestone without adding codecs or changing a released capability. The constitution, schema baseline, compatibility contract, and architecture control shared behavior. P02 owns the planning contract, P05 owns schema realization, and P06-P08 own corpus, ingest and rendering evidence. The P identifiers refer to atomic outcomes in the S023 milestone plan; their completion and development availability are stated separately below.

S024 established typed schema/model recognition; S025-S027 completed native ingest/render, independent restoration, twelve-direction conversion, shared CLI discovery and conformance hardening. S028 froze and promoted this bounded profile to exact stable 1.1.0, and #66 published and independently verified that historical release. S030 completed its schema/site activation through #76 and #67. The published v1.2.0 release retains the native profile and emits exact 1.2.0 documents while accepting historical 1.0.0 and 1.1.0 through their local contracts. Optional consumer speaker assignments and media timing remain separate from native actor observations and receive explicit omission reporting during textual rendering and conversion. Official native encode and private targets declare stable capability; exact-current schema-only and complete experimental declarations remain accepted unchanged observations. Former development identities are not accepted. Published v1.0.0 remains unchanged. S035 prepares matching v1.2.0 schema/site content; #86 governs authorized post-merge production activation and independent live verification.

References and authority

S026 implemented the ten remaining directions and verified the full twelve-direction graph in the conversion contract. Native owner losses remain atomic; text-target drawing-only/unreadable dialogue is fatal, mixed drawings are reported, text-source targets use deterministic defaults and checked nearest-centisecond ties-up rounding, and dialect differences are mapped or accounted per field. A private original-plus-target validation/render boundary preserves exact source truth without changing public Cue JSON validation. S027 completed P11/P12 CLI and conformance acceptance; S028 froze P13 and prepared P14 release proof.

References were inspected on 2026-09-15. They inform the dialect boundaries; the requirements below are Cueson's acceptance and fidelity policy, not a promise to reproduce a particular pixel renderer.

• R1: libass ASS File Format Guide, displayed revision dated 2025-06-06. The maintainers explicitly describe it as generation best practices, not a comprehensive parser specification, and warn that the historical ass-specs.doc sketch is inaccurate as a modern reference.
• R2: Aegisub ASS Override Tags, accessed 2026-09-15. This is the primary semantic reference for text escapes, overrides, karaoke, and drawings. The live manual is not an immutable specification; the acceptance rows below freeze Cueson's selected interpretation.
• R3: libass 0.17.4 parser source, pinned commit bbb3c7f1570a4a021e52683f3fbdf74fe492ae84. The source supplies concrete canonical field lists and illustrates declared-field parsing, Actor/Name compatibility, and centisecond arithmetic.
• R4: Aegisub 3.4.0 document parser, pinned commit b0fc741099f610ee9486bfaf0186d39f74b8d756. Its recognized project metadata identifies external-media and automation fields requiring a deliberate privacy boundary. Cueson does not adopt its omission of comments or unknown content.
• R5: Aegisub 3.4.0 event parser and serializer, pinned to the same commit. It distinguishes dialogue/comment records, event text, and drawing spans; its source also records disagreement between renderers on unmatched braces. Cueson therefore defines its own deterministic malformed-content treatment.
• R6: Aegisub Attachment Manager, accessed 2026-09-15. Embedded fonts and graphics are retained content, never permission to load, install, rasterize, or execute an asset.

Capability and dialect boundaries

The canonical JSON format keys and native CLI tokens are ass and ssa; .ass and .ssa extensions are detection hints, not authority. Content must declare ScriptType: v4.00+ for ASS with [V4+ Styles], or ScriptType: v4.00 for SSA with [V4 Styles]. R1 documents these dialect distinctions. v4++, ASS2, older SSA versions, container packet grammars, and libass-specific extension semantics are outside the accepted profile. Unknown extensions inside an otherwise accepted document remain retained native content with diagnostics. The release implements native encode/render and the complete conversion/CLI surface for this profile; other profiles remain unsupported.

Detection scans bounded decoded content for Script Info, one unambiguous ScriptType value, and a matching style section. An extension mismatch is diagnosed; mixed style dialects, missing or conflicting ScriptType declarations, and unsupported dialects fail the whole encode operation. Identical repeated ScriptType declarations may be retained with a duplicate diagnostic. There is no silent fallback from an ambiguous script to a different codec.

Encoding, timing, and source authority

The accepted text-decoding profile is valid UTF-8, optionally beginning with a UTF-8 BOM. LF and CRLF source line endings are accepted and observed. Invalid UTF-8, other selected encodings, NUL, and bare CR fail with deterministic diagnostics. SSA's historical style Encoding field is preserved as a native charset identifier; it never selects a system codepage or changes the UTF-8 decoding contract. Legacy encoded SSA remains an explicit later expansion, not implicit platform-dependent support.

Source capture uses the existing 64 MiB input ceiling and source-envelope integrity rules. The original primary script bytes, byte length, and SHA-256 are unchanged. Native decoded line views exclude terminators and the leading BOM, while the source envelope retains both exactly. A captured filename is a portable safe basename; a caller path, working directory, user identity, hostname, or discovered asset path is never written into Cue JSON. Exact restoration verifies and reproduces the accepted original asset, independently of all native/common edits.

Accepted event timing is nonnegative h:mm:ss.cc with one or more hour digits, exactly two minute/second/fraction digits, minute and second ranges 00-59, and fraction range 00-99. Checked integer arithmetic computes milliseconds as ((h * 60 + mm) * 60 + ss) * 1000 + cc * 10; overflow or a nonpositive dialogue interval rejects encode. Event starts are inclusive and ends exclusive. Source order, overlap, and decreasing starts remain intact, with decreasing starts diagnosed. This is a deliberately bounded timing profile; Cueson does not copy permissive integer scanning or overflow behavior from R3.

Timer must be absent or numerically equal to 100. A syntactically invalid or non-100 Timer fails the whole encode operation with unsupported_timer; no apparently usable common timing is fabricated. Duplicate identical Timer declarations are retained and diagnosed; conflicting declarations fail. Non-100 timer semantics are deferred until an explicit contract and tests exist. Rendering edited times not divisible by 10 milliseconds fails with unrepresentable_centiseconds, without silent rounding. P09/P10 define any reported conversion quantization policy, but strict conversion must reject that loss.

Ordered native shape and declared fields

The current exact 1.2.0 release schema retains the following structural ownership. S023 first ratified these logical shapes for P05; S028 accepted them under the historical 1.1.0 identity, preserving the original ownership boundaries.

These native structures live under the matching format_data.ass or format_data.ssa branch, following the existing SubRip/WebVTT ownership pattern. They never flatten into the shared format_data object or coexist as mixed native branches. source_order is unique and contiguous across section-header and record occurrences, allowing reconstruction of the entire decoded physical-line sequence. Style, event, and attachment arrays use references into this sequence, not a second independent ordering. Each common cue's source_order equals the position of its owning dialogue record; it is a reference to that position, not another sequence participant. An empty primary script is invalid. Record references resolve exactly once; duplicate IDs, orphaned occurrences, missing ownership, cycles, and mismatched dialects are semantic errors. Ordered original raw views are capture observations: edits cannot silently transform them into claims about the original source.

Each matching section occurrence begins with no active Format declaration. A valid Format: declaration applies only to subsequent matching records in that occurrence, until another declaration appears. Names are recognized by ASCII case-insensitive comparison after removing surrounding ASCII spaces in the declaration view; exact original names and spaces remain retained. Actor is an explicitly accepted alias for the event Name field, following R3. No other alias is inferred. Reordered declared fields and additional unknown fields are accepted when unambiguous.

For events, Text must appear once and last. Split only the first N-1 commas for an N-field declaration; the remaining suffix is the complete Text, including commas, trailing spaces, and empty text. Non-Text event fields and all style fields cannot represent a literal comma. There is no CSV quoting or backslash comma escaping. Every field from the applicable canonical list below is mandatory exactly once, subject to the explicit Name/Actor alias; unknown extra fields may occur before final Text. Duplicate recognized fields, simultaneous Name/Actor aliases, missing mandatory fields, missing active declarations, invalid field counts, and non-final Text make the affected record uninterpretable. A malformed Dialogue record fails whole encode because discarding its semantics would hide a timed unit; a bounded malformed non-dialogue record may be retained with malformed_native_record and blocked from rendering.

Privacy classification follows declaration and record framing validation. A recognized prefix alone never grants a content exemption. Malformed Dialogue rejects; retained malformed Comment/Style records require conservative inspection of the complete unsplit value before any content-role exemption, including missing or uninterpretable declarations. Style framing counts every comma; only an interpretable event declaration with final Text permits a comma-bearing suffix.

Declaration and field names are structural metadata, so they cannot carry resource or identity markers even when their values are empty. Semicolon comments retained as inert content are inspected before exemption; a comment capturing a source path or execution reference fails whole operation. Safe unknown names and inert comments remain ordered and unchanged.

The canonical native lists in R3 are the serialization defaults for newly constructed records. ASS style fields are Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding. SSA style fields are Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, TertiaryColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, AlphaLevel, Encoding. ASS events use Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text; SSA substitutes Marked for Layer, with canonical value Marked=0.

Styles, events, text, and derived observations

Every bounded style occurrence remains ordered and retains complete native values. Recognized values expose typed booleans, integers, finite decimals, color components, font-family names, margins, and alignment without rewriting lexical values. ASS colors preserve ABGR-native meaning; SSA TertiaryColour, AlphaLevel, and legacy alignment remain distinct rather than coerced into ASS equivalents. No font is resolved against the local machine. Invalid styles are retained and diagnosed; any Dialogue referencing an invalid, missing, or duplicate-name ambiguous style fails whole encode with unresolved_style. Unused duplicate style names may remain with a diagnostic, but block strict rendering.

Dialogue records map one-to-one to common cues, including empty text and drawing-only dialogue. Cue IDs are generated document-local identities, not native line numbers or source paths. Common payload.raw_text equals the exact event Text. payload.lines is the ordered logical readable-line projection under the hard/soft-break, override, and drawing rules below; payload.plain_text joins those lines with LF. Native Text and raw_text retain every original escape and override, independently of this derived projection. Empty text or drawing-only dialogue produces one empty logical line; leading, consecutive, and trailing explicit breaks retain their empty lines. Commentary, blank records, metadata, unsupported event types, styles, and embedded assets remain native document content, without artificial common cues.

Projection recognizes R2's \N as a hard line break, \h as U+00A0, and \n as a line break only with effective wrap mode 2, otherwise a space. Cueson does not simulate automatic wrapping, collision layout, glyph shaping, or video geometry. Effective WrapStyle and \q state determine only this explicit soft-break interpretation. Unknown or invalid wrap state producing ambiguous text fails dialogue projection rather than inventing layout.

For example, native Text first\Nsecond produces logical lines ["first", "second"] while raw_text remains first\Nsecond. Text first\nsecond produces the same two lines with effective wrap mode 2 and ["first second"] otherwise. Projection scans explicit escapes only in literal text spans, preserving malformed ambiguous content under the rules below rather than treating override parameters or drawing commands as readable line breaks.

An iterative scanner retains Text and separates ordered literal-text, override/comment, and drawing spans with half-open Unicode scalar offsets into Text. Override blocks and tag occurrences preserve lexemes, duplicate tags, parameters, and encounter order. Basic emphasis and reset state (\b, \i, \u, \s, \r) may supply derived semantic spans; positioning, movement, clipping, transforms, fading, colors, scale, rotations, font selection, and effects remain native semantics with no visual-equivalence claim. Unrecognized tags are retained and diagnosed, never deleted. Alphabetic reset/font parameters are split from r/fn only when the complete suffix identifies a declared style/font-family name; otherwise the entire unknown alphabetic name survives with unsupported_override. This conservative interpretation replaces unconditional prefix guessing without changing raw Text. Unterminated or nested braces are retained verbatim with malformed_override; plain-text projection keeps ambiguous text rather than deleting it, and strict rendering/conversion refuses the diagnosed ambiguity. This differs deliberately from renderer-specific recovery noted in R5.

Positive \p enters drawing mode and \p0 leaves it. Drawing spans and drawing commands remain native and are excluded from readable dialogue text, with native-derived provenance explaining that exclusion. Unsupported drawing commands, clipping paths, and baseline offsets remain retained. Invalid or ambiguous drawing-state transitions fail encode because reliable dialogue-vs-drawing projection is unavailable. A drawing-only cue has empty derived plain text while retaining its timed native payload; conversion must report the drawing loss, not silently omit its existence.

Karaoke tags \k, \K, \kf, and \ko retain native centisecond durations and variant identity. The selected derived token profile requires nonnegative checked durations, sequential cumulative timing anchored to cue start, and intervals within the cue. \kt, negative/overflowing durations, ambiguous nested state, and out-of-cue sums remain retained with unsupported_karaoke_timing; they produce no fabricated timed tokens and block strict operations. Native syllable occurrences remain inspectable even when timed tokens cannot be derived. Name/Actor values yield only native speaker observations, with explicit event-field provenance; no speaker inference uses style names, local accounts, or attachment metadata. Text-native cues have no OCR observations unless a later explicitly provenanced operation supplies them.

Attachments, external metadata, and privacy

Embedded font and graphic declarations and their encoded lines remain ordered inside the captured script. Header names must satisfy the existing portable safe-basename rules; duplicate safe names are retained as distinct occurrences with a diagnostic, not written to a filesystem. The selected attachment profile checks the custom 6-bit encoded alphabet, final-group validity, line bounds, and decoded length without loading a font or image. Malformed bounded encoded content is retained with malformed_attachment and blocked from model rendering; whole encode fails if it exceeds a limit. Embedded binary bytes are content, not executable authority. Do not register fonts, decode image pixels, extract attachments, or discover companion assets during these workflows.

R4 identifies Audio URI, Audio File, Video File, Timecodes File, Keyframes File, Automation Scripts, Last Style Storage, and authoring settings as external-resource or environment metadata. Nonempty known resource/path fields, path-bearing attachment headers, and explicit machine identity metadata fail whole encode with unsafe_source_metadata, including their occurrences in Script Info, Aegisub Project Garbage, or equivalent recognized authoring locations. Empty resource fields may be retained. Relative paths and remote URIs are also rejected in these known slots: they neither become safe basename guesses nor authorize access. Automation templates, Command events, and explicit script execution references are rejected with unsafe_active_content, without running them.

The active Effect classification includes Karaoke Templater code directives such as code once, code line and code syl, alongside template and !code forms. Outside explicit dialogue/font/actor/style content roles, slash or backslash separators are conservatively treated as resource markers, including relative paths. Ambiguous separator-bearing title prose may therefore reject instead of receiving a guessed content exemption. These checks apply to original and edited native views and publish no sanitized substitute.

This is a deliberate accepted-source restriction rather than silent sanitization. Deleting only parsed metadata would leave prohibited information inside the required original source bytes. A rejected operation therefore publishes no Cue JSON or rendered output, and never modifies the caller's source. Privacy inspection covers original decoded metadata records and future edited native values regardless of whether their section or key is recognized. Unknown authoring metadata carrying filesystem references, external resource URIs, or environment identities also fails whole encode/render with unsafe_source_metadata. This includes drive/UNC/POSIX/home-relative paths, explicit relative resource references, and identity-bearing keys or assignment markers; absence from the known-key list is never evidence of safety.

Unknown metadata may be retained only when its inert, non-environment content role is established by the accepted profile; unclassifiable authoring metadata fails whole operation with unsafe_source_metadata rather than being copied into raw_line or the embedded original source. An unrecognized section is not a privacy exemption. P05-P08 must define a closed, fixture-backed context classification: metadata in Script Info, Aegisub Project Garbage, and unknown authoring/metadata sections is inspected conservatively, while dialogue/event Text, font-family names, and bounded embedded asset content keep their explicit content roles. Unknown non-Text/style extension fields are retained only as bounded inert scalars; environment/resource-bearing names and path-bearing or unclassifiable values reject. A field name alone cannot grant another context's content exemption. Unknown inert comments and records within an established content role retain their original bytes and ordering. Checks must not mistake dialogue punctuation, a spoken filename, or a font-family name for captured runtime identity. Diagnostics identify the reason and bounded record position, never echo an unsafe path, machine identity, asset bytes, or script body.

Model edits and deterministic rendering

Restoration always reads integrity-verified source assets, not reconstructed records. Rendering validates the complete model, source envelope, native references, privacy rules and ownership before opening a destination. Recognized records are serialized from owning structured values; raw_line is never replayed over edited timing, Text, style fields, or declared-field values. Capture-time timestamp lexemes and raw time-field occurrences remain unchanged observations while common timing supplies canonical rendered Start/End. Regenerating rendered timestamps does not normalize or rewrite those original-source views; semantic validation must not demand their equality to an edited common time. Editing event Text requires updating common raw payload and its deterministic derived text/speakers/tokens consistently; editing only derived plain text is rejected with inconsistent_projection. Common timing changes similarly require recomputing derived karaoke token timing. These failures prevent silently stale views from overriding or ignoring user edits.

Non-time native field edits must update both the owning typed value and its lexical occurrence, or omit the optional typed value so the validator derives it from that occurrence. Start/End are the explicit exception: common timing owns edits and captured native time lexemes stay original observations. Multiple competing editable values are invalid. Known records retain their active declaration's accepted field order, including unknown fields. For a constructed owner without a captured declaration reference, the renderer uses canonical dialect field names/order with ordered unknown additions before final event Text, and emits the required declaration when it differs from the active one. If a following captured owner refers to its original declaration, the renderer restores that declaration before serializing the owner. These output-only transitions never modify source positions, captures or declaration references. Exact field-name whitespace is joined without adding new separator spaces, preventing repeated render/parse cycles from expanding declaration whitespace. All style/non-Text fields reject inserted commas, CR/LF, NUL, and unsafe metadata before publication. No serializer replaces commas with semicolons or silently removes newlines, even though R5 illustrates such behaviors in another tool.

Capture-only raw_header, raw_line, and timestamp lexemes are present for ingested occurrences when observed, and omitted for newly constructed occurrences without a captured value. Each supplied observation must match its physical position in the integrity-verified original source; timestamp observations use that source record's active Format declaration. They are never fabricated from canonical output or required to equal later edited values. Constructed recognized sections and records serialize from their structured owners and common timing. Retained uninterpreted records and encoded attachment-data records require their truthful raw_line because no structured content owner can reconstruct them; constructing such a record without an explicit supported content owner fails model validation. P05/P08 must verify new structured section/style/dialogue construction without capture fields, alongside edited captured-record rendering.

The renderer writes UTF-8 without BOM, LF physical lines, normalized prefixes, deterministic canonical recognized scalar formatting, retained ordering, and a final LF. Unknown inert lines and blank/comment records may reuse their retained decoded raw text after safety checks. It never reorders by timestamp, deduplicates styles/events, executes effects, flattens overrides, or fetches attachments. Uninterpretable declarations, malformed retained records/attachments, unresolved ownership, or unsafe ambiguity fail rendering in all modes. Permissive rendering may emit safely interpretable diagnosed unknown/duplicate native content with warnings; strict mode rejects every known conformance ambiguity before publication.

Safely bounded malformed non-dialogue records and attachment content remain preservation-only with truthful raw captures and diagnostics. A malformed or empty attachment header has no fabricated attachment owner or zero-length data range. Accepted-source privacy checks still apply before retention, so a malformed prefix cannot grant Text, font or embedded-content exemptions. Generic inspection and exact restoration may accept these retained documents; model-driven rendering refuses them in both modes. The renderer reparses its complete bounded document before exposing bytes, independently checking declaration/framing safety and conformance diagnostics even when an edited model omitted an observation.

Parse-render-parse equivalence compares dialect, complete item ordering and occurrence identities after position-based remapping, declared unknown field/value order, styles, events, attachments, common timing/text/speakers/tokens, and safety classifications. Canonical whitespace, BOM, line terminators, numeric lexemes, capture-only raw-line observations, and diagnostic line positions may differ; source restoration is tested separately for exact original bytes. A successful textual cycle proves model semantics and retention under this profile, not identical subtitle pixels across renderers.

Deterministic diagnostics and bounds

P05-P08 must define and test closed diagnostic identifiers, severity, stable encounter ordering, safe positions, and strict/fatal effects. Diagnostics retain no caller path or unsafe source value. Fatal errors and strict losses publish no partial destination, no partial structured stdout, and no source rewrite. Independent diagnostics cannot be lost through first-error shortcuts except after a fatal acquisition/decoding/complexity boundary makes continued examination unsafe.

The implementation remains subordinate to the unchanged shared limits: 64 MiB native input, 1 GiB Cue JSON input, 65,536 document items, 1,024 repeated values per item, and 8,192 diagnostics or conversion losses. The model collection limits remain the owning implementation baseline. Scripted sections plus physical records have a combined 65,536-occurrence ceiling; each style/event/attachment occurrence references those records rather than amplifying that item count. Field, tag, span, speaker, and token arrays never exceed 1,024 occurrences in their owning item. Attachment data uses a checked contiguous record range rather than duplicating all data lines inside one repeated-value array; ranges must stay in the owning section, reference only encoded-data records, and not overlap another attachment's range. A 128-field declaration ceiling and 1,000,000 total field occurrences further constrain amplification.

Additional selected-profile limits are 1 MiB per physical line, nesting depth 32, 1,000,000 total tags/spans per document, 1,024 attachment occurrences, 16 MiB decoded per attachment and 32 MiB decoded attachment content in total, and 64 MiB canonical native output so accepted rendered files remain within the reparse acquisition bound. Attachment encoded data lines are additionally at most 80 ASCII bytes each; the shared physical-record ceiling can reject a bundle before these byte limits are reached. Checked arithmetic and iterative scanning prevent overflow, recursion exhaustion, and superlinear rescanning. Crossing any ceiling fails with complexity_limit; no silent truncation, omitted record, replacement source envelope, or success-with-incomplete-diagnostics/losses is allowed. P12 must prove native platform and fuzz boundaries; any limit adjustment requires an explicit contract change with evidence before stable freeze.

Source-linked acceptance and evidence matrix

Each row identifies an acceptance requirement and its verification owners. S025 supplies corpus/ingest/render/restoration evidence, S026 supplies all twelve conversion directions, S027 supplies shared CLI and conformance/hostile-input evidence, S028 closes the stable render/platform gates with exact release identity and packaged-host proof, and #66 establishes independently verified public release availability. The executable conformance matrix links every row to valid governed evidence; public schema/site hosting remains separate.

The frozen profile is limited to these seventeen acceptance rows. Stable contract, conformance and publication do not grant visual equivalence, legacy encoding support or external resource execution. Profiles outside these rows require an explicit ratified expansion; schema recognition and exact restoration alone do not establish native support.