# 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.