91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
# 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.
|