diff --git a/.gitignore b/.gitignore index c624ec6..25d914e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ __pycache__/ *.py[cod] junk/ -.vscode .ipynb_checkpoints/ tools/ansible/inventory/hawaii.yml tools/ansible/inventory/peppermint.yml @@ -17,6 +16,7 @@ dist/ *.egg-info/ .venv/ venv/ +docs/_build/ .codex @@ -24,4 +24,4 @@ venv/ *.webm *.mp4 ffmpeg2pass-0.log -*.sup \ No newline at end of file +*.sup diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..6c7e62c --- /dev/null +++ b/.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" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..daa653b --- /dev/null +++ b/.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" +} diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md index 89eaddd..25f63bb 100644 --- a/SCRATCHPAD.md +++ b/SCRATCHPAD.md @@ -69,3 +69,11 @@ ## Delete When - Delete this scratchpad once the optimization backlog is either converted into issues/work items or distilled into durable project guidance. + + + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..38f13a3 --- /dev/null +++ b/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 ' where 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) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..7abda7a --- /dev/null +++ b/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: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..54a69b5 --- /dev/null +++ b/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 + diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..0d9281e --- /dev/null +++ b/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``. diff --git a/docs/esbonio.db b/docs/esbonio.db new file mode 100644 index 0000000..0de02ec Binary files /dev/null and b/docs/esbonio.db differ diff --git a/docs/file_formats.md b/docs/file_formats.md deleted file mode 100644 index 25f827c..0000000 --- a/docs/file_formats.md +++ /dev/null @@ -1,170 +0,0 @@ -# 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: - -```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: - -| 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/ diff --git a/docs/file_formats.rst b/docs/file_formats.rst new file mode 100644 index 0000000..df9af19 --- /dev/null +++ b/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/ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..bb60bc9 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,25 @@ +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: 2 + :caption: Contributor Guide + + development + api diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..a2bface --- /dev/null +++ b/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``. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2ec8f45 --- /dev/null +++ b/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 ^' where ^ is one of +echo html to make standalone HTML files +echo linkcheck to check all external links for integrity + +:end +popd diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..5599e8d --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,75 @@ +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`` and ``--subtitle-prefix`` for sidecar subtitle + imports +* ``--copy-video`` or ``--copy-audio`` to preserve selected stream types +* ``--rename-only`` for filename normalization without media rewriting + +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. diff --git a/pyproject.toml b/pyproject.toml index 1d50c85..6a75f42 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 = [ diff --git a/tests/prepare.sh b/tests/prepare.sh new file mode 100755 index 0000000..f5a3ec5 --- /dev/null +++ b/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 </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 "$@"