fix styled ASS and refactor att format

requirements/source_file_formats.md

@@ -0,0 +1,90 @@
+# Source File Formats
+
+This file defines source-file-format-specific processing requirements for FFX.
+It is intended to grow as additional relevant source file types are identified.
+
+The first covered format is Matroska media that contains styled ASS/SSA
+subtitle streams together with embedded font attachments.
+
+## Scope
+
+- Detecting source files that use ASS subtitle streams together with embedded
+  font attachments needed for correct rendering.
+- Defining the required `ffx convert` behavior when this format is present.
+- Preserving the required attachment streams during conversion.
+- Keeping normal subtitle-track manipulation behavior for the ASS subtitle
+  tracks themselves.
+
+## Out Of Scope
+
+- General subtitle behavior for sources that do not carry this pattern.
+- A complete catalog of all source file formats FFX may support later.
+
+## Terms
+
+- `styled ASS source`: a source media file that contains one or more subtitle
+  streams with `codec_type="subtitle"` and `codec_name="ass"` together with
+  one or more font-bearing attachment streams.
+- `font attachment`: an attachment stream whose metadata identifies a font
+  payload, commonly through `tags.mimetype` and attachment filename metadata.
+- `external subtitle feed`: subtitle tracks supplied from separate subtitle
+  files through the existing subtitle-import path.
+- `special attachment subtracks`: the embedded font attachment streams that
+  belong to the styled ASS source pattern.
+
+## Rules
+
+- `SOURCE_FILE_FORMATS-0001`: The system shall recognize the styled ASS source
+  pattern.
+- `SOURCE_FILE_FORMATS-0002`: Recognition shall not depend on fixed stream
+  counts, fixed stream indices, or one exact attachment count.
+- `SOURCE_FILE_FORMATS-0003`: Recognition shall use the best available ffprobe
+  signals. For known subtitle streams this includes
+  `codec_type="subtitle"` together with `codec_name="ass"`.
+- `SOURCE_FILE_FORMATS-0004`: Recognition of the special attachment subtracks
+  shall use attachment-oriented signals such as `codec_type="attachment"` and
+  font-identifying metadata such as `tags.mimetype="font/ttf"` when present.
+- `SOURCE_FILE_FORMATS-0005`: Recognition shall tolerate known ffprobe
+  variation in attachment reporting, including files where attachment streams
+  do not expose a `codec_name` but do expose `codec_type="attachment"` and
+  font-identifying tags.
+- `SOURCE_FILE_FORMATS-0006`: When attachment metadata varies across files,
+  detection shall not depend on one exact MIME string alone. Detection shall
+  be written so the known pattern can vary while still recognizing font
+  attachments.
+- `SOURCE_FILE_FORMATS-0007`: When the styled ASS source pattern is detected,
+  `ffx convert` shall emit an operator-facing message that reports the
+  detection and hints that special subtitle preservation handling is being
+  applied.
+- `SOURCE_FILE_FORMATS-0008`: When the styled ASS source pattern is present on
+  the source file, `ffx convert` shall not process an external subtitle feed.
+  The command shall stop before conversion and report an error that explains
+  that separate subtitle-file import is incompatible with this source format.
+- `SOURCE_FILE_FORMATS-0009`: Normal manipulation of the ASS subtitle streams
+  themselves shall continue to work through the usual selection, ordering,
+  metadata, language, title, and disposition handling paths.
+- `SOURCE_FILE_FORMATS-0010`: The special attachment subtracks shall be
+  preserved in the target media file as-is rather than transcoded,
+  regenerated, or replaced from external sources.
+- `SOURCE_FILE_FORMATS-0011`: Preserving the special attachment subtracks
+  as-is includes retaining the attachment payload and the attachment metadata
+  required by consumers, especially attachment filename and mimetype
+  information.
+- `SOURCE_FILE_FORMATS-0012`: This file shall remain the extension point for
+  additional source-file-format contracts as FFX adds support for more special
+  source formats.
+
+## Acceptance
+
+- A source file matching the observed pattern of embedded ASS subtitles plus
+  font attachments is recognized even when the attachment streams do not carry
+  a `codec_name`.
+- `ffx convert` output contains a clear detection message before the actual
+  conversion work proceeds.
+- If external subtitle import is requested for such a source file, the command
+  fails fast with an explicit error instead of mixing sidecar subtitles into
+  the job.
+- Existing manipulation of the ASS subtitle tracks still works for metadata,
+  titles, languages, ordering, and dispositions.
+- The output media preserves the required font attachment streams and their
+  identifying metadata needed by downstream media players.