Skip to content

v0.2.11

Choose a tag to compare

View all tags
@github-actions github-actions released this 26 Apr 11:05
· 7 commits to main since this release
v0.2.11
e8daee9

vfo Installation and Quick Start

vfo is positioned as an autonomous media optimization engine:

  • input: mixed mezzanine libraries
  • decision layer: profile + scenario rules
  • output: deterministic, target-shaped media variants
  • verification: readiness/status observability and optional quality scoring gates

This release keeps that loop explicit for operators who want outcome ownership, not just batch transcoding.

Supported platforms (this release)

  • macOS 13+ (Apple Silicon ARM64 and Intel x64)
  • Linux/Windows installers are not yet published

Runtime requirements

  • Required:
    • ffmpeg (includes ffprobe)
    • mkvmerge (from mkvtoolnix)
  • Optional:
    • dovi_tool (recommended for Dolby Vision workflows)
    • ffmpeg with libvmaf filter (only if using QUALITY_CHECK_INCLUDE_VMAF=true)

vfo now checks required dependencies before pipeline execution and clearly reports what is missing.
Use vfo status or vfo status-json to inspect component/stage readiness before running the pipeline.
Use vfo visualize to generate local workflow artifacts (HTML + JSON + Mermaid).
vfo mezzanine-clean provides optional mezzanine folder/filename hygiene with probe-based recommendations.

CI automation (Codex loop v1)

  • Scheduled proactive sweep lane (read-only Codex audit issue updates).
  • Issue trigger lane via agent-ready label (bounded change proposal + PR creation).
  • Bounded failed-CI autofix lane for Codex-owned PRs only.
  • No unrestricted auto-merge and no production deploy automation.
  • Setup/guardrails: infra/docs/codex-autonomous-loop.md
  • Docs build + Pages deployment lane: .github/workflows/ci-docs-pages.yml
  • GHCR package lane: .github/workflows/ci-package-ghcr.yml (ghcr.io/<owner>/vfo)
  • Release deployment environments: release-stable and release-beta
  • Delivery model reference: infra/docs/github-delivery-lanes.md
  • GHCR quickstart:
    • docker pull ghcr.io/craigwatt/vfo:main
    • docker run --rm ghcr.io/craigwatt/vfo:main --version

Documentation site

  • Source: platform/docs-site/
  • Docs engine: zensical (using mkdocs.yml compatibility mode during migration)
  • Generated profile docs script: infra/scripts/generate-profile-docs.sh
  • Local build:
    • make docs-generate
    • make docs-build
  • Local preview:
    • make docs-serve
  • Published URL (after enabling GitHub Pages in repo settings):
    • https://craigwatt.github.io/vfo/

Desktop architecture scaffold (monorepo)

  • services/vfo/ remains the standalone CLI processing engine.
  • platform/vfo-desktop/ is scaffolded for Tauri runtime + React UI integration.
  • platform/vfo-contracts/ contains shared JSON schemas for status/progress/error payload contracts.
  • Desktop bridge command allowlist scaffold: platform/vfo-desktop/contracts/allowed-cli-commands.json

macOS (recommended: signed package)

  1. Download vfo_macOS_installer-v*.*.*.pkg from this release's assets.
  2. If macOS blocks first launch, right-click the package and choose Open.
  3. Complete the installer.
  4. Verify installation:
    • vfo --version
    • vfo doctor

Installed paths:

  • Binary: /usr/local/bin/vfo
  • Action scripts: /usr/local/bin/*.sh (for example transcode_*_profile.sh, profile_guardrail_skip.sh)
  • Config directory: /usr/local/bin/vfo_conf_folder
  • Config file: /usr/local/bin/vfo_conf_folder/vfo_config.conf
  • Stock presets: /usr/local/bin/vfo_conf_folder/presets/

macOS (advanced: static build zip)

  1. Download static_build.zip from assets and unzip it.
  2. Move static_build/bin/vfo and all static_build/bin/*.sh action scripts to /usr/local/bin.
  3. Create config directory and copy the default config:
    • sudo mkdir -p /usr/local/bin/vfo_conf_folder
    • sudo cp static_build/vfo_conf_folder/vfo_config.conf /usr/local/bin/vfo_conf_folder/vfo_config.conf
    • sudo cp -R static_build/vfo_conf_folder/presets /usr/local/bin/vfo_conf_folder/
  4. Verify installation:
    • vfo --version
    • vfo doctor

First-run workflow

  1. vfo wizard to generate or update config interactively.
    • wizard now supports onboarding modes: quickstart (recommended defaults) and advanced (full control)
    • wizard includes preflight checks (tool availability + config path permissions)
    • wizard writes config atomically and creates a timestamped backup before replacing an existing config
    • wizard supports stock preset pack multi-select (balanced_open_audio, device_targets_open_audio, netflixy_main_subtitle_intent)
  2. vfo show to review active config values.
  3. vfo doctor to validate paths and required tools.
  4. vfo status (or vfo status-json) to confirm engine readiness.
  5. vfo visualize to generate a local workflow report and formal-model references.
  6. vfo mezzanine-clean to audit (or apply) mezzanine naming/structure hygiene.
  7. vfo run to execute the default pipeline (including optional quality scoring when enabled).

Multi-location storage routing

  • MEZZANINE_LOCATIONS, SOURCE_LOCATIONS, and <PROFILE>_LOCATIONS support semicolon-separated paths.
  • MEZZANINE_LOCATION_MAX_USAGE_PCT, SOURCE_LOCATION_MAX_USAGE_PCT, and <PROFILE>_LOCATION_MAX_USAGE_PCT set per-path usage caps.
  • vfo routes writes by projected utilization and free-space reserve, then retries on alternate locations when a destination fails.

Optional mezzanine hygiene controls

  • MEZZANINE_CLEAN_ENABLED: enable/disable automatic mezzanine hygiene in vfo run.
  • MEZZANINE_CLEAN_APPLY_CHANGES: false = audit only, true = perform rename/move.
  • MEZZANINE_CLEAN_APPEND_MEDIA_TAGS: append tags like UHD/HDR10/HEVC/AAC to filenames.
  • MEZZANINE_CLEAN_STRICT_QUALITY_GATE: fail when mezzanine warnings are detected.

Optional post-profile quality scoring controls

  • QUALITY_CHECK_ENABLED: enable/disable quality scoring stage in vfo run.
  • QUALITY_CHECK_INCLUDE_VMAF: include VMAF when FFmpeg has libvmaf; otherwise PSNR/SSIM only.
  • QUALITY_CHECK_STRICT_GATE: fail run on threshold failures/missing references/metric errors.
  • QUALITY_CHECK_REFERENCE_LAYER: auto|source|mezzanine reference selection.
  • QUALITY_CHECK_MIN_PSNR: minimum PSNR threshold (0 disables threshold).
  • QUALITY_CHECK_MIN_SSIM: minimum SSIM threshold (0 disables threshold).
  • QUALITY_CHECK_MIN_VMAF: minimum VMAF threshold (0 disables threshold).
  • QUALITY_CHECK_MAX_FILES_PER_PROFILE: sample cap per profile (0 means all files).

Optional Dolby Vision profile conversion controls

  • VFO_DV_CONVERT_P7_TO_81: in transcode_hevc_4k_dv_profile.sh, convert DV profile 7 metadata to profile 8.1 (1 default).
  • VFO_DV_P7_TO_81_MODE: conversion mode passed to dovi_tool (2 default, 5 supported).
  • VFO_DV_REQUIRE_P7_TO_81: fail when profile 7 input cannot be converted to profile 8.x (1 default).

Optional legacy sub-HD subtitle-intent controls

  • transcode_hevc_legacy_main_subtitle_preserve_profile.sh: stock lane for old/sub-HD stragglers in the netflixy pack.
  • VFO_LEGACY_DEINTERLACE: auto|always|off (auto default).
  • VFO_LEGACY_AUTOCROP: enable/disable stable black-bar crop (1 default).
  • VFO_LEGACY_CROP_SAMPLE_SECONDS: crop-detect probe window per sample (3 default).
  • VFO_LEGACY_CROP_DETECT_LIMIT: crop-detect black threshold (24 default).
  • VFO_LEGACY_CROP_MIN_PIXELS: minimum removed pixels required before applying crop (8 default).

Troubleshooting

  • required command missing: ffmpeg/ffprobe:
    • brew install ffmpeg
  • required command missing: mkvmerge:
    • brew install mkvtoolnix
  • optional command missing: dovi_tool:
    • brew install dovi_tool
  • could not create config directory during vfo wizard:
    • run with elevated permissions, for example: sudo vfo wizard
  • Gatekeeper warning on .pkg:
    • right-click installer -> Open

Full Changelog: v0.2.10...v0.2.11

Assets 4
Loading