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.