makemkv-workstation

Log | Files | Refs | README

CLAUDE.md (4145B)

      1 # CLAUDE.md
      2 
      3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
      4 
      5 ## What this project is
      6 
      7 An Ansible playbook that provisions a Debian desktop machine for Blu-ray/DVD archiving. It installs MakeMKV (via Flatpak), HandBrake, ffmpeg, a TigerVNC server with XFCE4, NFS client storage, and two ripping/encoding scripts.
      8 
      9 Target host: `192.168.0.118` (user `cjr`), defined in `inventory/hosts.yml`. Passwordless SSH access to this host is available (`ssh cjr@192.168.0.118`) — use it directly to inspect logs, run `rip`/`encode` diagnostics, query the disc via `makemkvcon`, etc.
     10 
     11 ## Running the playbook
     12 
     13 ```bash
     14 # Full provision
     15 ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
     16 
     17 # Run a specific role only
     18 ansible-playbook -i inventory/hosts.yml site.yml --tags vnc --ask-vault-pass
     19 ansible-playbook -i inventory/hosts.yml site.yml --tags flatpaks --ask-vault-pass
     20 ansible-playbook -i inventory/hosts.yml site.yml --tags nfs --ask-vault-pass
     21 ansible-playbook -i inventory/hosts.yml site.yml --tags scripts --ask-vault-pass
     22 ansible-playbook -i inventory/hosts.yml site.yml --tags update --ask-vault-pass
     23 
     24 # Dry run
     25 ansible-playbook -i inventory/hosts.yml site.yml --check --ask-vault-pass
     26 
     27 # Lint
     28 ansible-lint site.yml
     29 ```
     30 
     31 ## Secrets / vault
     32 
     33 `group_vars/all/vault.yml` is Ansible Vault-encrypted (AES256). It holds `vnc_password`. Always pass `--ask-vault-pass` when running the playbook. Never commit plaintext secrets.
     34 
     35 To edit vault contents:
     36 ```bash
     37 ansible-vault edit group_vars/all/vault.yml
     38 ```
     39 
     40 ## Architecture
     41 
     42 ### Role overview
     43 
     44 | Role | Purpose |
     45 |------|---------|
     46 | `system_update` | `apt dist-upgrade` + autoremove/autoclean |
     47 | `vnc` | TigerVNC on display `:5`, XFCE4 session, systemd service `vncserver@5` |
     48 | `flatpaks` | Flathub remote, MakeMKV + HandBrake flatpaks, DVD libs (`libdvdcss` via `libdvd-pkg`), `ffmpeg` |
     49 | `nfs` | Mounts NFS share `192.168.0.240:/mnt/Movies` → `/mnt/Movies` (persisted in fstab) |
     50 | `scripts` | Deploys `rip` and `encode` to `~/.scripts/` and adds it to `PATH` |
     51 
     52 ### Variables
     53 
     54 All non-secret variables live in `group_vars/all/vars.yml`. Role defaults are in `roles/vnc/defaults/main.yml` and are overridden by `group_vars`. The vault provides `vnc_password`.
     55 
     56 Key variables:
     57 - `vnc_user` / `vnc_uid` / `vnc_display` / `vnc_geometry` / `vnc_depth` — TigerVNC config (`vnc_uid` must match the actual UID of `vnc_user` on the target; default 1000)
     58 - `nfs_server` / `nfs_export` / `nfs_mountpoint` / `nfs_opts` — NFS mount config
     59 
     60 ### Rip database
     61 
     62 `/mnt/Movies/.rip.db` is a SQLite database that tracks every completed rip. Before ripping, `rip` checks the disc's label against this database and prompts if a duplicate is detected. To query it:
     63 
     64 ```bash
     65 sqlite3 /mnt/Movies/.rip.db "SELECT title, output_file, ripped_at FROM rips ORDER BY ripped_at DESC;"
     66 ```
     67 
     68 ### The rip/encode pipeline
     69 
     70 `rip.sh` and `encode.sh` are deployed to `~/.scripts/` on the target. They form a two-step pipeline:
     71 
     72 1. **`rip [disc] [title] [crf] [--software] [--name "Movie Title"]`** — verifies `/dev/sr0` exists and a disc is actually readable in it, queries the disc title via `makemkvcon info` (auto-names the output), prompts for a name override (falls back to the auto-detected name after a 60s timeout so it never hangs unattended), extracts an MKV to `/mnt/Movies`, calls `encode` on the result, then ejects the disc. `--name` overrides the auto-detected title.
     73 2. **`encode <input.mkv> [output.mkv] [crf] [--software]`** — transcodes to x265 using VA-API hardware encoding (`hevc_vaapi` on `/dev/dri/renderD128`) by default, or `libx265` software with `--software`. Strips non-English audio and subtitle tracks via `ffprobe` stream inspection.
     74 
     75 The user (`cjr`) is added to the `video` and `render` groups by the VNC role to enable GPU access for VA-API. `/dev/sr0` access is a static `cdrom` group grant (`cjr` is already a member) — not tied to any login session, so `rip` works the same whether run over SSH, VNC, or a background service.
     76 
     77 MakeMKV Flatpak is granted access to `home` and `/mnt/Movies` via `flatpak override`.