OpenTranscode(v4)

v4 adds: real end-to-end stability verification (caught a real bug!), CLI argument parsing, package split into opentranscode/, and pyproject.toml ready for PyPI (publishing deferred until maintainer confirms stability).

Quick start

Option A: Install as a package (recommended)

cd /path/to/this/directory
pip install -e .                   # editable install (dev)
# OR
pip install -e ".[dev]"            # with pytest + build tools

# Now you can run it three ways:
opentranscode                       # console entry point
python -m opentranscode             # module entry point
python -m opentranscode --version   # → opentranscode 3.0.0

Option B: Run the single-file v3 (backwards compat)

python open-transcode.v3.py         # the v3 single-file version still works

Option C: Verify your environment without encoding

opentranscode --dry-run             # probe env + smoke test, no GUI, no encode
opentranscode --verify-only /path/to/existing_output.mkv   # re-verify an output

Files

Path	Description
opentranscode/	v4 package — 16 modules, 5,744 lines. Importable as import opentranscode.
pyproject.toml	PEP 621 build config. Entry point: opentranscode = opentranscode.__main__:main. Ready for pip install -e . and python -m build. Not yet published to PyPI.
tests/	70 tests across 10 files: 24 mocked unit tests + 10 real-ffmpeg e2e tests + 36 package-structure tests. All pass in ~9s.
open-transcode.v3.py	Single-file v3 (5,370 lines). Kept for backwards compat + as the test target for the mocked tests.
open-transcode.v2.py	Single-file v2 (4,874 lines). Kept for diff reference.
OpenTranscode_QA_Report.pdf	The master QA report (26 pages).
pytest.ini	pytest config (also in pyproject.toml).
README.md	This file.

v4 changes (3 items)

ID	Severity	Description
v4-01	Critical bug fix	Real end-to-end tests caught a bug in _probe_ffmpeg_libs: the search strings for libsvtav1 and libaom were wrong (used _ instead of nothing/hyphen). This caused the probe to report False for both even when installed, which would have made _handle_vs_incompat tell users "ffmpeg also lacks libsvtav1" and abort — even though ffmpeg actually had it. Fixed in v3 + v4. The e2e test test_probe_detects_ffmpeg_libs is the regression guard.
v4-02	Feature	CLI argument parsing: --version, --dry-run, --verify-only PATH, --help. Lets users verify their setup without committing to a full encode.
v4-03	Architectural	Split single-file v3 (5,370 lines) into opentranscode/ package (16 modules, 5,744 lines). Dependency graph is acyclic; import opentranscode works without PySide6 installed (lazy imports).
v4-04	Packaging	pyproject.toml — PEP 621 compliant, entry point opentranscode = opentranscode.__main__:main. pip install -e . works. python -m build produces sdist+wheel. NOT published to PyPI (per maintainer request).
v4-05	Test coverage	36 new package-structure tests verifying: metadata, submodule imports, public API surface, CLI parser, FFMPEG_LIB_KEY_MAP, DISTRO_REGISTRY (6 entries), entry points.
v4-06	Docs	This README.

The critical v4-01 fix (in detail)

The e2e test suite runs REAL ffmpeg encodes and verifies the output files. The first run caught this bug:

# v3 (BUGGY):
checks = [
    ("libsvtav1", ["libsvt_av1", "svt_av1"]),   # WRONG — ffmpeg prints "libsvtav1"
    ("libaom",    ["libaom_av1", "aom_av1"]),   # WRONG — ffmpeg prints "libaom-av1"
    ...
]

# v4 (FIXED):
checks = [
    ("libsvtav1", ["libsvtav1 ", "libsvt_av1", "svt_av1 "]),   # correct + backward compat
    ("libaom",    ["libaom-av1 ", "libaom_av1", "aom_av1 "]),
    ...
]

Impact without the fix: When av1an's VSScript is broken (the common case that triggers the ffmpeg fallback path), the user clicks ENCODE, the smoke test correctly fails, the code checks if ffmpeg has libsvtav1 to offer fallback — but _probe_ffmpeg_libs returns False (because the search string doesn't match), so the user sees:

ABORT: ffmpeg also lacks libsvtav1. Install the encoder binary (e.g. SvtAv1EncApp, vpxenc, x265) or use the REBUILD FROM GIT button.

...even though ffmpeg -encoders clearly shows libsvtav1 is available. The user would then spend time installing SvtAv1EncApp or rebuilding from git, neither of which is necessary. With the fix, the fallback dialog correctly offers "Use ffmpeg Fallback" and the encode proceeds.

Test suite

cd /path/to/this/directory
python -m pytest tests/ -v

# 70 tests, ~9 seconds:
#   24 mocked unit tests (test_smoke_test, test_encode_pipeline, etc.)
#   10 real-ffmpeg e2e tests (test_e2e_real_encode) — requires ffmpeg + ffprobe
#   36 package-structure tests (test_package_structure)

The e2e tests generate a real 2-second test video with ffmpeg, run the full EncoderWorker pipeline on it (AV1→MKV, x265→MKV, VP9→WebM), and verify the output file exists, is non-empty, has the correct codec, and has the expected duration. If these tests pass, the "actually producing files" requirement is met.

What's deferred

Per the maintainer's request, PyPI publishing is on hold until production stability is confirmed on a real desktop Linux system with av1an + VapourSynth installed. The pyproject.toml is ready; when the maintainer is ready to publish:

python -m build               # produces dist/opentranscode-3.0.0.tar.gz + .whl
twine upload dist/*           # publishes to PyPI

Verification (run these to confirm v4 works)

# 1. Package imports cleanly
python -c "import opentranscode; print(opentranscode.__version__)"  # → 3.0.0

# 2. CLI works
python -m opentranscode --version        # → opentranscode 3.0.0
python -m opentranscode --help           # → usage
python -m opentranscode --dry-run        # → env probe report (if ffmpeg installed)

# 3. All tests pass
python -m pytest tests/ -q               # → 70 passed in ~9s

# 4. Install works
pip install -e .                         # → installs opentranscode + PySide6
opentranscode --version                  # → opentranscode 3.0.0

# 5. Single-file v3 still works (backwards compat)
python open-transcode.v3.py              # → launches GUI (if PySide6 + display)