Metadata-Version: 2.4
Name: hevc-transcode
Version: 1.1.0
Summary: Watched-folder to HEVC conversion queue - with verification gates: a conversion only replaces/lands after structural, full-decode, content(SSIM) and read-back-hash checks pass.
Author: Hoelee Enterprise
License: MIT
Project-URL: Repository, https://git.hoelee.com/hoelee/hevc-transcode
Keywords: hevc,h265,transcode,ffmpeg,x265,nvenc,video,queue
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: license.json
Requires-Dist: PyYAML>=6.0
Requires-Dist: cryptography>=3.4
Requires-Dist: numpy>=1.24
Provides-Extra: measure
Requires-Dist: websocket-client>=1.6; extra == "measure"
Provides-Extra: desktop
Requires-Dist: pywebview>=5.0; extra == "desktop"
Requires-Dist: pystray>=0.19; extra == "desktop"
Requires-Dist: Pillow>=10.0; extra == "desktop"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# hevc-transcode

**A watched-folder → HEVC conversion queue that refuses to trust its own output.**

Point it at a folder. It probes every file, decides how each one should be converted (skip, remux,
CPU x265, or GPU NVENC), hands one item at a time to `ffmpeg`, and — this is the part that makes it
different from a `for f in *.mp4; do ffmpeg ...` script — **only installs a result that passed every
gate**:

| gate | what it catches |
|---|---|
| structural check | wrong container/codec tag (`hvc1`), wrong pixel format - i.e. "plays on my PC, not on the iPad" |
| full decode | a truncated or broken encode |
| content check (SSIM vs the source, per band) | an encode that is technically valid and visibly worse |
| read-back hash of the installed file | a network share / virtual mount that reported success while writing half the file |

If a gate fails, the source is left exactly as it was and the item goes back to the queue (with the
reason, and after a bounded number of tries, to a "needs a decision" list instead of burning the
machine forever).

---

## Install

Requirements: **Python 3.10+**, **FFmpeg on `PATH`** (`ffmpeg` *and* `ffprobe`), and the converter
engine (see below). No admin rights, no service, no NAS required.

**Windows only.** The process layer (Job Objects for the CPU cap, core affinity, kill-by-PID, the
logon launcher) is Windows-specific, and so are the accelerator backends this build drives — NVIDIA
NVENC, Intel QSV, AMD AMF. Linux VAAPI and macOS VideoToolbox are **not implemented**; `doctor` says
so on every run rather than leaving it to be discovered.

```bash
uv tool install "git+https://git.hoelee.com/hoelee/hevc-transcode"
# or, without uv:      pipx install "git+https://git.hoelee.com/hoelee/hevc-transcode"
# or from a checkout:  uv tool install .
```

That puts one command on your `PATH`: `hevc-transcode`.

The conversion itself is done by the **folder engine** (`library_run.py`), which is a separate
repository today. Point the install at it with `settings.engines.library` (`hevc-transcode init`
asks for it, and `doctor` refuses to let a conversion start without it).

## Quick start

```bash
hevc-transcode init --folder "D:\Videos\ToConvert"     # wizard: folders, output policy, work dirs
hevc-transcode doctor                                  # read-only; 0 FAIL means this machine can convert
hevc-transcode backends                                # really test each HEVC encoder (cached per ffmpeg build)
hevc-transcode start                                   # dashboard on http://127.0.0.1:8790/console
hevc-transcode scan                                    # enqueue what is in the folders
hevc-transcode status                                  # lanes, guards, queue - one screen
hevc-transcode pause                                   # stop at the item boundary (nothing is killed)
hevc-transcode resume                                  # carry on
hevc-transcode stop                                    # stop the supervisor (waits for the boundary)
```

Nothing converts until a lane is started, and the defaults are conservative: the dashboard shows
what each gate measured for every finished item.

## Where your converted files go (`output_mode`)

| mode | behaviour |
|---|---|
| **`folder`** (default) | results are written into `output_dir`, **the original is kept**. Layout: `<output_dir>/<job-id>/<relative path>.mp4` |
| `beside` | the verified result **replaces the original in place**. Only ever after every gate passed; a failure leaves the original untouched. |

`beside` is what this project's own install uses (it has been converting its library that way for
months, with the gates in front of it) — but it is a choice, not a default: replacing someone's only
copy has to be explicit, so `init` picks `folder` and `doctor` reports which mode is live.

```bash
hevc-transcode init --folder D:\Videos --output-mode beside   # explicit, and it says so
```

## A conversion is expensive; the queue is patient

* One item per lane, per lane type (`io` remux/audio, `cpu` x265, `gpu` NVENC). The engine takes its
  own per-tier lock, so a second run of the same tier backs off instead of racing on the output.
* Guards before every item: free space on the scratch drive, free space on the work drive, and
  commit headroom (a machine that is out of memory fails an encode *after* spending an hour on it).
* Pause has two meanings and the dashboard says which: **pause-after** stops at the item boundary,
  **pause-now** kills the running item's process tree (its row goes back to `pending`; the original
  is never touched).
* A restart is safe by design: rows left `running` are swept back to `pending`, their partial files
  are deleted, and the queue carries on.

## Configure

* `jobs.yaml` — the watched folders and the policy (which you edit, with comments explaining every
  number).
* `jobs.local.yaml` — machine-local overrides written by the dashboard (paths of *this* machine).
* the queue database's `settings` table — what the dashboard changes at runtime.

`hevc-transcode where` prints which files those are, and why. Point a second install at the same
state directory with `HEVC_TRANSCODE_HOME=<dir>`.

## Uninstall

```bash
hevc-transcode stop
uv tool uninstall hevc-transcode      # or: pipx uninstall hevc-transcode
```

Your media is untouched, and the state directory (config, queue, logs) is left where it is — delete
it yourself if you want it gone. `hevc-transcode where` tells you the path.

## Docs

* [`docs/INSTALL.md`](docs/INSTALL.md) — every install route, the first run, and the checks.
* [`docs/DESIGN.md`](docs/DESIGN.md) — why the lanes, skip taxonomy, pause semantics and gates work
  the way they do (the authority for *why*).
* [`docs/OPERATIONS.md`](docs/OPERATIONS.md) — the runbook, and the live status of this install.
* [`docs/archive/`](docs/archive/) — history: the original site-specific runbook (TubeSync library on a
  Synology NAS, Portainer, the DSM reverse proxy), the finished batch plans, and the old session state.
  None of it is needed for local-folder use.
