Release v0.4.4

.gitignore

@@ -1,7 +1,6 @@
 __pycache__/
 *.py[cod]
 junk/
-.vscode
 .ipynb_checkpoints/
 tools/ansible/inventory/hawaii.yml
 tools/ansible/inventory/peppermint.yml
@@ -10,11 +9,14 @@ tools/ansible/inventory/group_vars/all.yml
 ffx_test_report.log
 bin/conversiontest.py
 
+tests/assets/
+
 build/
 dist/
 *.egg-info/
 .venv/
 venv/
+docs/_build/
 .codex
 
 

.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "swyddfa.esbonio",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-python.debugpy",
+    "tamasfe.even-better-toml",
+    "redhat.vscode-yaml",
+    "DavidAnson.vscode-markdownlint"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+  "esbonio.sphinx.pythonCommand": "${venv:.venv}/bin/python",
+  "esbonio.sphinx.buildCommand": [
+    "sphinx-build",
+    "-b",
+    "html",
+    "docs",
+    "docs/_build/html"
+  ],
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": [
+    "--ignore=tests/legacy",
+    "--ignore=tests/support",
+    "tests"
+  ],
+  "restructuredtext.confPath": "${workspaceFolder}/docs"
+}

README.md

@@ -99,75 +99,4 @@ TMDB-backed metadata enrichment requires `TMDB_API_KEY` to be set in the environ
 
 ## Version History
 
-### 0.3.0
+See the [version history](docs/history.rst) for release notes.
-
-- inspect and edit screens now refresh nested track and pattern changes more reliably, with inspect-mode tables aligned to the target pattern view shown in the differences pane
-- metadata editing got a follow-up polish pass with clearer ffmpeg notifications, a shared in-screen log pane, safer apply/reload handling, and expanded cleanup and normalization coverage
-- track and asset probing recognize additional codecs, and the modern test suite now covers more metadata-editor, change-set, screen-state, and asset-probe behavior
-- Textual now requires version `8.0` or newer to match the UI APIs used by the current screens
-
-### 0.2.6
-
-- DB-free `ffx edit` workflow for in-place metadata editing via temporary-file rewrite
-- inspect and edit workflows split into dedicated Textual screens with shared media-workflow support
-- Textual tables and row actions now separate raw data from rendered labels to avoid markup leaking into stored metadata
-- responsive screen layout pass, `Esc` back handling, sortable show/inspect tables, and improved edit-screen notifications/toggles
-- application-wide UTF-8 i18n catalogs with language precedence from CLI over config over system over German default
-- metadata normalization extended for localized subtitle titles, ISO language cleanup, and smarter track editor language/title helpers
-
-### 0.2.5
-
-- show-level quality and notes fields
-- pattern-over-show-over-default season-shift resolution with dynamic DB migration loading
-- migration prompt now reports the upgrade path and creates an in-place DB backup before applying schema changes
-- `upgrade --branch <name>` now fetches remote-only branches before switching
-- `unmux` now applies season shifting to subtitle output filenames
-- convert now keeps DB-defined target subtitle dispositions authoritative over sidecar filename disposition flags when a pattern definition exists
-- focused modern tests added around migrations, unmux, upgrade, and subtitle-disposition import precedence
-
-### 0.2.4
-
-- lightweight CLI commands now stay import-light via lazy runtime loading
-- setup/config templating moved to `assets/ffx.json.j2`
-- aligned two-step local setup wrappers: `ffx setup` and `ffx configure_workstation`
-- combined `ffprobe` payload reuse in `FileProperties`
-- configurable crop-detect sampling plus per-process crop result caching
-- single-query controller accessors and conditional DB schema bootstrap
-- shared screen bootstrap/controller wiring for large detail screens
-- configurable default season/episode digit lengths
-- digit-aware `rename` and padded `unmux` filename markers
-
-### 0.2.3
-
-- PyPI packaging
-- output filename templating
-- season shifting
-- DB versioning
-
-### 0.2.2
-
-- CLI overrides
-
-### 0.2.1
-
-- signature handling
-- tag cleanup
-- bugfixes and refactoring
-
-### 0.2.0
-
-- tests
-- config file
-
-### 0.1.3
-
-- subtitle file imports
-
-### 0.1.2
-
-- bugfixes
-
-### 0.1.1
-
-- bugfixes
-- TMDB show identification

docs/Makefile

@@ -0,0 +1,21 @@
+SPHINXOPTS       ?=
+VENV_SPHINXBUILD = ../.venv/bin/sphinx-build
+SPHINXBUILD      ?= $(if $(wildcard $(VENV_SPHINXBUILD)),$(VENV_SPHINXBUILD),sphinx-build)
+SOURCEDIR        = .
+BUILDDIR         = _build
+
+.PHONY: help clean html linkcheck
+
+help:
+	@echo "Please use 'make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+linkcheck:
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)

docs/api.rst

@@ -0,0 +1,31 @@
+API Reference
+=============
+
+This section exposes selected modules that are useful when working on tests,
+diagnostics, process execution, metadata editing, and file probing.
+
+CLI Helpers
+-----------
+
+.. automodule:: ffx.cli
+   :members:
+   :undoc-members:
+
+Process Helpers
+---------------
+
+.. automodule:: ffx.process
+   :members:
+   :undoc-members:
+
+File Probing
+------------
+
+.. automodule:: ffx.file_properties
+
+Metadata Editing
+----------------
+
+.. automodule:: ffx.metadata_editor
+   :members:
+   :undoc-members:

docs/conf.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as package_version
+from pathlib import Path
+import sys
+
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+SRC_DIR = ROOT_DIR / "src"
+sys.path.insert(0, str(SRC_DIR))
+
+project = "FFX"
+author = "javanaut@maveno.de"
+copyright = "2026, Maveno"
+
+try:
+    release = package_version("ffx")
+except PackageNotFoundError:
+    release = "0.0.0"
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "FFX"
+html_static_path = []
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+

docs/development.rst

@@ -0,0 +1,50 @@
+Development
+===========
+
+The repo-local ``.venv`` is the preferred environment for contributors working
+on tests or documentation:
+
+.. code-block:: sh
+
+   tests/prepare.sh
+
+The preparation script installs the package in editable mode with both test and
+documentation extras:
+
+.. code-block:: text
+
+   .[test,docs]
+
+Run Tests
+---------
+
+Run the modern pytest suite:
+
+.. code-block:: sh
+
+   .venv/bin/python -m pytest --ignore=tests/legacy --ignore=tests/support tests
+
+The legacy harness remains available separately and is intentionally not part of
+the default pytest run.
+
+Build Docs
+----------
+
+Build HTML documentation:
+
+.. code-block:: sh
+
+   .venv/bin/sphinx-build -b html docs docs/_build/html
+
+The same command is wrapped by the Sphinx ``Makefile``:
+
+.. code-block:: sh
+
+   make -C docs html
+
+VS Code
+-------
+
+The repository includes ``.vscode/extensions.json`` with recommended
+extensions, including Esbonio for Sphinx language-server support. The workspace
+settings point Python tooling and Esbonio at the repo-local ``.venv``.

docs/file_formats.rst

@@ -0,0 +1,192 @@
+File Formats
+============
+
+This document captures source-file-format notes that complement the normative
+requirements in ``requirements/source_file_formats.md``.
+
+The first documented format is a Matroska source that carries styled ASS/SSA
+subtitle streams together with embedded font attachments.
+
+Styled ASS In Matroska With Embedded Fonts
+------------------------------------------
+
+These files are typically ``.mkv`` releases where subtitle rendering quality
+depends on keeping both parts of the subtitle package together:
+
+* one or more subtitle streams with codec ``ass``
+* one or more attachment streams that embed font files used by those subtitles
+
+This matters because ASS subtitles are not plain text subtitles in the narrow
+WebVTT sense. They can carry layout, styling, positioning, karaoke, signs, and
+other typesetting effects. If the matching embedded fonts are lost, consumers
+can still see subtitle text but the intended styling and sometimes glyph
+coverage can be degraded.
+
+For FFX this format is special because the ASS subtitle streams should remain
+normally editable and mappable, while the related font attachments should be
+transported unchanged.
+
+Observed Sample
+---------------
+
+Assessment date: ``2026-04-17``
+
+Observed sample file:
+
+* ``tests/assets/boruto_s01e283_ssa.mkv``
+
+Commands used for assessment:
+
+.. code-block:: bash
+
+   ffprobe tests/assets/boruto_s01e283_ssa.mkv
+   ffprobe -hide_banner -show_format -show_streams -of json tests/assets/boruto_s01e283_ssa.mkv
+
+Observed stream layout:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Stream index
+     - Kind
+     - Key details
+   * - ``0``
+     - video
+     - ``codec_name=h264``
+   * - ``1``
+     - audio
+     - ``codec_name=aac``, ``language=jpn``
+   * - ``2``
+     - subtitle
+     - ``codec_name=ass``, ``language=ger``, default
+   * - ``3``
+     - subtitle
+     - ``codec_name=ass``, ``language=eng``
+   * - ``4``-``13``
+     - attachment
+     - ``tags.mimetype=font/ttf``, ``.ttf`` filenames
+
+Observed attachment filenames:
+
+* ``AmazonEmberTanuki-Italic.ttf``
+* ``AmazonEmberTanuki-Regular.ttf``
+* ``Arial.ttf``
+* ``Arial Bold.ttf``
+* ``Georgia.ttf``
+* ``Times New Roman.ttf``
+* ``Times New Roman Bold.ttf``
+* ``Trebuchet MS.ttf``
+* ``Verdana.ttf``
+* ``Verdana Bold.ttf``
+
+Important probe behavior from the real sample:
+
+* Plain ``ffprobe`` lists the font streams as ``Attachment: none``.
+* Plain ``ffprobe`` also prints warnings such as ``Could not find codec
+  parameters for stream 4 (Attachment: none): unknown codec`` and later
+  ``Unsupported codec with id 0 for input stream ...``.
+* The JSON produced by ``FileProperties.FFPROBE_COMMAND_TOKENS``
+  (``ffprobe -hide_banner -show_format -show_streams -of json``) still exposes
+  the attachment streams clearly through ``codec_type="attachment"`` and the
+  attachment tags.
+* In that JSON, the attachment streams do not expose ``codec_name``.
+
+This last point is important for FFX: robust detection must not depend on
+attachment ``codec_name`` being present.
+
+Detection Guidance
+------------------
+
+Current known indicators for this format are:
+
+* one or more subtitle streams with ``codec_type="subtitle"`` and
+  ``codec_name="ass"``
+* one or more attachment streams with ``codec_type="attachment"``
+* attachment tags that identify embedded fonts, especially
+  ``tags.mimetype="font/ttf"``
+* attachment filenames that end in ``.ttf``
+
+The pattern can vary. FFX should therefore treat the above as a cluster of
+signals rather than an exact signature tied to one file.
+
+Inference from the observed sample plus FFmpeg documentation:
+
+* MIME matching should not be limited to ``font/ttf`` alone.
+* The Boruto sample uses ``font/ttf``.
+* FFmpeg's Matroska attachment example uses
+  ``mimetype=application/x-truetype-font`` for a ``.ttf`` attachment.
+* Detection should therefore normalize multiple TTF-like MIME values rather
+  than depend on a single exact string.
+
+Processing Expectations In FFX
+------------------------------
+
+The format-specific requirements live in
+``requirements/source_file_formats.md``. In practical terms, FFX should:
+
+* recognize the ASS-plus-font-attachment pattern even when attachment probe data
+  is incomplete
+* tell the operator that the pattern was detected and that special handling is
+  being used
+* reject sidecar subtitle import for such sources, because converting or
+  replacing these subtitle tracks with ordinary external text subtitles would
+  break the intended subtitle package
+* continue to allow normal manipulation of the ASS subtitle tracks themselves
+* preserve the font attachment streams unchanged
+
+FFmpeg Notes
+------------
+
+Relevant FFmpeg documentation confirms several behaviors that line up with
+FFX's needs:
+
+* FFmpeg documents ``-attach`` as adding an attachment stream to the output, and
+  explicitly names Matroska fonts used in subtitle rendering as an example.
+* FFmpeg documents attachment streams as regular streams that are created after
+  the mapped media streams.
+* FFmpeg documents ``-dump_attachment`` for extracting attachment streams, which
+  is useful for debugging or validating a source file's embedded fonts.
+* FFmpeg's Matroska example requires a ``mimetype`` metadata tag for attached
+  fonts, which is consistent with using attachment tags as detection signals.
+* FFmpeg also notes that attachments are implemented as codec extradata. That
+  helps explain why probe output for attachment streams can look different from
+  ordinary audio, video, and subtitle streams.
+
+Implication for FFX:
+
+* Attachment preservation is not an optional cosmetic feature for this format.
+  It is part of preserving the subtitle package correctly.
+
+Jellyfin Notes
+--------------
+
+Jellyfin's documentation also supports keeping this format intact:
+
+* Jellyfin's subtitle compatibility table lists ``ASS/SSA`` as supported in
+  ``MKV`` and not supported in ``MP4``.
+* Jellyfin notes that when subtitles must be transcoded, they are either
+  converted to a supported format or burned into the video, and burning them in
+  is the most CPU-intensive path.
+* Jellyfin's subtitle-extraction example for ``SSA/ASS`` first dumps attachment
+  streams and then extracts the ASS subtitle stream, which reflects the real
+  relationship between ASS subtitles and embedded fonts in MKV releases.
+* Jellyfin's font documentation says text-based subtitles require fonts to
+  render properly.
+* Jellyfin's configuration documentation says the web client uses configured
+  fallback fonts for ASS subtitles when other fonts such as MKV attachments or
+  client-side fonts are not available.
+
+Inference from the Jellyfin compatibility tables:
+
+* Keeping this subtitle format in Matroska is the safest interoperability choice
+  for Jellyfin consumers.
+* Converting the subtitle payload to WebVTT would lose styled ASS behavior.
+* Dropping the attachment streams would force client or fallback font
+  substitution and can change appearance or glyph coverage.
+
+References
+----------
+
+* FFmpeg documentation: https://ffmpeg.org/ffmpeg.html
+* Jellyfin codec support: https://jellyfin.org/docs/general/clients/codec-support/
+* Jellyfin configuration and fonts: https://jellyfin.org/docs/general/administration/configuration/

docs/history.rst

@@ -0,0 +1,123 @@
+Version History
+===============
+
+0.4.4
+-----
+
+- External subtitle imports can now match prefixless sidecar files against the source basename, choose their extension, and confirm partial substitutions.
+- Unmux now creates missing output directories with confirmation or the new ``--yes`` option.
+- Project documentation is now built with Sphinx and includes installation, usage, development, file-format, and API references.
+
+0.4.3
+-----
+
+- Styled ASS subtitle sources with embedded font attachments are now detected explicitly, keep MKV output, preserve current source font attachments, and reject incompatible sidecar subtitle import.
+- Attachment descriptors are now treated as source-runtime data instead of pattern schema data, so pattern persistence skips them and source-vs-pattern validation ignores them.
+- Inspect differences no longer report planned changes for attachment filename/count drift while still showing attachment streams in the stream table.
+
+0.4.2
+-----
+
+- Pattern details now show an inline ``Show: <quality>`` hint next to the quality field when the pattern itself has no stored quality but the selected show does.
+- Inspect stream tables now show attachment format labels like ``TTF`` in the codec column and keep attachment language cells blank instead of showing an undefined language.
+- FFmpeg damaged-MP3 diagnostics now recognize additional corruption lines such as ``invalid new backstep``, keeping them grouped under the ``warn-corrupt-mpeg-audio`` review summary.
+
+0.4.1
+-----
+
+- ``convert`` now supports ``--copy-video`` and ``--copy-audio`` to keep the selected stream type in copy mode without applying the corresponding reencode flags, filters, or formatting options.
+- FFmpeg conversions now monitor diagnostics while the process is running, retry unset AVI packet timestamps once with ``-fflags +genpts``, and stop early when a file should be skipped instead of waiting for the full job to finish.
+- End-of-run convert summaries now list only FFmpeg findings that still require review, including named remedy identifiers such as ``warn-corrupt-mpeg-audio``.
+- ``upgrade`` now finishes by reporting the installed FFX version together with the active bundle branch.
+
+0.3.1
+-----
+
+- Debug mode screen titles now append the active Textual screen class name, making screen-specific troubleshooting easier during inspect and edit flows.
+- ``--cut`` again works as a combined flag/option: omitted disables cutting, bare ``--cut`` applies the default ``60,180``, and explicit duration or ``START,DURATION`` values stay supported.
+- H.265 unmux commands no longer force an invalid ``-f h265`` output format, keeping FFmpeg copy extraction aligned with the required Annex B bitstream filter.
+- H.264 encoding now falls back from ``libx264`` to ``libopenh264`` with a warning when needed, and the test fixtures use the same encoder fallback so the suite remains portable across FFmpeg builds.
+
+0.3.0
+-----
+
+- Inspect and edit screens now refresh nested track and pattern changes more reliably, with inspect-mode tables aligned to the target pattern view shown in the differences pane.
+- Metadata editing got a follow-up polish pass with clearer FFmpeg notifications, a shared in-screen log pane, safer apply/reload handling, and expanded cleanup and normalization coverage.
+- Track and asset probing recognize additional codecs, and the modern test suite now covers more metadata-editor, change-set, screen-state, and asset-probe behavior.
+- Textual now requires version ``8.0`` or newer to match the UI APIs used by the current screens.
+
+0.2.6
+-----
+
+- DB-free ``ffx edit`` workflow for in-place metadata editing via temporary-file rewrite.
+- Inspect and edit workflows split into dedicated Textual screens with shared media-workflow support.
+- Textual tables and row actions now separate raw data from rendered labels to avoid markup leaking into stored metadata.
+- Responsive screen layout pass, ``Esc`` back handling, sortable show/inspect tables, and improved edit-screen notifications/toggles.
+- Application-wide UTF-8 i18n catalogs with language precedence from CLI over config over system over German default.
+- Metadata normalization extended for localized subtitle titles, ISO language cleanup, and smarter track editor language/title helpers.
+
+0.2.5
+-----
+
+- Show-level quality and notes fields.
+- Pattern-over-show-over-default season-shift resolution with dynamic DB migration loading.
+- Migration prompt now reports the upgrade path and creates an in-place DB backup before applying schema changes.
+- ``upgrade --branch <name>`` now fetches remote-only branches before switching.
+- ``unmux`` now applies season shifting to subtitle output filenames.
+- Convert now keeps DB-defined target subtitle dispositions authoritative over sidecar filename disposition flags when a pattern definition exists.
+- Focused modern tests added around migrations, unmux, upgrade, and subtitle-disposition import precedence.
+
+0.2.4
+-----
+
+- Lightweight CLI commands now stay import-light via lazy runtime loading.
+- Setup/config templating moved to ``assets/ffx.json.j2``.
+- Aligned two-step local setup wrappers: ``ffx setup`` and ``ffx configure_workstation``.
+- Combined ``ffprobe`` payload reuse in ``FileProperties``.
+- Configurable crop-detect sampling plus per-process crop result caching.
+- Single-query controller accessors and conditional DB schema bootstrap.
+- Shared screen bootstrap/controller wiring for large detail screens.
+- Configurable default season/episode digit lengths.
+- Digit-aware ``rename`` and padded ``unmux`` filename markers.
+
+0.2.3
+-----
+
+- PyPI packaging.
+- Output filename templating.
+- Season shifting.
+- DB versioning.
+
+0.2.2
+-----
+
+- CLI overrides.
+
+0.2.1
+-----
+
+- Signature handling.
+- Tag cleanup.
+- Bugfixes and refactoring.
+
+0.2.0
+-----
+
+- Tests.
+- Config file.
+
+0.1.3
+-----
+
+- Subtitle file imports.
+
+0.1.2
+-----
+
+- Bugfixes.
+
+0.1.1
+-----
+
+- Bugfixes.
+- TMDB show identification.

docs/index.rst

@@ -0,0 +1,31 @@
+FFX Documentation
+=================
+
+FFX is a local command-line and Textual terminal UI for inspecting TV episode
+files, storing normalization rules, and converting media into predictable
+archive-ready outputs.
+
+This documentation covers operator setup, day-to-day command usage, contributor
+workflow, format-specific notes, and generated API references for the smaller
+utility modules.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   installation
+   usage
+   file_formats
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Release Notes
+
+   history
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contributor Guide
+
+   development
+   api

docs/installation.rst

@@ -0,0 +1,52 @@
+Installation
+============
+
+FFX is designed for a Linux-like workstation with local command execution. The
+runtime media tools must be available on ``PATH``:
+
+* ``ffmpeg``
+* ``ffprobe``
+* ``cpulimit``
+
+User Bundle
+-----------
+
+The persistent user installation is prepared with the two-step flow described in
+the project README:
+
+.. code-block:: sh
+
+   bash tools/setup.sh
+   bash tools/configure_workstation.sh
+
+``tools/setup.sh`` creates the long-lived bundle virtualenv at
+``~/.local/share/ffx.venv`` and exposes the ``ffx`` command. The workstation
+script checks system tools and seeds local config directories.
+
+Local Test And Docs Environment
+-------------------------------
+
+Contributor test and documentation work uses the repo-local virtualenv:
+
+.. code-block:: sh
+
+   tests/prepare.sh
+
+The script creates ``.venv``, installs FFX in editable mode with test and docs
+extras, and verifies the Sphinx toolchain. Use check-only mode when you only
+want to inspect readiness:
+
+.. code-block:: sh
+
+   tests/prepare.sh --check
+
+Documentation Build
+-------------------
+
+After preparation, build the documentation with:
+
+.. code-block:: sh
+
+   .venv/bin/sphinx-build -b html docs docs/_build/html
+
+The generated site starts at ``docs/_build/html/index.html``.

docs/make.bat

@@ -0,0 +1,42 @@
+@ECHO OFF
+
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" if exist ..\.venv\Scripts\sphinx-build.exe (
+	set SPHINXBUILD=..\.venv\Scripts\sphinx-build.exe
+)
+if "%SPHINXBUILD%" == "" set SPHINXBUILD=sphinx-build
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo The 'sphinx-build' command was not found. Make sure Sphinx is installed,
+	echo then set SPHINXBUILD to the full path if needed.
+	exit /b 1
+)
+
+if "%1" == "" goto help
+if "%1" == "html" goto html
+if "%1" == "linkcheck" goto linkcheck
+echo.
+echo Unknown target "%1".
+goto help
+
+:html
+%SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS%
+goto end
+
+:linkcheck
+%SPHINXBUILD% -b linkcheck %SOURCEDIR% %BUILDDIR%\linkcheck %SPHINXOPTS%
+goto end
+
+:help
+echo.
+echo Please use 'make.bat ^<target^>' where ^<target^> is one of
+echo   html       to make standalone HTML files
+echo   linkcheck  to check all external links for integrity
+
+:end
+popd

docs/usage.rst

@@ -0,0 +1,97 @@
+Usage
+=====
+
+FFX exposes a single ``ffx`` command with subcommands for inspection,
+conversion, metadata editing, setup, and maintenance.
+
+Inspect Files
+-------------
+
+Open the inspection workflow for one or more files:
+
+.. code-block:: sh
+
+   ffx inspect /path/to/episode.mkv
+
+Print resolved season-shift mappings without opening the TUI:
+
+.. code-block:: sh
+
+   ffx inspect --shift /path/to/episode.mkv
+
+Convert Files
+-------------
+
+Convert one or more source files using stored rules where available:
+
+.. code-block:: sh
+
+   ffx convert /path/to/episode.mkv
+
+Useful overrides include:
+
+* ``--no-pattern`` to skip database pattern matching
+* ``--show``, ``--season``, and ``--episode`` for explicit episode identity
+* ``--output-directory`` for generated output placement
+* ``--subtitle-directory`` for source-basename sidecar subtitle imports
+* ``--subtitle-prefix`` for explicit or configured-prefix subtitle imports
+* ``--subtitle-extension`` to select the imported sidecar format (default:
+  ``vtt``)
+* ``--yes`` to accept a valid partial sidecar set without prompting
+* ``--copy-video`` or ``--copy-audio`` to preserve selected stream types
+* ``--rename-only`` for filename normalization without media rewriting
+
+Directory-only subtitle import matches the source basename. For example,
+``A2_t01.mkv`` discovers files such as ``A2_t01_2_deu_DEF.vtt`` in the
+provided directory:
+
+.. code-block:: sh
+
+   ffx convert --subtitle-directory /path/to/subtitles A2_t01.mkv
+
+Select a different sidecar set by extension, with or without the leading dot:
+
+.. code-block:: sh
+
+   ffx convert --subtitle-directory /path/to/subtitles \
+     --subtitle-extension .mkv A2_t01.mkv
+
+When only some source subtitle tracks have matching sidecar files, conversion
+asks for confirmation. Use ``--yes`` to substitute that valid subset without
+prompting. ``--yes`` also permits this case when ``--no-prompt`` is set.
+
+Manage Shows And Patterns
+-------------------------
+
+Open the Textual interface for show and pattern management:
+
+.. code-block:: sh
+
+   ffx shows
+
+Extract Streams
+---------------
+
+Extract streams from a file:
+
+.. code-block:: sh
+
+   ffx unmux /path/to/episode.mkv
+
+For subtitle-only extraction:
+
+.. code-block:: sh
+
+   ffx unmux --subtitles-only --label show-name /path/to/episode.mkv
+
+Detect Crop
+-----------
+
+Ask FFmpeg to suggest crop parameters:
+
+.. code-block:: sh
+
+   ffx cropdetect /path/to/episode.mkv
+
+The default sampling window is controlled by the application defaults and can be
+overridden with command options.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ffx"
 description = "FFX recoding and metadata managing tool"
-version = "0.3.0"
+version = "0.4.4"
 license = {file = "LICENSE.md"}
 dependencies = [
   "requests",
@@ -31,6 +31,12 @@ Issues = "https://gitea.maveno.de/Javanaut/ffx/issues"
 test = [
   "pytest",
 ]
+docs = [
+  "esbonio",
+  "sphinx",
+  "sphinx-copybutton",
+  "sphinx-rtd-theme",
+]
 
 [build-system]
 requires = [

src/ffx/attachment_format.py

@@ -0,0 +1,67 @@
+from enum import Enum
+import os
+
+
+class AttachmentFormat(Enum):
+
+    TTF = {'identifier': 'ttf', 'format': None, 'extension': 'ttf', 'label': 'TTF'}
+    PNG = {'identifier': 'png', 'format': None, 'extension': 'png', 'label': 'PNG'}
+
+    UNKNOWN = {'identifier': 'unknown', 'format': None, 'extension': None, 'label': 'UNKNOWN'}
+
+    def identifier(self):
+        return str(self.value['identifier'])
+
+    def label(self):
+        return str(self.value['label'])
+
+    def format(self):
+        return self.value['format']
+
+    def extension(self):
+        return str(self.value['extension'])
+
+    @staticmethod
+    def identify(identifier: str):
+        formats = [f for f in AttachmentFormat if f.value['identifier'] == str(identifier)]
+        if formats:
+            return formats[0]
+        return AttachmentFormat.UNKNOWN
+
+    @staticmethod
+    def identifyFfprobeStream(streamObj: dict):
+        identifier = streamObj.get("codec_name")
+        identifiedFormat = AttachmentFormat.identify(identifier)
+        if identifiedFormat != AttachmentFormat.UNKNOWN:
+            return identifiedFormat
+
+        if str(streamObj.get("codec_type", "")).strip() != "attachment":
+            return AttachmentFormat.UNKNOWN
+
+        tags = streamObj.get("tags", {}) or {}
+        mimetype = str(tags.get("mimetype", "")).strip().lower()
+        filename = str(tags.get("filename", "")).strip().lower()
+        filenameExtension = os.path.splitext(filename)[1]
+
+        if (
+            mimetype in {
+                "font/ttf",
+                "application/x-truetype-font",
+                "application/x-font-ttf",
+            }
+            or "truetype" in mimetype
+            or filenameExtension == ".ttf"
+        ):
+            return AttachmentFormat.TTF
+
+        if mimetype in {"image/png", "image/x-png"} or filenameExtension == ".png":
+            return AttachmentFormat.PNG
+
+        return AttachmentFormat.UNKNOWN
+
+    @staticmethod
+    def fromTrackCodec(trackCodec):
+        identifier = getattr(trackCodec, "identifier", None)
+        if callable(identifier):
+            return AttachmentFormat.identify(trackCodec.identifier())
+        return AttachmentFormat.UNKNOWN

src/ffx/cli.py

@@ -41,13 +41,17 @@ CPU_OPTION_HELP = (
     + "Omit to disable; 0 also disables."
 )
 SUBTITLE_DIRECTORY_OPTION_HELP = (
-    "Load subtitles from here. When omitted and --subtitle-prefix is set, "
+    "Load subtitles from here. Without --subtitle-prefix, match the source filename "
+    + "basename. When omitted and --subtitle-prefix is set, "
     + "FFX uses the configured subtitlesDirectory base path plus the prefix as a subdirectory."
 )
 SUBTITLE_PREFIX_OPTION_HELP = (
     "Subtitle filename prefix. Requires --subtitle-directory, or a configured "
     + "subtitlesDirectory base path that contains a matching <prefix>/ subdirectory."
 )
+SUBTITLE_EXTENSION_OPTION_HELP = (
+    "External subtitle filename extension. A leading dot is optional."
+)
 UNMUX_OUTPUT_DIRECTORY_OPTION_HELP = (
     "Write extracted streams here. When omitted together with --subtitles-only and "
     + "--label, FFX uses the configured subtitlesDirectory base path plus the label."
@@ -68,6 +72,14 @@ CUT_OPTION_HELP = (
     + "or --cut START,DURATION for an explicit start and duration. "
     + "Omit to disable."
 )
+COPY_VIDEO_OPTION_HELP = (
+    "Copy video streams without re-encoding. Skips video encoder options "
+    + "and video filters."
+)
+COPY_AUDIO_OPTION_HELP = (
+    "Copy audio streams without re-encoding. Skips audio encoder options "
+    + "and audio filters."
+)
 
 
 def normalizeNicenessOption(ctx, param, value):
@@ -88,6 +100,18 @@ def normalizeCpuOption(ctx, param, value):
         raise click.BadParameter(str(ex)) from ex
 
 
+def normalizeSubtitleExtension(ctx, param, value):
+    normalizedExtension = str(value).strip().lower()
+    if normalizedExtension.startswith('.'):
+        normalizedExtension = normalizedExtension[1:]
+    if not normalizedExtension or not normalizedExtension.isalnum():
+        raise click.BadParameter(
+            "Subtitle extension must contain only letters and numbers, "
+            + "with an optional leading dot."
+        )
+    return normalizedExtension
+
+
 def parseCutOptionValue(value) -> tuple[int, int] | None:
     if value is None:
         return None
@@ -138,11 +162,21 @@ def resolveSubtitleImportOptions(context, subtitleDirectory, subtitlePrefix):
         else ''
     )
 
-    if not resolvedSubtitlePrefix:
-        return False, resolvedSubtitleDirectory, resolvedSubtitlePrefix
-
     if resolvedSubtitleDirectory:
-        return True, resolvedSubtitleDirectory, resolvedSubtitlePrefix
+        if not os.path.isdir(resolvedSubtitleDirectory):
+            raise click.ClickException(
+                "The provided subtitle directory does not exist: "
+                + resolvedSubtitleDirectory
+            )
+        return (
+            True,
+            resolvedSubtitleDirectory,
+            resolvedSubtitlePrefix,
+            not resolvedSubtitlePrefix,
+        )
+
+    if not resolvedSubtitlePrefix:
+        return False, resolvedSubtitleDirectory, resolvedSubtitlePrefix, False
 
     configuredSubtitlesBaseDirectory = context['config'].getSubtitlesDirectoryPath()
     if not configuredSubtitlesBaseDirectory:
@@ -162,7 +196,85 @@ def resolveSubtitleImportOptions(context, subtitleDirectory, subtitlePrefix):
             + resolvedSubtitleDirectory
         )
 
-    return True, resolvedSubtitleDirectory, resolvedSubtitlePrefix
+    return True, resolvedSubtitleDirectory, resolvedSubtitlePrefix, False
+
+
+def importExternalSubtitles(
+    context,
+    mediaDescriptor,
+    sourceFileBasename,
+    season,
+    episode,
+    preserveDispositions=False,
+):
+    matchSourceBasename = context['subtitle_match_source_basename']
+    subtitlePrefix = (
+        sourceFileBasename
+        if matchSourceBasename
+        else context['subtitle_prefix']
+    )
+
+    try:
+        importResult = mediaDescriptor.importSubtitles(
+            context['subtitle_directory'],
+            subtitlePrefix,
+            season,
+            episode,
+            preserve_dispositions=preserveDispositions,
+            extension=context['subtitle_extension'],
+            strict=matchSourceBasename,
+        )
+    except (OSError, ValueError) as ex:
+        raise click.ClickException(
+            f"External subtitle discovery failed for '{sourceFileBasename}': {ex}"
+        ) from ex
+
+    if not matchSourceBasename:
+        return importResult
+
+    importedTrackIndices = importResult['imported_track_indices']
+    missingTrackIndices = importResult['missing_track_indices']
+    extension = context['subtitle_extension']
+    importedDescription = (
+        ', '.join(f"#{index}" for index in importedTrackIndices)
+        if importedTrackIndices
+        else 'none'
+    )
+    click.echo(
+        f"External subtitle scan for '{sourceFileBasename}': found "
+        + f"{importResult['candidate_count']} .{extension} file(s); "
+        + f"matched subtitle tracks {importedDescription}."
+    )
+
+    if not missingTrackIndices:
+        return importResult
+
+    missingDescription = ', '.join(f"#{index}" for index in missingTrackIndices)
+    incompleteMessage = (
+        f"External subtitle files are missing for subtitle tracks "
+        + f"{missingDescription} in '{sourceFileBasename}'."
+    )
+    if context.get('yes', False):
+        click.echo(
+            incompleteMessage
+            + " Continuing with the matching subtitle files because --yes is set."
+        )
+        return importResult
+
+    if context['no_prompt']:
+        raise click.ClickException(
+            incompleteMessage
+            + " Partial subtitle substitution requires confirmation, but --no-prompt is set."
+        )
+
+    click.echo(incompleteMessage)
+    if not click.confirm(
+        "Continue and substitute only the subtitle tracks with matching files?",
+        default=False,
+    ):
+        raise click.ClickException("External subtitle substitution aborted by user.")
+
+    return importResult
 
 
 def resolveUnmuxOutputDirectory(context, outputDirectory, subtitlesOnly, label):
@@ -173,7 +285,10 @@ def resolveUnmuxOutputDirectory(context, outputDirectory, subtitlesOnly, label):
     )
     resolvedLabel = str(label).strip()
 
-    if resolvedOutputDirectory or not subtitlesOnly or not resolvedLabel:
+    if resolvedOutputDirectory:
+        return resolvedOutputDirectory, True
+
+    if not subtitlesOnly or not resolvedLabel:
         return resolvedOutputDirectory, False
 
     configuredSubtitlesBaseDirectory = context['config'].getSubtitlesDirectoryPath()
@@ -186,6 +301,63 @@ def resolveUnmuxOutputDirectory(context, outputDirectory, subtitlesOnly, label):
     return os.path.join(configuredSubtitlesBaseDirectory, resolvedLabel), True
 
 
+def confirmUnmuxOutputDirectoryCreation(outputDirectory):
+    message = (
+        "Create unmux output directory and missing parents: "
+        + str(outputDirectory)
+    )
+
+    if not sys.stdin.isatty():
+        return click.confirm(message, default=True)
+
+    click.echo(f"{message} [Y/n]: ", nl=False)
+    while True:
+        char = click.getchar()
+        if char in ('\r', '\n'):
+            click.echo()
+            return True
+
+        normalizedChar = char.lower()
+        if normalizedChar == 'y':
+            click.echo(char)
+            return True
+        if normalizedChar == 'n':
+            click.echo(char)
+            return False
+        if char in ('\x03', '\x04'):
+            raise click.Abort()
+
+        click.echo("\nPlease respond with 'y' or 'n': ", nl=False)
+
+
+def ensureUnmuxOutputDirectory(context, outputDirectory):
+    resolvedOutputDirectory = os.path.expanduser(str(outputDirectory).strip())
+    if not resolvedOutputDirectory:
+        return False
+
+    if os.path.isdir(resolvedOutputDirectory):
+        return False
+
+    if os.path.exists(resolvedOutputDirectory):
+        raise click.ClickException(
+            "Unmux output path exists but is not a directory: "
+            + resolvedOutputDirectory
+        )
+
+    if context.get('dry_run', False):
+        return False
+
+    if context.get('yes', False):
+        os.makedirs(resolvedOutputDirectory, exist_ok=True)
+        return True
+
+    if not confirmUnmuxOutputDirectoryCreation(resolvedOutputDirectory):
+        raise click.ClickException("Unmux output directory creation aborted by user.")
+
+    os.makedirs(resolvedOutputDirectory, exist_ok=True)
+    return True
+
+
 def resolveIndicatorDigitLengths(context=None, showDescriptor=None):
     from ffx.show_descriptor import ShowDescriptor
 
@@ -252,9 +424,15 @@ def buildRenameTargetFilename(
 @click.pass_context
 @click.option('--language', 'app_language', type=str, default='', help='Set application language')
 @click.option('--database-file', type=str, default='', help='Path to database file')
+@click.option(
+    '--debug',
+    is_flag=True,
+    default=False,
+    help='Enable debug-only TUI diagnostics such as the log pane',
+)
 @click.option('-v', '--verbose', type=int, default=0, help='Set verbosity of output')
 @click.option("--dry-run", is_flag=True, default=False)
-def ffx(ctx, app_language, database_file, verbose, dry_run):
+def ffx(ctx, app_language, database_file, debug, verbose, dry_run):
     """FFX"""
 
     ctx.obj = {}
@@ -274,6 +452,7 @@ def ffx(ctx, app_language, database_file, verbose, dry_run):
     )
     set_current_language(resolvedLanguage)
     ctx.obj['language'] = resolvedLanguage
+    ctx.obj['debug'] = bool(debug)
 
     if ctx.invoked_subcommand in LIGHTWEIGHT_COMMANDS:
         ctx.obj['dry_run'] = dry_run
@@ -287,6 +466,7 @@ def ffx(ctx, app_language, database_file, verbose, dry_run):
 
     ctx.obj['dry_run'] = dry_run
     ctx.obj['verbosity'] = verbose
+    ctx.obj['debug'] = bool(debug)
     ctx.obj['language'] = resolve_application_language(
         cli_language=app_language,
         config_language=ctx.obj['config'].getLanguage(),
@@ -377,6 +557,41 @@ def getTrackedGitChanges(repoPath):
     return [line for line in completed.stdout.splitlines() if line.strip()]
 
 
+def getCurrentGitBranch(repoPath):
+    completed = subprocess.run(
+        ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+        cwd=repoPath,
+        capture_output=True,
+        text=True,
+    )
+
+    if completed.returncode != 0:
+        commandLabel = 'git rev-parse --abbrev-ref HEAD'
+        errorOutput = completed.stderr.strip() or completed.stdout.strip()
+        raise click.ClickException(
+            f"Unable to inspect bundle repository branch using '{commandLabel}': {errorOutput}"
+        )
+
+    return completed.stdout.strip() or "unknown"
+
+
+def getBundleVersion(repoPath):
+    constantsPath = os.path.join(repoPath, 'src', 'ffx', 'constants.py')
+
+    try:
+        with open(constantsPath, encoding='utf-8') as constantsFile:
+            for line in constantsFile:
+                strippedLine = line.strip()
+                if strippedLine.startswith('VERSION=') or strippedLine.startswith('VERSION ='):
+                    return strippedLine.split('=', 1)[1].strip().strip('"\'')
+    except OSError as ex:
+        raise click.ClickException(
+            f"Unable to inspect bundle version from {constantsPath}: {ex}"
+        ) from ex
+
+    raise click.ClickException(f"Unable to inspect bundle version from {constantsPath}")
+
+
 def runScriptWrapper(ctx, scriptPath, missingDescription, commandArgs):
     if not os.path.isfile(scriptPath):
         raise click.ClickException(f"{missingDescription} not found at {scriptPath}")
@@ -391,6 +606,20 @@ def runScriptWrapper(ctx, scriptPath, missingDescription, commandArgs):
     ctx.exit(completed.returncode)
 
 
+def runTuiApp(ctx) -> None:
+    from ffx.ffx_app import FfxApp
+    from ffx.logging_utils import set_ffx_console_logging_enabled
+
+    logger = ctx.obj.get('logger')
+    set_ffx_console_logging_enabled(logger, enabled=False)
+
+    try:
+        app = FfxApp(ctx.obj)
+        app.run()
+    finally:
+        set_ffx_console_logging_enabled(logger, enabled=True)
+
+
 @ffx.command(name='setup')
 @click.pass_context
 @click.option('--check', is_flag=True, default=False, help='Only verify bundle-setup readiness')
@@ -485,6 +714,10 @@ def upgrade(ctx, branch):
         if completed.returncode != 0:
             ctx.exit(completed.returncode)
 
+    upgradedBranch = getCurrentGitBranch(bundleRepoPath)
+    upgradedVersion = getBundleVersion(bundleRepoPath)
+    click.echo(f"Updated FFX to version {upgradedVersion} from branch {upgradedBranch}.")
+
 
 @ffx.command()
 @click.pass_context
@@ -527,14 +760,11 @@ def inspect(ctx, shift, filenames):
     if len(filenames) != 1:
         raise click.ClickException("Inspect without --shift requires exactly one filename.")
 
-    from ffx.ffx_app import FfxApp
-
     ctx.obj['command'] = 'inspect'
     ctx.obj['arguments'] = {}
     ctx.obj['arguments']['filename'] = filenames[0]
 
-    app = FfxApp(ctx.obj)
+    runTuiApp(ctx)
-    app.run()
 
 
 @ffx.command()
@@ -544,8 +774,6 @@ def edit(ctx, filename):
     if not os.path.isfile(filename):
         raise click.ClickException(f"File not found: {filename}")
 
-    from ffx.ffx_app import FfxApp
-
     ctx.obj['command'] = 'edit'
     ctx.obj['arguments'] = {'filename': filename}
     ctx.obj['use_pattern'] = False
@@ -554,8 +782,7 @@ def edit(ctx, filename):
     ctx.obj['apply_metadata_normalization'] = True
     ctx.obj['resource_limits'] = ctx.obj.get('resource_limits', {})
 
-    app = FfxApp(ctx.obj)
+    runTuiApp(ctx)
-    app.run()
 
 
 @ffx.command()
@@ -615,29 +842,33 @@ def rename(ctx, paths, prefix, season, suffix, dry_run):
 
 
 def getUnmuxSequence(trackDescriptor: TrackDescriptor, sourcePath, targetPrefix, targetDirectory = ''):
+    from ffx.track_codec import TrackCodec
+    from ffx.track_type import TrackType
 
     # executable and input file
     commandTokens = list(FFMPEG_COMMAND_TOKENS) + ['-i', sourcePath]
 
     trackType = trackDescriptor.getType()
+    trackCodec = trackDescriptor.getCodec()
+    trackFormat = trackDescriptor.getFormatDescriptor()
 
     targetPathBase = os.path.join(targetDirectory, targetPrefix) if targetDirectory else targetPrefix
 
     # mapping
-    commandTokens += ['-map',
+    commandTokens += ['-map', f"0:{trackType.indicator()}:{trackDescriptor.getSubIndex()}"]
-            f"0:{trackType.indicator()}:{trackDescriptor.getSubIndex()}",
-            '-c',
-            'copy']
 
-    trackCodec = trackDescriptor.getCodec()
+    if trackType == TrackType.VIDEO and trackCodec == TrackCodec.H265:
+        commandTokens += ['-c:v', 'copy', '-bsf:v', 'hevc_mp4toannexb']
+    else:
+        commandTokens += ['-c', 'copy']
 
     # output format
-    codecFormat = trackCodec.format()
+    codecFormat = trackFormat.format()
     if codecFormat is not None:
         commandTokens += ['-f', codecFormat]
 
     # output filename
-    commandTokens += [f"{targetPathBase}.{trackCodec.extension()}"]
+    commandTokens += [f"{targetPathBase}.{trackFormat.extension()}"]
 
     return commandTokens
 
@@ -649,6 +880,12 @@ def getUnmuxSequence(trackDescriptor: TrackDescriptor, sourcePath, targetPrefix,
 @click.option('-l', '--label', type=str, default='', help='Label to be used as filename prefix')
 @click.option("-o", "--output-directory", type=str, default='', help=UNMUX_OUTPUT_DIRECTORY_OPTION_HELP)
 @click.option("-s", "--subtitles-only", is_flag=True, default=False)
+@click.option(
+    "--yes",
+    is_flag=True,
+    default=False,
+    help="Create a missing unmux output directory without prompting.",
+)
 @click.option(
     '--nice',
     type=int,
@@ -670,6 +907,7 @@ def unmux(ctx,
             label,
             output_directory,
             subtitles_only,
+            yes,
             nice,
             cpu):
     from ffx.file_properties import FileProperties
@@ -685,15 +923,16 @@ def unmux(ctx,
     ctx.obj['resource_limits']['niceness'] = nice
     ctx.obj['resource_limits']['cpu_limit'] = cpu
     ctx.obj['resource_limits']['cpu_percent'] = cpu
+    ctx.obj['yes'] = bool(yes)
 
-    output_directory, create_output_directory = resolveUnmuxOutputDirectory(
+    output_directory, requires_output_directory = resolveUnmuxOutputDirectory(
         ctx.obj,
         output_directory,
         subtitles_only,
         label,
     )
-    if create_output_directory and existingSourcePaths and not ctx.obj.get('dry_run', False):
+    if requires_output_directory and existingSourcePaths:
-        os.makedirs(output_directory, exist_ok=True)
+        ensureUnmuxOutputDirectory(ctx.obj, output_directory)
 
     shiftedSeasonController = ShiftedSeasonController(ctx.obj)
 
@@ -752,7 +991,7 @@ def unmux(ctx,
                         if not ctx.obj['dry_run']:
 
                             #TODO #425: Codec Enum
-                            ctx.obj['logger'].info(f"Unmuxing stream {trackDescriptor.getIndex()} into file {targetPrefix}.{trackDescriptor.getCodec().extension()}")
+                            ctx.obj['logger'].info(f"Unmuxing stream {trackDescriptor.getIndex()} into file {targetPrefix}.{trackDescriptor.getFormatDescriptor().extension()}")
 
                             ctx.obj['logger'].debug(f"Executing unmuxing sequence")
 
@@ -837,12 +1076,8 @@ def cropdetect(ctx,
 @click.pass_context
 
 def shows(ctx):
-    from ffx.ffx_app import FfxApp
-
     ctx.obj['command'] = 'shows'
-
+    runTuiApp(ctx)
-    app = FfxApp(ctx.obj)
-    app.run()
 
 
 def checkUniqueDispositions(context, mediaDescriptor: MediaDescriptor):
@@ -899,6 +1134,8 @@ def checkUniqueDispositions(context, mediaDescriptor: MediaDescriptor):
 @click.option('-l', '--label', type=str, default='', help='Label to be used as filename prefix')
 
 @click.option('-v', '--video-encoder', type=str, default=DEFAULT_VIDEO_ENCODER_LABEL, help=f"Target video encoder (vp9, av1, h264 or copy)", show_default=True)
+@click.option('--copy-video', is_flag=True, default=False, help=COPY_VIDEO_OPTION_HELP)
+@click.option('--copy-audio', is_flag=True, default=False, help=COPY_AUDIO_OPTION_HELP)
 
 @click.option('-q', '--quality', type=str, default="", help=f"Quality settings to be used with VP9/H264 encoder")
 @click.option('-p', '--preset', type=str, default="", help=f"Quality preset to be used with AV1 encoder")
@@ -909,6 +1146,14 @@ def checkUniqueDispositions(context, mediaDescriptor: MediaDescriptor):
 
 @click.option('--subtitle-directory', type=str, default='', help=SUBTITLE_DIRECTORY_OPTION_HELP)
 @click.option('--subtitle-prefix', type=str, default='', help=SUBTITLE_PREFIX_OPTION_HELP)
+@click.option(
+    '--subtitle-extension',
+    type=str,
+    default='vtt',
+    callback=normalizeSubtitleExtension,
+    show_default=True,
+    help=SUBTITLE_EXTENSION_OPTION_HELP,
+)
 
 @click.option('--language', type=str, multiple=True, help='Set stream language. Use format <stream index>:<3 letter iso code>')
 @click.option('--title', type=str, multiple=True, help='Set stream title. Use format <stream index>:<title>')
@@ -943,7 +1188,6 @@ def checkUniqueDispositions(context, mediaDescriptor: MediaDescriptor):
     metavar="DURATION|START,DURATION",
     is_flag=False,
     flag_value=DEFAULT_CUT_OPTION_VALUE,
-    default=None,
     callback=normalizeCutOption,
     help=CUT_OPTION_HELP,
 )
@@ -970,6 +1214,12 @@ def checkUniqueDispositions(context, mediaDescriptor: MediaDescriptor):
 @click.option("--dont-pass-dispositions", is_flag=True, default=False)
 
 @click.option("--no-prompt", is_flag=True, default=False)
+@click.option(
+    "--yes",
+    is_flag=True,
+    default=False,
+    help="Confirm partial external subtitle substitution without prompting.",
+)
 @click.option("--no-signature", is_flag=True, default=False)
 @click.option("--keep-mkvmerge-metadata", is_flag=True, default=False)
 
@@ -996,6 +1246,8 @@ def convert(ctx,
             paths,
             label,
             video_encoder,
+            copy_video,
+            copy_audio,
             quality,
             preset,
             stereo_bitrate,
@@ -1004,6 +1256,7 @@ def convert(ctx,
 
             subtitle_directory,
             subtitle_prefix,
+            subtitle_extension,
 
             language,
             title,
@@ -1042,6 +1295,7 @@ def convert(ctx,
             no_pattern,
             dont_pass_dispositions,
             no_prompt,
+            yes,
             no_signature,
             keep_mkvmerge_metadata,
             
@@ -1055,6 +1309,11 @@ def convert(ctx,
     Suffices will we appended to filename in case of multiple created files
     or if the filename has not changed."""
     from ffx.ffx_controller import FfxController
+    from ffx.diagnostics import (
+        FfmpegSkipFileWarning,
+        getUnremediedIssues,
+        iterUnremediedIssueSummaryLines,
+    )
     from ffx.file_properties import FileProperties
     from ffx.filter.crop_filter import CropFilter
     from ffx.filter.deinterlace_filter import DeinterlaceFilter
@@ -1068,6 +1327,7 @@ def convert(ctx,
     from ffx.tmdb_controller import TmdbController
     from ffx.track_codec import TrackCodec
     from ffx.track_disposition import TrackDisposition
+    from ffx.track_type import TrackType
     from ffx.video_encoder import VideoEncoder
 
     startTime = time.perf_counter()
@@ -1075,9 +1335,12 @@ def convert(ctx,
     context = ctx.obj
     
     context['video_encoder'] = VideoEncoder.fromLabel(video_encoder)
+    context['copy_video'] = copy_video
+    context['copy_audio'] = copy_audio
+    copyVideoEffective = copy_video or context['video_encoder'] == VideoEncoder.COPY
 
     # HINT: quick and dirty override for h264, todo improve
-    if context['video_encoder'] in (VideoEncoder.H264, VideoEncoder.COPY):
+    if context['video_encoder'] in (VideoEncoder.H264, VideoEncoder.COPY) or copy_video or copy_audio:
         targetFormat = ''
         targetExtension = 'mkv'
     else:
@@ -1087,6 +1350,7 @@ def convert(ctx,
     context['use_tmdb'] = not no_tmdb
     context['use_pattern'] = not no_pattern
     context['no_prompt'] = no_prompt
+    context['yes'] = yes
     context['no_signature'] = no_signature
     context['keep_mkvmerge_metadata'] = keep_mkvmerge_metadata
 
@@ -1105,6 +1369,7 @@ def convert(ctx,
         context['import_subtitles'],
         resolvedSubtitleDirectory,
         resolvedSubtitlePrefix,
+        context['subtitle_match_source_basename'],
     ) = resolveSubtitleImportOptions(
         context,
         subtitle_directory,
@@ -1113,6 +1378,7 @@ def convert(ctx,
     if context['import_subtitles']:
         context['subtitle_directory'] = resolvedSubtitleDirectory
         context['subtitle_prefix'] = resolvedSubtitlePrefix
+        context['subtitle_extension'] = subtitle_extension
 
 
     existingSourcePaths = [p for p in paths if os.path.isfile(p) and p.split('.')[-1] in SUPPORTED_INPUT_FILE_EXTENSIONS]
@@ -1210,36 +1476,54 @@ def convert(ctx,
     tc = TmdbController() if context['use_tmdb'] else None
 
 
-    qualityKwargs = {QualityFilter.QUALITY_KEY: str(quality)}
+    if copyVideoEffective and quality:
+        ctx.obj['logger'].warning("Ignoring quality settings because video is being copied")
+
+    qualityKwargs = {
+        QualityFilter.QUALITY_KEY: "" if copyVideoEffective else str(quality)
+    }
     qf = QualityFilter(**qualityKwargs)
 
 
 
-    if context['video_encoder'] == VideoEncoder.AV1 and preset:
+    if context['video_encoder'] == VideoEncoder.AV1 and preset and not copyVideoEffective:
         presetKwargs = {PresetFilter.PRESET_KEY: preset}
         PresetFilter(**presetKwargs)
 
     cf = None
     # if crop != 'none':
-    if crop == 'auto':
+    videoFilterOptionsRequested = (
+        crop != 'none'
+        or deinterlace != 'none'
+        or denoise != 'none'
+        or denoise_strength
+        or denoise_patch_size
+        or denoise_chroma_patch_size
+        or denoise_research_window
+        or denoise_chroma_research_window
+    )
+    if copyVideoEffective and videoFilterOptionsRequested:
+        ctx.obj['logger'].warning("Ignoring video filter options because video is being copied")
+
+    if crop == 'auto' and not copyVideoEffective:
         cropKwargs = {}
         cf = CropFilter(**cropKwargs)
 
     denoiseKwargs = {}
-    if denoise_strength:
+    if denoise_strength and not copyVideoEffective:
         denoiseKwargs[NlmeansFilter.STRENGTH_KEY] = denoise_strength
-    if denoise_patch_size:
+    if denoise_patch_size and not copyVideoEffective:
         denoiseKwargs[NlmeansFilter.PATCH_SIZE_KEY] = denoise_patch_size
-    if denoise_chroma_patch_size:
+    if denoise_chroma_patch_size and not copyVideoEffective:
         denoiseKwargs[NlmeansFilter.CHROMA_PATCH_SIZE_KEY] = denoise_chroma_patch_size
-    if denoise_research_window:
+    if denoise_research_window and not copyVideoEffective:
         denoiseKwargs[NlmeansFilter.RESEARCH_WINDOW_KEY] = denoise_research_window
-    if denoise_chroma_research_window:
+    if denoise_chroma_research_window and not copyVideoEffective:
         denoiseKwargs[NlmeansFilter.CHROMA_RESEARCH_WINDOW_KEY] = denoise_chroma_research_window
-    if denoise != 'none' or denoiseKwargs:
+    if not copyVideoEffective and (denoise != 'none' or denoiseKwargs):
         NlmeansFilter(**denoiseKwargs)
 
-    if deinterlace != 'none':
+    if deinterlace != 'none' and not copyVideoEffective:
         DeinterlaceFilter()
 
     chainYield = list(qf.getChainYield())
@@ -1299,13 +1583,31 @@ def convert(ctx,
         sourceMediaDescriptor = mediaFileProperties.getMediaDescriptor()
 
 
-        if ([smd for smd in sourceMediaDescriptor.getSubtitleTracks()
+        from ffx.attachment_format import AttachmentFormat
-                    if smd.getCodec() == TrackCodec.ASS]
-                and [amd for amd in sourceMediaDescriptor.getAttachmentTracks()
-                    if amd.getCodec() == TrackCodec.TTF]):
 
+        styledAssDetector = getattr(
+            sourceMediaDescriptor,
+            "hasStyledAssSubtitlesWithFontAttachments",
+            None,
+        )
+        styledAssSourceDetected = (
+            bool(styledAssDetector())
+            if callable(styledAssDetector)
+            else False
+        )
+        if styledAssSourceDetected:
+            styledAssMessage = (
+                "Styled ASS subtitles with embedded font attachments detected; "
+                + "preserving source font attachments."
+            )
+            click.echo(styledAssMessage)
             targetFormat = ''
             targetExtension = 'mkv'
+            if context['import_subtitles']:
+                raise click.ClickException(
+                    "External subtitle import is incompatible with styled ASS "
+                    + "sources that carry embedded font attachments."
+                )
 
 
         #HINT: This is None if the filename did not match anything in database
@@ -1320,10 +1622,13 @@ def convert(ctx,
             currentShowDescriptor = None
 
             if context['import_subtitles']:
-                sourceMediaDescriptor.importSubtitles(context['subtitle_directory'],
+                importExternalSubtitles(
-                                                        context['subtitle_prefix'],
+                    context,
+                    sourceMediaDescriptor,
+                    sourceFileBasename,
                     showSeason,
-                                                        showEpisode)
+                    showEpisode,
+                )
 
             if cliOverrides:
                 sourceMediaDescriptor.applyOverrides(cliOverrides)
@@ -1332,6 +1637,12 @@ def convert(ctx,
 
         else:
             targetMediaDescriptor = currentPattern.getMediaDescriptor(ctx.obj)
+            if styledAssSourceDetected:
+                targetMediaDescriptor = targetMediaDescriptor.withSourceAttachmentTracks(
+                    sourceMediaDescriptor,
+                    AttachmentFormat.TTF,
+                    context=ctx.obj,
+                )
             checkUniqueDispositions(context, targetMediaDescriptor)
             currentShowDescriptor = currentPattern.getShowDescriptor(ctx.obj)
 
@@ -1341,6 +1652,8 @@ def convert(ctx,
             targetTrackDescriptorList = targetMediaDescriptor.getTrackDescriptors()
 
             for ttd in targetTrackDescriptorList:
+                if ttd.getType() == TrackType.ATTACHMENT:
+                    continue
 
                 tti = ttd.getIndex()
                 ttsi = ttd.getSourceIndex()
@@ -1359,11 +1672,14 @@ def convert(ctx,
 
 
             if context['import_subtitles']:
-                targetMediaDescriptor.importSubtitles(context['subtitle_directory'],
+                importExternalSubtitles(
-                                                        context['subtitle_prefix'],
+                    context,
+                    targetMediaDescriptor,
+                    sourceFileBasename,
                     showSeason,
                     showEpisode,
-                                                        preserve_dispositions=True)
+                    preserveDispositions=True,
+                )
 
             # ctx.obj['logger'].debug(f"tmd subindices: {[t.getIndex() for t in targetMediaDescriptor.getAllTrackDescriptors()]} {[t.getSubIndex() for t in targetMediaDescriptor.getAllTrackDescriptors()]}  {[t.getDispositionFlag(TrackDisposition.DEFAULT) for t in targetMediaDescriptor.getAllTrackDescriptors()]}")
             ctx.obj['logger'].debug(f"tmd subindices: {[t.getIndex() for t in targetMediaDescriptor.getTrackDescriptors()]} {[t.getSubIndex() for t in targetMediaDescriptor.getTrackDescriptors()]}  {[t.getDispositionFlag(TrackDisposition.DEFAULT) for t in targetMediaDescriptor.getTrackDescriptors()]}")
@@ -1511,6 +1827,7 @@ def convert(ctx,
             if rename_only:
                 shutil.move(sourcePath, targetPath)
             else:
+                try:
                     fc.runJob(sourcePath,
                                 targetPath,
                                 targetFormat,
@@ -1518,11 +1835,22 @@ def convert(ctx,
                                 cropArguments,
                                 currentPattern,
                                 currentShowDescriptor)
+                except FfmpegSkipFileWarning:
+                    if os.path.exists(targetPath):
+                        os.remove(targetPath)
+                    continue
 
 
 
     endTime = time.perf_counter()
     ctx.obj['logger'].info(f"\nDONE\nTime elapsed {endTime - startTime}")
+    unremediedIssues = getUnremediedIssues(context)
+    if unremediedIssues:
+        ctx.obj['logger'].warning("\nFiles with ffmpeg findings that require review:")
+        for summaryLine in iterUnremediedIssueSummaryLines(context):
+            ctx.obj['logger'].warning(summaryLine)
+    else:
+        ctx.obj['logger'].info("All files converted with no issues.")
 
 
 if __name__ == '__main__':

src/ffx/confirm_screen.py

@@ -62,6 +62,13 @@ class ConfirmScreen(Screen):
         yield build_screen_log_pane()
         yield Footer()
 
+
+    def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
+
     def on_button_pressed(self, event: Button.Pressed) -> None:
         if event.button.id == "confirm_button":
             self.dismiss(True)

src/ffx/constants.py

@@ -1,4 +1,4 @@
-VERSION='0.3.0'
+VERSION='0.4.4'
 DATABASE_VERSION = 3
 
 DEFAULT_QUALITY = 32

src/ffx/diagnostics/__init__.py

@@ -0,0 +1,24 @@
+from .base import FfmpegRemedy, FfmpegRemedyDecision, FfmpegSkipFileWarning
+from .monitor import FfmpegCommandRunner, FfmpegDiagnosticMonitor
+from .retry_with_generated_pts import RetryWithGeneratedPtsRemedy
+from .state import (
+    getDiagnosticsState,
+    getUnremediedIssues,
+    iterUnremediedIssueSummaryLines,
+    recordUnremediedIssue,
+)
+from .warn_corrupt_mpeg_audio import WarnCorruptMpegAudioRemedy
+
+__all__ = [
+    "FfmpegCommandRunner",
+    "FfmpegDiagnosticMonitor",
+    "FfmpegRemedy",
+    "FfmpegRemedyDecision",
+    "FfmpegSkipFileWarning",
+    "RetryWithGeneratedPtsRemedy",
+    "WarnCorruptMpegAudioRemedy",
+    "getDiagnosticsState",
+    "getUnremediedIssues",
+    "iterUnremediedIssueSummaryLines",
+    "recordUnremediedIssue",
+]

src/ffx/diagnostics/base.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class FfmpegSkipFileWarning(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class FfmpegRemedyDecision:
+    stop_process: bool = False
+    retry_input_tokens: tuple[str, ...] = ()
+    skip_file: bool = False
+    console_warning: str = ""
+    summary_identifier: str = ""
+    unremedied_issue_identifier: str = ""
+
+    @property
+    def retry_requested(self) -> bool:
+        return bool(self.retry_input_tokens)
+
+
+class FfmpegRemedy:
+    identifier = "ffmpeg-remedy"
+    harmless = False
+
+    def inspect_line(
+        self,
+        line: str,
+        session: "FfmpegDiagnosticMonitor",
+    ) -> FfmpegRemedyDecision | None:
+        raise NotImplementedError

src/ffx/diagnostics/monitor.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import re
+
+from ffx.logging_utils import get_ffx_logger
+from ffx.process import executeProcess
+
+from .base import FfmpegSkipFileWarning, FfmpegRemedy
+from .retry_with_generated_pts import RetryWithGeneratedPtsRemedy
+from .state import recordUnremediedIssue
+from .warn_corrupt_mpeg_audio import WarnCorruptMpegAudioRemedy
+
+UNHANDLED_DIAGNOSTIC_PATTERNS = (
+    re.compile(r"\bwarning\b", re.IGNORECASE),
+    re.compile(r"\berror\b", re.IGNORECASE),
+    re.compile(r"\bfailed\b", re.IGNORECASE),
+    re.compile(r"\binvalid\b", re.IGNORECASE),
+    re.compile(r"\bmissing\b", re.IGNORECASE),
+    re.compile(r"\bcorrupt\b", re.IGNORECASE),
+    re.compile(r"\boverflow\b", re.IGNORECASE),
+    re.compile(r"\bdeprecated\b", re.IGNORECASE),
+)
+
+
+class FfmpegDiagnosticMonitor:
+    def __init__(
+        self,
+        context: dict | None,
+        command_sequence: list[str],
+        *,
+        remedies: list[FfmpegRemedy] | None = None,
+        emittedWarnings: set[str] | None = None,
+    ):
+        self.context = context or {}
+        self.command_sequence = list(command_sequence)
+        self.logger = self.context.get("logger", get_ffx_logger())
+        self.source_path = str(self.context.get("current_source_path", "")).strip()
+        self.remedies = remedies or [
+            RetryWithGeneratedPtsRemedy(),
+            WarnCorruptMpegAudioRemedy(),
+        ]
+        self._emittedWarnings = emittedWarnings if emittedWarnings is not None else set()
+        self.retry_input_tokens: tuple[str, ...] = ()
+        self.skip_file = False
+        self.skip_file_message = ""
+
+    def describe_source(self) -> str:
+        return self.source_path if self.source_path else "current file"
+
+    def command_contains_tokens(self, tokens: tuple[str, ...]) -> bool:
+        tokenCount = len(tokens)
+        if tokenCount == 0:
+            return True
+
+        return any(
+            tuple(self.command_sequence[index:index + tokenCount]) == tuple(tokens)
+            for index in range(len(self.command_sequence) - tokenCount + 1)
+        )
+
+    def emitConsoleWarning(self, warningMessage: str) -> None:
+        if warningMessage and warningMessage not in self._emittedWarnings:
+            self.logger.warning(warningMessage)
+            self._emittedWarnings.add(warningMessage)
+
+    def recordUnremediedIssue(self, issueIdentifier: str, issueLine: str) -> None:
+        isFirstIssueForFile = recordUnremediedIssue(
+            self.context,
+            self.describe_source(),
+            issueIdentifier,
+        )
+        if not isFirstIssueForFile:
+            return
+
+        self.emitConsoleWarning(
+            f"ffmpeg reported a diagnostic with no automatic remedy while converting "
+            + f"{self.describe_source()}. FFX will continue, but review the output "
+            + f"file. First unhandled line: {issueLine}"
+        )
+
+    def lineLooksLikeUnhandledDiagnostic(self, line: str) -> bool:
+        return any(pattern.search(line) for pattern in UNHANDLED_DIAGNOSTIC_PATTERNS)
+
+    def getUnhandledDiagnosticIdentifier(self, line: str) -> str:
+        loweredLine = str(line).lower()
+
+        if any(token in loweredLine for token in ("error", "failed", "invalid", "missing", "corrupt", "overflow")):
+            return "unhandled-error"
+        if any(token in loweredLine for token in ("warning", "deprecated")):
+            return "unhandled-warning"
+        return "unhandled-diagnostic"
+
+    def getSummaryIdentifier(
+        self,
+        remedy: FfmpegRemedy,
+        decision,
+    ) -> str:
+        explicitIdentifier = str(decision.summary_identifier).strip()
+        if explicitIdentifier:
+            return explicitIdentifier
+
+        remedyIdentifier = str(getattr(remedy, "identifier", "")).strip()
+        if remedyIdentifier and remedyIdentifier != FfmpegRemedy.identifier:
+            return remedyIdentifier
+
+        return str(decision.unremedied_issue_identifier).strip()
+
+    def shouldRecordSummary(
+        self,
+        remedy: FfmpegRemedy,
+        decision,
+    ) -> bool:
+        if getattr(remedy, "harmless", False):
+            return False
+
+        if decision.retry_requested and not decision.skip_file:
+            return False
+
+        return bool(self.getSummaryIdentifier(remedy, decision))
+
+    def handle_stderr_line(self, line: str) -> bool:
+        strippedLine = str(line).strip()
+        if not strippedLine:
+            return False
+
+        for remedy in self.remedies:
+            decision = remedy.inspect_line(strippedLine, self)
+            if decision is None:
+                continue
+
+            self.emitConsoleWarning(decision.console_warning)
+
+            if decision.retry_requested:
+                self.retry_input_tokens = tuple(decision.retry_input_tokens)
+
+            if self.shouldRecordSummary(remedy, decision):
+                recordUnremediedIssue(
+                    self.context,
+                    self.describe_source(),
+                    self.getSummaryIdentifier(remedy, decision),
+                )
+
+            if decision.skip_file:
+                self.skip_file = True
+                self.skip_file_message = (
+                    decision.console_warning
+                    or f"Skipping file {self.describe_source()} because ffmpeg reported a fatal diagnostic."
+                )
+
+            return bool(decision.stop_process)
+
+        if self.lineLooksLikeUnhandledDiagnostic(strippedLine):
+            self.recordUnremediedIssue(
+                self.getUnhandledDiagnosticIdentifier(strippedLine),
+                strippedLine,
+            )
+
+        return False
+
+    @property
+    def retry_requested(self) -> bool:
+        return bool(self.retry_input_tokens)
+
+
+def insertFfmpegInputOptions(
+    commandSequence: list[str],
+    extraTokens: tuple[str, ...],
+) -> list[str]:
+    if not extraTokens:
+        return list(commandSequence)
+
+    if not commandSequence:
+        return list(extraTokens)
+
+    return [commandSequence[0]] + list(extraTokens) + list(commandSequence[1:])
+
+
+class FfmpegCommandRunner:
+    def __init__(
+        self,
+        context: dict | None,
+        *,
+        remedies: list[FfmpegRemedy] | None = None,
+    ):
+        self.__context = context or {}
+        self.__remedies = remedies
+
+    def execute(
+        self,
+        commandSequence: list[str],
+        *,
+        directory: str = None,
+        timeoutSeconds: float = None,
+    ):
+        emittedWarnings: set[str] = set()
+        attemptCommandSequence = list(commandSequence)
+
+        while True:
+            monitor = FfmpegDiagnosticMonitor(
+                self.__context,
+                attemptCommandSequence,
+                remedies=self.__remedies,
+                emittedWarnings=emittedWarnings,
+            )
+            out, err, rc = executeProcess(
+                attemptCommandSequence,
+                directory=directory,
+                context=self.__context,
+                timeoutSeconds=timeoutSeconds,
+                stderrLineHandler=monitor.handle_stderr_line,
+            )
+
+            if monitor.retry_requested:
+                attemptCommandSequence = insertFfmpegInputOptions(
+                    attemptCommandSequence,
+                    monitor.retry_input_tokens,
+                )
+                continue
+
+            if monitor.skip_file:
+                raise FfmpegSkipFileWarning(monitor.skip_file_message)
+
+            return out, err, rc

src/ffx/diagnostics/retry_with_generated_pts.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+
+from .base import FfmpegRemedy, FfmpegRemedyDecision
+
+
+class RetryWithGeneratedPtsRemedy(FfmpegRemedy):
+    identifier = "retry-with-generated-pts"
+    RETRY_INPUT_TOKENS = ("-fflags", "+genpts")
+    TIMESTAMP_UNSET_PATTERN = re.compile(
+        r"Timestamps are unset in a packet for stream \d+"
+    )
+
+    def inspect_line(
+        self,
+        line: str,
+        session: "FfmpegDiagnosticMonitor",
+    ) -> FfmpegRemedyDecision | None:
+        if self.TIMESTAMP_UNSET_PATTERN.search(line) is None:
+            return None
+
+        if session.command_contains_tokens(self.RETRY_INPUT_TOKENS):
+            return FfmpegRemedyDecision(
+                stop_process=True,
+                skip_file=True,
+                console_warning=(
+                    f"Skipping file {session.describe_source()}: ffmpeg still reported "
+                    + "unset packet timestamps after retry with -fflags +genpts."
+                ),
+                unremedied_issue_identifier="timestamp-unset-after-genpts",
+            )
+
+        return FfmpegRemedyDecision(
+            stop_process=True,
+            retry_input_tokens=self.RETRY_INPUT_TOKENS,
+            console_warning=(
+                f"ffmpeg reported unset packet timestamps for {session.describe_source()}. "
+                + "Stopping early and retrying with -fflags +genpts."
+            ),
+        )

src/ffx/diagnostics/state.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+
+
+DIAGNOSTICS_STATE_KEY = "diagnostics_state"
+UNREMEDIED_ISSUES_KEY = "unremedied_issues"
+
+
+def getDiagnosticsState(context: dict | None) -> dict:
+    if context is None:
+        return {UNREMEDIED_ISSUES_KEY: {}}
+
+    if DIAGNOSTICS_STATE_KEY not in context:
+        context[DIAGNOSTICS_STATE_KEY] = {
+            UNREMEDIED_ISSUES_KEY: {},
+        }
+
+    return context[DIAGNOSTICS_STATE_KEY]
+
+
+def recordUnremediedIssue(
+    context: dict | None,
+    sourcePath: str,
+    identifier: str,
+) -> bool:
+    if not sourcePath:
+        return False
+
+    diagnosticsState = getDiagnosticsState(context)
+    unremediedIssues = diagnosticsState[UNREMEDIED_ISSUES_KEY]
+    issueList = unremediedIssues.setdefault(sourcePath, [])
+    strippedIdentifier = str(identifier).strip()
+
+    if not strippedIdentifier or strippedIdentifier in issueList:
+        return False
+
+    issueList.append(strippedIdentifier)
+    return True
+
+
+def getUnremediedIssues(context: dict | None) -> dict[str, list[str]]:
+    diagnosticsState = getDiagnosticsState(context)
+    return diagnosticsState.get(UNREMEDIED_ISSUES_KEY, {})
+
+
+def iterUnremediedIssueSummaryLines(context: dict | None) -> list[str]:
+    summaryLines = []
+    unremediedIssues = getUnremediedIssues(context)
+    for sourcePath in sorted(unremediedIssues.keys()):
+        identifiers = unremediedIssues[sourcePath]
+        summaryLines.append(f"{os.path.basename(sourcePath)}: {', '.join(identifiers)}")
+    return summaryLines

src/ffx/diagnostics/warn_corrupt_mpeg_audio.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import re
+
+from .base import FfmpegRemedy, FfmpegRemedyDecision
+
+
+class WarnCorruptMpegAudioRemedy(FfmpegRemedy):
+    identifier = "warn-corrupt-mpeg-audio"
+    PATTERNS = (
+        re.compile(r"\[mp3float @ .*\] invalid block type", re.IGNORECASE),
+        re.compile(r"\[mp3float @ .*\] invalid new backstep -?\d+", re.IGNORECASE),
+        re.compile(r"\[mp3float @ .*\] Header missing"),
+        re.compile(r"\[mp3float @ .*\] overread, skip ", re.IGNORECASE),
+        re.compile(r"Error while decoding MPEG audio frame\."),
+        re.compile(
+            r"Error submitting packet to decoder: Invalid data found when processing input"
+        ),
+    )
+
+    def inspect_line(
+        self,
+        line: str,
+        session: "FfmpegDiagnosticMonitor",
+    ) -> FfmpegRemedyDecision | None:
+        if not any(pattern.search(line) for pattern in self.PATTERNS):
+            return None
+
+        return FfmpegRemedyDecision(
+            console_warning=(
+                f"ffmpeg reported damaged MPEG audio frames while converting "
+                + f"{session.describe_source()}. FFX will continue, but the output "
+                + "audio may contain gaps or glitches."
+            ),
+        )

src/ffx/ffmpeg_diagnostics.py

@@ -0,0 +1,27 @@
+from .diagnostics import (
+    FfmpegCommandRunner,
+    FfmpegDiagnosticMonitor,
+    FfmpegRemedy,
+    FfmpegRemedyDecision,
+    FfmpegSkipFileWarning,
+    RetryWithGeneratedPtsRemedy,
+    WarnCorruptMpegAudioRemedy,
+    getDiagnosticsState,
+    getUnremediedIssues,
+    iterUnremediedIssueSummaryLines,
+    recordUnremediedIssue,
+)
+
+__all__ = [
+    "FfmpegCommandRunner",
+    "FfmpegDiagnosticMonitor",
+    "FfmpegRemedy",
+    "FfmpegRemedyDecision",
+    "FfmpegSkipFileWarning",
+    "RetryWithGeneratedPtsRemedy",
+    "WarnCorruptMpegAudioRemedy",
+    "getDiagnosticsState",
+    "getUnremediedIssues",
+    "iterUnremediedIssueSummaryLines",
+    "recordUnremediedIssue",
+]

src/ffx/ffx_app.py

@@ -4,7 +4,7 @@ from .i18n import set_current_language, t
 from .shows_screen import ShowsScreen
 from .inspect_details_screen import InspectDetailsScreen
 from .media_edit_screen import MediaEditScreen
-from .screen_support import toggle_screen_log_pane
+from .screen_support import configure_screen_log_handler, set_screen_log_pane_enabled
 
 
 class FfxApp(App):
@@ -14,7 +14,6 @@ class FfxApp(App):
     BINDINGS = [
         ("q", "quit()", t("Quit")),
         ("h", "switch_mode('help')", t("Help")),
-        ("l", "toggle_log_pane", t("Log")),
     ]
 
 
@@ -24,6 +23,13 @@ class FfxApp(App):
         # Data 'input' variable
         self.context = context
         set_current_language(self.context.get("language"))
+        debug_mode = bool(self.context.get("debug", False))
+        set_screen_log_pane_enabled(debug_mode)
+        configure_screen_log_handler(
+            self.context.get("logger"),
+            self,
+            enabled=debug_mode,
+        )
 
 
     def on_mount(self) -> None:
@@ -43,6 +49,3 @@ class FfxApp(App):
     def getContext(self):
         """Data 'output' method"""
         return self.context
-
-    def action_toggle_log_pane(self) -> None:
-        toggle_screen_log_pane(self.screen)

src/ffx/ffx_controller.py

@@ -1,7 +1,9 @@
-import os, click
+import os, click, subprocess
+from functools import lru_cache
 from logging import Logger
 
 from ffx.media_descriptor_change_set import MediaDescriptorChangeSet
+from ffx.diagnostics import FfmpegCommandRunner
 
 from ffx.media_descriptor import MediaDescriptor
 from ffx.audio_layout import AudioLayout
@@ -61,9 +63,51 @@ class FfxController():
                                                 sourceMediaDescriptor)
 
         self.__logger: Logger = context['logger']
+        self.__warnedH264Fallback = False
+        self.__ffmpegCommandRunner = FfmpegCommandRunner(context)
+
+
+    @staticmethod
+    @lru_cache(maxsize=None)
+    def isFfmpegEncoderAvailable(encoderName: str) -> bool:
+        completed = subprocess.run(
+            ["ffmpeg", "-encoders"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if completed.returncode != 0:
+            return False
+
+        resolvedEncoderName = str(encoderName).strip()
+
+        for line in completed.stdout.splitlines():
+            if not line.startswith(" "):
+                continue
+
+            tokens = line.split(maxsplit=2)
+            if len(tokens) >= 2 and tokens[1] == resolvedEncoderName:
+                return True
+
+        return False
+
+
+    @classmethod
+    def getSupportedSoftwareH264Encoder(cls) -> str | None:
+        if cls.isFfmpegEncoderAvailable("libx264"):
+            return "libx264"
+        if cls.isFfmpegEncoderAvailable("libopenh264"):
+            return "libopenh264"
+        return None
 
 
     def executeCommandSequence(self, commandSequence):
+        if commandSequence and str(commandSequence[0]).strip() == "ffmpeg":
+            out, err, rc = self.__ffmpegCommandRunner.execute(
+                commandSequence,
+                timeoutSeconds=None,
+            )
+        else:
             out, err, rc = executeProcess(commandSequence, context=self.__context)
         if rc:
             raise click.ClickException(f"Command resulted in error: rc={rc} error={err}")
@@ -79,11 +123,28 @@ class FfxController():
 
     # -c:v libx264 -preset slow -crf 17
     def generateH264Tokens(self, quality, subIndex : int = 0):
+        h264Encoder = self.getSupportedSoftwareH264Encoder()
 
+        if h264Encoder == "libx264":
             return [f"-c:v:{int(subIndex)}", 'libx264',
                     "-preset", "slow",
                     '-crf', str(quality)]
 
+        if h264Encoder == "libopenh264":
+            if not self.__warnedH264Fallback:
+                self.__logger.warning(
+                    "libx264 encoder unavailable; falling back to libopenh264 for H.264 encoding."
+                )
+                self.__warnedH264Fallback = True
+
+            return [f"-c:v:{int(subIndex)}", 'libopenh264',
+                    '-pix_fmt', 'yuv420p']
+
+        raise click.ClickException(
+            "H.264 encoding requested but no supported software H.264 encoder is available. "
+            + "Tried libx264 and libopenh264."
+        )
+
 
     # -c:v:0 libvpx-vp9 -row-mt 1 -crf 32 -pass 1 -speed 4 -frame-parallel 0 -g 9999 -aq-mode 0
     def generateVP9Pass1Tokens(self, quality, subIndex : int = 0):
@@ -119,6 +180,16 @@ class FfxController():
     def generateAudioCopyTokens(self, subIndex):
         return [f"-c:a:{int(subIndex)}", 'copy']
 
+    def generateVideoCopyAllTokens(self):
+        if self.__targetMediaDescriptor.getTrackDescriptors(trackType=TrackType.VIDEO):
+            return ["-c:v", "copy"]
+        return []
+
+    def generateAudioCopyAllTokens(self):
+        if self.__targetMediaDescriptor.getTrackDescriptors(trackType=TrackType.AUDIO):
+            return ["-c:a", "copy"]
+        return []
+
     def generateSubtitleCopyTokens(self, subIndex):
         return [f"-c:s:{int(subIndex)}", 'copy']
 
@@ -239,6 +310,12 @@ class FfxController():
         return audioTokens
 
 
+    def generateAudioProcessingTokens(self):
+        if self.__context.get('copy_audio', False):
+            return self.generateAudioCopyAllTokens()
+        return self.generateAudioEncodingTokens()
+
+
     def runJob(self,
                 sourcePath,
                 targetPath,
@@ -252,6 +329,8 @@ class FfxController():
 
 
         videoEncoder: VideoEncoder = self.__context.get('video_encoder', VideoEncoder.VP9)
+        self.__context['current_source_path'] = sourcePath
+        copyVideo = self.__context.get('copy_video', False) or videoEncoder == VideoEncoder.COPY
 
 
         qualityFilters = [fy for fy in chainIteration if fy['identifier'] == 'quality']
@@ -262,6 +341,10 @@ class FfxController():
         deinterlaceFilters = [fy for fy in chainIteration if fy['identifier'] == 'bwdif']
 
 
+        if copyVideo:
+            quality = None
+            self.__context['encoding_metadata_tags'] = {}
+        else:
             if qualityFilters and (quality := qualityFilters[0]['parameters']['quality']):
                 self.__logger.info(f"Setting quality {quality} from command line")
             elif currentPattern is not None and (quality := currentPattern.quality):
@@ -276,6 +359,7 @@ class FfxController():
 
 
         preset = presetFilters[0]['parameters']['preset'] if presetFilters else PresetFilter.DEFAULT_PRESET
+        if not copyVideo:
             self.__context['encoding_metadata_tags'] = self.generateEncodingMetadataTags(
                 videoEncoder,
                 quality,
@@ -285,7 +369,7 @@ class FfxController():
 
         filterParamTokens = []
         
-        if cropArguments:
+        if cropArguments and not copyVideo:
 
             cropParams = (f"crop="
                             + f"{cropArguments[CropFilter.OUTPUT_WIDTH_KEY]}"
@@ -295,6 +379,7 @@ class FfxController():
     
             filterParamTokens.append(cropParams)
 
+        if not copyVideo:
             filterParamTokens.extend(denoiseFilters[0]['tokens'] if denoiseFilters else [])
             filterParamTokens.extend(deinterlaceFilters[0]['tokens'] if deinterlaceFilters else [])
 
@@ -327,6 +412,29 @@ class FfxController():
                 self.executeCommandSequence(commandSequence)
             return
 
+        if copyVideo:
+
+            commandSequence = (commandTokens
+                                + self.__targetMediaDescriptor.getImportFileTokens()
+                                + self.__targetMediaDescriptor.getInputMappingTokens(sourceMediaDescriptor = self.__sourceMediaDescriptor)
+                                + self.__mdcs.generateDispositionTokens())
+
+            commandSequence += self.__mdcs.generateMetadataTokens()
+            commandSequence += self.generateVideoCopyAllTokens()
+            commandSequence += self.generateAudioProcessingTokens()
+
+            if self.__context['perform_cut']:
+                commandSequence += self.generateCropTokens()
+
+            commandSequence += self.generateOutputTokens(targetPath,
+                                                        targetFormat)
+
+            self.__logger.debug("FfxController.runJob(): Running command sequence")
+
+            if not self.__context['dry_run']:
+                self.executeCommandSequence(commandSequence)
+            return
+
         if videoEncoder == VideoEncoder.AV1:
 
             commandSequence = (commandTokens
@@ -343,7 +451,7 @@ class FfxController():
                 if td.getCodec != TrackCodec.PNG:
                     commandSequence += self.generateAV1Tokens(int(quality), int(preset))
 
-            commandSequence += self.generateAudioEncodingTokens()
+            commandSequence += self.generateAudioProcessingTokens()
 
             if self.__context['perform_cut']:
                 commandSequence += self.generateCropTokens()
@@ -373,7 +481,7 @@ class FfxController():
                 if td.getCodec != TrackCodec.PNG:
                     commandSequence += self.generateH264Tokens(int(quality))
 
-            commandSequence += self.generateAudioEncodingTokens()
+            commandSequence += self.generateAudioProcessingTokens()
 
             if self.__context['perform_cut']:
                 commandSequence += self.generateCropTokens()
@@ -432,7 +540,7 @@ class FfxController():
                 if td.getCodec != TrackCodec.PNG:
                     commandSequence2 += self.generateVP9Pass2Tokens(int(quality)) 
 
-            commandSequence2 += self.generateAudioEncodingTokens()
+            commandSequence2 += self.generateAudioProcessingTokens()
 
             if self.__context['perform_cut']:
                 commandSequence2 += self.generateCropTokens()

src/ffx/help_screen.py

@@ -20,5 +20,12 @@ class HelpScreen(Screen):
         yield build_screen_log_pane()
         yield Footer()
 
+
+    def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
+
     def action_back(self):
         go_back_or_exit(self)

src/ffx/helper.py

@@ -6,12 +6,23 @@ from .configuration_controller import ConfigurationController
 from .logging_utils import get_ffx_logger
 from .show_descriptor import ShowDescriptor
 
+from enum import Enum
+
 
 class EmptyStringUndefined(Undefined):
     def __str__(self):
         return ''
 
 
+class LogLevel(Enum):
+
+    DEBUG = 'debug'
+    INFO = 'info'
+    WARNING = 'warning'
+    ERROR = 'error'
+    CRITICAL = 'critical'
+
+
 DIFF_ADDED_KEY = 'added'
 DIFF_REMOVED_KEY = 'removed'
 DIFF_CHANGED_KEY = 'changed'
@@ -119,7 +130,7 @@ def setDiff(a : set, b : set) -> set:
 def permutateList(inputList: list, permutation: list):
 
     # 0,1,2: ABC
-    # 0,2,1: ACB
+    # 0,2,1: ACBffmpeg:
     # 1,2,0: BCA
 
     pass

src/ffx/inspect_details_screen.py

@@ -39,8 +39,8 @@ class InspectDetailsScreen(MediaWorkflowScreenBase):
     CSS = f"""
 
     Grid {{
-        grid-size: 6 11;
+        grid-size: 6 8;
-        grid-rows: 9 2 2 2 2 8 2 2 2 8 8;
+        grid-rows: 9  2 2  2  2 10  2 10;
         grid-columns: {GRID_COLUMN_LABEL_MIN} {GRID_COLUMN_2} {GRID_COLUMN_3} {GRID_COLUMN_4} {GRID_COLUMN_5} {GRID_COLUMN_6};
         height: 100%;
         width: 100%;
@@ -88,6 +88,10 @@ class InspectDetailsScreen(MediaWorkflowScreenBase):
     #differences-table {{
         row-span: 10;
     }}
+
+    .yellow {{
+        tint: yellow 40%;
+    }}
     """
 
     @classmethod
@@ -157,6 +161,7 @@ class InspectDetailsScreen(MediaWorkflowScreenBase):
             yield Static(" ")
             yield self.differencesTable
 
+
             # Row 2
             yield Static(" ", classes="five")
 
@@ -165,29 +170,26 @@ class InspectDetailsScreen(MediaWorkflowScreenBase):
             yield Button(t("Substitute"), id="pattern_button")
             yield Static(" ", classes="three")
 
+
             # Row 4
             yield Static(t("Pattern"))
             yield Input(type="text", id="pattern_input", classes="three")
             yield Static(" ")
 
+
             # Row 5
             yield Static(" ", classes="five")
 
             # Row 6
             yield Static(t("Media Tags"))
             yield self.mediaTagsTable
-            yield Static(" ", classes="two")
+            yield Static(" ")
+
 
             # Row 7
             yield Static(" ", classes="five")
 
             # Row 8
-            yield Static(" ")
-            yield Button(t("Set Default"), id="select_default_button")
-            yield Button(t("Set Forced"), id="select_forced_button")
-            yield Static(" ", classes="two")
-
-            # Row 9
             yield Static(t("Streams"))
             yield self.tracksTable
             yield Static(" ")
@@ -314,6 +316,10 @@ class InspectDetailsScreen(MediaWorkflowScreenBase):
         self._update_show_header_labels()
 
     def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         self._update_grid_layout()
 
         if self._currentPattern is None:

src/ffx/logging_utils.py

@@ -5,6 +5,7 @@ import os
 FFX_LOGGER_NAME = "FFX"
 CONSOLE_HANDLER_NAME = "ffx-console"
 FILE_HANDLER_NAME = "ffx-file"
+MUTED_CONSOLE_LEVEL = logging.CRITICAL + 1
 
 
 def get_ffx_logger(name: str = FFX_LOGGER_NAME) -> logging.Logger:
@@ -66,3 +67,31 @@ def configure_ffx_logger(
     )
 
     return logger
+
+
+def set_ffx_console_logging_enabled(
+    logger: logging.Logger | None,
+    *,
+    enabled: bool,
+):
+    if logger is None:
+        return None
+
+    console_handler = next(
+        (handler for handler in logger.handlers if handler.get_name() == CONSOLE_HANDLER_NAME),
+        None,
+    )
+    if console_handler is None:
+        return None
+
+    if enabled:
+        saved_level = getattr(console_handler, "_ffx_saved_level", None)
+        if saved_level is not None:
+            console_handler.setLevel(saved_level)
+            delattr(console_handler, "_ffx_saved_level")
+        return console_handler
+
+    if not hasattr(console_handler, "_ffx_saved_level"):
+        console_handler._ffx_saved_level = console_handler.level
+    console_handler.setLevel(MUTED_CONSOLE_LEVEL)
+    return console_handler

src/ffx/media_descriptor.py

@@ -2,6 +2,7 @@ import os, re, click
 
 from typing import List, Self
 
+from ffx.attachment_format import AttachmentFormat
 from ffx.track_type import TrackType
 from ffx.iso_language import IsoLanguage
 
@@ -328,6 +329,96 @@ class MediaDescriptor:
             if s.getType() == TrackType.ATTACHMENT
         ]
 
+    def hasStyledAssSubtitlesWithFontAttachments(self) -> bool:
+        return (
+            any(
+                trackDescriptor.getCodec() == TrackCodec.ASS
+                for trackDescriptor in self.getSubtitleTracks()
+            )
+            and any(
+                trackDescriptor.getAttachmentFormat() == AttachmentFormat.TTF
+                for trackDescriptor in self.getAttachmentTracks()
+            )
+        )
+
+    def withoutAttachmentTracks(
+        self,
+        attachmentFormat: AttachmentFormat | None = None,
+        context: dict | None = None,
+    ):
+        filteredTrackDescriptors = []
+        for trackDescriptor in self.__trackDescriptors:
+            if trackDescriptor.getType() == TrackType.ATTACHMENT and (
+                attachmentFormat is None
+                or trackDescriptor.getAttachmentFormat() == attachmentFormat
+            ):
+                continue
+            filteredTrackDescriptors.append(
+                trackDescriptor.clone(
+                    context=context if context is not None else self.__context
+                )
+            )
+
+        kwargs = {
+            MediaDescriptor.TAGS_KEY: dict(self.__mediaTags),
+            MediaDescriptor.TRACK_DESCRIPTOR_LIST_KEY: filteredTrackDescriptors,
+        }
+        if context is not None:
+            kwargs[MediaDescriptor.CONTEXT_KEY] = context
+        elif self.__context:
+            kwargs[MediaDescriptor.CONTEXT_KEY] = self.__context
+
+        filteredMediaDescriptor = MediaDescriptor(**kwargs)
+        filteredMediaDescriptor.reindexSubIndices()
+        return filteredMediaDescriptor
+
+    def withoutAttachmentsForComparison(self):
+        return self.withoutAttachmentTracks(context=self.__context)
+
+    def withSourceAttachmentTracks(
+        self,
+        sourceMediaDescriptor: Self,
+        attachmentFormat: AttachmentFormat | None = None,
+        context: dict | None = None,
+    ):
+        trackDescriptors = []
+        for trackDescriptor in self.__trackDescriptors:
+            if trackDescriptor.getType() == TrackType.ATTACHMENT and (
+                attachmentFormat is None
+                or trackDescriptor.getAttachmentFormat() == attachmentFormat
+            ):
+                continue
+            trackDescriptors.append(
+                trackDescriptor.clone(
+                    context=context if context is not None else self.__context
+                )
+            )
+
+        for sourceTrackDescriptor in sourceMediaDescriptor.getAttachmentTracks():
+            if (
+                attachmentFormat is not None
+                and sourceTrackDescriptor.getAttachmentFormat() != attachmentFormat
+            ):
+                continue
+            attachmentClone = sourceTrackDescriptor.clone(
+                context=context if context is not None else self.__context
+            )
+            attachmentClone.setIndex(len(trackDescriptors))
+            trackDescriptors.append(attachmentClone)
+
+        kwargs = {
+            MediaDescriptor.TAGS_KEY: dict(self.__mediaTags),
+            MediaDescriptor.TRACK_DESCRIPTOR_LIST_KEY: trackDescriptors,
+        }
+        if context is not None:
+            kwargs[MediaDescriptor.CONTEXT_KEY] = context
+        elif self.__context:
+            kwargs[MediaDescriptor.CONTEXT_KEY] = self.__context
+
+        mergedMediaDescriptor = MediaDescriptor(**kwargs)
+        mergedMediaDescriptor.reindexSubIndices()
+        return mergedMediaDescriptor
+
 
     def getImportFileTokens(self, use_sub_index: bool = True):
         """Generate ffmpeg import options for external stream files"""
@@ -340,10 +431,13 @@ class MediaDescriptor:
             importedFilePath = td.getExternalSourceFilePath()
 
             if importedFilePath:
-
+                substitutionMessage = (
-                self.__logger.info(f"Substituting subtitle stream #{td.getIndex()} "
+                    f"Substituting subtitle stream #{td.getIndex()} "
                     + f"({td.getType().label()}:{td.getSubIndex()}) "
-                                    + f"with import from file {td.getExternalSourceFilePath()}")
+                    + f"with import from file {td.getExternalSourceFilePath()}"
+                )
+                click.echo(substitutionMessage)
+                self.__logger.debug(substitutionMessage)
 
                 importFileTokens += [
                     "-i",
@@ -421,11 +515,11 @@ class MediaDescriptor:
 
         if sourceMediaDescriptor:
             fontDescriptors = [ftd for ftd in sourceMediaDescriptor.getAttachmentTracks()
-                                if ftd.getCodec() == TrackCodec.TTF]
+                                if ftd.getAttachmentFormat() == AttachmentFormat.TTF]
         else:
             fontDescriptors = [ftd for ftd in self.__trackDescriptors
                                 if ftd.getType() == TrackType.ATTACHMENT
-                                and ftd.getCodec() == TrackCodec.TTF]
+                                and ftd.getAttachmentFormat() == AttachmentFormat.TTF]
 
         for ad in sorted(fontDescriptors, key=lambda d: d.getIndex()):
             inputMappingTokens += ["-map", f"0:{ad.getIndex()}"]
@@ -433,25 +527,72 @@ class MediaDescriptor:
         return inputMappingTokens
 
 
-    def searchSubtitleFiles(self, searchDirectory, prefix):
+    def searchSubtitleFiles(
-
+        self,
-        sesld_match = re.compile(f"{prefix}_{MediaDescriptor.SEASON_EPISODE_STREAM_LANGUAGE_DISPOSITIONS_MATCH}")
+        searchDirectory,
-        sld_match = re.compile(f"{prefix}_{MediaDescriptor.STREAM_LANGUAGE_DISPOSITIONS_MATCH}")
+        prefix,
-
+        extension=SUBTITLE_FILE_EXTENSION,
-        subtitleFileDescriptors = []
+        strict=False,
-
-        for subtitleFilename in os.listdir(searchDirectory):
-            if subtitleFilename.startswith(prefix) and subtitleFilename.endswith(
-                "." + MediaDescriptor.SUBTITLE_FILE_EXTENSION
     ):
 
-                sesld_result = sesld_match.search(subtitleFilename)
+        normalizedExtension = str(extension).strip().lower()
-                sld_result = None if not sesld_result is None else sld_match.search(subtitleFilename)
+        if normalizedExtension.startswith('.'):
+            normalizedExtension = normalizedExtension[1:]
+        escapedPrefix = re.escape(prefix)
+        sesld_match = re.compile(
+            f"{escapedPrefix}_{MediaDescriptor.SEASON_EPISODE_STREAM_LANGUAGE_DISPOSITIONS_MATCH}"
+        )
+        sld_match = re.compile(
+            f"{escapedPrefix}_{MediaDescriptor.STREAM_LANGUAGE_DISPOSITIONS_MATCH}"
+        )
 
-                if not sesld_result is None:
+        subtitleFileDescriptors = []
+        subtitleFilenames = []
+
+        for subtitleFilename in sorted(os.listdir(searchDirectory)):
+            subtitleFilePath = os.path.join(searchDirectory, subtitleFilename)
+            subtitleFilenameStem, subtitleFilenameExtension = os.path.splitext(
+                subtitleFilename
+            )
+            if (
+                os.path.isfile(subtitleFilePath)
+                and subtitleFilenameStem.startswith(prefix + '_')
+                and subtitleFilenameExtension.lower() == '.' + normalizedExtension
+            ):
+                subtitleFilenames.append(subtitleFilename)
+
+        expectedSubtitleTrackIndices = {
+            subtitleTrack.getIndex()
+            for subtitleTrack in self.getSubtitleTracks()
+        }
+        if strict and len(subtitleFilenames) > len(expectedSubtitleTrackIndices):
+            raise ValueError(
+                f"Found {len(subtitleFilenames)} matching .{normalizedExtension} files "
+                + f"for {len(expectedSubtitleTrackIndices)} subtitle tracks."
+            )
+
+        for subtitleFilename in subtitleFilenames:
+            subtitleFilenameStem = os.path.splitext(subtitleFilename)[0]
+            sesld_result = (
+                None
+                if strict
+                else sesld_match.fullmatch(subtitleFilenameStem)
+            )
+            sld_result = (
+                None
+                if sesld_result is not None
+                else sld_match.fullmatch(subtitleFilenameStem)
+            )
+
+            if strict and sesld_result is None and sld_result is None:
+                raise ValueError(
+                    f"Subtitle filename does not match the expected pattern: "
+                    + subtitleFilename
+                )
+
+            if sesld_result is not None:
 
                 subtitleFilePath = os.path.join(searchDirectory, subtitleFilename)
-                    if os.path.isfile(subtitleFilePath):
 
                 subtitleFileDescriptor = {}
                 subtitleFileDescriptor["path"] = subtitleFilePath
@@ -465,17 +606,18 @@ class MediaDescriptor:
                 numCaptGroups = len(dispCaptGroups)
                 if numCaptGroups > 4:
                     for groupIndex in range(numCaptGroups - 4):
-                                disp = TrackDisposition.fromIndicator(dispCaptGroups[groupIndex + 4])
+                        disp = TrackDisposition.fromIndicator(
+                            dispCaptGroups[groupIndex + 4]
+                        )
                         if disp is not None:
                             dispSet.add(disp)
                 subtitleFileDescriptor["disposition_set"] = dispSet
 
                 subtitleFileDescriptors.append(subtitleFileDescriptor)
 
-                if not sld_result is None:
+            if sld_result is not None:
 
                 subtitleFilePath = os.path.join(searchDirectory, subtitleFilename)
-                    if os.path.isfile(subtitleFilePath):
 
                 subtitleFileDescriptor = {}
                 subtitleFileDescriptor["path"] = subtitleFilePath
@@ -487,13 +629,52 @@ class MediaDescriptor:
                 numCaptGroups = len(dispCaptGroups)
                 if numCaptGroups > 2:
                     for groupIndex in range(numCaptGroups - 2):
-                                disp = TrackDisposition.fromIndicator(dispCaptGroups[groupIndex + 2])
+                        disp = TrackDisposition.fromIndicator(
+                            dispCaptGroups[groupIndex + 2]
+                        )
                         if disp is not None:
                             dispSet.add(disp)
                 subtitleFileDescriptor["disposition_set"] = dispSet
 
                 subtitleFileDescriptors.append(subtitleFileDescriptor)
 
+        if strict:
+            discoveredTrackIndices = [
+                descriptor['index'] for descriptor in subtitleFileDescriptors
+            ]
+            duplicateTrackIndices = sorted(
+                {
+                    trackIndex
+                    for trackIndex in discoveredTrackIndices
+                    if discoveredTrackIndices.count(trackIndex) > 1
+                }
+            )
+            if duplicateTrackIndices:
+                duplicateDescription = ', '.join(
+                    f"#{index}" for index in duplicateTrackIndices
+                )
+                raise ValueError(
+                    "Multiple external subtitle files refer to subtitle track(s) "
+                    + duplicateDescription
+                    + "."
+                )
+
+            unexpectedTrackIndices = sorted(
+                set(discoveredTrackIndices) - expectedSubtitleTrackIndices
+            )
+            if unexpectedTrackIndices:
+                unexpectedDescription = ', '.join(
+                    f"#{index}" for index in unexpectedTrackIndices
+                )
+                expectedDescription = ', '.join(
+                    f"#{index}" for index in sorted(expectedSubtitleTrackIndices)
+                ) or 'none'
+                raise ValueError(
+                    "External subtitle track index pattern does not match the media "
+                    + f"subtitle tracks: found {unexpectedDescription}; "
+                    + f"expected a subset of {expectedDescription}."
+                )
+
 
         self.__logger.debug(f"searchSubtitleFiles(): Available subtitle files {subtitleFileDescriptors}")
 
@@ -507,12 +688,19 @@ class MediaDescriptor:
         season: int = -1,
         episode: int = -1,
         preserve_dispositions: bool = False,
+        extension: str = SUBTITLE_FILE_EXTENSION,
+        strict: bool = False,
     ):
         
         # click.echo(f"Season: {season} Episode: {episode}")
         self.__logger.debug(f"importSubtitles(): Season: {season} Episode: {episode}")
 
-        availableFileSubtitleDescriptors = self.searchSubtitleFiles(searchDirectory, prefix)
+        availableFileSubtitleDescriptors = self.searchSubtitleFiles(
+            searchDirectory,
+            prefix,
+            extension=extension,
+            strict=strict,
+        )
         
         self.__logger.debug(f"importSubtitles(): availableFileSubtitleDescriptors: {availableFileSubtitleDescriptors}")
 
@@ -525,7 +713,8 @@ class MediaDescriptor:
                 [
                     d
                     for d in availableFileSubtitleDescriptors
-                    if ((season == -1 and episode == -1)
+                    if (strict
+                        or (season == -1 and episode == -1)
                         or (
                             d.get("season") == int(season)
                             and d.get("episode") == int(episode)
@@ -539,6 +728,7 @@ class MediaDescriptor:
 
         self.__logger.debug(f"importSubtitles(): matchingSubtitleFileDescriptors: {matchingSubtitleFileDescriptors}")
 
+        importedTrackIndices = []
         for msfd in matchingSubtitleFileDescriptors:
             matchingSubtitleTrackDescriptor = [s for s in subtitleTracks if s.getIndex() == msfd["index"]]
             if matchingSubtitleTrackDescriptor:
@@ -552,6 +742,19 @@ class MediaDescriptor:
                 matchingTrack.getTags()["language"] = msfd["language"]
                 if msfd["disposition_set"] and not preserve_dispositions:
                     matchingTrack.setDispositionSet(msfd["disposition_set"])
+                importedTrackIndices.append(matchingTrack.getIndex())
+
+        expectedTrackIndices = sorted(
+            subtitleTrack.getIndex() for subtitleTrack in subtitleTracks
+        )
+        importedTrackIndices = sorted(set(importedTrackIndices))
+        return {
+            "candidate_count": len(availableFileSubtitleDescriptors),
+            "imported_track_indices": importedTrackIndices,
+            "missing_track_indices": sorted(
+                set(expectedTrackIndices) - set(importedTrackIndices)
+            ),
+        }
 
 
     def getConfiguration(self, label: str = ''):

src/ffx/media_descriptor_change_set.py

@@ -56,8 +56,24 @@ class MediaDescriptorChangeSet():
                                     and 'ignore' in metadataConfiguration['streams'].keys() else [])
 
 
-        self.__targetTrackDescriptors = targetMediaDescriptor.getTrackDescriptors() if targetMediaDescriptor is not None else []
+        self.__targetTrackDescriptors = (
-        self.__sourceTrackDescriptors = sourceMediaDescriptor.getTrackDescriptors() if sourceMediaDescriptor is not None else []
+            [
+                trackDescriptor
+                for trackDescriptor in targetMediaDescriptor.getTrackDescriptors()
+                if trackDescriptor.getType() != TrackType.ATTACHMENT
+            ]
+            if targetMediaDescriptor is not None
+            else []
+        )
+        self.__sourceTrackDescriptors = (
+            [
+                trackDescriptor
+                for trackDescriptor in sourceMediaDescriptor.getTrackDescriptors()
+                if trackDescriptor.getType() != TrackType.ATTACHMENT
+            ]
+            if sourceMediaDescriptor is not None
+            else []
+        )
         self.__targetTrackDescriptorsByIndex = {
             trackDescriptor.getIndex(): trackDescriptor
             for trackDescriptor in self.__targetTrackDescriptors

src/ffx/media_edit_screen.py

@@ -12,11 +12,13 @@ from ffx.track_descriptor import TrackDescriptor
 from .i18n import t
 from .confirm_screen import ConfirmScreen
 from .media_workflow_screen_base import MediaWorkflowScreenBase
-from .screen_support import build_screen_log_pane, localized_column_width, write_screen_log
+from .screen_support import build_screen_log_pane, localized_column_width
 from .tag_delete_screen import TagDeleteScreen
 from .tag_details_screen import TagDetailsScreen
 from .track_details_screen import TrackDetailsScreen
 
+from .helper import LogLevel
+
 
 class MediaEditScreen(MediaWorkflowScreenBase):
 
@@ -176,6 +178,10 @@ class MediaEditScreen(MediaWorkflowScreenBase):
         yield Footer()
 
     def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         self._update_grid_layout()
         self.updateMediaTags()
         self.updateTracks()
@@ -207,9 +213,24 @@ class MediaEditScreen(MediaWorkflowScreenBase):
         if self._messageText:
             self.notify(self._messageText)
 
-    def _notify_from_worker(self, message: str) -> None:
+
-        self.app.call_from_thread(write_screen_log, self, str(message))
+    def workerLoggingHandler(self,
-        self.app.call_from_thread(self.notify, str(message))
+                                message: str,
+                                level: LogLevel = LogLevel.INFO) -> None:
+
+        if level == LogLevel.DEBUG:
+            self.context["logger"].debug(str(message))
+        elif level == LogLevel.INFO:
+            self.context["logger"].info(str(message))
+        elif level == LogLevel.WARNING:
+            self.context["logger"].warning(str(message))
+        elif level == LogLevel.ERROR:
+            self.context["logger"].error(str(message))
+        elif level == LogLevel.CRITICAL:
+            self.context["logger"].critical(str(message))
+        else:
+            raise Exception(f"Undefined Logging Level (msg={message})")
+
 
     def _report_apply_timings(self, applyResult: dict, reloadSeconds: float = 0.0) -> None:
         timings = dict(applyResult.get("timings", {}))
@@ -226,10 +247,6 @@ class MediaEditScreen(MediaWorkflowScreenBase):
             + f"total={totalSeconds:.2f}s"
         )
         self.context["logger"].info(timingSummary)
-        write_screen_log(self, timingSummary)
-
-        if int(self.context.get("verbosity", 0) or 0) > 0:
-            self.notify(timingSummary)
 
     def updateToggleButtons(self):
         self._set_toggle_button_state(
@@ -402,9 +419,8 @@ class MediaEditScreen(MediaWorkflowScreenBase):
             self.setMessage(t("Apply already running."))
             return
 
-        write_screen_log(
+        self.context["logger"].info(
-            self,
+            t("Starting metadata apply for {filename}.", filename=self._mediaFilename)
-            t("Starting metadata apply for {filename}.", filename=self._mediaFilename),
         )
         self._applyChangesWorker = self.run_apply_changes_worker()
 
@@ -420,7 +436,7 @@ class MediaEditScreen(MediaWorkflowScreenBase):
             self._mediaFilename,
             self._baselineMediaDescriptor,
             self._sourceMediaDescriptor,
-            notify=self._notify_from_worker,
+            loggingHandler = self.workerLoggingHandler,
         )
 
     def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
@@ -435,7 +451,6 @@ class MediaEditScreen(MediaWorkflowScreenBase):
                     self._mediaFilename,
                     exc_info=(type(error), error, error.__traceback__),
                 )
-                write_screen_log(self, t("Apply failed: {error}", error=error))
                 self.setMessage(t("Apply failed: {error}", error=error))
             self._applyChangesWorker = None
             return
@@ -447,8 +462,7 @@ class MediaEditScreen(MediaWorkflowScreenBase):
 
         if applyResult.get("dry_run", False):
             self._report_apply_timings(applyResult, reloadSeconds=0.0)
-            write_screen_log(
+            self.context["logger"].info(
-                self,
                 t(
                     "Dry-run prepared temporary output {target_path}.",
                     target_path=applyResult["target_path"],
@@ -464,12 +478,12 @@ class MediaEditScreen(MediaWorkflowScreenBase):
             return
 
         reloadStart = monotonic()
-        write_screen_log(self, t("Reloading file after metadata write."))
+        self.context["logger"].info(t("Reloading file after metadata write."))
         self.reloadProperties(reset_draft=True)
         self.refreshAfterDraftChange()
         reloadSeconds = monotonic() - reloadStart
         self._report_apply_timings(applyResult, reloadSeconds=reloadSeconds)
-        write_screen_log(self, t("Changes applied and file reloaded."))
+        self.context["logger"].info(t("Changes applied and file reloaded."))
         self.setMessage(t("Changes applied and file reloaded."))
         self._applyChangesWorker = None
 

src/ffx/media_workflow_screen_base.py

@@ -6,6 +6,7 @@ from textual.screen import Screen
 from textual.widgets import DataTable
 from textual.widgets._data_table import CellDoesNotExist
 
+from ffx.attachment_format import AttachmentFormat
 from ffx.audio_layout import AudioLayout
 from ffx.file_properties import FileProperties
 from ffx.helper import DIFF_ADDED_KEY, DIFF_CHANGED_KEY, DIFF_REMOVED_KEY
@@ -125,6 +126,32 @@ class MediaWorkflowScreenBase(Screen):
         add_auto_table_column(self.differencesTable, t(self.DIFFERENCES_COLUMN_LABEL))
         self.differencesTable.cursor_type = "row"
 
+    def _track_codec_cell_value(self, trackDescriptor: TrackDescriptor) -> str:
+        if trackDescriptor.getType() == TrackType.ATTACHMENT:
+            attachmentFormat = trackDescriptor.getAttachmentFormat()
+            if attachmentFormat == AttachmentFormat.UNKNOWN:
+                return attachmentFormat.identifier()
+            return attachmentFormat.label()
+        return trackDescriptor.getFormatDescriptor().label()
+
+    def _track_language_cell_value(self, trackDescriptor: TrackDescriptor) -> str:
+        if trackDescriptor.getType() == TrackType.ATTACHMENT:
+            return " "
+        return trackDescriptor.getLanguage().label()
+
+    def _track_disposition_cell_value(
+        self,
+        trackDescriptor: TrackDescriptor,
+        disposition: TrackDisposition,
+    ) -> str:
+        if trackDescriptor.getType() == TrackType.ATTACHMENT:
+            return " "
+        return (
+            t("Yes")
+            if disposition in trackDescriptor.getDispositionSet()
+            else t("No")
+        )
+
     def reloadProperties(self, reset_draft: bool = True):
         self._mediaFileProperties = FileProperties(self.context, self._mediaFilename)
         probedMediaDescriptor = self._mediaFileProperties.getMediaDescriptor()
@@ -139,10 +166,9 @@ class MediaWorkflowScreenBase(Screen):
             self._baselineMediaDescriptor = probedMediaDescriptor
             self._sourceMediaDescriptor = probedMediaDescriptor
             self._currentPattern = self._mediaFileProperties.getPattern()
-            self._targetMediaDescriptor = (
+            self._targetMediaDescriptor = self._resolve_target_media_descriptor(
-                self._currentPattern.getMediaDescriptor(self.context)
+                self._currentPattern,
-                if self._currentPattern is not None
+                self._sourceMediaDescriptor,
-                else None
             )
 
         self.rebuildChangeSet()
@@ -178,6 +204,25 @@ class MediaWorkflowScreenBase(Screen):
     def getTrackEditSourceDescriptor(self) -> TrackDescriptor | None:
         return self.getSelectedTrackDescriptor()
 
+    def _resolve_target_media_descriptor(self, currentPattern, sourceMediaDescriptor):
+        if currentPattern is None:
+            return None
+
+        targetMediaDescriptor = currentPattern.getMediaDescriptor(self.context)
+        styledAssDetector = getattr(
+            sourceMediaDescriptor,
+            "hasStyledAssSubtitlesWithFontAttachments",
+            None,
+        )
+        if callable(styledAssDetector) and styledAssDetector():
+            targetMediaDescriptor = targetMediaDescriptor.withSourceAttachmentTracks(
+                sourceMediaDescriptor,
+                AttachmentFormat.TTF,
+                context=self.context,
+            )
+
+        return targetMediaDescriptor
+
     def updateMediaTags(self):
         displayedMediaDescriptor = self.getDisplayedMediaDescriptor()
         self._sourceMediaTagRowData = populate_tag_table(
@@ -221,15 +266,21 @@ class MediaWorkflowScreenBase(Screen):
                 trackDescriptor.getIndex(),
                 t(trackType.label()),
                 typeCounter[trackType],
-                trackDescriptor.getCodec().label(),
+                self._track_codec_cell_value(trackDescriptor),
                 t(audioLayout.label())
                 if trackType == TrackType.AUDIO
                 and audioLayout != AudioLayout.LAYOUT_UNDEFINED
                 else " ",
-                trackDescriptor.getLanguage().label(),
+                self._track_language_cell_value(trackDescriptor),
                 trackTitle,
-                t("Yes") if TrackDisposition.DEFAULT in dispositionSet else t("No"),
+                self._track_disposition_cell_value(
-                t("Yes") if TrackDisposition.FORCED in dispositionSet else t("No"),
+                    trackDescriptor,
+                    TrackDisposition.DEFAULT,
+                ),
+                self._track_disposition_cell_value(
+                    trackDescriptor,
+                    TrackDisposition.FORCED,
+                ),
             )
 
             row_key = self.tracksTable.add_row(*map(str, row))

src/ffx/metadata_editor.py

@@ -16,6 +16,8 @@ from .media_descriptor_change_set import MediaDescriptorChangeSet
 from .process import executeProcess, formatCommandSequence
 from .video_encoder import VideoEncoder
 
+from .helper import LogLevel
+
 
 def create_temporary_output_path(source_path: str) -> str:
     sourceDirectory = os.path.dirname(os.path.abspath(source_path)) or "."
@@ -75,22 +77,22 @@ def notify_ffmpeg_invocation(
     context: dict,
     command_sequence: list[str],
     *,
-    notify=None,
+    loggingHandler = None,
     dry_run: bool = False,
 ) -> None:
-    notify_callback = notify or context.get("notify_callback")
+    loggingCallback = loggingHandler or context.get("logging_handler")
-    if not callable(notify_callback):
+    if not callable(loggingCallback):
         return
 
     verbosity = int(context.get("verbosity", 0) or 0)
     if verbosity > 0:
         if dry_run:
-            notify_callback(f"ffmpeg dry-run: {formatCommandSequence(command_sequence)}")
+            loggingCallback(f"ffmpeg dry-run: {formatCommandSequence(command_sequence)}", level = LogLevel.DEBUG)
         else:
-            notify_callback(f"ffmpeg: {formatCommandSequence(command_sequence)}")
+            loggingCallback(f"ffmpeg: {formatCommandSequence(command_sequence)}", level = LogLevel.DEBUG)
         return
 
-    notify_callback("ffmpeg dry-run prepared.") if dry_run else notify_callback(
+    loggingCallback("ffmpeg dry-run prepared.") if dry_run else loggingCallback(
         "ffmpeg metadata write started."
     )
 
@@ -101,7 +103,7 @@ def apply_metadata_edits(
     baseline_descriptor: MediaDescriptor,
     draft_descriptor: MediaDescriptor,
     *,
-    notify=None,
+    loggingHandler = None,
 ) -> dict[str, object]:
 
     temporaryOutputPath = create_temporary_output_path(source_path)
@@ -126,7 +128,7 @@ def apply_metadata_edits(
             notify_ffmpeg_invocation(
                 editContext,
                 commandSequence,
-                notify=notify,
+                loggingHandler = loggingHandler,
                 dry_run=True,
             )
 
@@ -142,7 +144,9 @@ def apply_metadata_edits(
                 },
             }
 
-        notify_ffmpeg_invocation(editContext, commandSequence, notify=notify)
+        notify_ffmpeg_invocation(editContext,
+                                    commandSequence,
+                                    loggingHandler = loggingHandler)
 
         ffmpegStart = monotonic()
         _out, err, rc = executeProcess(commandSequence, context=editContext)

src/ffx/model/pattern.py

@@ -7,6 +7,7 @@ from .show import Base, Show
 
 from ffx.media_descriptor import MediaDescriptor
 from ffx.show_descriptor import ShowDescriptor
+from ffx.track_type import TrackType
 
 
 class Pattern(Base):
@@ -76,6 +77,8 @@ class Pattern(Base):
         subIndexCounter = {}
         for track in self.tracks:
             trackType = track.getType()
+            if trackType == TrackType.ATTACHMENT:
+                continue
             if not trackType in subIndexCounter.keys():
                 subIndexCounter[trackType] = 0
             kwargs[MediaDescriptor.TRACK_DESCRIPTOR_LIST_KEY].append(track.getDescriptor(context, subIndex = subIndexCounter[trackType]))

src/ffx/model/track.py

@@ -4,6 +4,7 @@ from sqlalchemy.orm import relationship, declarative_base, sessionmaker
 
 from .show import Base
 
+from ffx.attachment_format import AttachmentFormat
 from ffx.track_type import TrackType
 
 from ffx.iso_language import IsoLanguage
@@ -132,9 +133,16 @@ class Track(Base):
 
         if trackType in [t.label() for t in TrackType]:
 
+            if trackType == TrackType.ATTACHMENT.label():
+                storedFormatIdentifier = AttachmentFormat.identifyFfprobeStream(streamObj).identifier()
+            else:
+                storedFormatIdentifier = TrackCodec.identify(
+                    streamObj.get(TrackDescriptor.FFPROBE_CODEC_KEY)
+                ).identifier()
+
             return cls(pattern_id = patternId,
                         track_type = trackType,
-                        codec_name = streamObj[TrackDescriptor.FFPROBE_CODEC_NAME_KEY],
+                        codec_name = storedFormatIdentifier,
                         disposition_flags = sum([2**t.index() for (k,v) in streamObj[TrackDescriptor.FFPROBE_DISPOSITION_KEY].items()
                                                         if v and (t := TrackDisposition.find(k)) is not None]),
                         audio_layout = AudioLayout.identify(streamObj))
@@ -153,8 +161,20 @@ class Track(Base):
         return TrackType.fromIndex(self.track_type)
 
     def getCodec(self) -> TrackCodec:
+        if self.getType() == TrackType.ATTACHMENT:
+            return TrackCodec.UNKNOWN
         return TrackCodec.identify(self.codec_name)
 
+    def getAttachmentFormat(self) -> AttachmentFormat:
+        if self.getType() != TrackType.ATTACHMENT:
+            return AttachmentFormat.UNKNOWN
+        return AttachmentFormat.identify(self.codec_name)
+
+    def getFormatDescriptor(self):
+        if self.getType() == TrackType.ATTACHMENT:
+            return self.getAttachmentFormat()
+        return self.getCodec()
+
     def getIndex(self):
         return int(self.index) if self.index is not None else -1
 
@@ -206,6 +226,9 @@ class Track(Base):
             kwargs[TrackDescriptor.SUB_INDEX_KEY] = subIndex
 
         kwargs[TrackDescriptor.TRACK_TYPE_KEY] = self.getType()
+        if self.getType() == TrackType.ATTACHMENT:
+            kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY] = self.getAttachmentFormat()
+        else:
             kwargs[TrackDescriptor.CODEC_KEY] = self.getCodec()
         
         kwargs[TrackDescriptor.DISPOSITION_SET_KEY] = self.getDispositionSet()

src/ffx/pattern_controller.py

@@ -8,6 +8,7 @@ from ffx.model.track import Track
 from ffx.model.track_tag import TrackTag
 from ffx.track_descriptor import TrackDescriptor
 from ffx.track_disposition import TrackDisposition
+from ffx.track_type import TrackType
 
 
 class DuplicatePatternMatchError(click.ClickException):
@@ -86,12 +87,16 @@ class PatternController:
             )
 
         normalized_descriptors = []
+        filtered_attachments = False
         for trackDescriptor in trackDescriptors:
             if type(trackDescriptor) is not TrackDescriptor:
                 raise TypeError(
                     "PatternController: All track descriptors are required to be of type TrackDescriptor"
                 )
-            normalized_descriptors.append(trackDescriptor)
+            if trackDescriptor.getType() == TrackType.ATTACHMENT:
+                filtered_attachments = True
+                continue
+            normalized_descriptors.append(trackDescriptor.clone())
 
         if not normalized_descriptors:
             raise InvalidPatternSchemaError(
@@ -102,6 +107,10 @@ class PatternController:
             normalized_descriptors, key=lambda descriptor: descriptor.getIndex()
         )
 
+        if filtered_attachments:
+            for index, descriptor in enumerate(normalized_descriptors):
+                descriptor.setIndex(index)
+
         index_set = {descriptor.getIndex() for descriptor in normalized_descriptors}
         expected_indexes = set(range(len(normalized_descriptors)))
         if index_set != expected_indexes:
@@ -134,7 +143,7 @@ class PatternController:
     def _build_track_row(self, trackDescriptor: TrackDescriptor) -> Track:
         track = Track(
             track_type=int(trackDescriptor.getType().index()),
-            codec_name=str(trackDescriptor.getCodec().identifier()),
+            codec_name=str(trackDescriptor.getFormatDescriptor().identifier()),
             index=int(trackDescriptor.getIndex()),
             source_index=int(trackDescriptor.getSourceIndex()),
             disposition_flags=int(
@@ -170,7 +179,7 @@ class PatternController:
             pattern.tracks.append(self._build_track_row(trackDescriptor))
 
     def _validate_persisted_pattern(self, pattern: Pattern):
-        if not pattern.tracks:
+        if not any(track.getType() != TrackType.ATTACHMENT for track in pattern.tracks):
             raise InvalidPatternSchemaError(
                 f"Pattern #{pattern.getId()} ({pattern.getPattern()!r}) is invalid because it has no tracks."
             )

src/ffx/pattern_delete_screen.py

@@ -68,6 +68,10 @@ class PatternDeleteScreen(Screen):
 
 
     def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         if self.__showDescriptor:
             self.query_one("#showlabel", Static).update(f"{self.__showDescriptor.getId()} - {self.__showDescriptor.getName()} ({self.__showDescriptor.getYear()})")
         if not self.__pattern is None:

src/ffx/pattern_details_screen.py

@@ -88,6 +88,9 @@ class PatternDetailsScreen(Screen):
     .three {
         column-span: 3;
     }
+    .two {
+        column-span: 2;
+    }
     
     .four {
         column-span: 4;
@@ -114,7 +117,7 @@ class PatternDetailsScreen(Screen):
     }
 
     .yellow {
-        tint: yellow 40%;
+        color: yellow;
     }
     """
 
@@ -175,7 +178,7 @@ class PatternDetailsScreen(Screen):
                 row = (td.getIndex(),
                         t(trackType.label()),
                         typeCounter[trackType],
-                        td.getCodec().label(),
+                        td.getFormatDescriptor().label(),
                         t(audioLayout.label()) if trackType == TrackType.AUDIO
                             and audioLayout != AudioLayout.LAYOUT_UNDEFINED else ' ',
                         trackLanguage.label() if trackLanguage != IsoLanguage.UNDEFINED else ' ',
@@ -326,8 +329,12 @@ class PatternDetailsScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         if not self.__showDescriptor is None:
             self.query_one("#showlabel", Static).update(f"{self.__showDescriptor.getId()} - {self.__showDescriptor.getName()} ({self.__showDescriptor.getYear()})")
+            self.updateShowQualityHint()
 
         if self.__pattern is not None:
 
@@ -347,6 +354,7 @@ class PatternDetailsScreen(Screen):
         if not hasattr(self, "tracksTable") or not hasattr(self, "tagsTable"):
             return
 
+        self.updateShowQualityHint()
         self.updateTags()
         self.updateTracks()
 
@@ -412,7 +420,9 @@ class PatternDetailsScreen(Screen):
             # Row 4
             yield Static(t("Quality"))
             yield Input(type="integer", id="quality_input")
-            yield Static(' ', classes="five")
+            yield Static(" ")
+            yield Static("", id="show_quality_hint", classes="two yellow")
+            yield Static(' ', classes="two")
 
 
             # Row 5
@@ -501,6 +511,23 @@ class PatternDetailsScreen(Screen):
     def getPatternFromInput(self):
         return str(self.query_one("#pattern_input", Input).value)
 
+    def getShowQualityHintText(self):
+        if self.__showDescriptor is None:
+            return ""
+
+        showQuality = int(self.__showDescriptor.getQuality() or 0)
+        if showQuality <= 0:
+            return ""
+
+        patternQuality = int(getattr(self.__pattern, "quality", 0) or 0)
+        if patternQuality > 0:
+            return ""
+
+        return f"{t('Show')}: {showQuality}"
+
+    def updateShowQualityHint(self):
+        self.query_one("#show_quality_hint", Static).update(self.getShowQualityHintText())
+
     def getQualityFromInput(self):
         try:
             return int(self.query_one("#quality_input", Input).value)

src/ffx/process.py

@@ -1,7 +1,10 @@
 import os
 import shlex
+import signal
 import subprocess
-from typing import Iterable, List
+import threading
+import time
+from typing import Callable, Iterable, List
 
 from .logging_utils import get_ffx_logger
 
@@ -118,6 +121,8 @@ def executeProcess(
     directory: str = None,
     context: dict = None,
     timeoutSeconds: float = None,
+    stdoutLineHandler: Callable[[str], bool] | None = None,
+    stderrLineHandler: Callable[[str], bool] | None = None,
 ):
 
     logger = context['logger'] if context is not None and 'logger' in context else get_ffx_logger()
@@ -131,6 +136,16 @@ def executeProcess(
         formatCommandSequence(wrappedCommandSequence),
     )
 
+    if stdoutLineHandler is not None or stderrLineHandler is not None:
+        return executeStreamingProcess(
+            wrappedCommandSequence,
+            directory=directory,
+            logger=logger,
+            timeoutSeconds=timeoutSeconds,
+            stdoutLineHandler=stdoutLineHandler,
+            stderrLineHandler=stderrLineHandler,
+        )
+
     try:
         completed = subprocess.run(
             wrappedCommandSequence,
@@ -167,3 +182,162 @@ def executeProcess(
         )
 
     return completed.stdout, completed.stderr, completed.returncode
+
+
+def terminateProcess(process: subprocess.Popen, *, killAfterSeconds: float = 1.0) -> None:
+    if process.poll() is not None:
+        return
+
+    try:
+        if hasattr(os, "killpg"):
+            os.killpg(process.pid, signal.SIGTERM)
+        else:
+            process.terminate()
+    except ProcessLookupError:
+        return
+
+    deadline = time.monotonic() + killAfterSeconds
+    while process.poll() is None and time.monotonic() < deadline:
+        time.sleep(0.05)
+
+    if process.poll() is not None:
+        return
+
+    try:
+        if hasattr(os, "killpg"):
+            os.killpg(process.pid, signal.SIGKILL)
+        else:
+            process.kill()
+    except ProcessLookupError:
+        return
+
+
+def readProcessStream(
+    stream,
+    outputParts: list[str],
+    lineHandler: Callable[[str], bool] | None,
+    stopRequested: threading.Event,
+    logger,
+) -> None:
+    try:
+        for line in iter(stream.readline, ''):
+            outputParts.append(line)
+
+            if lineHandler is None:
+                continue
+
+            try:
+                if lineHandler(line):
+                    stopRequested.set()
+            except Exception:
+                logger.exception("Process line handler raised an exception")
+    finally:
+        stream.close()
+
+
+def executeStreamingProcess(
+    commandSequence: List[str],
+    *,
+    directory: str = None,
+    logger = None,
+    timeoutSeconds: float = None,
+    stdoutLineHandler: Callable[[str], bool] | None = None,
+    stderrLineHandler: Callable[[str], bool] | None = None,
+):
+    logger = logger or get_ffx_logger()
+
+    try:
+        process = subprocess.Popen(
+            commandSequence,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            cwd=directory,
+            bufsize=1,
+            start_new_session=True,
+        )
+    except FileNotFoundError as ex:
+        error = (
+            "Command not found while running "
+            + f"{formatCommandSequence(commandSequence)}: {ex.filename or ex}"
+        )
+        logger.error(error)
+        return '', error, COMMAND_NOT_FOUND_RETURN_CODE
+
+    stdoutParts: list[str] = []
+    stderrParts: list[str] = []
+    stopRequested = threading.Event()
+    timedOut = False
+
+    stdoutThread = threading.Thread(
+        target=readProcessStream,
+        args=(
+            process.stdout,
+            stdoutParts,
+            stdoutLineHandler,
+            stopRequested,
+            logger,
+        ),
+        daemon=True,
+    )
+    stderrThread = threading.Thread(
+        target=readProcessStream,
+        args=(
+            process.stderr,
+            stderrParts,
+            stderrLineHandler,
+            stopRequested,
+            logger,
+        ),
+        daemon=True,
+    )
+
+    stdoutThread.start()
+    stderrThread.start()
+
+    deadline = (
+        time.monotonic() + float(timeoutSeconds)
+        if timeoutSeconds is not None
+        else None
+    )
+    terminationRequested = False
+
+    while process.poll() is None:
+        if stopRequested.is_set():
+            terminationRequested = True
+            terminateProcess(process)
+            break
+
+        if deadline is not None and time.monotonic() >= deadline:
+            timedOut = True
+            terminationRequested = True
+            terminateProcess(process)
+            break
+
+        time.sleep(0.05)
+
+    returnCode = process.wait()
+    stdoutThread.join()
+    stderrThread.join()
+
+    stdout = ''.join(stdoutParts)
+    stderr = ''.join(stderrParts)
+
+    if timedOut:
+        error = (
+            f"Command timed out after {timeoutSeconds} seconds while running "
+            + formatCommandSequence(commandSequence)
+        )
+        if stderr:
+            error = f"{error}\n{stderr}"
+        logger.error(error)
+        return stdout, error, COMMAND_TIMED_OUT_RETURN_CODE
+
+    if returnCode != 0 and not terminationRequested:
+        logger.warning(
+            "executeProcess() rc=%s command=%s",
+            returnCode,
+            formatCommandSequence(commandSequence),
+        )
+
+    return stdout, stderr, returnCode

src/ffx/screen_support.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import logging
+import weakref
 from collections.abc import Mapping
 from dataclasses import dataclass
 
 from rich.cells import cell_len
 from rich.measure import measure_renderables
 from rich.text import Text
-from textual.widgets import Collapsible, RichLog
+from textual import events
+from textual.widgets import Collapsible, RichLog, Static
 
 from .helper import formatRichColor
 from .i18n import t
@@ -20,6 +23,152 @@ from .track_controller import TrackController
 
 SCREEN_LOG_PANE_ID = "screen_log_pane"
 SCREEN_LOG_VIEW_ID = "screen_log_view"
+SCREEN_LOG_RESIZE_HANDLE_ID = "screen_log_resize_handle"
+SCREEN_LOG_HANDLER_NAME = "ffx-screen-log"
+SCREEN_LOG_DEFAULT_HEIGHT = 8
+SCREEN_LOG_MIN_HEIGHT = 4
+SCREEN_LOG_COMPONENT_WIDTH = 16
+SCREEN_LOG_LEVEL_WIDTH = 8
+
+_SCREEN_LOG_PANE_ENABLED = False
+
+
+class ScreenLogHandler(logging.Handler):
+    """Mirror logger output into the active screen log pane when available."""
+
+    def __init__(self, app) -> None:
+        super().__init__(level=logging.DEBUG)
+        self.set_name(SCREEN_LOG_HANDLER_NAME)
+        self.set_app(app)
+
+    def set_app(self, app) -> None:
+        self._app_ref = weakref.ref(app) if app is not None else lambda: None
+
+    def emit(self, record: logging.LogRecord) -> None:
+        app = self._app_ref()
+        if app is None:
+            return
+
+        try:
+            message = str(self.format(record)).strip()
+        except Exception:
+            self.handleError(record)
+            return
+
+        if not message:
+            return
+
+        try:
+            app.call_from_thread(write_screen_log, app.screen, message)
+        except RuntimeError:
+            write_screen_log(app.screen, message)
+        except Exception:
+            self.handleError(record)
+
+
+class ScreenLogResizeHandle(Static):
+    DEFAULT_CSS = """
+    ScreenLogResizeHandle {
+        width: 100%;
+        height: 1;
+        content-align: center middle;
+        color: $text-muted;
+        background: $panel-lighten-1;
+    }
+
+    ScreenLogResizeHandle:hover {
+        color: $text;
+        background: $panel-lighten-2;
+    }
+    """
+
+    def __init__(self) -> None:
+        super().__init__(" drag to resize ", id=SCREEN_LOG_RESIZE_HANDLE_ID)
+        self._drag_active = False
+        self._drag_origin_screen_y = 0
+        self._drag_origin_height = SCREEN_LOG_DEFAULT_HEIGHT
+
+    def _get_log_pane(self):
+        return self.parent.parent if self.parent is not None else None
+
+    def on_mouse_down(self, event: events.MouseDown) -> None:
+        if event.button != 1:
+            return
+
+        log_pane = self._get_log_pane()
+        if log_pane is None:
+            return
+
+        self._drag_active = True
+        self._drag_origin_screen_y = event.screen_y
+        self._drag_origin_height = log_pane.get_log_height()
+        self.capture_mouse()
+        event.stop()
+
+    def on_mouse_move(self, event: events.MouseMove) -> None:
+        if not self._drag_active:
+            return
+
+        log_pane = self._get_log_pane()
+        if log_pane is None:
+            return
+
+        next_height = self._drag_origin_height + (
+            self._drag_origin_screen_y - event.screen_y
+        )
+        log_pane.set_log_height(next_height)
+        event.stop()
+
+    def on_mouse_up(self, event: events.MouseUp) -> None:
+        if not self._drag_active:
+            return
+
+        self._drag_active = False
+        self.release_mouse()
+        event.stop()
+
+
+class ResizableScreenLogPane(Collapsible):
+    def __init__(self) -> None:
+        self._log_view = RichLog(
+            id=SCREEN_LOG_VIEW_ID,
+            wrap=True,
+            markup=False,
+            highlight=False,
+            auto_scroll=True,
+        )
+        self._log_height = SCREEN_LOG_DEFAULT_HEIGHT
+        self._apply_log_height()
+
+        super().__init__(
+            ScreenLogResizeHandle(),
+            self._log_view,
+            title=t("Log"),
+            collapsed=True,
+            id=SCREEN_LOG_PANE_ID,
+        )
+        self.styles.width = "100%"
+
+    def _apply_log_height(self) -> None:
+        self._log_view.styles.height = self._log_height
+        self._log_view.styles.width = "100%"
+
+    def get_log_height(self) -> int:
+        return int(self._log_height)
+
+    def set_log_height(self, height: int) -> None:
+        next_height = max(SCREEN_LOG_MIN_HEIGHT, int(height))
+
+        try:
+            available_height = int(self.app.size.height) - 8
+        except Exception:
+            available_height = next_height
+
+        if available_height > 0:
+            next_height = min(next_height, available_height)
+
+        self._log_height = next_height
+        self._apply_log_height()
 
 
 @dataclass(frozen=True)
@@ -52,6 +201,48 @@ def build_screen_bootstrap(context: dict) -> ScreenBootstrap:
     )
 
 
+def set_screen_log_pane_enabled(enabled: bool) -> None:
+    global _SCREEN_LOG_PANE_ENABLED
+    _SCREEN_LOG_PANE_ENABLED = bool(enabled)
+
+
+def is_screen_log_pane_enabled() -> bool:
+    return bool(_SCREEN_LOG_PANE_ENABLED)
+
+
+def configure_screen_log_handler(logger, app, *, enabled: bool):
+    if logger is None:
+        return None
+
+    screen_log_handler = next(
+        (handler for handler in logger.handlers if handler.get_name() == SCREEN_LOG_HANDLER_NAME),
+        None,
+    )
+
+    if not enabled:
+        if screen_log_handler is not None:
+            logger.removeHandler(screen_log_handler)
+            screen_log_handler.close()
+        return None
+
+    if screen_log_handler is None:
+        screen_log_handler = ScreenLogHandler(app)
+        logger.addHandler(screen_log_handler)
+    elif isinstance(screen_log_handler, ScreenLogHandler):
+        screen_log_handler.set_app(app)
+
+    screen_log_handler.setLevel(logging.DEBUG)
+    screen_log_handler.setFormatter(
+        logging.Formatter(
+            f"%(name)-{SCREEN_LOG_COMPONENT_WIDTH}s "
+            + f"%(levelname)-{SCREEN_LOG_LEVEL_WIDTH}s "
+            + "%(asctime)s | %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    return screen_log_handler
+
+
 def build_screen_controllers(
     context: dict,
     *,
@@ -149,27 +340,15 @@ def update_table_column_label(table, column_key, label) -> None:
     table.refresh()
 
 
-def build_screen_log_pane() -> Collapsible:
+def build_screen_log_pane() -> ResizableScreenLogPane | Static:
     """Create a shared collapsible log pane for screen-local diagnostics."""
 
-    logView = RichLog(
+    if not is_screen_log_pane_enabled():
-        id=SCREEN_LOG_VIEW_ID,
+        hidden = Static("", id=f"{SCREEN_LOG_PANE_ID}_disabled")
-        wrap=True,
+        hidden.display = False
-        markup=False,
+        return hidden
-        highlight=False,
-        auto_scroll=True,
-    )
-    logView.styles.height = 8
-    logView.styles.width = "100%"
 
-    logPane = Collapsible(
+    return ResizableScreenLogPane()
-        logView,
-        title=t("Log"),
-        collapsed=True,
-        id=SCREEN_LOG_PANE_ID,
-    )
-    logPane.styles.width = "100%"
-    return logPane
 
 
 def toggle_screen_log_pane(screen) -> bool:

src/ffx/settings_screen.py

@@ -20,5 +20,12 @@ class SettingsScreen(Screen):
         yield build_screen_log_pane()
         yield Footer()
 
+
+    def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
+
     def action_back(self):
         go_back_or_exit(self)

src/ffx/shifted_season_delete_screen.py

@@ -67,6 +67,9 @@ class ShiftedSeasonDeleteScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         shiftedSeason: ShiftedSeason = self.__ssc.getShiftedSeason(self.__shiftedSeasonId)
 
         ownerLabel = (

src/ffx/shifted_season_details_screen.py

@@ -109,6 +109,9 @@ class ShiftedSeasonDetailsScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         if self.__shiftedSeasonId is not None:
             shiftedSeason: ShiftedSeason = self.__ssc.getShiftedSeason(self.__shiftedSeasonId)
 

src/ffx/show_delete_screen.py

@@ -109,5 +109,12 @@ class ShowDeleteScreen(Screen):
         if event.button.id == "cancel_button":
             self.app.pop_screen()
 
+
+    def on_mount(self):
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
+
     def action_back(self):
         go_back_or_exit(self)

src/ffx/show_details_screen.py

@@ -175,6 +175,9 @@ class ShowDetailsScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         if self.__showDescriptor is not None:
 
             showId = int(self.__showDescriptor.getId())

src/ffx/shows_screen.py

@@ -244,6 +244,10 @@ class ShowsScreen(Screen):
 
 
     def on_mount(self) -> None:
+
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         for show in self.__sc.getAllShows():
             self._add_show_row(show.getDescriptor(self.context))
 

src/ffx/tag_delete_screen.py

@@ -64,6 +64,9 @@ class TagDeleteScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         self.query_one("#keylabel", Static).update(str(self.__key))
         self.query_one("#valuelabel", Static).update(str(self.__value))
 

src/ffx/tag_details_screen.py

@@ -87,6 +87,9 @@ class TagDetailsScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         if self.__key is not None:
             self.query_one("#key_input", Input).value = str(self.__key)
 

src/ffx/track_codec.py

@@ -4,7 +4,7 @@ from enum import Enum
 class TrackCodec(Enum):
 
     VP9  =      {'identifier': 'vp9',                'format': 'ivf',        'extension': 'ivf'  , 'label':   'VP9'}
-    H265 =      {'identifier': 'hevc',               'format': 'h265',       'extension': 'h265' ,'label':   'H.265'}
+    H265 =      {'identifier': 'hevc',               'format': None,       'extension': 'h265' ,'label':   'H.265'}
     H264 =      {'identifier': 'h264',               'format': 'h264',       'extension': 'h264' ,'label':   'H.264'}
     MPEG4 =     {'identifier': 'mpeg4',             'format': 'm4v',        'extension': 'm4v' ,'label':   'MPEG-4'}
     MPEG2 =     {'identifier': 'mpeg2video',        'format': 'mpeg2video', 'extension': 'mpg' ,'label':   'MPEG-2'}
@@ -19,7 +19,6 @@ class TrackCodec(Enum):
     WEBVTT =    {'identifier': 'webvtt',             'format': 'webvtt',     'extension': 'vtt'  , 'label':  'WebVTT'}
     SRT  =      {'identifier': 'subrip',             'format': 'srt',        'extension': 'srt'  , 'label':  'SRT'}
     ASS  =      {'identifier': 'ass',                'format': 'ass',        'extension': 'ass'  , 'label':  'ASS'}
-    TTF  =      {'identifier': 'ttf',                'format': None,         'extension': 'ttf'  , 'label':  'TTF'}
     PGS  =      {'identifier': 'hdmv_pgs_subtitle',  'format': 'sup',        'extension': 'sup'  , 'label':  'PGS'}
     VOBSUB =    {'identifier': 'dvd_subtitle',       'format': None,         'extension': 'mkv'  , 'label':  'VobSub'}
 

src/ffx/track_controller.py

@@ -35,6 +35,8 @@ class TrackController():
 
 
     def addTrack(self, trackDescriptor : TrackDescriptor, patternId = None):
+        if trackDescriptor.getType() == TrackType.ATTACHMENT:
+            return False
 
         # option to override pattern id in case track descriptor has not set it
         patId = int(trackDescriptor.getPatternId() if patternId is None else patternId)
@@ -43,7 +45,7 @@ class TrackController():
             s = self.Session()
             track = Track(pattern_id = patId,
                             track_type = int(trackDescriptor.getType().index()),
-                            codec_name = str(trackDescriptor.getCodec().identifier()),
+                            codec_name = str(trackDescriptor.getFormatDescriptor().identifier()),
                             index = int(trackDescriptor.getIndex()),
                             source_index = int(trackDescriptor.getSourceIndex()),
                             disposition_flags = int(TrackDisposition.toFlags(trackDescriptor.getDispositionSet())),
@@ -72,6 +74,8 @@ class TrackController():
 
         if type(trackDescriptor) is not TrackDescriptor:
             raise TypeError('TrackController.updateTrack(): Argument trackDescriptor is required to be of type TrackDescriptor')
+        if trackDescriptor.getType() == TrackType.ATTACHMENT:
+            return False
 
         try:
             s = self.Session()
@@ -82,7 +86,7 @@ class TrackController():
                 track.index = int(trackDescriptor.getIndex())
 
                 track.track_type = int(trackDescriptor.getType().index())
-                track.codec_name = str(trackDescriptor.getCodec().identifier())
+                track.codec_name = str(trackDescriptor.getFormatDescriptor().identifier())
                 track.audio_layout = int(trackDescriptor.getAudioLayout().index())
 
                 track.disposition_flags = int(TrackDisposition.toFlags(trackDescriptor.getDispositionSet()))

src/ffx/track_delete_screen.py

@@ -67,6 +67,9 @@ class TrackDeleteScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         self.query_one("#subindexlabel", Static).update(str(self.__trackDescriptor.getSubIndex()))
         self.query_one("#patternlabel", Static).update(str(self.__trackDescriptor.getPatternId()))
         self.query_one("#languagelabel", Static).update(str(self.__trackDescriptor.getLanguage().label()))

src/ffx/track_descriptor.py

@@ -1,5 +1,6 @@
 from typing import Self
 
+from .attachment_format import AttachmentFormat
 from .iso_language import IsoLanguage
 from .track_type import TrackType
 from .audio_layout import AudioLayout
@@ -26,6 +27,7 @@ class TrackDescriptor:
 
     TRACK_TYPE_KEY = "track_type"
     CODEC_KEY = "codec_name"
+    ATTACHMENT_FORMAT_KEY = "attachment_format"
     AUDIO_LAYOUT_KEY = "audio_layout"
 
     FFPROBE_INDEX_KEY = "index"
@@ -110,15 +112,6 @@ class TrackDescriptor:
         else:
             self.__trackType = TrackType.UNKNOWN
 
-        if TrackDescriptor.CODEC_KEY in kwargs.keys():
-            if type(kwargs[TrackDescriptor.CODEC_KEY]) is not TrackCodec:
-                raise TypeError(
-                    f"TrackDesciptor.__init__(): Argument {TrackDescriptor.CODEC_KEY} is required to be of type TrackCodec"
-                )
-            self.__trackCodec = kwargs[TrackDescriptor.CODEC_KEY]
-        else:
-            self.__trackCodec = TrackCodec.UNKNOWN
-
         if TrackDescriptor.TAGS_KEY in kwargs.keys():
             if type(kwargs[TrackDescriptor.TAGS_KEY]) is not dict:
                 raise TypeError(
@@ -151,6 +144,34 @@ class TrackDescriptor:
         else:
             self.__audioLayout = AudioLayout.LAYOUT_UNDEFINED
 
+        self.__trackCodec = TrackCodec.UNKNOWN
+        self.__attachmentFormat = AttachmentFormat.UNKNOWN
+
+        if self.__trackType == TrackType.ATTACHMENT:
+            if TrackDescriptor.ATTACHMENT_FORMAT_KEY in kwargs.keys():
+                if type(kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY]) is not AttachmentFormat:
+                    raise TypeError(
+                        f"TrackDesciptor.__init__(): Argument {TrackDescriptor.ATTACHMENT_FORMAT_KEY} is required to be of type AttachmentFormat"
+                    )
+                self.__attachmentFormat = kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY]
+            elif TrackDescriptor.CODEC_KEY in kwargs.keys():
+                legacyCodec = kwargs[TrackDescriptor.CODEC_KEY]
+                if type(legacyCodec) is AttachmentFormat:
+                    self.__attachmentFormat = legacyCodec
+                elif type(legacyCodec) is TrackCodec:
+                    self.__attachmentFormat = AttachmentFormat.fromTrackCodec(legacyCodec)
+                else:
+                    raise TypeError(
+                        f"TrackDesciptor.__init__(): Argument {TrackDescriptor.CODEC_KEY} is required to be of type TrackCodec for legacy attachment compatibility"
+                    )
+        else:
+            if TrackDescriptor.CODEC_KEY in kwargs.keys():
+                if type(kwargs[TrackDescriptor.CODEC_KEY]) is not TrackCodec:
+                    raise TypeError(
+                        f"TrackDesciptor.__init__(): Argument {TrackDescriptor.CODEC_KEY} is required to be of type TrackCodec"
+                    )
+                self.__trackCodec = kwargs[TrackDescriptor.CODEC_KEY]
+
     @classmethod
     def fromFfprobe(cls, streamObj, subIndex: int = -1):
         """Processes ffprobe stream data as array with elements according to the following example
@@ -215,7 +236,12 @@ class TrackDescriptor:
 
             kwargs[TrackDescriptor.TRACK_TYPE_KEY] = trackType
 
-            kwargs[TrackDescriptor.CODEC_KEY] = TrackCodec.identify(streamObj[TrackDescriptor.FFPROBE_CODEC_KEY])
+            if trackType == TrackType.ATTACHMENT:
+                kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY] = AttachmentFormat.identifyFfprobeStream(streamObj)
+            else:
+                kwargs[TrackDescriptor.CODEC_KEY] = TrackCodec.identify(
+                    streamObj.get(TrackDescriptor.FFPROBE_CODEC_KEY)
+                )
 
             kwargs[TrackDescriptor.DISPOSITION_SET_KEY] = (
                 {
@@ -277,6 +303,14 @@ class TrackDescriptor:
     def getCodec(self) -> TrackCodec:
         return self.__trackCodec
 
+    def getAttachmentFormat(self) -> AttachmentFormat:
+        return self.__attachmentFormat
+
+    def getFormatDescriptor(self):
+        if self.__trackType == TrackType.ATTACHMENT:
+            return self.__attachmentFormat
+        return self.__trackCodec
+
     def getLanguage(self):
         if "language" in self.__trackTags.keys():
             return IsoLanguage.findThreeLetter(self.__trackTags["language"])
@@ -353,12 +387,16 @@ class TrackDescriptor:
             TrackDescriptor.SOURCE_INDEX_KEY: int(self.__sourceIndex),
             TrackDescriptor.SUB_INDEX_KEY: int(self.__subIndex),
             TrackDescriptor.TRACK_TYPE_KEY: self.__trackType,
-            TrackDescriptor.CODEC_KEY: self.__trackCodec,
             TrackDescriptor.TAGS_KEY: dict(self.__trackTags),
             TrackDescriptor.DISPOSITION_SET_KEY: set(self.__dispositionSet),
             TrackDescriptor.AUDIO_LAYOUT_KEY: self.__audioLayout,
         }
 
+        if self.__trackType == TrackType.ATTACHMENT:
+            kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY] = self.__attachmentFormat
+        else:
+            kwargs[TrackDescriptor.CODEC_KEY] = self.__trackCodec
+
         if context is not None:
             kwargs[TrackDescriptor.CONTEXT_KEY] = context
         elif self.__context:

src/ffx/track_details_screen.py

@@ -5,6 +5,7 @@ from textual.widgets import Header, Footer, Static, Button, SelectionList, Selec
 from textual.containers import Grid
 from textual.widgets._data_table import CellDoesNotExist
 
+from .attachment_format import AttachmentFormat
 from .audio_layout import AudioLayout
 from .iso_language import IsoLanguage
 from .tag_delete_screen import TagDeleteScreen
@@ -141,6 +142,7 @@ class TrackDetailsScreen(Screen):
         if self.__isNew:
             self.__trackType = trackType
             self.__trackCodec = TrackCodec.UNKNOWN
+            self.__attachmentFormat = AttachmentFormat.UNKNOWN
             self.__audioLayout = AudioLayout.LAYOUT_UNDEFINED
             self.__index = index
             self.__subIndex = subIndex
@@ -150,6 +152,7 @@ class TrackDetailsScreen(Screen):
         else:
             self.__trackType = trackDescriptor.getType()
             self.__trackCodec = trackDescriptor.getCodec()
+            self.__attachmentFormat = trackDescriptor.getAttachmentFormat()
             self.__audioLayout = trackDescriptor.getAudioLayout()
             self.__index = trackDescriptor.getIndex()
             self.__subIndex = trackDescriptor.getSubIndex()
@@ -236,6 +239,9 @@ class TrackDetailsScreen(Screen):
 
     def on_mount(self):
 
+        if getattr(self, 'context', {}).get('debug', False):
+            self.title = f"{self.app.title} - {self.__class__.__name__}"
+
         self.query_one("#index_label", Static).update(
             str(self.__index) if self.__index is not None else "-"
         )
@@ -430,6 +436,9 @@ class TrackDetailsScreen(Screen):
         if not isinstance(selectedTrackType, TrackType):
             selectedTrackType = TrackType.UNKNOWN
         kwargs[TrackDescriptor.TRACK_TYPE_KEY] = selectedTrackType
+        if selectedTrackType == TrackType.ATTACHMENT:
+            kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY] = self.__attachmentFormat
+        else:
             kwargs[TrackDescriptor.CODEC_KEY] = self.__trackCodec
 
         if selectedTrackType == TrackType.AUDIO:

tests/integration/subtrack_mapping/test_cli_bundle.py

@@ -18,6 +18,7 @@ from tests.support.ffx_bundle import (
     write_vtt,
 )
 
+from ffx.attachment_format import AttachmentFormat
 from ffx.track_type import TrackType
 
 try:
@@ -280,6 +281,72 @@ class SubtrackMappingBundleTests(unittest.TestCase):
         self.assertIn("non-existent source track #99", error_output)
         self.assertFalse(expected_output_path(self.workdir, source_filename).exists())
 
+    def test_styled_ass_source_preserves_current_font_attachments_when_pattern_count_differs(self):
+        source_filename = "styled_ass_s01e01.mkv"
+        source_path = create_source_fixture(
+            self.workdir,
+            source_filename,
+            [
+                SourceTrackSpec(TrackType.VIDEO, identity="video-0"),
+                SourceTrackSpec(TrackType.AUDIO, identity="audio-1", language="eng"),
+                SourceTrackSpec(
+                    TrackType.SUBTITLE,
+                    identity="subtitle-2",
+                    language="eng",
+                    subtitle_lines=("styled subtitle payload",),
+                ),
+                SourceTrackSpec(TrackType.ATTACHMENT, attachment_name="current.ttf"),
+            ],
+            subtitle_encoder="ass",
+        )
+
+        prepare_pattern_database(
+            self.database_path,
+            r"^styled_ass_(s[0-9]+e[0-9]+)\.mkv$",
+            [
+                PatternTrackSpec(index=0, source_index=0, track_type=TrackType.VIDEO),
+                PatternTrackSpec(index=1, source_index=1, track_type=TrackType.AUDIO),
+                PatternTrackSpec(index=2, source_index=2, track_type=TrackType.SUBTITLE),
+                PatternTrackSpec(
+                    index=3,
+                    source_index=3,
+                    track_type=TrackType.ATTACHMENT,
+                    attachment_format=AttachmentFormat.TTF,
+                ),
+                PatternTrackSpec(
+                    index=4,
+                    source_index=4,
+                    track_type=TrackType.ATTACHMENT,
+                    attachment_format=AttachmentFormat.TTF,
+                ),
+            ],
+        )
+
+        completed = run_ffx_convert(
+            self.workdir,
+            self.home_dir,
+            self.database_path,
+            "--video-encoder",
+            "copy",
+            "--no-tmdb",
+            "--no-prompt",
+            "--no-signature",
+            str(source_path),
+        )
+        self.assertCompleted(completed)
+        self.assertIn("Styled ASS subtitles", completed.stdout)
+
+        output_path = expected_output_path(self.workdir, source_filename)
+        streams = ffprobe_json(output_path)["streams"]
+
+        self.assertEqual(
+            [stream["codec_type"] for stream in streams],
+            ["video", "audio", "subtitle", "attachment"],
+        )
+        self.assertEqual(streams[2]["codec_name"], "ass")
+        self.assertEqual(streams[3]["codec_name"], "ttf")
+        self.assertEqual(get_tag(streams[3], "filename"), "current.ttf")
+
     def test_external_subtitle_file_replaces_payload_and_overrides_metadata(self):
         source_filename = "substitute_s01e01.mkv"
         self.write_config(
@@ -354,6 +421,59 @@ class SubtrackMappingBundleTests(unittest.TestCase):
         self.assertIn("external subtitle payload", extracted_subtitle)
         self.assertNotIn("embedded subtitle payload", extracted_subtitle)
 
+    def test_subtitle_directory_without_prefix_uses_source_basename(self):
+        source_filename = "basename_substitute.mkv"
+        subtitle_directory = self.workdir / "sidecars"
+        subtitle_directory.mkdir()
+        source_path = create_source_fixture(
+            self.workdir,
+            source_filename,
+            [
+                SourceTrackSpec(TrackType.VIDEO, identity="video-0"),
+                SourceTrackSpec(TrackType.AUDIO, identity="audio-1", language="eng"),
+                SourceTrackSpec(
+                    TrackType.SUBTITLE,
+                    identity="embedded-subtitle",
+                    language="eng",
+                    subtitle_lines=("embedded subtitle payload",),
+                ),
+            ],
+        )
+        write_vtt(
+            subtitle_directory / "basename_substitute_2_deu_DEF.vtt",
+            ("external subtitle payload",),
+        )
+
+        completed = run_ffx_convert(
+            self.workdir,
+            self.home_dir,
+            self.database_path,
+            "--video-encoder",
+            "copy",
+            "--no-pattern",
+            "--no-tmdb",
+            "--no-prompt",
+            "--no-signature",
+            "--subtitle-directory",
+            str(subtitle_directory),
+            str(source_path),
+        )
+        self.assertCompleted(completed)
+        self.assertIn("matched subtitle tracks #2", completed.stdout)
+        self.assertIn("Substituting subtitle stream #2", completed.stdout)
+
+        output_path = expected_output_path(self.workdir, source_filename)
+        subtitle_stream = [
+            stream
+            for stream in ffprobe_json(output_path)["streams"]
+            if stream["codec_type"] == "subtitle"
+        ][0]
+        self.assertEqual("deu", get_tag(subtitle_stream, "language"))
+
+        extracted_subtitle = extract_first_subtitle_text(self.workdir, output_path)
+        self.assertIn("external subtitle payload", extracted_subtitle)
+        self.assertNotIn("embedded subtitle payload", extracted_subtitle)
+
     def test_subtitle_prefix_uses_configured_base_directory_when_directory_is_omitted(self):
         source_filename = "substitute_default_s01e01.mkv"
         subtitle_prefix = "substitute_default"

tests/integration/test_cli_unmux.py

@@ -35,7 +35,13 @@ if pytest is not None:
 SRC_ROOT = Path(__file__).resolve().parents[2] / "src"
 
 
-def run_ffx_unmux(workdir: Path, home_dir: Path, database_path: Path, *args: str) -> subprocess.CompletedProcess[str]:
+def run_ffx_unmux(
+    workdir: Path,
+    home_dir: Path,
+    database_path: Path,
+    *args: str,
+    input_text: str | None = None,
+) -> subprocess.CompletedProcess[str]:
     env = os.environ.copy()
     env["HOME"] = str(home_dir)
     existing_pythonpath = env.get("PYTHONPATH", "")
@@ -50,7 +56,14 @@ def run_ffx_unmux(workdir: Path, home_dir: Path, database_path: Path, *args: str
         "unmux",
         *args,
     ]
-    return subprocess.run(command, cwd=workdir, env=env, capture_output=True, text=True)
+    return subprocess.run(
+        command,
+        cwd=workdir,
+        env=env,
+        capture_output=True,
+        input=input_text,
+        text=True,
+    )
 
 
 class UnmuxCliTests(unittest.TestCase):
@@ -161,6 +174,7 @@ class UnmuxCliTests(unittest.TestCase):
             self.home_dir,
             self.database_path,
             "--subtitles-only",
+            "--yes",
             "--label",
             "dball",
             str(source_path),

tests/prepare.sh

@@ -0,0 +1,471 @@
+#!/usr/bin/env bash
+
+set -u
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
+VENV_DIR="${FFX_TEST_VENV_DIR:-${ROOT_DIR}/.venv}"
+VENV_BIN_DIR="${VENV_DIR}/bin"
+VENV_PYTHON="${VENV_BIN_DIR}/python"
+VENV_PIP="${VENV_BIN_DIR}/pip"
+
+CHECK_ONLY=0
+READINESS_FAILURES=0
+INSTALL_FAILURES=0
+
+MISSING_REQUIRED_SYSTEM=()
+
+COLOR_RESET=""
+COLOR_GREEN=""
+COLOR_YELLOW=""
+COLOR_RED=""
+
+if [ -t 1 ]; then
+    COLOR_RESET="$(printf '\033[0m')"
+    COLOR_GREEN="$(printf '\033[32m')"
+    COLOR_YELLOW="$(printf '\033[33m')"
+    COLOR_RED="$(printf '\033[31m')"
+fi
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [--check] [--help]
+
+Prepare the repo-local FFX test environment at:
+  ${VENV_DIR}
+
+Actions:
+  - verify or install required system commands for tests
+  - create or reuse the repo-local test virtualenv
+  - install this repository into the venv with Python test and docs extras
+
+Options:
+  --check  Report readiness only. Do not create, install, or modify.
+  --help   Show this help text.
+
+Environment overrides:
+  FFX_TEST_VENV_DIR  Override the test virtualenv path. Defaults to ${ROOT_DIR}/.venv.
+
+Notes:
+  - This script prepares a project-local test environment, not the persistent user bundle.
+  - The persistent bundle setup remains owned by tools/setup.sh.
+EOF
+}
+
+status_ok() {
+    printf '%sok%s' "${COLOR_GREEN}" "${COLOR_RESET}"
+}
+
+status_warn() {
+    printf '%swarn%s' "${COLOR_YELLOW}" "${COLOR_RESET}"
+}
+
+status_fail() {
+    printf '%sfailed%s' "${COLOR_RED}" "${COLOR_RESET}"
+}
+
+report_component() {
+    local level="$1"
+    local label="$2"
+    local detail="$3"
+    local rendered_status=""
+
+    case "${level}" in
+        ok)
+            rendered_status="$(status_ok)"
+            ;;
+        warn)
+            rendered_status="$(status_warn)"
+            ;;
+        *)
+            rendered_status="$(status_fail)"
+            ;;
+    esac
+
+    printf '[%s] %s%s\n' "${rendered_status}" "${label}" "${detail:+: $detail}"
+}
+
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+check_python_venv_support() {
+    python3 -m venv --help >/dev/null 2>&1
+}
+
+check_system_command() {
+    command_exists "$1"
+}
+
+check_venv_python() {
+    [ -x "${VENV_PYTHON}" ]
+}
+
+check_venv_pip() {
+    check_venv_python && "${VENV_PIP}" --version >/dev/null 2>&1
+}
+
+check_venv_ffx() {
+    check_venv_python && "${VENV_PYTHON}" -m ffx version >/dev/null 2>&1
+}
+
+check_venv_pytest() {
+    check_venv_python && "${VENV_PYTHON}" -m pytest --version >/dev/null 2>&1
+}
+
+check_venv_sphinx() {
+    check_venv_python && "${VENV_BIN_DIR}/sphinx-build" --version >/dev/null 2>&1
+}
+
+check_venv_docs_packages() {
+    check_venv_python && "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
+import esbonio
+import sphinx
+import sphinx_rtd_theme
+PY
+}
+
+check_editable_install() {
+    check_venv_python && FFX_REPO_ROOT="${ROOT_DIR}" "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import ffx
+
+repo_root = Path(os.environ["FFX_REPO_ROOT"]).resolve()
+package_path = Path(ffx.__file__).resolve()
+
+raise SystemExit(0 if repo_root in package_path.parents else 1)
+PY
+}
+
+check_python_environment_ready() {
+    check_venv_python &&
+        check_venv_pip &&
+        check_venv_pytest &&
+        check_venv_sphinx &&
+        check_venv_docs_packages &&
+        check_venv_ffx &&
+        check_editable_install
+}
+
+command_detail() {
+    command -v "$1" || printf "command '%s' not found" "$1"
+}
+
+python_venv_detail() {
+    if check_python_venv_support; then
+        printf 'python3 -m venv is available'
+    else
+        printf 'python3 venv support is unavailable'
+    fi
+}
+
+venv_python_detail() {
+    if check_venv_python; then
+        printf '%s' "${VENV_PYTHON}"
+    else
+        printf 'missing %s' "${VENV_PYTHON}"
+    fi
+}
+
+venv_pip_detail() {
+    if check_venv_pip; then
+        "${VENV_PIP}" --version
+    else
+        printf 'missing pip in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_ffx_detail() {
+    if check_venv_ffx; then
+        printf 'ffx import and CLI entry are available'
+    else
+        printf 'ffx is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_pytest_detail() {
+    if check_venv_pytest; then
+        "${VENV_PYTHON}" -m pytest --version 2>/dev/null | head -n 1
+    else
+        printf 'pytest is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_sphinx_detail() {
+    if check_venv_sphinx; then
+        "${VENV_BIN_DIR}/sphinx-build" --version 2>&1
+    else
+        printf 'sphinx-build is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_docs_packages_detail() {
+    if check_venv_docs_packages; then
+        printf 'Sphinx, Read the Docs theme, and Esbonio packages are importable'
+    else
+        printf 'one or more docs packages are missing in %s' "${VENV_DIR}"
+    fi
+}
+
+editable_install_detail() {
+    if check_editable_install; then
+        printf 'ffx resolves from %s' "${ROOT_DIR}"
+    else
+        printf 'ffx does not resolve from the project source tree'
+    fi
+}
+
+report_required_command() {
+    local label="$1"
+    local command_name="$2"
+
+    if check_system_command "${command_name}"; then
+        report_component ok "${label}" "$(command_detail "${command_name}")"
+    else
+        report_component failed "${label}" "$(command_detail "${command_name}")"
+        MISSING_REQUIRED_SYSTEM+=("${command_name}")
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+}
+
+print_system_status() {
+    MISSING_REQUIRED_SYSTEM=()
+
+    echo "System toolchain status:"
+    report_required_command "git" "git"
+    report_required_command "python3" "python3"
+
+    if check_system_command "python3" && check_python_venv_support; then
+        report_component ok "python3 venv" "$(python_venv_detail)"
+    else
+        report_component failed "python3 venv" "$(python_venv_detail)"
+        MISSING_REQUIRED_SYSTEM+=("python3-venv")
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    report_required_command "ffmpeg" "ffmpeg"
+    report_required_command "ffprobe" "ffprobe"
+    report_required_command "cpulimit" "cpulimit"
+}
+
+print_python_status() {
+    echo "Repo test and docs virtualenv status:"
+
+    if check_venv_python; then
+        report_component ok "test virtualenv" "$(venv_python_detail)"
+    else
+        report_component failed "test virtualenv" "$(venv_python_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_pip; then
+        report_component ok "test pip" "$(venv_pip_detail)"
+    else
+        report_component failed "test pip" "$(venv_pip_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_pytest; then
+        report_component ok "test pytest" "$(venv_pytest_detail)"
+    else
+        report_component failed "test pytest" "$(venv_pytest_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_sphinx; then
+        report_component ok "docs sphinx" "$(venv_sphinx_detail)"
+    else
+        report_component failed "docs sphinx" "$(venv_sphinx_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_docs_packages; then
+        report_component ok "docs packages" "$(venv_docs_packages_detail)"
+    else
+        report_component failed "docs packages" "$(venv_docs_packages_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_ffx; then
+        report_component ok "test ffx" "$(venv_ffx_detail)"
+    else
+        report_component failed "test ffx" "$(venv_ffx_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_editable_install; then
+        report_component ok "editable source" "$(editable_install_detail)"
+    else
+        report_component failed "editable source" "$(editable_install_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+}
+
+print_status_report() {
+    READINESS_FAILURES=0
+
+    print_system_status
+    echo
+    print_python_status
+}
+
+detect_package_manager() {
+    if command_exists apt-get; then
+        printf 'apt-get\n'
+        return 0
+    fi
+    if command_exists pacman; then
+        printf 'pacman\n'
+        return 0
+    fi
+    return 1
+}
+
+run_root_command() {
+    if [ "${EUID}" -eq 0 ]; then
+        "$@"
+    elif command_exists sudo; then
+        sudo -n "$@"
+    else
+        return 1
+    fi
+}
+
+install_system_requirements() {
+    local package_manager
+
+    if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -eq 0 ]; then
+        return 0
+    fi
+
+    if ! package_manager="$(detect_package_manager)"; then
+        printf 'No supported package manager found for automatic system preparation.\n' >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    case "${package_manager}" in
+        apt-get)
+            printf 'Installing required system dependencies via apt-get...\n'
+            if ! run_root_command apt-get update; then
+                printf 'apt-get update failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            if ! run_root_command apt-get install -y git python3 python3-venv ffmpeg cpulimit; then
+                printf 'apt-get install failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            ;;
+        pacman)
+            printf 'Installing required system dependencies via pacman...\n'
+            if ! run_root_command pacman -Sy --noconfirm git python ffmpeg cpulimit; then
+                printf 'pacman install failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            ;;
+    esac
+
+    return 0
+}
+
+ensure_test_venv() {
+    if ! check_venv_python; then
+        printf 'Creating repo test virtualenv at %s...\n' "${VENV_DIR}"
+        if ! python3 -m venv "${VENV_DIR}"; then
+            printf 'Failed to create test virtualenv at %s.\n' "${VENV_DIR}" >&2
+            INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+            return 1
+        fi
+    fi
+
+    if ! check_venv_pip; then
+        printf 'Missing pip in %s.\n' "${VENV_DIR}" >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    printf 'Installing FFX package with test and docs extras into %s...\n' "${VENV_DIR}"
+    if ! (
+        cd "${ROOT_DIR}" &&
+        "${VENV_PIP}" install --editable '.[test,docs]'
+    ); then
+        printf 'Failed to install FFX package with test and docs extras into %s.\n' "${VENV_DIR}" >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    return 0
+}
+
+parse_args() {
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+            --check)
+                CHECK_ONLY=1
+                ;;
+            --help|-h)
+                usage
+                exit 0
+                ;;
+            *)
+                printf 'Unknown option: %s\n\n' "$1" >&2
+                usage >&2
+                exit 2
+                ;;
+        esac
+        shift
+    done
+}
+
+main() {
+    parse_args "$@"
+
+    print_status_report
+
+    if [ "${CHECK_ONLY}" -eq 0 ]; then
+        if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -gt 0 ]; then
+            echo
+            install_system_requirements
+        fi
+
+        if check_python_environment_ready; then
+            echo
+            report_component ok "Python package install" "repo test and docs virtualenv is already ready"
+        elif check_system_command "python3" && check_python_venv_support; then
+            echo
+            ensure_test_venv
+        fi
+
+        echo
+        print_status_report
+    fi
+
+    echo
+    if [ "${INSTALL_FAILURES}" -gt 0 ]; then
+        echo "One or more test preparation steps failed; see the status checks above." >&2
+        exit 1
+    fi
+
+    if [ "${READINESS_FAILURES}" -gt 0 ]; then
+        if [ "${CHECK_ONLY}" -eq 1 ]; then
+            echo "The FFX test and docs environment is incomplete." >&2
+        else
+            echo "Required test or docs components are still missing after preparation." >&2
+        fi
+        exit 1
+    fi
+
+    if [ "${CHECK_ONLY}" -eq 1 ]; then
+        echo "The FFX test and docs environment is ready."
+    else
+        echo "The FFX test and docs environment is prepared."
+    fi
+}
+
+main "$@"

tests/support/ffx_bundle.py

@@ -7,6 +7,7 @@ import os
 from pathlib import Path
 import subprocess
 import sys
+from functools import lru_cache
 from typing import Mapping
 
 
@@ -17,6 +18,7 @@ if str(SRC_ROOT) not in sys.path:
     sys.path.insert(0, str(SRC_ROOT))
 
 
+from ffx.attachment_format import AttachmentFormat
 from ffx.audio_layout import AudioLayout
 from ffx.database import databaseContext
 from ffx.pattern_controller import PatternController
@@ -55,6 +57,7 @@ class PatternTrackSpec:
     tags: Mapping[str, str] = field(default_factory=dict)
     dispositions: tuple[TrackDisposition, ...] = ()
     audio_layout: AudioLayout = AudioLayout.LAYOUT_STEREO
+    attachment_format: AttachmentFormat = AttachmentFormat.UNKNOWN
 
 
 def make_logger(name: str) -> logging.Logger:
@@ -95,8 +98,69 @@ def write_vtt(path: Path, lines: tuple[str, ...]) -> Path:
     return path
 
 
-def create_source_fixture(workdir: Path, filename: str, tracks: list[SourceTrackSpec], duration_seconds: int = 1) -> Path:
+@lru_cache(maxsize=None)
+def _ffmpeg_encoder_is_available(encoder_name: str) -> bool:
+    completed = subprocess.run(
+        ["ffmpeg", "-encoders"],
+        capture_output=True,
+        text=True,
+    )
+    if completed.returncode != 0:
+        return False
+
+    encoder_label = str(encoder_name).strip()
+    for line in completed.stdout.splitlines():
+        if not line.startswith(" "):
+            continue
+
+        tokens = line.split(maxsplit=2)
+        if len(tokens) >= 2 and tokens[1] == encoder_label:
+            return True
+
+    return False
+
+
+def _resolve_fixture_video_encoder(
+    video_encoder: str,
+    video_encoder_options: tuple[str, ...],
+) -> tuple[str, tuple[str, ...]]:
+    if video_encoder != "libx264":
+        return video_encoder, video_encoder_options
+
+    if _ffmpeg_encoder_is_available("libx264"):
+        return video_encoder, video_encoder_options
+
+    if _ffmpeg_encoder_is_available("libopenh264"):
+        # Keep fixture generation software-based when libx264 is missing.
+        return "libopenh264", ("-pix_fmt", "yuv420p")
+
+    return video_encoder, video_encoder_options
+
+
+def create_source_fixture(
+    workdir: Path,
+    filename: str,
+    tracks: list[SourceTrackSpec],
+    duration_seconds: int = 1,
+    *,
+    video_encoder: str = "libx264",
+    video_encoder_options: tuple[str, ...] = (
+        "-preset",
+        "ultrafast",
+        "-crf",
+        "35",
+        "-pix_fmt",
+        "yuv420p",
+    ),
+    audio_encoder: str = "aac",
+    audio_encoder_options: tuple[str, ...] = ("-b:a", "48k"),
+    subtitle_encoder: str = "webvtt",
+) -> Path:
     output_path = workdir / filename
+    video_encoder, video_encoder_options = _resolve_fixture_video_encoder(
+        video_encoder,
+        video_encoder_options,
+    )
 
     has_video = any(track.track_type == TrackType.VIDEO for track in tracks)
     has_audio = any(track.track_type == TrackType.AUDIO for track in tracks)
@@ -189,21 +253,16 @@ def create_source_fixture(workdir: Path, filename: str, tracks: list[SourceTrack
     command += map_tokens
     command += metadata_tokens
     command += disposition_tokens
+    if has_video:
+        command += ["-c:v", video_encoder] + list(video_encoder_options)
+
+    if has_audio:
+        command += ["-c:a", audio_encoder] + list(audio_encoder_options)
+
+    if subtitle_input_indices:
+        command += ["-c:s", subtitle_encoder]
+
     command += [
-        "-c:v",
-        "libx264",
-        "-preset",
-        "ultrafast",
-        "-crf",
-        "35",
-        "-pix_fmt",
-        "yuv420p",
-        "-c:a",
-        "aac",
-        "-b:a",
-        "48k",
-        "-c:s",
-        "webvtt",
         "-t",
         str(duration_seconds),
         "-shortest",
@@ -242,6 +301,8 @@ def prepare_pattern_database(database_path: Path, filename_pattern: str, track_s
             }
             if track.track_type == TrackType.AUDIO:
                 kwargs[TrackDescriptor.AUDIO_LAYOUT_KEY] = track.audio_layout
+            if track.track_type == TrackType.ATTACHMENT:
+                kwargs[TrackDescriptor.ATTACHMENT_FORMAT_KEY] = track.attachment_format
             track_descriptors.append(TrackDescriptor(**kwargs))
 
         pattern_id = PatternController(context).savePatternSchema(

tests/unit/test_cli_convert_diagnostics.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+
+from ffx import cli  # noqa: E402
+from ffx.diagnostics import FfmpegSkipFileWarning, recordUnremediedIssue  # noqa: E402
+from ffx.logging_utils import get_ffx_logger  # noqa: E402
+
+
+class _FakeMediaDescriptor:
+    def getVideoTracks(self):
+        return []
+
+    def getAudioTracks(self):
+        return []
+
+    def getSubtitleTracks(self):
+        return []
+
+    def getAttachmentTracks(self):
+        return []
+
+    def applyOverrides(self, overrides):
+        return None
+
+
+class _FakeFileProperties:
+    def __init__(self, context, source_path):
+        self.source_path = source_path
+
+    def getShowId(self):
+        return -1
+
+    def getSeason(self):
+        return -1
+
+    def getEpisode(self):
+        return -1
+
+    def getMediaDescriptor(self):
+        return _FakeMediaDescriptor()
+
+    def getPattern(self):
+        return None
+
+
+class _FakeShiftedSeasonController:
+    def __init__(self, context):
+        self.context = context
+
+    def shiftSeason(self, show_id, season, episode, patternId=None):
+        return season, episode
+
+
+class _FakeShowController:
+    def __init__(self, context):
+        self.context = context
+
+    def getShowDescriptor(self, show_id):
+        return None
+
+
+class _FakeFfxController:
+    calls: list[str] = []
+    mode = "skip_first"
+
+    def __init__(self, context, *args, **kwargs):
+        self.context = context
+
+    def runJob(self, sourcePath, *args, **kwargs):
+        self.calls.append(sourcePath)
+        if self.mode == "clean":
+            return
+
+        if self.mode == "warn_unhandled" and sourcePath.endswith("episode1.avi"):
+            recordUnremediedIssue(
+                self.context,
+                sourcePath,
+                "unhandled-warning",
+            )
+            return
+
+        if self.mode == "skip_first" and sourcePath.endswith("episode1.avi"):
+            message = (
+                f"Skipping file {sourcePath}: ffmpeg still reported unset packet "
+                + "timestamps after retry with -fflags +genpts."
+            )
+            recordUnremediedIssue(
+                self.context,
+                sourcePath,
+                "retry-with-generated-pts",
+            )
+            self.context["logger"].warning(message)
+            raise FfmpegSkipFileWarning(message)
+
+
+class ConvertDiagnosticCliTests(unittest.TestCase):
+    def setUp(self):
+        logger = get_ffx_logger()
+        for handler in list(logger.handlers):
+            logger.removeHandler(handler)
+            try:
+                handler.close()
+            except Exception:
+                pass
+
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.home_dir = Path(self.tempdir.name) / "home"
+        self.home_dir.mkdir()
+        self.database_path = Path(self.tempdir.name) / "test.db"
+        self.source_dir = Path(self.tempdir.name) / "source"
+        self.source_dir.mkdir()
+        self.source_one = self.source_dir / "episode1.avi"
+        self.source_two = self.source_dir / "episode2.avi"
+        self.source_one.write_bytes(b"one")
+        self.source_two.write_bytes(b"two")
+        _FakeFfxController.calls = []
+        _FakeFfxController.mode = "skip_first"
+
+    def tearDown(self):
+        self.tempdir.cleanup()
+
+    def test_convert_continues_after_skipping_one_file_due_to_ffmpeg_diagnostic(self):
+        runner = CliRunner()
+
+        with (
+            patch("ffx.file_properties.FileProperties", _FakeFileProperties),
+            patch("ffx.ffx_controller.FfxController", _FakeFfxController),
+            patch(
+                "ffx.shifted_season_controller.ShiftedSeasonController",
+                _FakeShiftedSeasonController,
+            ),
+            patch("ffx.show_controller.ShowController", _FakeShowController),
+        ):
+            result = runner.invoke(
+                cli.ffx,
+                [
+                    "--database-file",
+                    str(self.database_path),
+                    "convert",
+                    "--no-tmdb",
+                    "--no-pattern",
+                    str(self.source_one),
+                    str(self.source_two),
+                ],
+                env={**os.environ, "HOME": str(self.home_dir)},
+            )
+
+        self.assertEqual(0, result.exit_code, result.output)
+        self.assertEqual(
+            [str(self.source_one), str(self.source_two)],
+            _FakeFfxController.calls,
+        )
+        self.assertIn("Skipping file", result.output)
+        self.assertIn("-fflags +genpts", result.output)
+        self.assertIn("Files with ffmpeg findings that require review:", result.output)
+        self.assertIn(
+            "episode1.avi: retry-with-generated-pts",
+            result.output,
+        )
+
+    def test_convert_prints_clean_summary_when_no_unremedied_issues_were_seen(self):
+        runner = CliRunner()
+        _FakeFfxController.mode = "clean"
+
+        with (
+            patch("ffx.file_properties.FileProperties", _FakeFileProperties),
+            patch("ffx.ffx_controller.FfxController", _FakeFfxController),
+            patch(
+                "ffx.shifted_season_controller.ShiftedSeasonController",
+                _FakeShiftedSeasonController,
+            ),
+            patch("ffx.show_controller.ShowController", _FakeShowController),
+        ):
+            result = runner.invoke(
+                cli.ffx,
+                [
+                    "--database-file",
+                    str(self.database_path),
+                    "convert",
+                    "--no-tmdb",
+                    "--no-pattern",
+                    str(self.source_one),
+                    str(self.source_two),
+                ],
+                env={**os.environ, "HOME": str(self.home_dir)},
+            )
+
+        self.assertEqual(0, result.exit_code, result.output)
+        self.assertIn(
+            "All files converted with no issues.",
+            result.output,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_lazy_imports.py

@@ -168,6 +168,40 @@ class CliLazyImportTests(unittest.TestCase):
             result["modules"],
         )
 
+    def test_root_debug_flag_parses_without_loading_runtime_modules(self):
+        result = self.run_python(
+            textwrap.dedent(
+                f"""
+                import json
+                import sys
+
+                sys.path.insert(0, {str(SRC_ROOT)!r})
+
+                import ffx.cli
+
+                context = ffx.cli.ffx.make_context(
+                    "ffx",
+                    ["--debug", "help"],
+                    resilient_parsing=True,
+                )
+
+                print(json.dumps({{
+                    "debug": context.params["debug"],
+                    "modules": {{
+                        module_name: module_name in sys.modules
+                        for module_name in {HEAVY_MODULES!r}
+                    }},
+                }}))
+                """
+            )
+        )
+
+        self.assertTrue(result["debug"])
+        self.assertTrue(
+            all(not is_loaded for is_loaded in result["modules"].values()),
+            result["modules"],
+        )
+
     def test_convert_cut_option_supports_flag_duration_and_start_duration_forms(self):
         result = self.run_python(
             textwrap.dedent(
@@ -229,6 +263,47 @@ class CliLazyImportTests(unittest.TestCase):
             result["modules"],
         )
 
+    def test_convert_copy_flags_parse_without_loading_runtime_modules(self):
+        result = self.run_python(
+            textwrap.dedent(
+                f"""
+                import click
+                import json
+                import sys
+
+                sys.path.insert(0, {str(SRC_ROOT)!r})
+
+                import ffx.cli
+
+                context = ffx.cli.convert.make_context(
+                    "convert",
+                    ["--copy-video", "--copy-audio"],
+                    resilient_parsing=True,
+                )
+                help_output = ffx.cli.convert.get_help(click.Context(ffx.cli.convert))
+
+                print(json.dumps({{
+                    "copy_video": context.params["copy_video"],
+                    "copy_audio": context.params["copy_audio"],
+                    "output": help_output,
+                    "modules": {{
+                        module_name: module_name in sys.modules
+                        for module_name in {HEAVY_MODULES!r}
+                    }},
+                }}))
+                """
+            )
+        )
+
+        self.assertTrue(result["copy_video"])
+        self.assertTrue(result["copy_audio"])
+        self.assertIn("--copy-video", result["output"])
+        self.assertIn("--copy-audio", result["output"])
+        self.assertTrue(
+            all(not is_loaded for is_loaded in result["modules"].values()),
+            result["modules"],
+        )
+
     def test_edit_command_avoids_database_bootstrap(self):
         result = self.run_python(
             textwrap.dedent(

tests/unit/test_cli_subtitle_directory.py

@@ -6,7 +6,9 @@ from pathlib import Path
 import sys
 import tempfile
 import unittest
+from unittest.mock import patch
 
+import click
 from click.testing import CliRunner
 
 
@@ -17,6 +19,10 @@ if str(SRC_ROOT) not in sys.path:
 
 
 from ffx import cli  # noqa: E402
+from ffx.logging_utils import get_ffx_logger  # noqa: E402
+from ffx.media_descriptor import MediaDescriptor  # noqa: E402
+from ffx.track_descriptor import TrackDescriptor  # noqa: E402
+from ffx.track_type import TrackType  # noqa: E402
 
 
 class SubtitleDirectoryCliTests(unittest.TestCase):
@@ -48,6 +54,35 @@ class SubtitleDirectoryCliTests(unittest.TestCase):
             env={**os.environ, "HOME": str(self.home_dir)},
         )
 
+    def make_subtitle_descriptor(self, indices=(2, 3, 4)) -> MediaDescriptor:
+        return MediaDescriptor(
+            context={"logger": get_ffx_logger()},
+            track_descriptors=[
+                TrackDescriptor(
+                    index=index,
+                    source_index=index,
+                    sub_index=subIndex,
+                    track_type=TrackType.SUBTITLE,
+                )
+                for subIndex, index in enumerate(indices)
+            ],
+        )
+
+    def make_import_context(
+        self,
+        subtitleDirectory: Path,
+        noPrompt: bool,
+        yes: bool = False,
+    ) -> dict:
+        return {
+            "subtitle_match_source_basename": True,
+            "subtitle_directory": str(subtitleDirectory),
+            "subtitle_prefix": "",
+            "subtitle_extension": "vtt",
+            "no_prompt": noPrompt,
+            "yes": yes,
+        }
+
     def test_subtitle_prefix_without_directory_or_default_fails(self):
         result = self.invoke_convert("--subtitle-prefix", "dball")
 
@@ -79,6 +114,153 @@ class SubtitleDirectoryCliTests(unittest.TestCase):
 
         self.assertEqual(0, result.exit_code, result.output)
 
+    def test_explicit_directory_without_prefix_enables_basename_matching(self):
+        explicitSubtitleDirectory = self.home_dir / "manual-subtitles"
+        explicitSubtitleDirectory.mkdir(parents=True, exist_ok=True)
+
+        enabled, directory, prefix, matchBasename = cli.resolveSubtitleImportOptions(
+            {},
+            str(explicitSubtitleDirectory),
+            "",
+        )
+
+        self.assertTrue(enabled)
+        self.assertEqual(str(explicitSubtitleDirectory), directory)
+        self.assertEqual("", prefix)
+        self.assertTrue(matchBasename)
+
+    def test_subtitle_extension_accepts_optional_leading_dot(self):
+        self.assertEqual("mkv", cli.normalizeSubtitleExtension(None, None, "mkv"))
+        self.assertEqual("mkv", cli.normalizeSubtitleExtension(None, None, ".mkv"))
+
+    def test_subtitle_extension_rejects_multiple_leading_dots(self):
+        with self.assertRaises(click.BadParameter):
+            cli.normalizeSubtitleExtension(None, None, "..mkv")
+
+    def test_complete_basename_set_does_not_prompt(self):
+        subtitleDirectory = self.home_dir / "complete-subtitles"
+        subtitleDirectory.mkdir()
+        for basename in (
+            "A2_t01_2_deu_DEF",
+            "A2_t01_3_eng",
+            "A2_t01_4_eng",
+        ):
+            (subtitleDirectory / f"{basename}.vtt").write_text(
+                "WEBVTT\n\n",
+                encoding="utf-8",
+            )
+        descriptor = self.make_subtitle_descriptor()
+        context = self.make_import_context(subtitleDirectory, noPrompt=True)
+
+        with patch("ffx.cli.click.confirm") as mockedConfirm:
+            result = cli.importExternalSubtitles(
+                context,
+                descriptor,
+                "A2_t01",
+                -1,
+                -1,
+            )
+
+        self.assertEqual([], result["missing_track_indices"])
+        mockedConfirm.assert_not_called()
+
+    def test_incomplete_basename_set_fails_with_no_prompt(self):
+        descriptor = self.make_subtitle_descriptor()
+        subtitleDirectory = self.home_dir / "partial-subtitles"
+        subtitleDirectory.mkdir()
+        (subtitleDirectory / "episode_2_deu.vtt").write_text(
+            "WEBVTT\n\n",
+            encoding="utf-8",
+        )
+        context = self.make_import_context(subtitleDirectory, noPrompt=True)
+
+        with patch("ffx.cli.click.confirm") as mockedConfirm:
+            with self.assertRaisesRegex(click.ClickException, "--no-prompt is set"):
+                cli.importExternalSubtitles(
+                    context,
+                    descriptor,
+                    "episode",
+                    -1,
+                    -1,
+                )
+
+        mockedConfirm.assert_not_called()
+
+    def test_incomplete_basename_set_can_be_confirmed(self):
+        descriptor = self.make_subtitle_descriptor()
+        subtitleDirectory = self.home_dir / "partial-subtitles"
+        subtitleDirectory.mkdir()
+        (subtitleDirectory / "episode_2_deu.vtt").write_text(
+            "WEBVTT\n\n",
+            encoding="utf-8",
+        )
+        context = self.make_import_context(subtitleDirectory, noPrompt=False)
+
+        with patch("ffx.cli.click.confirm", return_value=True) as mockedConfirm:
+            result = cli.importExternalSubtitles(
+                context,
+                descriptor,
+                "episode",
+                -1,
+                -1,
+            )
+
+        self.assertEqual([3, 4], result["missing_track_indices"])
+        mockedConfirm.assert_called_once()
+
+    def test_incomplete_basename_set_with_yes_does_not_prompt(self):
+        descriptor = self.make_subtitle_descriptor()
+        subtitleDirectory = self.home_dir / "partial-subtitles"
+        subtitleDirectory.mkdir()
+        (subtitleDirectory / "episode_2_deu.vtt").write_text(
+            "WEBVTT\n\n",
+            encoding="utf-8",
+        )
+        context = self.make_import_context(
+            subtitleDirectory,
+            noPrompt=False,
+            yes=True,
+        )
+
+        with patch("ffx.cli.click.confirm") as mockedConfirm:
+            result = cli.importExternalSubtitles(
+                context,
+                descriptor,
+                "episode",
+                -1,
+                -1,
+            )
+
+        self.assertEqual([2], result["imported_track_indices"])
+        self.assertEqual([3, 4], result["missing_track_indices"])
+        mockedConfirm.assert_not_called()
+
+    def test_yes_takes_precedence_over_no_prompt_for_incomplete_set(self):
+        descriptor = self.make_subtitle_descriptor()
+        subtitleDirectory = self.home_dir / "partial-subtitles"
+        subtitleDirectory.mkdir()
+        (subtitleDirectory / "episode_2_deu.vtt").write_text(
+            "WEBVTT\n\n",
+            encoding="utf-8",
+        )
+        context = self.make_import_context(
+            subtitleDirectory,
+            noPrompt=True,
+            yes=True,
+        )
+
+        with patch("ffx.cli.click.confirm") as mockedConfirm:
+            result = cli.importExternalSubtitles(
+                context,
+                descriptor,
+                "episode",
+                -1,
+                -1,
+            )
+
+        self.assertEqual([3, 4], result["missing_track_indices"])
+        mockedConfirm.assert_not_called()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_cli_unmux_output_directory.py

@@ -4,6 +4,7 @@ from pathlib import Path
 import sys
 import tempfile
 import unittest
+from unittest.mock import patch
 
 import click
 
@@ -42,7 +43,7 @@ class UnmuxOutputDirectoryTests(unittest.TestCase):
         self.assertEqual(str(Path(tempdir) / "subtitles" / "dball"), resolved_output_directory)
         self.assertTrue(should_create)
 
-    def test_explicit_output_directory_keeps_existing_behavior(self):
+    def test_explicit_output_directory_requires_directory(self):
         with tempfile.TemporaryDirectory() as tempdir:
             context = {
                 "config": StaticConfig(str(Path(tempdir) / "subtitles")),
@@ -57,7 +58,7 @@ class UnmuxOutputDirectoryTests(unittest.TestCase):
             )
 
         self.assertEqual(explicit_output_directory, resolved_output_directory)
-        self.assertFalse(should_create)
+        self.assertTrue(should_create)
 
     def test_subtitles_only_without_label_keeps_existing_behavior(self):
         context = {
@@ -89,6 +90,110 @@ class UnmuxOutputDirectoryTests(unittest.TestCase):
 
         self.assertIn("subtitlesDirectory default", str(caught.exception))
 
+    def test_missing_output_directory_can_be_confirmed_and_created_with_parents(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "missing" / "parents" / "manual"
+
+            with patch("ffx.cli.click.confirm", return_value=True) as mocked_confirm:
+                created = cli.ensureUnmuxOutputDirectory(
+                    {"dry_run": False},
+                    str(output_directory),
+                )
+
+            self.assertTrue(created)
+            self.assertTrue(output_directory.is_dir())
+            mocked_confirm.assert_called_once()
+
+    def test_tty_carriage_return_accepts_default_directory_creation(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "missing" / "manual"
+
+            with patch("ffx.cli.sys.stdin.isatty", return_value=True), patch(
+                "ffx.cli.click.getchar",
+                return_value="\r",
+            ) as mocked_getchar, patch("ffx.cli.click.confirm") as mocked_confirm:
+                created = cli.ensureUnmuxOutputDirectory(
+                    {"dry_run": False},
+                    str(output_directory),
+                )
+
+            self.assertTrue(created)
+            self.assertTrue(output_directory.is_dir())
+            mocked_getchar.assert_called_once()
+            mocked_confirm.assert_not_called()
+
+    def test_yes_creates_missing_output_directory_without_prompt(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "missing" / "parents" / "manual"
+
+            with patch("ffx.cli.click.confirm") as mocked_confirm:
+                created = cli.ensureUnmuxOutputDirectory(
+                    {"dry_run": False, "yes": True},
+                    str(output_directory),
+                )
+
+            self.assertTrue(created)
+            self.assertTrue(output_directory.is_dir())
+            mocked_confirm.assert_not_called()
+
+    def test_missing_output_directory_can_be_rejected(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "missing" / "manual"
+
+            with patch("ffx.cli.click.confirm", return_value=False) as mocked_confirm:
+                with self.assertRaises(click.ClickException) as caught:
+                    cli.ensureUnmuxOutputDirectory(
+                        {"dry_run": False},
+                        str(output_directory),
+                    )
+
+            self.assertFalse(output_directory.exists())
+            self.assertIn("aborted by user", str(caught.exception))
+            mocked_confirm.assert_called_once()
+
+    def test_existing_output_directory_does_not_prompt(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "manual"
+            output_directory.mkdir()
+
+            with patch("ffx.cli.click.confirm") as mocked_confirm:
+                created = cli.ensureUnmuxOutputDirectory(
+                    {"dry_run": False},
+                    str(output_directory),
+                )
+
+            self.assertFalse(created)
+            mocked_confirm.assert_not_called()
+
+    def test_existing_non_directory_output_path_fails_without_prompt(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_path = Path(tempdir) / "manual"
+            output_path.write_text("not a directory", encoding="utf-8")
+
+            with patch("ffx.cli.click.confirm") as mocked_confirm:
+                with self.assertRaises(click.ClickException) as caught:
+                    cli.ensureUnmuxOutputDirectory(
+                        {"dry_run": False},
+                        str(output_path),
+                    )
+
+            self.assertIn("not a directory", str(caught.exception))
+            mocked_confirm.assert_not_called()
+
+    def test_dry_run_does_not_prompt_or_create_missing_output_directory(self):
+        with tempfile.TemporaryDirectory() as tempdir:
+            output_directory = Path(tempdir) / "missing" / "manual"
+
+            with patch("ffx.cli.click.confirm") as mocked_confirm:
+                created = cli.ensureUnmuxOutputDirectory(
+                    {"dry_run": True},
+                    str(output_directory),
+                )
+
+            self.assertFalse(created)
+            self.assertFalse(output_directory.exists())
+            mocked_confirm.assert_not_called()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_cli_unmux_sequence.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import unittest
+
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+
+from ffx import cli  # noqa: E402
+from ffx.track_codec import TrackCodec  # noqa: E402
+from ffx.track_descriptor import TrackDescriptor  # noqa: E402
+from ffx.track_type import TrackType  # noqa: E402
+
+
+class UnmuxSequenceTests(unittest.TestCase):
+    def test_h265_video_unmux_uses_annex_b_bitstream_filter_without_forced_format(self):
+        track_descriptor = TrackDescriptor(
+            index=0,
+            sub_index=0,
+            track_type=TrackType.VIDEO,
+            codec_name=TrackCodec.H265,
+            tags={},
+            disposition_set=set(),
+        )
+
+        sequence = cli.getUnmuxSequence(
+            track_descriptor,
+            "input.mp4",
+            "episode_0_eng",
+        )
+
+        self.assertEqual(
+            [
+                "ffmpeg",
+                "-y",
+                "-i",
+                "input.mp4",
+                "-map",
+                "0:v:0",
+                "-c:v",
+                "copy",
+                "-bsf:v",
+                "hevc_mp4toannexb",
+                "episode_0_eng.h265",
+            ],
+            sequence,
+        )
+
+    def test_non_h265_unmux_keeps_generic_copy_behavior(self):
+        track_descriptor = TrackDescriptor(
+            index=1,
+            sub_index=0,
+            track_type=TrackType.SUBTITLE,
+            codec_name=TrackCodec.SRT,
+            tags={},
+            disposition_set=set(),
+        )
+
+        sequence = cli.getUnmuxSequence(
+            track_descriptor,
+            "input.mkv",
+            "episode_1_eng",
+        )
+
+        self.assertEqual(
+            [
+                "ffmpeg",
+                "-y",
+                "-i",
+                "input.mkv",
+                "-map",
+                "0:s:0",
+                "-c",
+                "copy",
+                "-f",
+                "srt",
+                "episode_1_eng.srt",
+            ],
+            sequence,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_upgrade.py

@@ -68,11 +68,14 @@ class UpgradeCommandTests(unittest.TestCase):
             subprocess_calls.append((args, kwargs))
             if args == ['git', 'status', '--porcelain', '--untracked-files=no']:
                 return self.make_completed(args, stdout="M  src/ffx/constants.py\n")
+            if args == ['git', 'rev-parse', '--abbrev-ref', 'HEAD']:
+                return self.make_completed(args, stdout="main\n")
             return self.make_completed(args)
 
         with (
             patch.object(cli, "getBundleRepoPath", return_value=repo_path),
             patch.object(cli, "getBundlePipPath", return_value=pip_path),
+            patch.object(cli, "getBundleVersion", return_value="0.3.2"),
             patch.object(cli.os.path, "isdir", return_value=True),
             patch.object(cli.os.path, "isfile", return_value=True),
             patch.object(cli.subprocess, "run", side_effect=fake_run),
@@ -81,6 +84,7 @@ class UpgradeCommandTests(unittest.TestCase):
 
         self.assertEqual(0, result.exit_code, result.output)
         self.assertIn("Tracked local changes detected in the bundle repository:", result.output)
+        self.assertIn("Updated FFX to version 0.3.2 from branch main.", result.output)
         self.assertEqual(
             [
                 ['git', 'status', '--porcelain', '--untracked-files=no'],
@@ -89,6 +93,7 @@ class UpgradeCommandTests(unittest.TestCase):
                 ['git', 'checkout', '-B', 'main', 'FETCH_HEAD'],
                 [pip_path, 'install', '--upgrade', 'pip', 'setuptools', 'wheel'],
                 [pip_path, 'install', '--editable', '.'],
+                ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
             ],
             [call[0] for call in subprocess_calls],
         )
@@ -106,11 +111,14 @@ class UpgradeCommandTests(unittest.TestCase):
             subprocess_calls.append((args, kwargs))
             if args == ['git', 'status', '--porcelain', '--untracked-files=no']:
                 return self.make_completed(args, stdout="")
+            if args == ['git', 'rev-parse', '--abbrev-ref', 'HEAD']:
+                return self.make_completed(args, stdout="develop\n")
             return self.make_completed(args)
 
         with (
             patch.object(cli, "getBundleRepoPath", return_value=repo_path),
             patch.object(cli, "getBundlePipPath", return_value=pip_path),
+            patch.object(cli, "getBundleVersion", return_value="0.3.3"),
             patch.object(cli.os.path, "isdir", return_value=True),
             patch.object(cli.os.path, "isfile", return_value=True),
             patch.object(cli.subprocess, "run", side_effect=fake_run),
@@ -118,12 +126,14 @@ class UpgradeCommandTests(unittest.TestCase):
             result = runner.invoke(cli.ffx, ["upgrade"])
 
         self.assertEqual(0, result.exit_code, result.output)
+        self.assertIn("Updated FFX to version 0.3.3 from branch develop.", result.output)
         self.assertEqual(
             [
                 ['git', 'status', '--porcelain', '--untracked-files=no'],
                 ['git', 'pull'],
                 [pip_path, 'install', '--upgrade', 'pip', 'setuptools', 'wheel'],
                 [pip_path, 'install', '--editable', '.'],
+                ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
             ],
             [call[0] for call in subprocess_calls],
         )

tests/unit/test_ffmpeg_diagnostics.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import unittest
+from unittest.mock import patch
+
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+
+from ffx.diagnostics import (  # noqa: E402
+    FfmpegCommandRunner,
+    FfmpegDiagnosticMonitor,
+    FfmpegSkipFileWarning,
+    getUnremediedIssues,
+    iterUnremediedIssueSummaryLines,
+)
+
+
+class RecordingLogger:
+    def __init__(self):
+        self.messages: list[str] = []
+
+    def warning(self, message, *args, **kwargs):
+        if args:
+            message = message % args
+        self.messages.append(str(message))
+
+
+class FfmpegDiagnosticsTests(unittest.TestCase):
+    def test_command_runner_retries_with_genpts_after_timestamp_warning(self):
+        logger = RecordingLogger()
+        context = {
+            "logger": logger,
+            "current_source_path": "tests/assets/avi/conan_S01E754_amalgam.avi",
+        }
+        runner = FfmpegCommandRunner(context)
+        commands = []
+
+        def fake_execute(commandSequence, **kwargs):
+            commands.append(list(commandSequence))
+            stderrLineHandler = kwargs["stderrLineHandler"]
+            if len(commands) == 1:
+                self.assertTrue(
+                    stderrLineHandler(
+                        "[matroska @ 0x1] Timestamps are unset in a packet for stream 0. "
+                        + "This is deprecated and will stop working in the future."
+                    )
+                )
+                return "", "timestamp warning\n", -15
+
+            return "done", "", 0
+
+        with patch("ffx.diagnostics.monitor.executeProcess", side_effect=fake_execute):
+            out, err, rc = runner.execute(["ffmpeg", "-y", "-i", "input.avi", "output.mkv"])
+
+        self.assertEqual("done", out)
+        self.assertEqual("", err)
+        self.assertEqual(0, rc)
+        self.assertEqual(
+            [
+                ["ffmpeg", "-y", "-i", "input.avi", "output.mkv"],
+                ["ffmpeg", "-fflags", "+genpts", "-y", "-i", "input.avi", "output.mkv"],
+            ],
+            commands,
+        )
+        self.assertEqual(
+            [
+                "ffmpeg reported unset packet timestamps for tests/assets/avi/conan_S01E754_amalgam.avi. "
+                + "Stopping early and retrying with -fflags +genpts."
+            ],
+            logger.messages,
+        )
+        self.assertEqual({}, getUnremediedIssues(context))
+
+    def test_command_runner_skips_file_when_timestamp_warning_persists_after_genpts(self):
+        logger = RecordingLogger()
+        context = {
+            "logger": logger,
+            "current_source_path": "tests/assets/avi/conan_S01E754_amalgam.avi",
+        }
+        runner = FfmpegCommandRunner(context)
+
+        def fake_execute(commandSequence, **kwargs):
+            stderrLineHandler = kwargs["stderrLineHandler"]
+            self.assertTrue(
+                stderrLineHandler(
+                    "[matroska @ 0x1] Timestamps are unset in a packet for stream 0. "
+                    + "This is deprecated and will stop working in the future."
+                )
+            )
+            return "", "timestamp warning\n", -15
+
+        with patch("ffx.diagnostics.monitor.executeProcess", side_effect=fake_execute):
+            with self.assertRaises(FfmpegSkipFileWarning):
+                runner.execute(
+                    ["ffmpeg", "-fflags", "+genpts", "-y", "-i", "input.avi", "output.mkv"]
+                )
+
+        self.assertEqual(
+            [
+                "Skipping file tests/assets/avi/conan_S01E754_amalgam.avi: ffmpeg still reported "
+                + "unset packet timestamps after retry with -fflags +genpts."
+            ],
+            logger.messages,
+        )
+        self.assertEqual(
+            {
+                "tests/assets/avi/conan_S01E754_amalgam.avi": ["retry-with-generated-pts"]
+            },
+            getUnremediedIssues(context),
+        )
+
+    def test_monitor_tracks_non_harmless_corrupt_mpeg_audio_remedy_in_summary(self):
+        logger = RecordingLogger()
+        context = {
+            "logger": logger,
+            "current_source_path": "tests/assets/avi/conan_S01E763_amalgam.avi",
+        }
+        monitor = FfmpegDiagnosticMonitor(
+            context,
+            ["ffmpeg", "-y", "-i", "input.avi", "output.mkv"],
+        )
+
+        self.assertFalse(
+            monitor.handle_stderr_line("[mp3float @ 0x1] invalid new backstep -1")
+        )
+        self.assertFalse(monitor.handle_stderr_line("[mp3float @ 0x1] invalid block type"))
+        self.assertFalse(
+            monitor.handle_stderr_line(
+                "[aist#0:1/mp3 @ 0x2] [dec:mp3float @ 0x3] Error submitting packet to decoder: "
+                + "Invalid data found when processing input"
+            )
+        )
+
+        self.assertEqual(
+            [
+                "ffmpeg reported damaged MPEG audio frames while converting "
+                + "tests/assets/avi/conan_S01E763_amalgam.avi. FFX will continue, but the "
+                + "output audio may contain gaps or glitches."
+            ],
+            logger.messages,
+        )
+        self.assertEqual(
+            {
+                "tests/assets/avi/conan_S01E763_amalgam.avi": ["warn-corrupt-mpeg-audio"]
+            },
+            getUnremediedIssues(context),
+        )
+        self.assertEqual(
+            ["conan_S01E763_amalgam.avi: warn-corrupt-mpeg-audio"],
+            iterUnremediedIssueSummaryLines(context),
+        )
+
+    def test_monitor_tracks_unhandled_diagnostic_for_summary(self):
+        context = {
+            "logger": RecordingLogger(),
+            "current_source_path": "tests/assets/avi/example.avi",
+        }
+        monitor = FfmpegDiagnosticMonitor(
+            context,
+            ["ffmpeg", "-y", "-i", "input.avi", "output.mkv"],
+        )
+
+        self.assertFalse(
+            monitor.handle_stderr_line(
+                "[avi @ 0x1] Strange warning with no automatic remedy is present"
+            )
+        )
+
+        self.assertEqual(
+            {
+                "tests/assets/avi/example.avi": ["unhandled-warning"]
+            },
+            getUnremediedIssues(context),
+        )
+        self.assertEqual(
+            ["example.avi: unhandled-warning"],
+            iterUnremediedIssueSummaryLines(context),
+        )
+        self.assertEqual(
+            [
+                "ffmpeg reported a diagnostic with no automatic remedy while converting "
+                + "tests/assets/avi/example.avi. FFX will continue, but review the output "
+                + "file. First unhandled line: [avi @ 0x1] Strange warning with no automatic remedy is present"
+            ],
+            context["logger"].messages,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_ffx_controller.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import click
 from pathlib import Path
 import sys
 import unittest
@@ -14,6 +15,7 @@ if str(SRC_ROOT) not in sys.path:
 
 
 from ffx.ffx_controller import FfxController  # noqa: E402
+from ffx.audio_layout import AudioLayout  # noqa: E402
 from ffx.logging_utils import get_ffx_logger  # noqa: E402
 from ffx.media_descriptor import MediaDescriptor  # noqa: E402
 from ffx.show_descriptor import ShowDescriptor  # noqa: E402
@@ -32,6 +34,9 @@ class StaticConfig:
 
 
 class FfxControllerTests(unittest.TestCase):
+    def tearDown(self):
+        FfxController.isFfmpegEncoderAvailable.cache_clear()
+
     def make_context(self, video_encoder: VideoEncoder) -> dict:
         return {
             "logger": get_ffx_logger(),
@@ -39,6 +44,8 @@ class FfxControllerTests(unittest.TestCase):
             "video_encoder": video_encoder,
             "dry_run": False,
             "perform_cut": False,
+            "copy_video": False,
+            "copy_audio": False,
             "bitrates": {
                 "stereo": "112k",
                 "ac3": "256k",
@@ -71,6 +78,56 @@ class FfxControllerTests(unittest.TestCase):
         )
         return descriptor, source_descriptor
 
+    def make_media_descriptors_with_audio(
+        self,
+        audio_layout: AudioLayout = AudioLayout.LAYOUT_STEREO,
+    ) -> tuple[MediaDescriptor, MediaDescriptor]:
+        descriptor = MediaDescriptor(
+            track_descriptors=[
+                TrackDescriptor(
+                    index=0,
+                    source_index=0,
+                    sub_index=0,
+                    track_type=TrackType.VIDEO,
+                    codec_name=TrackCodec.H264,
+                ),
+                TrackDescriptor(
+                    index=1,
+                    source_index=1,
+                    sub_index=0,
+                    track_type=TrackType.AUDIO,
+                    codec_name=TrackCodec.AAC,
+                    audio_layout=audio_layout,
+                ),
+            ]
+        )
+        source_descriptor = MediaDescriptor(
+            track_descriptors=[
+                TrackDescriptor(
+                    index=0,
+                    source_index=0,
+                    sub_index=0,
+                    track_type=TrackType.VIDEO,
+                    codec_name=TrackCodec.H264,
+                ),
+                TrackDescriptor(
+                    index=1,
+                    source_index=1,
+                    sub_index=0,
+                    track_type=TrackType.AUDIO,
+                    codec_name=TrackCodec.AAC,
+                    audio_layout=audio_layout,
+                ),
+            ]
+        )
+        return descriptor, source_descriptor
+
+    def assert_token_pair(self, command: list[str], first: str, second: str):
+        self.assertTrue(
+            any(command[index:index + 2] == [first, second] for index in range(len(command) - 1)),
+            command,
+        )
+
     def test_vp9_run_job_emits_file_level_encoding_quality_metadata(self):
         context = self.make_context(VideoEncoder.VP9)
         target_descriptor, source_descriptor = self.make_media_descriptors()
@@ -192,6 +249,135 @@ class FfxControllerTests(unittest.TestCase):
         self.assertIn("ENCODING_QUALITY=19", commands[0])
         mocked_info.assert_any_call("Setting quality 19 from pattern")
 
+    def test_copy_video_uses_single_copy_command_without_video_encoding_options(self):
+        context = self.make_context(VideoEncoder.VP9)
+        context["copy_video"] = True
+        target_descriptor, source_descriptor = self.make_media_descriptors_with_audio()
+        controller = FfxController(context, target_descriptor, source_descriptor)
+        commands = []
+
+        with patch.object(
+            controller,
+            "executeCommandSequence",
+            side_effect=lambda command: commands.append(command) or ("", "", 0),
+        ):
+            controller.runJob(
+                "input.mkv",
+                "output.mkv",
+                chainIteration=[
+                    {
+                        "identifier": "quality",
+                        "parameters": {"quality": 27},
+                    },
+                    {
+                        "identifier": "nlmeans",
+                        "parameters": {},
+                        "tokens": ["nlmeans=s=2.0"],
+                    },
+                ],
+                cropArguments={
+                    "output_width": 1280,
+                    "output_height": 720,
+                    "x_offset": 0,
+                    "y_offset": 0,
+                },
+            )
+
+        self.assertEqual(1, len(commands))
+        self.assert_token_pair(commands[0], "-c:v", "copy")
+        self.assertIn("libopus", commands[0])
+        self.assertNotIn("libvpx-vp9", commands[0])
+        self.assertNotIn("-pass", commands[0])
+        self.assertNotIn("-vf", commands[0])
+        self.assertFalse(any(token.startswith("ENCODING_QUALITY=") for token in commands[0]))
+
+    def test_copy_audio_uses_audio_copy_without_audio_encoding_options(self):
+        context = self.make_context(VideoEncoder.H264)
+        context["copy_audio"] = True
+        target_descriptor, source_descriptor = self.make_media_descriptors_with_audio(
+            AudioLayout.LAYOUT_5_1
+        )
+        controller = FfxController(context, target_descriptor, source_descriptor)
+        commands = []
+
+        with patch.object(
+            controller,
+            "executeCommandSequence",
+            side_effect=lambda command: commands.append(command) or ("", "", 0),
+        ):
+            controller.runJob(
+                "input.mkv",
+                "output.mkv",
+                chainIteration=[
+                    {
+                        "identifier": "quality",
+                        "parameters": {"quality": 21},
+                    }
+                ],
+            )
+
+        self.assertEqual(1, len(commands))
+        self.assert_token_pair(commands[0], "-c:a", "copy")
+        self.assertIn("libx264", commands[0])
+        self.assertNotIn("libopus", commands[0])
+        self.assertFalse(any(token.startswith("-b:a") for token in commands[0]))
+        self.assertFalse(any(token.startswith("-filter:a") for token in commands[0]))
+    def test_generate_h264_tokens_prefers_libx264_when_available(self):
+        context = self.make_context(VideoEncoder.H264)
+        target_descriptor, source_descriptor = self.make_media_descriptors()
+        controller = FfxController(context, target_descriptor, source_descriptor)
+
+        with patch.object(
+            FfxController,
+            "getSupportedSoftwareH264Encoder",
+            return_value="libx264",
+        ):
+            tokens = controller.generateH264Tokens(23)
+
+        self.assertEqual(
+            ["-c:v:0", "libx264", "-preset", "slow", "-crf", "23"],
+            tokens,
+        )
+
+    def test_generate_h264_tokens_falls_back_to_libopenh264_and_logs_warning(self):
+        context = self.make_context(VideoEncoder.H264)
+        target_descriptor, source_descriptor = self.make_media_descriptors()
+        controller = FfxController(context, target_descriptor, source_descriptor)
+
+        with (
+            patch.object(
+                FfxController,
+                "getSupportedSoftwareH264Encoder",
+                return_value="libopenh264",
+            ),
+            patch.object(context["logger"], "warning") as mocked_warning,
+        ):
+            tokens = controller.generateH264Tokens(23)
+
+        self.assertEqual(
+            ["-c:v:0", "libopenh264", "-pix_fmt", "yuv420p"],
+            tokens,
+        )
+        mocked_warning.assert_called_once_with(
+            "libx264 encoder unavailable; falling back to libopenh264 for H.264 encoding."
+        )
+
+    def test_generate_h264_tokens_raises_when_no_supported_software_encoder_exists(self):
+        context = self.make_context(VideoEncoder.H264)
+        target_descriptor, source_descriptor = self.make_media_descriptors()
+        controller = FfxController(context, target_descriptor, source_descriptor)
+
+        with patch.object(
+            FfxController,
+            "getSupportedSoftwareH264Encoder",
+            return_value=None,
+        ):
+            with self.assertRaisesRegex(
+                click.ClickException,
+                "no supported software H.264 encoder is available",
+            ):
+                controller.generateH264Tokens(23)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_file_properties_asset_probe.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from pathlib import Path
 import sys
+import tempfile
 import unittest
 
 
@@ -16,6 +17,7 @@ from ffx.i18n import set_current_language  # noqa: E402
 from ffx.logging_utils import get_ffx_logger  # noqa: E402
 from ffx.track_codec import TrackCodec  # noqa: E402
 from ffx.track_type import TrackType  # noqa: E402
+from tests.support.ffx_bundle import SourceTrackSpec, create_source_fixture  # noqa: E402
 
 
 class StaticConfig:
@@ -39,10 +41,26 @@ class FilePropertiesAssetProbeTests(unittest.TestCase):
         }
         set_current_language("de")
 
-        media_path = (
+        with tempfile.TemporaryDirectory() as tmpdir:
-            Path(__file__).resolve().parents[1]
+            media_path = create_source_fixture(
-            / "assets"
+                Path(tmpdir),
-            / "Boruto; Naruto Next Generations (2017) - 0069 Super-Chochos Liebestaumel - S01E0069.webm"
+                "fixture.webm",
+                [
+                    SourceTrackSpec(TrackType.VIDEO, identity="video-0"),
+                    SourceTrackSpec(TrackType.AUDIO, identity="audio-1", language="eng"),
+                    SourceTrackSpec(
+                        TrackType.SUBTITLE,
+                        identity="subtitle-2",
+                        language="eng",
+                        subtitle_lines=("Lorem ipsum dolor sit amet.",),
+                    ),
+                ],
+                duration_seconds=3,
+                video_encoder="libvpx-vp9",
+                video_encoder_options=("-b:v", "0", "-crf", "45"),
+                audio_encoder="libopus",
+                audio_encoder_options=("-b:a", "48k"),
+                subtitle_encoder="webvtt",
             )
 
             file_properties = FileProperties(context, str(media_path))

tests/unit/test_logging.py

@@ -16,8 +16,10 @@ if str(SRC_ROOT) not in sys.path:
 from ffx.logging_utils import (  # noqa: E402
     CONSOLE_HANDLER_NAME,
     FILE_HANDLER_NAME,
+    MUTED_CONSOLE_LEVEL,
     configure_ffx_logger,
     get_ffx_logger,
+    set_ffx_console_logging_enabled,
 )
 
 
@@ -81,6 +83,33 @@ class LoggingUtilsTests(unittest.TestCase):
 
         self.cleanup_logger(logger_name)
 
+    def test_set_ffx_console_logging_enabled_mutes_and_restores_console_handler(self):
+        logger_name = "ffx-test-console-mute"
+        self.cleanup_logger(logger_name)
+
+        with tempfile.TemporaryDirectory() as tempdir:
+            log_path = Path(tempdir) / "ffx.log"
+
+            logger = configure_ffx_logger(
+                str(log_path),
+                logging.DEBUG,
+                logging.INFO,
+                name=logger_name,
+            )
+            console_handler = next(
+                handler for handler in logger.handlers if handler.get_name() == CONSOLE_HANDLER_NAME
+            )
+
+            self.assertEqual(logging.INFO, console_handler.level)
+
+            set_ffx_console_logging_enabled(logger, enabled=False)
+            self.assertEqual(MUTED_CONSOLE_LEVEL, console_handler.level)
+
+            set_ffx_console_logging_enabled(logger, enabled=True)
+            self.assertEqual(logging.INFO, console_handler.level)
+
+        self.cleanup_logger(logger_name)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_media_descriptor_change_set.py

@@ -13,6 +13,7 @@ if str(SRC_ROOT) not in sys.path:
 
 from ffx.media_descriptor import MediaDescriptor  # noqa: E402
 from ffx.media_descriptor_change_set import MediaDescriptorChangeSet  # noqa: E402
+from ffx.attachment_format import AttachmentFormat  # noqa: E402
 from ffx.track_descriptor import TrackDescriptor  # noqa: E402
 from ffx.track_type import TrackType  # noqa: E402
 from ffx.i18n import set_current_language  # noqa: E402
@@ -436,6 +437,47 @@ class MediaDescriptorChangeSetTests(unittest.TestCase):
         self.assertNotIn("creation_time=", metadata_tokens)
         self.assertNotIn("BPS=", metadata_tokens)
 
+    def test_attachment_tracks_are_ignored_for_pattern_comparison(self):
+        context = {
+            "logger": get_ffx_logger(),
+            "config": StaticConfig({}),
+        }
+
+        source_track = TrackDescriptor(
+            index=0,
+            source_index=0,
+            sub_index=0,
+            track_type=TrackType.ATTACHMENT,
+            attachment_format=AttachmentFormat.TTF,
+            tags={"filename": "current.ttf", "mimetype": "font/ttf"},
+        )
+        target_track = TrackDescriptor(
+            index=0,
+            source_index=0,
+            sub_index=0,
+            track_type=TrackType.ATTACHMENT,
+            attachment_format=AttachmentFormat.TTF,
+            tags={"filename": "stored.ttf", "mimetype": "font/ttf"},
+        )
+        stale_target_track = TrackDescriptor(
+            index=1,
+            source_index=1,
+            sub_index=1,
+            track_type=TrackType.ATTACHMENT,
+            attachment_format=AttachmentFormat.TTF,
+            tags={"filename": "missing.ttf", "mimetype": "font/ttf"},
+        )
+
+        change_set = MediaDescriptorChangeSet(
+            context,
+            MediaDescriptor(track_descriptors=[target_track, stale_target_track]),
+            MediaDescriptor(track_descriptors=[source_track]),
+        )
+
+        self.assertEqual({}, change_set.getChangeSetObj())
+        self.assertEqual([], change_set.generateMetadataTokens())
+        self.assertEqual([], change_set.generateDispositionTokens())
+
     def test_normalization_can_be_disabled_per_context(self):
         context = {
             "logger": get_ffx_logger(),

tests/unit/test_media_descriptor_import_subtitles.py

@@ -20,18 +20,32 @@ from ffx.track_type import TrackType  # noqa: E402
 
 
 class MediaDescriptorImportSubtitlesTests(unittest.TestCase):
-    def make_descriptor(self) -> MediaDescriptor:
+    COMPLETE_SIDECAR_NAMES = (
+        "A2_t01_2_deu_DEF",
+        "A2_t01_3_eng",
+        "A2_t01_4_eng",
+    )
+
+    def write_complete_sidecar_set(self, directory: str, extension: str) -> None:
+        for basename in self.COMPLETE_SIDECAR_NAMES:
+            (Path(directory) / f"{basename}.{extension}").write_text(
+                "WEBVTT\n\n",
+                encoding="utf-8",
+            )
+
+    def make_descriptor(self, indices=(3,)) -> MediaDescriptor:
         return MediaDescriptor(
             context={"logger": get_ffx_logger()},
             track_descriptors=[
                 TrackDescriptor(
-                    index=3,
+                    index=index,
-                    source_index=3,
+                    source_index=index,
-                    sub_index=0,
+                    sub_index=subIndex,
                     track_type=TrackType.SUBTITLE,
                     tags={"language": "eng", "title": "DB Subtitle"},
                     disposition_set={TrackDisposition.DEFAULT},
                 )
+                for subIndex, index in enumerate(indices)
             ],
         )
 
@@ -74,6 +88,114 @@ class MediaDescriptorImportSubtitlesTests(unittest.TestCase):
         self.assertEqual("deu", track.getTags()["language"])
         self.assertEqual({TrackDisposition.FORCED}, track.getDispositionSet())
 
+    def test_strict_basename_import_recognizes_vtt_asset_set(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self.write_complete_sidecar_set(tmpdir, "vtt")
+            result = descriptor.importSubtitles(
+                tmpdir,
+                "A2_t01",
+                strict=True,
+            )
+
+        self.assertEqual(3, result["candidate_count"])
+        self.assertEqual([2, 3, 4], result["imported_track_indices"])
+        self.assertEqual([], result["missing_track_indices"])
+        self.assertEqual(
+            [
+                "A2_t01_2_deu_DEF.vtt",
+                "A2_t01_3_eng.vtt",
+                "A2_t01_4_eng.vtt",
+            ],
+            [
+                Path(track.getExternalSourceFilePath()).name
+                for track in descriptor.getSubtitleTracks()
+            ],
+        )
+
+    def test_strict_basename_import_accepts_dotted_mkv_extension(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self.write_complete_sidecar_set(tmpdir, "mkv")
+            result = descriptor.importSubtitles(
+                tmpdir,
+                "A2_t01",
+                extension=".mkv",
+                strict=True,
+            )
+
+        self.assertEqual(3, result["candidate_count"])
+        self.assertEqual([2, 3, 4], result["imported_track_indices"])
+        self.assertEqual([], result["missing_track_indices"])
+        self.assertTrue(
+            all(
+                track.getExternalSourceFilePath().endswith(".mkv")
+                for track in descriptor.getSubtitleTracks()
+            )
+        )
+
+    def test_strict_basename_import_reports_missing_tracks(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            sidecarPath = Path(tmpdir) / "episode_2_deu.vtt"
+            sidecarPath.write_text("WEBVTT\n\n", encoding="utf-8")
+
+            result = descriptor.importSubtitles(
+                tmpdir,
+                "episode",
+                strict=True,
+            )
+
+        self.assertEqual([2], result["imported_track_indices"])
+        self.assertEqual([3, 4], result["missing_track_indices"])
+
+    def test_strict_basename_import_rejects_too_many_files(self):
+        descriptor = self.make_descriptor(indices=(2,))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            for filename in ("episode_2_deu.vtt", "episode_3_eng.vtt"):
+                (Path(tmpdir) / filename).write_text("WEBVTT\n\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ValueError, "2 matching .* for 1 subtitle tracks"):
+                descriptor.importSubtitles(tmpdir, "episode", strict=True)
+
+    def test_strict_basename_import_rejects_unknown_track_index(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            (Path(tmpdir) / "episode_9_eng.vtt").write_text(
+                "WEBVTT\n\n",
+                encoding="utf-8",
+            )
+
+            with self.assertRaisesRegex(ValueError, "track index pattern does not match"):
+                descriptor.importSubtitles(tmpdir, "episode", strict=True)
+
+    def test_strict_basename_import_rejects_malformed_filtered_filename(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            (Path(tmpdir) / "episode_s01e01_2_deu.vtt").write_text(
+                "WEBVTT\n\n",
+                encoding="utf-8",
+            )
+
+            with self.assertRaisesRegex(ValueError, "expected pattern"):
+                descriptor.importSubtitles(tmpdir, "episode", strict=True)
+
+    def test_strict_basename_import_rejects_duplicate_track_indices(self):
+        descriptor = self.make_descriptor(indices=(2, 3, 4))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            for filename in ("episode_2_deu.vtt", "episode_2_eng.vtt"):
+                (Path(tmpdir) / filename).write_text("WEBVTT\n\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ValueError, "Multiple external subtitle files"):
+                descriptor.importSubtitles(tmpdir, "episode", strict=True)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_metadata_editor.py

@@ -15,6 +15,7 @@ if str(SRC_ROOT) not in sys.path:
 
 
 from ffx.logging_utils import get_ffx_logger  # noqa: E402
+from ffx.helper import LogLevel  # noqa: E402
 from ffx.media_descriptor import MediaDescriptor  # noqa: E402
 from ffx.metadata_editor import (  # noqa: E402
     apply_metadata_edits,
@@ -33,6 +34,16 @@ class StaticConfig:
         return {}
 
 
+class NotificationCollector:
+    def __init__(self) -> None:
+        self.messages: list[str] = []
+        self.levels: list[LogLevel | None] = []
+
+    def __call__(self, message: str, level: LogLevel | None = None) -> None:
+        self.messages.append(message)
+        self.levels.append(level)
+
+
 def make_context(*, dry_run: bool = False) -> dict:
     return {
         "logger": get_ffx_logger(),
@@ -151,7 +162,7 @@ class MetadataEditorTests(unittest.TestCase):
         context = make_context(dry_run=True)
         baseline_descriptor = make_descriptor()
         draft_descriptor = baseline_descriptor.clone(context=context)
-        notifications = []
+        notifications = NotificationCollector()
         expected_command = build_metadata_edit_command(
             build_metadata_edit_context(context),
             "/tmp/example.mkv",
@@ -170,12 +181,13 @@ class MetadataEditorTests(unittest.TestCase):
                 "/tmp/example.mkv",
                 baseline_descriptor,
                 draft_descriptor,
-                notify=notifications.append,
+                loggingHandler = notifications,
             )
 
         mocked_execute.assert_not_called()
         mocked_replace.assert_not_called()
-        self.assertEqual(["ffmpeg dry-run prepared."], notifications)
+        self.assertEqual(["ffmpeg dry-run prepared."], notifications.messages)
+        self.assertEqual([None], notifications.levels)
         self.assertEqual(
             {
                 "applied": False,
@@ -204,7 +216,7 @@ class MetadataEditorTests(unittest.TestCase):
         context["verbosity"] = 1
         baseline_descriptor = make_descriptor()
         draft_descriptor = baseline_descriptor.clone(context=context)
-        notifications = []
+        notifications = NotificationCollector()
 
         with (
             patch("ffx.metadata_editor.create_temporary_output_path", return_value="/tmp/.edit.mkv"),
@@ -216,11 +228,12 @@ class MetadataEditorTests(unittest.TestCase):
                 "/tmp/example.mkv",
                 baseline_descriptor,
                 draft_descriptor,
-                notify=notifications.append,
+                loggingHandler = notifications,
             )
 
-        self.assertEqual(1, len(notifications))
+        self.assertEqual(1, len(notifications.messages))
-        self.assertTrue(notifications[0].startswith("ffmpeg: ffmpeg "))
+        self.assertTrue(notifications.messages[0].startswith("ffmpeg: ffmpeg "))
+        self.assertEqual([LogLevel.DEBUG], notifications.levels)
 
 
 if __name__ == "__main__":

tests/unit/test_pattern_management.py

@@ -193,6 +193,36 @@ class PatternManagementTests(unittest.TestCase):
 
         self.assertIn("at least one track", str(caught.exception))
 
+    def test_save_pattern_schema_does_not_persist_attachment_tracks(self):
+        pattern_id = self.save_pattern(
+            1,
+            r"^noattachments_(s[0-9]+e[0-9]+)\.mkv$",
+            tracks=[
+                make_track_descriptor(0, track_type=TrackType.VIDEO),
+                make_track_descriptor(1, track_type=TrackType.ATTACHMENT),
+            ],
+        )
+
+        Session = self.context["database"]["session"]
+        session = Session()
+        try:
+            tracks = session.query(Pattern).filter(Pattern.id == pattern_id).first().tracks
+            self.assertEqual(1, len(tracks))
+            self.assertEqual(TrackType.VIDEO, tracks[0].getType())
+        finally:
+            session.close()
+
+    def test_track_controller_does_not_add_attachment_tracks_to_patterns(self):
+        pattern_id = self.save_pattern(1, r"^skipadd_(s[0-9]+e[0-9]+)\.mkv$")
+
+        added = self.track_controller.addTrack(
+            make_track_descriptor(1, track_type=TrackType.ATTACHMENT),
+            patternId=pattern_id,
+        )
+
+        self.assertFalse(added)
+        self.assertEqual(1, len(self.track_controller.findTracks(pattern_id)))
+
     def test_match_filename_rejects_existing_trackless_pattern_rows(self):
         self.insert_trackless_pattern_row(1, r"^invalid_(s[0-9]+e[0-9]+)\.mkv$")
 

tests/unit/test_process.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from pathlib import Path
 import sys
+import time
 import unittest
 from unittest.mock import patch
 
@@ -51,6 +52,33 @@ class ProcessTests(unittest.TestCase):
         self.assertIn("Command timed out", err)
         self.assertIn(sys.executable, err)
 
+    def test_execute_process_can_stop_early_while_streaming_stderr(self):
+        start = time.monotonic()
+        observed_lines = []
+
+        out, err, rc = executeProcess(
+            [
+                sys.executable,
+                "-c",
+                (
+                    "import sys, time; "
+                    "sys.stderr.write('fatal warning\\n'); sys.stderr.flush(); "
+                    "time.sleep(2); "
+                    "sys.stderr.write('late line\\n'); sys.stderr.flush()"
+                ),
+            ],
+            stderrLineHandler=lambda line: observed_lines.append(line) or ("fatal warning" in line),
+        )
+
+        elapsed = time.monotonic() - start
+
+        self.assertLess(elapsed, 1.5)
+        self.assertNotEqual(0, rc)
+        self.assertEqual("", out)
+        self.assertIn("fatal warning", err)
+        self.assertNotIn("late line", err)
+        self.assertEqual(["fatal warning\n"], observed_lines)
+
     def test_get_wrapped_command_sequence_leaves_command_unwrapped_when_limits_disabled(self):
         wrapped = getWrappedCommandSequence(
             ["ffmpeg", "-i", "input.mkv"],

tests/unit/test_screen_support.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+import logging
 import sys
 import unittest
 from unittest.mock import patch
@@ -57,9 +58,38 @@ class FakeScreen:
         self.app = FakeApp(screen_stack)
 
 
+class FakeRichLog:
+    def __init__(self):
+        self.messages = []
+
+    def write(self, message):
+        self.messages.append(message)
+
+
+class FakeScreenWithLog:
+    def __init__(self):
+        self.log_view = FakeRichLog()
+
+    def query_one(self, selector, _widget_type=None):
+        if selector == f"#{screen_support.SCREEN_LOG_VIEW_ID}":
+            return self.log_view
+        raise LookupError(selector)
+
+
+class FakeThreadedApp:
+    def __init__(self, screen):
+        self.screen = screen
+        self.calls = []
+
+    def call_from_thread(self, func, *args):
+        self.calls.append((func, args))
+        return func(*args)
+
+
 class ScreenSupportTests(unittest.TestCase):
     def tearDown(self):
         set_current_language("de")
+        screen_support.set_screen_log_pane_enabled(False)
 
     def make_context(self):
         return {
@@ -168,6 +198,63 @@ class ScreenSupportTests(unittest.TestCase):
         self.assertGreater(len(translated), 8)
         self.assertEqual(len(translated) + 2, screen_support.localized_column_width(translated, 8))
 
+    def test_build_screen_log_pane_is_hidden_when_debug_mode_is_disabled(self):
+        screen_support.set_screen_log_pane_enabled(False)
+
+        log_pane = screen_support.build_screen_log_pane()
+
+        self.assertFalse(log_pane.display)
+
+    def test_build_screen_log_pane_is_collapsed_when_debug_mode_is_enabled(self):
+        screen_support.set_screen_log_pane_enabled(True)
+
+        log_pane = screen_support.build_screen_log_pane()
+
+        self.assertIsInstance(log_pane, screen_support.ResizableScreenLogPane)
+        self.assertEqual(screen_support.SCREEN_LOG_PANE_ID, log_pane.id)
+        self.assertTrue(log_pane.collapsed)
+
+    def test_resizable_screen_log_pane_clamps_height_to_minimum(self):
+        log_pane = screen_support.ResizableScreenLogPane()
+
+        log_pane.set_log_height(1)
+
+        self.assertEqual(screen_support.SCREEN_LOG_MIN_HEIGHT, log_pane.get_log_height())
+
+    def test_configure_screen_log_handler_routes_logger_messages_to_active_screen(self):
+        logger_name = "ffx-test-screen-log-handler"
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(logging.DEBUG)
+        logger.propagate = False
+
+        for handler in list(logger.handlers):
+            logger.removeHandler(handler)
+            handler.close()
+
+        screen = FakeScreenWithLog()
+        app = FakeThreadedApp(screen)
+
+        try:
+            handler = screen_support.configure_screen_log_handler(
+                logger,
+                app,
+                enabled=True,
+            )
+            self.assertIsNotNone(handler)
+
+            logger.info("hello pane")
+
+            self.assertEqual(1, len(screen.log_view.messages))
+            self.assertRegex(
+                screen.log_view.messages[0],
+                r"^ffx-test-screen-log-handler\s+INFO\s+\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} \| hello pane$",
+            )
+        finally:
+            screen_support.configure_screen_log_handler(logger, app, enabled=False)
+            for handler in list(logger.handlers):
+                logger.removeHandler(handler)
+                handler.close()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_tag_table_screen_state.py

@@ -14,12 +14,14 @@ if str(SRC_ROOT) not in sys.path:
 
 
 from ffx.audio_layout import AudioLayout  # noqa: E402
-from ffx.helper import DIFF_ADDED_KEY  # noqa: E402
+from ffx.attachment_format import AttachmentFormat  # noqa: E402
+from ffx.helper import DIFF_ADDED_KEY, DIFF_REMOVED_KEY  # noqa: E402
 from ffx.iso_language import IsoLanguage  # noqa: E402
 from ffx.logging_utils import get_ffx_logger  # noqa: E402
 from ffx.inspect_details_screen import InspectDetailsScreen  # noqa: E402
 from ffx.i18n import set_current_language  # noqa: E402
 from ffx.media_descriptor import MediaDescriptor  # noqa: E402
+from ffx.media_descriptor_change_set import MediaDescriptorChangeSet  # noqa: E402
 from ffx.media_edit_screen import MediaEditScreen  # noqa: E402
 from ffx.pattern_details_screen import PatternDetailsScreen  # noqa: E402
 from ffx.show_descriptor import ShowDescriptor  # noqa: E402
@@ -200,6 +202,32 @@ class TagTableScreenStateTests(unittest.TestCase):
         self.assertEqual("German Audio", descriptor.getTitle())
         self.assertEqual("value", descriptor.getTags()["KEEP"])
 
+    def test_track_details_screen_preserves_attachment_format_for_attachment_tracks(self):
+        screen = object.__new__(TrackDetailsScreen)
+        screen.context = {"logger": get_ffx_logger()}
+        screen._TrackDetailsScreen__trackDescriptor = None
+        screen._TrackDetailsScreen__patternId = 5
+        screen._TrackDetailsScreen__index = 4
+        screen._TrackDetailsScreen__subIndex = 0
+        screen._TrackDetailsScreen__trackCodec = TrackCodec.UNKNOWN
+        screen._TrackDetailsScreen__attachmentFormat = AttachmentFormat.TTF
+        screen._TrackDetailsScreen__draftTrackTags = {"filename": "font.ttf", "mimetype": "font/ttf"}
+
+        widgets = {
+            "#type_select": FakeValueWidget(TrackType.ATTACHMENT),
+            "#audio_layout_select": FakeValueWidget(AudioLayout.LAYOUT_UNDEFINED),
+            "#language_select": FakeValueWidget(Select.NULL),
+            "#title_input": FakeInputWidget(""),
+            "#dispositions_selection_list": FakeSelectionListWidget(set()),
+        }
+        screen.query_one = lambda selector, _widget_type=None: widgets[selector]
+
+        descriptor = screen.getTrackDescriptorFromInput()
+
+        self.assertEqual(TrackType.ATTACHMENT, descriptor.getType())
+        self.assertEqual(AttachmentFormat.TTF, descriptor.getAttachmentFormat())
+        self.assertEqual(TrackCodec.UNKNOWN, descriptor.getCodec())
+
     def test_track_details_screen_auto_sets_localized_title_from_selected_language(self):
         set_current_language("de")
         screen = object.__new__(TrackDetailsScreen)
@@ -521,6 +549,11 @@ class TagTableScreenStateTests(unittest.TestCase):
         screen.tagsTable = FakeTagTable()
         screen.shiftedSeasonsTable = FakeTagTable()
         screen._PatternDetailsScreen__pattern = object()
+        screen._PatternDetailsScreen__showDescriptor = None
+        widgets = {
+            "#show_quality_hint": FakeStaticWidget(),
+        }
+        screen.query_one = lambda selector, _type=None: widgets[selector]
 
         calls = []
         screen.updateTags = lambda: calls.append("updateTags")
@@ -534,6 +567,48 @@ class TagTableScreenStateTests(unittest.TestCase):
             calls,
         )
 
+    def test_pattern_details_screen_on_mount_shows_show_quality_hint_for_new_pattern(self):
+        set_current_language("en")
+
+        screen = object.__new__(PatternDetailsScreen)
+        screen.context = {}
+        screen._PatternDetailsScreen__showDescriptor = ShowDescriptor(
+            id=7,
+            name="Demo",
+            year=1999,
+            quality=23,
+        )
+        screen._PatternDetailsScreen__pattern = None
+
+        widgets = {
+            "#showlabel": FakeStaticWidget(),
+            "#show_quality_hint": FakeStaticWidget(),
+        }
+        screen.query_one = lambda selector, _type=None: widgets[selector]
+
+        screen.on_mount()
+
+        self.assertEqual("7 - Demo (1999)", widgets["#showlabel"].value)
+        self.assertEqual("Show: 23", widgets["#show_quality_hint"].value)
+
+    def test_pattern_details_screen_show_quality_hint_is_hidden_when_pattern_quality_exists(self):
+        set_current_language("en")
+
+        screen = object.__new__(PatternDetailsScreen)
+        screen._PatternDetailsScreen__showDescriptor = ShowDescriptor(
+            id=7,
+            name="Demo",
+            year=1999,
+            quality=23,
+        )
+        screen._PatternDetailsScreen__pattern = type(
+            "_Pattern",
+            (),
+            {"quality": 19},
+        )()
+
+        self.assertEqual("", screen.getShowQualityHintText())
+
     def test_inspect_details_screen_handle_edit_pattern_refreshes_even_without_result(self):
         screen = object.__new__(InspectDetailsScreen)
 
@@ -695,6 +770,142 @@ class TagTableScreenStateTests(unittest.TestCase):
         self.assertIn("English Full", screen.tracksTable.rows["row-0"])
         self.assertIs(target_track, screen.getSelectedTrackDescriptor())
 
+    def test_inspect_details_screen_update_tracks_shows_attachment_format_and_blanks_language(self):
+        attachment_track = TrackDescriptor(
+            index=4,
+            source_index=4,
+            sub_index=0,
+            track_type=TrackType.ATTACHMENT,
+            attachment_format=AttachmentFormat.TTF,
+            tags={"filename": "font.ttf", "mimetype": "font/ttf"},
+        )
+
+        screen = object.__new__(InspectDetailsScreen)
+        screen.tracksTable = FakeTagTable()
+        screen._sourceMediaDescriptor = FakeMediaDescriptor([attachment_track])
+        screen._targetMediaDescriptor = None
+        screen._currentPattern = None
+        screen._trackRowData = {}
+        screen._applyNormalization = False
+
+        screen.updateTracks()
+
+        row = screen.tracksTable.rows["row-0"]
+
+        self.assertEqual("4", row[0])
+        self.assertEqual("TTF", row[3])
+        self.assertEqual(" ", row[5])
+        self.assertEqual(" ", row[7])
+        self.assertEqual(" ", row[8])
+
+    def test_inspect_details_screen_update_tracks_shows_unknown_for_unknown_attachment_format(self):
+        attachment_track = TrackDescriptor(
+            index=5,
+            source_index=5,
+            sub_index=0,
+            track_type=TrackType.ATTACHMENT,
+            attachment_format=AttachmentFormat.UNKNOWN,
+            tags={"filename": "blob.bin", "mimetype": "application/octet-stream"},
+        )
+
+        screen = object.__new__(InspectDetailsScreen)
+        screen.tracksTable = FakeTagTable()
+        screen._sourceMediaDescriptor = FakeMediaDescriptor([attachment_track])
+        screen._targetMediaDescriptor = None
+        screen._currentPattern = None
+        screen._trackRowData = {}
+        screen._applyNormalization = False
+
+        screen.updateTracks()
+
+        row = screen.tracksTable.rows["row-0"]
+
+        self.assertEqual("unknown", row[3])
+        self.assertEqual(" ", row[5])
+
+    def test_inspect_details_screen_uses_source_font_attachments_for_styled_ass(self):
+        class _Config:
+            def getData(self):
+                return {}
+
+        class _Pattern:
+            def __init__(self, media_descriptor):
+                self._media_descriptor = media_descriptor
+
+            def getMediaDescriptor(self, _context):
+                return self._media_descriptor
+
+        source_descriptor = MediaDescriptor(
+            track_descriptors=[
+                TrackDescriptor(
+                    index=0,
+                    source_index=0,
+                    sub_index=0,
+                    track_type=TrackType.SUBTITLE,
+                    codec_name=TrackCodec.ASS,
+                    tags={"title": "Styled Subtitle"},
+                ),
+                TrackDescriptor(
+                    index=1,
+                    source_index=1,
+                    sub_index=0,
+                    track_type=TrackType.ATTACHMENT,
+                    attachment_format=AttachmentFormat.TTF,
+                    tags={"filename": "current.ttf", "mimetype": "font/ttf"},
+                ),
+            ]
+        )
+        pattern_descriptor = MediaDescriptor(
+            track_descriptors=[
+                TrackDescriptor(
+                    index=0,
+                    source_index=0,
+                    sub_index=0,
+                    track_type=TrackType.SUBTITLE,
+                    codec_name=TrackCodec.ASS,
+                    tags={"title": "Styled Subtitle"},
+                ),
+                TrackDescriptor(
+                    index=1,
+                    source_index=1,
+                    sub_index=0,
+                    track_type=TrackType.ATTACHMENT,
+                    attachment_format=AttachmentFormat.TTF,
+                    tags={"filename": "old.ttf", "mimetype": "font/ttf"},
+                ),
+                TrackDescriptor(
+                    index=2,
+                    source_index=2,
+                    sub_index=1,
+                    track_type=TrackType.ATTACHMENT,
+                    attachment_format=AttachmentFormat.TTF,
+                    tags={"filename": "missing.ttf", "mimetype": "font/ttf"},
+                ),
+            ]
+        )
+
+        screen = object.__new__(InspectDetailsScreen)
+        screen.context = {"logger": get_ffx_logger(), "config": _Config()}
+
+        resolved_descriptor = screen._resolve_target_media_descriptor(
+            _Pattern(pattern_descriptor),
+            source_descriptor,
+        )
+        attachment_tracks = resolved_descriptor.getAttachmentTracks()
+
+        self.assertEqual(1, len(attachment_tracks))
+        self.assertEqual({"filename": "current.ttf", "mimetype": "font/ttf"}, attachment_tracks[0].getTags())
+
+        change_set = MediaDescriptorChangeSet(
+            screen.context,
+            resolved_descriptor,
+            source_descriptor,
+        ).getChangeSetObj()
+        self.assertNotIn(
+            1,
+            change_set.get("tracks", {}).get(DIFF_REMOVED_KEY, {}),
+        )
+
     def test_inspect_details_screen_maps_target_selection_back_to_source_track(self):
         source_track = TrackDescriptor(
             index=3,

tests/unit/test_track_descriptor_probe.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import unittest
+
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+
+from ffx.attachment_format import AttachmentFormat  # noqa: E402
+from ffx.track_codec import TrackCodec  # noqa: E402
+from ffx.track_descriptor import TrackDescriptor  # noqa: E402
+from ffx.track_type import TrackType  # noqa: E402
+
+
+class TrackDescriptorProbeTests(unittest.TestCase):
+    def test_attachment_without_codec_name_uses_font_metadata_to_identify_ttf(self):
+        descriptor = TrackDescriptor.fromFfprobe(
+            {
+                "index": 4,
+                "codec_type": "attachment",
+                "disposition": {"default": 0},
+                "tags": {
+                    "filename": "AmazonEmberTanuki-Italic.ttf",
+                    "mimetype": "font/ttf",
+                },
+            },
+            subIndex=0,
+        )
+
+        self.assertIsNotNone(descriptor)
+        self.assertEqual(TrackType.ATTACHMENT, descriptor.getType())
+        self.assertEqual(AttachmentFormat.TTF, descriptor.getAttachmentFormat())
+        self.assertEqual(AttachmentFormat.TTF, descriptor.getFormatDescriptor())
+        self.assertEqual(TrackCodec.UNKNOWN, descriptor.getCodec())
+
+    def test_attachment_without_codec_name_still_probes_as_unknown_when_not_font(self):
+        descriptor = TrackDescriptor.fromFfprobe(
+            {
+                "index": 9,
+                "codec_type": "attachment",
+                "disposition": {"default": 0},
+                "tags": {
+                    "filename": "cover.bin",
+                    "mimetype": "application/octet-stream",
+                },
+            },
+            subIndex=0,
+        )
+
+        self.assertIsNotNone(descriptor)
+        self.assertEqual(TrackType.ATTACHMENT, descriptor.getType())
+        self.assertEqual(AttachmentFormat.UNKNOWN, descriptor.getAttachmentFormat())
+        self.assertEqual(TrackCodec.UNKNOWN, descriptor.getCodec())
+
+if __name__ == "__main__":
+    unittest.main()