diff --git a/.clang-tidy b/.clang-tidy index 10e6259..d9c53e6 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -1,14 +1,18 @@ --- # Lint for the project libraries (make tidy). Naming conventions from ADR-0001. +# Keep the gate stable across rolling Arch clang-tidy versions: signed API masks and shifts, +# and local const suggestions added in newer releases need a separate review before enabling. Checks: > -*, bugprone-*, -bugprone-easily-swappable-parameters, + -bugprone-signed-bitwise, cert-err58-cpp, concurrency-*, cppcoreguidelines-pro-type-member-init, cppcoreguidelines-slicing, misc-*, + -misc-const-correctness, -misc-include-cleaner, -misc-non-private-member-variables-in-classes, -misc-no-recursion, @@ -41,6 +45,8 @@ CheckOptions: - { key: readability-identifier-naming.ProtectedMemberSuffix, value: _ } - { key: readability-identifier-naming.ConstexprVariableCase, value: CamelCase } - { key: readability-identifier-naming.ConstexprVariablePrefix, value: k } + # Frame rates spell their value: frame_rates::k23_976, k29_97, k59_94 (base/time.hpp). + - { key: readability-identifier-naming.ConstexprVariableIgnoredRegexp, value: '^k[0-9]+_[0-9]+$' } - { key: readability-identifier-naming.GlobalConstantCase, value: CamelCase } - { key: readability-identifier-naming.GlobalConstantPrefix, value: k } ... diff --git a/.github/rulesets/master.json b/.github/rulesets/master.json new file mode 100644 index 0000000..64fe139 --- /dev/null +++ b/.github/rulesets/master.json @@ -0,0 +1,44 @@ +{ + "name": "Protect master", + "target": "branch", + "enforcement": "active", + "bypass_actors": [ + { + "actor_id": 5, + "actor_type": "RepositoryRole", + "bypass_mode": "always" + } + ], + "conditions": { + "ref_name": { + "include": ["refs/heads/master"], + "exclude": [] + } + }, + "rules": [ + {"type": "deletion"}, + {"type": "non_fast_forward"}, + {"type": "required_linear_history"}, + { + "type": "pull_request", + "parameters": { + "allowed_merge_methods": ["squash", "rebase"], + "dismiss_stale_reviews_on_push": false, + "require_code_owner_review": false, + "require_last_push_approval": false, + "required_approving_review_count": 0, + "required_review_thread_resolution": true + } + }, + { + "type": "required_status_checks", + "parameters": { + "required_status_checks": [ + {"context": "ci"}, + {"context": "conventional commits"} + ], + "strict_required_status_checks_policy": true + } + } + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4cff0de..4060799 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,19 +1,27 @@ name: CI +# Independent jobs run in parallel; `ci` gates on all of them (one required check for branch +# protection). The release workflow calls this workflow before it publishes anything. on: push: branches: [master] pull_request: + workflow_call: permissions: contents: read +concurrency: + # A newer push to the same pull request replaces the run in progress; master and tags never do. + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: # Arch Linux container: same toolchain as Omarchy (current GCC/Clang). # The container runs through `docker run` so the host kernel can be tuned first: # ThreadSanitizer fails with the default mmap entropy of recent runners. test: - name: ${{ matrix.compiler }} / ${{ matrix.build }} + name: test ${{ matrix.compiler }} / ${{ matrix.build }} runs-on: ubuntu-latest strategy: fail-fast: false @@ -22,20 +30,10 @@ jobs: build: [debug, asan, tsan, release] steps: - uses: actions/checkout@v7 - - name: Lower mmap_rnd_bits for TSan run: sudo sysctl -w vm.mmap_rnd_bits=28 - - name: Build and test - run: | - docker run --rm --cap-add SYS_PTRACE \ - -v "$PWD:/src" -w /src archlinux:latest bash -euo pipefail -c ' - pacman -Syu --noconfirm >/dev/null - scripts/deps.sh --install --noconfirm >/dev/null - make -j"$(nproc)" BUILD=${{ matrix.build }} CXX=${{ matrix.compiler }} \ - test JUNIT_DIR=build/junit - ' - + run: bash scripts/ci-run.sh test '${{ matrix.compiler }}' '${{ matrix.build }}' - name: JUnit reports if: always() uses: actions/upload-artifact@v7 @@ -44,17 +42,61 @@ jobs: path: build/junit/ if-no-files-found: ignore - lint: - name: format and clang-tidy + smoke: + name: GUI smoke (headless sway, lavapipe) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - name: Run the GUI smoke on a headless compositor + run: bash scripts/ci-run.sh smoke + + format: + name: clang-format runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - - name: clang-format and clang-tidy + - name: Check formatting + run: bash scripts/ci-run.sh format + + tidy: + name: clang-tidy + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - name: clang-tidy on the libs + run: bash scripts/ci-run.sh tidy + + includes: + # Plain grep over the sources: no container or dependencies needed. + name: include rules + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - name: Check include placement + run: scripts/check-includes.sh + + fuzz: + name: fuzz ${{ matrix.target }} (libFuzzer, ASan/UBSan) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + target: [cube, project, subtitles, otio, edl, mlt, fcpxml, probe] + steps: + - uses: actions/checkout@v7 + - name: Fuzz one parser of untrusted files + run: bash scripts/ci-run.sh fuzz '${{ matrix.target }}' + + ci: + # Fails unless every job above succeeded (a skipped or cancelled job fails it too). + name: ci + if: always() + needs: [test, smoke, format, tidy, includes, fuzz] + runs-on: ubuntu-latest + steps: + - name: All jobs passed + env: + RESULTS: ${{ join(needs.*.result, ' ') }} run: | - docker run --rm -v "$PWD:/src" -w /src archlinux:latest bash -euo pipefail -c ' - pacman -Syu --noconfirm >/dev/null - scripts/deps.sh --install --noconfirm >/dev/null - make format-check - make compdb - make tidy - ' + echo "results: $RESULTS" + for r in $RESULTS; do [[ $r == success ]] || exit 1; done diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ecfa31e..8a5be61 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,49 +1,135 @@ name: Release -# Tag vX.Y.Z (or vX.Y.Z-rc.N) → release build + tests → GitHub Release with notes generated -# from Conventional Commits and the source tarball. App binaries are added once the app -# exists (M6/M7), as ---linux.tar.gz, the layout OmaStore expects. +# Tag vX.Y.Z (or vX.Y.Z-rc.N) → a GitHub Release with notes generated from Conventional Commits, +# the source tarball and the app as omamovie--x86_64-linux.tar.gz (the tree +# `make install` lays out under usr/, which omastore.toml points OmaStore at). Qt 6, FFmpeg and +# Vulkan stay system libraries (Arch packages, PKGBUILD depends). +# +# A tag is checked before the full CI, source, and app jobs run. `publish` starts a draft, +# verifies its assets, and makes it public only after every prerequisite succeeds. on: push: tags: ['v*.*.*'] permissions: - contents: write + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false jobs: - release: + validate: + name: release tag runs-on: ubuntu-latest steps: + - name: Accept only version or release-candidate tags + env: + TAG: ${{ github.ref_name }} + run: | + [[ $TAG =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-rc\.[1-9][0-9]*)?$ ]] - uses: actions/checkout@v7 with: fetch-depth: 0 - - - name: Build and test (release) + - name: Require the tagged commit on master run: | - docker run --rm -v "$PWD:/src" -w /src archlinux:latest bash -euo pipefail -c ' - pacman -Syu --noconfirm >/dev/null - scripts/deps.sh --install --no-dev --noconfirm >/dev/null - make -j"$(nproc)" BUILD=release test - ' + git fetch origin master --no-tags + bash scripts/require-release-commit.sh HEAD origin/master + + ci: + needs: validate + uses: ./.github/workflows/ci.yml + source: + name: notes and source tarball + needs: validate + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 - name: Release notes and source tarball run: | tag="${GITHUB_REF_NAME}" version="${tag#v}" - scripts/changelog.sh "$tag" > release-notes.md - git archive --format=tar.gz --prefix="oma-movie-${version}/" -o "oma-movie-${version}-src.tar.gz" "$tag" - sha256sum "oma-movie-${version}-src.tar.gz" > "oma-movie-${version}-src.tar.gz.sha256" - cat release-notes.md + mkdir dist + scripts/changelog.sh "$tag" > dist/release-notes.md + git archive --format=tar.gz --prefix="oma-movie-${version}/" -o "dist/oma-movie-${version}-src.tar.gz" "$tag" + (cd dist && sha256sum "oma-movie-${version}-src.tar.gz" > "oma-movie-${version}-src.tar.gz.sha256") + cat dist/release-notes.md + - uses: actions/upload-artifact@v7 + with: + name: release-source + path: dist/ + if-no-files-found: error + app: + name: app tarball (release build, tested) + needs: validate + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - name: Build, test and install (release) + run: bash scripts/ci-run.sh release + - name: App tarball + run: | + version="${GITHUB_REF_NAME#v}" + app="omamovie-${version}-x86_64-linux.tar.gz" + mkdir dist + tar --owner=0 --group=0 -C stage -czf "dist/$app" usr + (cd dist && sha256sum "$app" > "$app.sha256") + - uses: actions/upload-artifact@v7 + with: + name: release-app + path: dist/ + if-no-files-found: error + + publish: + name: publish + needs: [validate, ci, source, app] + runs-on: ubuntu-latest + permissions: + contents: write + id-token: write + attestations: write + artifact-metadata: write + steps: + - uses: actions/download-artifact@v8 + with: + pattern: release-* + path: dist + merge-multiple: true + - name: Verify release archives + run: | + version="${GITHUB_REF_NAME#v}" + (cd dist && sha256sum -c "oma-movie-${version}-src.tar.gz.sha256" \ + "omamovie-${version}-x86_64-linux.tar.gz.sha256") + - name: Attest release archives + uses: actions/attest@v4 + with: + subject-path: dist/*.tar.gz - name: Publish release env: GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} run: | tag="${GITHUB_REF_NAME}" version="${tag#v}" prerelease="" if [[ $tag == *-* ]]; then prerelease="--prerelease"; fi - gh release create "$tag" $prerelease \ + gh release create "$tag" --draft --verify-tag $prerelease \ --title "OmaMovie ${version}" \ - --notes-file release-notes.md \ - "oma-movie-${version}-src.tar.gz" "oma-movie-${version}-src.tar.gz.sha256" + --notes-file dist/release-notes.md \ + dist/oma-movie-${version}-src.tar.gz dist/oma-movie-${version}-src.tar.gz.sha256 \ + dist/omamovie-${version}-x86_64-linux.tar.gz dist/omamovie-${version}-x86_64-linux.tar.gz.sha256 + assets="$(gh release view "$tag" --json assets,isDraft)" + jq -e --arg version "$version" ' + .isDraft == true and + ([.assets[].name] | sort) == ([ + "oma-movie-\($version)-src.tar.gz", + "oma-movie-\($version)-src.tar.gz.sha256", + "omamovie-\($version)-x86_64-linux.tar.gz", + "omamovie-\($version)-x86_64-linux.tar.gz.sha256" + ] | sort) + ' <<<"$assets" + gh release edit "$tag" --draft=false diff --git a/CLAUDE.md b/CLAUDE.md index 76257df..09a6655 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,813 +1,111 @@ -# CLAUDE.md — OmaMovie - -Operational guide for coding agents working in this repository. It defines engineering -rules, architectural invariants, priorities and conventions. It is not user documentation. - -> **Simple UI, serious pipeline.** -> The UI may hide complexity. The architecture may not pretend it does not exist. - ---- - -## 0. Repository status - -- **M0 done** (2026-10-02): GNU Make build, `libs/base` (rational time, `Result`/`Error`, - logging, job system), tests with Cest, CI and ADRs 0001–0003. The other libs, the app - and the tools do not exist yet. -- The structure, commands and decisions below are the **target**. When creating something - this document describes, follow it. When diverging, record why in an ADR (§20) and - update this file in the same commit. -- Keep §3 (Commands) in sync with reality. A documented command that does not work is a bug. -- What to build and in which order: `Docs/implementation-plan.md`. The research behind the - decisions lives in `Docs/Research/`. -- **All repository content is written in English**: docs, READMEs, ADRs, code comments, - log messages, CI step names and commit messages. - ---- - -## 1. Identity and naming - -| Item | Name | -|---|---| -| Product | `OmaMovie` | -| Repository | `oma-movie` | -| Main executable | `omamovie` | -| Reusable libraries | `oma-media`, `oma-timeline`, `oma-compositor`, `oma-project`, … | -| Project CLI | `oma-project` | -| Root C++ namespace | `oma::` (one sub-namespace per module: `oma::media`, `oma::timeline`, …) | - -**Forbidden:** `OmaVideo`, `omavideo`, `oma-video` anywhere (code, docs, file names, log messages). - -Target platform: **Omarchy** (Arch Linux + Hyprland, Wayland). The project is **not -cross-platform**. Do not add portability layers for Windows/macOS, nor X11 paths. It is fine -to assume a recent toolchain (current Arch GCC/Clang), recent Qt 6, recent Mesa/NVIDIA, -PipeWire and Wayland. - ---- - -## 2. Scope - -### Goals -Non-destructive editing · multitrack timeline · GPU compositing (Vulkan) · real-time -playback · GPU-first pipeline · modern formats · importing projects from other NLEs · -modular architecture · Omarchy integration · simple, contextual UI · growth without -rewriting the core. - -### Non-goals (until an explicit decision says otherwise) -- a Premiere clone or an After Effects–style compositor; -- full motion graphics, advanced multicam, complex tracking; -- AI without a concrete use case; -- cloud, remote collaboration; -- **a third-party plugin system** before the architecture stabilizes; -- writing proprietary third-party formats before the parser is well understood. - -If a task pushes toward a non-goal, stop and ask. - ---- - -## 3. Commands - -GNU Make build (ADR-0001). `make help` lists everything. - -```sh -make deps # install every dependency declared in the PKGBUILD (sudo pacman) -make -j # libs + tests + compile_commands.json (BUILD=debug) -make -j test # build and run the tests (generates the fixtures first) -make -j test FILTER=rescale # only tests whose name contains the pattern -make -j BUILD=asan test # AddressSanitizer + UBSan (third-party suppressions: tests/support/) -make -j BUILD=tsan test # ThreadSanitizer -make -j BUILD=release test # -O2 -make -j CXX=clang++ test # another compiler (CI runs g++ and clang++) -make format | make format-check -make tidy # clang-tidy on the libs (warnings are errors) -make fixtures # regenerate test media in tests/fixtures/generated/ (ffmpeg) -make spikes # M1 spikes in tools/spikes (Docs/spikes/) -makepkg -si # build and install the Arch package from the PKGBUILD -``` - -Commits and releases: - -```sh -scripts/check-commits.sh origin/master..HEAD # validate Conventional Commits before pushing -git tag v0.1.0 && git push origin v0.1.0 # triggers the release workflow -``` - -- **Conventional Commits in English**, imperative mood, no trailing period, at most 100 - characters: `(): `. Types: `feat fix docs style refactor perf test - build ci chore revert`. Scope = lib or area (`base`, `media`, `timeline`, `ui`, `research`, - `adr`...). `!` marks a breaking change. -- **Microcommits**: one commit per coherent change that builds and passes the tests on its - own. Do not mix refactoring with features, nor docs with code, in one commit. -- CI validates commit messages (`.github/workflows/commits.yml`), builds and tests with - g++/clang++ × debug/asan/tsan/release (`ci.yml`). `vX.Y.Z` tags produce a release with - notes built from the commits (`release.yml`, `scripts/changelog.sh`). - -Target commands, not available yet: - -```sh -# Run -./build/debug/apps/omamovie/omamovie - -# Project CLI -./build/debug/tools/oma-project/oma-project inspect - -# Benchmarks -./build/release/tools/bench/oma-bench --scenario --json out.json -``` - -Before declaring a task done: `make test` passes without new warnings, and concurrent -changes also pass with `BUILD=tsan`. If you did not run the tests, say so. - ---- - -## 4. Stack - -| Layer | Technology | Notes | -|---|---|---| -| Core | C++23 | `std::expected`, `std::span`, concepts. Arch compilers support it. | -| Build | Non-recursive GNU Make (`Makefile` + one `module.mk` per lib) | ADR-0001. **Do not use CMake.** | -| Tests | Cest (`third_party/cest`, header-only) | ADR-0001; rules in §25. | -| UI | Qt 6 Quick / QML | Presentation and interaction only. | -| Media | FFmpeg (libavformat/codec/util/filter/swresample) | Wrapped by `oma-media`. | -| GPU / compositing | Vulkan | Main graphics backend. | -| Compute | Vulkan Compute, CUDA, CPU | Behind `ComputeBackend`. **No OpenCL** (§9.3). | -| Audio | PipeWire | System integration. **Do not use OpenAL** as the foundation. | -| Structured data | SQLite | Only where justified (§17). | -| Crypto | OpenSSL | Only for real cryptographic needs. Content hashing alone does not require OpenSSL. | - -**Dependencies are declared in the `PKGBUILD`** (single source of truth): `depends` for what -shipped code uses at runtime, `makedepends`/`checkdepends` for building and testing the -package, and `_devdepends` for development-only tools. `scripts/deps.sh` and CI install from -it; never list packages anywhere else (README, CI files, scripts). Move a package from -`_devdepends` to `depends` when shipped code starts using it. - -**New dependencies:** any dependency not listed here needs a justification in the commit/PR -(problem solved, alternatives considered, build/runtime cost) and an entry in the `PKGBUILD`. -A large dependency needs an ADR. Do not add a framework to solve a trivial problem. - -Fuzzing with libFuzzer (Clang). - ---- - -## 5. Module architecture - -### 5.1 Layout - -``` -oma-movie/ - apps/ - omamovie/ # Qt Quick executable. Wires everything together. QML + C++ bridge. - libs/ - base/ # Result/Error, logging, time (RationalTime), utilities. No Qt. - gpu/ # Vulkan device, memory, sync, interop (DMA-BUF, CUDA). No Qt. - media/ # oma-media: probe, demux, decode, encode, mux, frames, hwaccel. - audio/ # Mixer, resampling, clock, PipeWire output. - compositor/ # Render graph + Vulkan compositor + effects. - timeline/ # Timeline model, editing operations, undo/redo. - project/ # Native format, serialization, migration. - project-ir/ # ProjectIR: neutral intermediate representation. - importers/ # One subdirectory per external format -> ProjectIR. - tools/ - oma-project/ # CLI: inspect, dump, diff, validate, convert. - bench/ # Pipeline benchmarks. - tests/ - / # Cest tests for each lib (module.mk + main.cpp + test_*.cpp). - support/ # oma_test.hpp: the Cest entry point for tests. - fixtures/ # Small, reproducible fixtures + generator scripts. - third_party/ # Vendored, pinned third-party code (cest/). - scripts/ # Repository scripts (commit check, changelog). - Makefile # Build; each lib has libs//module.mk. - PKGBUILD # Arch package and the single source of truth for dependencies. - Docs/ - adr/ # Architecture Decision Records. - Research/ # Product/UX and technology research (non-normative). -``` - -`libs/base` and `libs/gpu` were not in the original sketch: `base` keeps time, errors and -logging from being duplicated or coupled to Qt; `gpu` lets the compositor, compute and decode -interop share one `VkDevice` without `media` depending on `compositor`. The structure may -change with a recorded technical justification. - -### 5.2 Dependency rules (invariants) - -``` -base <- gpu <- media <- compositor -base <- audio -base <- timeline (timeline does NOT depend on gpu, concrete media, compositor or Qt) -base <- project-ir (project-ir does NOT depend on timeline, project or importers) -project-ir <- importers (importers do NOT depend on OmaMovie's internal model) -timeline, project-ir <- project -everything <- apps/omamovie, tools/* -``` - -- The Makefile enforces this graph (`ALLOWED_DEPS_`): a forbidden dependency fails the build. -- **Qt only in `apps/` and in explicitly marked bridge code.** The libs (`base`, `gpu`, - `media`, `timeline`, `project-ir`, `project`, `importers`) do not include Qt headers. This - keeps `oma-media` separable and testable without a UI. Possible exception: the Qt RHI ↔ - Vulkan integration, which lives in the app (§9.4). -- **No Vulkan, CUDA or FFmpeg includes in the public headers of `timeline`, `project`, - `project-ir` or `importers`.** -- FFmpeg headers (`libav*`) appear only inside `libs/media` (and in `tools/` if needed for - diagnostics). -- Dependency cycles between libs are forbidden. If one appears, the design is wrong. -- Each lib exposes its public API in `include/oma//` and hides its implementation in `src/`. - ---- - -## 6. Time representation (critical invariant) - -**Never use `float`/`double` as the primary time representation.** Doubles are allowed only -for display in the UI and for disposable derived values. - -Types in `libs/base` (implemented, ADR-0002): - -- `Rational` — `num/den` in `int64`, always normalized, `den > 0`. -- `RationalTime` — an instant: `value * timebase` seconds. -- `TimeRange` — half-open interval `[start, start + duration)`. -- `FrameRate` (rational: 30000/1001, not 29.97) and `SampleRate` as distinct types. - -Rules: -1. **Conversions are explicit** and specify rounding (`Floor`, `Ceil`, `Nearest`). No - implicit conversion between timebases. -2. Rescale with 128-bit arithmetic (`__int128`); detect overflow, never truncate silently. -3. Compare times in different timebases only through the exact comparison. -4. **Do not assume CFR.** Frames are located by PTS, never by `index * frame_duration` in - arbitrary media. VFR is the normal case. -5. Audio is addressed in samples (sample-accurate). Audio editing must not be quantized to - the video frame grid. -6. The timeline has its own timebase (project/sequence). Each clip maps timeline time → - media time through an explicit `TimeMap` (including speed and speed ramps, ADR-0002). -7. Timestamps from FFmpeg (`AVRational`, `AV_NOPTS_VALUE`) are converted at the `oma-media` - boundary; `AV_NOPTS_VALUE` becomes an empty `std::optional`, not a magic number. - -Time conversion tests are mandatory and must cover: 23.976/29.97/59.94, 44.1k/48k/96k, large -values (hours of media in a 90 kHz timebase), rounding and overflow. - ---- - -## 7. GPU-first pipeline - -The GPU compositor is part of the fundamental architecture, not a future optimization. - -### 7.1 Target path - -``` -compressed media -> demux -> HW decode -> GPU surface -> Vulkan compositor -> effects -> preview - \-> HW encode (export) -``` - -### 7.2 Forbidden anti-pattern in playback/export paths - -``` -CPU decode -> upload -> process -> download -> upload again -``` - -Any GPU→CPU readback on the hot path needs an explicit justification in a comment and must be -visible in profiling and in the `gpu` log category. - -### 7.3 Decode per vendor (investigate and validate before committing) - -| Hardware | Preferred path | Vulkan interop | -|---|---|---| -| Intel / AMD | VA-API through FFmpeg hwaccel, or Vulkan Video | DMA-BUF export → Vulkan import (`VK_EXT_external_memory_dma_buf`, `VK_EXT_image_drm_format_modifier`) | -| NVIDIA | NVDEC (FFmpeg `cuda` hwaccel), or Vulkan Video | CUDA ↔ Vulkan external memory/semaphores (`VK_KHR_external_memory_fd`, `cuImportExternalMemory`) | -| Any | FFmpeg Vulkan hwaccel (Vulkan Video decode) | Native, if the driver supports the codec | -| Fallback | Software decode | A single upload to the GPU through a reused staging buffer | - -- Detect capabilities at runtime (codec × profile × resolution × bit depth × driver) and log - the chosen path and why. -- A software fallback is mandatory and must work; the HW path is not the only path. -- Encode: VA-API, NVENC, Vulkan Video encode when mature; software fallback (e.g. - libx264/libx265/SVT-AV1). - -### 7.4 Color - -- YUV→RGB conversion in the shader, honoring the stream's matrix, range (limited/full), - primaries and transfer. Never assume BT.709 limited without reading the metadata. -- Support 10-bit (P010 and similar) from the frame format design onward. -- The compositor's working space (e.g. linear float16) is an ADR decision. Blending happens - in the space defined there, not "wherever it works". - ---- - -## 8. oma-media - -A reusable layer, separable from the app. Responsible for: probing, demux, decode, encode, -mux, GPU/CPU frame abstraction, frame lifetime and synchronization, hardware acceleration, -conversion. - -Rules: -- **No FFmpeg calls outside `libs/media`.** -- Abstractions must have architectural value (lifetime, threading, backend selection, strong - types). Do **not** write one-line wrappers that only rename FFmpeg functions. Inside - `libs/media`, using the FFmpeg API directly is fine. -- FFmpeg resources are RAII: `unique_ptr` with deleters for `AVFormatContext`, - `AVCodecContext`, `AVFrame`, `AVPacket`, `AVBufferRef`. -- FFmpeg errors are converted to `oma::Error`, preserving the code and `av_strerror`. -- Probing returns its own structure (streams, codec, dimensions, timebase, duration, color, - rotation/display matrix, channel layout), not `AVStream*`. - -### 8.1 Frames and lifetime - -- `Frame` is a handle with **explicit ownership** and controlled reference counting (pool), - not `shared_ptr` scattered around. Releasing returns it to the pool. -- A GPU frame carries: Vulkan image(s) / imported memory, format, color space, PTS - (`RationalTime`) and a **synchronization primitive** (Vulkan timeline semaphore) that tells - when it is ready and when it can be reused. -- No frame may outlive the device/pool that created it. Shutdown destroys in order: - consumers → pools → device. -- No `vkDeviceWaitIdle`/`vkQueueWaitIdle` on the hot path. Synchronize with specific - semaphores/fences. -- HW-decoded frames keep a reference to the source `AVFrame`/surface while the imported image - is in use. - ---- - -## 9. Compositor, render graph and backends - -### 9.1 Layers (invariant) - -``` -Timeline (model) -> RenderGraph (description per instant) -> Compositor -> Graphics backend (Vulkan) -``` - -- The timeline **does not know Vulkan**. For a time `t` it produces a declarative description - (layers, transforms, crop, opacity, blend, effects with evaluated parameters). -- The render graph is plain data and testable without a GPU ("which graph comes out of this - timeline state"). -- The compositor translates the graph into backend commands and manages pipelines, - descriptor sets and transient resources. - -### 9.2 Compositor responsibilities -Layers, scale, crop, rotation, translation, alpha blending, masks, transitions, LUTs, color -transforms, overlays, titles, blend modes. - -### 9.3 Compute - -```cpp -class ComputeBackend; // interface -// VulkanComputeBackend, CudaBackend, CpuBackend -``` - -- **Effects do not depend directly on CUDA.** An effect declares what it needs; the backend - executes it. -- `CpuBackend` exists as the correctness reference and for tests (output comparison with a - tolerance). -- **Vulkan Compute is the generic backend**: every effect has a Vulkan implementation. -- CUDA only where there is a measured gain on NVIDIA. -- **OpenCL is not used.** Reasons: Omarchy installs no OpenCL runtime, and rusticl (Mesa) has - no zero-copy interop with Vulkan, which would force frame copies (violates §7). See - `Docs/Research/opencl.md`. Do not add OpenCL without an explicit decision and an ADR. -- Do not implement the three backends at once. Interface first, one real backend, CPU for - tests; the others when there is a reason. - -### 9.4 Preview in Qt Quick -- Qt Quick must run on the **Vulkan** RHI backend, sharing or importing compositor images - without a CPU readback. -- Investigate and record in an ADR: a shared device (Qt using OmaMovie's `VkDevice`) vs. - separate devices with external memory. Prefer what avoids copies and simplifies - synchronization. -- The QML preview item only displays the final texture. It does not decide what to render. - -### 9.5 Pipelines and shaders -- Shaders in GLSL or Slang compiled to SPIR-V at build time. Persisted pipeline cache (an - invalidatable cache, §15). -- No pipeline creation during playback if it can be done earlier (warm-up). - ---- - -## 10. Timeline - -The central component. Progressive support for: multiple video and audio tracks, clips, -in/out, split, trim, ripple, roll, slip, slide, snapping, transitions, keyframes, speed, -nested structures (when justified), undo/redo. - -Rules: -- Timeline model in plain C++ (`libs/timeline`), without Qt, GPU or FFmpeg. -- **Every edit is a command** (`Command` with `apply`/`revert`), applied through a single - entry point. Undo/redo is born with the model, not added later. -- Compound operations (e.g. ripple delete) form a single transaction in the history. -- Invariants checkable by a function (`validate()`) and tested: no improper overlap in a - track, valid ranges, existing media references. -- Editing is non-destructive: clips reference media and ranges and never modify source files. -- Clips reference media by stable ID, not by pointer or path. -- **Render state never lives in the timeline's QML components.** The UI reads an exposed - model (`QAbstractItemModel`/properties) and emits edit intents. - ---- - -## 11. UI (Qt Quick / QML) - -Inspired by the simplicity of iMovie, without copying its visual identity or proprietary -behavior. **Reference design and decisions: `Docs/ui-design.md`** (layout, adjustment drawer, -timeline, shortcuts, theme). Diverging from it requires updating that document. - -Fixed decisions (2026-10-02): -- Adjustment controls in a **drawer above the viewer**, not in a fixed side panel. -- **The Omarchy font** across the whole UI (`omarchy-font-current`, with a fallback). -- **Our own SVG icons**, monochrome and tinted by the theme. No Nerd Font glyphs and no - third-party icons without a compatible license. -- Shortcuts follow the **iMovie/Final Cut convention** (`Cmd`→`Ctrl`); never use `SUPER`. -- The start screen **depends on how the app was opened**: launcher → Projects; project or - media file → Edit. Single instance. - -Structure: `MediaPanel`, `PreviewPanel`, `TimelineView`, `Inspector`, `TransportControls`. - -- Large preview, clear timeline, visual library, few permanent controls. -- **Contextual inspector**: the selection determines its content. - - Video: transform, crop, opacity, speed, color, effects. - - Audio: gain, fades, EQ, processing. - - Text: font, size, layout, animation. -- Advanced tools appear in context, not as always-visible panels. Hiding complexity ≠ - removing capability. -- Visual integration with the active Omarchy theme (mechanism documented in - `Docs/Research/omarchy-integration.md`); isolate that reading in a single place. The viewer, - thumbnails and scopes **never** take colors from the theme. -- Native Wayland. Do not use X11 APIs. - -### 11.1 QML vs C++ -QML: layout, interaction, UI animation, property bindings. -**Forbidden in JavaScript/QML:** decoding, a complex timeline model, the render graph, -compositing, synchronization, persistence, project parsing. Non-trivial JS logic inside QML -means a C++ model is missing. - -### 11.2 Shortcuts -Full keyboard editing is a requirement. Plan early for: split, delete, ripple delete, -undo/redo, frame step (±1 frame, ±N frames), J/K/L (including multiple speeds by repeated -presses), in/out, next/previous clip selection. -- Actions are registered in a central action system (id, name, default shortcut, handler), - not in scattered `Keys.onPressed`. -- Shortcuts must be remappable later; do not hardcode them in components. - ---- - -## 12. Audio - -- PipeWire is the main integration. Do not use OpenAL as the foundation. -- **During playback the master clock is audio** (derived from the samples actually consumed - by the device). Video syncs to it: frames are dropped or repeated; audio is never - "stretched". Without audio, use a monotonic clock. -- The PipeWire real-time callback **does not allocate, block, log synchronously or take a - contended mutex**. Communication through preallocated lock-free queues/ring buffers. -- Cover: project vs. media vs. device sample rate, resampling (libswresample or equivalent, - in `media`/`audio`), volume, fades, mixing, waveforms, device-reported latency. -- Internal processing in planar float32 (to be confirmed in an ADR). - ---- - -## 13. Concurrency - -Never block the UI thread with: decode, encode, thumbnails, waveforms, probing, cache, -proxies, imports, large saves. - -Thread model (ADR-0003): - -| Thread / pool | Responsibility | -|---|---| -| UI (main) | QML, events, edit command dispatch | -| Render (Qt) | Scene graph, preview presentation | -| Playback | Clock, frame scheduling, requests to decode/compositor | -| Decode workers | One pipeline per active stream, with a bounded queue | -| Audio RT | PipeWire callback (rules in §12) | -| Job pool | Background tasks: probe, thumbnails, waveforms, proxies, imports, export | - -Rules: -- **No ad hoc `std::thread` in components.** Every asynchronous task goes through the job - system (`libs/base`). -- Every long task supports **cancellation** (cooperative token) and **progress**. -- Ownership of data passed between threads is explicit (move, pool handle, or shared - immutable). Document which. -- Queues between stages are **bounded** (backpressure). No queues that grow without limit. -- Safe shutdown: cancel jobs → drain queues → stop workers → release the GPU. Test shutdown - in the middle of playback and of an import. -- Callbacks to the UI arrive on the UI thread through a single mechanism (e.g. - `QMetaObject::invokeMethod` with `Qt::QueuedConnection` in the bridge). -- Before changing threading, describe the impact on lifetime and synchronization (§21). - ---- - -## 14. Native project format - -- Our own format, **versioned** (integer `format_version` at the top). -- The persisted format does **not** mirror in-memory structs. There is an explicit - serialization layer (DTOs/schema) between the model and the disk. -- **Explicit chained migrations** `vN -> vN+1`, each tested with a fixture of the old - version. Never edit a published migration. -- Opening a project newer than supported: refuse with a clear message (or read-only mode), - never corrupt it. -- Atomic save: write to a temporary file → `fsync` → `rename`. Backup/autosave separate from - the main file. -- Must represent: media references, timelines, tracks, clips, transitions, effects, - keyframes, metadata, and unsupported external objects (§16.3). -- A media reference stores: path relative to the project, absolute path and a fingerprint - (size + partial hash + duration/streams) for relinking. -- Unknown fields from compatible future versions are preserved, not dropped. -- The concrete format (JSON / single file / bundle with SQLite, etc.) is an ADR decision. - Requirements: diffable when possible, robust against truncated files. - ---- - -## 15. Cache - -Design the cache from the start, even if only partially implemented. - -Kinds: decoded frames, thumbnails, waveforms, proxies, rendered intermediate frames, shader pipelines. - -- **The cache is never a source of truth.** Deleting the whole cache loses no project data. -- Every entry has a key derived from the inputs that produced it (media identity + - parameters + algorithm version). If an input changes, the key changes: invalidation by - construction. -- Configurable memory/disk limits with an eviction policy (LRU or similar). -- Disk caches live in `$XDG_CACHE_HOME/omamovie/`, never next to the project unless - explicitly requested. -- The GPU frame cache respects the VRAM budget and the synchronization in §8.1. - ---- - -## 16. Interoperability and reverse engineering - -### 16.1 Three distinct categories (do not mix) -1. **Media formats** (containers/codecs) → `oma-media`. -2. **Interchange formats** (OTIO, EDL, AAF, FCPXML/XML) → `importers/`. -3. **Proprietary projects** (Premiere, Resolve, Avid, Vegas, …) → `importers/`. - -### 16.2 ProjectIR - -``` -External project -> Importer -> ProjectIR -> converter -> OmaMovie project -``` - -- `ProjectIR` is neutral, independent of any external format and of the internal model. -- Importers produce **only** ProjectIR. They do not touch the internal model. -- **Details of external formats never leak into the core model.** If the internal model needs - a new concept, it is added on its own merit, with its own name. -- Times in ProjectIR use `RationalTime`, preserving the source timebase. - -### 16.3 Preserving external data -Never drop silently. Represent as `UnknownEffect`, `UnsupportedEffect`, -`OpaqueExternalObject`, storing: source format, original identifier, raw payload (when -feasible) and partially parsed parameters. The goal is to allow a future round trip. - -### 16.4 Import report -Every import produces a structured report (shown in the UI and the CLI) with, for each issue: -affected object, reason, compatibility level reached, likely impact (e.g. "transition replaced -by a hard cut; duration preserved"). - -### 16.5 Support levels -Never write "supports Premiere". Declare per format **and version**: - -| Level | Meaning | +# OmaMovie — agent guide + +OmaMovie is a native, local-first video editor for Linux and Omarchy, written mainly in +C++. It serves recordings, personal video and content creation through a simple, +contextual interface backed by an engine that can grow toward demanding workflows. +The useful reference is iMovie's approachability with some of Final Cut Pro's depth, +without copying either interface or promising feature parity. + +## Source of truth and context loading + +For mutable facts, use this order: **code and relevant tests → accepted ADRs → dated +benchmark/workload evidence → implementation plan → specialized Docs → this guide**. +An ADR records a decision, not proof that it shipped. Research is provisional. Resolve +conflicts by checking current code, tests and dated evidence, then correct the stale doc. + +Load context progressively: this guide → one relevant skill if useful → the relevant +[implementation milestone](Docs/implementation-plan.md) and [next step](Docs/implementation-plan-next-step.md) +→ its [ADR](Docs/adr/README.md) → affected source/tests → evidence. Expand only when the +question requires it. Use [UI design](Docs/ui-design.md) for UX, +[format architecture](Docs/format-architecture.md) and [interop matrix](Docs/interop.md) +for formats, and [QA](Docs/implementation-plan-qa.md) for validation. [CONTRIBUTING.md](CONTRIBUTING.md) +contains build commands and contribution process; `make help` lists current targets. + +## Facts, goals, preferences and evidence + +**Facts** are checked in code: the app uses C++23, Qt Quick/QML, FFmpeg, Vulkan and +PipeWire; inspect current implementations before describing a path. **Goals** include +GPU-native export, clearer Session ownership and more explicit QML composition; the +[M12 plan](Docs/implementation-plan-m12-gpu-export-architecture.md) marks these as planned. +**Maintainer preferences** below guide choices but may be challenged by code or evidence. +**Evidence** lives in `Docs/Research/evidence/`, tests and workload protocols, not here. + +Use status terms precisely: *implemented* = connected code; *tested* = relevant test; +*measured* = repeatable benchmark; *validated* = declared workload plus recorded result; +*supported* = bounded commitment backed by suitable evidence; *planned* = intended work. +Do not infer zero-copy, real-time performance, HDR, vendor or format support from a type, +architecture sketch or passing build. + +## How to work + +- Keep native-first, local-first and Linux/Omarchy-first behavior. Performance and + accessibility are product requirements. Prefer a GPU path where justified, with a + usable software fallback where feasible and an observable reason for downgrade. +- Measure before optimizing: baseline → hypothesis → instrumentation → change → same-fixture + measurement → regression check. Inspect algorithmic cost as clips, frames, media and + effects grow; hardware does not excuse a poor algorithm. +- Preserve behavior before restructuring. Extract by owned state, lifecycle, concurrency + boundary or testable contract, not file length. Work in small vertical changes; reject + decorative interfaces, global event buses, service locators and framework imitations. +- Use C++, Qt/QML, Vulkan, FFmpeg and PipeWire's own abstractions before inventing a new + layer. Respect the dependency graph enforced by `cmake/OmaDependencyGraph.cmake` and + `scripts/check-includes.sh`; inspect ownership, threading, time and CPU/GPU transfers + before changing those boundaries. Record changed decisions in a new ADR. +- Let the engine own project and edit semantics. Compose QML with explicit properties + flowing down and intents flowing up; QML owns presentation and ephemeral interaction + state. React is inspiration for composition, not a request for JSX, hooks, Redux or a + Virtual DOM. Keep the UI low-clutter, contextual, context-menu-first, discoverable by keyboard + and mouse, readable at supported text scales and accessible without hover alone. +- Agents may implement autonomously within the task's scope. Agent-written code receives + the same design, behavior, build, test and evidence review + as any other code. A passing build is not a completed workflow; a benchmark without a + method is not a performance claim. Question a maintainer proposal when observed code + or measurements argue against it, and state the evidence. + +## Skill routing + +Use the smallest useful combination, and inspect the installed skill's own instructions +before invoking it. Skill availability and paths can vary by agent. The +Skill-Library is installed locally when available; its `SKILL.md` descriptions define +scope. + +| Task | Useful skill, when available | |---|---| -| 0 | File recognized and version identified | -| 1 | Referenced media and clips | -| 2 | Tracks, cuts, transitions | -| 3 | Transforms, audio (gain/fades), keyframes | -| 4 | Effects with a mapped equivalent | -| 5 | Round trip | - -Keep a table in `Docs/interop.md` with the level per format/version and the tests that prove -each level. - -### 16.6 Reverse engineering rules -- Goal: **interoperability**, focused on project representation. -- Start **read-only**. Writing only after the parser is understood and tested. -- **Forbidden:** implementing anything meant to bypass DRM, licensing, protective encryption, - authentication or access control. If a format is protected, document it and stop. -- Priority order by accessibility: text → XML → JSON → ZIP/container → SQLite → known - structured binary → proprietary binary → protected. Validate the architecture with - accessible formats (OTIO, FCPXML, EDL, export XMLs) before attacking hard binaries. -- Document format findings in `Docs/formats/.md` (structure, observed versions, - known/unknown fields, how each was deduced). - -### 16.7 `oma-project` CLI -`inspect` (summary and detected level) · `dump` (structured tree/ProjectIR) · `diff` (compare -two projects with small known changes, field/offset-oriented output, for RE) · `validate` -(invariants) · `convert` (through ProjectIR). The CLI reuses the same libs as the app. No -parsing logic exists only in the CLI. - ---- - -## 17. Persistence and SQLite - -SQLite for: media metadata, indexes, structured caches, project metadata when it makes sense. -- Do not use SQLite "because it is there". Justify it in the module. -- Large binaries (proxies, frames, large waveforms) stay as **files**; the database stores - references. -- Versioned schema with migrations, like the project format. -- Database access off the UI thread. - ---- - -## 18. Parser safety - -Media and project files are **untrusted input**, always. - -- Validate sizes, offsets and counts before use. Size arithmetic with overflow checks. -- Limit allocations (cap per structure and in total); never allocate from an unbounded size - read from the file. -- Truncated files and invalid structures produce a handled error, never a crash, UB or an - infinite loop. -- Limit recursion depth in nested formats. -- XML parsers: disable external entities (XXE) and entity expansion. -- ZIP: protect against zip bombs and path traversal. -- Every external format parser has a fuzzing target (libFuzzer) and runs in CI with ASan/UBSan. -- Reverse engineering does not justify an unsafe parser. - ---- - -## 19. Logging and errors - -### Logging -- Structured logging through a facade in `libs/base` (no Qt), with a sink that can forward to - `QLoggingCategory` in the app. -- Categories: `media`, `decode`, `encode`, `gpu`, `compositor`, `timeline`, `project`, - `importer`, `audio`, `cache`, `playback`, `ui`. -- **No stray `printf`/`std::cout`/`qDebug()`** as observability. -- Logging on the hot path: no allocation, no expensive per-frame formatting; use levels and - rate limiting. -- Logging from the audio RT thread is forbidden (use counters/lock-free queues). - -### Errors -- APIs between subsystems return `std::expected` (alias `Result`). -- `oma::Error` has: a typed code (enum class), category, message, context (file/stream/object). -- **Exceptions do not cross library boundaries.** If a dependency throws, catch at the - boundary and convert. -- Silent failure is forbidden. Degradation (e.g. fallback to SW decode) is logged with the reason. - ---- - -## 20. ADRs - -Record in `Docs/adr/NNNN-title.md` (context, decision, alternatives, consequences). -Mandatory for decisions about: graphics backend, threading model, time representation, -project format, GPU interop, cache, import system, large new dependencies. - -The current list and the pending ADRs are in `Docs/adr/README.md`. - ---- - -## 21. Rules for AI agents - -### Before changing the architecture -1. Understand the affected module and read its public API. -2. Check existing interfaces before creating new ones. -3. Identify the impact on **lifetime** and **threading**. -4. Assess the effect on **CPU↔GPU transfers**. -5. Check existing tests and what needs new tests. -6. Explain structural changes in the reply/PR. If it is an ADR decision, write the ADR. - -### Always -- Follow the dependency rules in §5.2. A violation is a bug, even if it compiles. -- Keep changes focused on the request. Do not rewrite large parts for aesthetic preference. -- Do not replace chosen technologies without a measurable technical reason. -- When you find a real architectural problem: document it (issue/ADR) and propose a fix; - do not silently work around it. -- Do not claim something is "fast", "real-time" or "zero-copy" without a benchmark or - evidence (e.g. verified absence of readback). -- Do not invent performance numbers as targets. -- Update this file when a rule or command changes. - -### Never -- Call FFmpeg outside `libs/media`; include Vulkan/CUDA in timeline/project/IR/importers. -- Put heavy logic in JS/QML. -- Use `double` as a reference timestamp. -- Create ad hoc threads; block the UI thread or the audio callback. -- Drop external project data silently. -- Implement DRM/license/encryption/authentication bypasses. -- Add a plugin system, AI or cloud without an explicit decision. -- Commit copyrighted media or large fixtures. - -### Ask before -- Adding a new dependency. -- Changing the project format, time representation or threading model. -- Starting support for a proprietary binary format. -- Diverging from the development order in §24. - ---- - -## 22. C++ code - -Prefer: explicit ownership, RAII, strong types (IDs and units with their own types, not raw -`int`/`std::string`), const correctness, small APIs, `enum class`, explicit error handling, -clear names. - -Avoid: globals, indiscriminate singletons, unnecessary macros, unsafe casts -(`reinterpret_cast`/C casts without justification), `shared_ptr` as the default choice, deep -inheritance, exceptions crossing subsystems. - -Conventions (ADR-0001; `.clang-format` and `.clang-tidy` at the root are the reference): -- Types and enum values `PascalCase`; functions and variables `snake_case`; private members - with a `_` suffix; constants `kPascalCase`. -- Do not use `describe`, `test`, `it`, `expect`, `bench`, `beforeEach`, `afterEach`, - `beforeAll`, `afterAll` as API names: they are Cest macros in tests. -- Headers with `#pragma once`. -- Identifiers, code comments, log messages and all docs in English. -- Comments explain **why** (invariants, synchronization, the reason for a copy), not the obvious. -- Warnings are errors (`WERROR=1` by default; full set in ADR-0001). -- Vulkan objects with their own RAII or a thin wrapper; no manual `vkDestroy*` scattered around. - ---- - -## 23. Performance - -Performance is a functional requirement. - -In critical code (decode, compositor, playback, audio): -- **Measure before optimizing.** Profile with perf, Tracy or RenderDoc/Nsight/RGP as appropriate. -- Zero allocations per frame on the hot path in steady state; use pools and reused buffers. -- Avoid large copies; prefer views (`std::span`) and handles. -- Control GPU resource lifetime explicitly. -- Avoid unnecessary GPU↔CPU synchronization. -- Instrument important zones from the start (a profiling macro/facade that can be disabled - in release builds). - -### Benchmarks (`tools/bench`) -Initial scenarios: N simultaneous 1080p60 streams, real-time compositing, A/V sync, timeline -interaction latency, 4K on reasonable hardware. - -Record as JSON: FPS, frame time (mean, p95, p99, max), dropped frames, CPU, GPU, VRAM, RAM, -upload/download bandwidth when relevant, **plus hardware, driver, FFmpeg version, codec and -the decode path used**. Results without that context are useless for comparison. - ---- - -## 24. Development order - -**Detailed plan with milestones, done criteria and releases: `Docs/implementation-plan.md`.** -Update the plan when a milestone is finished. The list below summarizes the order. - -Not rigid, but prioritize: - -1. Build system (Make, `base`, tests, sanitizers, clang-format/tidy) -2. Media probing -3. Decode (SW first for correctness, then HW) -4. GPU frame abstraction -5. Vulkan compositor -6. Preview -7. Playback clock -8. Audio synchronization -9. Timeline model -10. Timeline UI -11. Project persistence -12. Import/export -13. Effects -14. Advanced interoperability - -**Do not start with the final visual look.** - -### First technical experiment (before a large UI) -A prototype that validates the pipeline: - -``` -video A + video B + image -> GPU compositor -> preview -``` - -Criteria: open several videos; decode them; keep frames on the GPU when possible (log where -not); composite layers through Vulkan with transform, scale, crop and opacity; present a -preview; synchronized playback. Instrument from the start: frame time, dropped frames, -uploads/readbacks. It may be an executable in `tools/` or `apps/` with a minimal window; -reusable code goes into the libs instead of staying stuck in the prototype. - ---- - -## 25. Tests - -Mandatory for structural components. Priority: timeline operations · time conversion · -serialization · project migration · importers · ProjectIR · render graph · frame lifetime · -parser robustness. - -- Every bug fixed in a structural component gets a regression test. -- Render graph tests do not need a GPU. GPU tests are marked and can be skipped on machines - without Vulkan. -- Image comparison with a tolerance against `CpuBackend` reference output. -- Small, reproducible fixtures in `tests/fixtures/`, with a **generator script** (e.g. - `ffmpeg -f lavfi -i testsrc2=...`) versioned next to them. No copyrighted media. -- For RE: pairs of projects with minimal known changes (one field per pair), when legally - possible, documenting what changed between them. -- TSan for concurrent code; ASan/UBSan for everything; fuzzing for parsers. - -### Writing tests with Cest -- One suite per file `tests//test_.cpp`, exposed as `void run__tests()` - and called from the lib's `main.cpp`. A new lib suite: `tests//module.mk` with - `oma_test` and an `include` in the `Makefile`. -- Include `oma_test.hpp` **last** (after project and standard headers). -- **No top-level commas** inside `describe`/`it`: the preprocessor splits macro arguments. - Avoid `std::pair`, `[&a, &b]` captures and `{1, 2}` directly in the block; use - `auto`, `[&]`, helper functions or parentheses. -- `expect()` only on the test thread; results from other threads go through atomics. -- Enums and types without a Cest overload: compare `static_cast(...)` or a boolean. - ---- - -## 26. Implementation philosophy - -Between two approaches, prefer the one that: preserves architectural separation · reduces -memory copies · makes testing easier · keeps APIs explicit · enables profiling · avoids -hidden dependencies · allows replacing backends. - -But: do not create abstractions without a real need, do not generalize prematurely, do not -build plugins before there is a stable architecture. An abstraction is justified by a second -concrete use, by a subsystem boundary defined in this document, or by testability. - -### The final question for every change - -> Does this implementation keep OmaMovie simple for the user without making its architecture simplistic? +| Simplify an overdesigned proposal | `ponytail` | +| Structural code refactor | `principled-refactoring` | +| Broad architecture audit / algorithmic audit | `software-project-analysis` / `algorithmic-project-review` respectively | +| Rigorous second pass on generated artifact | `anti-ai-mediocrity` | +| Disputed external technical claim | `skeptical-research` | +| Product readiness or scope thesis | `software-product-review` / `quantify-ambition` respectively | +| Omarchy end-user desktop configuration | `omarchy` where installed; not ordinary OmaMovie source work | +| PR, issue, release or repository health | the matching focused audit/resolution/release skill only | + +Do not invoke several reviewers for a routine edit. Skills supply reusable method, while +Docs and code supply OmaMovie's current decisions and facts. + +## Scope and completion + +Build the committed workflow before adding effect categories or competitor parity. The +[v0.1 release decision](Docs/implementation-plan-milestone-overview.md) covers only its +validated Intel/software scope; the [first-opening tour](Docs/implementation-plan-v1-onboarding.md) +and bundled editable demo are in v0.1, while contextual tooltip and novice task gates +remain open. AMD/NVIDIA, full HDR and other desired capabilities require their +own evidence. Do not turn aesthetic refactoring into a release gate. + +A change is done when its actual behavior and error/fallback path have proportional +checks, affected integration/workload gates pass, documentation states the resulting +scope accurately, and the report names any unverified claim. See +[CONTRIBUTING.md](CONTRIBUTING.md) for commands and [milestone rules](Docs/implementation-plan-milestones.md) +for release criteria. + +## Older section references + +Older source comments cite sections of the former long guide. Resolve them through the +sources here: §3–5 build/dependencies → `CONTRIBUTING.md`, ADR-0001/0018 and CMake; +§6 time → ADR-0002; §7–9 GPU/media/compositor → ADR-0004/0005/0006 and M2/M3/M12; +§10–11 timeline/UI → M5/M6 and `Docs/ui-design.md`; §12–13 audio/concurrency → +ADR-0003/0020 and M4; §14–15 project/cache → ADR-0007/0009 and M7; +§16 interop → ADR-0008 and `Docs/interop.md`; §18–19 parser/errors → QA and code; +§20–26 agent/process/performance/tests → ADR index, evidence, milestones and +`CONTRIBUTING.md`. Update a touched comment to its direct source rather than extending +this compatibility map. diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..135a9f3 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,38 @@ +# OmaMovie — CMake build (ADR-0018). The GNU Makefile is a thin front-end over these presets. +# +# cmake --preset debug && cmake --build --preset debug && ctest --preset debug +# cmake --preset release | asan | tsan +# cmake --preset spikes (M1 prototypes) | cmake --preset fuzz (libFuzzer, Clang) +# +# Each lib and test suite declares its own CMakeLists.txt; cmake/OmaDependencyGraph.cmake enforces +# the §5.2 graph at configure time; cmake/OmaTargets.cmake holds the oma_library/oma_test helpers. + +cmake_minimum_required(VERSION 3.25) +project(omamovie LANGUAGES CXX) + +if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) + set(CMAKE_BUILD_TYPE debug CACHE STRING "Build type (debug release asan tsan)" FORCE) +endif() + +set(CMAKE_CXX_STANDARD 23) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) +# compile_commands.json for clangd and clang-tidy; written into the build dir (the Make front-end +# links it at the root). +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) +set(CMAKE_POSITION_INDEPENDENT_CODE ON) + +include(cmake/OmaBuildOptions.cmake) + +list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake) +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) + +find_package(PkgConfig REQUIRED) +find_package(Threads REQUIRED) + +include(OmaDependencyGraph) +include(OmaTargets) + +enable_testing() +include(cmake/OmaProjectTargets.cmake) +include(cmake/OmaDeveloperTargets.cmake) diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..aedd775 --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,35 @@ +{ + "version": 6, + "cmakeMinimumRequired": { "major": 3, "minor": 25, "patch": 0 }, + "include": ["cmake/presets/build-types.json", "cmake/presets/specialized.json"], + "buildPresets": [ + { "name": "debug", "configurePreset": "debug" }, + { "name": "release", "configurePreset": "release" }, + { "name": "asan", "configurePreset": "asan" }, + { "name": "tsan", "configurePreset": "tsan" }, + { "name": "spikes", "configurePreset": "spikes" }, + { "name": "fuzz", "configurePreset": "fuzz" } + ], + "testPresets": [ + { + "name": "debug", + "configurePreset": "debug", + "output": { "outputOnFailure": true } + }, + { + "name": "release", + "configurePreset": "release", + "output": { "outputOnFailure": true } + }, + { + "name": "asan", + "configurePreset": "asan", + "output": { "outputOnFailure": true } + }, + { + "name": "tsan", + "configurePreset": "tsan", + "output": { "outputOnFailure": true } + } + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ef2520c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to OmaMovie + +Repository content, code comments, logs and commit messages are written in English. +Keep changes small enough to build and verify independently. Explain behavioral and +architectural consequences; update the relevant plan, ADR or evidence record when they +change. A build alone is not a correctness check. + +## Build and checks + +The `Makefile` is the front end to CMake (ADR-0018). `make help` is the current command +list; `PKGBUILD` is the dependency source of truth. Common commands: + +```sh +make -j +make -j test +make -j BUILD=asan test +make -j BUILD=tsan test +make format-check +make tidy +make run-gui +make run-gui RUN_GUI_SMOKE=1 +make fuzz +``` + +`make deps` installs the `PKGBUILD` dependencies on Arch/Omarchy and may use sudo. +`scripts/check-includes.sh` verifies dependency boundaries not expressed by CMake. +`scripts/package-check.sh` exercises the package in disposable containers. Benchmark +and spike commands, their fixtures and measurement protocols live beside each task in +`Docs/Research/evidence/`, `Docs/spikes/` and `tools/bench/`; run only the relevant ones. + +Commit messages use Conventional Commits in English, with an imperative description +under 100 characters. Check a range with `scripts/check-commits.sh`. Do not create a +release tag as part of normal implementation work; the [release plan](Docs/implementation-plan-m10-validation.md) +and CI define its separate gates. + +## Change protocol + +1. Read the relevant implementation milestone, ADR and current code/tests. A document's + target architecture is not proof of implementation. +2. For a behavior change, run focused checks and the affected integration/workflow test. + For concurrent code, include the appropriate sanitizer subset. For performance changes, + record a same-fixture baseline, hypothesis, measurement and regression check. +3. Keep the supported hardware/format statement no broader than the validated evidence. + Record fallback paths and reasons. Treat media and project files as untrusted input. +4. Update an ADR for a changed architectural decision. Keep observed results in evidence + files rather than copying numbers into the agent guide. +5. Report what ran and what remains unverified. Do not silently ignore a relevant warning + or failure. + +Key sources: [implementation plan](Docs/implementation-plan.md), [ADR index](Docs/adr/README.md), +[UI design](Docs/ui-design.md), [format architecture](Docs/format-architecture.md), +[interop support levels](Docs/interop.md), and [QA plan](Docs/implementation-plan-qa.md). diff --git a/Docs/Research/README.md b/Docs/Research/README.md index 04e4325..fc26926 100644 --- a/Docs/Research/README.md +++ b/Docs/Research/README.md @@ -1,150 +1,57 @@ # Research -Market, UX and technology research that guides OmaMovie. It is not a specification: -recommendations here only become rules once they reach `CLAUDE.md` or an ADR. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. +> VEGAS Pro 23 was added in a separate documentary review on 2026-10-07. -**Product and UX** +The architecture remains a defensible direction, subject to driver, synchronization, +color and workload checks. The product positioning and UX proposals remain hypotheses. +The 2026-10-03 review replaces the previous unsourced market rankings and broad hardware +claims; it does not certify the implementation or complete the pending spikes. -| Document | Topic | -|---|---| -| [premiere-pro.md](premiere-pro.md) | Why Adobe Premiere Pro is a powerful editor (engine, editing model, color, interop, weaknesses) | -| [imovie.md](imovie.md) | Apple iMovie UI/UX (layout, contextual inspector, magnetic timeline, templates) | -| [movie-maker.md](movie-maker.md) | Windows Movie Maker and its successors UI/UX (storyboard/timeline, Clipchamp) | -| [davinci-resolve.md](davinci-resolve.md) | Why DaVinci Resolve is powerful (pages, Cut page, node color, database projects, OTIO, the Linux situation) | -| [capcut.md](capcut.md) | What people like and dislike about CapCut (templates, captions, speed ramps, paywall, terms of service) | -| [other-editors.md](other-editors.md) | Final Cut Pro, Descript, Kdenlive, Shotcut and patterns shared across editors | - -**Technology and platform** - -| Document | Topic | -|---|---| -| [hardware-strategy.md](hardware-strategy.md) | **Synthesis**: role of each API, single Vulkan device, runtime selection, proposed `CLAUDE.md` changes, spikes | -| [vulkan.md](vulkan.md) | Vulkan-Hpp, Vulkan Video, VA-API→Vulkan, FFmpeg `hwcontext_vulkan`, Qt Quick on an external device, libplacebo | -| [cuda.md](cuda.md) | NVDEC/NVENC without the toolkit, CUDA↔Vulkan interop, kernels through PTX (clang), hybrid laptops | -| [opencl.md](opencl.md) | The analysis that led to **removing OpenCL** (rusticl, NEO, ROCm, Vulkan interop, the Blender lesson) | -| [omarchy-integration.md](omarchy-integration.md) | Theme, window opacity, screen recordings, Quickshell shell, menu, installed drivers, distribution | - -## Method - -- Sources: official documentation (Adobe Help, Apple Support, Blackmagic, Kdenlive), Wikipedia, - trade press, independent benchmarks (Puget Systems) and review aggregators (G2, Capterra; - treated as a signal of opinion, not as measurement). Links in each document. -- Claims without a specific source are marked **(general knowledge)** or **(general observation)**. -- Each section ends with **Implications for OmaMovie**, linking the finding to `CLAUDE.md` sections. -- Goal: extract principles. Copying visual identity or proprietary behavior is forbidden (`CLAUDE.md` §11). - ---- - -## Synthesis - -### Where each product sits - -``` -simple ◄───────────────────────────────────────────────────────────────► powerful -Movie Maker/Photos iMovie CapCut/Clipchamp Shotcut/Kdenlive FCP Premiere/Resolve -(storyboard) (FCP X engine) (presets, social) (free, MLT) (cockpit/pages) - -OmaMovie: a surface close to iMovie/CapCut, an engine close to Premiere/Resolve. -On Linux, the space between Kdenlive/Shotcut and Resolve is empty. -``` - -### Conclusions - -1. **Simplicity comes from contextual disclosure, not from removing features.** iMovie's - adjustments bar and Clipchamp's properties panel show only what applies to the selection. - Premiere solves it with 16 workspaces. OmaMovie's contextual inspector is the right path. - Also adopt the **visual indicator of which adjustments are active** on a clip (iMovie). - -2. **A redesign that removes capability causes rejection.** iMovie '08 and Windows Live Movie - Maker had to bring features back in the following versions. This confirms "hide, do not - remove" and "grow without rewriting the core". - -3. **A professional engine under a simple UI works.** iMovie has used the Final Cut Pro X - engine since 2013 and exports to it. That is OmaMovie's thesis, with the difference of - being a single app: progressive disclosure needs more care. - -4. **Named operations over a generic compositor.** iMovie's PiP, cutaway, split screen and - green screen are presets. In OmaMovie they must produce normal layers and parameters in the - render graph, editable afterwards, without iMovie's layer ceiling. +## Reading order -5. **Semantic storyboard ↔ timeline zoom** (Movie Maker 2012). A single TimelineView whose - minimum zoom becomes a storyboard (equal-size clips, focus on order). A strong UX - differentiator. Requires virtualization and a thumbnail cache. +1. [Skeptical review](skeptical-review.md): hypotheses, corrections, foundations and gates. +2. [Source register](sources.md): documents actually inspected and their limits. +3. [Hardware strategy](hardware-strategy.md): bounded application to the pipeline. +4. [Implementation plan](../implementation-plan.md): milestone work and acceptance criteria. -6. **"Powerful" starts in the engine**: real-time GPU playback of native media, hardware - decode/encode with a fallback, a float pipeline, proxies. Premiere also shows that - **effects without a GPU path need a visible indication** (the render bar). +## Documents -7. **A complete editing model in the core, a gradual UI.** Ripple/roll/slip/slide, split edits - and three-point editing should exist as timeline commands early. iMovie shows roll and - split edits can have a friendly UI (Precision Editor, Clip Trimmer). Premiere shows full - keyboard access. - -8. **Automatic color management** (Premiere 25.2: color space detection, presets, effects - that know their color space). Feeds ADR-0006. - -9. **Stability is part of power.** The main criticism of Premiere is instability and corrupted - projects. Atomic save, tested migrations and parser fuzzing are a competitive advantage, - not bureaucracy. - -10. **`.prproj` is gzip-compressed XML.** A relatively accessible import target to validate - `Importer → ProjectIR`, after OTIO/FCPXML/EDL. - -11. **Resolve on Linux leaves an opening.** The free version does not decode H.264/H.265 or - AAC on Linux, official support is NVIDIA only and the documented audio path is ALSA. Phone - video + an AMD/Intel GPU + PipeWire, the typical Omarchy setup, is poorly served. This is - OmaMovie's **clearest positioning**. - -12. **Simple and fast are not opposites.** Blackmagic created the Cut page (source tape, dual - timeline) for professionals on a deadline. CapCut wins on time to result. OmaMovie's - simplicity must also serve advanced users. - -13. **Overview + detail in the timeline**: Resolve's dual timeline and Movie Maker's semantic - zoom attack the same problem. Prototype both approaches (or a minimap) in the TimelineView. - -14. **Graph inside, stack outside.** Resolve 21 added a layer-list view to its color node - graph. OmaMovie's render graph is a DAG; the UI shows the stack. - -15. **Projects as files, not in a database.** Resolve projects live in a database - (local/PostgreSQL/cloud) and need a `.drp` export to become a file. This confirms - `CLAUDE.md` §14/§17: the file is the source of truth. - -16. **OTIO is the first interop target.** Resolve has exported OTIO natively since 18.5: a - Resolve → OmaMovie path without reverse engineering. - -17. **Outcome operations, not mechanism operations.** CapCut sells "hero time", not "speed - keyframes". Intent presets first, parameters later. - -18. **Competitors' weak points are OmaMovie's differentiators**: paywall and content terms - (CapCut), subscription (Premiere), crashes with lost work (Premiere, CapCut, Shotcut), slow - preview (Shotcut), learning curve and demanding hardware (Resolve). Offline, no account, - stable and GPU-first. - -### Architecture requirements that emerged - -| Requirement | Origin | Affects | -|---|---|---| -| Fast seek and a multi-density thumbnail cache with aggressive cancellation | Skimming (iMovie), semantic zoom (Movie Maker) | `media`, cache, job system | -| Interactive preview overlays that emit commands | Crop/position/eyedropper in the viewer (iMovie) | PreviewPanel, `timeline` | -| Magnetism as a UI editing policy, not a model restriction | Magnetic timeline (iMovie/FCP X) | `timeline` | -| GPU capability declared per effect and indication of non-real-time sections | Mercury (Premiere) | `compositor`, UI | -| Templates produce a normal, editable timeline | Trailers (iMovie), AutoMovie | `timeline`, `project-ir` | -| Per-stream color metadata and color-space-aware effects | Color management (Premiere) | `media`, `compositor` | -| Editing during playback (dynamic trim) | Premiere | Threading (ADR-0003) | -| **Curve-based time mapping** (not only constant speed), decided before implementing speed | Speed ramps (CapCut) | `base` time, `timeline` (ADR-0002) | -| A first-class caption/text track, SRT/VTT import/export | CapCut, Premiere, Resolve | `timeline`, `project` | -| A canvas with changeable aspect ratio; decide normalized coordinates vs. pixels | Vertical/horizontal (CapCut, Clipchamp) | `compositor`, `timeline` | -| Markers in the timeline model | Beat sync (CapCut), review | `timeline` | -| Serializable commands with no UI dependency (base for future scripting/MCP) | Scripting and MCP (Resolve 21.1) | `timeline` | -| An action system independent of the input device | Speed Editor (Resolve) | UI | -| Background render filling the cache when real time is not possible | Final Cut Pro | `compositor`, cache, job system | -| Transcript as a view of the timeline (words with a `TimeRange`) | Descript, Premiere | `timeline` (future) | -| Benchmarks including Intel/AMD integrated GPUs | Resolve needs strong hardware | `tools/bench` | - -### Suggested next research - -- **OpenTimelineIO**: data model as a reference for ProjectIR (priority, given Resolve's native support). -- **Final Cut Pro in depth**: storylines, roles, FCPXML (interop target). -- **Kdenlive/MLT internals**: MLT architecture, why 10-bit and GPU decode arrived late, project format (importer candidate). -- **Linux hardware pipeline**: current state of VA-API, Vulkan Video and DMA-BUF interop on Mesa/NVIDIA (technical base for `CLAUDE.md` §7.3). -- **Avid Media Composer and Vegas**: editing model and formats (future interop targets). +| Document | Scope | +|---|---| +| [Vulkan](vulkan.md) | API contracts, video capabilities, FFmpeg, Qt and libplacebo | +| [CUDA](cuda.md) | NVIDIA runtime/build distinction, interop and proposed comparison | +| [OpenCL](opencl.md) | Scope exclusion; counterevidence to an impossibility claim | +| [Hardware strategy](hardware-strategy.md) | Device ownership, selection, experiments and fallbacks | +| [Omarchy integration](omarchy-integration.md) | Installed-file observations and version-sensitive adapters | +| [Premiere](premiere-pro.md) | Editing, color and importer hypotheses | +| [Final Cut Pro](final-cut-pro.md) | Anchored editing, precise placement, recovery, proxies and bounded FCPXML | +| [VEGAS Pro 23](vegas-pro.md) | Source trimming, ripple scope, sync links, takes and adjustment events; bounded OmaMovie pilots | +| [iMovie](imovie.md) | Contextual controls and transferable UX proposals | +| [Movie Maker / Clipchamp](movie-maker.md) | Historical limits and current documented interactions | +| [Resolve](davinci-resolve.md) | Versioned codec evidence and limits of competitive inference | +| [CapCut](capcut.md) | Documented captions/curves; unmeasured audience preferences | +| [Other editors](other-editors.md) | Credible baselines and bounded comparisons | +| [GPU effects](gpu-effects.md) | Grading (CDL, curves, 3D LUTs), multi-pass cost, keyframes; measured locally | +| [Post-production effects and catalog](post-production-effects.md) | Core effect choices from editor research, candidates to remove, and staged third-party marketplace | +| [Agent-assisted editing with MCP](agentic-mcp.md) | Local project tools, bounded edit proposals, approval, protocol limits and pilot gates | +| [Long-form editing](long-form-editing.md) | Project size versus duration, timeline/UI scaling, proxies, preview cache, recovery and export gates | + +## Evidence rules + +- **Documented** means a cited passage or local API contract supports the stated scope. +- **Observed locally** describes the installed files or a named experiment, with versions. +- **Hypothesis / inference** names a proposed explanation or deduction, with a disconfirming check. +- **Preference** records a product/engineering choice; competitor behavior cannot prove it. +- **Pending** means the decisive check has not run. A checkbox for implementation is not validation. + +Sources are linked beside claims. Multiple vendor pages from one organization are one +lineage, not independent measurements. Marketing pages establish advertised features only. +Unverified release details, prices, legal interpretations and anecdotal complaint rankings +have been removed from active guidance; git history retains the earlier text. + +## Supported synthesis + +[Read the synthesis](synthesis.md) diff --git a/Docs/Research/agentic-mcp-alternatives.md b/Docs/Research/agentic-mcp-alternatives.md new file mode 100644 index 0000000..76942c4 --- /dev/null +++ b/Docs/Research/agentic-mcp-alternatives.md @@ -0,0 +1,21 @@ +## Alternatives and discriminating checks + +| Option | Benefit | Cost / decisive check | +|---|---|---| +| Manual GUI baseline | Existing undo and visible timeline. | Measure correction steps, completion and unexpected changes for the same exact-time tasks. | +| Deterministic `oma-project` CLI or macro | Smallest reuse of existing commands; reproducible without a model. | If it handles the task with equal effort/accuracy, MCP adds little product value. | +| MCP read/propose adapter | External hosts can discover typed project data and actions. | Check real host compatibility, typed-output fidelity, privacy and maintenance cost; not proof of model quality. | +| Embedded AI assistant | Integrated preview/approval may fit editing better. | Requires a chosen model, UX, cost/privacy policy and MCP **client** only if connecting to external servers; defer until the external-host pilot identifies unmet needs. | + +**Proposed local pilot, not executed:** after M7, use small synthetic projects +with stable media and an adversarial filename/metadata string containing tool +instructions. Run 10–20 exact-time editing tasks through GUI, CLI and one pinned +MCP host/model on the same fixtures. Record version, prompt, tool calls, elapsed +time, user corrections, final timeline diff, undo result, disclosure of media +content and errors. Require no unintended edits, correct atomic undo, stale +revision rejection and no action induced by the adversarial metadata before +considering broader use. Compare completion effort only on successful tasks; +report failures separately. Sample size is a pilot, not a general usability +estimate. A second pilot would need representative user tasks and media. + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp-architecture.md b/Docs/Research/agentic-mcp-architecture.md new file mode 100644 index 0000000..f2d19ef --- /dev/null +++ b/Docs/Research/agentic-mcp-architecture.md @@ -0,0 +1,43 @@ +## Proposed architecture and minimal contract + +```text +external AI host + MCP client + | local stdio (one chosen project) + oma-mcp adapter + | typed, bounded calls + project service / Editor commands / M7 persistence + | user-visible proposed diff and one undo transaction + OmaMovie UI +``` + +The adapter is **not** a plugin loader or a second timeline implementation. +For an offline project, it can reuse a headless application service after M7; +for a project open in the GUI, the bridge must marshal edits to the owning UI +thread. Do not let two independent `Editor` instances overwrite the same file. +Before implementation, an ADR must choose one ownership path and specify +locking, save, crash recovery and UI presentation. + +Suggested initial operations, subject to the ADR and a real host test: + +1. Read-only `project_summary`, `list_media`, `read_timeline` with pagination, + stable clip/media IDs, rational time as numerator/denominator/timebase, and + a persisted project content revision. Optional thumbnail sampling is + explicitly bounded by count, resolution and media path; no transcript or + scene semantics are claimed. +2. `propose_edit` accepts a bounded list of **typed existing commands** and an + expected project revision; it dry-runs validation on a copy, returning a + structured before/after diff, warnings, affected clip IDs and a proposal + token. The server rejects free-form code, shell commands and unknown fields. +3. The OmaMovie UI shows the proposal and lets the user apply or reject it. + Apply checks project identity and revision again and executes one + transaction through `Editor::execute`; stale proposals fail without change. + If a mutating MCP tool is later needed, require an approval artifact minted + by the trusted app after showing the exact diff. A model-supplied boolean is + not approval. Design retry/idempotency behavior before exposing that tool. + +Read-only tools can be useful sooner, but cannot validate “agent edits” alone. +The pilot does not require an embedded chat panel, a specific model provider, +network access, or the MCP Tasks extension. A fixed tool vocabulary also avoids +making every low-level timeline primitive an independent model action. + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp-criteria.md b/Docs/Research/agentic-mcp-criteria.md new file mode 100644 index 0000000..3049ce3 --- /dev/null +++ b/Docs/Research/agentic-mcp-criteria.md @@ -0,0 +1,26 @@ +## Question, hypotheses and decision criteria + +**Question:** Does a local MCP adapter help a user complete precise, reviewable +edits in OmaMovie better than the current GUI or a deterministic CLI/script? +Criteria set before results: correct media/time selection, no hidden edits, +recoverable one-step undo, refusal of stale/conflicting proposals, bounded +media exposure, and task completion effort. Cost includes implementation, +model/API use, data disclosure and extra approvals. The first research budget +was four targeted search passes plus the official protocol's architecture, +tools, resources, transport, security and Tasks pages, and local API inspection. + +| Hypothesis | Prediction that would support it | What would weaken it | +|---|---|---| +| H1: structured project tools improve edit planning | In the same exact-time tasks, an external host using OmaMovie tools makes fewer invalid operations or needs less user correction than generic file/shell access. | No advantage over a small CLI or a saved edit macro. | +| H2: proposal + review makes agent edits controllable | Users can identify the affected clips/ranges before apply, reject wrong edits, and undo an applied batch in one step. | The preview hides material side effects or users still accept wrong edits. | +| H3: MCP is the right interface | A compatible host can discover, read and call the tools without OmaMovie-specific integration while the core logic remains reusable. | Host/version support or protocol maintenance costs outweigh reuse; a CLI meets the use case. | + +“Agentic” here means a host can choose a sequence of project queries and edits +to meet a user goal. MCP supplies the tool contract; it does not provide the +model, visual understanding, reliable planning, or safe authorization. The +[MCP architecture overview](https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture) +separates host, client and server and says the protocol does not dictate how an +AI application uses an LLM. This is a **verified protocol distinction**; +OmaMovie's proposed workflow is an **engineering inference**. + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp-protocol.md b/Docs/Research/agentic-mcp-protocol.md new file mode 100644 index 0000000..9a9f035 --- /dev/null +++ b/Docs/Research/agentic-mcp-protocol.md @@ -0,0 +1,17 @@ +## Protocol evidence and design consequences + +| Official contract, 2026-07-28 | Consequence for OmaMovie | +|---|---| +| [Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools), “Tool”, “Structured Content”, “Security Considerations”: tools have JSON Schema input and optional output, structured results, and server-side validation/access control. Tool annotations are untrusted hints. | Publish a small set of typed read/propose actions. Validate stable IDs, rational times, ranges and project access in the server. Do not use annotations or prompt text as enforcement. | +| [Resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources), “Resource Contents” and “Security Considerations”: text/binary resources, templates and URI/path validation. | Expose bounded project summary/timeline/media metadata and optional small thumbnails, not arbitrary paths or raw project files by default. Media filenames and metadata returned to a model are untrusted data. | +| [stdio transport](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio) and [security guidance](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices), “Local MCP Server Compromise”: local child-process transport avoids a listening port; a local server still has the user's filesystem privileges. | Pilot with a packaged, client-launched `stdio` server, scoped to one explicitly chosen project. No network listener, arbitrary shell tool or unrestricted filesystem resource. Restrict process permissions where feasible. | +| [2026 revision overview](https://blog.modelcontextprotocol.io/posts/2026-07-28/), “No handshake or sessions” and “Tasks”: cross-call state uses explicit handles; older lifecycle assumptions changed. | Pin a protocol/SDK revision and test real hosts. A project handle is not authorization; use project identity plus a persisted content revision and check both again at apply time. | +| [Tasks extension](https://tasks.extensions.modelcontextprotocol.io/), “Architecture” and “Cancellation”: long work can return a durable task ID; cancellation is cooperative and requires client support. | Export/proxy work may use Tasks later, only after M7 jobs exist and the chosen host supports the extension. A short edit proposal does not need a task store. | + +The 2026-07-28 spec is the inspected version, not a promise of support by every +host. Annotations such as `readOnlyHint` help clients present risk but are +explicitly not security controls; see the [maintainers' explanation](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/), +“What Annotations Can't Do”. MCP security guidance also warns that explicit +state handles must not be treated as authentication (“State Handle Hijacking”). + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp-scope.md b/Docs/Research/agentic-mcp-scope.md new file mode 100644 index 0000000..33358a8 --- /dev/null +++ b/Docs/Research/agentic-mcp-scope.md @@ -0,0 +1,19 @@ +## Conclusion and scope + +An OmaMovie MCP **server** is a plausible adapter for an external AI host to +inspect a local project and propose edits. It should call the same validated +timeline/project operations as the UI, and keep the model outside the rendering +engine. The first useful task is bounded: “In this saved project, split the +selected shot at a specified time, remove a specified range, and lower a named +audio clip's gain; show the exact proposed changes before applying.” This tests +command composition and human review without assuming speech recognition, +semantic scene understanding, or automatic selection of “good” footage. + +The pilot belongs **after M7 save/load**. Today the README says sessions cannot +be saved or exported. The existing [Editor API](../../libs/timeline/include/oma/timeline/editor.hpp) +already supplies atomic commands, undo/redo and a changing in-memory revision; +its state belongs to the UI thread. That is a credible execution core, but not +yet a durable cross-process automation surface. An ADR is required before +committing to AI or a new dependency under `CLAUDE.md` §§2, 20–21. + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp-sources.md b/Docs/Research/agentic-mcp-sources.md new file mode 100644 index 0000000..89fa195 --- /dev/null +++ b/Docs/Research/agentic-mcp-sources.md @@ -0,0 +1,16 @@ +## Source and stopping record + +Accessed **2026-10-04**. MCP project/maintainer pages above were read in HTML; +their protocol version is 2026-07-28, while individual page publication/update +dates were not exposed except the dated 2026-07-28 release post and 2026-03-16 +annotation post. These pages share the MCP project's evidential lineage and +establish protocol behavior, not editing effectiveness or actual host support. +Local `README.md`, `CLAUDE.md`, `Docs/implementation-plan.md`, +`libs/timeline/include/oma/timeline/editor.hpp` and `edit.hpp` were inspected +from this working tree, which contains uncommitted changes. No MCP server, +host integration, security test, user study or benchmark was executed. The +investigation stops at a bounded design: the decisive missing observation is +whether a real host improves precise edits over CLI/GUI once durable projects +exist. If not, keep the deterministic automation surface and stop the MCP pilot. + +[Return to agentic-mcp.md](agentic-mcp.md) diff --git a/Docs/Research/agentic-mcp.md b/Docs/Research/agentic-mcp.md new file mode 100644 index 0000000..e9bfce6 --- /dev/null +++ b/Docs/Research/agentic-mcp.md @@ -0,0 +1,28 @@ +# Agent-assisted editing with MCP + +> Skeptical research, 2026-10-04. This is an architecture and product pilot, +> not an implemented feature or a claim that an LLM can edit video reliably. + +## Conclusion and scope + +[Read this section](agentic-mcp-scope.md) + +## Question, hypotheses and decision criteria + +[Read this section](agentic-mcp-criteria.md) + +## Protocol evidence and design consequences + +[Read this section](agentic-mcp-protocol.md) + +## Proposed architecture and minimal contract + +[Read this section](agentic-mcp-architecture.md) + +## Alternatives and discriminating checks + +[Read this section](agentic-mcp-alternatives.md) + +## Source and stopping record + +[Read this section](agentic-mcp-sources.md) diff --git a/Docs/Research/capcut.md b/Docs/Research/capcut.md index db4d9ad..31da8bb 100644 --- a/Docs/Research/capcut.md +++ b/Docs/Research/capcut.md @@ -1,133 +1,55 @@ -# CapCut: what people like (and dislike) +# CapCut: documented features and untested preferences -> Research done on 2026-10-02. Sourced facts are linked in the [Sources](#sources) section. -> Part of the CapCut sources are promotional material or written by competitors (e.g. VEED, -> Podcastle). Read prices and complaints with that in mind. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +Editable timed captions and speed curves are documented feature references. They do not +establish market dominance, universal demand, or the right order of OmaMovie milestones. +Offline/no-account operation remains a project preference, not proof of competitor failure. -CapCut (ByteDance) is the most popular editor among short-form creators. People like it for -**time to result**: +## 2. Inspected product evidence -1. **Templates** where you only swap the clips; -2. editable **automatic captions**; -3. ready-made **"trending" effects** (speed ramps, transitions, stickers); -4. a **clean**, drag-and-drop **interface** you learn in minutes; -5. **cross-platform** with sync (phone → desktop). +[CapCut's guide](https://www.capcut.com/resource/how-to-use-capcut) describes speed curves +and editable presets alongside effect keyframes. [Its caption page](https://www.capcut.com/tools/auto-caption-generator) +describes generating, correcting and styling timed text. These are promotional primary +sources: they establish advertised workflows, not accuracy, completion times or plan +availability for every region/app/version. -And dislike: an **aggressive paywall** (the Pro price doubled in 2025), **terms of service** -that give ByteDance a perpetual license over content (including drafts), **political -instability** (bans) and **crashes that lose work**. +The former price-doubling, bans, perpetual-license/draft claims and billing/crash complaints +were based on commentary, with no verified applicable policy/jurisdiction or representative +sample. They are removed from active guidance. No legal conclusion is made by this audit. -For OmaMovie, CapCut shows **which high-level operations the audience wants**, and its weak -points are obvious differentiators: offline, no account, no paywall and the user's content -under the user's control. +## 3. Foundations: time mapping ---- - -## 2. What people like - -### 2.1 Time to result -The most repeated argument: going from raw footage to a finished video in minutes. Templates, -presets and automation exist for that. - -### 2.2 Templates -- Ready templates where the user **only swaps photos or clips**. -- Templates follow **trends** (TikTok integration), making it easy to join trends and viral challenges. - -### 2.3 Automatic captions -- Generated by AI from the audio and **editable** afterwards. -- Important because a lot of social video is watched **without sound**. -- The feature most often cited as "saves a lot of time". - -### 2.4 Speed ramps (speed curves) -- Speed > Curve with named presets: **bullet, montage, jump cut, hero time, flash in, flash - out**, all customizable. -- They create progressive slow motion and accelerations without manual keyframes. - -### 2.5 Other high-level features -| Feature | What it does | -|---|---| -| Keyframes | On "every setting" | -| Auto Reframe | Detects the subject and recomposes for another aspect ratio (e.g. horizontal → vertical) | -| Beat Sync | Aligns cuts to the music's beat | -| Text-to-speech | Several voices and languages | -| Background removal | Without a green screen | -| Chroma key, stabilization, motion tracking | Free when CapCut became popular | -| Library of stickers, effects, transitions, audio | Ready-made content | - -### 2.6 Interface -- "Clean, straightforward", drag and drop; you start editing within minutes. -- A conventional multitrack timeline on desktop. -- **Mobile-first**: the phone version is the most polished; the desktop one is described as less polished. -- iOS, Android, web and desktop: start on the phone and finish on the computer. - ---- - -## 3. What people dislike - -| Problem | Detail | -|---|---| -| **Price** | In May 2025 Pro went from US$ 9.99 to US$ 19.99/month. Dynamic captions, effects and cloud storage moved behind the paywall | -| **Billing and support** | Complaints about charges after cancellation and slow support, limited to FAQs and email | -| **Terms of service (June 2025)** | A **perpetual, irrevocable, worldwide, royalty-free** license for ByteDance over all uploaded content, **including unpublished drafts**, even after deleting the account. A risk for agencies and NDA-bound content | -| **Availability** | Banned in India since 2020; in the US, banned in January 2025 and, according to VEED's review, unavailable for new downloads in US app stores | -| **Content removal** | May remove content without notice | -| **Stability** | Reports of crashes while editing with **lost work** | - ---- +Speed is the derivative of source position with respect to timeline time. If timeline time +is `t` seconds and dimensionless speed is `s(t)`, source time is +`m(t) = m(0) + integral_0^t s(u) du`. Merely interpolating source timestamps is not always +the same as interpolating speed; define the interpolation and endpoint duration explicitly. +A frozen segment has a duration despite zero source displacement. Reverse playback needs +a decreasing source map and audio policy. Exact endpoints do not make arbitrary curve +samples exact rationals. See the audit calculation and ADR-0002 review note. ## 4. Implications for OmaMovie -### 4.1 Obvious differentiators - -What CapCut does not offer and OmaMovie offers by definition: - -- **Offline and local**: media and project never leave the machine. -- **No account, no terms over the user's content, no feature paywall, no watermark.** -- **Stability and preservation of work**: atomic save and autosave (`CLAUDE.md` §14). Lost work - is the most serious complaint about any editor. - -### 4.2 Features to consider and their architectural impact - -| CapCut feature | Recommendation | Architectural impact | +| Choice | Supported application | Pending dependency | |---|---|---| -| **Speed ramps with presets** | Yes, medium term | **Mapping timeline time → media time cannot be "constant speed" only.** It needs a **curve** (piecewise monotonic function), evaluated in `RationalTime`. Decide in ADR-0002 (time representation) **before** implementing speed, even if the first UI only has constant speed. Frame interpolation (optical flow) is a later, separate step | -| **Keyframes everywhere** | Yes | Already planned. Effect and transform parameters must be animatable by default, not by exception | -| **Captions as a first-class element** | Yes | A **caption/text** track type in the model, with SRT/VTT import/export. Generating captions automatically needs transcription, an AI non-goal; if it ever lands, prefer a **local** (offline) model and keep the result as ordinary editable captions | -| **Changing the project aspect ratio (vertical/horizontal)** | Yes | The project canvas must be resizable without breaking the edit. Decide in the compositor ADR whether transforms are stored in **normalized coordinates** or pixels, and what happens when the aspect ratio changes. Auto Reframe (subject detection) comes later | -| **Templates** | Future | Same conclusion as iMovie: a template produces a normal, editable timeline (`imovie.md` §7) | -| **Beat sync** | Future | Needs beat detection (audio analysis, no heavy AI) and timeline markers. Markers must exist in the model | -| **Named effect/transition presets** | Yes | Presets are data (saved parameters) over generic effects, like iMovie's overlay presets | -| **Text-to-speech, background removal, stock** | Not now | Non-goals (AI/cloud) | -| **Cross-platform sync** | No | Non-goal (cloud). A file-based project already lets users sync with their own tools | - -### 4.3 Audience - -CapCut shows that the vertical short-form audience is large and wants **outcome operations** -("make it dramatic slow motion"), not **mechanism operations** ("add a speed keyframe"). For -OmaMovie: the inspector offers the intent preset first and the parameters afterwards. The same -principle as iMovie's named operations. - -### 4.4 What not to copy - -- A "trends" library and stock content (needs a server). -- A mobile-first interface. -- Account and cloud dependence. - ---- - -## Sources - -- [App Store: CapCut](https://apps.apple.com/app/1500855883) -- [Microsoft Store: CapCut](https://apps.microsoft.com/detail/xp9kn75rrb9nhs) -- [CapCut: How to use CapCut (official guide)](https://capcut.com/resource/how-to-use-capcut) -- [The Nerd in Charge: Why I'm obsessed with CapCut](https://thenerdincharge.substack.com/p/dont-just-survivestorytell-it-why) -- [ABNewswire: CapCut is basically the cheat code for making videos](https://markets.financialcontent.com/lightport.lightport5/article/abnewswire-2025-12-30-capcut-is-basically-the-cheat-code-for-making-videos-that-dont-look-boring) -- [Skillademia: CapCut keyboard shortcuts](https://www.skillademia.com/shortcuts/capcut-shortcuts/) -- [VEED: CapCut review 2026](https://www.veed.io/learn/capcut-review) -- [Podcastle: CapCut's latest terms of service and pricing](https://podcastle.ai/blog/capcut-terms-of-service) -- [Fluxnote: CapCut questions answered (June 2026)](https://fluxnote.io/guides/capcut-questions-answered) -- [Wikipedia (mirror): CapCut](https://wiki.krisyotam.com/content/wikipedia_en_all_nopic_2026-03/CapCut) +| Captions | First-class timed text; SRT/VTT pilot in M8 | Timing/layout/encoding/round-trip tests | +| Speed curves | Explicit TimeMap domain, rounding and interpolation | Complementary ADR and reverse/freeze tests | +| Intent presets | Normal editable commands/parameters | Discoverability/recovery in M6/M8 | +| Resizable canvas | Define transform anchoring before implementation | Coordinate ADR, portrait/landscape tests | +| Transcription | Separate generator of editable timed text | Concrete local use case; remains non-goal initially | + +Imported captions can exist without speech recognition. A preset UI does not require cloud +stock, account infrastructure or a separate project model. + +## 5. Proposed discriminating test + +Compare preset-first with parameter-first controls on identical simple tasks (caption +correction, slow motion, overlay) and mixed-duration media. Record completion/errors, undo, +output timing and ability to adjust after applying a preset. The claim would weaken if +presets hide important changes or slow experienced users without helping beginners. +No task study or caption-accuracy benchmark was executed. Defer high-cost automation until +basic editing proves useful; no feature inherits priority merely from CapCut advertising it. diff --git a/Docs/Research/cuda-hybrid-systems.md b/Docs/Research/cuda-hybrid-systems.md new file mode 100644 index 0000000..6724762 --- /dev/null +++ b/Docs/Research/cuda-hybrid-systems.md @@ -0,0 +1,7 @@ +## 6. Hybrid systems and scope + +One selected GPU per pipeline is a preference that limits cross-device complexity. Verify +CUDA UUID against Vulkan identity and the decode render node. Presentation can still involve +the desktop compositor's other GPU; one application device does not remove that cost. +Power-safe enumeration is unvalidated: capability queries may load drivers or wake devices. +Record power behavior before claiming otherwise. No NVIDIA/hybrid benchmark was run. diff --git a/Docs/Research/cuda.md b/Docs/Research/cuda.md index d7d2919..2e8ebce 100644 --- a/Docs/Research/cuda.md +++ b/Docs/Research/cuda.md @@ -1,149 +1,57 @@ -# CUDA and the NVIDIA path in OmaMovie +# CUDA and NVIDIA: runtime, interop and comparison -> Research done on 2026-10-02. Sourced facts are linked in the [Sources](#sources) section. -> Items marked **(verify)** need confirmation. -> -> Verified locally: `nvidia-utils` 610.57 provides `libcuda.so`, `libnvcuvid.so` (NVDEC) and -> `libnvidia-encode.so` (NVENC). The system FFmpeg was built with -> `--enable-nvdec --enable-nvenc --enable-cuda-llvm`. Arch's `cuda` package (toolkit) is -> **4.71 GiB** and is not installed. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +NVDEC/NVENC are candidates through the already packaged FFmpeg. CUDA effects remain optional +and require measured advantage. No NVIDIA GPU result exists in this review; S7 gates support. +The former approximately 5× encode claim is withdrawn as a selection rule: a forum report +cannot rank different settings, quality, hardware and driver versions for this project. -"Using CUDA" in OmaMovie means **three different things**, with very different costs: +## 2. Runtime versus build -| What | Needs the CUDA toolkit? | Gain | Recommendation | -|---|---|---|---| -| **NVDEC/NVENC** (hardware decode/encode) | **No**. FFmpeg loads the driver libraries at runtime | High: NVENC is about 5x faster than Vulkan Video encode on NVIDIA | **Yes, early** | -| **CUDA ↔ Vulkan interop** (bringing NVDEC frames to the Vulkan compositor) | No, it uses the driver API (`libcuda`) | Needed to keep frames in VRAM | **Yes**, together with NVDEC | -| **Our own CUDA kernels** (effects) | Only at build time (headers/libdevice); at runtime the driver is enough | Depends on the effect; Vulkan Compute covers most | **Only with a measured gain** | +[NVIDIA's FFmpeg guide](https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/ffmpeg-with-nvidia-gpu/index.html) +distinguishes runtime use from compiling its suggested toolkit/NPP-enabled configuration. +Its binary can run without the toolkit. For OmaMovie, linking the system FFmpeg is different +from rebuilding FFmpeg or writing CUDA kernels. Check the actual FFmpeg configuration and +SDK/driver compatibility; installed libraries alone do not establish supported devices/codecs. +[FFmpeg nv-codec-headers](https://github.com/FFmpeg/nv-codec-headers) is the interface source, +not proof that every FFmpeg configuration builds without any toolkit components. -Conclusion: on NVIDIA the biggest gain comes from NVDEC/NVENC, which **requires neither -distributing nor building with the toolkit**. CUDA kernels are a later specialization. +## 3. CUDA ↔ Vulkan ---- +[NVIDIA's external-resource API](https://docs.nvidia.com/cuda/cuda-runtime-api/cuda_runtime_api/group__CUDART__EXTRES__INTEROP.html) +documents handle-specific memory mappings and semaphore semantics. Binary and timeline +semaphores have different behavior; the old blanket prohibition on CUDA wait-before-signal +was not established by the inspected reference. Specify the exact handle type/API/version +and prove scheduler liveness rather than applying a forum observation universally. -## 2. NVDEC and NVENC +Possible path: export Vulkan storage, import in CUDA, copy NVDEC output device-to-device, +then synchronize Vulkan consumption. That GPU copy is not allocation-level zero-copy. +Matching the physical GPU, pitch/planes, allocation flags, handle ownership and teardown +are prerequisites. FFmpeg CUDA↔Vulkan mapping support must be checked in the installed +source/API and exercised; it is not assumed by this document. -- Part of the NVIDIA Video Codec SDK. FFmpeg accesses them through `ffnvcodec-headers`, which - **load `libcuda`/`libnvcuvid`/`libnvidia-encode` dynamically**. There is no build-time link - against NVIDIA libraries **(verify: known ffnvcodec behavior)**. -- A frame decoded by NVDEC lives in **CUDA memory** (FFmpeg's `cuda` hwaccel). -- NVENC accepts CUDA frames directly. -- Comparison reported on the NVIDIA forum: Vulkan Video encode ~194 fps vs. NVENC ~910 fps. +## 4. Kernel build -### Omarchy and NVIDIA -Omarchy installs `nvidia-open-dkms`, `nvidia-utils` and `libva-nvidia-driver` (GPUs with GSP) -and sets `LIBVA_DRIVER_NAME=nvidia` and `NVD_BACKEND=direct`. So VA-API exists on NVIDIA, but -through a translation layer on top of NVDEC. +PTX loaded by the driver and a Clang build are possible future approaches, not a mandated +build architecture. Compiler/toolkit/libdevice compatibility, PTX target, initialization +cost and distribution terms need a concrete kernel/configuration review before adoption. +Do not make toolkit size a permanent architectural premise. Do not copy a vendor guide's +`--enable-nonfree` configuration into releases without the packaging license check. -**For OmaMovie:** on NVIDIA, use NVDEC/NVENC directly (FFmpeg's `cuda` hwaccel), not the VA-API -layer, which adds a translation step and has known DMA-BUF/NV12 limitations when imported by -Vulkan (see `vulkan.md` §4). +## 5. S7: proposed discriminating check ---- +Compare NVDEC + Vulkan interop, native Vulkan decode and software + upload on one NVIDIA +GPU. Use identical media, verify frame format/content, count host and device copies, and +report seek latency, end-to-end frame times, CPU/GPU/memory and initialization costs. +For encode compare codec/profile, quality or bitrate, rate control, preset, GOP and output +correctness as well as throughput. A faster encode at lower quality is not an equivalent win. +Reject a path on corruption, synchronization errors, unbounded memory or hidden fallback. -## 3. CUDA ↔ Vulkan interop +## 6. Hybrid systems and scope -The compositor is Vulkan, but the NVDEC frame is in CUDA memory. To avoid going through RAM: - -1. OmaMovie creates an **exportable** Vulkan image/buffer (`VK_KHR_external_memory_fd`, opaque fd handle). -2. CUDA imports that memory: `cuImportExternalMemory` (driver API) or `cudaImportExternalMemory` (runtime API). -3. The NVDEC surface is copied into it with a **device-to-device copy** (it stays in VRAM; not - zero-copy, but no download). -4. Synchronization through a **timeline semaphore** exported from Vulkan and imported into CUDA - (`cudaImportExternalSemaphore`, `cudaSignalExternalSemaphoresAsync`, `cudaWaitExternalSemaphoresAsync`). - -**Important restriction:** in CUDA it is **illegal to wait before the corresponding signal has -been issued**. Vulkan timeline semaphores' wait-before-signal does not hold on the CUDA side. -OmaMovie's scheduler must guarantee the order (signal submitted before the wait is submitted in CUDA). - -Alternatives to evaluate: -- **FFmpeg frame mapping** between the `cuda` and `vulkan` contexts **(verify whether FFmpeg 9 - supports `av_hwframe_map`/transfer CUDA→Vulkan without the CPU)**. If it does, it avoids - writing the interop by hand. -- **Vulkan Video decode directly on NVIDIA**: removes the interop. Decode performance (not - encode) must be measured before ruling it out. - ---- - -## 4. Our own CUDA kernels - -### When it would be worth it -- Heavy effects where CUDA has a **measured** advantage over Vulkan Compute on the same GPU - (e.g. mature libraries such as NPP, or kernels relying on specific features). -- `CLAUDE.md` already says: CUDA only where there is a real gain, and effects do not depend - directly on CUDA. - -### Building without `nvcc` and without requiring the toolkit at runtime -The system FFmpeg uses `--enable-cuda-llvm`: its CUDA kernels are compiled by **clang to PTX**. -The same pattern works for OmaMovie: - -1. `.cu` kernels compiled with **clang** to PTX (LLVM has supported CUDA since 3.9). The build - needs the CUDA headers/libdevice (`--cuda-path`). -2. The PTX is **embedded in the binary**. -3. At runtime, `libcuda.so` is loaded with `dlopen` (it ships with `nvidia-utils`) and the PTX - through the driver API (`cuModuleLoadData` / `cuLinkAddData`). The driver JITs it for the GPU present. - -Consequences: -- End users **do not** need to install the toolkit (4.7 GiB). -- Machines without NVIDIA load nothing; the CUDA backend simply does not appear. -- The CUDA build is **optional** (a Make option), so not every developer needs the toolkit. - ---- - -## 5. Hybrid laptops (Intel/AMD + NVIDIA) - -Omarchy detects hybrid GPUs and avoids waking the dGPU needlessly (its detectors read sysfs -instead of `lspci`, because waking the GPU exceeds Hyprland's reload time budget). - -**Implications for OmaMovie:** -- Device choice is a first-class decision: decoding on the dGPU and compositing/presenting on - the iGPU implies **a copy between GPUs** over the bus. -- Proposed initial rule: **one primary device for the whole pipeline** (decode, compositing, - preview), chosen by the user or by a heuristic (dGPU when plugged in?), and logged. -- Do not wake the dGPU just to enumerate capabilities; use sysfs/Vulkan information without - creating a device when possible **(verify)**. - ---- - -## 6. Licensing - -- Loading `libcuda`/`libnvcuvid`/`libnvidia-encode` dynamically from the installed driver is the - model used by FFmpeg and other free projects. -- The CUDA toolkit has its own EULA. Do not redistribute parts of the toolkit; the PTX OmaMovie - generates is project code **(verify the EULA regarding libdevice embedded in the PTX)**. - ---- - -## 7. Recommendations - -1. **Decode/encode phase (M1–M7)**: NVDEC/NVENC through FFmpeg on NVIDIA, no toolkit. -2. **Interop**: try FFmpeg's frame mapping first; if there is no CPU-free path, implement - external memory + timeline semaphore interop in `libs/gpu`. -3. **Benchmark**: NVDEC + interop vs. direct Vulkan Video decode on NVIDIA. Choose by measurement. -4. **Compute `CudaBackend`**: only after the Vulkan `ComputeBackend` exists and an effect has a - measured gain. PTX through clang, `dlopen` at runtime, optional build. -5. **Test hardware**: the current machine has no NVIDIA GPU (`nvidia-utils` is installed, but - `lspci` only shows the Iris Xe). Validating the NVIDIA path needs another machine. - ---- - -## Sources - -- [NVIDIA: CUDA Runtime API — External Resource Interoperability](https://docs.nvidia.com/cuda/cuda-runtime-api/group__CUDART__EXTRES__INTEROP.html) -- [NVIDIA: CUDA Driver API — Module Management](https://docs.nvidia.com/cuda/archive/13.2.2/cuda-driver-api/group__CUDA__MODULE.html) -- [NVIDIA Forums: cudaWaitExternalSemaphoresAsync blocks CPU kernel launch](https://forums.developer.nvidia.com/t/cudawaitexternalsemaphoresasync-blocks-cpu-kernel-launch/329028) -- [IWOCL 2025: SYCL interoperability (external memory/semaphores)](https://www.iwocl.org/wp-content/uploads/iwocl-2025-duncan-brawley-sycl-interoperability.pdf) -- [Intel: DPC++ Compatibility Tool — migration examples (Vulkan interop)](https://www.intel.com/content/www/us/en/docs/dpcpp-compatibility-tool/developer-guide-reference/2025-2/migration-examples.html) -- [vulkane: external memory export example](https://docs.rs/crate/vulkane/0.10.1/source/examples/external_memory_export.rs) -- [LLVM: Compiling CUDA with clang](https://llvm.org/docs/_sources/CompileCudaWithLLVM.md.txt) -- [NVIDIA Forums: Building CUDA code with clang](https://forums.developer.nvidia.com/t/building-cuda-code-with-clang/28781) -- [NVIDIA: Video Codec SDK](https://developer.nvidia.com/video-codec-sdk/download) -- [Phoronix: Using NVIDIA's NVENC on Linux with FFmpeg](https://www.phoronix.com/news/MTg0NTY) -- [Phoronix: FFmpeg NVDEC-accelerated H.264 decoding](https://www.phoronix.com/news/FFmpeg-NVDEC-H264-Acceleration) -- [Phoronix: NVIDIA VA-API driver 0.0.18](https://phoronix.com/news/NVIDIA-VA-API-Driver-0.0.18) -- [NVIDIA Forums: Vulkan Video is 5x slower than NVENC](https://forums.developer.nvidia.com/t/vulkan-video-is-5x-slower-than-nvenc/373916) -- Local Omarchy 4.0.4 files: `/usr/share/omarchy/install/hardware/nvidia.sh`, `/usr/share/omarchy/default/hypr/nvidia.lua` +[Read the hybrid systems assessment](cuda-hybrid-systems.md) diff --git a/Docs/Research/davinci-interchange.md b/Docs/Research/davinci-interchange.md new file mode 100644 index 0000000..a2c671a --- /dev/null +++ b/Docs/Research/davinci-interchange.md @@ -0,0 +1,18 @@ +## 5. OTIO and fidelity + +[OTIO's file specification](https://opentimelineio.readthedocs.io/en/latest/tutorials/otio-file-format-specification.html) +defines a versioned timeline schema. That makes a bounded first importer reasonable. This +review did not read a versioned Blackmagic OTIO export contract or run an export. The prior +"native since 18.5 including otioz" statement is not a validated end-to-end conversion path. +Obtain real, versioned exports and compare cuts, media references, time and unsupported +effects. Public schema accessibility is distinct from lossless application interoperability. + +## 6. Proposed audience check + +Baseline Kdenlive/Shotcut and the exact Resolve edition with the same phone/recording files. +Observe import friction, simple edit completion, preview deadlines and output correctness +on integrated graphics. The hypothesis is that local consumer-media editing with low setup +cost is useful on Omarchy. Evidence that existing tools already meet the tasks with similar +friction would weaken the proposed differentiation. No user or competitor benchmark ran. + +[Return to davinci-resolve.md](davinci-resolve.md) diff --git a/Docs/Research/davinci-resolve.md b/Docs/Research/davinci-resolve.md index dc20bdb..a91b52a 100644 --- a/Docs/Research/davinci-resolve.md +++ b/Docs/Research/davinci-resolve.md @@ -1,303 +1,51 @@ -# DaVinci Resolve: why it is a powerful editor +# Resolve: versioned Linux constraints and product hypotheses -> Research done on 2026-10-02 (current version: Resolve 21.x). Sourced facts are linked in the -> [Sources](#sources) section. Items marked **(general knowledge)** are widely documented but -> have no specific source in this research; verify before using them as requirements. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +The inspected codec matrix supports a bounded Linux codec-accessibility opportunity. +It does not establish that only NVIDIA can run Resolve, that ALSA prevents use on PipeWire, +or that the market between consumer and professional Linux editors is empty. -Resolve is powerful for five reasons: +## 2. Version and source boundaries -1. **Cinema-grade color.** It was born as a color correction system, and its node-based grading - is considered the industry standard. -2. **Everything in one program.** Editing, compositing (Fusion), color, audio (Fairlight) and - delivery as "pages" of the same app, on the same project. -3. **Two editing philosophies.** The **Cut** page is fast and lean; the **Edit** page is the full traditional NLE. -4. **Pricing model.** A very capable free version, and Studio as a **one-time purchase** (about US$ 299). -5. **It runs natively on Linux**, which none of the big competitors do. +The [current Blackmagic product page](https://www.blackmagicdesign.com/products/davinciresolve/techspecs) +identifies Resolve 21 and editing, Cut, Color, Fusion and Fairlight contexts. It is product +information, not a benchmark or specification of private engine internals. This audit did +not verify the former 21.1/MCP/API counts or release chronology; those claims are withdrawn. -On the other hand: a steep learning curve, demanding hardware, and **on Linux the free version -does not decode H.264/H.265 or AAC**. That last point is very relevant for OmaMovie. +Codec evidence below comes from the **Resolve 20, July 2025** matrix. Do not silently apply +it to Resolve 21, different editions, containers or future updates. ---- +## 3. Linux codec evidence -## 2. History +[Blackmagic's supported-codec PDF](https://documents.blackmagicdesign.com/SupportNotes/DaVinci_Resolve_20_Supported_Codec_List.pdf), +printed pp. 11 and 14, under Rocky Linux 8.6 (CUDA): -**(general knowledge, unless stated)** - -| Year | Milestone | -|---|---| -| 1980s–2000s | da Vinci Systems builds color correction systems for telecine | -| 2009 | Blackmagic Design buys da Vinci | -| ~2011 | Free (Lite) version released | -| 2014 (v11) | Becomes a full editor (Edit page) | -| 2017 (v14) | Fairlight (audio) integrated | -| 2018 (v15) | Fusion (node compositing) integrated | -| 2019 (v16) | **Cut** page | -| 2020-11 | **Speed Editor** (dedicated editing keyboard) | -| v18 | "Databases" renamed "Project Libraries"; Blackmagic Cloud | -| v18.5 | Native **OpenTimelineIO** support | -| 2025-05 (v20) | 100+ new features, including AI tools | -| 2026-06 (v21) | **Photo** page, more AI tools | -| v21.1 | **MCP** support and 20 new scripting APIs | - ---- - -## 3. Pages: one app, several contexts - -| Page | Function | -|---|---| -| Media | Import and organization | -| **Cut** | Fast assembly | -| **Edit** | Full traditional editing | -| **Fusion** | Node-based compositing and VFX | -| **Color** | Node-based grading | -| **Fairlight** | Audio mixing and mastering | -| Deliver | Export | -| Photo (v21) | Photo editing with Resolve's color tools | - -Every page works on the same timeline and project. There is no export/import between apps, -unlike Premiere + After Effects + Audition, and that is cited as a reason for switching (see -`premiere-pro.md` §10). - -### Implications for OmaMovie - -- Pages are a third way to organize complexity, alongside Premiere's workspaces and iMovie's - contextual inspector. They work for professional workflows in phases (assemble → grade → - mix), but mean context switches and a dense interface on every page. -- For OmaMovie the contextual inspector stays the main model. A future "focus mode" (e.g. - full-screen color) may exist, but as an extension of the inspector, not an app inside the app. -- The strongest architectural lesson: **a single project model for every function**. Color, - audio and compositing read and write the same model. OmaMovie already follows this - (`timeline` → render graph); do not create parallel models per function. - ---- - -## 4. The Cut page: speed for professionals - -Introduced in v16 for fast assemblies on short deadlines: - -- **Source tape**: one button shows every clip in the bin in the viewer as **a single - continuous tape**. You can scrub through all the material and edit without hunting clip by clip. -- **Dual timeline**: the upper timeline shows **the whole program**; the lower one shows **the - working region** zoomed in. Both are editable. Blackmagic justifies it by saying that zooming - and scrolling the timeline is slow. -- A lean interface with fewer visible tools. -- Designed for the **Speed Editor** (§9). - -### Implications for OmaMovie - -- Blackmagic itself, owner of the most "complete" editor, created a simplified page. This - confirms **simple and fast are not opposites**: the Cut page is simple and made for - professionals on a deadline. -- The **dual timeline** is an alternative to Movie Maker's semantic zoom (`movie-maker.md` §4). - Both solve the same problem (overview + detail without constant zooming). Evaluate in the - TimelineView prototype: a compact overview bar (minimap-style) above the timeline may give - the benefit without duplicating the interface. -- **Source tape** is a way to browse the library with the same skimming engine (`imovie.md` §6). - Same technical requirement: fast seek and a thumbnail cache. - ---- - -## 5. Color - -- **Node-based grading**: each node is one correction step; nodes are connected, reordered and - changed without affecting the rest of the grade. Non-destructive by construction. -- Tools: color wheels, curves, **qualifiers** (selection by color/luminance), **power windows** (tracked masks). -- v21: viewing nodes as a **layer list** (layer-list node graph), up to 8-layer stacks per node, - improved ACES workflows, group grading with versions. -- Independent HDR trims for Dolby Vision, HDR10+ and HDR Vivid (21.1). - -### Implications for OmaMovie - -- **Resolve v21 added a layer-list view for the node graph.** Even for colorists, a pure graph - is not always the best interface. For OmaMovie: **render graph as a DAG internally, a list of - layers/effects in the UI**. The graph stays in the core; the UI shows the stack. -- Full node-based grading is an initial non-goal. But the effect interface should allow a color - effect to have several internal stages, so that door stays open. -- ACES and HDR reinforce ADR-0006 (working color space), in line with Premiere 25.2. - ---- - -## 6. Fusion and Fairlight - -- **Fusion**: node-based compositing integrated as a page. v20 brought more advanced multi-layer - compositing; v21/21.1 added the Krokodove toolset (70+ graphics, 3D and procedural tools). -- **Fairlight**: a complete audio workstation inside the editor; v20 brought IntelliCut (removes - silence and splits dialogue between speakers); v21 brought folder tracks. - -### Implications for OmaMovie - -- After Effects/Fusion-style compositing is a **non-goal**. Fusion shows the category's ceiling, - not a requirement. -- Audio: silence removal is a concrete, useful function for spoken content (podcasts, - tutorials). It can be done with audio level analysis, without AI. A low-cost future candidate. - ---- - -## 7. Projects: a database, not a file - -- Projects live in a **Project Library** (formerly "Database"): - - local: a structure managed by Resolve on disk; - - network: **PostgreSQL** (through the "DaVinci Resolve Project Server", a bundled PostgreSQL); - - **Blackmagic Cloud**: hosted libraries for collaboration. -- To get a portable file you must **export a `.drp`**, which contains timelines, edits, grades - and settings, **without media**. At the destination Resolve relinks. -- Forums report crashes and failures when copying libraries to PostgreSQL. - -### Implications for OmaMovie - -- The database model is great for studio collaboration but adds friction for individual users: - the project is not a file you can copy, version or send. -- **It reinforces the `CLAUDE.md` §14/§17 decision**: the project file is the source of truth; - SQLite only for indexes/cache/metadata. An OmaMovie project should be copyable, versionable - in git and attachable to an email. -- `.drp` is a potential import target. Investigate the format before prioritizing it (`Docs/formats/`). - ---- - -## 8. Interoperability - -- **Native OpenTimelineIO since v18.5**: import/export of `.otio` (timeline metadata only) and - `.otioz` (timeline plus media). -- XML, AAF and EDL **(general knowledge)**. - -### Implications for OmaMovie - -- **OTIO is the first interop target.** Resolve (and others) export OTIO natively. That enables - a Resolve → OmaMovie path **without reverse engineering**, validating `Importer → ProjectIR` - with an open, documented format. -- `.otioz` (timeline + media) is a good model for an eventual "export packaged project" in OmaMovie. - ---- - -## 9. Dedicated hardware: Speed Editor - -- An editing keyboard made for the Cut page (released in November 2020). -- A heavy metal **search dial** to move through the timeline quickly; with a trim button held, - the dial becomes a **real-time trim** control. -- Shuttle/jog/scroll buttons change the dial's mode; one key per editing function. -- USB-C or Bluetooth. - -### Implications for OmaMovie - -- Shows the value of mouse-free editing: the same principle as J/K/L in `CLAUDE.md` §11.2. -- The central action system must be **independent of the input device**: keyboard today, - jog/shuttle controllers (USB HID/MIDI) in the future, mapped to the same actions. Do not - implement it now; just do not couple actions to keyboard events. - ---- - -## 10. Scripting, AI and MCP - -- Scripting API (Python/Lua) **(general knowledge)**. 21.1 added 20 APIs (render presets, media - pool, multicam, timeline properties, audio normalization) and **dropped Python 2**. -- **MCP (21.1)**: assistants such as Claude and ChatGPT Codex drive Resolve in natural language - (analyze projects, organize media, change settings, batch render, build highlight reels). -- v20 AI: IntelliScript (timeline from a script), animated captions, Multicam SmartSwitch - (angle switching by who is speaking), Magic Mask, depth map. -- v21 AI: IntelliSearch, CineFocus, facial refinement. - -### Implications for OmaMovie - -- The timeline command system (`CLAUDE.md` §10: every edit is a command) is the natural base for - scripting and automation. A well-defined command serves the UI, the CLI, scripts and an - eventual MCP server. -- **Do not implement scripting now.** Just keep commands serializable and free of UI - dependencies, which undo/redo and tests already require. - ---- - -## 11. Resolve on Linux - -Highly relevant, because it is the professional editor an Omarchy user would use today. - -| Aspect | Situation | +| Entry inspected | Supported conclusion within that table | |---|---| -| Official distro | A **Rocky Linux 8.6**–based environment; Ubuntu/Mint work in practice | -| GPU | **NVIDIA with proprietary drivers** is the only officially supported path (CUDA ≥ 12.8, ≥ 4 GB VRAM). AMD with AMDGPU Pro works, but CUDA-only effects are slow. Intel is not mentioned | -| H.264/H.265 (Free) | **Decode and encode not supported** (licensing) | -| H.264/H.265 (Studio) | Decode supported; **encode only on NVIDIA** | -| AAC | **Not supported on Linux**, not even in Studio | -| Audio | ALSA documented; PipeWire not mentioned | -| Common workaround | Transcode with FFmpeg to DNxHR and remux audio to PCM before importing | - -### Implications for OmaMovie - -**This is the biggest opportunity found in the research.** On Omarchy the typical user has phone -video (H.264/HEVC + AAC), often an AMD or Intel GPU, and PipeWire. The free Resolve cannot open -that material without transcoding, and support outside NVIDIA is partial. - -OmaMovie can take exactly that space: -- H.264/HEVC/AV1 + AAC through FFmpeg and VA-API, **without transcoding**; -- **Intel and AMD as first-class citizens** (VA-API/Vulkan Video), not only NVIDIA; -- native PipeWire; -- packaging for Arch instead of "supported on Rocky Linux". - -This reinforces the priorities in `CLAUDE.md` §7.3. Hardware tests must cover AMD and Intel, not only NVIDIA. - ---- - -## 12. Weaknesses and criticism - -- **A steep learning curve** and a dense interface; professional defaults scare beginners. -- **Demanding hardware**; frequent complaints about performance and crashes on modest machines. -- Free version limits on resolution, effects, codecs and GPU use. -- Linux: codec and GPU limitations (§11). - -### Implications for OmaMovie - -- Resolve shows the capability ceiling but does not serve people who want to edit quickly on a - laptop. OmaMovie must **work well on modest hardware** (Intel/AMD integrated GPUs), with - proxies and explicit degradation instead of freezing. -- Benchmarks (`CLAUDE.md` §23) must include at least one machine with an integrated GPU. +| H.264/H.265 mov/mkv/mp4 | Decode marked Studio only, acceleration on NVIDIA; encode Studio + NVIDIA | +| AAC / m4a | Decode/encode marked unavailable | +| Linux section title | Documents a CUDA configuration; does not prove all other GPU APIs impossible | ---- +This is documentary analysis, not a local Resolve installation test. The old blanket +"NVIDIA only officially supported" and ALSA/PipeWire exclusion are not inferred from a codec +matrix. Edition-specific media restrictions must be rechecked before public comparisons. -## 13. Prioritization table for OmaMovie +## 4. UX and project inference -| Resolve capability | Adopt? | When | Module | -|---|---|---|---| -| A single project model for every function | Yes (already planned) | From the start | `timeline`, `project` | -| Overview + detail timeline (dual timeline / minimap) | Evaluate in the prototype | Phase 10 | UI | -| Source tape (library as a continuous tape) | Evaluate | After the library | UI, `media` | -| Internal DAG render graph, layer-stack UI | Yes | Phase 5 | `compositor` | -| OTIO import | Yes, first interop target | Phase 12 | `importers` | -| Projects in a database | **No**; the file is the source of truth | — | `project` | -| Silence removal | Future, without AI | After audio | `audio` | -| Actions independent of the input device | Yes (design) | Phase 10 | UI | -| Serializable commands (base for scripting/MCP) | Yes (design) | Phase 9 | `timeline` | -| Scripting/MCP | Not now | Future | — | -| Full Fusion/Fairlight | No | Non-goal | — | -| Consumer codecs + AMD/Intel + PipeWire on Linux | **Yes, a differentiator** | Phases 2–8 | `media`, `audio` | -| `.drp` import | Investigate | Future | `importers` | +Cut and Edit suggest that the same product can present editing in different contexts. +For OmaMovie a minimap versus single zoomed timeline is still a testable preference; pages +or a node/layer view do not validate our exact layout or render-graph representation. ---- +Choose file-based project persistence for portability/recovery requirements. Database +storage can also provide transactions and portability via export; no storage form is +inherently unreliable. A database/workspace workflow does not prove that a file design is +universally better. `.drp` import remains uninvestigated, not an accessible-format promise. -## Sources +## 5. OTIO and fidelity -- [Blackmagic Design: DaVinci Resolve 20 announcement](https://www.blackmagicdesign.com/media/partial/release/20250404-02) -- [Post Magazine: Blackmagic Design unveils DaVinci Resolve 20](https://www.postmagazine.com/Press-Center/Daily-News/2025/Blackmagic-Design-unveils-DaVinci-Resolve-20-wit.aspx) -- [Post Magazine: Blackmagic Design releases v20 of DaVinci Resolve & Fusion](https://www.postmagazine.com/Press-Center/Daily-News/2025/Blackmagic-Design-releases-V-20-of-DaVinci-Resol.aspx) -- [Newsshooter: DaVinci Resolve 20 announced](https://www.newsshooter.com/2025/04/04/blackmagic-design-davinci-resolve-20-announced-with-100-new-features-including-ai-enhancements/) -- [Broadcast Now: NAB 2025 — AI rough cut and audio generation in Resolve](https://www.broadcastnow.co.uk/production-and-post/nab-2025-blackmagic-adds-ai-powered-rough-cut-and-audio-generation-to-resolve/5203915.article) -- [PetaPixel: DaVinci Resolve 21 officially released](https://petapixel.com/2026/06/03/davinci-resolve-21-officially-released-with-new-photo-editing-ai-tools/) -- [CineD: DaVinci Resolve 21 announced](https://www.cined.com/davinci-resolve-21-announced-new-photo-page-eight-new-ai-tools-tethered-camera-controls-and-more/) -- [Motion Media: DaVinci Resolve 21.1 update](https://www.motionmedia.com/mm-blog/davinci-resolve-21-1-update-new-features) -- [RedShark News: DaVinci Resolve 21.1 new features](https://www.redsharknews.com/davinci-resolve-21.1-new-features-release) -- [Storyblocks: Color grading in DaVinci Resolve](https://www.storyblocks.com/resources/tutorials/davinci-resolve-color-grading) -- [TourBox: A complete guide to nodes in DaVinci Resolve](https://www.tourboxtech.com/en/news/davinci-resolve-nodes.html) -- [Pro Video Coalition: DaVinci Resolve 16](https://www.provideocoalition.com/davinci-resolve-16-adds-lufs-audio-loudness-standards-linear-features/) -- [Wipster: Inside DaVinci Resolve's new Cut page](https://wipster.io/blog/inside-davinci-resolves-new-cut-page) -- [PremiumBeat: DaVinci Resolve 16 Cut page review](https://www.premiumbeat.com/blog/davinci-resolve-16-cut-page-review/) -- [Uncle: DaVinci Resolve Project Library vs database](https://tryuncle.com/learn/davinci-resolve/davinci-resolve-project-library-vs-database) -- [Blackmagic Forum: Copy DB from local to Postgres fails or crashes](https://forum.blackmagicdesign.com/viewtopic.php?p=746517) -- [Prism Pipeline: OpenTimelineIO integration](https://prism-pipeline.com/docs/latest/general/miscellaneous/opentimelineio/) -- [Digital Production: DaVinci Resolve Speed Editor release](https://digitalproduction.com/2020/11/11/davinci-resolve-speed-editor-release/) -- [tal.org: Blackmagic DaVinci Resolve on Linux](https://www.tal.org/tutorials/blackmagic-davinci-resolve-linux) -- [NixOS Wiki: DaVinci Resolve](https://wiki.nixos.org/wiki/DaVinci%20Resolve) -- [Blackmagic Forum: Can't play clips, use CUDA, .mp4 or h.264 in Linux](https://forum.blackmagicdesign.com/viewtopic.php?p=742208) -- [Movavi: How to use DaVinci Resolve (beginner's guide)](https://www.movavi.com/support/how-to/how-to-use-davinci-resolve/) -- [rfp.wiki: DaVinci Resolve vs Final Cut Pro](https://www.rfp.wiki/vendors/davinci-resolve/final-cut-pro) +[Continue in davinci-interchange.md](davinci-interchange.md) diff --git a/Docs/Research/evidence/2026-10-03-calculations.txt b/Docs/Research/evidence/2026-10-03-calculations.txt new file mode 100644 index 0000000..bfa2c78 --- /dev/null +++ b/Docs/Research/evidence/2026-10-03-calculations.txt @@ -0,0 +1,11 @@ +1920x1080 NV12: 3110400 bytes; 2.966309 MiB; one full-frame transfer at 60 fps: 0.186624 GB/s +1920x1080 P010: 6220800 bytes; 5.932617 MiB; one full-frame transfer at 60 fps: 0.373248 GB/s +1920x1080 RGBA16F: 16588800 bytes; 15.820312 MiB; one full-frame transfer at 60 fps: 0.995328 GB/s +3840x2160 NV12: 12441600 bytes; 11.865234 MiB; one full-frame transfer at 60 fps: 0.746496 GB/s +3840x2160 P010: 24883200 bytes; 23.730469 MiB; one full-frame transfer at 60 fps: 1.492992 GB/s +3840x2160 RGBA16F: 66355200 bytes; 63.281250 MiB; one full-frame transfer at 60 fps: 3.981312 GB/s +60 fps deadline: 16.666666666666668 ms +4K RGBA16F, 3 streams x 8 frames: 1518.75 MiB +10 s constant 2x: 20 s source +10 s linear 1x to 2x: 15.0 s source +10 s freeze: 0 s source diff --git a/Docs/Research/evidence/2026-10-03-local.txt b/Docs/Research/evidence/2026-10-03-local.txt new file mode 100644 index 0000000..58afc5f --- /dev/null +++ b/Docs/Research/evidence/2026-10-03-local.txt @@ -0,0 +1,48 @@ +Audit date: 2026-10-03 +Repository baseline: 2f6abf32e95a10f29ebeb39ac2b67ec36b297397 +Read-only environment observations; no GPU benchmark rerun. + +$ pacman -Q omarchy ffmpeg mesa qt6-base vulkan-headers +omarchy 4.0.4-1 +ffmpeg 2:9.0.1-4 +mesa 1:26.2.2-1 +qt6-base 6.11.2-3 +vulkan-headers 1:1.4.357.0-1 + +exit=0 + +$ pkg-config --modversion libavutil Qt6Quick +61.1.101 +6.11.2 + +exit=0 + +$ ffmpeg -version +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +built with gcc 16 (GCC) +configuration: --prefix=/usr --disable-debug --disable-static --disable-stripping --enable-amf --enable-avisynth --enable-cuda-llvm --enable-lto --enable-fontconfig --enable-frei0r --enable-gmp --enable-gnutls --enable-gpl --enable-ladspa --enable-lcms2 --enable-libaom --enable-libass --enable-libbluray --enable-libbs2b --enable-libdav1d --enable-libdrm --enable-libdvdnav --enable-libdvdread --enable-libfreetype --enable-libfribidi --enable-libgsm --enable-libharfbuzz --enable-libiec61883 --enable-libjack --enable-libjxl --enable-libmodplug --enable-libmp3lame --enable-libopencore_amrnb --enable-libopencore_amrwb --enable-libopenjpeg --enable-libopenmpt --enable-libopus --enable-libplacebo --enable-libpulse --enable-librav1e --enable-librsvg --enable-librubberband --enable-libsnappy --enable-libsoxr --enable-libspeex --enable-libsrt --enable-libssh --enable-libsvtav1 --enable-libtheora --enable-libv4l2 --enable-libvidstab --enable-libvmaf --enable-libvorbis --enable-libvpl --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxcb --enable-libxml2 --enable-libxvid --enable-libzimg --enable-libzmq --enable-nvdec --enable-nvenc --enable-opencl --enable-opengl --enable-shared --enable-vapoursynth --enable-version3 --enable-vulkan --disable-decoder=magicyuv +libavutil 61. 1.101 / 61. 1.101 +libavcodec 63. 1.101 / 63. 1.101 +libavformat 63. 1.101 / 63. 1.101 +libavdevice 63. 1.101 / 63. 1.101 +libavfilter 12. 1.101 / 12. 1.101 +libswscale 10. 1.101 / 10. 1.101 +libswresample 7. 1.101 / 7. 1.101 + +Exiting with exit code 0 + +exit=0 + +SHA-256 of inspected local sources (installed files, not upstream release provenance): +9d1aaeb0c16104d678742c04d6a8700fed365e7eb65a8eaef5fb3845ddf634e3 /usr/share/omarchy/version +2356e6e19656fcc67aa345fc46352a310945e54146706c039bf92a7bd3b3fb5a /usr/share/omarchy/bin/omarchy-theme-set +a429ed1b18114ff3e784fc4479c6b829e9effb64c0f9d22d3b15eda4c62d86b5 /usr/share/omarchy/bin/omarchy-theme-color +6d70541c44a82fde5a44d712f348df35f8372c080436433916694738627c4c66 /usr/share/omarchy/bin/omarchy-capture-screenrecording +fa35b43154b49a286c2717490a07b542b5868b3e5101e86e3df628b22bc55962 /usr/share/omarchy/default/hypr/windows.lua +e2409d80ef7e88455326e50f853d60bb18b2cf909b5820066bf46d538aaeedd7 /usr/share/omarchy/default/hypr/apps/davinci-resolve.lua +99434167d84b242050bbb32485679e92c29934fd5102df01265f7673612167fc /usr/share/omarchy/install/omarchy-base.packages +036d13f9b4e74653fbf18f30b867b5ec3397f39d87b97d0400aac3378d6a6603 /usr/share/omarchy/install/hardware/vulkan.sh +1c796829df784813ad53df48c967eb17281054a9b0ff544949be2ad3a1bcb946 /usr/share/omarchy/install/hardware/intel/video-acceleration.sh +aeb211e2a4c97eac7fd2ff8908e57b075dc2a125f66a2fe47e770c8cf7cc2634 /usr/include/libavutil/hwcontext_vulkan.h + +/usr/share/omarchy/version: 4.0.0.alpha diff --git a/Docs/Research/evidence/2026-10-03-make-test.txt b/Docs/Research/evidence/2026-10-03-make-test.txt new file mode 100644 index 0000000..4459c2e --- /dev/null +++ b/Docs/Research/evidence/2026-10-03-make-test.txt @@ -0,0 +1,960 @@ +Command: make test +Mode: debug, executed outside sandbox after sandbox GPU initialization failure +Exit status: 0 +Environment: 2026-10-03-local.txt +These are existing tests, not the proposed validation pilots. GPU-dependent branches may be conditional. + + +== base_tests (debug) + +● Rational + normalizes sign and common factors + ✓ r.has_value() to be truthy + ✓ r->num() to equal -3 + ✓ r->den() to equal 4 + rejects a zero denominator + ✓ r.has_value() to be falsy + ✓ static_cast(r.error().code()) to equal static_cast(ErrorCode::InvalidArgument) + rejects INT64_MIN because it cannot be negated + ✓ Rational::make(kMin, 1).has_value() to be falsy + ✓ Rational::make(1, kMin).has_value() to be falsy + orders fractions exactly + ✓ Rational::literal(1, 3) < Rational::literal(1, 2) to be truthy + ✓ Rational::literal(-1, 2) < Rational::literal(1, 3) to be truthy + ✓ Rational::literal(30000, 1001) > Rational::literal(29, 1) to be truthy + ✓ Rational::literal(kMax, 1) > Rational::literal(kMax - 1, 1) to be truthy + ✓ Rational::literal(kMax, kMax - 1) > Rational::literal(kMax - 1, kMax - 2) to be falsy + inverts and refuses to invert zero + ✓ Rational::literal(1001, 30000).inverse()->num() to equal 30000 + ✓ Rational::literal(0, 1).inverse().has_value() to be falsy + +● rescale + converts seconds to a 90 kHz timebase exactly + ✓ rescale_ok(1, kSecond, kTb90k, Rounding::Floor) to equal 90000 + converts one 29.97 fps frame to 90 kHz exactly (3003 ticks) + ✓ rescale_ok(1, kFrame2997, kTb90k, Rounding::Floor) to equal 3003 + rounds one 23.976 fps frame (3753.75 ticks) as requested + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Floor) to equal 3753 + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Ceil) to equal 3754 + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Nearest) to equal 3754 + rounds negative values toward the right direction + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Floor) to equal -3754 + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Ceil) to equal -3753 + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Nearest) to equal -3754 + breaks ties away from zero with Nearest + ✓ rescale_ok(1, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal 1 + ✓ rescale_ok(-1, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal -1 + ✓ rescale_ok(3, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal 2 + maps video frames to audio samples (29.97 fps at 48 kHz = 1601.6 samples) + ✓ rescale_ok(1, kFrame2997, kTb48k, Rounding::Nearest) to equal 1602 + ✓ rescale_ok(5, kFrame2997, kTb48k, Rounding::Nearest) to equal 8008 + ✓ rescale_ok(1, kFrame2997, Rational::literal(1, 44100), Rounding::Floor) to equal 1471 + handles ten hours of media in a 90 kHz timebase + ✓ rescale_ok(ten_hours, kTb90k, kTb48k, Rounding::Floor) to equal 10LL * 3600 * 48000 + ✓ rescale_ok(ten_hours, kTb90k, kFrame2997, Rounding::Floor) to equal 1078921 + reports overflow instead of truncating + ✓ static_cast(rescale_error(kMax, kSecond, kTb90k)) to equal static_cast(ErrorCode::Overflow) + ✓ rescale_ok(kMax, kTb90k, kSecond, Rounding::Floor) to equal kMax / 90000 + rejects non-positive units + ✓ static_cast(rescale_error(1, Rational::literal(0, 1), kSecond)) to equal static_cast(ErrorCode::InvalidArgument) + ✓ static_cast(rescale_error(1, kSecond, Rational::literal(-1, 25))) to equal static_cast(ErrorCode::InvalidArgument) + +● RationalTime + compares instants exactly across timebases + ✓ t(3003, kTb90k) == t(1001, kTb30k) to be truthy + ✓ t(48000, kTb48k) == t(90000, kTb90k) to be truthy + ✓ t(1, kTb48k) < t(2, kTb90k) to be truthy + ✓ t(-1, kTb48k) < t(0, kTb90k) to be truthy + compares extreme values without overflowing + ✓ t(max, kSecond) > t(max, Rational::literal(1, 2)) to be truthy + ✓ t(max, kTb90k) < t(max, kTb48k) to be truthy + ✓ t(max - 1, Rational::literal(1, max)) < t(1, kSecond) to be truthy + rejects a non-positive timebase + ✓ RationalTime::make(1, Rational::literal(0, 1)).has_value() to be falsy + ✓ RationalTime::make(1, Rational::literal(-1, 25)).has_value() to be falsy + rescales with explicit rounding + ✓ r->value() to equal 3754 + ✓ r->timebase() == kTb90k to be truthy + adds only within one timebase + ✓ t(10, kTb90k).plus(t(5, kTb90k))->value() to equal 15 + ✓ code_of(bad.error()) to equal static_cast(ErrorCode::InvalidArgument) + detects overflow in addition + ✓ code_of(r.error()) to equal static_cast(ErrorCode::Overflow) + +● TimeRange + is half-open + ✓ range->contains(t(100, kTb90k)) to be truthy + ✓ range->contains(t(149, kTb90k)) to be truthy + ✓ range->contains(t(150, kTb90k)) to be falsy + ✓ range->contains(t(99, kTb90k)) to be falsy + ✓ range->end().value() to equal 150 + checks membership across timebases + ✓ range->contains(t(89999, kTb90k)) to be truthy + ✓ range->contains(t(90000, kTb90k)) to be falsy + detects overlap + ✓ a->overlaps(*b) to be falsy + ✓ a->overlaps(*c) to be truthy + rejects negative durations and mixed timebases + ✓ TimeRange::make(t(0, kTb90k), t(-1, kTb90k)).has_value() to be falsy + ✓ TimeRange::make(t(0, kTb90k), t(1, kTb48k)).has_value() to be falsy + +● FrameRate + represents NTSC rates as exact fractions + ✓ fr::k29_97.fps() == Rational::literal(30000, 1001) to be truthy + ✓ fr::k59_94.frame_duration() == Rational::literal(1001, 60000) to be truthy + maps frame 300 at 29.97 fps to 10.01 s + ✓ at == t(1001, Rational::literal(1, 100)) to be truthy + maps a time back to a frame with explicit rounding + ✓ *fr::k29_97.time_to_frame(t(10, kSecond), Rounding::Floor) to equal 299 + ✓ *fr::k29_97.time_to_frame(t(10, kSecond), Rounding::Nearest) to equal 300 + ✓ *fr::k25.time_to_frame(t(10, kSecond), Rounding::Floor) to equal 250 + rejects non-positive rates + ✓ FrameRate::make(Rational::literal(0, 1)).has_value() to be falsy + +● SampleRate + addresses audio in samples + ✓ *sr->time_to_sample(t(1, kSecond), Rounding::Floor) to equal 48000 + ✓ sr->sample_to_time(24000) == t(1, Rational::literal(1, 2)) to be truthy + converts 44.1 kHz positions to 96 kHz + ✓ *sr96->time_to_sample(pos, Rounding::Floor) to equal 96000 + rejects non-positive rates + ✓ SampleRate::make(0).has_value() to be falsy + ✓ SampleRate::make(-48000).has_value() to be falsy + +● Error and Result + carries code, category, message and context + ✓ static_cast(e.code()) to equal static_cast(ErrorCode::InvalidData) + ✓ static_cast(e.category()) to equal static_cast(Category::Importer) + ✓ e.message() to equal "truncated header" + ✓ e.context() to equal "clip.prproj" + describes itself for logs and UI warnings + ✓ e.summary() to equal "[timeline] overflow: trim too long (clip 4)" + ✓ bare.summary() to equal "[base] cancelled: stopped" + propagates through Result + ✓ *parse_positive(3) to equal 3 + ✓ r.has_value() to be falsy + ✓ r.error().context() to equal "field 'duration'" + +● Logging + formats messages and records category and call site + ✓ record_count() to equal 1 + ✓ c.message to equal "opened clip.mp4 (2 streams)" + ✓ static_cast(c.category) to equal static_cast(Category::Decode) + ✓ static_cast(c.level) to equal static_cast(LogLevel::Info) + ✓ c.line to be greater than 0 + drops records below the category level + ✓ record_count() to equal 0 + ✓ record_count() to equal 1 + reports enabled levels without formatting + ✓ oma::log_enabled(Category::Cache, LogLevel::Info) to be falsy + ✓ oma::log_enabled(Category::Cache, LogLevel::Error) to be truthy + ✓ oma::log_enabled(Category::Cache, LogLevel::Off) to be falsy + +● JobPool + runs a job and reports success with full progress + ✓ h.wait().has_value() to be truthy + ✓ value.load() to equal 42 + ✓ state_of(h) to equal st(JobState::Succeeded) + ✓ h.progress() to be close to 1 (precision 0.0001) + keeps the error of a failed job + ✓ wait_code(h) to equal static_cast(ErrorCode::InvalidData) + ✓ state_of(h) to equal st(JobState::Failed) + never starts a pending job that was cancelled + ✓ first.wait().has_value() to be truthy + ✓ wait_code(second) to equal static_cast(ErrorCode::Cancelled) + ✓ state_of(second) to equal st(JobState::Cancelled) + ✓ second_ran.load() to be falsy + cancels a running job cooperatively + ✓ wait_code(h) to equal static_cast(ErrorCode::Cancelled) + ✓ state_of(h) to equal st(JobState::Cancelled) + shuts down with running and pending jobs + ✓ state_of(running) to equal st(JobState::Cancelled) + ✓ state_of(pending) to equal st(JobState::Cancelled) + ✓ pending_ran.load() to be falsy + refuses work after shutdown + ✓ state_of(h) to equal st(JobState::Cancelled) + turns an escaping exception into an internal error + ✓ wait_code(h) to equal static_cast(ErrorCode::Internal) + ✓ state_of(h) to equal st(JobState::Failed) + runs many jobs across workers + ✓ counter.load() to equal 200 + +Test Suites Summary: + All 109 tests passed! + + +== gpu_tests (debug) + +● gpu::Device +15:19:52.251 INFO gpu device: Intel(R) Iris(R) Xe Graphics (TGL GT2) (Intel open-source Mesa driver, Mesa 26.2.2-arch1.1), Vulkan 1.4, 8 extensions, internally synchronized queues: yes (device.cpp:280) + reports the selected device + ✓ d->info().name.empty() to be falsy + ✓ d->info().api_version >= VK_API_VERSION_1_3 to be truthy + device: Intel(R) Iris(R) Xe Graphics (TGL GT2) (Mesa 26.2.2-arch1.1) + exposes valid raw handles for interop + ✓ d->instance() != VK_NULL_HANDLE to be truthy + ✓ d->physical_device() != VK_NULL_HANDLE to be truthy + ✓ d->device() != VK_NULL_HANDLE to be truthy + ✓ d->instance_proc_addr() != nullptr to be truthy + has a graphics and compute queue family + ✓ family_has(*d, g, VK_QUEUE_GRAPHICS_BIT) to be truthy + ✓ family_has(*d, g, VK_QUEUE_COMPUTE_BIT) to be truthy + ✓ d->queue(g, 0) != VK_NULL_HANDLE to be truthy + enables timeline semaphores and synchronization2 + ✓ timeline to be truthy + ✓ sync2 to be truthy + only reports extensions it enabled + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension("VK_NOT_A_REAL_extension") to be falsy + matches the queue creation flags to internal synchronization + ✓ flagged == d->internally_synchronized_queues() to be truthy + locks and unlocks every queue it created + ✓ true to be truthy + +● gpu::enumerate_devices + lists the device that was created + ✓ all.has_value() to be truthy + ✓ found to be truthy + rejects a device name that does not exist + ✓ r.has_value() to be falsy + ✓ static_cast(r.error().code()) to equal static_cast(ErrorCode::Unsupported) + +● gpu::Buffer and gpu::CommandRunner + round-trips bytes through device-local memory + ✓ upload && local && readback && runner to be truthy + ✓ upload->mapped() != nullptr to be truthy + ✓ local->mapped() == nullptr to be truthy + ✓ ran.has_value() to be truthy + ✓ std::memcmp(readback->mapped(), pattern.data(), pattern.size()) == 0 to be truthy + creates images with views and moves them + ✓ img.has_value() to be truthy + ✓ img->handle() != VK_NULL_HANDLE to be truthy + ✓ img->view() != VK_NULL_HANDLE to be truthy + ✓ img->desc().width to equal 64 + ✓ moved.handle() != VK_NULL_HANDLE to be truthy + ✓ img->handle() == VK_NULL_HANDLE to be truthy + +Test Suites Summary: + All 37 tests passed! + + +== media_tests (debug) + +● media::probe + describes an H.264 + AAC file + ✓ info.has_value() to be truthy + ✓ info->container to contain "mp4" + ✓ info->streams.size() to equal 2 + ✓ info->duration.has_value() to be truthy + ✓ info->duration->seconds_approx() to be close to 1 (precision 0.1) + ✓ v != nullptr to be truthy + ✓ v->kind == StreamKind::Video to be truthy + ✓ v->codec to equal "h264" + ✓ v->video->width to equal 320 + ✓ v->video->height to equal 180 + ✓ v->video->pixel_format to equal "yuv420p" + ✓ v->video->bit_depth to equal 8 + ✓ v->video->rotation to equal 0 + ✓ v->video->frame_rate.has_value() to be truthy + ✓ v->video->frame_rate->fps() == Rational::literal(30, 1) to be truthy + ✓ v->video->variable_frame_rate to be falsy + ✓ v->video->still_image to be falsy + ✓ v->frame_count.value_or(0) to equal 30 + ✓ a != nullptr to be truthy + ✓ a->codec to equal "aac" + ✓ a->audio->sample_rate.has_value() to be truthy + ✓ a->audio->sample_rate->hz() to equal 48000 + ✓ a->audio->channels to equal 1 + ✓ a->audio->channel_layout to equal "mono" + keeps NTSC frame rates exact + ✓ info.has_value() to be truthy + ✓ rate.has_value() to be truthy + ✓ rate && rate->fps() == Rational::literal(30000, 1001) to be truthy + detects variable frame rate from timestamps + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->variable_frame_rate to be truthy + reads the display rotation + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->rotation to equal 90 + reports 10-bit HEVC + ✓ info.has_value() to be truthy + ✓ v.codec to equal "hevc" + ✓ v.profile to equal "Main 10" + ✓ v.video->bit_depth to equal 10 + ✓ v.video->color.range == ColorRange::Full to be falsy + describes audio-only files + ✓ info.has_value() to be truthy + ✓ info->best_video.has_value() to be falsy + ✓ a != nullptr to be truthy + ✓ a->audio->sample_rate->hz() to equal 44100 + ✓ a->duration.has_value() to be truthy + ✓ a->duration->seconds_approx() to be close to 2 (precision 0.05) + marks still images + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->still_image to be truthy + ✓ best_video(*info)->video->width to equal 640 + rejects a truncated file as invalid data + ✓ info.has_value() to be falsy + ✓ code_of(info.error()) to equal static_cast(ErrorCode::InvalidData) + reports a missing file as an I/O error + ✓ info.has_value() to be falsy + ✓ code_of(info.error()) to equal static_cast(ErrorCode::IoError) + ✓ info.error().context() to contain "does-not-exist.mp4" + +● media::VideoDecoder (software) + decodes every frame in presentation order + ✓ d.has_value() to be truthy + ✓ d->path() == DecodePath::Software to be truthy + ✓ d->stream().codec to equal "h264" + ✓ f.has_value() to be truthy + ✓ frame.on_gpu() to be falsy + ✓ frame.width() to equal 320 + ✓ frame.height() to equal 180 + ✓ std::string(frame.pixel_format()) to equal "yuv420p" + ✓ frame.plane_count() to equal 3 + ✓ frame.layout().chroma_shift_x to equal 1 + ✓ frame.layout().chroma_shift_y to equal 1 + ✓ frame.layout().interleaved_chroma to be falsy + ✓ frame.layout().container_bits to equal 8 + ✓ frame.stride(0) >= 320 to be truthy + ✓ frame.plane(0).size() >= static_cast(frame.stride(0)) * 180 to be truthy + ✓ frame.pts().has_value() to be truthy + ✓ frame.pts()->value() to equal 0 + ✓ frame.acquire_gpu().has_value() to be falsy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ count to equal 30 + ✓ increasing to be truthy + ✓ after_end.has_value() && !after_end->has_value() to be truthy + keeps 10-bit samples + ✓ d.has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ std::string((*f)->pixel_format()) to equal "yuv420p10le" + ✓ (*f)->bit_depth() to equal 10 + ✓ (*f)->layout().container_bits to equal 16 + ✓ (*f)->layout().lsb_shift to equal 0 + seeks to the frame on screen on VFR media + ✓ d.has_value() to be truthy + ✓ pts.size() > 10 to be truthy + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + seeks to exact frames, before the start and past the end + ✓ d.has_value() to be truthy + ✓ d->seek(ticks(*d, pts[5])).has_value() to be truthy + ✓ on && *on && (*on)->pts()->value() == pts[5] to be truthy + ✓ d->seek(ticks(*d, -1000)).has_value() to be truthy + ✓ first && *first && (*first)->pts()->value() == pts.front() to be truthy + ✓ d->seek(ticks(*d, pts.back() + 10000)).has_value() to be truthy + ✓ last && *last && (*last)->pts()->value() == pts.back() to be truthy + ✓ end.has_value() && !end->has_value() to be truthy + seeks with a time in another timebase + ✓ d.has_value() to be truthy + ✓ d->seek(t).has_value() to be truthy + ✓ f && *f && (*f)->pts().has_value() to be truthy + ✓ *(*f)->pts() == t to be truthy + fails without a usable path + ✓ d.has_value() to be falsy + ✓ code_of(d.error()) to equal static_cast(ErrorCode::Unsupported) + rejects damaged files and non-video streams + ✓ truncated.has_value() to be falsy + ✓ wrong.has_value() to be falsy + ✓ code_of(wrong.error()) to equal static_cast(ErrorCode::InvalidArgument) + +● media::VideoDecoder (GPU paths) + decodes H.264 onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ frame.layout().interleaved_chroma to be truthy + ✓ frame.layout().lsb_shift to equal bit_depth > 8 ? 16 - bit_depth : 0 + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + h264_30fps_aac.mp4: VA-API to Vulkan, 30 frames, 30 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal frames + ✓ consumer.consumed() to equal frames + ✓ same_luma(gpu_luma, software_luma(name), bit_depth) to be truthy + decodes 10-bit HEVC onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ frame.layout().interleaved_chroma to be truthy + ✓ frame.layout().lsb_shift to equal bit_depth > 8 ? 16 - bit_depth : 0 + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + hevc_10bit.mp4: VA-API to Vulkan, 30 frames, 30 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal frames + ✓ consumer.consumed() to equal frames + ✓ same_luma(gpu_luma, software_luma(name), bit_depth) to be truthy + decodes AV1 onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ frame.layout().interleaved_chroma to be truthy + ✓ frame.layout().lsb_shift to equal bit_depth > 8 ? 16 - bit_depth : 0 + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + av1_opus.mkv: VA-API to Vulkan, 30 frames, 30 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal frames + ✓ consumer.consumed() to equal frames + ✓ same_luma(gpu_luma, software_luma(name), bit_depth) to be truthy + falls back to software when the driver refuses a stream + ✓ d.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + h264_444.mp4: software + ✓ frames to equal 30 + ✓ first_pts to equal 0 + reports a refusal when software is not allowed + ✓ (f && *f && (*f)->on_gpu()) || (!f && f.error().code() == oma::ErrorCode::Unsupported) to be truthy + +● media::AudioDecoder + decodes PCM to planar float with contiguous timestamps + ✓ d.has_value() to be truthy + ✓ (*d)->sample_rate().hz() to equal 44100 + ✓ (*d)->channels() to equal 1 + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ t.frames to equal 88200 + ✓ t.first_pts to equal 0 + ✓ t.contiguous to be truthy + ✓ static_cast(t.peak) to be close to 0.125 (precision 0.01) + resamples and changes the channel count + ✓ d.has_value() to be truthy + ✓ (*d)->sample_rate().hz() to equal 48000 + ✓ (*d)->channels() to equal 2 + ✓ first && *first && (*first)->channel(1).size() == (*first)->channel(0).size() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ total to equal 96000 + decodes AAC and Opus + ✓ aac.has_value() to be truthy + ✓ (*aac)->stream().codec to equal "aac" + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ std::llabs(t.frames - 48000) <= 2048 to be truthy + ✓ t.contiguous to be truthy + ✓ opus.has_value() to be truthy + ✓ (*opus)->stream().codec to equal "opus" + ✓ (*opus)->sample_rate().hz() to equal 48000 + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ std::llabs(t.frames - 48000) <= 2048 to be truthy + seeks to an exact sample + ✓ (*d)->seek(t).has_value() to be truthy + ✓ b && *b to be truthy + ✓ (*b)->pts.value() to equal 30000 + ✓ static_cast((*b)->channel(0)[0]) to be close to 0.113194 (precision 0.001) + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ first_frames + rest.frames to equal 88200 - 30000 + fails on files without audio + ✓ d.has_value() to be falsy + ✓ code_of(d.error()) to equal static_cast(ErrorCode::InvalidArgument) + +Test Suites Summary: + All 571 tests passed! + + +== compositor_tests (debug) + +● compositor geometry + composes and inverts affine transforms + ✓ maps(m, 1, 0, 10, 22) to be truthy + ✓ inv.has_value() to be truthy + ✓ maps(*inv, 10, 22, 1, 0) to be truthy + ✓ maps(m.then(*inv), 5, -7, 5, -7, 1e-12) to be truthy + ✓ Affine::scale(0, 1).inverse().has_value() to be falsy + fits, fills and places sources natively + ✓ maps(m, 0, 0, 0, 0) && maps(m, 320, 180, 1920, 1080) to be truthy + ✓ maps(m, 0, 0, 240, 0) && maps(m, 640, 480, 1680, 1080) to be truthy + ✓ maps(m, 0, 0, 0, -180) && maps(m, 640, 480, 1920, 1260) to be truthy + ✓ maps(m, 0, 0, 800, 450) to be truthy + applies display rotation and pixel aspect + ✓ box.has_value() to be truthy + ✓ (*box)[0] to equal 656 + ✓ (*box)[2] to equal 1264 + ✓ (*box)[1] to equal 0 + ✓ (*box)[3] to equal 1080 + ✓ maps(m, 0, 0, 656.25, 1080) to be truthy + ✓ maps(w, 160, 180, 1920, 1080) to be truthy + crops, scales and offsets layers + ✓ maps(m, 200, 100, 600, 450) to be truthy + ✓ maps(m, 100, 100, 400, 450) to be truthy + ✓ box && (*box)[0] == 400 && (*box)[2] == 800 && (*box)[1] == 250 && (*box)[3] == 650 to be truthy + ✓ oma::compositor::covered_pixels(layer, src, 1000, 1000).has_value() to be falsy + validates render graphs + ✓ oma::compositor::validate(g, 1).has_value() to be truthy + ✓ oma::compositor::validate(g, 0).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ !r && r.error().code() == ErrorCode::InvalidArgument to be truthy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + +● compositor color + converts limited, full and 10-bit YUV + ✓ rgb_near(rgb(m8, 16.0 / 255, 128.0 / 255, 128.0 / 255), 0, 0, 0) to be truthy + ✓ rgb_near(rgb(m8, 235.0 / 255, 128.0 / 255, 128.0 / 255), 1, 1, 1) to be truthy + ✓ rgb_near(rgb(m8, 63.0 / 255, 102.0 / 255, 240.0 / 255), 1, 0, 0, 0.01) to be truthy + ✓ rgb_near(rgb(m10, 64.0 / 1023, 512.0 / 1023, 512.0 / 1023), 0, 0, 0) to be truthy + ✓ rgb_near(rgb(m10, 940.0 / 1023, 512.0 / 1023, 512.0 / 1023), 1, 1, 1) to be truthy + ✓ rgb_near(rgb(full, 1.0, 128.0 / 255, 128.0 / 255), 1, 1, 1) to be truthy + ✓ near(sd.matrix.at(0, 2), hd.matrix.at(0, 2), 1e-3) to be falsy + converts primaries and decodes transfers + ✓ near(same.at(0, 0), 1, 1e-9) && near(same.at(0, 1), 0, 1e-9) && near(same.at(2, 2), 1, 1e-9) to be truthy + ✓ near(m.at(0, 0), 1.6605, 1e-3) && near(m.at(0, 1), -0.5876, 1e-3) && near(m.at(0, 2), -0.0728, 1e-3) to be truthy + ✓ near(m.at(1, 0), -0.1246, 1e-3) && near(m.at(1, 1), 1.1329, 1e-3) to be truthy + ✓ near(m.at(2, 1), -0.1006, 1e-3) && near(m.at(2, 2), 1.1187, 1e-3) to be truthy + ✓ near(oma::compositor::to_linear(0.5, Transfer::Srgb), 0.214041, 1e-6) to be truthy + ✓ near(oma::compositor::to_linear(0.5, Transfer::Bt1886), std::pow(0.5, 2.4)) to be truthy + ✓ near(oma::compositor::to_linear(1.7, Transfer::Linear), 1.0) to be truthy + ✓ oma::compositor::resolve_transfer(16, &hdr) == Transfer::Bt1886 && hdr to be truthy + ✓ oma::compositor::resolve_transfer(13, &hdr) == Transfer::Srgb && !hdr to be truthy + +● compositor::CpuCompositor + fills the background premultiplied + ✓ out.has_value() to be truthy + ✓ static_cast(px[0]) to be close to 0.5 (precision 1e-06) + ✓ static_cast(px[1]) to be close to 0.25 (precision 1e-06) + ✓ static_cast(px[3]) to be close to 0.5 (precision 1e-06) + draws opaque layers and moves them by exact pixels + ✓ src.frame.has_value() to be truthy + ✓ a && b to be truthy + ✓ static_cast(a->at(0, 0)[3]) to be close to 1 (precision 1e-06) + ✓ shifted to be truthy + ✓ static_cast(b->at(5, 100)[1]) to be close to 0 (precision 1e-06) + ✓ static_cast(b->at(5, 100)[2]) to be close to 1 (precision 1e-06) + applies opacity and blend modes + ✓ full && half && doubled to be truthy + ✓ static_cast(h[0]) to be close to 0.0250907 (precision 1e-06) + ✓ static_cast(h[3]) to be close to 0.5 (precision 1e-06) + ✓ static_cast(d[1]) to be close to 1.93159 (precision 1e-06) + ✓ static_cast(d[3]) to be close to 1 (precision 1e-06) + rejects missing inputs + ✓ CpuCompositor{}.render(g, empty).has_value() to be falsy + ✓ CpuCompositor{}.render(g, {}).has_value() to be falsy + +● compositor::VulkanCompositor + matches the CPU reference on uploaded frames + ✓ vk.has_value() to be truthy + ✓ rendered.has_value() to be truthy + ✓ cpu && gpu to be truthy + max difference 0.00178, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + matches the CPU reference on zero-copy GPU frames + ✓ (*vk)->render(g, gpu_inputs).has_value() to be truthy + ✓ (*vk)->render(g, gpu_inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + VA-API to Vulkan frames: max difference 0.00121, 0 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + measures three 1080p layers + ✓ (*vk)->render(g, inputs).has_value() to be truthy + 1080p, 3 layers (GPU inputs): 3.93 ms per frame, submit to completion + +Test Suites Summary: + All 68 tests passed! + diff --git a/Docs/Research/evidence/2026-10-04-compositor-bench.cpp b/Docs/Research/evidence/2026-10-04-compositor-bench.cpp new file mode 100644 index 0000000..5360158 --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-compositor-bench.cpp @@ -0,0 +1,54 @@ +// Scratch benchmark (not part of the repo): wall time of VulkanCompositor::render per feature. +#include "oma/compositor/compositor.hpp" +#include "oma/gpu/device.hpp" +#include "oma/media/video_decoder.hpp" +#include +#include +#include +#include +using namespace oma; +int main(int argc, char** argv) { + auto dev = gpu::Device::create(); + if (!dev) { std::puts("no device"); return 1; } + for (int f = 1; f < argc; ++f) { + media::VideoDecoderOptions o; o.paths = {media::DecodePath::Software}; + auto d = media::VideoDecoder::open(argv[f], o); + auto fr = (*d)->next(); + media::VideoFrame frame = std::move(**fr); + compositor::LayerInput in; in.frame = &frame; in.color = (*d)->stream().video->color; + auto comp = compositor::VulkanCompositor::create(**dev); + struct Case { const char* name; compositor::Layer layer; }; + std::vector cases; + compositor::Layer base; base.input = 0; + compositor::Layer tiny = base; tiny.transform.offset_x = 100000; // off screen: upload+clear+submit only + compositor::Layer look = base; look.color.exposure = 0.5; look.color.contrast = 0.3; look.filter.kind = compositor::FilterKind::Vignette; + compositor::Layer blur = base; blur.sharpness = -1.0; + compositor::Layer blur_small = base; blur_small.sharpness = -0.1; + compositor::Layer sharpen = base; sharpen.sharpness = 1.0; + auto lut = std::make_shared(); lut->size = 33; + for (int b = 0; b < 33; ++b) for (int g2 = 0; g2 < 33; ++g2) for (int r = 0; r < 33; ++r) { + lut->rgb.push_back(g2 / 32.0F); lut->rgb.push_back(b / 32.0F); lut->rgb.push_back(r / 32.0F); } + compositor::Layer cdl = base; cdl.grade.cdl.slope = {1.1, 0.9, 1.0}; cdl.grade.cdl.power = {0.9, 1.0, 1.1}; cdl.grade.cdl.saturation = 1.2; + compositor::Layer curves = base; curves.grade.curves.master = {{0, 0}, {0.25, 0.2}, {0.5, 0.5}, {0.75, 0.8}, {1, 1}}; + curves.grade.curves.red = {{0, 0}, {0.5, 0.55}, {1, 1}}; curves.grade.curves.green = curves.grade.curves.red; curves.grade.curves.blue = curves.grade.curves.red; + compositor::Layer lutl = base; lutl.grade.lut = lut; + compositor::Layer all = curves; all.grade.cdl = cdl.grade.cdl; all.grade.lut = lut; + cases = {{"off-screen (upload)", tiny}, {"plain", base}, {"look+vignette", look}, + {"blur 10%", blur_small}, {"blur max", blur}, {"sharpen max", sharpen}, + {"grade: CDL", cdl}, {"grade: curves (5+3x3 pts)", curves}, {"grade: LUT 33", lutl}, {"grade: all three", all}}; + std::printf("%s (%dx%d) -> 1920x1080\n", argv[f], frame.width(), frame.height()); + for (auto& c : cases) { + compositor::RenderGraph g; g.layers.push_back(c.layer); + std::vector ms; + for (int i = 0; i < 25; ++i) { + auto t0 = std::chrono::steady_clock::now(); + auto r = (*comp)->render(g, std::span(&in, 1)); + auto t1 = std::chrono::steady_clock::now(); + if (!r) { std::printf("fail %s\n", r.error().summary().c_str()); return 1; } + if (i >= 5) ms.push_back(std::chrono::duration(t1 - t0).count()); + } + std::ranges::sort(ms); + std::printf(" %-22s median %7.2f ms p90 %7.2f ms\n", c.name, ms[ms.size()/2], ms[ms.size()*9/10]); + } + } +} diff --git a/Docs/Research/evidence/2026-10-04-decode-allocations.txt b/Docs/Research/evidence/2026-10-04-decode-allocations.txt new file mode 100644 index 0000000..509f803 --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-decode-allocations.txt @@ -0,0 +1,118 @@ +Per-frame heap allocations while decoding (2026-10-04, release libs, Iris Xe, FFmpeg n9.0.1, iHD 26.2.4). +Method: LD_PRELOAD shim counting malloc + posix_memalign (source below) around VideoDecoder::next(), frames 100-500 of h264.mp4 (1080p60 testsrc2, tools/spikes/s3-decode-paths.sh); callers from backtrace()+dladdr, top 4 frames. + +software: 36.4 allocations per frame (frames 100-500) +VA-API: 103.2 allocations per frame (frames 100-500) + +-- callers, sw (400 frames) + 6114 ALLOC av_malloc +#include +#include +#include +#include +#include +atomic_long oma_alloc_count; +int oma_alloc_trace; +static __thread int busy; +static void* (*real_malloc)(size_t); +static int (*real_memalign)(void**, size_t, size_t); +static void note(void) { + if (!oma_alloc_trace || busy) return; + busy = 1; + void* bt[8]; int n = backtrace(bt, 8); + char line[512] = ""; + for (int i = 2; i < n && i < 6; ++i) { Dl_info inf; if (dladdr(bt[i], &inf) && inf.dli_sname) { strncat(line, inf.dli_sname, 60); strcat(line, "<"); } else strcat(line, "?<"); } + fprintf(stderr, "ALLOC %s\n", line); + busy = 0; +} +void* malloc(size_t n) { if (!real_malloc) real_malloc = dlsym(RTLD_NEXT, "malloc"); oma_alloc_count++; note(); return real_malloc(n); } +int posix_memalign(void** p, size_t a, size_t n) { if (!real_memalign) real_memalign = dlsym(RTLD_NEXT, "posix_memalign"); oma_alloc_count++; note(); return real_memalign(p, a, n); } + +-- probe (probe.cpp) +#include "oma/gpu/device.hpp" +#include "oma/media/video_decoder.hpp" +#include +#include +#include +#include +using namespace oma; +int main(int argc, char** argv) { + auto* counter = static_cast*>(dlsym(RTLD_DEFAULT, "oma_alloc_count")); + const bool hw = argc > 2 && std::string_view(argv[2]) == "hw"; + auto dev = gpu::Device::create(); + media::VideoDecoderOptions o; + o.device = dev->get(); + if (!hw) o.paths = {media::DecodePath::Software}; + auto d = media::VideoDecoder::open(argv[1], o); + long before = 0; + int n = 0; + for (;; ++n) { + if (n == 100) { before = counter->load(); *static_cast(dlsym(RTLD_DEFAULT, "oma_alloc_trace")) = 1; } + auto f = (*d)->next(); + if (!f || !*f) break; + if (n == 500) { std::printf("%s: %.1f allocations per frame (frames 100-500)\n", hw ? "VA-API" : "software", (counter->load() - before) / 400.0); break; } + } +} + +== Vulkan device memory (vkAllocateMemory/vkFreeMemory called by OmaMovie code; FFmpeg allocates through its own dispatch table and is not counted) +S5 scene, 600 frames, release; maxMemoryAllocationCount = 4294967295 (ANV). +-- software +vkAllocateMemory from OmaMovie code: 16 calls, 16 freed, peak 16 live, peak 46.9 MB +-- hardware +vkAllocateMemory from OmaMovie code: 8 calls, 8 freed, peak 8 live, peak 28.4 MB +-- shim (vkcount.c) +#define _GNU_SOURCE +#include +#include +#include +#include +#include +static atomic_long allocs, frees, live, peak; +static atomic_ullong bytes, peak_bytes; +VKAPI_ATTR VkResult VKAPI_CALL vkAllocateMemory(VkDevice d, const VkMemoryAllocateInfo* i, const VkAllocationCallbacks* a, VkDeviceMemory* m) { + static PFN_vkAllocateMemory real; if (!real) real = (PFN_vkAllocateMemory)dlsym(RTLD_NEXT, "vkAllocateMemory"); + allocs++; long l = ++live; if (l > peak) peak = l; + unsigned long long b = (bytes += i->allocationSize); if (b > peak_bytes) peak_bytes = b; + return real(d, i, a, m); +} +VKAPI_ATTR void VKAPI_CALL vkFreeMemory(VkDevice d, VkDeviceMemory m, const VkAllocationCallbacks* a) { + static PFN_vkFreeMemory real; if (!real) real = (PFN_vkFreeMemory)dlsym(RTLD_NEXT, "vkFreeMemory"); + if (m) { frees++; live--; } + real(d, m, a); +} +__attribute__((destructor)) static void report(void) { + fprintf(stderr, "vkAllocateMemory from OmaMovie code: %ld calls, %ld freed, peak %ld live, peak %.1f MB\n", (long)allocs, (long)frees, (long)peak, peak_bytes / 1048576.0); +} diff --git a/Docs/Research/evidence/2026-10-04-gpu-effects.txt b/Docs/Research/evidence/2026-10-04-gpu-effects.txt new file mode 100644 index 0000000..0a8ce6c --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-gpu-effects.txt @@ -0,0 +1,83 @@ +GPU effects research, local evidence (2026-10-04) +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2-arch1.1, Vulkan 1.4. +vulkaninfo: subTexelPrecisionBits = 8, maxImageDimension3D = 2048, maxUniformBufferRange = 1073741824. + +Numerics recheck (2026-10-04): ran + python3 Docs/Research/evidence/2026-10-04-grading-numerics.py +with NumPy 2.5.3. It exited 0 and reproduced every printed figure in section 2 below +to the shown precision, including the no-overshoot and neutral-grey checks. This +rechecks the synthetic numerical model, not grading against an independent color oracle. +The broader recheck and current `make test` log are recorded in +2026-10-04-verification.md and 2026-10-04-make-test.txt. + +1. Compositor render time (2026-10-04-compositor-bench.cpp, release libs, 25 renders, first 5 + dropped, median/p90). One layer, output 1920x1080, software-decoded yuv420p testsrc2 frame, + so every render includes the upload. Two runs; ranges cover both. + + case 1080p source 2160p source + off-screen (upload only) 0.81-2.41 ms 3.42-5.80 ms + plain 2.62-3.47 ms 4.92-5.62 ms + look + vignette 2.96-3.10 ms 5.24-5.29 ms + blur 10% (sharpness -0.1) 10.12-10.48 ms 57.09-58.09 ms + blur max (sharpness -1) 52.63-52.65 ms 208.96-214.07 ms + sharpen max 8.77-8.94 ms 42.44-45.13 ms + +2. Grading numerics (2026-10-04-grading-numerics.py, numpy, synthetic data) + (a) lift/gamma/gain vs ASC CDL (slope = gain*(1-lift), offset = gain*lift, power = gamma), + 1000 random grades x 100000 inputs: max abs diff 6.43e-15. + (b) monotone cubic curve sampled into a table, read with linear interpolation: + S-curve 256 entries 1.59e-05, 1024 entries 9.92e-07 + steep 256 entries 2.25e-03, 1024 entries 1.58e-04 (10-bit step 9.78e-04) + no overshoot outside [0, 1] for either curve. + (c) synthetic nonlinear 3D transform (saturation 1.6, gamma 0.8, hue twist), max abs error: + 17^3 trilinear 3.99e-02 tetrahedral 3.54e-02 + 33^3 trilinear 2.44e-02 tetrahedral 2.12e-02 + 65^3 trilinear 1.30e-02 tetrahedral 1.19e-02 + 33^3 on greys, max channel spread: trilinear 2.91e-03, tetrahedral 0 (exact 0). + +3. Grading after implementation (same benchmark, grading cases added; two runs, medians). + CDL: slope/power per channel + saturation 1.2. Curves: master 5 points, red/green/blue 3. + LUT: 33^3 channel rotation. + + case 1080p source 2160p source + plain 2.79-3.02 ms 4.33-5.38 ms + grade: CDL 2.99-3.03 ms 4.75-5.03 ms + grade: curves 3.88-3.98 ms 5.59-5.61 ms + grade: LUT 33 3.27-4.26 ms 4.85-4.86 ms + grade: all three 3.85-4.03 ms 5.50-5.73 ms + + Target "under +1 ms at 1080p": +0.83 ms in run 1, +1.24 ms in run 2 (noise of about 0.5 ms + from the synchronous upload). Borderline; curves are the costliest stage (a loop over the + points per channel, master then channel). + +4. Tests (make test, debug): GPU vs CPU with CDL + curves + LUT on two layers: max difference + 6.8e-4, 0 of 230400 pixels over the 4e-3 tolerance. Mutation check: swapping two tetrahedral + weights in the shader only made the same test fail (24538 and 170661 pixels over tolerance). + +5. Blur after the rework (same benchmark, release libs, two runs, medians). The source is + linearized and box-reduced by a factor f = max(sigma / 3, source px per output px), the + gaussian runs on the reduced image (radius <= 18), the composite reads it back bilinearly; + intermediates RGBA16F (were RGBA32F at the full source size). + + case 1080p source 2160p source (shown at 1080p) + plain 2.69-2.71 ms 4.75-4.84 ms + blur 10% (sharpness -0.1) 7.87-8.28 ms 10.96-11.59 ms (was 10.1-10.5 / 57-58) + blur max (sharpness -1) 3.51-3.59 ms 14.38-14.72 ms (was 52.6 / 209-214) + sharpen max 8.53-8.58 ms 11.61-11.72 ms (was 8.8-8.9 / 42-45) + + Intermediate steps, 2160p source: the reduction alone (RGBA32F) gave blur max 13.2-14.1 ms + but left blur 10% at 45-52 ms and sharpen at 46 ms (factor 1, full-size float images); + RGBA16F brought those to 36-38 and 29-30 ms; the display factor to the numbers above. + Blur max at 2160p (f = 14) costs more than blur 10% (f = 2): each reduce thread averages + 196 decoded texels serially. Done afterwards: a separable reduce (across into a + width-reduced image, then down), two runs, 2160p source: blur max 5.65-5.83 ms (plain + 4.73-5.65), blur 10% 12.0-12.5 ms, sharpen 12.0-12.3 ms; 1080p: blur max 2.80-3.13 ms. + GPU vs CPU on the factor-2 test: max difference 2.5e-3 (the across image is half float). + Left as is: with factor 1 the reduce-down pass is a plain copy (one full-size read and write); + blur 10% at 1080p costs 8.5-10.2 ms against 2.7 ms plain. + Strength: sigma = 2% of the source height per unit at any resolution (it was clamped to + 21.3 px, half the relative blur for a 2160p source). + + Tests: GPU vs CPU with a factor-2 blur and a crop on a 640x360 still: max difference 9.7e-4. + With RGBA16F intermediates the looks test (blur + sharpen layers) rose from 2.3e-3 to + 4.5e-3 maximum, 0 of 230400 pixels over the 4e-3 tolerance. diff --git a/Docs/Research/evidence/2026-10-04-grading-numerics.py b/Docs/Research/evidence/2026-10-04-grading-numerics.py new file mode 100644 index 0000000..48a7fcd --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-grading-numerics.py @@ -0,0 +1,89 @@ +import numpy as np +rng = np.random.default_rng(1) + +# (a) Lift/gamma/gain -> ASC CDL (slope, offset, power) is exact: +# gain*(x + lift*(1-x)) == x*slope + offset with slope = gain*(1-lift), offset = gain*lift +x = rng.random(100000) +worst = 0 +for _ in range(1000): + lift, gain, gamma = rng.uniform(-0.25, 0.25), rng.uniform(0.5, 2), rng.uniform(0.5, 2) + lgg = np.clip(gain * (x + lift * (1 - x)), 0, 1) ** gamma + slope, offset = gain * (1 - lift), gain * lift + cdl = np.clip(x * slope + offset, 0, 1) ** gamma + worst = max(worst, np.abs(lgg - cdl).max()) +print(f"(a) LGG vs CDL max abs diff over 1000 random grades: {worst:.2e}") + +# (b) monotone cubic (Fritsch-Carlson) curve sampled into an N-entry table, read with linear interpolation +def pchip(xs, ys, q): + xs, ys = np.asarray(xs, float), np.asarray(ys, float) + h = np.diff(xs); d = np.diff(ys) / h + m = np.zeros_like(xs) + m[1:-1] = np.where(d[:-1] * d[1:] > 0, (d[:-1] + d[1:]) / 2, 0) + m[0], m[-1] = d[0], d[-1] + for k in range(len(d)): # Fritsch-Carlson limiter + if d[k] == 0: m[k] = m[k+1] = 0; continue + a, b = m[k] / d[k], m[k+1] / d[k] + s = a*a + b*b + if s > 9: t = 3 / np.sqrt(s); m[k] = t*a*d[k]; m[k+1] = t*b*d[k] + i = np.clip(np.searchsorted(xs, q) - 1, 0, len(h) - 1) + t = (q - xs[i]) / h[i] + h00, h10, h01, h11 = 2*t**3-3*t**2+1, t**3-2*t**2+t, -2*t**3+3*t**2, t**3-t**2 + return h00*ys[i] + h10*h[i]*m[i] + h01*ys[i+1] + h11*h[i]*m[i+1] +q = np.linspace(0, 1, 200001) +for name, xs, ys in [("S-curve", [0, .25, .5, .75, 1], [0, .12, .5, .88, 1]), + ("steep crush", [0, .1, .15, 1], [0, 0, .6, 1])]: + exact = pchip(xs, ys, q) + for n in (256, 1024): + table = pchip(xs, ys, np.linspace(0, 1, n)) + approx = np.interp(q, np.linspace(0, 1, n), table) + print(f"(b) {name:12s} {n:5d} entries: max err {np.abs(exact-approx).max():.2e} (10-bit step {1/1023:.2e})") + print(f" overshoot outside [0,1]: {exact.min() < -1e-12 or exact.max() > 1+1e-12}") + +# (c) tetrahedral vs trilinear on a nonlinear 3D transform (saturation boost + gamma + hue twist) +def f(rgb): + luma = rgb @ np.array([0.2126, 0.7152, 0.0722]) + sat = luma[:, None] + 1.6 * (rgb - luma[:, None]) + out = np.clip(sat, 0, 1) ** 0.8 + return out[:, [1, 2, 0]] * 0.3 + out * 0.7 +def lut(n): + g = np.linspace(0, 1, n) + b, gg, r = np.meshgrid(g, g, g, indexing="ij") # red fastest + return f(np.stack([r.ravel(), gg.ravel(), b.ravel()], 1)).reshape(n, n, n, 3) # [b][g][r] +def trilinear(L, p): + n = L.shape[0]; s = p * (n - 1); i = np.minimum(np.floor(s).astype(int), n - 2); t = s - i + out = 0 + for dz in (0, 1): + for dy in (0, 1): + for dx in (0, 1): + w = (t[:,0] if dx else 1-t[:,0]) * (t[:,1] if dy else 1-t[:,1]) * (t[:,2] if dz else 1-t[:,2]) + out = out + w[:, None] * L[i[:,2]+dz, i[:,1]+dy, i[:,0]+dx] + return out +def tetra(L, p): + n = L.shape[0]; s = p * (n - 1); i = np.minimum(np.floor(s).astype(int), n - 2); f_ = s - i + def at(dx, dy, dz): return L[i[:,2]+dz, i[:,1]+dy, i[:,0]+dx] + fr, fg, fb = f_[:,0:1], f_[:,1:2], f_[:,2:3] + c000, c111 = at(0,0,0), at(1,1,1) + out = np.zeros_like(p) + cases = [ # (condition, vertex1, vertex2, weights) + ((fr>=fg)&(fg>=fb), at(1,0,0), at(1,1,0), (1-fr, fr-fg, fg-fb, fb)), + ((fr>=fb)&(fb>fg), at(1,0,0), at(1,0,1), (1-fr, fr-fb, fb-fg, fg)), + ((fb>fr)&(fr>=fg), at(0,0,1), at(1,0,1), (1-fb, fb-fr, fr-fg, fg)), + ((fg>fr)&(fr>=fb), at(0,1,0), at(1,1,0), (1-fg, fg-fr, fr-fb, fb)), + ((fg>=fb)&(fb>fr), at(0,1,0), at(0,1,1), (1-fg, fg-fb, fb-fr, fr)), + ((fb>fg)&(fg>fr), at(0,0,1), at(0,1,1), (1-fb, fb-fg, fg-fr, fr)), + ] + done = np.zeros(len(p), bool) + for cond, v1, v2, (w0, w1, w2, w3) in cases: + c = cond[:, 0] & ~done + out[c] = (w0*c000 + w1*v1 + w2*v2 + w3*c111)[c] + done |= c + return out +p = rng.random((400000, 3)); exact = f(p) +for n in (17, 33, 65): + L = lut(n) + e_tl = np.abs(trilinear(L, p) - exact).max(); e_te = np.abs(tetra(L, p) - exact).max() + print(f"(c) {n:2d}^3 LUT: trilinear max err {e_tl:.2e}, tetrahedral {e_te:.2e}") +# neutral axis: greys must stay grey +grey = np.repeat(rng.random((20000, 1)), 3, 1); L = lut(33) +for name, fn in (("trilinear", trilinear), ("tetrahedral", tetra)): + o = fn(L, grey); print(f"(c) 33^3 {name:11s} on greys: max channel spread {np.ptp(o, axis=1).max():.2e} (exact {np.ptp(f(grey), axis=1).max():.2e})") diff --git a/Docs/Research/evidence/2026-10-04-m2-m3-intel-recheck.md b/Docs/Research/evidence/2026-10-04-m2-m3-intel-recheck.md new file mode 100644 index 0000000..2b8c6bc --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-m2-m3-intel-recheck.md @@ -0,0 +1,51 @@ +# M2/M3 Intel recheck — 2026-10-04 + +The checks below ran outside the filesystem sandbox so Vulkan could see the development +machine's Intel Iris Xe (TGL GT2), Mesa 26.2.2, `/dev/dri/renderD128`. They extend the +existing S1–S6 evidence; they do not test AMD, NVIDIA or a hybrid laptop. + +## Runtime capability report + +Command: `make -j4 test FILTER=prerequisites` after adding `DeviceInfo`'s advertised +interop and video fields. Exit code 0; the filtered GPU suite reported 5 checks passed. +The selected device reported: + +| Prerequisite | Runtime report | +|---|---| +| DMA-BUF import | yes | +| DRM format modifiers | yes | +| External semaphore fd | yes | +| Vulkan Video decode queue | no | +| Advertised Vulkan Video codec operations | `0x0` | + +The render node and extension combination are consistent with S1's default-driver +observation and the current VA-API → DMA-BUF → Vulkan path. These flags are prerequisites, +not codec/profile support. S1's actual FFmpeg negotiated-format tests and S5's image/time +checks provide separate execution evidence. A hybrid machine is still needed to verify +selection, power behavior and identity when more than one physical GPU is present. + +## Independent decoded-frame color check + +Command: `make -j4 test FILTER=libswscale` on the same Intel device. Exit code 0; the +filtered compositor suite reported 5 checks passed. For four interior pixels of the +generated YUV patch frame, maximum difference between Vulkan linear output and +`libswscale`'s nonlinear RGB output after BT.1886 decoding was `0.02220` (test bound +`0.025`). `ffprobe` reports the Y4M fixture's color fields as unknown, so this checks +the untagged SD/BT.601 fallback. It does not validate tagged BT.709/2020 frames, chroma +siting, HDR tone mapping, display presentation or export. + +The previous sandbox run used llvmpipe and produced the same sampled difference. A passing +test on this Intel driver is useful for the stated scene only; it is not a general color +accuracy claim. + +## Pipeline cache on Intel + +With a temporary `XDG_CACHE_HOME`, `make -j4 test FILTER=encodes` passed on the Iris Xe +and wrote an 85,175-byte pipeline cache file. Repeating the same command with that cache +present also passed. This checks persistence and reuse without a rendering failure; no +startup-time comparison was measured. The earlier llvmpipe check covered an empty-header +cache and a corrupted-file fallback. + +## Full test suite + +`make -j4 test` passed on the same Intel device after the M2 capability-report changes. diff --git a/Docs/Research/evidence/2026-10-04-make-test.txt b/Docs/Research/evidence/2026-10-04-make-test.txt new file mode 100644 index 0000000..675f279 --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-make-test.txt @@ -0,0 +1,1858 @@ + +== base_tests (debug) + +● Rational + normalizes sign and common factors + ✓ r.has_value() to be truthy + ✓ r->num() to equal -3 + ✓ r->den() to equal 4 + rejects a zero denominator + ✓ r.has_value() to be falsy + ✓ static_cast(r.error().code()) to equal static_cast(ErrorCode::InvalidArgument) + rejects INT64_MIN because it cannot be negated + ✓ Rational::make(kMin, 1).has_value() to be falsy + ✓ Rational::make(1, kMin).has_value() to be falsy + orders fractions exactly + ✓ Rational::literal(1, 3) < Rational::literal(1, 2) to be truthy + ✓ Rational::literal(-1, 2) < Rational::literal(1, 3) to be truthy + ✓ Rational::literal(30000, 1001) > Rational::literal(29, 1) to be truthy + ✓ Rational::literal(kMax, 1) > Rational::literal(kMax - 1, 1) to be truthy + ✓ Rational::literal(kMax, kMax - 1) > Rational::literal(kMax - 1, kMax - 2) to be falsy + inverts and refuses to invert zero + ✓ Rational::literal(1001, 30000).inverse()->num() to equal 30000 + ✓ Rational::literal(0, 1).inverse().has_value() to be falsy + +● rescale + converts seconds to a 90 kHz timebase exactly + ✓ rescale_ok(1, kSecond, kTb90k, Rounding::Floor) to equal 90000 + converts one 29.97 fps frame to 90 kHz exactly (3003 ticks) + ✓ rescale_ok(1, kFrame2997, kTb90k, Rounding::Floor) to equal 3003 + rounds one 23.976 fps frame (3753.75 ticks) as requested + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Floor) to equal 3753 + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Ceil) to equal 3754 + ✓ rescale_ok(1, kFrame23976, kTb90k, Rounding::Nearest) to equal 3754 + rounds negative values toward the right direction + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Floor) to equal -3754 + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Ceil) to equal -3753 + ✓ rescale_ok(-1, kFrame23976, kTb90k, Rounding::Nearest) to equal -3754 + breaks ties away from zero with Nearest + ✓ rescale_ok(1, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal 1 + ✓ rescale_ok(-1, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal -1 + ✓ rescale_ok(3, Rational::literal(1, 2), kSecond, Rounding::Nearest) to equal 2 + maps video frames to audio samples (29.97 fps at 48 kHz = 1601.6 samples) + ✓ rescale_ok(1, kFrame2997, kTb48k, Rounding::Nearest) to equal 1602 + ✓ rescale_ok(5, kFrame2997, kTb48k, Rounding::Nearest) to equal 8008 + ✓ rescale_ok(1, kFrame2997, Rational::literal(1, 44100), Rounding::Floor) to equal 1471 + handles ten hours of media in a 90 kHz timebase + ✓ rescale_ok(ten_hours, kTb90k, kTb48k, Rounding::Floor) to equal 10LL * 3600 * 48000 + ✓ rescale_ok(ten_hours, kTb90k, kFrame2997, Rounding::Floor) to equal 1078921 + reports overflow instead of truncating + ✓ static_cast(rescale_error(kMax, kSecond, kTb90k)) to equal static_cast(ErrorCode::Overflow) + ✓ rescale_ok(kMax, kTb90k, kSecond, Rounding::Floor) to equal kMax / 90000 + rejects non-positive units + ✓ static_cast(rescale_error(1, Rational::literal(0, 1), kSecond)) to equal static_cast(ErrorCode::InvalidArgument) + ✓ static_cast(rescale_error(1, kSecond, Rational::literal(-1, 25))) to equal static_cast(ErrorCode::InvalidArgument) + +● RationalTime + compares instants exactly across timebases + ✓ t(3003, kTb90k) == t(1001, kTb30k) to be truthy + ✓ t(48000, kTb48k) == t(90000, kTb90k) to be truthy + ✓ t(1, kTb48k) < t(2, kTb90k) to be truthy + ✓ t(-1, kTb48k) < t(0, kTb90k) to be truthy + compares extreme values without overflowing + ✓ t(max, kSecond) > t(max, Rational::literal(1, 2)) to be truthy + ✓ t(max, kTb90k) < t(max, kTb48k) to be truthy + ✓ t(max - 1, Rational::literal(1, max)) < t(1, kSecond) to be truthy + rejects a non-positive timebase + ✓ RationalTime::make(1, Rational::literal(0, 1)).has_value() to be falsy + ✓ RationalTime::make(1, Rational::literal(-1, 25)).has_value() to be falsy + rescales with explicit rounding + ✓ r->value() to equal 3754 + ✓ r->timebase() == kTb90k to be truthy + adds only within one timebase + ✓ t(10, kTb90k).plus(t(5, kTb90k))->value() to equal 15 + ✓ code_of(bad.error()) to equal static_cast(ErrorCode::InvalidArgument) + detects overflow in addition + ✓ code_of(r.error()) to equal static_cast(ErrorCode::Overflow) + +● TimeRange + is half-open + ✓ range->contains(t(100, kTb90k)) to be truthy + ✓ range->contains(t(149, kTb90k)) to be truthy + ✓ range->contains(t(150, kTb90k)) to be falsy + ✓ range->contains(t(99, kTb90k)) to be falsy + ✓ range->end().value() to equal 150 + checks membership across timebases + ✓ range->contains(t(89999, kTb90k)) to be truthy + ✓ range->contains(t(90000, kTb90k)) to be falsy + detects overlap + ✓ a->overlaps(*b) to be falsy + ✓ a->overlaps(*c) to be truthy + rejects negative durations and mixed timebases + ✓ TimeRange::make(t(0, kTb90k), t(-1, kTb90k)).has_value() to be falsy + ✓ TimeRange::make(t(0, kTb90k), t(1, kTb48k)).has_value() to be falsy + +● FrameRate + represents NTSC rates as exact fractions + ✓ fr::k29_97.fps() == Rational::literal(30000, 1001) to be truthy + ✓ fr::k59_94.frame_duration() == Rational::literal(1001, 60000) to be truthy + maps frame 300 at 29.97 fps to 10.01 s + ✓ at == t(1001, Rational::literal(1, 100)) to be truthy + maps a time back to a frame with explicit rounding + ✓ *fr::k29_97.time_to_frame(t(10, kSecond), Rounding::Floor) to equal 299 + ✓ *fr::k29_97.time_to_frame(t(10, kSecond), Rounding::Nearest) to equal 300 + ✓ *fr::k25.time_to_frame(t(10, kSecond), Rounding::Floor) to equal 250 + rejects non-positive rates + ✓ FrameRate::make(Rational::literal(0, 1)).has_value() to be falsy + +● SampleRate + addresses audio in samples + ✓ *sr->time_to_sample(t(1, kSecond), Rounding::Floor) to equal 48000 + ✓ sr->sample_to_time(24000) == t(1, Rational::literal(1, 2)) to be truthy + converts 44.1 kHz positions to 96 kHz + ✓ *sr96->time_to_sample(pos, Rounding::Floor) to equal 96000 + rejects non-positive rates + ✓ SampleRate::make(0).has_value() to be falsy + ✓ SampleRate::make(-48000).has_value() to be falsy + +● Error and Result + carries code, category, message and context + ✓ static_cast(e.code()) to equal static_cast(ErrorCode::InvalidData) + ✓ static_cast(e.category()) to equal static_cast(Category::Importer) + ✓ e.message() to equal "truncated header" + ✓ e.context() to equal "clip.prproj" + describes itself for logs and UI warnings + ✓ e.summary() to equal "[timeline] overflow: trim too long (clip 4)" + ✓ bare.summary() to equal "[base] cancelled: stopped" + propagates through Result + ✓ *parse_positive(3) to equal 3 + ✓ r.has_value() to be falsy + ✓ r.error().context() to equal "field 'duration'" + +● Logging + formats messages and records category and call site + ✓ record_count() to equal 1 + ✓ c.message to equal "opened clip.mp4 (2 streams)" + ✓ static_cast(c.category) to equal static_cast(Category::Decode) + ✓ static_cast(c.level) to equal static_cast(LogLevel::Info) + ✓ c.line to be greater than 0 + drops records below the category level + ✓ record_count() to equal 0 + ✓ record_count() to equal 1 + reports enabled levels without formatting + ✓ oma::log_enabled(Category::Cache, LogLevel::Info) to be falsy + ✓ oma::log_enabled(Category::Cache, LogLevel::Error) to be truthy + ✓ oma::log_enabled(Category::Cache, LogLevel::Off) to be falsy + +● JobPool + runs a job and reports success with full progress + ✓ h.wait().has_value() to be truthy + ✓ value.load() to equal 42 + ✓ state_of(h) to equal st(JobState::Succeeded) + ✓ h.progress() to be close to 1 (precision 0.0001) + keeps the error of a failed job + ✓ wait_code(h) to equal static_cast(ErrorCode::InvalidData) + ✓ state_of(h) to equal st(JobState::Failed) + never starts a pending job that was cancelled + ✓ first.wait().has_value() to be truthy + ✓ wait_code(second) to equal static_cast(ErrorCode::Cancelled) + ✓ state_of(second) to equal st(JobState::Cancelled) + ✓ second_ran.load() to be falsy + cancels a running job cooperatively + ✓ wait_code(h) to equal static_cast(ErrorCode::Cancelled) + ✓ state_of(h) to equal st(JobState::Cancelled) + shuts down with running and pending jobs + ✓ state_of(running) to equal st(JobState::Cancelled) + ✓ state_of(pending) to equal st(JobState::Cancelled) + ✓ pending_ran.load() to be falsy + refuses work after shutdown + ✓ state_of(h) to equal st(JobState::Cancelled) + turns an escaping exception into an internal error + ✓ wait_code(h) to equal static_cast(ErrorCode::Internal) + ✓ state_of(h) to equal st(JobState::Failed) + runs many jobs across workers + ✓ counter.load() to equal 200 + +● BoundedQueue + keeps order between a producer and a consumer thread + ✓ stream_in_order(5000) to equal -1LL + blocks the producer while full + ✓ push_waits_for_room() to be truthy + releases a blocked producer on close + ✓ close_releases_producer() to be truthy + pops only what the predicate accepts + ✓ q.try_pop_if([](int v) { return v > 5; }).has_value() to be falsy + ✓ q.try_pop_if([](int v) { return v == 5; }).value_or(0) to equal 5 + ✓ q.size() to equal 1U + drops everything on clear and keeps accepting + ✓ q.size() to equal 0U + ✓ q.push(3) to be truthy + treats a zero capacity as one + ✓ q.capacity() to equal 1U + +Test Suites Summary: + All 118 tests passed! + + +== gpu_tests (debug) + +● gpu::Device +14:26:55.535 INFO gpu device: llvmpipe (LLVM 22.1.8, 256 bits) (llvmpipe, Mesa 26.2.2-arch1.1 (LLVM 22.1.8)), Vulkan 1.4, 6 extensions, internally synchronized queues: no (device.cpp:306) + reports the selected device + ✓ d->info().name.empty() to be falsy + ✓ d->info().api_version >= VK_API_VERSION_1_3 to be truthy + device: llvmpipe (LLVM 22.1.8, 256 bits) (Mesa 26.2.2-arch1.1 (LLVM 22.1.8)) + exposes valid raw handles for interop + ✓ d->instance() != VK_NULL_HANDLE to be truthy + ✓ d->physical_device() != VK_NULL_HANDLE to be truthy + ✓ d->device() != VK_NULL_HANDLE to be truthy + ✓ d->instance_proc_addr() != nullptr to be truthy + has a graphics and compute queue family + ✓ family_has(*d, g, VK_QUEUE_GRAPHICS_BIT) to be truthy + ✓ family_has(*d, g, VK_QUEUE_COMPUTE_BIT) to be truthy + ✓ d->queue(g, 0) != VK_NULL_HANDLE to be truthy + enables timeline semaphores and synchronization2 + ✓ timeline to be truthy + ✓ sync2 to be truthy + only reports extensions it enabled + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension(e) to be truthy + ✓ d->has_extension("VK_NOT_A_REAL_extension") to be falsy + matches the queue creation flags to internal synchronization + ✓ flagged == d->internally_synchronized_queues() to be truthy + locks and unlocks every queue it created + ✓ true to be truthy + can create zero-flag queues for consumers using vkGetDeviceQueue +14:26:55.604 INFO gpu device: llvmpipe (LLVM 22.1.8, 256 bits) (llvmpipe, Mesa 26.2.2-arch1.1 (LLVM 22.1.8)), Vulkan 1.4, 6 extensions, internally synchronized queues: no (device.cpp:306) + ✓ compatible.has_value() to be truthy + ✓ c.internally_synchronized_queues() to be falsy + ✓ c.queue_create_flags() to equal VkDeviceQueueCreateFlags{0} + ✓ retrieved != VK_NULL_HANDLE to be truthy + ✓ retrieved == c.queue(c.graphics_family(), 0) to be truthy + ✓ queue_lock_is_recursive_and_exclusive(c) to be truthy + +● gpu::enumerate_devices + lists the device that was created + ✓ all.has_value() to be truthy + ✓ found to be truthy + rejects a device name that does not exist + ✓ r.has_value() to be falsy + ✓ static_cast(r.error().code()) to equal static_cast(ErrorCode::Unsupported) + +● gpu::Buffer and gpu::CommandRunner + round-trips bytes through device-local memory + ✓ upload && local && readback && runner to be truthy + ✓ upload->mapped() != nullptr to be truthy + ✓ local->mapped() == nullptr to be truthy + ✓ ran.has_value() to be truthy + ✓ std::memcmp(readback->mapped(), pattern.data(), pattern.size()) == 0 to be truthy + creates images with views and moves them + ✓ img.has_value() to be truthy + ✓ img->handle() != VK_NULL_HANDLE to be truthy + ✓ img->view() != VK_NULL_HANDLE to be truthy + ✓ img->desc().width to equal 64 + ✓ moved.handle() != VK_NULL_HANDLE to be truthy + ✓ img->handle() == VK_NULL_HANDLE to be truthy + +Test Suites Summary: + All 41 tests passed! + + +== media_tests (debug) + +● media::probe + describes an H.264 + AAC file + ✓ info.has_value() to be truthy + ✓ info->container to contain "mp4" + ✓ info->streams.size() to equal 2 + ✓ info->duration.has_value() to be truthy + ✓ info->duration->seconds_approx() to be close to 1 (precision 0.1) + ✓ v != nullptr to be truthy + ✓ v->kind == StreamKind::Video to be truthy + ✓ v->codec to equal "h264" + ✓ v->video->width to equal 320 + ✓ v->video->height to equal 180 + ✓ v->video->pixel_format to equal "yuv420p" + ✓ v->video->bit_depth to equal 8 + ✓ v->video->rotation to equal 0 + ✓ v->video->frame_rate.has_value() to be truthy + ✓ v->video->frame_rate->fps() == Rational::literal(30, 1) to be truthy + ✓ v->video->variable_frame_rate to be falsy + ✓ v->video->still_image to be falsy + ✓ v->frame_count.value_or(0) to equal 30 + ✓ a != nullptr to be truthy + ✓ a->codec to equal "aac" + ✓ a->audio->sample_rate.has_value() to be truthy + ✓ a->audio->sample_rate->hz() to equal 48000 + ✓ a->audio->channels to equal 1 + ✓ a->audio->channel_layout to equal "mono" + keeps NTSC frame rates exact + ✓ info.has_value() to be truthy + ✓ rate.has_value() to be truthy + ✓ rate && rate->fps() == Rational::literal(30000, 1001) to be truthy + detects variable frame rate from timestamps + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->variable_frame_rate to be truthy + reads the display rotation + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->rotation to equal 90 + reports 10-bit HEVC + ✓ info.has_value() to be truthy + ✓ v.codec to equal "hevc" + ✓ v.profile to equal "Main 10" + ✓ v.video->bit_depth to equal 10 + ✓ v.video->color.range == ColorRange::Full to be falsy + describes audio-only files + ✓ info.has_value() to be truthy + ✓ info->best_video.has_value() to be falsy + ✓ a != nullptr to be truthy + ✓ a->audio->sample_rate->hz() to equal 44100 + ✓ a->duration.has_value() to be truthy + ✓ a->duration->seconds_approx() to be close to 2 (precision 0.05) + marks still images + ✓ info.has_value() to be truthy + ✓ best_video(*info)->video->still_image to be truthy + ✓ best_video(*info)->video->width to equal 640 + rejects a truncated file as invalid data + ✓ info.has_value() to be falsy + ✓ code_of(info.error()) to equal static_cast(ErrorCode::InvalidData) + reports a missing file as an I/O error + ✓ info.has_value() to be falsy + ✓ code_of(info.error()) to equal static_cast(ErrorCode::IoError) + ✓ info.error().context() to contain "does-not-exist.mp4" + +● media format boundary + uses the existing probe DTO for imported media + ✓ result.has_value() to be truthy + ✓ result->best_video.has_value() to be truthy + ✓ result->best_audio.has_value() to be truthy + accepts a muxer and installed video encoder that fit together + ✓ output.check_output(format).has_value() to be truthy + rejects missing and incompatible output formats + ✓ code_of(output.check_output(missing).error()) to equal static_cast(oma::ErrorCode::Unsupported) + ✓ code_of(output.check_output(wrong_kind).error()) to equal static_cast(oma::ErrorCode::Unsupported) + ✓ code_of(output.check_output(incompatible).error()) to equal static_cast(oma::ErrorCode::Unsupported) + +● media::VideoDecoder (software) + decodes every frame in presentation order + ✓ d.has_value() to be truthy + ✓ d->path() == DecodePath::Software to be truthy + ✓ d->stream().codec to equal "h264" + ✓ f.has_value() to be truthy + ✓ frame.on_gpu() to be falsy + ✓ frame.width() to equal 320 + ✓ frame.height() to equal 180 + ✓ std::string(frame.pixel_format()) to equal "yuv420p" + ✓ frame.plane_count() to equal 3 + ✓ frame.layout().chroma_shift_x to equal 1 + ✓ frame.layout().chroma_shift_y to equal 1 + ✓ frame.layout().interleaved_chroma to be falsy + ✓ frame.layout().container_bits to equal 8 + ✓ frame.stride(0) >= 320 to be truthy + ✓ frame.plane(0).size() >= static_cast(frame.stride(0)) * 180 to be truthy + ✓ frame.pts().has_value() to be truthy + ✓ frame.pts()->value() to equal 0 + ✓ frame.acquire_gpu().has_value() to be falsy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ count to equal 30 + ✓ increasing to be truthy + ✓ after_end.has_value() && !after_end->has_value() to be truthy + keeps 10-bit samples + ✓ d.has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ std::string((*f)->pixel_format()) to equal "yuv420p10le" + ✓ (*f)->bit_depth() to equal 10 + ✓ (*f)->layout().container_bits to equal 16 + ✓ (*f)->layout().lsb_shift to equal 0 + seeks to the frame on screen on VFR media + ✓ d.has_value() to be truthy + ✓ pts.size() > 10 to be truthy + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + ✓ d->seek(ticks(*d, target)).has_value() to be truthy + ✓ f.has_value() && f->has_value() to be truthy + ✓ (*f)->pts()->value() to equal pts[i] + ✓ following.has_value() && following->has_value() to be truthy + ✓ (*following)->pts()->value() to equal pts[i + 1] + seeks to exact frames, before the start and past the end + ✓ d.has_value() to be truthy + ✓ d->seek(ticks(*d, pts[5])).has_value() to be truthy + ✓ on && *on && (*on)->pts()->value() == pts[5] to be truthy + ✓ d->seek(ticks(*d, -1000)).has_value() to be truthy + ✓ first && *first && (*first)->pts()->value() == pts.front() to be truthy + ✓ d->seek(ticks(*d, pts.back() + 10000)).has_value() to be truthy + ✓ last && *last && (*last)->pts()->value() == pts.back() to be truthy + ✓ end.has_value() && !end->has_value() to be truthy + seeks with a time in another timebase + ✓ d.has_value() to be truthy + ✓ d->seek(t).has_value() to be truthy + ✓ f && *f && (*f)->pts().has_value() to be truthy + ✓ *(*f)->pts() == t to be truthy + fails without a usable path + ✓ d.has_value() to be falsy + ✓ code_of(d.error()) to equal static_cast(ErrorCode::Unsupported) + rejects damaged files and non-video streams + ✓ truncated.has_value() to be falsy + ✓ wrong.has_value() to be falsy + ✓ code_of(wrong.error()) to equal static_cast(ErrorCode::InvalidArgument) + +● media::VideoDecoder (GPU paths) + decodes H.264 onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + h264_30fps_aac.mp4: software, 30 frames, 0 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal 0 + decodes 10-bit HEVC onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + hevc_10bit.mp4: software, 30 frames, 0 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal 0 + decodes AV1 onto OmaMovie's device + ✓ d.has_value() to be truthy + ✓ consumer.ok() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + ✓ frame.path() == (*d)->path() to be truthy + ✓ f.has_value() to be truthy + av1_opus.mkv: software, 30 frames, 0 on the GPU + ✓ frames to equal 30 + ✓ on_gpu to equal 0 + falls back to software when the driver refuses a stream + ✓ d.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + ✓ f.has_value() to be truthy + h264_444.mp4: software + ✓ frames to equal 30 + ✓ first_pts to equal 0 + reports a refusal when software is not allowed + ✓ code_of(d.error()) to equal static_cast(oma::ErrorCode::Unsupported) + +● media::AudioDecoder + decodes PCM to planar float with contiguous timestamps + ✓ d.has_value() to be truthy + ✓ (*d)->sample_rate().hz() to equal 44100 + ✓ (*d)->channels() to equal 1 + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ t.frames to equal 88200 + ✓ t.first_pts to equal 0 + ✓ t.contiguous to be truthy + ✓ static_cast(t.peak) to be close to 0.125 (precision 0.01) + resamples and changes the channel count + ✓ d.has_value() to be truthy + ✓ (*d)->sample_rate().hz() to equal 48000 + ✓ (*d)->channels() to equal 2 + ✓ first && *first && (*first)->channel(1).size() == (*first)->channel(0).size() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ total to equal 96000 + upmixes mono to both channels at full level + ✓ d.has_value() to be truthy + ✓ std::abs(left - 0.125F) < 0.002F && std::abs(right - 0.125F) < 0.002F to be truthy + decodes AAC and Opus + ✓ aac.has_value() to be truthy + ✓ (*aac)->stream().codec to equal "aac" + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ std::llabs(t.frames - 48000) <= 2048 to be truthy + ✓ t.contiguous to be truthy + ✓ opus.has_value() to be truthy + ✓ (*opus)->stream().codec to equal "opus" + ✓ (*opus)->sample_rate().hz() to equal 48000 + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ std::llabs(t.frames - 48000) <= 2048 to be truthy + seeks to an exact sample + ✓ (*d)->seek(t).has_value() to be truthy + ✓ b && *b to be truthy + ✓ (*b)->pts.value() to equal 30000 + ✓ static_cast((*b)->channel(0)[0]) to be close to 0.113194 (precision 0.001) + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ first_frames + rest.frames to equal 88200 - 30000 + fails on files without audio + ✓ d.has_value() to be falsy + ✓ code_of(d.error()) to equal static_cast(ErrorCode::InvalidArgument) + reduces steady hiss and keeps the tone + ✓ plain.has_value() && clean.has_value() to be truthy + hiss -38.8 dB -> -64.8 dB + ✓ hiss - reduced > 15.0 to be truthy + ✓ std::abs(tone - kept) < 1.0 to be truthy + lands on the exact sample after a denoised seek + ✓ d.has_value() to be truthy + ✓ (*d)->seek(*RationalTime::make(100000, oma::Rational::literal(1, 48000))).has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ b.has_value() to be truthy + ✓ t.first_pts to equal 100000 + ✓ t.contiguous to be truthy + ✓ t.frames to equal 144000 - 100000 + rejects a denoise amount outside [0, 1] + ✓ AudioDecoder::open(fixture("noisy_tone.wav"), o).has_value() to be falsy + +Test Suites Summary: + All 652 tests passed! + + +== compositor_tests (debug) + +● compositor geometry + composes and inverts affine transforms + ✓ maps(m, 1, 0, 10, 22) to be truthy + ✓ inv.has_value() to be truthy + ✓ maps(*inv, 10, 22, 1, 0) to be truthy + ✓ maps(m.then(*inv), 5, -7, 5, -7, 1e-12) to be truthy + ✓ Affine::scale(0, 1).inverse().has_value() to be falsy + fits, fills and places sources natively + ✓ maps(m, 0, 0, 0, 0) && maps(m, 320, 180, 1920, 1080) to be truthy + ✓ maps(m, 0, 0, 240, 0) && maps(m, 640, 480, 1680, 1080) to be truthy + ✓ maps(m, 0, 0, 0, -180) && maps(m, 640, 480, 1920, 1260) to be truthy + ✓ maps(m, 0, 0, 800, 450) to be truthy + applies display rotation and pixel aspect + ✓ box.has_value() to be truthy + ✓ (*box)[0] to equal 656 + ✓ (*box)[2] to equal 1264 + ✓ (*box)[1] to equal 0 + ✓ (*box)[3] to equal 1080 + ✓ maps(m, 0, 0, 656.25, 1080) to be truthy + ✓ maps(w, 160, 180, 1920, 1080) to be truthy + crops, scales and offsets layers + ✓ maps(m, 200, 100, 600, 450) to be truthy + ✓ maps(m, 100, 100, 400, 450) to be truthy + ✓ box && (*box)[0] == 400 && (*box)[2] == 800 && (*box)[1] == 250 && (*box)[3] == 650 to be truthy + ✓ oma::compositor::covered_pixels(layer, src, 1000, 1000).has_value() to be falsy + validates render graphs + ✓ oma::compositor::validate(g, 1).has_value() to be truthy + ✓ oma::compositor::validate(g, 0).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ !r && r.error().code() == ErrorCode::InvalidArgument to be truthy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be truthy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + ✓ oma::compositor::validate(g, 1).has_value() to be falsy + +● compositor color + converts limited, full and 10-bit YUV + ✓ rgb_near(rgb(m8, 16.0 / 255, 128.0 / 255, 128.0 / 255), 0, 0, 0) to be truthy + ✓ rgb_near(rgb(m8, 235.0 / 255, 128.0 / 255, 128.0 / 255), 1, 1, 1) to be truthy + ✓ rgb_near(rgb(m8, 63.0 / 255, 102.0 / 255, 240.0 / 255), 1, 0, 0, 0.01) to be truthy + ✓ rgb_near(rgb(m10, 64.0 / 1023, 512.0 / 1023, 512.0 / 1023), 0, 0, 0) to be truthy + ✓ rgb_near(rgb(m10, 940.0 / 1023, 512.0 / 1023, 512.0 / 1023), 1, 1, 1) to be truthy + ✓ rgb_near(rgb(full, 1.0, 128.0 / 255, 128.0 / 255), 1, 1, 1) to be truthy + ✓ near(sd.matrix.at(0, 2), hd.matrix.at(0, 2), 1e-3) to be falsy + converts primaries and decodes transfers + ✓ near(same.at(0, 0), 1, 1e-9) && near(same.at(0, 1), 0, 1e-9) && near(same.at(2, 2), 1, 1e-9) to be truthy + ✓ near(m.at(0, 0), 1.6605, 1e-3) && near(m.at(0, 1), -0.5876, 1e-3) && near(m.at(0, 2), -0.0728, 1e-3) to be truthy + ✓ near(m.at(1, 0), -0.1246, 1e-3) && near(m.at(1, 1), 1.1329, 1e-3) to be truthy + ✓ near(m.at(2, 1), -0.1006, 1e-3) && near(m.at(2, 2), 1.1187, 1e-3) to be truthy + ✓ near(oma::compositor::to_linear(0.5, Transfer::Srgb), 0.214041, 1e-6) to be truthy + ✓ near(oma::compositor::to_linear(0.5, Transfer::Bt1886), std::pow(0.5, 2.4)) to be truthy + ✓ near(oma::compositor::to_linear(1.7, Transfer::Linear), 1.0) to be truthy + ✓ oma::compositor::resolve_transfer(16, &hdr) == Transfer::Bt1886 && hdr to be truthy + ✓ oma::compositor::resolve_transfer(13, &hdr) == Transfer::Srgb && !hdr to be truthy + +● compositor::CpuCompositor + fills the background premultiplied + ✓ out.has_value() to be truthy + ✓ static_cast(px[0]) to be close to 0.5 (precision 1e-06) + ✓ static_cast(px[1]) to be close to 0.25 (precision 1e-06) + ✓ static_cast(px[3]) to be close to 0.5 (precision 1e-06) + draws opaque layers and moves them by exact pixels + ✓ src.frame.has_value() to be truthy + ✓ a && b to be truthy + ✓ static_cast(a->at(0, 0)[3]) to be close to 1 (precision 1e-06) + ✓ shifted to be truthy + ✓ static_cast(b->at(5, 100)[1]) to be close to 0 (precision 1e-06) + ✓ static_cast(b->at(5, 100)[2]) to be close to 1 (precision 1e-06) + applies opacity and blend modes + ✓ full && half && doubled to be truthy + ✓ static_cast(h[0]) to be close to 0.0250907 (precision 1e-06) + ✓ static_cast(h[3]) to be close to 0.5 (precision 1e-06) + ✓ static_cast(d[1]) to be close to 1.93159 (precision 1e-06) + ✓ static_cast(d[3]) to be close to 1 (precision 1e-06) + rejects missing inputs + ✓ CpuCompositor{}.render(g, empty).has_value() to be falsy + ✓ CpuCompositor{}.render(g, {}).has_value() to be falsy + adjusts exposure, saturation, temperature, contrast and filters + ✓ static_cast(twice[c]) to be close to 0.319598 (precision 1e-05) + ✓ static_cast(twice[c]) to be close to 0.319598 (precision 1e-05) + ✓ static_cast(twice[c]) to be close to 0.319598 (precision 1e-05) + ✓ w[0] > base[0] && w[2] < base[2] to be truthy + ✓ luma(w) to be close to 0.159799 (precision 0.0001) + ✓ luma(at(dark, punchy, {})) < luma(at(dark, {}, {})) to be truthy + ✓ luma(at(280, punchy, {})) > luma(at(280, {}, {})) to be truthy + ✓ std::abs(g[0] - g[1]) < 1e-6F && std::abs(g[1] - g[2]) < 1e-6F to be truthy + ✓ static_cast(g[0]) to be close to 0.152737 (precision 1e-05) + ✓ static_cast(bw[0]) to be close to 0.152737 (precision 1e-06) + ✓ static_cast(half[0]) to be close to 0.34568 (precision 1e-05) + darkens the corners with a vignette + ✓ center == looked(in, {}, {}, 160, 90) to be truthy + ✓ luma(corner) < 0.3 * luma(looked(in, {}, {}, 2, 2)) to be truthy + blurs and sharpens edges, leaving flat areas + ✓ luma(detailed_at(in, -0.5, 78)) > edge + 0.005 to be truthy + ✓ luma(detailed_at(in, -0.5, 40)) to be close to 0.0179314 (precision 0.0001) + ✓ luma(detailed_at(in, 1.0, 79)) < luma(detailed_at(in, 0.0, 79)) - 0.002 to be truthy + ✓ luma(detailed_at(in, 1.0, 40)) to be close to 0.0179314 (precision 0.0001) + reveals the left part of a layer for wipes + ✓ out.has_value() to be truthy + ✓ static_cast(out->at(79, 90)[3]) to be close to 1 (precision 1e-06) + ✓ static_cast(out->at(80, 90)[3]) to be close to 0 (precision 1e-06) + ✓ half && std::abs(half->at(80, 90)[3] - 0.5F) < 1e-5F to be truthy + +● compositor::VulkanCompositor + matches the CPU reference on uploaded frames + ✓ vk.has_value() to be truthy + ✓ rendered.has_value() to be truthy + ✓ cpu && gpu to be truthy + max difference 0.00178, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + matches the CPU reference with color adjustments and filters + ✓ vk.has_value() to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + max difference 0.00447, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + matches the CPU reference with a reduced blur + ✓ vk.has_value() to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + max difference 0.00166, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + matches the CPU reference on zero-copy GPU frames + (skipped: no hardware decode here) + encodes the output for an SDR display + ✓ vk.has_value() to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ encoded.has_value() to be truthy + ✓ linear && display to be truthy + ✓ display->size() == linear->pixels.size() to be truthy + worst difference 0 of 255 + ✓ worst <= 1 to be truthy + draws RGB images as sRGB + ✓ png.frame->layout().yuv to be falsy + ✓ png.frame->copy_rgba(rgba, static_cast(w) * 4).has_value() to be truthy + ✓ cpu.has_value() to be truthy + worst difference from the PNG 0.000000 + ✓ worst < 1e-4 to be truthy + ✓ vk.has_value() to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ gpu.has_value() to be truthy + ✓ compare(*gpu, *cpu, kTolerance).over_tolerance == 0U to be truthy + measures three 1080p layers + ✓ (*vk)->render(g, inputs).has_value() to be truthy + 1080p, 3 layers (uploaded inputs): 105.48 ms per frame, submit to completion + +● compositor grading + parses Adobe and Resolve .cube files + ✓ adobe.has_value() to be truthy + ✓ static_cast(adobe->size) to equal 3 + ✓ static_cast(adobe->rgb.size()) to equal 27 * 3 + ✓ static_cast(adobe->domain_max[2]) to equal 2.0 + ✓ static_cast(adobe->rgb[3]) to be close to 0.5 (precision 1e-06) + ✓ resolve.has_value() to be truthy + ✓ static_cast(resolve->domain_max[0]) to equal 1.5 + refuses malformed .cube files + ✓ parses(good) to be truthy + ✓ parses("0 0 0\n") to be falsy + ✓ parses(cube(2, "").substr(0, good.size() - 9)) to be falsy + ✓ parses(good + "1 1 1\n") to be falsy + ✓ parses(good + "TITLE \"late\"\n") to be falsy + ✓ parses("LUT_3D_SIZE 1\n0 0 0\n") to be falsy + ✓ parses("LUT_3D_SIZE 66\n") to be falsy + ✓ parses("LUT_3D_SIZE 2.5\n") to be falsy + ✓ parses("LUT_3D_SIZE 2\n0 0 nan\n") to be falsy + ✓ parses("LUT_3D_SIZE 2\n0 0 0 0\n") to be falsy + ✓ parses("LUT_3D_SIZE 2\n0 0x\n") to be falsy + ✓ parses("DOMAIN_MIN 1 1 1\nDOMAIN_MAX 0 0 0\n" + good) to be falsy + ✓ !one_d && one_d.error().code() == oma::ErrorCode::Unsupported to be truthy + ✓ parses(std::string(oma::compositor::kMaxCubeBytes + 1, '#')) to be falsy + passes curves through their points without overshoot + ✓ oma::compositor::evaluate_curve(crush, p.x) to be close to 0 (precision 1e-12) + ✓ oma::compositor::evaluate_curve(crush, p.x) to be close to 0 (precision 1e-12) + ✓ oma::compositor::evaluate_curve(crush, p.x) to be close to 0.6 (precision 1e-12) + ✓ oma::compositor::evaluate_curve(crush, p.x) to be close to 1 (precision 1e-12) + ✓ monotone to be truthy + ✓ oma::compositor::evaluate_curve(inner, 0.05) to be close to 0.3 (precision 1e-12) + ✓ oma::compositor::evaluate_curve({}, 0.42) to be close to 0.42 (precision 1e-12) + validates grades + ✓ oma::compositor::validate(g).has_value() to be truthy + ✓ oma::compositor::validate(g).has_value() to be falsy + ✓ oma::compositor::validate(g).has_value() to be falsy + ✓ oma::compositor::validate(g).has_value() to be falsy + keeps the image under an identity LUT + ✓ static_cast(max_difference(graded_row(in, identity), graded_row(in, {}))) to be less than 2e-5 + keeps greys grey under a creative LUT + ✓ static_cast(std::abs(row[x][0] - row[x][1])) to be less than 1e-6 + ✓ static_cast(std::abs(row[x][1] - row[x][2])) to be less than 1e-6 + ✓ static_cast(std::abs(row[x][0] - row[x][1])) to be less than 1e-6 + ✓ static_cast(std::abs(row[x][1] - row[x][2])) to be less than 1e-6 + ✓ std::abs(row[200][0] - plain[200][0]) > 0.01F to be truthy + ✓ static_cast(max_difference(graded_row(src.input(), g), plain)) to be less than 1e-6 + applies the CDL and curves to code values + ✓ static_cast(encode(graded[120][0])) to be close to 0.232877 (precision 0.0001) + ✓ static_cast(encode(graded[120][1])) to be close to 0.565753 (precision 0.0001) + ✓ static_cast(encode(graded[120][2])) to be close to 0.216926 (precision 0.0001) + ✓ static_cast(negative[280][1]) to be less than 1e-4 + ✓ static_cast(encode(negative[40][1])) to be close to 0.812785 (precision 0.0001) + matches the CPU reference on the GPU + ✓ vk.has_value() to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + CDL, curves and LUT: max difference 0.00068, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + same LUT again (cached): max difference 0.00068, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + ✓ (*vk)->render(g, inputs).has_value() to be truthy + ✓ cpu && gpu to be truthy + another LUT: max difference 0.00068, 0 of 230400 pixels over tolerance + ✓ diff.over_tolerance <= cpu->pixels.size() / 4 / 500 to be truthy + +Test Suites Summary: + All 164 tests passed! + + +== audio_tests (debug) + +● SampleRing + rounds the capacity up to a power of two frames + ✓ ring.capacity() to equal 128U + ✓ ring.writable() to equal 128U + ✓ ring.readable() to equal 0U + writes and reads whole interleaved frames in order + ✓ ring.write(in) to equal 3U + ✓ ring.read(out) to equal 3U + ✓ out[0] to equal 0.0F + ✓ out[5] to equal 5.0F + ignores a trailing partial frame + ✓ ring.write(in) to equal 2U + ✓ ring.readable() to equal 2U + accepts only what fits and keeps the rest for later + ✓ ring.write(in) to equal 4U + ✓ ring.writable() to equal 0U + ✓ ring.read(out) to equal 2U + ✓ out[1] to equal 11.0F + ✓ ring.write(more) to equal 2U + ✓ ring.read(rest) to equal 4U + ✓ rest[0] to equal 12.0F + ✓ rest[3] to equal 21.0F + drops everything readable on discard + ✓ ring.readable() to equal 0U + ✓ ring.writable() to equal 8U + keeps order between a producer and a consumer thread + ✓ stream_through_ring(20000) to equal -1LL + +● PlaybackClock + starts at the anchor and advances with consumed frames + ✓ clock.anchor(at(0, 1, 1), 0).has_value() to be truthy + ✓ clock.position(0, 0) == at(0, 1, 1) to be truthy + ✓ clock.position(48000, 0) == at(1, 1, 1) to be truthy + subtracts the device latency + ✓ clock.anchor(at(10, 1, 1), 1000).has_value() to be truthy + ✓ clock.position(49000, 2400) == at(10 * 48000 + 45600, 1, 48000) to be truthy + never reports a position before the anchor + ✓ clock.anchor(at(5, 1, 1), 500).has_value() to be truthy + ✓ clock.position(600, 1024) == at(5, 1, 1) to be truthy + rounds a video anchor to the nearest sample + ✓ clock.anchor(at(1, 1001, 30000), 0).has_value() to be truthy + ✓ clock.anchor_sample() to equal 1471LL + re-anchors after a seek relative to the new consumed count + ✓ clock.anchor(at(0, 1, 1), 0).has_value() to be truthy + ✓ clock.anchor(at(3600, 1, 1), 192000).has_value() to be truthy + ✓ clock.position(288000, 0) == at(3601, 1, 1) to be truthy + reports overflow for an anchor beyond the sample range + ✓ clock.anchor(huge, 0).has_value() to be falsy + +● NullOutput + rejects an invalid format + ✓ oma::audio::make_null_output(bad).has_value() to be falsy + consumes everything written + ✓ null_consumes_everything_written() to be truthy + counts underruns and stalls the clock without data + ✓ null_counts_underruns_without_advancing() to be truthy + drops queued frames on flush + ✓ null_flush_drops_queued_frames() to be truthy + consumes frames no faster than real time + ✓ null_consumes_at_the_device_rate() to be truthy + flushes and stops safely when never started + ✓ out->ring().readable() to equal 0U + +● PipeWireOutput + plays silence through the daemon when one answers + (skipping PipeWire test: [audio] unsupported: no PipeWire output available (Operation not permitted)) + +● ClipGain + is constant between the fades + ✓ faded().at(50) to equal 0.5F + ✓ faded().at(10) to equal 0.5F + ✓ faded().at(79) to equal 0.5F + ramps linearly in from silence + ✓ faded().at(0) to equal 0.0F + ✓ faded().at(5) to equal 0.25F + ramps out to silence at the last sample + ✓ faded().at(99) to equal 0.0F + ✓ faded().at(89) to equal 0.25F + is silent outside the clip + ✓ faded().at(-1) to equal 0.0F + ✓ faded().at(100) to equal 0.0F + +● mix_planar + interleaves planar stereo and adds to what is there + ✓ out[0] to equal 2.0F + ✓ out[1] to equal 11.0F + ✓ out[6] to equal 5.0F + ✓ out[7] to equal 41.0F + feeds mono to every output channel + ✓ out[0] == 3.0F && out[1] == 3.0F to be truthy + ✓ out[2] == 5.0F && out[3] == 5.0F to be truthy + applies the gain at the clip position of each sample + ✓ out[0] to equal 0.025F + ✓ out[2] == 0.0F && out[4] == 0.0F && out[6] == 0.0F to be truthy + never writes past the output + ✓ out[0] == 1.0F && out[1] == 10.0F to be truthy + +● audio::ClipGain crossfades + plays before and after the clip under equal-power ramps + ✓ g.at(-101) to equal 0.0F + ✓ g.at(-100) to equal 0.0F + ✓ std::abs(g.at(0) - 0.70710678F) < 1e-6F to be truthy + ✓ g.at(500) to equal 1.0F + ✓ g.at(1100) to equal 0.0F + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + ✓ std::abs((out * out) + (in * in) - 1.0F) < 1e-5F to be truthy + +● audio::Equalizer + leaves samples untouched when flat + ✓ eq.active() to be falsy + ✓ x[0] == 0.1F && x[1] == -0.2F && x[2] == 0.3F to be truthy + boosts and cuts each band where it acts + ✓ near(gain_db(bands(6.0F, 0.0F, 0.0F), 30.0), 6.0, 0.3) to be truthy + ✓ near(gain_db(bands(6.0F, 0.0F, 0.0F), 4000.0), 0.0, 0.2) to be truthy + ✓ near(gain_db(bands(0.0F, -6.0F, 0.0F), 1000.0), -6.0, 0.2) to be truthy + ✓ near(gain_db(bands(0.0F, -6.0F, 0.0F), 60.0), 0.0, 0.3) to be truthy + ✓ near(gain_db(bands(0.0F, 0.0F, 6.0F), 18000.0), 6.0, 0.4) to be truthy + ✓ near(gain_db(bands(0.0F, 0.0F, 6.0F), 200.0), 0.0, 0.2) to be truthy + filters each channel with its own state + ✓ right to equal 0.0F + ✓ x[0] != 1.0F to be truthy + +● audio::EffectChain + lets samples through untouched while no effect is active + ✓ chain.active() to be falsy + ✓ x == samples() to be truthy + runs the active effects in slot order + ✓ chain.active() to be truthy + ✓ x == samples() to be truthy + ✓ x[3] to equal 2.0F + keeps an effect of the same kind and replaces one of another kind + ✓ &chain.at(0) == first to be truthy + ✓ chain.at(0).factor to equal 3.0F + ✓ chain.at(0).active() to be truthy + resets every effect and drops slots past a size + ✓ static_cast(chain.size()) to equal 3 + ✓ chain.at(0).resets to equal 1 + ✓ static_cast(chain.size()) to equal 1 + +Test Suites Summary: + All 89 tests passed! + + +== timeline_tests (debug) + +● Timeline model + picks a timebase that holds frames and samples + ✓ default_den(oma::frame_rates::k29_97, 48000) to equal 240000LL + ✓ default_den(oma::frame_rates::k23_976, 44100) to equal 3528000LL + ✓ default_den(oma::frame_rates::k59_94, 96000) to equal 480000LL + ✓ default_den(oma::frame_rates::k25, 48000) to equal 48000LL + ✓ tl->to_ticks(oma::frame_rates::k29_97.frame_to_time(1)).value() to equal 8008LL + ✓ tl->to_ticks(oma::SampleRate::make(48000).value().sample_to_time(1)).value() to equal 5LL + rejects a timebase that does not hold whole frames + ✓ Timeline::create(oma::frame_rates::k29_97, q(1, 30)).has_value() to be falsy + ✓ Timeline::create(oma::frame_rates::k30, q(1, 30)).has_value() to be truthy + converts exact times from other timebases and rejects inexact ones + ✓ tl.to_ticks(exact).value() to equal 2LL + ✓ tl.to_ticks(inexact).has_value() to be falsy + finds clips by half-open ranges + ✓ tl.clip_at(fx.video, 9)->id == a to be truthy + ✓ tl.clip_at(fx.video, 10)->id == b to be truthy + ✓ tl.clip_at(fx.video, 20) == nullptr to be truthy + ✓ tl.track_of(b)->id == fx.video to be truthy + ✓ tl.duration() == f(20) to be truthy + ✓ tl.validate().has_value() to be truthy + rejects non-positive speeds + ✓ TimeMap::constant(q(0, 1)).has_value() to be falsy + ✓ TimeMap::constant(q(-1, 1)).has_value() to be falsy + ✓ TimeMap::constant(q(1, 2)).has_value() to be truthy + edits audio at sample positions between frames + ✓ ed.execute(edit::overwrite(a, id, ed.timeline().at(0), edit::ClipSource{.media = kMusic, .source_in = zero, .duration = second, .time_map = {}, .video = {}, .audio = {}})) .has_value() to be truthy + ✓ ed.execute(edit::split(id, sample)).has_value() to be truthy + ✓ tail->source_in == sample to be truthy + keeps source positions exact through trims on a non-matching media grid + ✓ trim_round_trip_is_exact(1) to be truthy + ✓ trim_round_trip_is_exact(10010) to be truthy + rounds media times down to the media grid only on evaluation + ✓ at_one->video.front().media_time.value() to equal 15360LL + ✓ at_frame->video.front().media_time.value() to equal 16000LL + +● timeline edits: placing clips + appends clips back to back + ✓ ok(fx, edit::append(v, fx.editor.new_clip_id(), camera(0, 10))) to be truthy + ✓ ok(fx, edit::append(v, fx.editor.new_clip_id(), camera(30, 5))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+5@30" + overwrites the middle of a clip by splitting it + ✓ place(fx, fx.video, 10, 100, 5).valid() to be truthy + ✓ layout(fx) to equal "0+10@0 10+5@100 15+15@15" + overwrites across an edit point by trimming both sides + ✓ layout(fx) to equal "0+5@0 5+10@200 15+5@55" + inserts inside a clip by splitting it and pushing the rest + ✓ ok(fx, edit::insert(fx.video, id, f(10), camera(100, 5))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+5@100 15+20@10 45+5@200" + inserts at an edit point without splitting + ✓ ok(fx, edit::insert(fx.video, fx.editor.new_clip_id(), f(10), camera(200, 5))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+5@200 15+10@50 25+10@100" + rejects media of the wrong kind and leaves the timeline unchanged + ✓ ok(fx, overwrite_music(fx.video, fx.editor.new_clip_id(), 0)) to be falsy + ✓ layout(fx) to equal before + ✓ fx.editor.revision() to equal revision + ✓ std::string(fx.editor.undo_name()) to equal "Overwrite" + accepts audio-only media on an audio track + ✓ ok(fx, overwrite_music(fx.audio, fx.editor.new_clip_id(), 0)) to be truthy + ✓ fx.editor.timeline().find_track(fx.audio)->clips.size() to equal 1U + rejects a source range beyond the media + ✓ place(fx, fx.video, 0, 295, 10).valid() to be falsy + ✓ place(fx, fx.video, 0, 290, 10).valid() to be truthy + rejects reusing a clip ID + ✓ ok(fx, edit::overwrite(fx.video, id, f(0), camera(0, 5))) to be truthy + ✓ ok(fx, edit::overwrite(fx.overlay, id, f(0), camera(0, 5))) to be falsy + rejects times off the sequence grid + ✓ ok(fx, edit::overwrite(fx.video, fx.editor.new_clip_id(), half_frame, camera(0, 5))) to be falsy + +● timeline edits: deleting and splitting + deletes a clip and leaves a gap + ✓ ok(fx, edit::remove_clip(clip_at(fx, 10))) to be truthy + ✓ layout(fx) to equal "0+10@0 20+10@100" + ripple deletes a clip and closes the gap + ✓ ok(fx, edit::ripple_delete(clip_at(fx, 10))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+10@100" + ripple deletes a range across clips + ✓ ok(fx, edit::ripple_delete_range(fx.video, f(5), f(25))) to be truthy + ✓ layout(fx) to equal "0+5@0 5+5@105" + ripple deletes a range inside one clip + ✓ ok(fx, edit::ripple_delete_range(fx.video, f(10), f(20))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+10@20" + splits a clip and gives the right part a new ID + ✓ ok(fx, edit::split(id, f(12))) to be truthy + ✓ layout(fx) to equal "0+12@0 12+18@12" + ✓ clip_at(fx, 0) == id to be truthy + ✓ clip_at(fx, 12) != id && clip_at(fx, 12).valid() to be truthy + refuses to split at a clip edge + ✓ ok(fx, edit::split(id, f(0))) to be falsy + ✓ ok(fx, edit::split(id, f(30))) to be falsy + +● timeline edits: trimming + trims the start in place, moving the source in + ✓ ok(fx, edit::remove_clip(clip_at(fx, 0))) to be truthy + ✓ ok(fx, edit::trim_start(clip_at(fx, 10), f(13), false)) to be truthy + ✓ layout(fx) to equal "13+7@53 20+10@100" + ✓ ok(fx, edit::trim_start(clip_at(fx, 13), f(4), false)) to be truthy + ✓ layout(fx) to equal "4+16@44 20+10@100" + ripple trims the start, pulling the following clips + ✓ ok(fx, edit::trim_start(clip_at(fx, 10), f(13), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+7@53 17+10@100" + ripple trims the end outward, pushing the following clips + ✓ ok(fx, edit::trim_end(clip_at(fx, 10), f(25), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+15@50 25+10@100" + refuses to trim into a neighbour without ripple + ✓ ok(fx, edit::trim_end(clip_at(fx, 10), f(25), false)) to be falsy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + refuses to trim before the start of the media + ✓ ok(fx, edit::trim_start(id, f(6), false)) to be falsy + ✓ ok(fx, edit::trim_start(id, f(7), false)) to be truthy + ✓ layout(fx) to equal "7+13@0" + rolls an edit point both ways + ✓ ok(fx, edit::roll(left, f(13))) to be truthy + ✓ layout(fx) to equal "0+13@0 13+7@53 20+10@100" + ✓ ok(fx, edit::roll(left, f(8))) to be truthy + ✓ layout(fx) to equal "0+8@0 8+12@48 20+10@100" + refuses to roll without an adjacent clip + ✓ ok(fx, edit::roll(id, f(11))) to be falsy + slips the source under a fixed range + ✓ ok(fx, edit::slip(clip_at(fx, 10), f(5))) to be truthy + ✓ layout(fx) to equal "0+10@0 10+10@55 20+10@100" + ✓ ok(fx, edit::slip(clip_at(fx, 0), f(-1))) to be falsy + slides a clip between its neighbours + ✓ ok(fx, edit::slide(clip_at(fx, 10), f(3))) to be truthy + ✓ layout(fx) to equal "0+13@0 13+10@50 23+7@103" + ✓ ok(fx, edit::slide(clip_at(fx, 13), f(-5))) to be truthy + ✓ layout(fx) to equal "0+8@0 8+10@50 18+12@98" + slides into a gap without touching the far clip + ✓ ok(fx, edit::slide(id, f(4))) to be truthy + ✓ layout(fx) to equal "0+14@0 14+10@50 25+10@100" + ✓ ok(fx, edit::slide(id, f(2))) to be falsy + +● timeline edits: moving, speed and properties + moves a clip to a free spot on another track + ✓ ok(fx, edit::move_clip(id, fx.overlay, f(40))) to be truthy + ✓ layout(fx) to equal "0+10@0 20+10@100" + ✓ layout(fx.editor.timeline(), fx.overlay) to equal "40+10@50" + refuses to move onto another clip or onto a track of another kind + ✓ ok(fx, edit::move_clip(id, fx.video, f(15))) to be falsy + ✓ ok(fx, edit::move_clip(id, fx.audio, f(40))) to be falsy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + reorders a clip along its track, closing and opening gaps + ✓ ok(fx, edit::ripple_move(clip_at(fx, 0), f(20))) to be truthy + ✓ layout(fx) to equal "0+10@50 10+10@100 20+10@0" + ✓ ok(fx, edit::ripple_move(clip_at(fx, 20), f(10))) to be truthy + ✓ layout(fx) to equal "0+10@50 10+10@0 20+10@100" + ✓ ok(fx, edit::ripple_move(clip_at(fx, 20), f(0))) to be truthy + ✓ layout(fx) to equal "0+10@100 10+10@50 20+10@0" + refuses a reorder that lands inside another clip + ✓ ok(fx, edit::ripple_move(clip_at(fx, 0), f(5))) to be falsy + ✓ ok(fx, edit::ripple_move(clip_at(fx, 0), f(-10))) to be falsy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + drops the transitions whose clip pairs a reorder separates + ✓ ok(fx, edit::set_transition(clip_at(fx, 10), dissolve())) to be truthy + ✓ ok(fx, edit::set_transition(clip_at(fx, 20), dissolve())) to be truthy + ✓ ok(fx, edit::ripple_move(first, f(10))) to be truthy + ✓ tl.find_clip(clip_at(fx, 0))->transition_in.has_value() to be falsy + ✓ tl.find_clip(first)->transition_in.has_value() to be falsy + ✓ tl.find_clip(clip_at(fx, 20))->transition_in.has_value() to be falsy + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.timeline().find_clip(clip_at(fx, 20))->transition_in.has_value() to be truthy + undoes and redoes a reorder exactly + ✓ undo_redo_round_trip(fx, std::move(commands)) to be truthy + doubles the speed, halving the duration and pulling later clips + ✓ ok(fx, edit::set_speed(clip_at(fx, 10), q(2, 1), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+5@50 15+10@100" + halves the speed, doubling the duration and pushing later clips + ✓ ok(fx, edit::set_speed(clip_at(fx, 10), q(1, 2), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+20@50 30+10@100" + ✓ ok(fx, edit::trim_start(clip_at(fx, 10), f(14), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+16@52 26+10@100" + rounds an uneven speed down to the sequence grid + ✓ ok(fx, edit::set_speed(clip_at(fx, 10), q(3, 1), true)) to be truthy + ✓ layout(fx) to equal "0+10@0 10+3@50 13+10@100" + rejects a non-positive speed + ✓ ok(fx, edit::set_speed(clip_at(fx, 10), q(0, 1), true)) to be falsy + changes video and audio properties, rejecting invalid ones + ✓ ok(fx, edit::set_video(id, v)) to be truthy + ✓ fx.editor.timeline().find_clip(id)->video == v to be truthy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ ok(fx, edit::set_video(id, v)) to be truthy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ ok(fx, edit::set_video(id, v)) to be truthy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ ok(fx, edit::set_audio(id, a)) to be truthy + ✓ ok(fx, edit::set_audio(id, a)) to be falsy + ✓ ok(fx, edit::set_audio(id, a)) to be truthy + ✓ ok(fx, edit::set_audio(id, a)) to be falsy + ✓ ok(fx, edit::set_audio(id, a)) to be falsy + ✓ ok(fx, edit::set_audio(id, a)) to be falsy + grades a clip with a registered LUT, refusing unknown ones and bad curves + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ fx.editor.add_lut(LutInfo{.id = LutId(77), .name = "Film"}).has_value() to be truthy + ✓ fx.editor.add_lut(LutInfo{.id = LutId(77), .name = "Again"}).has_value() to be falsy + ✓ ok(fx, edit::set_video(id, v)) to be truthy + ✓ fx.editor.timeline().find_clip(id)->video.grade == v.grade to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.timeline().find_clip(id)->video.grade == ColorGrade{} to be truthy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + ✓ ok(fx, edit::set_video(id, v)) to be falsy + +● timeline edits: history + undoes and redoes every operation exactly + ✓ undo_redo_round_trip(fx, std::move(commands)) to be truthy + records each compound operation as one history entry + ✓ std::string(fx.editor.undo_name()) to equal "Overwrite" + ✓ fx.editor.undo().has_value() to be truthy + ✓ layout(fx) to equal "0+30@0" + groups commands in a transaction and rolls all back on failure + ✓ ok(fx, edit::transaction("Delete Selection", std::move(good))) to be truthy + ✓ layout(fx) to equal "10+10@50" + ✓ fx.editor.undo().has_value() to be truthy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + ✓ ok(fx, edit::transaction("Broken", std::move(bad))) to be falsy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + clears the redo stack on a new edit + ✓ ok(fx, edit::remove_clip(clip_at(fx, 0))) to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.can_redo() to be truthy + ✓ ok(fx, edit::remove_clip(clip_at(fx, 20))) to be truthy + ✓ fx.editor.can_redo() to be falsy + ✓ fx.editor.redo().has_value() to be falsy + restores a removed track with its clips + ✓ ok(fx, edit::remove_track(fx.video)) to be truthy + ✓ fx.editor.timeline().find_track(fx.video) == nullptr to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + ✓ fx.editor.timeline().tracks().front().id == fx.video to be truthy + registers media outside the history + ✓ ed.add_media(cam).has_value() to be truthy + ✓ ed.can_undo() to be falsy + ✓ ed.add_media(cam).has_value() to be falsy + ✓ ed.timeline().find_media(kCamera) != nullptr to be truthy + forgets the history but keeps the timeline + ✓ fx.editor.can_undo() to be truthy + ✓ fx.editor.can_undo() || fx.editor.can_redo() to be falsy + ✓ layout(fx) to equal "0+10@0 10+10@50 20+10@100" + never reuses an ID after undo + ✓ ok(fx, edit::split(id, f(10))) to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ ok(fx, edit::split(id, f(10))) to be truthy + ✓ clip_at(fx, 10) != first_tail to be truthy + bumps the revision on execute, undo and redo + ✓ ok(fx, edit::remove_clip(clip_at(fx, 0))) to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.redo().has_value() to be truthy + ✓ fx.editor.revision() - r0 to equal 3U + adds, sorts and removes markers through the history + ✓ ok(fx, edit::add_marker(late, f(90), "chorus")) to be truthy + ✓ ok(fx, edit::add_marker(early, f(30), "intro")) to be truthy + ✓ fx.editor.timeline().markers().front().name to equal "intro" + ✓ ok(fx, edit::remove_marker(early)) to be truthy + ✓ fx.editor.timeline().markers().size() to equal 1U + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.timeline().markers().size() to equal 2U + ✓ ok(fx, edit::add_marker(fx.editor.new_marker_id(), off_grid, "x")) to be falsy + +● timeline edits: detaching audio + moves a video clip's sound to an audio clip of its own + ✓ ok(fx, edit::detach_audio(video, fx.audio, sound)) to be truthy + ✓ a != nullptr && tl.track_of(sound)->id == fx.audio to be truthy + ✓ a->start == f(10) && a->duration == f(30) && a->source_in == mf(5) to be truthy + ✓ tl.find_clip(video)->audio_detached to be truthy + ✓ c.audio.size() to equal 1U + ✓ c.audio.front().clip == sound to be truthy + ✓ c.video.size() to equal 1U + lets the two parts be trimmed apart and joins them on undo + ✓ ok(fx, edit::detach_audio(video, fx.audio, sound)) to be truthy + ✓ ok(fx, edit::trim_start(sound, f(7), false)) to be truthy + ✓ layout(fx.editor.timeline(), fx.audio) to equal "7+33@2" + ✓ layout(fx) to equal "10+30@5" + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.undo().has_value() to be truthy + ✓ fx.editor.timeline().find_clip(sound) == nullptr to be truthy + ✓ fx.editor.timeline().find_clip(video)->audio_detached to be falsy + ✓ evaluate(fx.editor.timeline(), f(20)).value().audio.size() to equal 1U + refuses clips without sound, occupied lanes and a second detach + ✓ fx.editor .execute(edit::overwrite(fx.overlay, picture, f(0), edit::ClipSource{.media = kPicture, .source_in = {}, .duration = f(10), .time_map = {}, .video = {}, .audio = {}})) .has_value() to be truthy + ✓ ok(fx, edit::detach_audio(picture, fx.audio, fx.editor.new_clip_id())) to be falsy + ✓ ok(fx, overwrite_music(fx.audio, fx.editor.new_clip_id(), 5)) to be truthy + ✓ ok(fx, edit::detach_audio(video, fx.audio, fx.editor.new_clip_id())) to be falsy + ✓ ok(fx, edit::detach_audio(video, fx.video, fx.editor.new_clip_id())) to be falsy + ✓ fx.editor.undo().has_value() to be truthy + ✓ ok(fx, edit::detach_audio(video, fx.audio, fx.editor.new_clip_id())) to be truthy + ✓ ok(fx, edit::detach_audio(video, fx.audio, fx.editor.new_clip_id())) to be falsy + keeps the detached state when the video clip is split + ✓ ok(fx, edit::detach_audio(video, fx.audio, fx.editor.new_clip_id())) to be truthy + ✓ ok(fx, edit::split(video, f(10))) to be truthy + ✓ fx.editor.timeline().find_clip(clip_at(fx, 20))->audio_detached to be truthy + +● timeline evaluation + is empty where nothing plays + ✓ c.video.empty() && c.audio.empty() to be truthy + maps timeline time to media time through the source in + ✓ c.video.size() to equal 1U + ✓ layer_frame(c, 0) to equal 55LL + ✓ c.video[0].media_time.timebase() == q(1, 90000) to be truthy + stacks video tracks bottom first and skips hidden tracks + ✓ c.video.size() to equal 2U + ✓ c.video[0].clip == base && c.video[1].clip == top to be truthy + ✓ fx.editor.execute(edit::set_track_flags(fx.overlay, false, true)).has_value() to be truthy + ✓ c.video.size() to equal 1U + ✓ c.video[0].clip == base to be truthy + applies the clip speed + ✓ fx.editor.execute(edit::set_speed(id, q(2, 1), false)).has_value() to be truthy + ✓ layer_frame(at(fx, 10), 0) to equal 60LL + ✓ at(fx, 10).audio.front().speed == q(2, 1) to be truthy + carries the clip's visual properties + ✓ fx.editor.execute(edit::set_video(id, v)).has_value() to be truthy + ✓ at(fx, 0).video[0].video == v to be truthy + plays the audio of video clips and audio tracks unless muted + ✓ fx.editor .execute(edit::overwrite( fx.audio, music, f(0), edit::ClipSource{.media = kMusic, .source_in = oma::RationalTime::make(0, q(1, 48000)).value(), .duration = f(30), .time_map = {}, .video = {}, .audio = {}})) .has_value() to be truthy + ✓ c.audio.size() to equal 2U + ✓ m.clip == music to be truthy + ✓ m.media_time.value() to equal 24000LL + ✓ m.clip_offset == f(15) && m.clip_duration == f(30) to be truthy + ✓ fx.editor.execute(edit::set_audio(cam, muted)).has_value() to be truthy + ✓ fx.editor.execute(edit::set_track_flags(fx.audio, true, false)).has_value() to be truthy + ✓ c.audio.empty() to be truthy + ✓ c.video.size() to equal 1U + shows a still image at any time + ✓ fx.editor .execute(edit::overwrite(fx.overlay, id, f(0), edit::ClipSource{.media = kPicture, .source_in = {}, .duration = f(900), .time_map = {}, .video = {}, .audio = {}})) .has_value() to be truthy + ✓ c.video.size() == 1U && c.audio.empty() to be truthy + rejects a time off the sequence grid + ✓ evaluate(fx.editor.timeline(), half).has_value() to be falsy + +● timeline transitions + dissolves across the cut, both clips playing past it + ✓ at(fx, 24).video.size() to equal 1U + ✓ early.video.size() to equal 2U + ✓ layer_frame(early, 0) to equal 27LL + ✓ layer_frame(early, 1) to equal 97LL + ✓ near(early.video[0].opacity, 1.0) && near(early.video[1].opacity, 0.2) to be truthy + ✓ layer_frame(late, 0) to equal 34LL + ✓ layer_frame(late, 1) to equal 104LL + ✓ near(late.video[1].opacity, 0.9) to be truthy + ✓ at(fx, 35).video.size() to equal 1U + dips through black and wipes from the left + ✓ out.video.size() to equal 1U + ✓ layer_frame(out, 0) to equal 27LL + ✓ near(out.video[0].opacity, 0.6) to be truthy + ✓ in.video.size() to equal 1U + ✓ layer_frame(in, 0) to equal 103LL + ✓ near(in.video[0].opacity, 0.6) to be truthy + ✓ half.video.size() to equal 2U + ✓ near(half.video[1].reveal, 0.5) && near(half.video[1].opacity, 1.0) to be truthy + shortens to the media the clips have to spare + ✓ at(fx, 28).video.size() to equal 1U + ✓ c.video.size() to equal 2U + ✓ layer_frame(c, 1) to equal 1LL + ✓ near(c.video[1].opacity, 0.25) to be truthy + ✓ at(fx, 32).video.size() to equal 1U + is a plain cut without a clip ending at the start + ✓ fx.editor .execute(edit::set_transition( b, Transition{.kind = TransitionKind::Dissolve, .duration = f(10)})) .has_value() to be truthy + ✓ at(fx, 31).video.size() to equal 1U + ✓ transition_window(fx.editor.timeline(), track, 1).has_value() to be falsy + rejects empty transitions and keeps them off new cuts + ✓ fx.editor .execute(edit::set_transition( b, Transition{.kind = TransitionKind::Dissolve, .duration = f(0)})) .has_value() to be falsy + ✓ fx.editor.execute(edit::split(b, f(45))).has_value() to be truthy + ✓ fx.editor.timeline().clip_at(fx.video, 50)->transition_in.has_value() to be falsy + ✓ fx.editor.timeline().find_clip(b)->transition_in.has_value() to be truthy + ✓ fx.editor.execute(edit::set_transition(b, std::nullopt)).has_value() to be truthy + ✓ at(fx, 31).video.size() to equal 1U + ✓ fx.editor.undo().has_value() to be truthy + ✓ at(fx, 31).video.size() to equal 2U + +● timeline keyframes + interpolates the transform between keys and holds it outside them + ✓ near(x_at(fx, 0), 0.0) to be truthy + ✓ near(x_at(fx, 10), 25.0) to be truthy + ✓ near(x_at(fx, 50), 100.0) to be truthy + ✓ near(half.scale_x, 2.0) && near(half.scale_y, 2.0) to be truthy + ✓ at(fx, 20).video.at(0).video.transform_keys.empty() to be truthy + eases and holds + ✓ near(x_at(eased, 10), 100.0 * 0.15625) to be truthy + ✓ near(x_at(eased, 20), 50.0) to be truthy + ✓ near(x_at(held, 39), 0.0) && near(x_at(held, 40), 100.0) to be truthy + keeps the motion on the picture through split, trim and slip + ✓ fx.editor.execute(edit::split(id, f(20))).has_value() to be truthy + ✓ near(x_at(fx, 30), before) to be truthy + ✓ fx.editor.execute(edit::trim_start(id, f(10), false)).has_value() to be truthy + ✓ near(x_at(fx, 10), 25.0) to be truthy + ✓ fx.editor.execute(edit::slip(id, f(8))).has_value() to be truthy + ✓ near(x_at(fx, 10), 45.0) to be truthy + rejects keys out of order or with an invalid transform + ✓ fx.editor.execute(edit::set_video(id, v)).has_value() to be falsy + ✓ fx.editor.execute(edit::set_video(id, v)).has_value() to be falsy + +Test Suites Summary: + All 292 tests passed! + + +== playback_tests (debug) + +● playback::TimelineAudio + plays a clip's audio only inside the clip + ✓ place(seq, 4800, 0, 24000).valid() to be truthy + ✓ out.empty() to be falsy + ✓ peak(out, 0, 4800) to equal 0.0F + ✓ near_tone(peak(out, 4800, 28800), 1.0F) to be truthy + ✓ peak(out, 28800, 48000) to equal 0.0F + applies the clip's gain and mute + ✓ place(seq, 0, 0, 24000, with_gain(0.5F)).valid() to be truthy + ✓ place(seq, 24000, 0, 24000, muted()).valid() to be truthy + ✓ near_tone(peak(out, 0, 24000), 0.5F) to be truthy + ✓ peak(out, 24000, 48000) to equal 0.0F + plays a split clip exactly like the unsplit clip + ✓ place(whole, 0, 0, 48000).valid() to be truthy + ✓ place(split, 0, 0, 20000).valid() to be truthy + ✓ place(split, 20000, 18375, 28000).valid() to be truthy + ✓ a.size() == b.size() && !a.empty() to be truthy + ✓ a == b to be truthy + plays detached sound exactly like the video clip's own + ✓ place_camera(joined, 4800).valid() to be truthy + ✓ detached.editor .execute(tl::edit::detach_audio(video, detached.audio, detached.editor.new_clip_id())) .has_value() to be truthy + ✓ peak(a, 4800, 52800) > 0.05F to be truthy + ✓ a == b to be truthy + equalizes a clip's sound + ✓ place_noisy(flat).valid() to be truthy + ✓ place_noisy(cut, mid_cut()).valid() to be truthy + ✓ drop > 3.0 && drop < 12.0 to be truthy + reduces steady noise when asked + ✓ place_noisy(plain).valid() to be truthy + ✓ place_noisy(clean, denoised()).valid() to be truthy + ✓ level_db(a, 24000, 48000) - level_db(b, 24000, 48000) > 15.0 to be truthy + ✓ std::abs(level_db(a, 96000, 144000) - level_db(b, 96000, 144000)) < 1.0 to be truthy + crossfades sound across a transition, both clips playing past the cut + ✓ peak(outgoing, 24000, 28000) > 0.01F to be truthy + ✓ peak(outgoing, 28800, 48000) to equal 0.0F + ✓ near_tone(peak(outgoing, 0, 19000), 1.0F) to be truthy + ✓ peak(incoming, 0, 19200) to equal 0.0F + ✓ peak(incoming, 20000, 24000) > 0.01F to be truthy + ✓ near_tone(peak(incoming, 29000, 48000), 1.0F) to be truthy + renders the same samples from a later start as in one pass + ✓ place(seq, 0, 0, 48000).valid() to be truthy + ✓ worst < 0.02F to be truthy + +● playback::compute_waveform + keeps one peak per hundredth of a second + ✓ w.has_value() to be truthy + ✓ w->sample_rate to equal 44100 + ✓ w->bucket_frames to equal 441LL + ✓ static_cast(w->peaks.size()) to equal 200LL + ✓ range.min > 0.12F && range.max < 0.13F to be truthy + answers peaks over a time range for drawing + ✓ w.has_value() to be truthy + ✓ w->peak_between(0.5, 0.6) > 0.12F to be truthy + ✓ w->peak_between(2.5, 3.0) to equal 0.0F + ✓ w->peak_between(0.6, 0.5) to equal 0.0F + estimates the noise floor from the quietest buckets + ✓ w.has_value() to be truthy + ✓ floor.has_value() to be truthy + noise floor -38.9 dB + ✓ floor && std::abs(*floor + 38.7F) < 2.0F to be truthy + ✓ w->noise_floor_db(1.0, 1.0).has_value() to be falsy + stops when the job is cancelled + ✓ w.has_value() to be falsy + ✓ !w && w.error().code() == oma::ErrorCode::Cancelled to be truthy + fails on files without audio + ✓ waveform_of("still.png").has_value() to be falsy + +Test Suites Summary: + All 49 tests passed! + + +== project_tests (debug) + +● project::Document + round-trips every saved field exactly + ✓ text.has_value() to be truthy + ✓ back.has_value() to be truthy + ✓ *oma::project::to_json(*back, dir) to equal *text + ✓ t.tracks().size() to equal 2U + ✓ t.tracks()[0].clips.size() to equal 2U + ✓ a.video == doc.timeline->tracks()[0].clips[0].video to be truthy + ✓ a.audio == doc.timeline->tracks()[0].clips[0].audio to be truthy + ✓ a.audio_detached to be truthy + ✓ t.tracks()[0].clips[1].transition_in.has_value() to be truthy + ✓ t.markers()[0].name to equal std::string("Intro, \"take 2\"\n") + ✓ back->media[0].path.string() to equal std::string("/projects/vlog/media/clip one.mp4") + ✓ back->media[0].fingerprint == doc.media[0].fingerprint to be truthy + ✓ static_cast(back->canvas_height) to equal 1920 + ✓ text->find("\"path\": \"media/clip one.mp4\"") != std::string::npos to be truthy + continues IDs after the saved ones + ✓ ed.new_clip_id().value() > largest to be truthy + refuses newer versions and keeps unknown fields + ✓ !r && r.error().code() == oma::ErrorCode::Unsupported to be truthy + ✓ doc.has_value() to be truthy + ✓ again->find(R"("future": {"a":[1,2.5,"x"]})") != std::string::npos to be truthy + rejects truncated, mistyped and inconsistent files + ✓ rejected(good.substr(0, good.size() / 2)) to be truthy + ✓ rejected("[]") to be truthy + ✓ rejected(R"({"format": "something else", "format_version": 1})") to be truthy + ✓ rejected(replace("\"fit\": \"fit\"", "\"fit\": \"zoom\"")) to be truthy + ✓ rejected(replace("\"timebase\": \"1/30\"", "\"timebase\": \"1/0\"")) to be truthy + ✓ rejected(replace("\"media\": 7", "\"media\": 8")) to be truthy + ✓ rejected(replace("\"start\": {\n \"value\": 40,", "\"start\": {\n \"value\": 20,")) to be truthy + ✓ rejected(deep + std::string(100, ']')) to be truthy + saves atomically and leaves the old file on failure + ✓ oma::project::save(doc, file).has_value() to be truthy + ✓ loaded.has_value() to be truthy + ✓ oma::project::save(changed, file).has_value() to be truthy + ✓ std::distance(fs::directory_iterator(dir), fs::directory_iterator()) to equal 1L + ✓ refused to be truthy + ✓ read_file(file) != first && read_file(file).find("\"width\": 1280") != std::string::npos to be truthy + finds media next to a moved project + ✓ oma::project::save(doc, root / "before" / "vlog.omamovie").has_value() to be truthy + ✓ loaded.has_value() to be truthy + ✓ loaded->media[0].path == (root / "after" / "media" / "clip one.mp4") to be truthy + fingerprints files + ✓ a && b && c to be truthy + ✓ *a == *c && !(*a == *b) to be truthy + ✓ oma::project::fingerprint_file(dir / "missing").has_value() to be falsy + +Test Suites Summary: + All 38 tests passed! diff --git a/Docs/Research/evidence/2026-10-04-s3-decode-paths.txt b/Docs/Research/evidence/2026-10-04-s3-decode-paths.txt new file mode 100644 index 0000000..4f3dd4e --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-s3-decode-paths.txt @@ -0,0 +1,42 @@ +== Machine + deviceName = Intel(R) Iris(R) Xe Graphics (TGL GT2) + driverInfo = Mesa 26.2.2-arch1.1 + deviceName = llvmpipe (LLVM 22.1.8, 256 bits) + driverInfo = Mesa 26.2.2-arch1.1 (LLVM 22.1.8) + Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.2.4 () + ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers + CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads + runs=5, 10s 1080p60 (600 frames) + +== Test media + generated in + +== Decode throughput (median of 5; frames discarded on the GPU) + h264.mp4 software 792 fps 568% CPU n/a J + h264.mp4 vaapi 715 fps 24% CPU n/a J + h264.mp4 qsv 664 fps 17% CPU n/a J + h264.mp4 vulkan+flag 729 fps 23% CPU n/a J + hevc10.mp4 software 676 fps 615% CPU n/a J + hevc10.mp4 vaapi 1255 fps 52% CPU n/a J + hevc10.mp4 qsv 1147 fps 28% CPU n/a J + hevc10.mp4 vulkan+flag 1258 fps 61% CPU n/a J + av1.mkv software 566 fps 241% CPU n/a J + av1.mkv vaapi 1085 fps 28% CPU n/a J + av1.mkv qsv 998 fps 27% CPU n/a J + av1.mkv vulkan+flag fallback (yuv420p) + +== Proxy intermediates (from h264.mp4: ProRes LT 4:2:2 10-bit, FFv1 4:2:0 8-bit level 4) + prores_ks_vulkan 1080p output does NOT decode + proxy_prores.mov 96.9 Mbit/s, PSNR 46.450642 dB vs source + proxy_prores.mov software 617 fps 612% CPU n/a J + proxy_prores.mov vulkan 240 fps 27% CPU n/a J + proxy_ffv1.mkv 83.5 Mbit/s, PSNR inf dB vs source + proxy_ffv1.mkv software 97 fps 638% CPU n/a J + proxy_ffv1.mkv vulkan 19 fps 3% CPU n/a J + +== Open + first frame vs. seek to the middle + one frame (median of 5, ms, software) + h264.mp4 start 95 ms middle 162 ms + hevc10.mp4 start 112 ms middle 298 ms + av1.mkv start 69 ms middle 211 ms + proxy_prores.mov start 74 ms middle 86 ms + proxy_ffv1.mkv start 224 ms middle 554 ms diff --git a/Docs/Research/evidence/2026-10-04-s5-minimal-compositing.txt b/Docs/Research/evidence/2026-10-04-s5-minimal-compositing.txt new file mode 100644 index 0000000..187eeda --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-s5-minimal-compositing.txt @@ -0,0 +1,51 @@ +S5 raw output (2026-10-04, release build, Iris Xe, Mesa 26.2.2, FFmpeg n9.0.1). Inputs from tools/spikes/s3-decode-paths.sh (h264.mp4, hevc10.mp4: 1080p60 testsrc2) and a 1920x1080 testsrc2 PNG. Two runs per path. +-- run 1, software + input 0: 1920x1080, path software + input 1: 1920x1080, path software + input 2: 1920x1080, path software + decode A + B p50 0.09 p95 0.12 p99 0.14 max 46.09 ms + composite (3 layers) p50 9.21 p95 20.05 p99 21.86 max 22.64 ms + decode + composite p50 9.31 p95 20.20 p99 22.07 max 60.23 ms + frames over 16.67 ms: 37 of 600 +-- run 1, hardware + input 0: 1920x1080, path VA-API to Vulkan + input 1: 1920x1080, path VA-API to Vulkan + input 2: 1920x1080, path software + decode A + B p50 3.05 p95 3.49 p99 3.82 max 8.54 ms + composite (3 layers) p50 5.52 p95 6.67 p99 6.95 max 18.96 ms + decode + composite p50 8.23 p95 9.61 p99 9.93 max 21.23 ms + frames over 16.67 ms: 3 of 600 +-- run 2, software + input 0: 1920x1080, path software + input 1: 1920x1080, path software + input 2: 1920x1080, path software + decode A + B p50 0.08 p95 0.11 p99 0.14 max 30.64 ms + composite (3 layers) p50 9.04 p95 10.50 p99 21.26 max 22.66 ms + decode + composite p50 9.13 p95 10.59 p99 21.52 max 40.33 ms + frames over 16.67 ms: 22 of 600 +-- run 2, hardware + input 0: 1920x1080, path VA-API to Vulkan + input 1: 1920x1080, path VA-API to Vulkan + input 2: 1920x1080, path software + decode A + B p50 3.06 p95 3.85 p99 4.40 max 9.93 ms + composite (3 layers) p50 5.48 p95 7.06 p99 7.47 max 18.37 ms + decode + composite p50 8.31 p95 9.95 p99 12.27 max 21.44 ms + frames over 16.67 ms: 4 of 600 + +== AV1 (added 2026-10-04 for the M2 done criterion): two av1.mkv streams (1080p60, SVT-AV1) + the PNG, hardware, two runs +-- run 1 + input 0: 1920x1080, path VA-API to Vulkan + input 1: 1920x1080, path VA-API to Vulkan + input 2: 1920x1080, path software + decode A + B p50 2.15 p95 10.51 p99 11.66 max 12.67 ms + composite (3 layers) p50 5.10 p95 5.31 p99 5.44 max 5.70 ms + decode + composite p50 7.16 p95 15.65 p99 16.81 max 17.86 ms + frames over 16.67 ms: 10 of 600 +-- run 2 + input 0: 1920x1080, path VA-API to Vulkan + input 1: 1920x1080, path VA-API to Vulkan + input 2: 1920x1080, path software + decode A + B p50 2.12 p95 10.48 p99 11.54 max 12.15 ms + composite (3 layers) p50 5.06 p95 5.25 p99 5.41 max 5.55 ms + decode + composite p50 7.09 p95 15.57 p99 16.54 max 17.11 ms + frames over 16.67 ms: 5 of 600 diff --git a/Docs/Research/evidence/2026-10-04-s6-libplacebo.txt b/Docs/Research/evidence/2026-10-04-s6-libplacebo.txt new file mode 100644 index 0000000..1257b50 --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-s6-libplacebo.txt @@ -0,0 +1,25 @@ +S6 raw output (2026-10-04, release build, Iris Xe, Mesa 26.2.2, libplacebo 7.360.1, FFmpeg n9.0.1). Input: h264.mp4 from tools/spikes/s3-decode-paths.sh. Two runs; a third run under VK_LAYER_KHRONOS_validation reported only FFmpeg's known VA-API mapping leak at vkDestroyDevice (ADR-0004). +== 1. pl_vulkan_import on OmaMovie's device (7 device extensions): OK +== 2. SDR display encode of the 1920x1080 RGBA16F compositor output (median of 20) + compositor encode_display 0.58 ms + libplacebo (no dither) 0.85 ms + max difference 4 of 255, 1346525 of 8294400 samples differ + vs the sRGB formula: compositor 1, libplacebo 4 levels at most +== 3. VA-API frame: 2 image(s), formats 9/16 + YUV->RGB + 1920x1080 -> 1280x720 linear RGBA16F (median of 20) + libplacebo fast 0.60 ms + libplacebo default 3.18 ms + libplacebo high quality 7.22 ms + compositor 0.89 ms (bilinear, includes its own output clear) +== 1. pl_vulkan_import on OmaMovie's device (7 device extensions): OK +== 2. SDR display encode of the 1920x1080 RGBA16F compositor output (median of 20) + compositor encode_display 0.56 ms + libplacebo (no dither) 1.80 ms + max difference 4 of 255, 1346525 of 8294400 samples differ + vs the sRGB formula: compositor 1, libplacebo 4 levels at most +== 3. VA-API frame: 2 image(s), formats 9/16 + YUV->RGB + 1920x1080 -> 1280x720 linear RGBA16F (median of 20) + libplacebo fast 0.89 ms + libplacebo default 2.77 ms + libplacebo high quality 7.17 ms + compositor 0.96 ms (bilinear, includes its own output clear) diff --git a/Docs/Research/evidence/2026-10-04-verification.md b/Docs/Research/evidence/2026-10-04-verification.md new file mode 100644 index 0000000..ae5077b --- /dev/null +++ b/Docs/Research/evidence/2026-10-04-verification.md @@ -0,0 +1,20 @@ +# Evidence recheck — 2026-10-04 + +This is a bounded recheck of local evidence, not a rerun of the S3/S5 or GPU-effects benchmarks. + +## Reproduced + +- `python3 Docs/Research/evidence/2026-10-04-grading-numerics.py` with NumPy 2.5.3 exited 0. Every printed value matched section 2 of [gpu-effects.txt](2026-10-04-gpu-effects.txt) to the displayed precision: LGG/CDL `6.43e-15`, steep-curve table errors `2.25e-03` (256) and `1.58e-04` (1024), 33³ tetrahedral LUT maximum error `2.12e-02`, and zero reported grey-axis spread. These are synthetic numerical checks; they are not an independent color reference. +- Independently recomputed the capacity arithmetic in [2026-10-03-calculations.txt](2026-10-03-calculations.txt) using Python's standard library: 4K RGBA16F is `63.28125 MiB`, one full-frame transfer at 60 fps is `3.981312 GB/s`, and three streams with eight frames each occupy `1518.75 MiB`, excluding other allocations. +- `make test` in the current debug tree exited 0. The [complete output](2026-10-04-make-test.txt) contains the eight suite summaries: base 118, gpu 41, media 652, compositor 164, audio 89, timeline 292, playback 49, project 38 Cest-reported checks passed. One compositor hardware-decode branch printed `(skipped: no hardware decode here)`; a green suite is not validation of that path. The first attempted rerun exited 2 because `compositor_tests` was temporarily non-executable during a rebuild; each test binary then exited 0 individually, and the final `make test` passed. + +## Documentary checks and limits + +- Rechecked the Q1 source-level premise against the [Vulkan `vkGetDeviceQueue` reference](https://docs.vulkan.org/refpages/latest/refpages/source/vkGetDeviceQueue.html) (Valid Usage, `flags-01841`, accessed 2026-10-04) and [Qt 6.11.2 `qrhivulkan.cpp`](https://raw.githubusercontent.com/qt/qtbase/v6.11.2/src/gui/rhi/qrhivulkan.cpp) (imported-device branch, lines 832–862, accessed 2026-10-04): the former requires a zero-flag queue, and the latter calls `vkGetDeviceQueue` for an imported device. This corroborates the historical mismatch in the skeptical review; it does not establish what patches the installed Qt binary contains or validate concurrent live playback. +- [S3's method](../../spikes/S3-decode-paths.md) had said SVT-AV1 preset 11; [its script](../../../tools/spikes/s3-decode-paths.sh) uses preset 12. The method was corrected to 12. The S3 throughput, CPU, seek, PSNR and fallback results were **not rerun**. Its saved output reports summary statistics, not individual trial timings; the input media is not retained here. +- [S5's results](2026-10-04-s5-minimal-compositing.txt) report two runs per path, with a reproducible harness but no retained per-frame timings or input media. In the recorded hardware runs, 3 and 4 of 600 sequential decode-plus-composite iterations exceeded 16.67 ms. The harness does not measure Qt presentation, audio or the viewer scheduler. These results support an S5 library pilot, not an end-to-end 1080p60 playback claim. +- The [GPU-effects benchmark](2026-10-04-compositor-bench.cpp) times synchronous compositor rendering of one decoded frame. The numerical recheck does not reproduce its GPU timing, nor establish AMD/NVIDIA behavior or independent color accuracy. + +## Next discriminating check + +Measure 1080p30/60 **new-frame time at Qt presentation** for the same declared media and scene, recording the negotiated decode path, dropped/repeated frames, p50/p95/p99/max, A/V drift and the render-thread stalls over a sustained run. Compare software decode/upload with the admitted hardware path on the same output. This is the M4 gate needed before choosing a viewer default or claiming real-time playback; isolated S3/S5 throughput cannot decide it. diff --git a/Docs/Research/evidence/2026-10-05-m4-av-drift.txt b/Docs/Research/evidence/2026-10-05-m4-av-drift.txt new file mode 100644 index 0000000..d94e0de --- /dev/null +++ b/Docs/Research/evidence/2026-10-05-m4-av-drift.txt @@ -0,0 +1,49 @@ +M4 10-minute A/V drift audit (2026-10-05) + +Machine: Intel Iris Xe (TigerLake), Mesa 26.2.2; environment below. Build: BUILD=release, +working tree on top of the commit shown (uncommitted M3/M4 work, including decoder reuse +across playback restarts). +Command: build/release/omamovie --m4-audit drift_1080p30.mp4 600 +Source (generated, not committed, 1.2 GB): + ffmpeg -f lavfi -i "testsrc2=size=1920x1080:rate=30,format=yuv420p" \ + -f lavfi -i "sine=frequency=440:sample_rate=48000" -t 620 \ + -c:v libx264 -preset ultrafast -g 60 -c:a aac -b:a 128k drift_1080p30.mp4 +Path: software decode + upload (default viewer), PipeWire output muted at the device. +Error = audible sample time - time of the last composited frame, sampled every 10 ms after +2 s; drift = |mean error of the first minute - mean error of the last minute|. Composition +time precedes Qt's presentation, so presentation latency is not included. + +Environment: +Mon Oct 5 09:37:48 PM -03 2026 +7.2.5-4-omarchy +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +Server Name: PulseAudio (on PipeWire 1.6.8) +980dcbe + +Result (one run): +M4 audit: PASS, 600 s, PipeWire audio, 58807 samples, 17996 composites, p99 33.33 ms, max 33.33 ms, first/last mean delta 2.23 ms, signed range -33.33..20.00 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms + +Seek restart latency (2026-10-05, same machine and source, BUILD=release) +Command: build/release/omamovie --m4-seek-audit drift_1080p30.mp4 60 +Plays, then every 500 ms seeks to a pseudo-random position (fixed seed, same positions in +every run). "UI blocked" is Session::startPlayback's duration on the UI thread; "first +composited frame" runs from the seek to the first composited frame within 30 frames after the +target (composition, not presentation). GOP is 60 frames, so a seek decodes up to 2 s. +Two runs each; no noise control beyond that. + +Decoders reused across restarts (current tree): +M4 seek audit: 60 seeks, PipeWire audio, UI blocked p50 16.18 p95 23.83 max 24.09 ms, first composited frame p50 77.25 p95 127.82 max 141.91 ms, 0 without a frame in 500 ms +M4 seek audit: 60 seeks, PipeWire audio, UI blocked p50 15.94 p95 23.80 max 26.20 ms, first composited frame p50 79.38 p95 117.36 max 145.27 ms, 0 without a frame in 500 ms + +Baseline, decoders reopened on every restart (video_scheduler/audio_player at HEAD 980dcbe): +M4 seek audit: 60 seeks, PipeWire audio, UI blocked p50 29.77 p95 39.02 max 40.27 ms, first composited frame p50 81.67 p95 110.41 max 116.69 ms, 0 without a frame in 500 ms +M4 seek audit: 60 seeks, PipeWire audio, UI blocked p50 31.08 p95 39.94 max 41.08 ms, first composited frame p50 79.95 p95 104.19 max 106.34 ms, 0 without a frame in 500 ms + +Restart blocking broken down (2026-10-06, h264_1080p60.mp4 from the hardware gate, hardware +decode, 31 seeks, temporary probe): audio stop 12.0 ms mean (max 25.4), scheduler stop +1.0 ms, audio start 2.1 ms. The audio stop waited for PipeWire's next callback (a quantum, +~21 ms) to flush the ring. The flush is now asynchronous: it records the ring's write position +and the consumer drops frames up to it at its next pull, keeping what the restart writes. +After the change (two runs of --m4-seek-audit h264_1080p60.mp4 40): +M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 2.39 p95 6.10 max 6.54 ms, first composited frame p50 124.31 p95 255.32 max 276.76 ms, 0 without a frame in 500 ms +M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 3.55 p95 8.12 max 8.66 ms, first composited frame p50 124.88 p95 270.54 max 275.28 ms, 0 without a frame in 500 ms diff --git a/Docs/Research/evidence/2026-10-06-m4-hardware-gate.txt b/Docs/Research/evidence/2026-10-06-m4-hardware-gate.txt new file mode 100644 index 0000000..784547e --- /dev/null +++ b/Docs/Research/evidence/2026-10-06-m4-hardware-gate.txt @@ -0,0 +1,120 @@ +M4 hardware decode pilot gate, first full run (2026-10-06) + +Machine: Intel Iris Xe (TigerLake), Mesa 26.2.2, FFmpeg 9.0.1, PipeWire 1.6.8, eDP-1 +1920x1080 @ 60 Hz (no VRR). BUILD=release, working tree after the own VA-API DMA-BUF import +(ADR-0004 amendment). Hardware path: VA-API decode imported into Vulkan, decoded on the +scheduler thread under ADR-0005 admission. Software path: FFmpeg CPU decode + one upload. +Sources (synthetic, 70 s, generated in the scratchpad, not committed): + testsrc2 + 440 Hz sine; H.264 1080p60 (x264 ultrafast, GOP 120), HEVC 10-bit 1080p60 + (x265 ultrafast, GOP 120), AV1 1080p60 (SVT-AV1 preset 12 -> M11, GOP 120), + H.264 2160p30 (x264 ultrafast, GOP 60). +Per file and path: two `--m4-audit FILE 60` runs and one `--m4-seek-audit FILE 40`. +The audit's error is audible time minus the last composited frame (composition, not Qt's +presentation); the pass rule is p99 <= one frame interval, no underruns (and drift for >= 120 s). + +Results (lines as printed, PipeWire output muted): +h264_1080p60.mp4 software run1: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5650 samples, 2808 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 787, frame interval 16.67 ms +h264_1080p60.mp4 software run2: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5656 samples, 2808 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 788, frame interval 16.67 ms +h264_1080p60.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 12.63 p95 24.30 max 24.81 ms, first composited frame p50 80.15 p95 179.48 max 194.35 ms, 0 without a frame in 500 ms +h264_1080p60.mp4 hardware run1: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5801 samples, 2810 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 788, frame interval 16.67 ms +h264_1080p60.mp4 hardware run2: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5797 samples, 2807 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 788, frame interval 16.67 ms +h264_1080p60.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 14.82 p95 24.49 max 25.15 ms, first composited frame p50 128.38 p95 277.86 max 285.76 ms, 0 without a frame in 500 ms +hevc10_1080p60.mp4 software run1: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5593 samples, 2806 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 787, frame interval 16.67 ms +hevc10_1080p60.mp4 software run2: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5602 samples, 2805 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 789, frame interval 16.67 ms +hevc10_1080p60.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 19.81 p95 24.52 max 25.91 ms, first composited frame p50 145.38 p95 225.58 max 241.80 ms, 0 without a frame in 500 ms +hevc10_1080p60.mp4 hardware run1: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5800 samples, 2809 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 787, frame interval 16.67 ms +hevc10_1080p60.mp4 hardware run2: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5795 samples, 2809 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 787, frame interval 16.67 ms +hevc10_1080p60.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 13.59 p95 25.35 max 26.26 ms, first composited frame p50 100.10 p95 167.57 max 175.54 ms, 0 without a frame in 500 ms +av1_1080p60.mkv software run1: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5648 samples, 2808 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 789, frame interval 16.67 ms +av1_1080p60.mkv software run2: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5630 samples, 2808 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 789, frame interval 16.67 ms +av1_1080p60.mkv software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 15.26 p95 24.23 max 37.58 ms, first composited frame p50 199.16 p95 342.54 max 356.15 ms, 0 without a frame in 500 ms +av1_1080p60.mkv hardware run1: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5793 samples, 2804 composites, p99 20.67 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 794, frame interval 16.67 ms +av1_1080p60.mkv hardware run2: M4 audit: FAIL, 60 s, hardware pilot decode, PipeWire audio, 5793 samples, 2806 composites, p99 20.00 ms, max 20.67 ms, first/last mean delta 0.00 ms, signed range -16.67..20.67 ms, underruns 0 (first -1.00 s), dropped video 790, frame interval 16.67 ms +av1_1080p60.mkv hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 18.01 p95 24.98 max 26.37 ms, first composited frame p50 121.49 p95 221.48 max 226.49 ms, 0 without a frame in 500 ms +h264_2160p30.mp4 software run1: M4 audit: PASS, 60 s, software decode, PipeWire audio, 4181 samples, 1798 composites, p99 32.00 ms, max 33.33 ms, first/last mean delta 0.00 ms, signed range -33.33..20.00 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms +h264_2160p30.mp4 software run2: M4 audit: PASS, 60 s, software decode, PipeWire audio, 4197 samples, 1794 composites, p99 32.00 ms, max 33.33 ms, first/last mean delta 0.00 ms, signed range -33.33..22.67 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 33.33 ms +h264_2160p30.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 14.05 p95 23.82 max 26.13 ms, first composited frame p50 148.94 p95 220.93 max 222.07 ms, 0 without a frame in 500 ms +h264_2160p30.mp4 hardware run1: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5402 samples, 1801 composites, p99 33.33 ms, max 33.33 ms, first/last mean delta 0.00 ms, signed range -33.33..20.00 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms +h264_2160p30.mp4 hardware run2: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5371 samples, 1799 composites, p99 33.33 ms, max 33.33 ms, first/last mean delta 0.00 ms, signed range -33.33..20.00 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 33.33 ms +h264_2160p30.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 16.81 p95 25.21 max 26.00 ms, first composited frame p50 205.77 p95 334.77 max 355.05 ms, 0 without a frame in 500 ms + +Finding from the first run: every codec and both paths composited ~2808 of 3600 frames at +1080p60 (~47 fps on a 60 Hz panel), so decode was not the limit. Per-stage timing added to +the audit (`M4 audit stages/UI/Qt frame` lines) showed composites of 3.5 ms (hardware) and +8 ms (software), Qt frames of 4.7 ms and UI ticks every 8 ms, but composites only every +~23 ms: the audio clock advanced only at PipeWire callbacks (about 21 ms of audio each), so +video following it jumped one or two frames per step. PipeWireOutput::frames_played now +interpolates between callbacks with the steady clock, capped at one quantum. + +Second run (2026-10-06, same machine and files, interpolated clock): +h264_1080p60.mp4 software run1: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5743 samples, 3558 composites, p99 17.21 ms, max 22.96 ms, first/last mean delta 0.00 ms, signed range -8.44..22.96 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 16.67 ms +h264_1080p60.mp4 software run2: M4 audit: PASS, 60 s, software decode, PipeWire audio, 5766 samples, 3585 composites, p99 9.00 ms, max 23.40 ms, first/last mean delta 0.00 ms, signed range -8.83..23.40 ms, underruns 0 (first -1.00 s), dropped video 4, frame interval 16.67 ms +h264_1080p60.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 15.46 p95 24.90 max 25.18 ms, first composited frame p50 87.97 p95 154.36 max 156.95 ms, 0 without a frame in 500 ms +h264_1080p60.mp4 hardware run1: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5800 samples, 3588 composites, p99 9.33 ms, max 9.79 ms, first/last mean delta 0.00 ms, signed range -7.56..9.79 ms, underruns 0 (first -1.00 s), dropped video 5, frame interval 16.67 ms +h264_1080p60.mp4 hardware run2: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5799 samples, 3586 composites, p99 12.37 ms, max 12.77 ms, first/last mean delta 0.00 ms, signed range -12.10..12.77 ms, underruns 0 (first -1.00 s), dropped video 6, frame interval 16.67 ms +h264_1080p60.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 17.91 p95 25.39 max 25.82 ms, first composited frame p50 135.50 p95 255.67 max 277.54 ms, 0 without a frame in 500 ms +hevc10_1080p60.mp4 software run1: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5655 samples, 3479 composites, p99 19.83 ms, max 22.35 ms, first/last mean delta 0.00 ms, signed range -9.65..22.35 ms, underruns 0 (first -1.00 s), dropped video 42, frame interval 16.67 ms +hevc10_1080p60.mp4 software run2: M4 audit: FAIL, 60 s, software decode, PipeWire audio, 5633 samples, 3472 composites, p99 18.50 ms, max 20.29 ms, first/last mean delta 0.00 ms, signed range -9.92..20.29 ms, underruns 0 (first -1.00 s), dropped video 32, frame interval 16.67 ms +hevc10_1080p60.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 15.09 p95 23.94 max 24.51 ms, first composited frame p50 146.64 p95 227.97 max 231.59 ms, 0 without a frame in 500 ms +hevc10_1080p60.mp4 hardware run1: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5777 samples, 3588 composites, p99 15.83 ms, max 16.56 ms, first/last mean delta 0.00 ms, signed range -12.08..16.56 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 16.67 ms +hevc10_1080p60.mp4 hardware run2: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5783 samples, 3571 composites, p99 15.77 ms, max 16.12 ms, first/last mean delta 0.00 ms, signed range -12.44..16.12 ms, underruns 0 (first -1.00 s), dropped video 0, frame interval 16.67 ms +hevc10_1080p60.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 15.67 p95 25.38 max 26.36 ms, first composited frame p50 102.65 p95 163.66 max 170.95 ms, 0 without a frame in 500 ms +av1_1080p60.mkv software run1: M4 audit: PASS, 60 s, software decode, PipeWire audio, 5771 samples, 3576 composites, p99 15.46 ms, max 23.44 ms, first/last mean delta 0.00 ms, signed range -8.04..23.44 ms, underruns 0 (first -1.00 s), dropped video 4, frame interval 16.67 ms +av1_1080p60.mkv software run2: M4 audit: PASS, 60 s, software decode, PipeWire audio, 5772 samples, 3589 composites, p99 11.90 ms, max 12.50 ms, first/last mean delta 0.00 ms, signed range -10.40..12.50 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 16.67 ms +av1_1080p60.mkv software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 14.11 p95 25.31 max 31.64 ms, first composited frame p50 180.76 p95 353.83 max 371.80 ms, 0 without a frame in 500 ms +av1_1080p60.mkv hardware run1: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5787 samples, 3580 composites, p99 8.35 ms, max 20.17 ms, first/last mean delta 0.00 ms, signed range -11.12..20.17 ms, underruns 0 (first -1.00 s), dropped video 8, frame interval 16.67 ms +av1_1080p60.mkv hardware run2: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5794 samples, 3587 composites, p99 7.87 ms, max 22.04 ms, first/last mean delta 0.00 ms, signed range -10.75..22.04 ms, underruns 0 (first -1.00 s), dropped video 8, frame interval 16.67 ms +av1_1080p60.mkv hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 17.64 p95 27.25 max 29.67 ms, first composited frame p50 130.88 p95 220.60 max 222.98 ms, 0 without a frame in 500 ms +h264_2160p30.mp4 software run1: M4 audit: PASS, 60 s, software decode, PipeWire audio, 3875 samples, 1796 composites, p99 15.75 ms, max 16.96 ms, first/last mean delta 0.00 ms, signed range -16.96..16.67 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms +h264_2160p30.mp4 software run2: M4 audit: PASS, 60 s, software decode, PipeWire audio, 3797 samples, 1796 composites, p99 15.54 ms, max 17.10 ms, first/last mean delta 0.00 ms, signed range -17.10..16.42 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms +h264_2160p30.mp4 software seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 13.75 p95 26.31 max 27.03 ms, first composited frame p50 149.70 p95 228.89 max 270.33 ms, 0 without a frame in 500 ms +h264_2160p30.mp4 hardware run1: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5378 samples, 1799 composites, p99 20.81 ms, max 21.67 ms, first/last mean delta 0.00 ms, signed range -21.67..17.83 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 33.33 ms +h264_2160p30.mp4 hardware run2: M4 audit: PASS, 60 s, hardware pilot decode, PipeWire audio, 5312 samples, 1801 composites, p99 20.98 ms, max 21.71 ms, first/last mean delta 0.00 ms, signed range -21.71..17.37 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms +h264_2160p30.mp4 hardware seek: M4 seek audit: 40 seeks, PipeWire audio, UI blocked p50 13.20 p95 24.27 max 26.42 ms, first composited frame p50 207.54 p95 335.80 max 339.04 ms, 0 without a frame in 500 ms +drift_1080p30 hardware 600 s: M4 audit: PASS, 600 s, hardware pilot decode, PipeWire audio, 59800 samples, 18000 composites, p99 27.56 ms, max 29.75 ms, first/last mean delta 0.03 ms, signed range -29.75..16.92 ms, underruns 0 (first -1.00 s), dropped video 0, frame interval 33.33 ms + +Memory (separate 300 s hardware run of drift_1080p30.mp4, editor's VmRSS every 30 s; the +sampling inside the second run measured the 'timeout' process and is discarded): +t=30s VmRSS: 322912 kB +t=60s VmRSS: 322756 kB +t=90s VmRSS: 322784 kB +t=120s VmRSS: 323112 kB +t=150s VmRSS: 322944 kB +t=180s VmRSS: 322936 kB +t=210s VmRSS: 322948 kB +t=240s VmRSS: 323164 kB +t=270s VmRSS: 322984 kB +M4 audit: PASS, 300 s, hardware pilot decode, PipeWire audio, 29795 samples, 8995 composites, p99 27.81 ms, max 29.44 ms, first/last mean delta 0.48 ms, signed range -29.44..16.62 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 33.33 ms + +Decision under the predeclared gate: hardware decode passed every 1080p60 codec (H.264, +10-bit HEVC, AV1: 2 of 2 each), 2160p30 H.264 and the 10-minute 1080p30 run (drift 0.03 ms, no +drops), with stable memory; software failed 10-bit HEVC 1080p60 twice and H.264 1080p60 once. +Hardware decode becomes the viewer default on Intel (the tested driver); other vendors stay on +software until S7/S8. Seek-to-first-frame is slower with hardware for H.264 (p50 136 vs 88 ms) +and 2160p (208 vs 150 ms), faster for HEVC and AV1. Not covered: two-layer scenes, other +GOP structures, hybrid machines. + +Adaptive preview comparison (2026-10-06, software decode forced with OMA_PREVIEW_HARDWARE=0, +40 s audits; "auto" halves the preview resolution for the rest of a playback after more than +2% of the frames due in two seconds are dropped; 0.5 is a fixed half-resolution preview). +H.264 2160p60 (x264 ultrafast, GOP 120, 50 s) was added as an overloaded scene. +hevc10_1080p60.mp4 software full: M4 audit stages: composite p50 8.68 p95 10.49 p99 11.64 ms, interval p50 16.75 p95 19.60 p99 21.98 ms +hevc10_1080p60.mp4 software full: M4 audit: PASS, 40 s, software decode, PipeWire audio, 3743 samples, 2393 composites, p99 8.88 ms, max 12.90 ms, first/last mean delta 0.00 ms, signed range -9.19..12.90 ms, underruns 0 (first -1.00 s), dropped video 0, frame interval 16.67 ms +hevc10_1080p60.mp4 software auto: M4 audit stages: composite p50 8.73 p95 10.53 p99 12.08 ms, interval p50 16.64 p95 19.10 p99 27.32 ms +hevc10_1080p60.mp4 software auto: M4 audit: PASS, 40 s, software decode, PipeWire audio, 3758 samples, 2389 composites, p99 13.85 ms, max 18.17 ms, first/last mean delta 0.00 ms, signed range -10.27..18.17 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 16.67 ms +hevc10_1080p60.mp4 software 0.5: M4 audit stages: composite p50 4.45 p95 5.33 p99 6.04 ms, interval p50 16.64 p95 29.00 p99 30.02 ms +hevc10_1080p60.mp4 software 0.5: M4 audit: PASS, 40 s, software decode, PipeWire audio, 3799 samples, 2390 composites, p99 13.62 ms, max 14.40 ms, first/last mean delta 0.00 ms, signed range -12.71..14.40 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 16.67 ms +h264_2160p60.mp4 software full: M4 audit stages: composite p50 16.50 p95 17.71 p99 18.39 ms, interval p50 17.45 p95 19.16 p99 30.40 ms +h264_2160p60.mp4 software full: M4 audit: FAIL, 40 s, software decode, PipeWire audio, 2197 samples, 2226 composites, p99 22.00 ms, max 25.44 ms, first/last mean delta 0.00 ms, signed range 0.73..25.44 ms, underruns 0 (first -1.00 s), dropped video 104, frame interval 16.67 ms +h264_2160p60.mp4 software auto: 09:57:08.888 INFO playback preview at half resolution: 15 of 135 frames dropped (session.cpp:1738) +h264_2160p60.mp4 software auto: M4 audit stages: composite p50 9.65 p95 15.92 p99 17.55 ms, interval p50 16.05 p95 35.95 p99 39.23 ms +h264_2160p60.mp4 software auto: M4 audit: FAIL, 40 s, software decode, PipeWire audio, 3512 samples, 2254 composites, p99 20.38 ms, max 30.65 ms, first/last mean delta 0.00 ms, signed range -8.27..30.65 ms, underruns 0 (first -1.00 s), dropped video 99, frame interval 16.67 ms +h264_2160p60.mp4 software 0.5: M4 audit stages: composite p50 10.04 p95 12.76 p99 14.88 ms, interval p50 16.76 p95 19.93 p99 34.39 ms +h264_2160p60.mp4 software 0.5: M4 audit: FAIL, 40 s, software decode, PipeWire audio, 3573 samples, 2368 composites, p99 17.00 ms, max 30.35 ms, first/last mean delta 0.00 ms, signed range -8.02..30.35 ms, underruns 0 (first -1.00 s), dropped video 12, frame interval 16.67 ms + +Reading: on 10-bit HEVC 1080p60 every setting passes and auto never triggers. On 2160p60, +full resolution fails and starves the UI thread (2197 audit samples instead of ~3500 in 40 s); +auto triggers after two seconds and restores UI responsiveness (3512 samples), fixed half +composites the most frames (2368); software decode of 2160p60 still cannot keep real time. +Automatic quality became the default: inert when not needed, helpful under overload, logged +when it acts, overridden by OMA_PREVIEW_SCALE=1 (full) or a fixed fraction. diff --git a/Docs/Research/evidence/2026-10-06-m6-long-timeline.txt b/Docs/Research/evidence/2026-10-06-m6-long-timeline.txt new file mode 100644 index 0000000..40a0f1e --- /dev/null +++ b/Docs/Research/evidence/2026-10-06-m6-long-timeline.txt @@ -0,0 +1,45 @@ +M6 long-form timeline interaction (2026-10-06) + +Machine: Intel Iris Xe (TigerLake), Mesa 26.2.2, Qt 6.11, 1600x900 window. BUILD=release. +Command: build/release/omamovie --m6-timeline-audit N (OMA_AUDIT_ZOOM=60 for a working zoom) +The audit imports tests/fixtures/generated/h264_30fps_aac.mp4, saves, builds a storyline of N +clips of 5 frames with the timeline's own commands, saves it with libs/project, opens it in +the editor and times 20 rounds of seek, select, split, ripple delete and undo (two undos per +round), each from the call to the end of the first Qt frame that began after it. Proposed +gate (implementation plan §5): p95 < 100 ms and no routine edit stall > 250 ms at 5,000 clips. + +Before (one delegate per storyline clip, rebuilt from a QVariantList on every edit): + 500 clips: split p50 327 / p95 463, ripple delete p50 401 / p95 575, undo p50 361 / max + 662 ms; RSS 3.7 GB. 2,000 clips ran the machine out of memory (stopped by the system). + Per edit, the C++ side cost 0.4 ms (command) + 1.9 ms (list); QML ~203 ms. + +Steps, each measured: + 1. Incremental model (ClipListModel: keeps rows whose clip ID did not move): 500 clips + split p50 60, ripple 83, undo 68 ms; RSS 424 MB. 2,000 clips: 0.9-1.7 s per action, + render thread busy in the driver. + 2. Level of detail (thumbnail, waveform, label, fades, trim edges only on clips >= 24 px) + and junction markers only near the view and with room: 2,000 clips seek p50 19, + split p50 69 / p95 87, ripple p50 223, undo p95 296 ms. + 3. Whole-list JS conversions removed (actions read the model's count, the minimap paints a + flat [start, duration] list): 5,000 clips split p50 164, ripple p50 520 ms. + 4. The model holds only clips near the view (pages of the view width), and more than 400 + in view draw as one strip (Canvas) with click-to-select: + +5,000 clips, whole sequence fitted (compact strip): + seek p50 5.1 p95 6.5 max 6.5 ms + select p50 9.6 p95 14.5 max 14.5 ms + split p50 22.3 p95 25.3 max 25.3 ms + ripple del p50 14.9 p95 20.2 max 20.2 ms + undo p50 16.5 p95 17.9 max 19.0 ms + RSS 328 MB +5,000 clips, 60 px/s (clip delegates in view): + seek p50 7.5 p95 11.9 max 11.9 ms + select p50 8.6 p95 10.4 max 10.4 ms + split p50 19.9 p95 30.7 max 30.7 ms + ripple del p50 16.2 p95 59.5 max 59.5 ms + undo p50 16.6 p95 29.5 max 59.9 ms + RSS 386 MB + +Not covered: drag/trim gestures and scrolling (only command-driven edits), audio/video lanes +with thousands of clips, a two-hour source, project open/save phases (the "open" figure is +dominated by the reimport and is not a phase breakdown), repeated runs. diff --git a/Docs/Research/evidence/2026-10-07-m7-export.txt b/Docs/Research/evidence/2026-10-07-m7-export.txt new file mode 100644 index 0000000..bf53790 --- /dev/null +++ b/Docs/Research/evidence/2026-10-07-m7-export.txt @@ -0,0 +1,65 @@ +M7 — export speed, picture fidelity and A/V offset (2026-10-07) + +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2, Arch/Omarchy. Build: release. +Tool: build/release/omamovie --export-audit SOURCE OUT (imports SOURCE onto the storyline, +exports it, prints per-phase time). Sources are generated with ffmpeg (lavfi), not committed. + +Speed, 1920x1080 30 fps H.264 + AAC source, 300 frames (10 s), libx264 defaults: + before float readback (RGBA32F) + CPU BT.709 conversion: 19.6 fps + per frame: build 0.17, render+readback 23.24, convert 19.51, encode 5.75, audio 0.97 ms + after BT.709 encoded on the GPU into RGBA8, 8-bit readback, RGBA into swscale: 51.4-52.9 fps + per frame: build 0.20, render+readback 9.1-9.5, convert 0, encode 7.1-7.3, audio 1.1-1.3 ms + (two runs each; the GPU encode matches the BT.709 OETF within one 8-bit level, compositor test) + +Picture fidelity: PSNR of the export against its source (ffmpeg psnr filter, all 300 frames) + source tagged BT.709 (scale=out_color_matrix=bt709, -colorspace bt709, crf 12): + Y 36.3 dB, U 35.5, V 33.8, average 35.7 (libx264 default crf 23 on a busy test pattern) + untagged source encoded by ffmpeg with BT.601: 25.8 dB average, with the hue shift of a + BT.601/BT.709 mismatch: OmaMovie reads untagged HD as BT.709 (the common convention), + ffmpeg had encoded BT.601. A policy question for untagged input, not an export defect. + +A/V offset: 1280x720 29.97 fps source with a one-frame white flash and a 1 kHz beep at 2 s and +5 s (beep onsets quantized by lavfi to 2.0201 s and 5.0156 s). Flash frames found with +signalstats, beep onsets as the first sample above 0.05. + before export beeps 23.2 ms early at both marks, flashes unchanged: one AAC frame at 44.1 kHz. + Cause: AudioDecoder::seek started output after the target (the first packet after a + seek decodes short: AAC priming/MDCT overlap); the mixer trusted the seek's promise and + placed that audio at the target. The same mixer drives playback. + after seek demuxes 200 ms early and trims to the target: export beeps at 2.0201 s and + 5.0156 s, equal to the source; flashes at 2.002 s and 5.005 s in both. + Regression tests: AAC seeks are sample-exact; Opus in Matroska still lands 24 samples + (0.5 ms) late after a seek (open). + +Not measured: long exports (two hours), hardware encoders, export while playing back. + +Two-hour export (2026-10-07) + Source: 320x180 30 fps testsrc2, BT.709-tagged H.264 (ultrafast, GOP 300) + AAC 48 kHz, 7200 s, + with a one-frame white flash and a 50 ms 1 kHz beep at 10 s, 3600 s and 7190 s. + Export: --export-audit to /var/tmp (disk, not tmpfs), automatic encoder (VA-API H.264). + 216,000 frames in 522 s (413.7 fps; 8 min 43 s wall), output 461 MB, + video 216,000 frames / 7200.000 s, AAC 7200.000 s. + Independent check (ffmpeg seeks to each mark, signalstats for the flash, first sample above + 0.05 for the beep), source and export: + mark 10 s: flash 10.0000 beep 10.0000 (both files) + mark 3600 s: flash 3600.0000 beep 3600.0000 (both files) + mark 7190 s: flash 7190.0000 beep 7190.0000 (both files) + No drift over two hours at frame and sample resolution. Not covered: cuts, transitions and + effects along a long timeline, 1080p at this length (~70 min at the measured 52-68 fps). + +Across a cut and a transition (2026-10-07) + Project (built with libs/project): sync.mp4 (29.97 fps, flash+beep at 2 s and 5 s) as clip A + = source [0, 3.003 s) and clip B = source from 3.5 s, placed at 3.003 s, with a 15-frame + dissolve centred on the cut; exported with --export-audit PROJECT. + Expected: A keeps its markers (flash frame 2.002 s, beep 2.0201 s); B maps source t to + 3.003 + (t - 3.5): beep 5.0156 -> 4.5186 s, flash in the frame whose source time first + reaches the source flash frame (5.005 s) -> timeline frame 4.5379 s. + Found: bright frames 2.002 / 2.035 s (the source's two) and 4.5379 s; beeps 2.0201 s and + 4.5186 s. Exact at sample resolution. + Found on the way: exporting right after opening a project rendered gaps (black, silent): + the library re-import had not delivered its results yet. Export now refuses until every + clip's media is loaded ("Wait for the media to finish loading"). + +Effects through export (2026-10-07, ADR-0016) + Project: src709.mp4 as clip A with oma.look.black-and-white and clip B without effects. + Decoded export (ffmpeg signalstats): t = 1 s (clip A) SATAVG 0, U 128, V 128; t = 4.5 s + (clip B) SATAVG 115.6. The stack reaches the exported pixels. diff --git a/Docs/Research/evidence/2026-10-07-m7-kill-recovery.txt b/Docs/Research/evidence/2026-10-07-m7-kill-recovery.txt new file mode 100644 index 0000000..f53350c --- /dev/null +++ b/Docs/Research/evidence/2026-10-07-m7-kill-recovery.txt @@ -0,0 +1,22 @@ +M7 — autosave recovery after the process is killed (2026-10-07) + +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2, Arch/Omarchy. Build: debug. +Isolation: XDG_STATE_HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME and XDG_RUNTIME_DIR in a scratch folder. + +Steps +1. build/debug/omamovie take.mp4 (a copy of tests/fixtures/generated/h264_30fps_aac.mp4) + The file is imported onto the storyline: an unsaved session. +2. Wait 40 s (autosave runs every 30 s with unsaved changes). +3. kill -9 (no shutdown code runs) +4. Inspect $XDG_STATE_HOME/omamovie/autosave/ + +Result +- untitled-.omamovie (3,295 bytes) and its .origin sidecar (empty: the session had no + project file) remained after the kill. +- oma-project validate: valid. oma-project inspect: format_version 4, 1 media, 1 track, 1 clip. +- The media reference holds the absolute path of take.mp4 besides the relative one. +- The GUI smoke already checks that a copy left this way is listed on Projects and restores + as unsaved changes; that listing was not re-checked by hand here. + +Not covered: a kill during the autosave write itself (the write is atomic: temporary file, +fsync, rename, directory fsync), power loss, and kills on other filesystems. diff --git a/Docs/Research/evidence/2026-10-07-m7-project-open-save.txt b/Docs/Research/evidence/2026-10-07-m7-project-open-save.txt new file mode 100644 index 0000000..baf81e9 --- /dev/null +++ b/Docs/Research/evidence/2026-10-07-m7-project-open-save.txt @@ -0,0 +1,29 @@ +M7 — native project save/open cost by phase (2026-10-07) + +Machine: Intel Core (Tiger Lake) laptop with Iris Xe, NVMe, Arch/Omarchy. Build: release +libraries (-O2), GCC, simdjson from Arch. Warm page cache (the file was just written); cold +open was not measured (it needs dropping the page cache as root). + +Workload: one storyline track, N clips of 2 s alternating over 50 media items, each clip with +opacity 0.9 and one look effect (format 4). Built with Timeline::restore, then +project::to_json / save / from_json / load. A scratch program linked against the libraries +(not in the repository); timings are single runs. + +clips file to_json save(atomic,fsync) from_json(parse+DTO+restore) load(all) validate peak RSS + 500 1.2 MB 2.7 ms 2.9 ms 3.3 ms 3.7 ms 0.1 ms 15 MB + 5000 12.1 MB 19.7 ms 21.7 ms 31.4 ms 34.6 ms 1.4 ms 107 MB +20000 48.5 MB 74.6 ms 81.2 ms 116.9 ms 149.1 ms 5.8 ms 368 MB + +Reading: every phase grows linearly with clip count; at the long-form gate's 5,000 clips the +library work for save and open is ~20-35 ms, well inside an interactive budget, so JSON + +simdjson stays (ADR-0007) and a SQLite index is not justified by project-file cost. + +Size: ~2.4 KB per clip. In a sample clip, default-valued groups (grade, colour, crop, +transform, audio) are about half the content and indentation most of the rest; gzip shrinks +the file ~15x. Omitting default-valued fields would roughly halve the file without a schema +change (readers already default absent fields). Not done: the measured cost does not need it, +and full output keeps diffs of a single setting local. + +Not measured here: cold open, re-import of the library (one probe per media item on the job +workers), and UI materialization (measured separately in +2026-10-06-m6-long-timeline.txt). diff --git a/Docs/Research/evidence/2026-10-12-m6-forced-hardware-fallback.txt b/Docs/Research/evidence/2026-10-12-m6-forced-hardware-fallback.txt new file mode 100644 index 0000000..8a638f5 --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-m6-forced-hardware-fallback.txt @@ -0,0 +1,20 @@ +M6 Settings: hardware decode chosen for media the GPU cannot decode (2026-10-12) + +Machine: Intel Iris Xe (TigerLake), iHD VA-API. vainfo lists H.264 ConstrainedBaseline, +Main and High only; no High 4:4:4 profile. +Command: OMA_PREVIEW_HARDWARE=1 build/debug/omamovie --m4-audit \ + tests/fixtures/generated/h264_444.mp4 5 +(OMA_PREVIEW_HARDWARE=1 forces the same path as Settings > Decode > Hardware.) + +Log (excerpt): + INFO decode h264_444.mp4: h264 VA-API to Vulkan decode + ERROR media [h264 @ ...] no frame! + WARN decode h264_444.mp4: VA-API to Vulkan decode refused h264 (High 4:4:4 Predictive), + falling back to software + M4 audit: media is shorter than 5 seconds + +Result: the forced hardware path is attempted, refused by the driver on the first frame and +replaced by software decode, with the profile named in the warning. FFmpeg's "no frame!" +error is logged once before the fallback. The audit itself stopped because the fixture is +shorter than its 5-second minimum, so frame pacing after the fallback was not measured here; +the viewer path after fallback is the ordinary software path covered elsewhere. diff --git a/Docs/Research/evidence/2026-10-12-m6-recordings-scan.txt b/Docs/Research/evidence/2026-10-12-m6-recordings-scan.txt new file mode 100644 index 0000000..0af0f0c --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-m6-recordings-scan.txt @@ -0,0 +1,24 @@ +M6 Recordings refresh (2026-10-12) + +Machine: Intel Iris Xe laptop, ext4 SSD, warm page cache, g++ -O2. +Bench: a scratch program calls omarchy::list_recordings(dir, 12) 30 times on synthetic +folders of N files ("screenrecording-i.mp4", every tenth a "-preview.png"). This is the +directory scan that Session::refreshRecordings runs on the UI thread when Projects opens +and when the folder changes; the rest of the refresh touches only the 12 shown entries. +No capture was in progress (/tmp/omarchy-screenrecord-filename absent). + +Before (two stats per video file: mtime and an unused size; full sort; when a capture is +in progress, std::filesystem::equivalent added two more stats per file): + 20 files: p50 0.047 p95 0.075 max 0.078 ms + 1,000 files: p50 3.136 p95 4.640 max 16.485 ms + 10,000 files: p50 33.390 p95 52.038 max 69.747 ms + +After (one stat per video file; a heap of the newest 12, O(files log 12), entries older +than the oldest kept are not copied; equivalent() only for files changed in the last 5 s): + 20 files: p50 0.029 p95 0.052 max 0.101 ms + 1,000 files: p50 1.222 p95 1.550 max 1.638 ms + 10,000 files: p50 14.848 p95 15.367 max 15.403 ms + +Decision: below one 60 Hz frame even at 10,000 files, so enumeration stays on the UI +thread. Not measured: a cold cache or network filesystem, and the in-progress capture case +(it would require writing the capture script's shared /tmp file). diff --git a/Docs/Research/evidence/2026-10-12-m6-trim-drag.txt b/Docs/Research/evidence/2026-10-12-m6-trim-drag.txt new file mode 100644 index 0000000..0c633ee --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-m6-trim-drag.txt @@ -0,0 +1,30 @@ +M6 edge-trim drag preview (2026-10-12) + +Machine: Intel Iris Xe (TigerLake), Qt 6.11, BUILD=release (omamovie target). +Command: OMA_AUDIT_ZOOM=60 build/release/omamovie --m6-timeline-audit N +After the routine edits, the audit drags the tail of the middle storyline clip with 100 +pointer events, four per frame of trim (0..25 frames), calling Session::previewTrim as +TimelineView.qml does. Each event is timed from the call to the end of the first Qt frame +that began after it. "Scope updates" counts editScopeChanged signals, i.e. previews that +copied the timeline and simulated the trim. Release = trimClip of 25 frames, then undo. + +Before (every pointer event simulated the trim): + 500 clips: 97 scope updates; drag event p50 16.7 / p95 26.6 / max 46.7 ms + 5,000 clips: 97 scope updates; drag event p50 16.6 / p95 26.5 / max 161.9 ms + +After (Session skips a preview whose clip, edge, frames and editor revision are unchanged): + 500 clips: 25 scope updates; drag event p50 16.6 / p95 20.5 / max 27.6 ms + 5,000 clips: 25 scope updates; drag event p50 16.6-16.8 / p95 23.8-27.0 / max 147.6-195.3 ms + 5,000 clips fitted (no OMA_AUDIT_ZOOM): p95 18.6-21.0 / max 25.2-25.4 ms + Release (trim + undo): 39-64 ms. Peak RSS (VmHWM) 0.80-0.94 GB for the whole audit. + +Where the time goes at 5,000 clips: one simulated preview costs 10-29 ms on the UI thread +(timeline copy, trim with storyline ripple moving ~2,500 clips, and a QVariantMap of every +moved clip for QML). The single 150-195 ms event at a working zoom recurs at event 56-57 and +is not a preview call (that event repeated the previous frame and was skipped); it is a +frame-side stall, absent when the sequence is fitted. Its cause is not identified here. + +Against the proposed long-form gate (p95 < 100 ms, no routine stall > 250 ms) the drag +passes at 5,000 clips, so the copy-and-simulate preview algorithm is kept. If it is changed +later, the cheaper shape is to report moved clips as a range of the ripple (O(affected) +data for QML) rather than one map entry per moved clip. diff --git a/Docs/Research/evidence/2026-10-12-m7-cold-open.txt b/Docs/Research/evidence/2026-10-12-m7-cold-open.txt new file mode 100644 index 0000000..2db68d6 --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-m7-cold-open.txt @@ -0,0 +1,25 @@ +M7 — cold and warm project open in the app, with library re-import (2026-10-12) + +Machine: Intel Core (Tiger Lake) laptop, NVMe, btrfs. Build: release app_tests (-O2). +Harness: a temporary Session test (not in the repository; kept in the session scratchpad) +run offscreen with private XDG folders. It writes 50 distinct media files (the 1 s +h264_30fps_aac.mp4 fixture plus i+1 trailing bytes, so each has its own fingerprint), imports +them, appends clips round-robin to 5,000 storyline clips and saves (11.7 MB). Then six opens +in fresh Sessions, alternating cold and warm. Cold: fdatasync + posix_fadvise(DONTNEED) on +the project file and every media file before opening; fincore confirmed eviction on this +btrfs volume (a first attempt under /tmp measured nothing: tmpfs cannot be evicted). + +"clips shown": openProject until Session::clips() holds 5,000 clips (read, parse, restore, +clip list). "re-imported": until no import is pending and all 50 media are in the library +(one probe per media item on the job workers; thumbnails come from the disk cache). + + clips shown library re-imported peak RSS +cold 74.2 / 80.7 / 80.4 ms 355 / 490 / 423 ms 237-242 MB +warm 60.2 / 60.4 / 57.6 ms 369 / 385 / 304 ms 237-242 MB + +Reading: a cold read adds about 20 ms to showing the clips; re-importing 50 media takes +0.3-0.5 s on the workers whatever the cache state, during which the timeline is already +editable and export is refused until every clip's media is loaded. Both stay within an +interactive budget at the long-form gate, so JSON/simdjson and per-item probing stay. +Not measured: a cold thumbnail cache, slow or network storage, and more than 50 media items. +UI materialization is in 2026-10-06-m6-long-timeline.txt. diff --git a/Docs/Research/evidence/2026-10-12-timeline-anchor-reattach.txt b/Docs/Research/evidence/2026-10-12-timeline-anchor-reattach.txt new file mode 100644 index 0000000..81bed58 --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-timeline-anchor-reattach.txt @@ -0,0 +1,19 @@ +Timeline: edit cost with many connected clips (2026-10-12) + +Bench (scratch, not versioned): tests/timeline/fixture.hpp's 30 fps fixture, 5,000 storyline +clips of 5 frames, the sound of every second clip detached (connected to its picture since +ADR-0014's 2026-10-12 note), then 20 splits near the end; mean per split, release libs. + +Every edit on a timeline with connected clips runs detail::reattach, which looked up each +connected clip's primary with Timeline::find_clip / track_of: a scan of every track per +connected clip, O(connected × clips). It now builds one ID index per reattach. + + connected before after + 0 4.27 ms 3.94 ms + 500 6.27 ms 6.65 ms + 2,000 19.72 ms 14.05 ms + +The quadratic term is gone but most of the cost remains: the before/after place maps, the +pass over every clip and the exact source arithmetic per connected clip are linear and were +not profiled further (no perf on this machine). Both stay under the long-form gate's p95 of +100 ms; revisit with a profile if connected clips grow past a few thousand. diff --git a/Docs/Research/evidence/2026-10-12-timeline-insert-clip.txt b/Docs/Research/evidence/2026-10-12-timeline-insert-clip.txt new file mode 100644 index 0000000..b9ae1b8 --- /dev/null +++ b/Docs/Research/evidence/2026-10-12-timeline-insert-clip.txt @@ -0,0 +1,19 @@ +Timeline: inserting clips into a long track (2026-10-12) + +Bench (scratch, not versioned): tests/timeline/fixture.hpp's 30 fps fixture; N edit::append +steps of 5 frames each executed as one transaction, against the release libs (g++ -O2). +Found while the M6 long-timeline audit spent 1.7-2.2 s building 5,000 clips. + +Cause: InsertClip::apply pushed the clip at the end and re-sorted the whole track +(O(n log n) moves of large Clip values per insert), so building n clips cost O(n² log n). +Tracks are sorted after every primitive command, so the clip now goes in at +upper_bound(start) instead. + + before after + 1,000 44.4 ms 2.5 ms + 5,000 1,247.8 ms 34.3 ms + 20,000 29,486.3 ms 993.5 ms + +Still O(n) per insert: the duplicate-ID check (Timeline::find_clip) and range_free scan the +track. At the 5,000-clip long-form gate that is 34 ms for the whole build, so they stay. +timeline_tests (423 checks) pass, also under ASan/UBSan. diff --git a/Docs/Research/evidence/2026-10-13-m10-real-recordings.txt b/Docs/Research/evidence/2026-10-13-m10-real-recordings.txt new file mode 100644 index 0000000..35cca68 --- /dev/null +++ b/Docs/Research/evidence/2026-10-13-m10-real-recordings.txt @@ -0,0 +1,22 @@ +M10 recording workflow on real Omarchy recordings (2026-10-13) + +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2, FFmpeg 9.0.1, debug build, software export. +Command: OMA_REAL_RECORDING= build/debug/tests/app_tests "real recording's frames" +Files: the user's own captures (omarchy-capture-screenrecording via gpu-screen-recorder), not +kept in the repository. Profile probed: H.264 High 1920x1080, 60 fps CFR, no B-frames, time base +1/15360, BT.709 limited range; AAC LC stereo 96 kHz when recorded with sound. + +Flow: import, split at 0.25 s, ripple delete the head, save, reopen, export (mp4-h264). +Checks by ffmpeg, outside OmaMovie: exported frame count = source - 15; every 15th exported frame +within 2 levels/pixel of its source frame and no frame within +-30 matching better by more than +1/8 level/pixel; mixed sound cross-correlated over every 0.5 s window with sound (+-10 ms search). + + 8.1 s, no sound 473 frames pass 14 s + 36.4 s, sound 2174 frames pass; 1 sounding window, lag 0 52 s +108.0 s, sound 6465 frames pass; 6 sounding windows, lag 0 154 s + +Found on the way: before the export-transfer fix (ADR-0006 amendment) exported frames differed +from their source by ~12 levels/pixel (SAD 44-50k of 3600 pixels); after it by ~0.2 (SAD ~700). +The first recording with sound had a silent left channel (microphone on the right only) and one +burst of sound in 36 s: a first-channel check at fixed points had compared nothing. The check now +mixes channels, scans every window and fails when sound exists but no window was compared. diff --git a/Docs/Research/evidence/2026-10-13-m7-package-check.txt b/Docs/Research/evidence/2026-10-13-m7-package-check.txt new file mode 100644 index 0000000..b02b0b4 --- /dev/null +++ b/Docs/Research/evidence/2026-10-13-m7-package-check.txt @@ -0,0 +1,23 @@ +M7 — PKGBUILD build, install and launch in clean containers (2026-10-13) + +Command: scripts/package-check.sh (podman, docker.io/library/archlinux:latest, 6.5 min). +1. Build container: base-devel + git; the PKGBUILD's source points at this checkout + (git+file, branch feature/first-release) instead of the published repository; + makepkg -s installs depends/makedepends/checkdepends and runs build() and check() + (the whole ctest suite: 10/10 on llvmpipe, Mesa 26.2.4). Package omamovie-git + r230.18c30f2-1 (2.84 MiB) plus its debug package. +2. Launch container: a second clean image; pacman -U the package, sway + vulkan-swrast; + sway runs headless (WLR_BACKENDS=headless, pixman renderer) as a non-root user and the + installed /usr/bin/omamovie runs --smoke with QT_QPA_PLATFORM=wayland from a read-only + mount of the repository (the smoke reads tests/fixtures/generated): GUI smoke PASS + (edits, keyboard, classic controls), exit 0. +Found on the way: + - QT_QPA_PLATFORM=offscreen cannot launch the app: "Qt could not adopt the Vulkan instance" + (the viewer needs a Vulkan-capable window); a Wayland compositor is required. + - sway's file capabilities cannot be granted in rootless podman; the script drops them + inside the throwaway container. + - makepkg could not update pkgver when the rewritten PKGBUILD belonged to root (r0-1). + - The new app write-fault test crashed check() with SIGBUS under llvmpipe (memfd-backed + device memory under RLIMIT_FSIZE); fixed by injecting app-level faults before rendering. +Not covered: Hyprland/Omarchy itself (the compositor here is sway), real GPU drivers in the +container, VA-API, PipeWire audio output (the smoke plays to a null sink there). diff --git a/Docs/Research/evidence/2026-10-13-m7-two-hour-1080p.txt b/Docs/Research/evidence/2026-10-13-m7-two-hour-1080p.txt new file mode 100644 index 0000000..02d1c5f --- /dev/null +++ b/Docs/Research/evidence/2026-10-13-m7-two-hour-1080p.txt @@ -0,0 +1,25 @@ +M7 — two-hour 1080p export with cuts, looks and a dissolve (2026-10-12/13) + +Machine: Intel Iris Xe (TGL GT2), Arch/Omarchy, btrfs on NVMe. Build: release omamovie. +Source (lavfi, not versioned, /var/tmp): 1920x1080 30 fps testsrc2, BT.709-tagged H.264 +(ultrafast, GOP 300) + AAC 48 kHz, 7200 s, 13.4 GB, with a one-frame white flash and a 50 ms +1 kHz beep at 10 s, 3600 s and 7190 s. Generation took 15 min. +Project (built through Session in a temporary harness, saved with libs/project): the source +cut into six contiguous 20-minute storyline clips; Black & White look on clips 2, 4 and 6; +a 1 s dissolve centred on the cut at 2400 s (clip 2 Black & White into clip 3 colour). +Export: build/release/omamovie --export-audit long.omamovie out.mp4, automatic encoder. + 216,000 frames in 3,165 s (68.2 fps, 52 min 45 s), VA-API H.264, Vulkan compositor. + per frame: build 0.06, render+readback 8.03, encode 6.12, audio 0.44 ms. + Output 8.27 GB: video 216,000 frames / 7200.000 s, AAC 7200.000 s; stage directory gone. +Independent check (ffmpeg only: signalstats per frame, first sample above 0.05), same script +on source and export: + mark 10 s: flash 10.0000 beep 10.0000 (both files) + mark 3600 s: flash 3600.0000 beep 3600.0000 (both files; clip 4, Black & White) + mark 7190 s: flash 7190.0000 beep 7190.0000 (both files; clip 6, Black & White) + SATAVG source everywhere ~117 (99.5-117 around the cut: test-pattern motion) + export 600 s 115.7 | 1800 s 0.00 | 3000 s 115.7 | 3605 s 0.00 | 5400 s 115.7 | + 7000 s 0.00; dissolve 2399.5 s 0.00, 2399.8 27.9, 2400.0 47.1, 2400.2 66.8, + 2400.5 115.2 (monotonic over exactly its 1 s window) +Reading: no A/V drift over two hours at 1080p through cuts, a dissolve and looks at frame and +sample resolution; each look covers exactly its clip and the dissolve exactly its window. +Not covered: software encoding at this length, blur/detail and grading along a long timeline. diff --git a/Docs/Research/evidence/2026-10-13-m8-speed-audio-cost.txt b/Docs/Research/evidence/2026-10-13-m8-speed-audio-cost.txt new file mode 100644 index 0000000..f66c136 --- /dev/null +++ b/Docs/Research/evidence/2026-10-13-m8-speed-audio-cost.txt @@ -0,0 +1,19 @@ +M8 — cost of constant-speed sound in playback::TimelineAudio (2026-10-13) + +Machine: Intel Core (Tiger Lake), Arch/Omarchy. Build: release playback_tests (-O2; built +with OMA_WERROR=OFF because GCC 16 raises a -Warray-bounds false positive in +tests/playback/test_waveform.cpp in release, as it does in tests/media). +Harness (temporary, not in the repository): tone_44100.wav (2 s, 44.1 kHz WAV) placed at +1x, 2x and 1/2x over as much of the sequence as the source allows; 20 passes per speed, each +a new TimelineAudio rendering 1,024-frame stereo blocks at 48 kHz from a different start +(so every pass opens the decoder and seeks), then to the end of the clip. + +speed open + seek + first block (mean of 20) steady decode + resample + mix + 1x 7.64 / 7.77 ms 0.588 / 0.596 ms per second of output + 2x 7.58 / 7.81 ms 0.923 / 0.924 ms per second of output + 1/2x 8.02 / 7.99 ms 0.440 / 0.449 ms per second of output + +Reading: cost scales with the media decoded (2x reads twice the source per output second), +below 0.1 % of real time on one core either way; the seek cost does not depend on speed. +Not measured: compressed sources (AAC/Opus decode), many retimed clips at once, and the +pitch-preserving alternative (needs a time-stretch dependency decision). diff --git a/Docs/Research/evidence/2026-10-14-async-scrub.txt b/Docs/Research/evidence/2026-10-14-async-scrub.txt new file mode 100644 index 0000000..75e6f0d --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-async-scrub.txt @@ -0,0 +1,108 @@ +Async paused scrub (ADR-0020) and the libuv spike (2026-10-14) + +Machine: Intel Core i5-1135G7 (4 cores / 8 threads), Iris Xe (TGL GT2), Mesa 26.2.2, iHD 26.2.4, +BUILD=release. Fixtures: FilmCraft's recipes (2026-10-14-filmcraft-equivalent-benchmarks.txt): +a1080.mp4 (H.264 1080p23.976, GOP 250), a2160.mp4 (H.264 2160p, ~170 Mbit/s, GOP 250), +hevc2160.mp4 (HEVC 2160p). Command: omamovie --m4-scrub-audit FILE 24 (paused seeks every +500 ms to pseudo-random positions; the gap is the longest wait between ticks of a 2 ms UI +timer per seek window). hw = default VA-API, sw = OMA_PREVIEW_HARDWARE=0; OMA_PREVIEW_SCALE=1. +Before = 6d3a6c5 (paused hardware frames decoded in Qt's sync phase; the audit fix that prints +first-frame latency for scrubs); after = c0365c4 (decoded on the job worker, latest wins). + +Note on "without a frame in 500 ms": before, a blocked UI could not issue the next seek, so a +slow seek was still counted when it arrived (up to 1.48 s); after, the next seek supersedes it. +At 4K H.264 the two columns are therefore not comparable; the UI gap is. + +== Before +a1080.mp4 hw run1 load 1.21 UI event-loop gap p50 66.85 p95 220.26 max 263.38 ms, first composited frame p50 66.85 p95 220.25 max 263.38 ms, 0 without a frame in 500 ms +a1080.mp4 hw run2 load 1.14 UI event-loop gap p50 66.83 p95 221.28 max 261.93 ms, first composited frame p50 66.82 p95 221.28 max 261.93 ms, 0 without a frame in 500 ms +a1080.mp4 sw run1 load 0.97 UI event-loop gap p50 8.84 p95 11.47 max 14.36 ms, first composited frame p50 220.38 p95 457.62 max 478.78 ms, 0 without a frame in 500 ms +a1080.mp4 sw run2 load 1.19 UI event-loop gap p50 9.02 p95 14.86 max 15.06 ms, first composited frame p50 240.47 p95 468.78 max 499.72 ms, 0 without a frame in 500 ms +a2160.mp4 hw run1 load 1.22 UI event-loop gap p50 469.72 p95 1320.92 max 1481.65 ms, first composited frame p50 332.08 p95 1320.91 max 1484.47 ms, 0 without a frame in 500 ms +a2160.mp4 hw run2 load 1.00 UI event-loop gap p50 469.39 p95 1325.83 max 1481.38 ms, first composited frame p50 329.99 p95 1325.83 max 1484.45 ms, 0 without a frame in 500 ms +a2160.mp4 sw run1 load 0.78 UI event-loop gap p50 3.50 p95 24.90 max 33.31 ms, first composited frame p50 109.40 p95 519.05 max 519.05 ms, 13 without a frame in 500 ms +a2160.mp4 sw run2 load 1.04 UI event-loop gap p50 3.49 p95 24.07 max 28.67 ms, first composited frame p50 49.96 p95 506.45 max 506.45 ms, 15 without a frame in 500 ms +hevc2160.mp4 hw run1 load 2.94 UI event-loop gap p50 175.80 p95 252.52 max 273.65 ms, first composited frame p50 183.49 p95 252.52 max 273.65 ms, 0 without a frame in 500 ms +hevc2160.mp4 hw run2 load 2.56 UI event-loop gap p50 174.99 p95 254.04 max 282.49 ms, first composited frame p50 174.98 p95 254.04 max 282.49 ms, 0 without a frame in 500 ms +hevc2160.mp4 sw run1 load 2.35 UI event-loop gap p50 3.37 p95 25.00 max 27.33 ms, first composited frame p50 70.84 p95 472.09 max 472.09 ms, 11 without a frame in 500 ms +hevc2160.mp4 sw run2 load 2.81 UI event-loop gap p50 5.91 p95 23.23 max 25.82 ms, first composited frame p50 111.02 p95 437.25 max 437.25 ms, 11 without a frame in 500 ms + +== After (the first two rows ran at load 6-8 right after a build; see the interleaved rerun) +a1080.mp4 hw run1 load 8.00 UI event-loop gap p50 6.57 p95 12.05 max 12.27 ms, first composited frame p50 63.09 p95 277.80 max 293.31 ms, 0 without a frame in 500 ms +a1080.mp4 hw run2 load 6.31 UI event-loop gap p50 5.42 p95 12.03 max 16.36 ms, first composited frame p50 61.04 p95 295.31 max 302.70 ms, 0 without a frame in 500 ms +a1080.mp4 sw run1 load 5.42 UI event-loop gap p50 8.70 p95 14.99 max 15.08 ms, first composited frame p50 140.98 p95 410.47 max 479.88 ms, 2 without a frame in 500 ms +a1080.mp4 sw run2 load 4.35 UI event-loop gap p50 9.40 p95 14.14 max 15.59 ms, first composited frame p50 151.56 p95 434.96 max 469.85 ms, 2 without a frame in 500 ms +a2160.mp4 hw run1 load 4.05 UI event-loop gap p50 2.92 p95 12.05 max 12.27 ms, first composited frame p50 243.54 p95 371.61 max 371.61 ms, 14 without a frame in 500 ms +a2160.mp4 hw run2 load 3.58 UI event-loop gap p50 2.70 p95 12.07 max 13.92 ms, first composited frame p50 250.57 p95 372.33 max 372.33 ms, 14 without a frame in 500 ms +a2160.mp4 sw run1 load 2.92 UI event-loop gap p50 2.99 p95 23.27 max 32.62 ms, first composited frame p50 2.46 p95 477.19 max 477.19 ms, 14 without a frame in 500 ms +a2160.mp4 sw run2 load 3.19 UI event-loop gap p50 3.51 p95 25.61 max 32.49 ms, first composited frame p50 3.15 p95 508.33 max 508.33 ms, 13 without a frame in 500 ms +hevc2160.mp4 hw run1 load 3.45 UI event-loop gap p50 11.71 p95 16.35 max 19.29 ms, first composited frame p50 141.85 p95 254.97 max 279.97 ms, 0 without a frame in 500 ms +hevc2160.mp4 hw run2 load 3.23 UI event-loop gap p50 11.77 p95 18.85 max 20.82 ms, first composited frame p50 144.73 p95 256.80 max 275.11 ms, 0 without a frame in 500 ms +hevc2160.mp4 sw run1 load 2.93 UI event-loop gap p50 3.18 p95 23.34 max 26.49 ms, first composited frame p50 104.85 p95 427.90 max 427.90 ms, 11 without a frame in 500 ms +hevc2160.mp4 sw run2 load 2.94 UI event-loop gap p50 8.05 p95 23.27 max 33.86 ms, first composited frame p50 90.93 p95 465.58 max 465.58 ms, 11 without a frame in 500 ms + +== Interleaved 1080p hardware, low load +before load 2.55 UI event-loop gap p50 63.76 p95 293.23 max 301.17 ms, first composited frame p50 63.76 p95 293.22 max 301.16 ms, 0 without a frame in 500 ms +after load 2.14 UI event-loop gap p50 5.64 p95 12.73 max 13.16 ms, first composited frame p50 61.49 p95 291.20 max 305.63 ms, 0 without a frame in 500 ms +before load 1.81 UI event-loop gap p50 63.99 p95 288.82 max 296.43 ms, first composited frame p50 63.98 p95 288.82 max 296.42 ms, 0 without a frame in 500 ms +after load 1.61 UI event-loop gap p50 6.13 p95 14.36 max 14.40 ms, first composited frame p50 63.75 p95 298.09 max 298.81 ms, 0 without a frame in 500 ms + +== Vulkan validation (VK_LAYER_KHRONOS_validation, synchronization validation, errors), after +Layer insertion confirmed with VK_LOADER_DEBUG=layer (instance and device). +--m4-scrub-audit a1080.mp4 24 and hevc2160.mp4 24, hardware: exit 0, 0 Validation Error, +0 SYNC-HAZARD (timings under the layer are not comparable). app_tests (101 tests, including +tests/app/test_paused_frames.cpp on the VA-API path): exit 0, 0 errors, 0 SYNC-HAZARD. + +== libuv spike (scratch program, not committed; libuv 1.52.1 from the system) +A burst of 20 requests 15 ms apart; each request decodes 1..100 frames (uniform, seed 7) of +3 ms each, stopping between frames when superseded; 10 rounds, means. + A oma::JobPool, one worker, Session's pattern (one in flight, one wanted, request counter) + B uv_queue_work on libuv's pool, uv_cancel for queued work, the same counter for running + work, publication in after_work on the loop thread + C oma::JobPool FIFO without cancellation +A JobPool latest-wins : last request published after 171.5 ms, 147.5 frames decoded, 1 stale published +B libuv latest-wins : last request published after 171.8 ms, 149.3 frames decoded, 1 stale published +C JobPool FIFO : last request published after 2879.6 ms, 1026.7 frames decoded, 190 stale published +"stale published" counts superseded requests that completed; the app's publication check drops +them. libuv cannot interrupt a running work callback, so B needs A's flag; B also adds libuv's +process-wide pool (4 threads by default) and a loop thread beside Qt's. + +== 5,000-clip timeline audit (--m6-timeline-audit 5000), unchanged by this work, 3 runs +split p95 135.6 / 138.3 / 146.9 ms, ripple delete 107.6 / 108.2 / 108.6, undo 128.1 / 130.6 / +125.5; trim drag p95 17.0. 2026-10-06 (same audit, fitted): split 25.3, ripple 20.2, undo 17.9. + +== Sanitizers, after (c0365c4) +make -j BUILD=tsan test: 13/13 suites passed; app_tests run directly under the same TSAN_OPTIONS: +101 tests passed, including all five paused-frame tests (VA-API on this machine), 0 reports. +make -j BUILD=asan test (ASan, LSan, UBSan): 13/13 suites passed. + +== Cancellation latency (63ca324 adds it to --m4-scrub-audit: ms from the first request that +replaces the seek in flight to the stopped job's return). Only seeks still decoding when the +audit's next seek arrives 500 ms later are stopped, so 1080p and HEVC 4K hardware have none. +With c0365c4's FrameSource (a stopped stream is dropped, closing its decoder): + a2160 hw: 11 cancellations, p50 150.50 p95 154.59 max 154.59 ms + a2160 sw: 13, p50 63.95 p95 98.95; hevc2160 sw: 13, p50 77.46 p95 125.44 +A temporary timer around the drop (not committed) measured 141-149 ms per drop in hardware and +58-95 ms in software: closing the decoder, not the stop, was the cost. +With 83caf29 (the stopped decoder stays open and seeks again): + a2160 hw: 12 cancellations, p50 5.02 p95 8.47 max 8.47 ms; first frame p50 244 -> 190 ms + a2160 sw: 13, p50 18.25 p95 43.58; hevc2160 sw: 13, p50 31.53 p95 70.58 + UI gap unchanged (a2160 hw p95 14.5, a1080 hw 12.8, hevc2160 hw 18.1 ms). Software HEVC 4K + UI gap p95 23.6-25.3 in both builds, interleaved runs (load 4-5). +Sanitizers at 83caf29: make -j BUILD=tsan test and make -j BUILD=asan test, 13/13 suites each. + +== Scrub during imports: a dedicated paused-viewer worker (2026-10-14) +A temporary audit patch (not committed) imported other files into the library through +Session::importUrl right after scrubbing began; a1080.mp4 hardware, 24 paused seeks. +Shared worker (1edad77): + one 4K import: gap p95 12.35 / 11.87, first frame p50 59-63 ms, 0 missed (the import + ends after a few seeks: no measurable effect) + 15 imports (all the FilmCraft fixtures but a1080): gap p95 25.09 / 13.59 ms, first frame p50 + 132 / 63 ms, 10 / 6 of 24 seeks without a frame in 500 ms (none: 0) +Own one-thread JobPool for paused frames, own software FrameSource (this commit): + 15 imports: gap p95 14.30 / 16.09 ms, first frame p50 63.7 / 60.7 ms, 0 missed + no imports: gap p95 13.87 / 12.47 ms, 0 missed + software decode with 15 imports: gap p95 19.0 / 24.0, 3 / 3 missed (decode-bound, not queued) +Cost: one more thread, and the viewer's software decoders no longer share their frame-history +budget with thumbnails (two budgets of min(384 MB, 1/8 of RAM) instead of one; not measured). +make -j BUILD=tsan test and app_tests run directly under TSan: pass, 0 reports. diff --git a/Docs/Research/evidence/2026-10-14-cross-editor-cuts.txt b/Docs/Research/evidence/2026-10-14-cross-editor-cuts.txt new file mode 100644 index 0000000..6f198cb --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-cross-editor-cuts.txt @@ -0,0 +1,48 @@ +Cross-editor cuts scene, same machine (2026-10-14): OmaMovie vs MLT melt (Kdenlive 26.08's engine) +Command: tools/bench/cross-editor/run.sh 5 DIR cuts (raw report below, app log lines removed). +Edit: five reordered cuts of the BT.709 20 s 1080p source (frames 400+40, 24+72, 200+60, 0+12, +300+72 = 256 frames), given to OmaMovie as OTIO converted by `oma-project convert` and to melt +as a playlist of in/out points. Checks by FFmpeg only: frame count, A/V length, and all 256 +output frames against the source trimmed and joined the same way (worst luma PSNR). + +Caveat: load average 6-7.5 throughout (another session active); order alternated per round. + +Summary (median wall of 5, peak RSS, bytes, worst frame PSNR, frames, all runs passed): + OmaMovie VA-API 6.7 s 690 MB 14.7 MB 44.4 dB 256/256 + melt VA-API 4.8 s 656 MB 16.1 MB 45.1 dB 256/256 + OmaMovie x264 12.4 s 1297 MB 8.9 MB 42.0 dB 256/256 + melt x264 10.5 s 1246 MB 10.4 MB 42.2 dB 256/256 +Both editors cut on the exact frames (worst frame is the same source frame for both, n 230). +Unlike the whole-file export, melt adds no frame here. OmaMovie is 1.4x slower on VA-API and +1.2x on x264; its export renders, reads back and encodes each frame in series (code review +part 5). + +Cross-editor export 2026-10-14 22:04:26 -0300, 5 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.2.4 () +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 7.37 6.21 4.83 +editors: OmaMovie 0e12ece (dirty); melt 7.40.0 (Kdenlive 26.08.0) +scene: cuts; source: xed_1080p24_bt709.mp4 sha256 2c18c4d39be559a6, 479 frames +round 1 oma hardware: measure: rc=0 wall_s=6.43 user_s=15.01 sys_s=1.50 peak_rss_mb=688 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=14652024 verdict=pass cut frames compared=256 worst psnr_y:44.37 at n:230 +round 1 melt hardware: measure: rc=0 wall_s=5.96 user_s=19.18 sys_s=0.58 peak_rss_mb=654 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 1 oma software: measure: rc=0 wall_s=12.24 user_s=72.26 sys_s=2.65 peak_rss_mb=1275 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 1 melt software: measure: rc=0 wall_s=10.41 user_s=68.39 sys_s=0.87 peak_rss_mb=1233 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 2 melt software: measure: rc=0 wall_s=10.35 user_s=68.38 sys_s=0.90 peak_rss_mb=1246 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 2 oma software: measure: rc=0 wall_s=12.69 user_s=72.15 sys_s=2.80 peak_rss_mb=1272 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 2 melt hardware: measure: rc=0 wall_s=4.74 user_s=17.22 sys_s=0.56 peak_rss_mb=654 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 2 oma hardware: measure: rc=0 wall_s=6.77 user_s=16.76 sys_s=1.68 peak_rss_mb=686 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=14652024 verdict=pass cut frames compared=256 worst psnr_y:44.37 at n:230 +round 3 oma hardware: measure: rc=0 wall_s=6.76 user_s=17.07 sys_s=1.54 peak_rss_mb=690 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=14652024 verdict=pass cut frames compared=256 worst psnr_y:44.37 at n:230 +round 3 melt hardware: measure: rc=0 wall_s=4.70 user_s=17.23 sys_s=0.56 peak_rss_mb=654 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 3 oma software: measure: rc=0 wall_s=13.21 user_s=73.42 sys_s=2.91 peak_rss_mb=1297 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 3 melt software: measure: rc=0 wall_s=10.48 user_s=68.07 sys_s=0.81 peak_rss_mb=1231 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 4 melt software: measure: rc=0 wall_s=10.51 user_s=68.67 sys_s=0.85 peak_rss_mb=1245 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 4 oma software: measure: rc=0 wall_s=12.41 user_s=71.65 sys_s=2.80 peak_rss_mb=1293 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 4 melt hardware: measure: rc=0 wall_s=4.84 user_s=17.43 sys_s=0.59 peak_rss_mb=656 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 4 oma hardware: measure: rc=0 wall_s=6.69 user_s=17.00 sys_s=1.66 peak_rss_mb=688 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=14652024 verdict=pass cut frames compared=256 worst psnr_y:44.37 at n:230 +round 5 oma hardware: measure: rc=0 wall_s=6.69 user_s=17.03 sys_s=1.62 peak_rss_mb=686 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=14652024 verdict=pass cut frames compared=256 worst psnr_y:44.37 at n:230 +round 5 melt hardware: measure: rc=0 wall_s=4.75 user_s=17.34 sys_s=0.58 peak_rss_mb=652 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 5 oma software: measure: rc=0 wall_s=12.31 user_s=72.11 sys_s=2.67 peak_rss_mb=1275 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 5 melt software: measure: rc=0 wall_s=10.50 user_s=68.50 sys_s=0.86 peak_rss_mb=1234 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +load at end: 7.43 7.03 5.51 diff --git a/Docs/Research/evidence/2026-10-14-cross-editor-export.txt b/Docs/Research/evidence/2026-10-14-cross-editor-export.txt new file mode 100644 index 0000000..410ea0f --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-cross-editor-export.txt @@ -0,0 +1,51 @@ +Cross-editor export, same machine (2026-10-14): OmaMovie vs MLT melt (Kdenlive 26.08's engine) +Command: tools/bench/cross-editor/run.sh 5 (raw report below, unedited except the app's log lines). +Workload: one 20 s 1080p 23.976 H.264/AAC file (FilmCraft's grain recipe, tagged BT.709 limited) +exported whole to MP4 H.264 + AAC 192k; each editor's encoder defaults (libx264 CRF 23 medium, +h264_vaapi CQP), no B-frames. Wall time is the whole process: start, import/probe, export, exit. +Checks by FFmpeg only: frame count, A/V length, luma PSNR against the source. + +Caveat: the 1-minute load average stayed 6.5-8.5 during the run (another session was active), +so absolute times are noisy; the order alternated each round. Rate control differs between the +editors (sizes and PSNR below), so these are separate profiles, not one quality target. + +Summary (median wall of completed runs, peak RSS, bytes, luma PSNR, frames): + OmaMovie VA-API 9.9 s (4 of 5; 1 hang) 420 MB 27.7 MB 47.7 dB 479/479 + melt VA-API 6.5 s (5 of 5) 351 MB 30.3 MB 48.7 dB 480/479 + OmaMovie x264 20.1 s (5 of 5) 1014 MB 16.7 MB 44.4 dB 479/479 + melt x264 17.7 s (5 of 5) 940 MB 19.5 MB 44.8 dB 480/479 +Findings: melt appends one frame (a near-copy of the last, 52.9 dB to it) to reach 20.02 s; +OmaMovie keeps the source's 479. OmaMovie's round 2 VA-API run wrote a complete file and then +hung: the viewer composited one GPU frame on two layers and the render thread deadlocked on the +frame lock it already held (core analysed; Docs/implementation-plan-code-review-4.md). +OmaMovie spends ~2 s of system time per export against melt's ~0.4-0.9 s; not yet explained. + +Cross-editor export 2026-10-14 21:24:20 -0300, 5 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.2.4 () +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 8.51 5.86 3.39 +editors: OmaMovie 0e12ece (dirty); melt 7.40.0 (Kdenlive 26.08.0) +source: xed_1080p24_bt709.mp4 sha256 2c18c4d39be559a6, 479 frames +round 1 oma hardware: measure: rc=0 wall_s=12.94 user_s=23.34 sys_s=2.51 peak_rss_mb=419 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=27685017 psnr_y:47.711786 verdict=pass +round 1 melt hardware: measure: rc=0 wall_s=7.98 user_s=20.22 sys_s=0.52 peak_rss_mb=351 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 1 oma software: measure: rc=0 wall_s=21.76 user_s=131.69 sys_s=4.68 peak_rss_mb=1014 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 1 melt software: measure: rc=0 wall_s=20.07 user_s=120.51 sys_s=1.22 peak_rss_mb=940 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 2 melt software: measure: rc=0 wall_s=19.97 user_s=119.34 sys_s=1.11 peak_rss_mb=938 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 2 oma software: measure: rc=0 wall_s=21.01 user_s=132.41 sys_s=4.55 peak_rss_mb=1005 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 2 melt hardware: measure: rc=0 wall_s=7.36 user_s=19.51 sys_s=0.46 peak_rss_mb=350 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 2 oma hardware: measure: rc=-6 wall_s=461.68 user_s=13.84 sys_s=0.78 peak_rss_mb=430 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=27685017 psnr_y:47.711786 verdict=pass +round 3 oma hardware: measure: rc=0 wall_s=9.91 user_s=19.36 sys_s=2.11 peak_rss_mb=418 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=27685017 psnr_y:47.711786 verdict=pass +round 3 melt hardware: measure: rc=0 wall_s=6.46 user_s=16.27 sys_s=0.41 peak_rss_mb=351 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 3 oma software: measure: rc=0 wall_s=20.07 user_s=125.92 sys_s=4.39 peak_rss_mb=1008 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 3 melt software: measure: rc=0 wall_s=16.39 user_s=114.16 sys_s=0.91 peak_rss_mb=942 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 4 melt software: measure: rc=0 wall_s=17.70 user_s=114.77 sys_s=0.92 peak_rss_mb=928 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 4 oma software: measure: rc=0 wall_s=19.82 user_s=125.88 sys_s=4.03 peak_rss_mb=1028 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 4 melt hardware: measure: rc=0 wall_s=6.53 user_s=17.12 sys_s=0.39 peak_rss_mb=351 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 4 oma hardware: measure: rc=0 wall_s=9.63 user_s=20.16 sys_s=2.03 peak_rss_mb=420 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=27685017 psnr_y:47.711786 verdict=pass +round 5 oma hardware: measure: rc=0 wall_s=9.67 user_s=20.22 sys_s=2.05 peak_rss_mb=419 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=27685017 psnr_y:47.711786 verdict=pass +round 5 melt hardware: measure: rc=0 wall_s=6.46 user_s=16.52 sys_s=0.38 peak_rss_mb=351 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 5 oma software: measure: rc=0 wall_s=19.96 user_s=126.41 sys_s=3.88 peak_rss_mb=1017 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 5 melt software: measure: rc=0 wall_s=16.46 user_s=114.35 sys_s=0.85 peak_rss_mb=942 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +load at end: 6.95 5.85 4.74 diff --git a/Docs/Research/evidence/2026-10-14-filmcraft-equivalent-benchmarks.txt b/Docs/Research/evidence/2026-10-14-filmcraft-equivalent-benchmarks.txt new file mode 100644 index 0000000..447f1a1 --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-filmcraft-equivalent-benchmarks.txt @@ -0,0 +1,192 @@ +FilmCraft-equivalent benchmarks on OmaMovie (2026-10-14) + +Machine: Intel Core i5-1135G7 (4 cores / 8 threads), Iris Xe (TGL GT2), Mesa 26.2.2, iHD 26.2.4, +15 GB RAM, eDP 1920x1080 @ 60 Hz. OmaMovie commit 1c587b2, BUILD=release. Load average 2-7 +(desktop session, no parallel builds). FilmCraft was not built or run here. +Fixtures: FilmCraft's own recipes (crates/ui-egui/examples/bench/fixtures.rs): testsrc2 + noise +alls=6, 24000/1001 fps; x264 fast crf 20, x265 fast crf 22 (Main and Main 10), libvpx-vp9 +realtime cpu-used 8 crf 32, SVT-AV1 preset 10 crf 35 keyint 48, prores_ks profile 3. Generated +in the scratchpad, not committed. + +== Decode: every frame through FFmpeg (the decoder oma-media wraps), not the app path. +Software = FFmpeg CPU decode; vaapi = -hwaccel vaapi -hwaccel_output_format vaapi (frames stay +on the GPU, no read-back, no Vulkan import). CPU ms/frame is the median of 3, fps the best of 3. +dec_h264_1080.mp4 off 120 frames CPU 30.7 ms/frame 215 fps +dec_h264_1080.mp4 vaapi 120 frames CPU 0.8 ms/frame 444 fps +dec_h264_2160.mp4 off 72 frames CPU 120.3 ms/frame 51 fps +dec_h264_2160.mp4 vaapi 72 frames CPU 2.4 ms/frame 118 fps +dec_hevc_1080.mp4 off 120 frames CPU 18.3 ms/frame 240 fps +dec_hevc_1080.mp4 vaapi 120 frames CPU 0.6 ms/frame 1121 fps +dec_hevc_2160.mp4 off 72 frames CPU 78.2 ms/frame 62 fps +dec_hevc_2160.mp4 vaapi 72 frames CPU 2.4 ms/frame 286 fps +dec_hevc10_2160.mp4 off 72 frames CPU 100.3 ms/frame 50 fps +dec_hevc10_2160.mp4 vaapi 72 frames CPU 3.0 ms/frame 247 fps +dec_vp9_1080.webm off 120 frames CPU 11.1 ms/frame 333 fps +dec_vp9_1080.webm vaapi 120 frames CPU 0.3 ms/frame 1212 fps +dec_vp9_2160.webm off 72 frames CPU 45.6 ms/frame 93 fps +dec_vp9_2160.webm vaapi 72 frames CPU 1.3 ms/frame 298 fps +dec_av1_1080.mp4 off 120 frames CPU 5.4 ms/frame 486 fps +dec_av1_1080.mp4 vaapi 120 frames CPU 0.3 ms/frame 1101 fps +dec_av1_2160.mp4 off 72 frames CPU 18.4 ms/frame 153 fps +dec_av1_2160.mp4 vaapi 72 frames CPU 1.1 ms/frame 285 fps +dec_prores_1080.mov off 48 frames CPU 32.5 ms/frame 187 fps +dec_prores_1080.mov vaapi fallback (yuv422p10le) +dec_prores_2160.mov off 24 frames CPU 127.5 ms/frame 45 fps +dec_prores_2160.mov vaapi fallback (yuv422p10le) + +== Playback: omamovie --m4-audit FILE 8 (192 frames due); hw = default VA-API to Vulkan, +sw = OMA_PREVIEW_HARDWARE=0; full = OMA_PREVIEW_SCALE=1, auto = adaptive preview quality. +== a1080.mp4 hw-full run1 load 3.14 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 599 samples, 190 composites, p99 30.79 ms, max 31.81 ms, first/last mean delta 0.00 ms, signed range -31.81..21.13 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 41.71 ms +M4 audit stages: composite p50 3.56 p95 7.33 p99 11.45 ms, interval p50 40.12 p95 59.71 p99 62.09 ms +== a1080.mp4 hw-full run2 load 2.97 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 599 samples, 192 composites, p99 32.27 ms, max 35.77 ms, first/last mean delta 0.00 ms, signed range -35.77..21.58 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 3.62 p95 7.36 p99 12.76 ms, interval p50 40.05 p95 60.22 p99 82.74 ms +== a1080.mp4 sw-full run1 load 2.81 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 600 samples, 188 composites, p99 31.00 ms, max 32.15 ms, first/last mean delta 0.00 ms, signed range -32.15..21.00 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 8.13 p95 10.54 p99 11.63 ms, interval p50 40.02 p95 61.21 p99 67.56 ms +== a1080.mp4 sw-full run2 load 2.69 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 599 samples, 188 composites, p99 31.92 ms, max 33.62 ms, first/last mean delta 0.00 ms, signed range -33.62..15.10 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 8.14 p95 10.28 p99 13.28 ms, interval p50 40.10 p95 61.82 p99 68.12 ms +== a1080.mp4 sw-auto run1 load 2.58 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 596 samples, 188 composites, p99 32.40 ms, max 34.29 ms, first/last mean delta 0.00 ms, signed range -34.29..26.75 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 7.95 p95 10.04 p99 16.36 ms, interval p50 40.18 p95 60.83 p99 65.97 ms +== a1080.mp4 sw-auto run2 load 3.19 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 600 samples, 188 composites, p99 31.44 ms, max 32.50 ms, first/last mean delta 0.00 ms, signed range -32.50..21.21 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 8.18 p95 9.66 p99 13.09 ms, interval p50 40.08 p95 60.83 p99 61.80 ms +== a2160.mp4 hw-full run1 load 3.02 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 594 samples, 191 composites, p99 28.02 ms, max 28.81 ms, first/last mean delta 0.00 ms, signed range -28.81..19.38 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 11.27 p95 15.05 p99 21.98 ms, interval p50 40.12 p95 59.88 p99 74.41 ms +== a2160.mp4 hw-full run2 load 2.77 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 584 samples, 189 composites, p99 28.27 ms, max 29.40 ms, first/last mean delta 0.00 ms, signed range -29.40..18.58 ms, underruns 0 (first -1.00 s), dropped video 5, frame interval 41.71 ms +M4 audit stages: composite p50 11.23 p95 16.59 p99 19.81 ms, interval p50 40.11 p95 59.77 p99 67.19 ms +== a2160.mp4 sw-full run1 load 2.58 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 560 samples, 180 composites, p99 24.96 ms, max 25.54 ms, first/last mean delta 0.00 ms, signed range -25.54..18.79 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.29 p95 23.14 p99 29.13 ms, interval p50 40.18 p95 59.60 p99 76.60 ms +== a2160.mp4 sw-full run2 load 3.78 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 541 samples, 180 composites, p99 24.60 ms, max 25.12 ms, first/last mean delta 0.00 ms, signed range -25.12..19.96 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.38 p95 23.12 p99 36.80 ms, interval p50 40.09 p95 59.60 p99 96.06 ms +== a2160.mp4 sw-auto run1 load 4.21 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 487 samples, 177 composites, p99 23.35 ms, max 24.21 ms, first/last mean delta 0.00 ms, signed range -24.21..20.73 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.81 p95 24.54 p99 31.63 ms, interval p50 40.23 p95 59.01 p99 62.28 ms +== a2160.mp4 sw-auto run2 load 5.05 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 542 samples, 172 composites, p99 25.17 ms, max 26.10 ms, first/last mean delta 0.00 ms, signed range -26.10..18.60 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 15.11 p95 24.27 p99 37.33 ms, interval p50 40.10 p95 60.46 p99 99.25 ms +== hevc2160.mp4 hw-full run1 load 4.89 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 580 samples, 192 composites, p99 28.83 ms, max 29.71 ms, first/last mean delta 0.00 ms, signed range -29.71..19.17 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 10.71 p95 15.17 p99 21.03 ms, interval p50 40.06 p95 59.88 p99 62.18 ms +== hevc2160.mp4 hw-full run2 load 4.29 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 588 samples, 190 composites, p99 29.04 ms, max 29.48 ms, first/last mean delta 0.00 ms, signed range -29.48..21.06 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 41.71 ms +M4 audit stages: composite p50 10.65 p95 14.98 p99 20.48 ms, interval p50 40.05 p95 60.10 p99 62.39 ms +== hevc2160.mp4 sw-full run1 load 4.01 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 566 samples, 183 composites, p99 24.10 ms, max 25.06 ms, first/last mean delta 0.00 ms, signed range -25.06..19.00 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 41.71 ms +M4 audit stages: composite p50 15.77 p95 21.64 p99 28.96 ms, interval p50 40.13 p95 59.48 p99 60.64 ms +== hevc2160.mp4 sw-full run2 load 3.55 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 539 samples, 182 composites, p99 24.58 ms, max 42.90 ms, first/last mean delta 0.00 ms, signed range -24.94..42.90 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.84 p95 24.41 p99 28.33 ms, interval p50 40.05 p95 59.86 p99 65.82 ms +== hevc2160.mp4 sw-auto run1 load 3.43 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 541 samples, 185 composites, p99 24.29 ms, max 24.81 ms, first/last mean delta 0.00 ms, signed range -24.81..19.71 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.85 p95 23.82 p99 31.24 ms, interval p50 40.16 p95 59.11 p99 66.08 ms +== hevc2160.mp4 sw-auto run2 load 3.76 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 567 samples, 181 composites, p99 24.94 ms, max 25.60 ms, first/last mean delta 0.00 ms, signed range -25.60..20.52 ms, underruns 0 (first -1.00 s), dropped video 0, frame interval 41.71 ms +M4 audit stages: composite p50 15.29 p95 25.41 p99 33.18 ms, interval p50 40.07 p95 59.17 p99 60.39 ms +== vp92160.webm hw-full run1 load 3.72 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 586 samples, 191 composites, p99 28.75 ms, max 30.23 ms, first/last mean delta 0.00 ms, signed range -30.23..19.25 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 10.55 p95 14.95 p99 24.74 ms, interval p50 40.07 p95 59.98 p99 60.80 ms +== vp92160.webm hw-full run2 load 3.45 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 595 samples, 190 composites, p99 28.62 ms, max 29.54 ms, first/last mean delta 0.00 ms, signed range -29.54..17.83 ms, underruns 0 (first -1.00 s), dropped video 4, frame interval 41.71 ms +M4 audit stages: composite p50 10.56 p95 11.29 p99 15.94 ms, interval p50 40.08 p95 59.54 p99 60.72 ms +== vp92160.webm sw-full run1 load 3.07 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 568 samples, 182 composites, p99 25.10 ms, max 26.10 ms, first/last mean delta 0.00 ms, signed range -26.10..19.96 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.40 p95 20.73 p99 26.94 ms, interval p50 40.01 p95 61.36 p99 68.44 ms +== vp92160.webm sw-full run2 load 2.75 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 551 samples, 181 composites, p99 25.10 ms, max 25.81 ms, first/last mean delta 0.00 ms, signed range -25.81..20.83 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 15.65 p95 21.57 p99 27.74 ms, interval p50 40.16 p95 60.07 p99 62.28 ms +== vp92160.webm sw-auto run1 load 2.85 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 552 samples, 182 composites, p99 24.31 ms, max 25.90 ms, first/last mean delta 0.00 ms, signed range -25.90..19.65 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.45 p95 20.62 p99 22.49 ms, interval p50 39.93 p95 59.62 p99 61.54 ms +== vp92160.webm sw-auto run2 load 2.87 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 565 samples, 182 composites, p99 24.79 ms, max 25.58 ms, first/last mean delta 0.00 ms, signed range -25.58..19.25 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 15.32 p95 22.55 p99 28.62 ms, interval p50 40.10 p95 60.81 p99 67.21 ms +== av12160.mp4 hw-full run1 load 2.81 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 567 samples, 192 composites, p99 28.44 ms, max 29.15 ms, first/last mean delta 0.00 ms, signed range -29.15..20.02 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 11.16 p95 18.01 p99 24.36 ms, interval p50 40.11 p95 60.71 p99 81.64 ms +== av12160.mp4 hw-full run2 load 2.60 +M4 audit: PASS, 8 s, hardware pilot decode, PipeWire audio, 586 samples, 189 composites, p99 28.23 ms, max 30.04 ms, first/last mean delta 0.00 ms, signed range -30.04..19.96 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 41.71 ms +M4 audit stages: composite p50 11.15 p95 16.80 p99 22.80 ms, interval p50 40.04 p95 59.79 p99 102.40 ms +== av12160.mp4 sw-full run1 load 2.44 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 537 samples, 188 composites, p99 23.54 ms, max 25.08 ms, first/last mean delta 0.00 ms, signed range -25.08..20.02 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 16.47 p95 22.16 p99 25.59 ms, interval p50 39.94 p95 60.62 p99 90.28 ms +== av12160.mp4 sw-full run2 load 2.29 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 530 samples, 187 composites, p99 23.42 ms, max 24.44 ms, first/last mean delta 0.00 ms, signed range -24.44..20.23 ms, underruns 0 (first -1.00 s), dropped video 1, frame interval 41.71 ms +M4 audit stages: composite p50 16.47 p95 23.18 p99 27.88 ms, interval p50 40.07 p95 60.92 p99 74.21 ms +== av12160.mp4 sw-auto run1 load 2.19 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 508 samples, 189 composites, p99 22.96 ms, max 24.65 ms, first/last mean delta 0.00 ms, signed range -24.65..21.31 ms, underruns 0 (first -1.00 s), dropped video 3, frame interval 41.71 ms +M4 audit stages: composite p50 16.76 p95 22.94 p99 30.43 ms, interval p50 40.10 p95 59.99 p99 79.85 ms +== av12160.mp4 sw-auto run2 load 2.40 +M4 audit: PASS, 8 s, software decode, PipeWire audio, 491 samples, 188 composites, p99 22.73 ms, max 24.15 ms, first/last mean delta 0.00 ms, signed range -24.15..21.08 ms, underruns 0 (first -1.00 s), dropped video 2, frame interval 41.71 ms +M4 audit stages: composite p50 16.83 p95 23.52 p99 25.40 ms, interval p50 40.16 p95 60.12 p99 104.34 ms + +== Process CPU per played frame: getrusage CPU of an --m4-audit 9 run minus a 5 run, / 96 frames +a1080.mp4 hw cpu5 2.12s cpu9 2.74s -> 6.5 ms CPU/frame, 0.16 cores +a1080.mp4 sw cpu5 7.30s cpu9 10.27s -> 31.0 ms CPU/frame, 0.74 cores +a2160.mp4 hw cpu5 3.52s cpu9 4.22s -> 7.3 ms CPU/frame, 0.18 cores +a2160.mp4 sw cpu5 34.40s cpu9 56.41s -> 229.6 ms CPU/frame, 5.50 cores +hevc2160.mp4 hw cpu5 2.79s cpu9 3.33s -> 5.6 ms CPU/frame, 0.13 cores +hevc2160.mp4 sw cpu5 19.89s cpu9 28.42s -> 88.9 ms CPU/frame, 2.13 cores +vp92160.webm hw cpu5 2.73s cpu9 3.41s -> 7.1 ms CPU/frame, 0.17 cores +vp92160.webm sw cpu5 15.20s cpu9 17.86s -> 27.7 ms CPU/frame, 0.66 cores +av12160.mp4 hw cpu5 1.71s cpu9 2.22s -> 5.3 ms CPU/frame, 0.13 cores +av12160.mp4 sw cpu5 6.80s cpu9 9.97s -> 33.0 ms CPU/frame, 0.79 cores + +== Seek (playing) and scrub (paused), 24 seeks each +-- a1080.mp4 hw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 3.26 p95 4.77 max 5.04 ms, first composited frame p50 147.51 p95 310.25 max 320.17 ms, 0 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 65.52 p95 270.18 max 301.68 ms, +-- a1080.mp4 sw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 3.28 p95 83.76 max 99.47 ms, first composited frame p50 190.10 p95 451.53 max 469.54 ms, 3 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 9.05 p95 13.03 max 15.48 ms, +-- a2160.mp4 hw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 9.10 p95 12.97 max 69.23 ms, first composited frame p50 258.89 p95 520.24 max 520.24 ms, 7 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 331.00 p95 1322.73 max 1481.29 ms, +-- a2160.mp4 sw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 77.19 p95 105.28 max 116.59 ms, first composited frame p50 229.54 p95 525.20 max 525.20 ms, 12 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 3.89 p95 24.34 max 26.37 ms, +-- hevc2160.mp4 hw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 3.18 p95 4.44 max 14.14 ms, first composited frame p50 119.04 p95 253.88 max 301.57 ms, 0 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 132.15 p95 253.36 max 274.77 ms, +-- hevc2160.mp4 sw +M4 seek audit: 24 seeks, PipeWire audio, UI blocked p50 71.14 p95 101.71 max 104.65 ms, first composited frame p50 92.91 p95 436.70 max 436.70 ms, 11 without a frame in 500 ms +M4 scrub audit: 24 paused seeks, null audio, UI event-loop gap p50 7.78 p95 25.03 max 31.01 ms, + +== Export (20 s 1080p H.264 + AAC source, default profile) and timeline (--m6-timeline-audit N) +export audit: 479 frames in 7670 ms (62.5 fps) -> /tmp/claude-1000/-home-kitsune-Projects-Omarchy-OmaMovie/cdc87586-0120-483d-b992-eab1ba70f607/scratchpad/out_a1080_1.mp4 + encoder: VA-API H.264 (GPU) + per frame: build 0.26 ms, render+readback 7.46 ms, convert 0.00 ms, encode 7.04 ms, audio 1.21 ms + result: written +RU cpu 26.999 s peakRSS 355 MB exit 0 +export audit: 479 frames in 7394 ms (64.8 fps) -> /tmp/claude-1000/-home-kitsune-Projects-Omarchy-OmaMovie/cdc87586-0120-483d-b992-eab1ba70f607/scratchpad/out_a1080_2.mp4 + encoder: VA-API H.264 (GPU) + per frame: build 0.28 ms, render+readback 7.29 ms, convert 0.00 ms, encode 6.68 ms, audio 1.14 ms + result: written +RU cpu 26.454 s peakRSS 359 MB exit 0 +M6 timeline audit: 1000 clips, model build 2.0 ms, open 95.0 ms (save, load, reimport, UI), RSS 367000 kB, peak 367000 kB + seek p50 16.5 p95 33.4 max 33.4 ms + select p50 12.3 p95 40.7 max 40.7 ms + split p50 19.4 p95 53.0 max 53.0 ms + ripple del p50 18.8 p95 42.0 max 42.0 ms + undo p50 16.5 p95 39.9 max 40.2 ms + trim drag: 100 pointer events, 25 scope updates + drag event p50 16.7 p95 16.9 max 32.3 ms + trim, undo p50 22.4 p95 22.4 max 22.4 ms +RU cpu 5.025 s peakRSS 358 MB exit 0 +M6 timeline audit: 5000 clips, model build 34.9 ms, open 194.4 ms (save, load, reimport, UI), RSS 595416 kB, peak 595416 kB + seek p50 12.6 p95 33.2 max 33.2 ms + select p50 11.6 p95 19.4 max 19.4 ms + split p50 36.8 p95 135.6 max 135.6 ms + ripple del p50 21.3 p95 107.6 max 107.6 ms + undo p50 29.2 p95 128.1 max 130.4 ms + trim drag: 100 pointer events, 25 scope updates + drag event p50 16.6 p95 17.0 max 17.2 ms + trim, undo p50 31.2 p95 31.2 max 31.2 ms +RU cpu 6.614 s peakRSS 581 MB exit 0 diff --git a/Docs/Research/evidence/2026-10-14-m10-effect-pass-cost.txt b/Docs/Research/evidence/2026-10-14-m10-effect-pass-cost.txt new file mode 100644 index 0000000..c000c0b --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-m10-effect-pass-cost.txt @@ -0,0 +1,22 @@ +M10 effects contract: pass cost per shipped effect (2026-10-14) + +Intel Iris Xe (TGL GT2), Mesa 26.2.2, release build. compositor_tests "measures each effect +pass at 1080p and 4K": one decoded 1080p H.264 layer (screenrecording_like.mp4) filling the +output, 20 warmed renders per case, submit to completion. Three runs; deltas against "no effect". + +Before the reduce-down change: + 1080p no effect 2.43-2.46 ms; each look -0.15..+0.58 (noise); blur (detail -0.6/-1.0) -0.2..+0.5; + sharpen (+0.6) +4.87 / +4.97 / +5.40 ms + 4K no effect 8.23-8.87 ms; each look -0.84..+0.79 (noise); blur -1.9..-3.2; + sharpen +6.50 / +7.03 / +8.14 ms +After (ReduceDown skipped when the detail factor is 1, an identity full-size copy): + 1080p sharpen +4.91 / +3.77 / +4.34 ms (mean 5.08 -> 4.34) + 4K sharpen +6.79 / +6.83 / +7.55 ms (mean 7.22 -> 7.06, within noise) + +Reading: looks are fused in the layer pass and cost nothing measurable. Blur reduces the source +first, so the composite reads a small intermediate and can come out faster than no effect. +Sharpen runs at full source resolution (sigma 1.2 px at 1080p, factor 1): linearize, two +9-tap gaussian passes and the composite reading both images; at 1080p60 it takes about a +quarter to a third of the 16.7 ms frame on this iGPU. Further options, not taken: bilinear +pair sampling (5 fetches instead of 9 per pass, changes border taps against the CPU reference) +or a fused 2-pass blur at full resolution. Memory per pass was not measured. diff --git a/Docs/Research/evidence/2026-10-14-m10-sustained-cycles.txt b/Docs/Research/evidence/2026-10-14-m10-sustained-cycles.txt new file mode 100644 index 0000000..342fd3b --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-m10-sustained-cycles.txt @@ -0,0 +1,22 @@ +M10 sustained workload, bounded headless pass (2026-10-14) + +tests/app/test_sustained.cpp: each cycle opens a Session on the 1 s camera fixture, splits, +plays 150 ms, saves the project, exports it in software (320x180, 30 frames) and destroys the +Session. Descriptors (/proc/self/fd) and VmRSS are read after each cycle. +Intel Iris Xe, Mesa 26.2.2, debug build at the commit adding the test. + +OMA_SUSTAINED_CYCLES=30, debug build (every third cycle shown): + cycle 0: 5 fds, 133568 KiB cycle 15: 5 fds, 149460 KiB + cycle 3: 5 fds, 144412 KiB cycle 18: 5 fds, 151444 KiB + cycle 6: 5 fds, 148344 KiB cycle 21: 5 fds, 149888 KiB + cycle 9: 5 fds, 152988 KiB cycle 24: 5 fds, 152568 KiB + cycle 12: 5 fds, 151704 KiB cycle 27: 5 fds, 150448 KiB +Descriptors constant; resident memory settles near 150 MB after about nine cycles (allocator, +Mesa and FFmpeg pools warming), then wanders within ~3 MB: no growth per cycle. + +Default 8 cycles in the suite (fails on any descriptor growth after two warm-up cycles, or +64 MiB of resident growth): debug 3.9 s, TSan 5 s (379 -> 424 MiB, tapering), ASan 7.8 s +(resident bound skipped: quarantine grows ~40 MiB per cycle by design; LSan checks leaks). + +Not covered: the long-form gate (hours of media, interaction latency percentiles, VRAM, cache +and disk use) and a committed per-machine baseline. diff --git a/Docs/Research/evidence/2026-10-14-m10-validation-layers.txt b/Docs/Research/evidence/2026-10-14-m10-validation-layers.txt new file mode 100644 index 0000000..20b0a1e --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-m10-validation-layers.txt @@ -0,0 +1,68 @@ +M10 concurrency/lifetime: Vulkan validation layers over the test suites (2026-10-14) + +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2-arch1.1, Vulkan 1.4.354, +vulkan-validation-layers 1.4.357.0-1. Debug build at commit 383eb9a. +The layer was confirmed inserted (VK_LOADER_DEBUG=layer: instance and device layer). + +Run 1, core validation: + VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation + gpu_tests, compositor_tests, app_tests (all, incl. the Session stress tests): exit 0, + 0 "Validation Error". + +Run 2, synchronization validation + best practices, errors/warnings/perf reported: + VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT: + VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT + VK_LAYER_REPORT_FLAGS=error,warn,perf + compositor_tests: exit 0, 0 errors, 0 SYNC-HAZARD. + 26 BestPractices-vkBindImageMemory-small-dedicated-allocation + 13 BestPractices-vkBindBufferMemory-small-dedicated-allocation + (known: VMA evaluated and not adopted, 16 setup-time allocations, M2) + 20 BestPractices-ImageBarrierAccessLayout + (gpu::transition uses ALL_COMMANDS with MEMORY_READ|WRITE for every layout change: + conservative and correct; narrowing it is an unmeasured optimization, left as is) + 3 VALIDATION-SETTINGS (settings given by environment variables) + app_tests and gpu_tests with synchronization validation (error,warn): exit 0, 0 errors, + 0 SYNC-HAZARD; only VALIDATION-SETTINGS notices. + +Not covered: the live Qt window (presentation, swapchain resize) under validation, which +needs the GUI smoke with the layer; NVIDIA/AMD drivers. + +Live window (same day), synchronization validation, errors only: + make run-gui RUN_GUI_SMOKE=1: PASS, but 7x UNASSIGNED-non-acquired-swapchain-image-used, + 7x SYNC-HAZARD-WRITE-AFTER-READ and 6x SYNC-HAZARD-WRITE-AFTER-PRESENT, all on Qt's own + swapchain frame (a layout transition / render pass on a presentable image whose acquire + semaphore the submit did not wait on). OmaMovie never writes swapchain images. + - Same counts with OMA_PREVIEW_HARDWARE=0: not the hardware-decode producer thread. + - A temporary marker before each smoke grabWindow() call: every error triple follows one of + the 7 grabWindow() calls, and nothing else in the run reports. + - omamovie --m4-audit on a 36 s recording, 10 s of playback, hardware decode on: 0 errors. + - Qt-only controls (qml6 with an animation; a QQuickView calling grabWindow() every 400 ms, + also while resizing every 150 ms), Vulkan RHI: 0 errors. + So the hazards come from grabWindow() in this app's window: Qt's grab path combined with + OmaMovie's frame hooks (queue hold from afterRendering to afterFrameEnd, compositor work in + sync), which the controls do not have. Normal use never calls grabWindow(); main.cpp already + notes that it disturbed validation. Attribution between Qt and the hooks is not settled. + +Attribution narrowed (same day): + - The smoke with OmaMovie's frame hooks disabled (no queue hold, admission left open): the same + 20 errors. Not the hooks. + - Qt-only controls under the threaded and the basic render loop: 0 errors. + - A minimal control with only oma::gpu::Device adopted by Qt (QVulkanInstance::setVkInstance + + QQuickGraphicsDevice::fromDeviceObjects, as main.cpp does), an animated QML item and + grabWindow() every 400 ms: 10 grabs, 10 error triples. The same program with Qt's own device: + 0. Telling Qt the instance is Vulkan 1.1 instead of 1.4 changes nothing. + Conclusion: grabWindow() on a window whose Vulkan device Qt adopted from OmaMovie (ADR-0005) + submits Qt's swapchain frame without waiting for the acquire semaphore, per the validation + layer. Normal frames on that device are clean. Not yet known whether a device property + (OmaMovie enables every supported feature and its interop/video extensions, which Qt cannot + see on an adopted device) or Qt's grab path for adopted devices is the trigger; the next step + is bisecting DeviceOptions/extensions in that control, or a Qt bug report with it. + +Bisect in that control (temporary, uncommitted switches in device.cpp, reverted): + default device: 27 errors; without the optional interop/video/descriptor-buffer extensions: 30; + with every optional feature off (core, 1.1-1.4; only timelineSemaphore and synchronization2, + which gpu::Device requires): 31; both: 30 (counts vary with how many frames a grab overlaps). + Extensions and features are ruled out. Left: OmaMovie's VkInstance (Qt adopts it too), the two + required features, and creating every queue of every family; or Qt's grab path for adopted + devices. Not pursued further: normal frames are clean and only grabWindow() triggers it. + diff --git a/Docs/Research/evidence/2026-10-14-m11-baseline.txt b/Docs/Research/evidence/2026-10-14-m11-baseline.txt new file mode 100644 index 0000000..592cab9 --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-m11-baseline.txt @@ -0,0 +1,66 @@ +M11 baseline before ownership/UI refactors (2026-10-14) + +Machine: Intel Iris Xe (TGL GT2), Mesa 26.2.2, Hyprland (live session), PipeWire. +Build: release at commit dc8cadd. Media (reproducible, not committed): + ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=60:duration=30 \ + -f lavfi -i sine=frequency=440:sample_rate=48000:duration=30 \ + -c:v libx264 -preset veryfast -pix_fmt yuv420p -c:a aac -shortest baseline_1080p60.mp4 + +Playback: omamovie --m4-audit baseline_1080p60.mp4 20 (hardware decode, two runs) + run 1: PASS, 1190 composites, A/V p99 12.46 ms, max 18.71 ms, underruns 0, dropped video 2 + Qt frame whole p50 8.75 p99 17.47 ms; composite p50 5.92 p95 7.57 p99 8.29 ms; + UI tick p50 0.02 p99 1.57 ms, tick gap p50 8.18 p99 15.05 ms + run 2: PASS, 1183 composites, A/V p99 9.85 ms, max 14.77 ms, underruns 0, dropped video 8 + Qt frame whole p50 7.45 p99 18.26 ms; composite p50 6.04 p95 7.64 p99 8.91 ms + +Seeking: omamovie --m4-seek-audit baseline_1080p60.mp4 30 + UI blocked p50 3.05 p95 4.23 max 5.69 ms; + first composited frame p50 207 ms, p95 420 ms, max 444 ms; 0 seeks without a frame in 500 ms. + The first frame after a seek is the slowest interaction measured here (decode from the + previous keyframe of a 1080p60 H.264 GOP); a candidate for M11's measured responsiveness work. + +Timeline scale: omamovie --m6-timeline-audit 1000 + 1000 clips: model build 2.4 ms, open 92.3 ms (save, load, reimport, UI), RSS 370 MB. + +Sustained cycles (headless): Docs/Research/evidence/2026-10-14-m10-sustained-cycles.txt. +Sizes and change coupling: Docs/analysis/m11-inventory-2026-10-14.md. +Not recorded yet: screenshots and keyboard walkthroughs at wide, half-width and 640 px with +a larger font (the GUI smoke checks the 640 px layout fits). + +First measured change (same machine, fixture and release build): seeking now skips +non-reference frames that end before the target (AVDISCARD_NONREF), redoing the seek without +skipping if a skipped frame was the one on screen. --m4-seek-audit baseline_1080p60.mp4 30, +two runs each, hardware decode: + before: first frame p50 198.9 / 208.4 ms, p95 392.0 / 378.4 ms, max 436.8 / 435.6 ms + after: first frame p50 152.5 / 160.5 ms, p95 292.1 / 280.8 ms, max 324.3 / 368.6 ms + (about -23 % p50, -26 % p95). Software decode after the change: p50 109 ms, p95 194 ms, + faster than VA-API for seeks on this GOP (worth a look: per-frame hardware latency). +Exactness: tests/media seeks every frame of h264_vfr.mkv, h264_29.97fps.mp4 and hevc_10bit.mp4 +at its time and mid-gap; skipping on pts <= target without the redo gives 38/28/28 wrong frames. + +Second measured change: seeking during playback with software decode on 4K. Fixture (not +committed): ffmpeg -f lavfi -i testsrc2=size=3840x2160:rate=30:duration=20 -f lavfi -i +sine=frequency=440:sample_rate=48000:duration=20 -c:v libx265 -preset ultrafast +-pix_fmt yuv420p10le -c:a aac -shortest hevc4k10.mp4 (GOP 8.3 s, B-frames). +--m4-seek-audit hevc4k10.mp4 20 (seeks while playing; "UI blocked" is the restart on the UI +thread, which joins the video producer): + software, before: UI blocked p50 173 ms, p95 799 ms; first frame p50 228 ms; 14 of 20 seeks + without a frame in 500 ms + software, after: UI blocked p50 25 ms, p95 77 ms; first frame p50 223 ms; 13 of 20 without + hardware, after: UI blocked p50 3.3 ms, p95 8.1 ms; first frame p50 203 ms, 0 without +The producer's seek decoded forward up to a whole GOP inside VideoDecoder::next() without +looking at cancellation, so stop() waited for it; the decoder now checks an interrupt between +decoded frames, the scheduler ties it to its job's cancellation, and FrameSource drops a stream +stopped mid-seek. Software decode stays too slow for 4K HEVC seeks (decode throughput), so the +paused/scrub policy is not switched to software despite its faster 1080p H.264 seeks. + +Third change: scrubbing the paused viewer (software decode, the default on GPUs not yet +validated for hardware decode). A temporary variant of --m4-seek-audit (not committed) paused +the editor and issued bursts of five seeks ~15 ms apart, timing the last one's frame; +baseline_1080p60.mp4, 15 bursts, two runs each: + before: final frame p50 190.8 / 189.2 ms, p95 285.8 / 295.9 ms + after: final frame p50 114.9 / 122.0 ms, p95 206.8 / 208.2 ms +A newer paused-viewer request now stops the frame in flight between decoded frames (the same +decoder interrupt), instead of letting a superseded seek finish its GOP of catch-up. +tests/app/test_frame_source_interrupt.cpp scrubs a 10 s one-keyframe clip; treating the +superseded frame as an error makes it fail. diff --git a/Docs/Research/evidence/2026-10-14-professional-workload-spike.txt b/Docs/Research/evidence/2026-10-14-professional-workload-spike.txt new file mode 100644 index 0000000..e92fdb2 --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-professional-workload-spike.txt @@ -0,0 +1,48 @@ +Professional workload spike: first 4K run (2026-10-14) +Code: 0e12ece plus uncommitted professional_workload.cpp and current workspace changes. +Build: CMake spikes preset, CMAKE_BUILD_TYPE=Release, target professional_workload_spike. +Host: Intel i5-1135G7, Iris Xe (TGL GT2), Mesa 26.2.2, kernel 7.2.5-4-omarchy, +FFmpeg n9.0.1. Power online=1; load observed shortly after run=13.49 8.10 6.66. +One run only; no controlled cold/warm cache or paired baseline. The same source file is +opened by three independent decoders, so filesystem cache reuse is likely. +Source: /home/kitsune/.cache/omamovie-bench/fixtures/dec_hevc10_2160.mp4 +SHA-256: 6cbe223ace0704af44a297bc126766387de7b6a2e960e6a141e1040ef6ea647d +Source: 3840x2160, HEVC Main 10, 24000/1001 fps; color tags unspecified. +Command: + build/spikes/tools/spikes/professional_workload_spike 3840 2160 24 24 hardware \ + /home/kitsune/.cache/omamovie-bench/fixtures/dec_hevc10_2160.mp4 \ + /home/kitsune/.cache/omamovie-bench/fixtures/dec_hevc10_2160.mp4 \ + /home/kitsune/.cache/omamovie-bench/fixtures/dec_hevc10_2160.mp4 + +Raw diagnostic output (application log lines retained): +02:12:37.760 INFO gpu device: Intel(R) Iris(R) Xe Graphics (TGL GT2) (Intel open-source Mesa driver, Mesa 26.2.2-arch1.1, /dev/dri/renderD128), Vulkan 1.4, 9 extensions, internally synchronized queues: yes (device.cpp:367) +02:12:37.761 INFO gpu advertised: DMA-BUF true, DRM modifiers true, external semaphore fd true, video decode queue false, video codec operations 0x0 (device.cpp:375) +02:12:37.793 INFO decode dec_hevc10_2160.mp4: hevc VA-API to Vulkan decode (video_decoder.cpp:550) +02:12:37.798 INFO decode dec_hevc10_2160.mp4: hevc VA-API to Vulkan decode (video_decoder.cpp:550) +02:12:37.803 INFO decode dec_hevc10_2160.mp4: hevc VA-API to Vulkan decode (video_decoder.cpp:550) +device=Intel(R) Iris(R) Xe Graphics (TGL GT2) output=3840x2160 deadline=41.67 ms mode=hardware frames=24 +source0=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +source1=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +source2=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +decode p50=23.10 p95=33.03 p99=34.89 max=82.98 ms +composite p50=41.89 p95=47.17 p99=51.73 max=56.94 ms +sequential-total p50=64.72 p95=76.58 p99=77.05 max=134.72 ms +sequential-over-deadline=24/24 throughput=14.7 fps cpu=5.7 ms/frame peak-rss=733544 KiB + +This is sequential decoder + synchronous compositor library work, without Qt presentation, +audio or export. The 24/24 count is deadline overruns in that loop, not dropped frames in +the editor. The 24 fps nominal budget of 41.67 ms is close to the source's 23.976 fps frame +interval (41.71 ms), but not identical. Do not use this one loaded run to claim the app +cannot play a three-layer scene in real time; a scheduler may overlap decode and render. + +Second run after rebuilding the final spike source, same input and command, 2026-10-14. +The host load was not controlled; this run is corroboration of the bottleneck and a +demonstration of timing variability, not a paired benchmark: +device=Intel(R) Iris(R) Xe Graphics (TGL GT2) output=3840x2160 deadline=41.67 ms mode=hardware frames=24 +source0=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +source1=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +source2=3840x2160 codec=hevc depth=10 nominal-fps=23.976 path=VA-API to Vulkan +decode p50=14.16 p95=25.35 p99=25.90 max=34.16 ms +composite p50=29.67 p95=31.43 p99=31.43 max=42.41 ms +sequential-total p50=43.03 p95=56.10 p99=58.09 max=62.99 ms +sequential-over-deadline=19/24 throughput=22.5 fps cpu=3.7 ms/frame peak-rss=733544 KiB diff --git a/Docs/Research/evidence/2026-10-14-session-stress.txt b/Docs/Research/evidence/2026-10-14-session-stress.txt new file mode 100644 index 0000000..b50cab8 --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-session-stress.txt @@ -0,0 +1,21 @@ +Session stress, 2026-10-14, commit 0e12ece plus dirty workspace changes. +Command: tools/bench/stress/run.sh 3 /tmp/omamovie-stress-intel-20261014 +Host: Intel Iris Xe (TGL GT2), Mesa 26.2.2, Linux 7.2.5-4-omarchy. +Build: debug app_tests; fixture SHA-256 +263600d970638826c89ac6d31c35435371281ff8c664feabb0092e39279cdaa3. +The recorded host load was 16.36 16.04 12.01. Timings are diagnostics, not a speed claim. + +Three rounds, seeds 9945, 17864 and 25783. Each round passed: +- two seeded transport/edit and project-switch tests; +- export cancellation; +- shutdown during playback/export; +- eight repeated open/edit/play/save/export/close cycles with FD and RSS checks. +All 15 selected test executions passed. Peak process RSS across cases: 177-234 MiB. +Full per-case output: /tmp/omamovie-stress-intel-20261014/summary.txt and round logs. + +An initial sandbox run used llvmpipe rather than the Intel GPU. Its resource test failed +at cycle 4: five FDs throughout, RSS 267100 KiB at cycle 1 and 337668 KiB at cycle 4, +exceeding the test's 64 MiB post-warmup allowance. The same resource test passed for +eight cycles on the real Intel GPU (five FDs throughout; RSS 176140 KiB at cycle 1 and +168960 KiB at cycle 7). This isolates the observed failure to the llvmpipe run; it does +not establish whether the increase was a driver cache or a leak in that path. diff --git a/Docs/Research/evidence/2026-10-14-timeline-5000-stalls.txt b/Docs/Research/evidence/2026-10-14-timeline-5000-stalls.txt new file mode 100644 index 0000000..0964184 --- /dev/null +++ b/Docs/Research/evidence/2026-10-14-timeline-5000-stalls.txt @@ -0,0 +1,56 @@ +5,000-clip edit p95: code regression ruled out, isolated stalls found (2026-10-14) + +Machine: i5-1135G7, Iris Xe, Mesa 26.2.2, Qt 6.11.2, eDP-1 1920x1080 (Hyprland tiles the window +to the screen), AC power, governor powersave, profile balanced. BUILD=release. +Command: omamovie --m6-timeline-audit 5000 (whole sequence fitted; 20 rounds of seek, select, +split, ripple delete, undo; each timed to the end of the first Qt frame after the call). + +1. Current code (1865c38), 3 runs: split p95 135.6 / 138.3 / 146.9, ripple 107.6 / 108.2 / + 108.6, undo 128.1 / 130.6 / 125.5 ms; p50 split 36-37, ripple 21, undo 29 ms. +2. The first commit with the audit (1d7a618, 2026-10-07), built today with WERROR=0 (newer GCC + warns in libs/project), 2 runs: split p95 135.0 / 131.9, ripple 110.5 / 109.9, undo + 99.6 / 99.1 (max 130.8 / 128.7), select p95 108.2 / 108.4, model build 1086 / 1055 ms. + The 2026-10-06 evidence (split p95 25.3, ripple 20.2, undo 17.9) used a 1600x900 window and + predates the committed audit. Same code, today's conditions, same p95: the gap is not a + code regression between 2026-10-07 and now. Which condition changed (window size, power + state, a temporary audit variant) is not established; pacman's log shows no Qt or Mesa + upgrade after 2026-10-05. +3. Raw samples (temporary print, not committed), two runs of the current code: + split 62 34 43 43 38 39 18 39 39 17 38 140 40 40 38 17 37 42 17 41 + 53 33 44 44 39 40 18 39 39 17 38 137 41 40 40 18 38 45 18 38 + ripple 33 24 24 108 25 25 22 21 25 22 25 25 26 25 21 22 25 25 21 25 + 26 29 26 107 25 25 21 22 25 22 25 25 26 26 22 22 26 24 22 25 + undo (40 per run) one to three samples of 114-137 ms, the rest 16-40 ms + select run 1: 114 and 110 in rounds 15 and 19, run 2: none above 20 ms + Each operation's p95 over 20 samples is one isolated sample. The split and ripple stalls + fall in the same round in both runs (deterministic, data-dependent); select, which changes + no structure, also stalled once. Typical structural edits cost 17-45 ms end to end. + QV4_MM_STATS=1 printed nothing in this build, so the QML garbage collector is neither + confirmed nor excluded. + +Conclusion: the 5,000-clip gate (p95 < 100 ms) still fails, but the hypothesis "structural +operations plus model/UI update exceed the budget" is rejected for the typical edit; the +failure is a ~110-140 ms stall in specific rounds. Next: time the phases (command, model +mutation, notifications, QML delegates, first frame) of the stalled rounds only. + +== Cause and fix (same day) +Phase stamps (temporary): in a stalled sample the edit call took 17-37 ms and the frame showing +it synced and ended by ~24-40 ms; the audit's loop then saw nothing until ~108-140 ms, so the +GUI thread was busy after the frame. A hypothesis that the audit raced with frame begin was +tested by waiting for the first frame synced after the edit instead: the stalls stayed, so it +was rejected and that change reverted. +A timed QGuiApplication::notify (temporary) found the long events: QEvent::MetaCall functors +posted to QQmlApplicationEngine, 84-105 ms each. Five main-thread stacks captured under gdb +50 ms into such an event (temporary watchdog sending SIGUSR1): all in +QV4::GCStateMachine::transition -> QMetaType::destroy(QList) -> ~QVariant(QMap): the QML engine's incremental garbage collector freeing whole clip lists, a sweep step +QV4_GC_TIMELIMIT=5 did not shorten. Main.qml had nine bindings reading `session.clips.length` +(menu enable states), each handing JS a reference to the 5,000-map list. +Fix (72cc2ca): Session::clipCount (int, same NOTIFY) for those bindings. 3 runs, 5,000 clips: + split p95 90.4 / 92.9 / 84.4 (was 136-147), ripple 43.1 / 33.7 / 33.4 (108), undo 33.0 / + 33.3 / 33.8 (126-131), seek 25, select 25-26, trim drag 16.9-17.0; RSS 388-399 MB (581-612). +The gate (p95 < 100 ms) passes. Split keeps one ~85-93 ms sample per run, not yet explained. +Remaining split sample, 3 more runs at 535af7e (load 0.8): split p95 94.2 / 36.7 / 38.8 ms, +ripple 34.5 / 33.5 / 33.5, undo 36.0 / 33.5 / 32.9. The ~90 ms split sample is intermittent (1 of +3 runs here; with a timed notify() it did not occur in 2 runs). Not chased further: every run +passes the gate. If it matters later, the same notify()/gdb method applies. diff --git a/Docs/Research/evidence/2026-10-15-cross-editor-after-export-work.txt b/Docs/Research/evidence/2026-10-15-cross-editor-after-export-work.txt new file mode 100644 index 0000000..6faf193 --- /dev/null +++ b/Docs/Research/evidence/2026-10-15-cross-editor-after-export-work.txt @@ -0,0 +1,78 @@ +Cross-editor rerun after the export work (2026-10-15): OmaMovie 066f14f vs MLT melt 7.40 (Kdenlive 26.08) +Commands: tools/bench/cross-editor/run.sh 5 DIR whole; run.sh 5 DIR cuts (raw reports below, app log +lines removed). Same machine, fixture and checks as 2026-10-14 (cross-editor-export/-cuts). +OmaMovie now encodes on its own worker and reads VA-API frames back as GPU-made NV12. + +Caveat: load average 2 at the start, 8.5-11 for most of the run (another session active); +order alternated per round. Treat sub-second differences as noise. + +Summary (median wall of 5, all runs completed; frames and worst luma PSNR): + whole file (479 frames) cuts (256 frames) + OmaMovie VA-API 6.0 s 479/479 47.7 dB 4.9 s 256/256 44.4 dB + melt VA-API 6.0 s 480/479 48.7 dB 4.8 s 256/256 45.1 dB + OmaMovie x264 19.7 s 479/479 44.4 dB 11.7 s 256/256 42.0 dB + melt x264 16.5 s 480/479 44.8 dB 10.5 s 256/256 42.2 dB +Before the export work (2026-10-14): OmaMovie VA-API 9.9 s / 6.7 s, x264 20.1 s / 12.4 s. +VA-API now matches melt within noise; x264 stays 12-20% slower (OmaMovie hands libx264 RGBA +and converts on the CPU; the NV12 path is VA-API only). melt still adds a frame to the whole file. + +Cross-editor export 2026-10-14 23:58:40 -0300, 5 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.2.4 () +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 2.08 5.58 10.04 +editors: OmaMovie 066f14f (dirty); melt 7.40.0 (Kdenlive 26.08.0) +scene: whole; source: xed_1080p24_bt709.mp4 sha256 2c18c4d39be559a6, 479 frames +round 1 oma hardware: measure: rc=0 wall_s=5.53 user_s=15.21 sys_s=1.38 peak_rss_mb=416 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=28619542 psnr_y:47.706526 verdict=pass +round 1 melt hardware: measure: rc=0 wall_s=5.71 user_s=14.07 sys_s=0.38 peak_rss_mb=350 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 1 oma software: measure: rc=0 wall_s=17.55 user_s=110.82 sys_s=3.53 peak_rss_mb=1030 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 1 melt software: measure: rc=0 wall_s=15.83 user_s=112.98 sys_s=0.86 peak_rss_mb=932 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 2 melt software: measure: rc=0 wall_s=18.44 user_s=114.27 sys_s=1.06 peak_rss_mb=932 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 2 oma software: measure: rc=0 wall_s=21.37 user_s=126.65 sys_s=4.47 peak_rss_mb=1031 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 2 melt hardware: measure: rc=0 wall_s=6.73 user_s=16.61 sys_s=0.42 peak_rss_mb=350 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 2 oma hardware: measure: rc=0 wall_s=6.02 user_s=19.78 sys_s=1.47 peak_rss_mb=412 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=28619542 psnr_y:47.706526 verdict=pass +round 3 oma hardware: measure: rc=0 wall_s=5.53 user_s=19.12 sys_s=1.36 peak_rss_mb=412 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=28619542 psnr_y:47.706526 verdict=pass +round 3 melt hardware: measure: rc=0 wall_s=5.98 user_s=15.02 sys_s=0.36 peak_rss_mb=353 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 3 oma software: measure: rc=0 wall_s=23.93 user_s=129.88 sys_s=4.71 peak_rss_mb=1037 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 3 melt software: measure: rc=0 wall_s=17.13 user_s=114.80 sys_s=0.88 peak_rss_mb=940 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 4 melt software: measure: rc=0 wall_s=16.45 user_s=114.56 sys_s=0.88 peak_rss_mb=937 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +round 4 oma software: measure: rc=0 wall_s=18.62 user_s=124.48 sys_s=3.83 peak_rss_mb=1053 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 4 melt hardware: measure: rc=0 wall_s=5.96 user_s=15.31 sys_s=0.36 peak_rss_mb=352 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 4 oma hardware: measure: rc=0 wall_s=6.41 user_s=20.64 sys_s=1.59 peak_rss_mb=417 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=28619542 psnr_y:47.706526 verdict=pass +round 5 oma hardware: measure: rc=0 wall_s=6.34 user_s=20.09 sys_s=1.65 peak_rss_mb=417 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=28619542 psnr_y:47.706526 verdict=pass +round 5 melt hardware: measure: rc=0 wall_s=5.97 user_s=15.34 sys_s=0.41 peak_rss_mb=351 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=30340364 psnr_y:48.748531 verdict=FAIL(frames 480 != 479) +round 5 oma software: measure: rc=0 wall_s=19.69 user_s=125.75 sys_s=4.08 peak_rss_mb=1026 | frames=479/479 video_s=19.978292 audio_s=19.989333 bytes=16686227 psnr_y:44.420869 verdict=pass +round 5 melt software: measure: rc=0 wall_s=15.90 user_s=113.76 sys_s=0.80 peak_rss_mb=930 | frames=480/479 video_s=20.020000 audio_s=20.032000 bytes=19490894 psnr_y:44.774165 verdict=FAIL(frames 480 != 479) +load at end: 10.47 8.48 9.69 + +Cross-editor export 2026-10-15 00:06:04 -0300, 5 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.2.4 () +ffmpeg version n9.0.1 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 10.47 8.48 9.69 +editors: OmaMovie 066f14f (dirty); melt 7.40.0 (Kdenlive 26.08.0) +scene: cuts; source: xed_1080p24_bt709.mp4 sha256 2c18c4d39be559a6, 479 frames +round 1 oma hardware: measure: rc=0 wall_s=4.37 user_s=14.10 sys_s=1.21 peak_rss_mb=634 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=15141105 verdict=pass cut frames compared=256 worst psnr_y:44.35 at n:230 +round 1 melt hardware: measure: rc=0 wall_s=4.90 user_s=17.91 sys_s=0.57 peak_rss_mb=654 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 1 oma software: measure: rc=0 wall_s=11.89 user_s=72.54 sys_s=2.59 peak_rss_mb=1221 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 1 melt software: measure: rc=0 wall_s=10.27 user_s=68.32 sys_s=0.81 peak_rss_mb=1235 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 2 melt software: measure: rc=0 wall_s=10.53 user_s=69.07 sys_s=0.89 peak_rss_mb=1241 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 2 oma software: measure: rc=0 wall_s=11.68 user_s=71.87 sys_s=2.63 peak_rss_mb=1229 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 2 melt hardware: measure: rc=0 wall_s=4.64 user_s=17.37 sys_s=0.52 peak_rss_mb=653 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 2 oma hardware: measure: rc=0 wall_s=4.97 user_s=16.68 sys_s=1.37 peak_rss_mb=591 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=15141105 verdict=pass cut frames compared=256 worst psnr_y:44.35 at n:230 +round 3 oma hardware: measure: rc=0 wall_s=4.92 user_s=16.53 sys_s=1.31 peak_rss_mb=587 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=15141105 verdict=pass cut frames compared=256 worst psnr_y:44.35 at n:230 +round 3 melt hardware: measure: rc=0 wall_s=5.44 user_s=19.14 sys_s=0.58 peak_rss_mb=656 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 3 oma software: measure: rc=0 wall_s=11.74 user_s=72.46 sys_s=2.80 peak_rss_mb=1190 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 3 melt software: measure: rc=0 wall_s=10.94 user_s=68.20 sys_s=0.81 peak_rss_mb=1235 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 4 melt software: measure: rc=0 wall_s=10.27 user_s=68.52 sys_s=0.81 peak_rss_mb=1228 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +round 4 oma software: measure: rc=0 wall_s=12.46 user_s=72.59 sys_s=2.98 peak_rss_mb=1199 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 4 melt hardware: measure: rc=0 wall_s=4.70 user_s=17.70 sys_s=0.55 peak_rss_mb=654 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 4 oma hardware: measure: rc=0 wall_s=4.93 user_s=16.70 sys_s=1.33 peak_rss_mb=584 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=15141105 verdict=pass cut frames compared=256 worst psnr_y:44.35 at n:230 +round 5 oma hardware: measure: rc=0 wall_s=4.97 user_s=16.47 sys_s=1.37 peak_rss_mb=584 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=15141105 verdict=pass cut frames compared=256 worst psnr_y:44.35 at n:230 +round 5 melt hardware: measure: rc=0 wall_s=4.75 user_s=17.53 sys_s=0.55 peak_rss_mb=653 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=16051821 verdict=pass cut frames compared=256 worst psnr_y:45.09 at n:230 +round 5 oma software: measure: rc=0 wall_s=11.69 user_s=71.82 sys_s=3.05 peak_rss_mb=1202 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=8940835 verdict=pass cut frames compared=256 worst psnr_y:42.03 at n:230 +round 5 melt software: measure: rc=0 wall_s=10.49 user_s=68.36 sys_s=0.89 peak_rss_mb=1242 | frames=256/256 video_s=10.677333 audio_s=10.688000 bytes=10436034 verdict=pass cut frames compared=256 worst psnr_y:42.17 at n:230 +load at end: 11.17 9.34 9.72 + diff --git a/Docs/Research/evidence/2026-10-15-export-transfer-baseline.md b/Docs/Research/evidence/2026-10-15-export-transfer-baseline.md new file mode 100644 index 0000000..fb0bddb --- /dev/null +++ b/Docs/Research/evidence/2026-10-15-export-transfer-baseline.md @@ -0,0 +1,58 @@ +# Export transfer boundary baseline — 2026-10-15 + +This is a **single-run diagnostic**, not an A/B performance result or a zero-copy claim. +The executable was built from working tree `a29f81e` plus the instrumentation in this +change. Intel Core i5-1135G7 / Iris Xe, Mesa 26.2.2-arch1.1, FFmpeg 9.0.1. The export +uses its own Vulkan device and VA-API H.264 writer. The diagnostic was run in the user's +graphical session; the sandbox's Qt platform plugin aborted before an export began. + +## Reproduce + +```sh +cmake --build build/release --target omamovie -j8 +build/release/omamovie --export-audit tests/fixtures/generated/screenrecording_like.mp4 /tmp/omamovie-export-transfers-1080p60.mp4 +build/release/omamovie --export-audit "$HOME/.cache/omamovie-bench/fixtures/a2160.mp4" /tmp/omamovie-export-transfers-4k24.mp4 +ffprobe -v error -show_entries stream=index,codec_name,width,height,nb_frames,duration -show_entries format=duration -of json /tmp/omamovie-export-transfers-1080p60.mp4 +ffprobe -v error -show_entries stream=index,codec_name,width,height,nb_frames,duration -show_entries format=duration -of json /tmp/omamovie-export-transfers-4k24.mp4 +ffmpeg -v error -i /tmp/omamovie-export-transfers-1080p60.mp4 -f null - +ffmpeg -v error -i /tmp/omamovie-export-transfers-4k24.mp4 -f null - +``` + +Generate the cached 4K fixture using the recipe in +`tools/bench/filmcraft-equivalent/fixtures.sh` if absent: `a2160.mp4` is 3840×2160, +24000/1001 fps, ten seconds of noisy `testsrc2`, H.264. The 1080p60 fixture is generated +by `make fixtures` (one second, 60 video frames). No benchmark media is committed here. + +## Observed explicit boundaries + +| Boundary | 1080p60, 60 frames | 4K23.976, 240 frames | Source of counter | +|---|---:|---:|---| +| Software frame inputs to Vulkan compositor | 60; 186,624,000 source-plane bytes | 240; 2,985,984,000 bytes | `exporter.cpp`, `VideoFrame::plane()` sizes before `VulkanCompositor::render` | +| Vulkan → CPU NV12 readbacks | 60; 186,624,000 bytes; 189.62 ms | 240; 2,985,984,000 bytes; 1536.16 ms | `VulkanCompositor::read_nv12` result and elapsed call time | +| CPU NV12 row copies into writer AVFrame | 186,624,000 bytes; 46.00 ms | 2,985,984,000 bytes; 651.90 ms | `VideoWriter::write_nv12` memcpy loop | +| CPU AVFrame → VA-API surface uploads | 60; 186,624,000 bytes; 186.12 ms | 240; 2,985,984,000 bytes; 2668.89 ms | successful `av_hwframe_transfer_data` calls | + +1080p60: 745 ms total, 80.5 exported fps; per frame build/decode 0.49 ms, +render+readback 10.97 ms, writer worker 5.47 ms. 4K: 10,193 ms total, 23.5 fps; +per frame build/decode 3.11 ms, render+readback 38.16 ms, writer worker 16.66 ms. +These are wall times with overlapping render/encode stages and one run each, so the +subtotals are **not additive** and do not show CPU time per frame. `read_nv12` includes +GPU color conversion, synchronization and host copy; its elapsed time does not isolate +those components. Source-plane bytes indicate data presented for compositor staging, +not a measurement of bus bandwidth. Driver-internal copies are outside these counters. +The startup logs can show a separate VA-API viewer decode; the export loop itself still +constructs `FrameSource(nullptr)` and logs software decode. + +Independent FFmpeg decode completed without errors for both outputs. `ffprobe` found +60 H.264 frames at 1920×1080 plus AAC for 1080p60, and 240 H.264 frames at 3840×2160 +plus AAC for 4K. This checks decodability, count and stream presence, not frame fidelity +or A/V sample alignment; those remain the M12 workload gates (existing app tests cover +selected exported frame/audio behavior on other fixtures). + +## Next measurement + +Split NV12 conversion, GPU wait and mapped-buffer host copy in the compositor diagnostic; +measure upload/staging wait separately, process CPU/frame, peak RAM/VRAM and GPU activity. +Repeat both fixtures under controlled load and record percentiles before using these +numbers as an optimization comparison. The Intel DMA-BUF encoder-input pilot follows +only after that baseline and a concrete ownership/synchronization contract. diff --git a/Docs/Research/evidence/2026-10-15-kdenlive-dataset-import.txt b/Docs/Research/evidence/2026-10-15-kdenlive-dataset-import.txt new file mode 100644 index 0000000..f983def --- /dev/null +++ b/Docs/Research/evidence/2026-10-15-kdenlive-dataset-import.txt @@ -0,0 +1,82 @@ +Kdenlive's own test projects through oma-project import (2026-10-15) +Source: https://invent.kde.org/multimedia/kdenlive/-/tree/master/tests/dataset (GPL; read +locally, not copied into this repository). Media are absent here, so clips report as gaps; +the point is structure: every file must read to ProjectIR and every skipped object be named. + +== av.kdenlive (version="7.7.0", 11906 bytes) +1 format: Kdenlive (MLT XML) +1 issue: : 13 source objects are not saved in the project; re-import from the source file to recover them +1 issue: black_track: color generator not imported as a track; left out +1 issue: filterN: audiolevel master filter not imported; kept in the import +2 issue: filterN: audiolevel track filter not imported; kept in the import +1 issue: filterN: panner master filter not imported; kept in the import +2 issue: filterN: panner track filter not imported; kept in the import +1 issue: filterN: volume master filter not imported; kept in the import +2 issue: filterN: volume track filter not imported; kept in the import +1 issue: /home/six/git/kdenlive/tests/dataset/: media file not found or not readable; its clips become gaps +2 issue: : clip cannot be placed (no media, or outside it); left as a gap of its length +2 issue: transitionN: frei0r.cairoblend between tracks not imported; kept in the import +2 issue: transitionN: mix between tracks not imported; kept in the import +1 level reached: 2 +1 media found: 0 of 1 (not probed) +1 version: 7.7.0 + +== test-mix.kdenlive (version="7.9.0", 14262 bytes) +1 format: Kdenlive (MLT XML) +1 issue: : 17 source objects are not saved in the project; re-import from the source file to recover them +1 issue: black_track: color generator not imported as a track; left out +1 issue: filterN: audiolevel master filter not imported; kept in the import +2 issue: filterN: audiolevel track filter not imported; kept in the import +1 issue: filterN: avfilter.fieldorder master filter not imported; kept in the import +1 issue: filterN: panner master filter not imported; kept in the import +2 issue: filterN: panner track filter not imported; kept in the import +1 issue: filterN: volume master filter not imported; kept in the import +2 issue: filterN: volume track filter not imported; kept in the import +3 issue: producer0: color generator not imported; left as a gap +2 issue: producer1: color generator not imported; left as a gap +2 issue: transitionN: frei0r.cairoblend between tracks not imported; kept in the import +3 issue: transitionN: luma within a track (a same-track mix) not imported; kept in the import; the clips meet at a cut +2 issue: transitionN: mix between tracks not imported; kept in the import +1 level reached: 2 +1 media found: 0 of 0 (not probed) +1 version: 7.9.0 + +== clip-ids.kdenlive (version="7.15.0", 88516 bytes) +1 format: Kdenlive (MLT XML) +1 issue: : 12 source objects are not saved in the project; re-import from the source file to recover them +4 issue: blue.mpg: clip cannot be placed (no media, or outside it); left as a gap of its length +1 issue: blue.mpg: media file not found or not readable; its clips become gaps +2 issue: filterN: audiolevel track filter not imported; kept in the import +3 issue: filterN: panner track filter not imported; kept in the import +3 issue: filterN: volume track filter not imported; kept in the import +4 issue: green.mpg: clip cannot be placed (no media, or outside it); left as a gap of its length +1 issue: green.mpg: media file not found or not readable; its clips become gaps +1 issue: producer0: color generator not imported as a track; left out +4 issue: red.mpg: clip cannot be placed (no media, or outside it); left as a gap of its length +1 issue: red.mpg: media file not found or not readable; its clips become gaps +2 issue: transitionN: mix within a track (a same-track mix) not imported; kept in the import; the clips meet at a cut +2 issue: transitionN: qtblend within a track (a same-track mix) not imported; kept in the import; the clips meet at a cut +4 issue: yellow.mpg: clip cannot be placed (no media, or outside it); left as a gap of its length +1 issue: yellow.mpg: media file not found or not readable; its clips become gaps +1 level reached: 2 +1 media found: 0 of 4 (not probed) +1 version: 7.15.0 + +== test-nesting.kdenlive (version="7.23.0", 30738 bytes) +1 format: Kdenlive (MLT XML) +1 issue: : 12 source objects are not saved in the project; re-import from the source file to recover them +2 issue: filterN: audiolevel track filter not imported; kept in the import +3 issue: filterN: panner track filter not imported; kept in the import +3 issue: filterN: volume track filter not imported; kept in the import +1 issue: producer0: color generator not imported; left as a gap +1 issue: producer1: color generator not imported as a track; left out +2 issue: transitionN: mix within a track (a same-track mix) not imported; kept in the import; the clips meet at a cut +2 issue: transitionN: qtblend within a track (a same-track mix) not imported; kept in the import; the clips meet at a cut +1 level reached: 2 +1 media found: 0 of 0 (not probed) +1 version: 7.23.0 + +Found on the way: the report first called Kdenlive's black background track "not a playlist", +colour clips "not a media clip or a mix", and said nothing about same-track mixes or track +filters inside per-track tractors; it now names the colour generator, nested sequences, +same-track luma mixes, track filters, master filters and cross-track transitions. diff --git a/Docs/Research/evidence/2026-10-15-m7-long-export-cuts.txt b/Docs/Research/evidence/2026-10-15-m7-long-export-cuts.txt new file mode 100644 index 0000000..81ccc7e --- /dev/null +++ b/Docs/Research/evidence/2026-10-15-m7-long-export-cuts.txt @@ -0,0 +1,38 @@ +M7 long export with reordered cuts (2026-10-15): tools/bench/long-export/run.sh 120 +Edit: 24 five-minute cuts of a ten-minute 1080p30 BT.709 source (testsrc2 with a hue sweep of +one turn per ten minutes, so distant source times differ in colour), reordered, a 1 s dissolve +between cuts 1 and 2, sepia on cut 3 and cut 23; OTIO converted by `oma-project convert` (level +2), looks added to the project. Export by the app (--export-audit, VA-API). Checks by FFmpeg +only: frame count, A/V length, mean volume at 1 s / 1 h / 1 h 59 min 58 s, and 72 sampled frames +(start, middle and end of every cut) against the source frame the plan puts there, as 160x90 +RGB thumbnails: plain cuts must match (<= 6 levels), looked cuts must differ (>= 10), the +dissolve's middle must sit nearer the average of its two ends than half-way to either. + +Result: PASS. 216000/216000 frames, video and audio 7200.000 s, 125.2 fps (28 min 47 s), peak +RSS 810 MB; plain cuts within 0.50 levels; dissolve middle 30.5 from the average against 73.2 / +72.4 from its ends. The 2026-10-13 run of a similar edit took 52 min 45 s (68.2 fps), before the +export moved its encoder to its own worker and read VA-API frames back as GPU-made NV12. + +Memory: sampled every 30 s on a 25-minute run, RSS rises from 803 to 815 MB after warm-up and +levels off; a first two-hour run peaked at 894 MB and this one at 810 MB. The slow part is the +MP4 muxer's sample index, kept until `moov` is written at the end: linear in duration, bounded. +Earlier attempt: the same run with an untinted source failed only its dissolve check, which had +no power there (the two ends differed by 2.6 grey levels); the hue sweep fixed the test. +A 25-minute attempt in a 3 GB tmpfs filled it at frame 43053: the app reported "cannot write +packet" and removed its temporary file (disk-full semantics, M7); the runner now checks space. + +Raw report: +Long export 2026-10-15 01:28:47 -0300: 120 min, commit db5b646 +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +load: 3.96 5.58 5.95; import: level reached: 2 media: 1 saved: /home/kitsune/.local/share/omamovie-bench/long-export/2026-10-15-0128/converted.omamovie +export audit: 216000 frames in 1725881 ms (125.2 fps) -> /home/kitsune/.local/share/omamovie-bench/long-export/2026-10-15-0128/out.mp4 + encoder: VA-API H.264 (GPU) + per frame: build 0.11 ms, render+readback 7.57 ms, wait for encoder 0.17 ms, encode (own worker) 4.85 ms, mix 0.13 ms + result: written +measure: rc=0 wall_s=1726.73 user_s=4221.04 sys_s=413.85 peak_rss_mb=810 +frames 216000/216000, video 7200.000000 s, audio 7200.000000 s, 8745770169 bytes +sound at 1 s: mean_volume: -21.1 dB +sound at 3600 s: mean_volume: -21.1 dB +sound at 7198 s: mean_volume: -21.1 dB +checked 72 frames: plain worst 0.50 levels; dissolve mix 30.5 vs ends 73.2/72.4; PASS +load at end: 8.70 7.23 5.81 diff --git a/Docs/Research/evidence/2026-10-15-mlt-roundtrip.txt b/Docs/Research/evidence/2026-10-15-mlt-roundtrip.txt new file mode 100644 index 0000000..1c5823b --- /dev/null +++ b/Docs/Research/evidence/2026-10-15-mlt-roundtrip.txt @@ -0,0 +1,23 @@ +MLT round trip (2026-10-15): tools/bench/cross-editor/roundtrip.sh +melt writes an MLT document of two cuts of the BT.709 bench source with a 12-frame luma mix +(melt SRC in=48 out=119 SRC in=200 out=271 -mix 12 -mixer luma), renders it itself (libx264 +CRF 12); OmaMovie converts the same document (oma-project convert) and exports it (software). +FFmpeg compares the two movies frame by frame (PSNR, both lossy encodes of a grainy source). + +Result: both 132 frames; outside the transition windows (frames 1-60, 80-132) worst 39.7 dB, +the level two encodes of the same frames reach; frames 61-79 down to 27.3 dB where OmaMovie +centres the dissolve on its cut (reported by the import) and mixes in linear light. +An earlier attempt with the untagged 320x180 fixture compared at ~21 dB everywhere although +the pictures were the same frames: OmaMovie reads untagged SD as BT.601 and writes BT.709-tagged +video, melt passes the YUV through, so raw Y differs. Round trips need colour-tagged sources. + +Raw report: +MLT round trip 2026-10-15 03:27:47 -0300: OmaMovie 871608a (dirty); melt 7.40.0 (Kdenlive 26.08.0) +issue: xed_1080p24_bt709.mp4: dissolve is not centred on the cut; centred, same total length +issue: xed_1080p24_bt709.mp4: 1 source objects are not saved in the project; re-import from the source file to recover them +level reached: 2 + result: written +measure: rc=0 wall_s=5.89 user_s=31.74 sys_s=1.78 peak_rss_mb=1075 +melt: 132 frames +oma: 132 frames +outside the mix: 113 frames, worst 39.7 dB; inside: 19 frames, worst 27.3 dB; PASS diff --git a/Docs/Research/evidence/2026-10-16-export-transfer-phases.md b/Docs/Research/evidence/2026-10-16-export-transfer-phases.md new file mode 100644 index 0000000..c4080e6 --- /dev/null +++ b/Docs/Research/evidence/2026-10-16-export-transfer-phases.md @@ -0,0 +1,40 @@ +# Export transfer phases — 2026-10-16 + +**Classification:** PERFORMANCE / QA GAP. This is a one-run diagnostic, not a speedup claim. +The previous counter in `2026-10-15-export-transfer-baseline.md` included NV12 conversion, +GPU synchronization, and host copying in one readback duration. The export path also did not +report the actual compositor downgrade reason or software decode output volume. + +`tools/bench/export-transfer/run.sh /tmp/omamovie-export-audit-v01-real 1` ran in the +graphical Intel session using the Release build from working tree `9f75558` plus this change. +The CPU is an i5-1135G7 with Iris Xe; FFmpeg is 9.0.1. The sandbox cannot initialize this +graphical path. Run logs and output movies are in `/tmp/omamovie-export-audit-v01-real/`. + +| Measured boundary | 1080p60, 60 frames | 4K23.976, 240 frames | +|---|---:|---:| +| Export duration | 771 ms | 8850 ms | +| Process CPU during export | 1613 ms | 44798 ms | +| Software decode output | 187 MB | 2986 MB | +| Software rows copied into Vulkan staging | 187 MB / 55 ms | 2986 MB / 900 ms | +| GPU NV12 dispatch (Vulkan timestamps) | 33 ms | 578 ms | +| NV12 fence wait (includes queued work) | 123 ms | 860 ms | +| NV12 mapped buffer copied to host vector | 17 ms | 367 ms | +| CPU NV12 rows copied into writer AVFrame | 187 MB / 49 ms | 2986 MB / 679 ms | +| CPU AVFrame uploaded to VA-API surface | 187 MB / 190 ms | 2986 MB / 2686 ms | + +Both exports used software decode, Vulkan composition, and VA-API H.264 encode. All GPU +readback frames had a valid Vulkan timestamp. These are overlapping phase totals, so they +must not be added to infer export wall time. The counters are explicit application API +boundaries; driver-internal transfers and VRAM use remain unmeasured. No zero-copy claim is +supported by this data. + +Independent FFmpeg decode succeeded. `ffprobe -count_frames` found exactly 60 and 240 video +frames at the requested resolutions and rates. Paired video PSNR was 40.97 dB mean for the +one-second screen recording and 25.76 dB for noisy 4K `testsrc2`; the latter is a lossy +re-encode of a deliberately grainy source and is not a visual acceptance threshold. The +additional 1080p tone fixture exported 479/479 video frames, and FFmpeg `apsnr` measured +170.136 dB for both decoded audio channels over 20 seconds. + +The benchmark script retains per-run exports and logs and accepts a repeat count. This +single run does not establish stable percentiles or regression limits. Those require +repeats under comparable load before changing the export pipeline. diff --git a/Docs/Research/evidence/2026-10-16-package-release-gate.md b/Docs/Research/evidence/2026-10-16-package-release-gate.md new file mode 100644 index 0000000..eb237d6 --- /dev/null +++ b/Docs/Research/evidence/2026-10-16-package-release-gate.md @@ -0,0 +1,58 @@ +# Installed package and PR gate — 2026-10-16 + +**Classification:** QA GAP / RELEASE GATE. + +The first clean Arch `scripts/package-check.sh` run failed in `makepkg`'s test stage: +12/13 CTest suites passed, but the compositor effect-memory test reported an impossible +`+17592186044416 MiB` on lavapipe. The test subtracted unsigned +`VK_EXT_memory_budget.heapUsage` samples; the budget also includes driver variation between +renders. The same test failed locally with `VK_DRIVER_FILES=/usr/share/vulkan/icd.d/lvp_icd.json` +before the fix. The compositor now reports its own live blur/sharpen image allocation sizes, +queried from the images' Vulkan memory requirements. The test passed on lavapipe and Intel +afterward, with 0 MiB added by looks and 5.0, 2.6 and 31.6 MiB for the sampled detail cases. + +The second clean package run used committed source `0f2e209`: + +```sh +scripts/package-check.sh /tmp/omamovie-package-v01-fixed +``` + +`makepkg` built `omamovie-git-r527.0f2e209-1-x86_64.pkg.tar.zst`, ran 13/13 CTest suites, +and installed it in a fresh Arch container with `vulkan-swrast`. Before launch the script +checked the installed binary, QML, desktop entry (`desktop-file-validate`), icon, MIME +registration (`gio` recognized `application/x-omamovie-project`), and `ldd` resolution. +The installed `/usr/bin/omamovie --smoke` under headless sway/lavapipe reported +`GUI smoke: PASS` and `smoke exit 0`. Logs and package are in +`/tmp/omamovie-package-v01-fixed/` on the test host. + +This proves the clean Arch package and software Vulkan workflow represented by the GUI smoke. +It does not replace the M6 human walkthrough T1–T5 on a fresh Omarchy profile, a native +installed Intel run, or the final release tarball smoke after `v0.1.0-rc.1`. + +PR [#4](https://github.com/KitsuneForgering/OmaMovie/pull/4) was opened as a draft against +`master` to exercise the active ruleset, whose required contexts are `ci` and +`conventional commits`. A defective CI run failed on Clang/clang-tidy diagnostics, and its +aggregate `ci` check failed too. After those fixes, run `38985319118` on `041ecb9` passed all +eight GCC/Clang build variants, GUI smoke, format, tidy, include rules, eight fuzz jobs and +`ci`; run `38985319129` passed `conventional commits`. The active `master` ruleset requires +the exact two contexts with strict status checks, and GitHub reported the PR merge state +`CLEAN` at that SHA. Recheck both contexts after the final branch commit. + +Run `38996647426` on `7b953e3` then caught one GCC TSan report in the app suite while +the source-marked edit workflow exported through lavapipe. Its read, write and heap +allocation were all in `libLLVM.so.23.1` shader workers created by `libvulkan_lvp.so`; +the application stack only created the Vulkan device. No OmaMovie frame accessed the +reported block. The other seven compiler/build variants, GUI smoke, lint and fuzz passed; +`ci` failed because GCC TSan failed, as the ruleset requires. A narrowly scoped +`race:libLLVM.so` suppression was added beside the existing third-party TSan entries. +The same focused app test passed locally on lavapipe with LLVM 22; CI with LLVM 23 must +still verify the suppression and the complete suite on the new SHA. + +The host-native Release app was installed to `/tmp/omamovie-host-stage/usr` and launched from +that staged tree on Intel. Its first GUI smoke attempt failed the play/J/K/L position checks +with audio running; a second attempt passed. This is an unresolved intermittent native smoke +observation, so this run is not evidence of a stable Intel GUI workflow. The Arch package from +the newer rolling snapshot also could not launch on this older host because it requires +`libsimdjson.so.34` while the host has `.33` (and different Qt minor versions). The clean +Arch container passed with its matched runtime libraries; Omarchy package validation must +use a compatible, updated environment. diff --git a/Docs/Research/evidence/2026-10-17-first-edit-tour.md b/Docs/Research/evidence/2026-10-17-first-edit-tour.md new file mode 100644 index 0000000..e6c9cb2 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-first-edit-tour.md @@ -0,0 +1,23 @@ +# First edit tour and bundled demo — 2026-10-17 + +## UX / integration gap + +The first-opening tour identified interface areas but did not teach the path from a source range to a saved and exported edit. It did not show how to open the Command Palette. A new user also had to supply media before seeing an editable sequence. + +## Cause and change + +The tour was a standalone explanation with no material to practice on. `WelcomeTour.qml` now presents six concrete steps with expected outcomes, uses the existing `OmaAction` names and shortcuts, opens the Command Palette directly, and hands off to a bundled three-shot project. F1 and visible Help/Tour controls reopen the guide. The demo is loaded through the normal project loader as an unsaved copy; Save therefore asks for the user's own destination. The package installs the project and its three small media files next to QML. + +Changed: `apps/omamovie/qml/WelcomeTour.qml`, `Main.qml`, `ProjectsScreen.qml`, `Icon.qml`; `app_settings.*`, `main.cpp`, `session.*`, `CMakeLists.txt`; `apps/omamovie/demo/`; `scripts/generate-demo-project.sh`, `ci-run.sh`, `package-check.sh`; `tests/app/test_demo_project.cpp`, `main.cpp`, `apps/omamovie/src/gui_smoke.cpp`; onboarding and M6 documentation. + +## Verification + +- The app test opens the bundled project, marks and appends a source range, saves, reopens, exports with software encoding, then independently decodes the exported movie and checks the order of the three shots. +- GUI smoke checks first presentation, Command Palette and demo handoffs, manual reopening, completion persistence, keyboard flow, and a 640 px window with 130% text. The native smoke passed with the Intel Vulkan device on the second run. A first run lost window focus during its later keyboard segment; the onboarding and demo checks passed in both runs. +- The generation script first removes its four previous demo outputs, then regenerates and validates them. After this clean regeneration, `make test` passed 14/14 suites (113 seconds). `make format-check`, `git diff --check`, and shell syntax checks passed. +- A fresh `DESTDIR` install contained the tour, project, three media files, desktop entry, icon, and MIME file. Its first GUI smoke passed the tour and demo checks but failed an existing title pixel comparison; a repeat passed overall. Native GUI smoke passed its full keyboard path on the second run. The visual check and desktop focus can vary between runs, so the human walkthrough is still needed. +- PR CI is not yet green: the previous SHA failed the sustained memory threshold on Clang Debug despite stable file descriptors. This onboarding change is not claimed as a release gate pass. + +## v0.1 impact and limit + +The first edit can be explored without importing personal media, while shortcuts and edit consequences remain tied to the application action registry. Automated tests confirm behavior and export content; a person unfamiliar with OmaMovie still needs to perform the M6 walkthrough to establish whether the wording and sequence are understandable. diff --git a/Docs/Research/evidence/2026-10-17-native-smoke-crash.md b/Docs/Research/evidence/2026-10-17-native-smoke-crash.md new file mode 100644 index 0000000..270af14 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-native-smoke-crash.md @@ -0,0 +1,33 @@ +# Native installed smoke: crash and false failure — 2026-10-17 + +**Classification:** QA GAP / BUG in the smoke driver. + +The staged Release binary from `86b30bd` exited with SIGSEGV on Intel/Omarchy during +`--smoke`. `coredumpctl info 4009459` records the command and signal. Symbolizing that +core identified `QVariant::toMap()` called from `gui_smoke.cpp:1785`, at +`session.clips().front()` in the export step. At the crash, the smoke's prior launch and +autosave checks had already failed, `clips_after_edit` was zero, and the restored timeline +was empty. The empty list access caused the SIGSEGV; the earlier reason for zero clips +was not recovered from this core. The core copy used for GDB was deleted afterward. + +`apps/omamovie/src/gui_smoke.cpp` now stops with a diagnostic if the forwarded-file +step fails or if there are no clips before autosave or export. A failing prerequisite +will fail the smoke instead of producing an unrelated crash. A later native run with +those guards produced a separate, actionable false failure at Save from the discard +dialog: the test read `session.dirty()` *after* clicking Save. The captured state was +`dirty 0`, `media 0`, empty project path, showing that save and New Project had already +completed. The check now records the dirty precondition before clicking; the following +step still verifies that New Project completed, and the reopen check verifies that the +saved edit survived. + +**Checks:** `make format-check` and `make test` passed (14/14 suites). The installed +Release binary in `/tmp/omamovie-host-stage/usr/bin/omamovie` passed three consecutive +native Intel GUI smokes after the check change, including keyboard, save/reopen, +autosave/recovery and VA-API export. The software-Vulkan installed smoke also passed in +the [clean Arch release-task run](2026-10-17-release-tag-and-staged-smoke.md). + +**v0.1 impact and limit:** the test can no longer turn a failed prerequisite into a +SIGSEGV, and fast successful saves no longer fail the guard check. The origin of the +one empty-timeline run remains unproven; repeat the installed native smoke on the RC +and investigate any new early failure using the added state diagnostics. This is not +evidence that arbitrary native project transitions are free of races. diff --git a/Docs/Research/evidence/2026-10-17-rc-correctness-pilot.md b/Docs/Research/evidence/2026-10-17-rc-correctness-pilot.md new file mode 100644 index 0000000..930de5e --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-rc-correctness-pilot.md @@ -0,0 +1,54 @@ +# RC correctness-gate pilot — 2026-10-17 + +**Scope:** Intel Iris Xe (Tiger Lake), Intel iHD 26.3.5, FFmpeg n9.0.2, MLT `melt` +7.42.0 (the engine used by installed Kdenlive 26.08.2). The checkout was dirty at +`0b2a8ab`; this is a pilot of the gate, not evidence for a frozen RC SHA. MLT renders +were driven by `melt`, not the Kdenlive user interface. Only one comparison round was +run, under varying system load, so the wall times below do not support a speed ranking. + +## Results + +- `make BUILD=release test` outside the sandbox: 14/14 CTest suites passed in 35.09 s. + The same run inside the sandbox stalled in the Vulkan compositor test; the unrestricted + run passed that suite in 6.00 s. `OMA_PROPERTY_RUNS=3000 OMA_PROPERTY_STEPS=200 + build/release/tests/timeline_tests` passed all 459 test cases, including 600,000 seeded + edit steps, in a separate run. +- The final shared fixture has 479 decoded 1920×1080 frames at 24000/1001, explicit + BT.709 primaries/transfer/matrix and limited range, and seeded pink-noise audio. SHA-256: + `b555007fdc2c34c94678969900a2beb2f5894c2f809f4db0b29e9dc5f69df8ed`. + An earlier fixture had BT.709 matrix but `unknown` primaries and transfer despite + encoder command-line tags. The new `setparams` step and oracle detect that error. +- `bash tools/bench/cross-editor/run.sh 1 /tmp/omamovie-rc-final cuts` passed for + OmaMovie/MLT × VA-API/libx264: each output had 256/256 decoded frames, 10.677 s duration, + all 256 picture frames matched the five reordered source intervals (worst luma PSNR + 42.04–45.09 dB), and audio at 15 points matched the correct source intervals (minimum + normalized correlation 0.915, measured lag 0 ms, minimum relative level 0.68). + [Full report](2026-10-17-rc-cuts.txt). +- `bash tools/bench/cross-editor/run.sh 1 /tmp/omamovie-rc-audio-v3 whole` passed for + all four routes: 479/479 frames, 19.978 s duration, worst luma PSNR 41.08–45.03 dB, + minimum audio correlation 0.988, measured lag 0 ms, and minimum relative level 0.70. + [Full report](2026-10-17-rc-whole.txt). +- `bash tools/bench/long-export/run.sh 25 /tmp/omamovie-rc-long` passed: 45,000 decoded + output frames, video 1,500.000 s, audio 1,500.011 s; 15 selected picture checks + passed across reordered cuts and looks, with the dissolve between its sources. Audio + at beginning/middle/end was non-silent. Export took 344.75 s and wrote 1.61 GB. + [Full report](2026-10-17-rc-long-25min.txt). + +The initial picture/frame-count oracle was checked against the source itself (pass) and +against a 479-frame output presented as the 256-frame cuts scene (failure). After audio +matching and color checks were added, the runner returned nonzero when the interim +fixture lacked color tags and retained the failed output for diagnosis. The final +oracle then passed the four-route cuts and whole-source runs above. +As a focused negative check, the v3 picture stream was copied unchanged and its audio +replaced with the older sine-tone fixture. `assert_output.py whole` failed at 0.999 s +with correlation 0.054, so correct picture and duration alone cannot satisfy the +audio oracle. + +## Remaining RC gate + +Run `scripts/rc-validation.sh` on the frozen SHA with its default five alternated rounds +per scene and 120-minute long export; retain its report and fixture hash. The pilot's +25-minute export validates the new long-form checker but does not replace the full +two-hour gate. The audio oracle checks 15 cut interior points and three whole-source +points with a 50 ms alignment search; it does not continuously compare every audio +sample or exercise Kdenlive's interactive editing workflow. diff --git a/Docs/Research/evidence/2026-10-17-rc-cuts.txt b/Docs/Research/evidence/2026-10-17-rc-cuts.txt new file mode 100644 index 0000000..c6c5384 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-rc-cuts.txt @@ -0,0 +1,18 @@ +Cross-editor export 2026-10-17 20:02:29 -0300, 1 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.3.5 () +ffmpeg version n9.0.2 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 1.44 1.82 2.40 +editors: OmaMovie 0b2a8ab (dirty); melt 7.42.0 (Kdenlive 26.08.2) +23:02:29.718 INFO decode xed_1080p24_bt709_noise-v3.mp4: h264 software decode (video_decoder.cpp:550) +scene: cuts; source: xed_1080p24_bt709_noise-v3.mp4 sha256 b555007fdc2c34c9, 479 frames +round 1 oma hardware: encoder: VA-API H.264 (GPU) measure: rc=0 wall_s=4.28 user_s=12.74 sys_s=1.16 peak_rss_mb=634 +PASS frames=256 duration=10.677s worst_psnr_y=44.35dB audio_min_corr=0.941 max_lag=0.0ms min_gain=0.98 bytes=15141751 +round 1 melt hardware: measure: rc=0 wall_s=4.39 user_s=15.49 sys_s=0.51 peak_rss_mb=656 +PASS frames=256 duration=10.677s worst_psnr_y=45.09dB audio_min_corr=0.915 max_lag=0.0ms min_gain=0.68 bytes=16052556 +round 1 oma software: encoder: libx264 measure: rc=0 wall_s=8.42 user_s=49.32 sys_s=1.95 peak_rss_mb=1194 +PASS frames=256 duration=10.677s worst_psnr_y=42.04dB audio_min_corr=0.941 max_lag=0.0ms min_gain=0.98 bytes=9261513 +round 1 melt software: measure: rc=0 wall_s=10.20 user_s=67.09 sys_s=0.88 peak_rss_mb=1231 +PASS frames=256 duration=10.677s worst_psnr_y=42.17dB audio_min_corr=0.915 max_lag=0.0ms min_gain=0.68 bytes=10436769 +load at end: 5.80 2.93 2.74 diff --git a/Docs/Research/evidence/2026-10-17-rc-long-25min.txt b/Docs/Research/evidence/2026-10-17-rc-long-25min.txt new file mode 100644 index 0000000..a0e6653 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-rc-long-25min.txt @@ -0,0 +1,19 @@ +Long export 2026-10-17 19:18:00 -0300: 25 min, commit 0b2a8ab +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +load: 6.83 5.85 4.27; import: level reached: 2 media: 1 saved: /tmp/omamovie-rc-long/2026-10-17-1918/converted.omamovie +export audit: 45000 frames in 343557 ms (131.0 fps) -> /tmp/omamovie-rc-long/2026-10-17-1918/out.mp4 + encoder: VA-API H.264 (GPU) + path: decode software (export FrameSource has no GPU device); compositor Vulkan (software frames staged to GPU) + process CPU: 965262 ms total, 21.45 ms/frame (all threads during export) + per frame: build 0.12 ms, render+readback 7.33 ms, wait for encoder 0.02 ms, encode (own worker) 4.86 ms, mix 0.15 ms + decode output: 45214 software frames, 140633625600 plane-span bytes (includes lookahead/seek) + transfers: software compositor inputs 45029 (140058201600 payload bytes), GPU readbacks 45000 (139968000000 bytes, 91942.26 ms total) + compositor staging: 45029 inputs, 140058201600 packed bytes, 38296.73 ms total (38202.09 ms row copies; GPU transfer in render time) + NV12 readback phases: record 2538.33 ms, submit 3092.12 ms, fence wait 70820.44 ms, invalidate 6.94 ms, host copy 14965.13 ms (fence wait includes queued GPU work) + NV12 GPU conversion: 20345.16 ms across 45000 timestamped frames (dispatch only; queue delay remains in fence wait) + writer: NV12 CPU row copies 139968000000 bytes (36997.23 ms), VA-API uploads 45000 (139968000000 bytes, 100357.33 ms) + result: written +measure: rc=0 wall_s=344.75 user_s=882.95 sys_s=83.71 peak_rss_mb=804 +frames 45000/45000, video 1500.000000 s, audio 1500.010667 s, 1607220126 bytes +checked 15 frames: plain worst 0.41 levels; dissolve mix 30.5 vs ends 73.2/72.4; PASS +load at end: 3.40 4.55 4.40 diff --git a/Docs/Research/evidence/2026-10-17-rc-whole.txt b/Docs/Research/evidence/2026-10-17-rc-whole.txt new file mode 100644 index 0000000..d396e44 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-rc-whole.txt @@ -0,0 +1,17 @@ +Cross-editor export 2026-10-17 19:50:29 -0300, 1 repeats, order alternated per round +CPU: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz, 8 threads +GPU: Intel(R) Iris(R) Xe Graphics (TGL GT2) +VA-API: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 26.3.5 () +ffmpeg version n9.0.2 Copyright (c) 2000-2026 the FFmpeg developers +power online: 1, load: 1.85 1.79 2.59 +editors: OmaMovie 0b2a8ab (dirty); melt 7.42.0 (Kdenlive 26.08.2) +scene: whole; source: xed_1080p24_bt709_noise-v3.mp4 sha256 b555007fdc2c34c9, 479 frames +round 1 oma hardware: encoder: VA-API H.264 (GPU) measure: rc=0 wall_s=5.11 user_s=13.93 sys_s=1.31 peak_rss_mb=416 +PASS frames=479 duration=19.978s worst_psnr_y=44.32dB audio_min_corr=0.995 max_lag=0.0ms min_gain=0.98 bytes=28620000 +round 1 melt hardware: measure: rc=0 wall_s=6.23 user_s=15.55 sys_s=0.39 peak_rss_mb=356 +PASS frames=479 duration=19.978s worst_psnr_y=45.03dB audio_min_corr=0.988 max_lag=0.0ms min_gain=0.70 bytes=30333816 +round 1 oma software: encoder: libx264 measure: rc=0 wall_s=17.54 user_s=107.02 sys_s=3.86 peak_rss_mb=1012 +PASS frames=479 duration=19.978s worst_psnr_y=41.08dB audio_min_corr=0.995 max_lag=0.0ms min_gain=0.98 bytes=17290827 +round 1 melt software: measure: rc=0 wall_s=17.90 user_s=113.04 sys_s=0.97 peak_rss_mb=944 +PASS frames=479 duration=19.978s worst_psnr_y=41.27dB audio_min_corr=0.988 max_lag=0.0ms min_gain=0.70 bytes=19468714 +load at end: 8.86 4.08 3.32 diff --git a/Docs/Research/evidence/2026-10-17-release-tag-and-staged-smoke.md b/Docs/Research/evidence/2026-10-17-release-tag-and-staged-smoke.md new file mode 100644 index 0000000..4cdd552 --- /dev/null +++ b/Docs/Research/evidence/2026-10-17-release-tag-and-staged-smoke.md @@ -0,0 +1,53 @@ +# Release tag and installed app gates — 2026-10-17 + +**Classification:** RELEASE GATE. + +## Tag ancestry + +**Problem and cause.** The tag workflow accepted a version-shaped tag on any commit. Its +CI and draft-publication dependencies did not require that commit to have passed through +the protected `master` branch, so a tag on `feature/first-release` could have published a +release before the PR merged. + +**Change.** `.github/workflows/release.yml` now fetches `master` after checking out the tag +and calls `scripts/require-release-commit.sh`. The script rejects a tagged commit that is +not an ancestor of `origin/master`. `tests/release_tag_guard.sh`, registered in CTest, +creates a temporary Git history with an RC tag on an unmerged feature commit. The same +tag is accepted after a fast-forward merge. The test failed with an always-accepting +guard (`unmerged release tag was accepted`) and passed with the new guard. `make test` +passed 14/14 suites locally, including this regression. + +**v0.1 impact.** A release tag from an unmerged branch stops in `validate`, before the +source archive, app build, full CI and publication jobs. The first real tag run remains +to be checked at `v0.1.0-rc.1`; no release tag was created here. + +## Installed release tree + +**Problem and cause.** `scripts/ci-run.sh release` built and tested the source tree, then +installed it under `stage/usr`, but never launched that installed binary. The separate CI +GUI smoke uses `build/release/omamovie`, so a missing installed QML file or launch failure +could pass every pre-publication job. + +**Change.** The release task now verifies the staged executable, QML, icon and MIME file, +validates the desktop entry, and runs `stage/usr/bin/omamovie --smoke` as an ordinary user +under headless sway/lavapipe. A failure exits the app job before the tarball is uploaded; +the `publish` job already needs the app job and full CI. + +**Reproduction and result.** The first local invocation against the working checkout +stopped at CMake configure because its existing `build/release/CMakeCache.txt` named the +host path, while Docker mounts the checkout at `/src`. Repeated from a clean `git archive` +copy of `86b30bd` with the changed release task, `bash scripts/ci-run.sh release` passed +13/13 Release CTest suites in Arch Linux, installed to `stage/usr`, and finished with +`GUI smoke: PASS` from that installed binary. The smoke reported llvmpipe/Mesa 26.2.4, +software H.264/HEVC decode, a libx264 export through the Vulkan compositor, and passing +edit, keyboard, recovery and device-loss checks. The clean archive preceded the new Git +ancestry test; that test was run in the working checkout's 14/14 local suite. + +**v0.1 impact and limit.** A tag cannot publish an app tarball whose installed layout fails +this smoke. This is a clean Arch software-Vulkan check. A native Omarchy install, the M6 +T1–T5 human walkthrough, and a smoke of the eventual RC archive remain open. + +For the PR gate, [run 39032076887](https://github.com/KitsuneForgering/OmaMovie/actions/runs/39032076887) +passed the complete GCC/Clang, Debug/Release/ASan/TSan, GUI, lint and fuzz matrix and +the `ci` aggregator on `86b30bd`; `conventional commits` passed on the same SHA. The +required contexts must be rechecked after this gate change is pushed. diff --git a/Docs/Research/final-cut-pro-decision.md b/Docs/Research/final-cut-pro-decision.md new file mode 100644 index 0000000..fe6bd36 --- /dev/null +++ b/Docs/Research/final-cut-pro-decision.md @@ -0,0 +1,34 @@ +## Conclusion and decision + +The most useful lesson is an **editing invariant**: when a primary shot moves, +dependent titles, B-roll and sound should remain attached to the intended +moment. OmaMovie already has a storyline and commands for ripple and precise +placement, but its ripple operations currently move clips on one track only. +The next step is to specify attachment semantics and test them before persisting +projects. A visible precise-placement mode and recoverable project versions are +smaller, complementary choices. Proxies and FCPXML are later, bounded pilots. +None of Apple's product descriptions proves these choices will improve OmaMovie +users' results; the M6 task comparison remains the product test. + +### Question, baseline, and hypotheses + +The decision is which Final Cut ideas help a local editor for short recordings +and phone videos on Omarchy without delaying basic save/export. Criteria set +before this review: (1) avoid accidental sync changes and data loss, (2) keep +precise edits possible, (3) fit OmaMovie's existing timeline/project boundaries, +and (4) earn added complexity with a representative task or measured workload. + +* **H1, attachment:** explicit dependent-clip anchors will prevent relative + timing errors during storyline edits. It weakens if linked and unlinked task + runs have similar errors, or anchor edge cases make editing less predictable. +* **H2, recovery:** durable save plus an accessible prior project version will + improve recovery from mistaken or interrupted edits. It weakens if crash and + reopen tests cannot recover a valid version, or the version adds no recovery + beyond autosave for realistic mistakes. +* **H3, proxy workflow:** a proxy helps only when original playback misses its + deadline enough to offset transcoding, storage and quality costs. It weakens + if end-to-end tests show no useful improvement on target media/hardware. + +These are **OmaMovie hypotheses**, not claims about measured Final Cut outcomes. + +[Return to final-cut-pro.md](final-cut-pro.md) diff --git a/Docs/Research/final-cut-pro-documentation.md b/Docs/Research/final-cut-pro-documentation.md new file mode 100644 index 0000000..3660aa4 --- /dev/null +++ b/Docs/Research/final-cut-pro-documentation.md @@ -0,0 +1,14 @@ +## What Apple's documents establish + +| Mechanism | Documented behavior | Bounded lesson | +|---|---|---| +| Magnetic timeline | A primary storyline ripples around edits. Connected clips move with the primary clip. The Position tool overwrites at a fixed place and leaves a gap at the origin. [Apple guide, “Intro to the Magnetic Timeline”](https://support.apple.com/en-hk/guide/final-cut-pro/verb8fcfc133/mac), “Primary storyline” through “Position tool and gap clips”. | Couple a dependent clip to an anchor, and expose a deliberate way to preserve absolute timing. The attractive language about being faster is vendor opinion, not evidence. | +| Recovery | Changes save automatically; a project can be duplicated; the library database is backed up separately from media. [Apple, “Save and back up projects”](https://support.apple.com/guide/final-cut-pro/save-and-back-up-projects-ver79aa3d71/mac), opening paragraphs. | Separate live autosave, a user-restorable version, and source-media backup claims. OmaMovie has no nested-clip snapshot requirement yet. | +| Media representations | Original, optimized and proxy media are distinct. Transcoding can happen in the background; generated files can be deleted and recreated. Apple instructs users to choose original/optimized before sharing. [Apple, “Create optimized and proxy files”](https://support.apple.com/en-md/guide/final-cut-pro/verb8e5f6fd/mac), “Create” and “Delete” sections. | Model proxy as replaceable media tied to an immutable source identity. OmaMovie should enforce an export-source policy itself rather than rely on the user's viewer setting. | +| Organization | Roles label clip function and support timeline grouping and separate exports. [Apple, “Organize clips by roles”](https://support.apple.com/en-gb/guide/final-cut-pro/verdbd59f7/mac), opening paragraphs. | Useful if source discovery or audio deliverables become frequent tasks; neither is established for OmaMovie's first release. | +| Interchange | Final Cut imports/exports versioned FCPXML; exports from version 1.10 onward use `.fcpxmld` bundles. [Apple, “Use XML to transfer projects”](https://support.apple.com/en-euro/guide/final-cut-pro/verdbd66ae/12.4/mac/26.6), “Import” and “Export”. Apple documents rational time attributes and a DTD. [Apple Developer, “Timing Attributes”](https://developer.apple.com/documentation/professional-video-applications/timing-attributes); [“Creating FCPXML Documents”](https://developer.apple.com/documentation/professional-video-applications/creating-fcpxml-documents). | M9 must pin an actual export version and test semantic mapping. XML validity alone does not establish edit fidelity. | + +All Apple pages share one vendor lineage. They establish advertised/documented +contracts, not independent evidence of efficiency or user preference. + +[Return to final-cut-pro.md](final-cut-pro.md) diff --git a/Docs/Research/final-cut-pro-local-fit.md b/Docs/Research/final-cut-pro-local-fit.md new file mode 100644 index 0000000..189859f --- /dev/null +++ b/Docs/Research/final-cut-pro-local-fit.md @@ -0,0 +1,27 @@ +## Foundation and fit to this repository + +The relevant foundation is an explicit timeline state model: time is rational, +clip identities survive edits, and a command must preserve declared invariants +or fail atomically. [ADR-0002](../adr/0002-time-representation.md) defines the +time representation; [the timeline API](../../libs/timeline/include/oma/timeline/edit.hpp) +states that ripple moves later clips **on the same track only** and exposes +transactional commands. These are verified local contracts. It is an **inference** +that a visual “connection” needs a persisted anchor relation rather than a +one-off UI group: otherwise save/load, undo/redo, and edits outside the UI can +break the relation. The exact anchor policy remains an assumption to resolve. + +Define a minimal anchor as `(dependent clip ID, primary clip ID, offset in +sequence ticks)` only after deciding what split, trim, delete, speed change, +locked tracks, and movement across the anchor boundary mean. A surviving +anchor must refer to an existing primary clip. A failed operation should leave +timeline and history untouched; a successful operation should be one undo entry. +Do **not** infer Apple's internal representation from its visible behavior. + +OmaMovie's current [implementation plan](../implementation-plan.md) already +includes M7 autosave/relink, M8 proxies and M9 FCPXML evaluation. The new issue +is order: anchor semantics must be settled before the native format is frozen. +The [README](../../README.md) says projects cannot yet be saved or exported, so +the immediate recovery gain is M7 durability, followed by versions only if the +mistake-recovery task justifies them. + +[Return to final-cut-pro.md](final-cut-pro.md) diff --git a/Docs/Research/final-cut-pro-sources.md b/Docs/Research/final-cut-pro-sources.md new file mode 100644 index 0000000..8ef3ba9 --- /dev/null +++ b/Docs/Research/final-cut-pro-sources.md @@ -0,0 +1,18 @@ +## Source and stopping record + +Accessed **2026-10-04**. Apple's Mac guide exposes a 12.4 selector on the +versioned pages linked above; unversioned links are live pages with publication +and update date **unknown**. The browser exposed the cited Apple Support +passages as HTML text. Apple Developer's timing and creation pages were visible +through indexed text, but direct full-text/Markdown access failed; details of +those pages remain provisional until a fixture and pinned DTD are inspected. +The search results for Apple's snapshot and keyword pages exposed descriptive +passages, but the direct pages were unavailable; neither is a decision premise. +Local code and docs were read from the working tree on this date; their state +may include uncommitted changes. Search covered the mechanisms above, not all +Final Cut features or competing editors. Stopping criterion: enough direct +documentation to identify bounded M5–M9 decisions; the biggest remaining +uncertainty is whether anchors improve representative OmaMovie tasks enough to +justify their editing and persistence complexity. + +[Return to final-cut-pro.md](final-cut-pro.md) diff --git a/Docs/Research/final-cut-pro-tests.md b/Docs/Research/final-cut-pro-tests.md new file mode 100644 index 0000000..f7fbab6 --- /dev/null +++ b/Docs/Research/final-cut-pro-tests.md @@ -0,0 +1,18 @@ +## Alternatives, tests, and stopping rules + +| Choice | Simpler baseline / cost | Proposed discriminating check (not executed) | +|---|---|---| +| Anchored dependents | Keep track-local ripple and manually group clips. Anchors add edge cases and migration rules. | Construct a short edit with title, cutaway and detached voiceover. Move, split, ripple-trim and delete the primary clip; save/load and undo/redo each action. Accept only if relative timing follows the written policy, locked tracks behave explicitly, and no invalid/dangling anchor survives. In M6, compare mistakes and recovery against manual grouping. | +| Explicit position mode | Reuse existing overwrite/remove commands without a mode. A mode adds state and discoverability work. | At wide/half/narrow layouts, ask users to replace a shot without moving later edits and then restore it. Require the destination, displaced material, and gap to be predictable, including keyboard-only operation. | +| Prior project version | Autosave alone is simpler and covers interruption, but also saves user mistakes. Versions use storage and need retention/restore UI. | Inject interruption during save and reopen; separately make an unwanted edit, autosave, then restore an earlier valid version. Accept only if project integrity and media references are preserved; document that source files require separate backup. | +| Proxy representation | First try bounded decode-ahead, reduced preview quality, and background render. Proxy generation costs time and disk. | On representative 1080p/4K phone and recording fixtures, compare smoothness/tail frame time, seek delay, generation time, disk use and output fidelity at fixed hardware/driver. Accept only for workloads where the end-to-end benefit is material; export must resolve originals or fail clearly. | +| Roles/keywords | Filename/date search and existing tracks are cheaper. Metadata and stem export add persistence/UI work. | Defer until users cannot find source shots or repeatedly need separate audio deliverables in observed tasks. | +| FCPXML | OTIO first has a public adapter/schema path already planned. FCPXML adds versioned bundle, timing and feature-mapping work. | Import actual version-pinned exports covering cut, connected clip, gap, audio and transition. Compare duration, order, anchors and media references; report every unsupported object. No blanket “Final Cut compatible” label from parsing alone. | + +This review executed **documentary checks only**: Apple guide passages and the +local model/plan were inspected. No Final Cut installation, exported fixture, +user study, workload benchmark, or crash injection was run. The acceptance +criteria above are proposed before results. No comparative performance or +usability claim follows from this review. + +[Return to final-cut-pro.md](final-cut-pro.md) diff --git a/Docs/Research/final-cut-pro.md b/Docs/Research/final-cut-pro.md new file mode 100644 index 0000000..baf7f0e --- /dev/null +++ b/Docs/Research/final-cut-pro.md @@ -0,0 +1,26 @@ +# Final Cut Pro: lessons for OmaMovie + +> Documentary research, 2026-10-04. Scope: Final Cut Pro **for Mac**, with the +> Apple guide's 12.4 page used where a version is exposed. This describes +> documented behavior, not a hands-on test, usability study, or performance +> comparison. Sources and access limits are recorded below. + +## Conclusion and decision + +[Read this section](final-cut-pro-decision.md) + +## What Apple's documents establish + +[Read this section](final-cut-pro-documentation.md) + +## Foundation and fit to this repository + +[Read this section](final-cut-pro-local-fit.md) + +## Alternatives, tests, and stopping rules + +[Read this section](final-cut-pro-tests.md) + +## Source and stopping record + +[Read this section](final-cut-pro-sources.md) diff --git a/Docs/Research/gpu-effects-checks.md b/Docs/Research/gpu-effects-checks.md new file mode 100644 index 0000000..7480e3d --- /dev/null +++ b/Docs/Research/gpu-effects-checks.md @@ -0,0 +1,7 @@ +## Open checks + +- End-to-end grading cost in the viewer. The isolated 1080p benchmark measured + +0.83 ms and +1.24 ms in two runs for all three stages, around a +1 ms target; + it includes a synchronous software-frame upload and does not measure presentation. +- AMD/NVIDIA behavior; only Intel was measured. +- Keyframe interpolation against FCPXML/Resolve exports once importers exist. diff --git a/Docs/Research/gpu-effects.md b/Docs/Research/gpu-effects.md new file mode 100644 index 0000000..d34d76d --- /dev/null +++ b/Docs/Research/gpu-effects.md @@ -0,0 +1,58 @@ +# GPU post-production effects + +> Researched on 2026-10-04 with skeptical-research, algorithmic-project-review, ponytail and +> anti-ai-mediocrity. Non-normative: the decisions live in [ADR-0012](../adr/0012-color-grading.md). Local evidence: +> [evidence/2026-10-04-gpu-effects.txt](evidence/2026-10-04-gpu-effects.txt) with the +> [benchmark](evidence/2026-10-04-compositor-bench.cpp) and the +> [numerics](evidence/2026-10-04-grading-numerics.py). + +Question: how to add color grading (3D LUTs, color wheels, curves), multi-pass effects and +keyframes to the Vulkan compositor without breaking its invariants (CPU reference, render +graph as plain data, no readback, timeline without GPU types). + +## Conclusions + +| Topic | Recommendation | Basis | +|---|---|---| +| Order | Grading first, then the multi-pass rework of blur, then keyframes | Grading fits the existing per-pixel pass; blur is the measured bottleneck | +| Wheels | Store ASC CDL (slope, offset, power per channel + saturation); the UI shows lift/gamma/gain | The mapping is exact (evidence 2a); CDL is public and travels in CMX EDLs through OTIO | +| Curves | Monotone cubic (Fritsch–Carlson) evaluated in the shader from at most 16 points | No overshoot; a 256-entry table misses the 10-bit step on steep curves (2b) and 1024 entries do not fit a per-layer UBO comfortably | +| 3D LUT | Tetrahedral interpolation with `texelFetch`, the same code path as the CPU reference | Greys stay grey (2c); four reads instead of eight; FFmpeg's default | +| Grading space | BT.709 primaries, re-encoded with the inverse of the layer's own transfer function, clamped to [0, 1] | The LUT and curves see the file's code values, as in a Rec.709 timeline; CDL's ASC style clamps too | +| `.cube` parser | 3D only, red fastest, `DOMAIN_MIN/MAX` and Resolve's `LUT_3D_INPUT_RANGE`, size 2–65, fuzzed | Both keyword families exist in the wild; size 256 would be 268 MB of floats | +| ComputeBackend | Not now | No effect needs a second backend; CLAUDE.md §9.3 asks for CUDA only on a measured gain | +| Blur | Linearize the source once per layer, then blur a downsampled pyramid | Measured 52.6 ms (1080p) and 214 ms (4K source) at maximum; cost is source pixels × taps. **Done** as a separable box reduction (evidence §5): about 3 ms and 5.7 ms | +| Keyframes | Hold/linear/ease, clip-relative `RationalTime`, evaluated in `timeline::evaluate` | Weak external evidence; the render graph already receives evaluated parameters (§9.1). **Implemented for the transform** (2026-10-04) with one deviation: keys sit in the clip's source time, not clip-relative time, so split/trim/slip/speed keep the motion on the picture without changing any edit command; lookup is a binary search, O(log k) | + +## Evidence + +**Documented.** OCIO's Resolve cube reader reads red-fastest data, optional +`LUT_3D_INPUT_RANGE`, 1D shaper plus 3D, and rejects wrong row counts +([source](https://raw.githubusercontent.com/AcademySoftwareFoundation/OpenColorIO/main/src/OpenColorIO/fileformats/FileFormatResolveCube.cpp)). +FFmpeg's `lut3d` reads `DOMAIN_MIN/MAX` and defaults to tetrahedral interpolation +([source](https://raw.githubusercontent.com/FFmpeg/FFmpeg/master/libavfilter/vf_lut3d.c)); +its ticket #10431 records that the Adobe 1.0 specification names `DOMAIN_MIN/MAX`, not the +`*_INPUT_RANGE` keywords ([ticket](https://ffmpeg.org/pipermail/ffmpeg-trac/2023-June/066367.html)). +OCIO's CDL "ASC" style clamps to [0, 1] and uses Rec.709 luma for saturation +([docs](https://opencolorio.readthedocs.io/en/latest/api/transforms.html)). OTIO's CMX 3600 +adapter carries `ASC_SOP`/`ASC_SAT` ([adapters](https://opentimelineio.readthedocs.io/en/v0.15/tutorials/adapters.html)). +A SMPTE study reports tetrahedral matching trilinear quality with LUTs 20–25% smaller +([abstract](https://journal.smpte.org/periodicals/SMPTE%20Motion%20Imaging%20Journal/129/2/17/)). + +**Not read directly.** The Adobe Cube LUT Specification 1.0 PDF (the archived copy was not +reachable); its content above comes through the FFmpeg ticket and the OCIO reader. + +**Observed locally.** Render times and numerics in the evidence file. The benchmark is +synchronous and includes the software-frame upload; one GPU only. + +**Algorithmic analysis.** Blur cost is `source_px × (2r + 1) × 2` taps plus a composite reading +the blurred image. Pass 1 decodes YUV and runs three `pow` per tap (`texel()` in +`shaders/composite.comp`): 387 `pow` per pixel at r = 64. `make_detail` clamps sigma to 21.3 px +(`src/look.cpp`), so at maximum a 2160p source gets half the relative blur of a 1080p one: the +strength depends on the file's resolution. Both are fixed by a linear-RGB intermediate and a +downsampled pyramid (cost independent of the radius), at 16 MB (1080p) or 66 MB (2160p) of +RGBA16F per layer that needs it. + +## Open checks + +[Read the pending checks](gpu-effects-checks.md) diff --git a/Docs/Research/hardware-strategy.md b/Docs/Research/hardware-strategy.md index 62fd7bc..111ba3d 100644 --- a/Docs/Research/hardware-strategy.md +++ b/Docs/Research/hardware-strategy.md @@ -1,129 +1,56 @@ -# Hardware strategy: synthesis +# Hardware strategy after skeptical review -> Synthesis of [`vulkan.md`](vulkan.md), [`cuda.md`](cuda.md), [`opencl.md`](opencl.md) (OpenCL -> removed) and [`omarchy-integration.md`](omarchy-integration.md). It is a proposal for -> discussion: it becomes a rule only after it enters `CLAUDE.md` or an ADR. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. -Goal: **use all available hardware** (decode, encode and compute on Intel, AMD and NVIDIA) -**without taking frames out of VRAM** and without requiring users to install anything beyond -what Omarchy already installs. +## 1. Supported direction ---- +Use the existing Vulkan compositor with explicit resource ownership, bounded work and a +logged software-decode fallback. Preserve the ADR-0004 application-owned device design, +while keeping Qt integration provisional until Q1/S4. No vendor-wide real-time or zero-copy +promise follows from one Intel report. -## 1. Proposed architecture +## 2. Roles and alternatives -``` - ┌──────────────── libs/gpu ─────────────────┐ - │ single VkInstance / VkDevice (Vulkan-Hpp) │ - │ queue lock · VMA · imported memory │ - └───────┬──────────────┬──────────────┬──────┘ - │ │ │ - ┌────────────────────────▼──┐ ┌───────▼────────┐ ┌──▼──────────────────┐ - │ libs/media (FFmpeg 9) │ │ libs/compositor│ │ apps/omamovie (Qt) │ - │ hwcontext_vulkan on │ │ render graph → │ │ QQuickGraphicsDevice │ - │ OmaMovie's device │ │ Vulkan (+ libplacebo?)│ ::fromDeviceObjects│ - │ │ │ ComputeBackend │ │ QSGVulkanTexture │ - │ Decode: │ │ ├ Vulkan (default)│ ::fromNative │ - │ Intel/AMD: Vulkan Video │ │ ├ CPU (reference) │ - │ or VA-API→map │ │ └ CUDA (optional, PTX) │ - │ NVIDIA: NVDEC→interop │ │ │ - │ or Vulkan Video │ └────────────────┘ └─────────────────────┘ - │ Encode: │ - │ Intel/AMD: Vulkan/VA-API │ AVVkFrame (one timeline semaphore per image) - │ NVIDIA: NVENC │ = OmaMovie's Frame, without copies - │ Intermediates: ProRes/FFv1 │ - │ in compute shaders │ - └────────────────────────────┘ -``` - ---- - -## 2. Role of each API - -| API | Role | Required? | +| Component | Current direction | Evidence boundary / alternative | |---|---|---| -| **Vulkan (Vulkan-Hpp)** | Single device; compositing; preview; default compute for effects; video decode/encode on AMD/Intel; compute codecs (ProRes, FFv1) | **Yes** | -| **VA-API** | Mature decode/encode on Intel/AMD; mapped to Vulkan by FFmpeg | Yes (through FFmpeg), chosen at runtime | -| **NVDEC/NVENC** | Decode/encode on NVIDIA; NVENC is much faster than Vulkan encode | Yes on NVIDIA (through FFmpeg, no toolkit) | -| **CUDA (driver API)** | NVDEC → Vulkan interop; optional kernels | Loaded at runtime, NVIDIA only | -| **CUDA (kernels)** | Effects with a measured gain on NVIDIA | Optional, optional build | -| ~~OpenCL~~ | **Removed** (decision of 2026-10-02, see `opencl.md`) | No | -| **libplacebo** | Candidate for color, tone mapping, scaling, LUTs | To be decided (ADR) | - ---- - -## 3. Runtime selection - -At startup, `libs/gpu` + `libs/media` build a **capability table** (logged in the `gpu` -category and shown on a diagnostics screen): - -| Question | Source | -|---|---| -| Which codecs/profiles/bit depths does Vulkan Video decode and encode? | `vkGetPhysicalDeviceVideoCapabilitiesKHR` | -| What does VA-API offer? | `vaQueryConfigProfiles` / FFmpeg | -| Is NVDEC/NVENC present? | Presence of `libnvcuvid`/`libnvidia-encode`, FFmpeg | -| Is CUDA present? | `dlopen` of `libcuda` | -| Which GPU is primary (hybrids)? | User choice or a heuristic, without waking the dGPU needlessly | - -For each stream, the decode path is chosen by an **ordered, testable policy** (e.g. Intel H.264 -→ VA-API if the benchmark favors it, else Vulkan Video → software). A software fallback is -always possible, and every degradation is logged (`CLAUDE.md` §19). - ---- - -## 4. Changes relative to the current `CLAUDE.md` - -Proposals (pending the maintainer's approval): - -1. ~~OpenCL as the generic backend~~ **Applied on 2026-10-02**: OpenCL removed; Vulkan Compute - is the generic backend (`CLAUDE.md` §4 and §9.3). -2. **Explicit Vulkan-Hpp** in the stack: `vk::raii`, no exceptions (`VULKAN_HPP_NO_EXCEPTIONS` + - `VULKAN_HPP_RAII_NO_EXCEPTIONS` with `std::expected`), include confined to - `libs/gpu`/`libs/compositor`. Affects §4 and §22. -3. **A single Vulkan device shared with FFmpeg and Qt** as an invariant. Affects §7 and §9.4. -4. **CUDA policy**: NVDEC/NVENC through FFmpeg without the toolkit; kernels only through PTX - (clang) + `dlopen`; optional CUDA build. Affects §4 and §9.3. -5. **Hybrid laptops**: one primary device per pipeline. Affects §7. -6. **Omarchy integration**: app_id `omamovie`, opacity rule, theme through - `omarchy-theme-color`, an isolated platform module. Affects §11. -7. **The `vulkan-headers` package** (and `vulkan-tools` for diagnostics) in the build dependencies. - ---- +| Vulkan | Composition, effects, optional video/compute codecs | Query device/profile/features and verify output | +| VA-API | First decode candidate on the reference Intel setup | Import may fail; software + upload remains baseline | +| Vulkan Video | Candidate when normally exposed | Debug-flag tests are exploratory, not supported defaults | +| NVDEC/NVENC | NVIDIA candidates | S7 pending; compare native Vulkan and total interop cost | +| CUDA effects | Optional specialization | Need an actual effect and same-output measurement | +| OpenCL | Excluded by project scope | Generic interop exists; no current use case | +| libplacebo | Color/scaling candidate | S6 and ADR-0006 pending | +| VMA | Allocation candidate | Existing wrappers first; adopt on demonstrated need | -## 5. Validation spikes (before the definitive code) +[API/source evidence](sources.md) establishes contracts, not total pipeline performance. -Each spike has a measurable criterion. They replace the technical part of the "first -experiment" in `CLAUDE.md` §24. +## 3. Runtime policy -| # | Spike | Success criterion | Hardware | -|---|---|---|---| -| S1 | `vulkaninfo` + `vainfo`: capability inventory on the Iris Xe | Documented codec × API table | Iris Xe | -| S2 | FFmpeg 9 using a `VkDevice` created by OmaMovie (Vulkan-Hpp) | H.264/HEVC/AV1 decoded into `AVVkFrame` without readback | Iris Xe | -| S3 | Vulkan Video vs. VA-API→map: frame time, CPU, power | Numbers per codec; selection policy defined | Iris Xe | -| S4 | Qt Quick on the same device showing the compositor image | 60 fps preview without a CPU copy; queue lock without deadlock | Iris Xe | -| S5 | Compositing 2 videos + 1 image (transform, crop, opacity, YUV→RGB) | Frame time measured at 1080p60 | Iris Xe | -| S6 | libplacebo on OmaMovie's images | Color conversion/scaling without copies; decision for the ADR | Iris Xe | -| S7 | NVDEC → Vulkan (interop) vs. Vulkan Video on NVIDIA | NVIDIA path chosen by measurement | **Needs an NVIDIA machine** | -| S8 | AMD (RADV) | Same measurements as S3 | **Needs an AMD machine** | +Distinguish five states: available API/library, advertised capability, successful open, +actual negotiated hardware frame, and validated path for this workload. Only the last +supports a compatibility/performance claim. Log skipped/failed paths and reasons. ---- +ADR-0004's VA-API → Vulkan → software order is provisional for the measured Intel setup. +Do not infer NVDEC availability from `libnvcuvid` presence. Match device identity for imports; +probe support at codec/profile/chroma/depth/size granularity. Driver-specific policy changes +need evidence, not a universal vendor ranking. Software fallback is correct behavior and +still needs a workload budget; it is not guaranteed real time. -## 6. Main risks +## 4. Device and synchronization choices -| Risk | Mitigation | -|---|---| -| Queue synchronization between Qt, FFmpeg and the compositor | S4 early; a single lock mechanism; ADR-0005 | -| Driver differences in DMA-BUF/modifiers | Use FFmpeg's mapping; fallback with a logged GPU→GPU copy | -| CUDA does not accept wait-before-signal | The scheduler guarantees the order; specific tests | -| No AMD/NVIDIA hardware for testing | Plan test machines or contributors; CI only covers software paths | -| Vulkan-Hpp compile cost | Confined include + PCH; evaluate the `vulkan` module | -| libplacebo not accepting external images as expected | S6 before deciding | +A shared device reduces explicit inter-device imports. A device created by FFmpeg could also +be handed to a consumer; it does not inherently force a second device or copy. The reason +for OmaMovie ownership is control over creation/features/lifetime (current ADR), not that +other ownership is impossible. ---- +Queues need host synchronization; images need GPU dependencies, layouts and lifetime. +Qt's ordinary imported-device path has an identified flagged-queue mismatch (Q1). +An application mutex protects Qt only if Qt submissions actually participate in that +protocol. Decide among render-thread submission, controlled rendering, verified native +queue injection, or separate-device external-memory import in S4/ADR-0005. -## Suggested next steps +## 5. Experiments and gates -1. The maintainer decides the remaining points of §4 (mainly libplacebo). -2. Update `CLAUDE.md` with whatever is approved. -3. Install `vulkan-headers vulkan-tools libva-utils` and run S1. -4. Continue with S2–S4 (M1 in `Docs/implementation-plan.md`). +[Continue in hardware-validation.md](hardware-validation.md) diff --git a/Docs/Research/hardware-validation.md b/Docs/Research/hardware-validation.md new file mode 100644 index 0000000..6ef644f --- /dev/null +++ b/Docs/Research/hardware-validation.md @@ -0,0 +1,32 @@ +## 5. Experiments and gates + +| Spike | Review status | Required additional evidence | +|---|---|---| +| S1 | Prior Intel report, not rerun | Retain capability vs executed-codec distinction; raw output/provenance | +| S2 | Prior single-submitter report, not rerun | Validation layers, chroma/multiple frames, lifetime/cancellation | +| S3 | Pending | Repeated equivalent workloads; decode + import + consumer, encode quality | +| S4 | Pending; Q1 identified | Queue retrieval, submission/lifetime protocol, display conversion | +| S5 | Library tests contain timings | End-to-end playback, percentiles/drops, independent color oracle | +| S6 | Pending | Installed libplacebo contracts, image-quality and copy comparisons | +| S7 | Pending; NVIDIA unavailable | Decode+interop+composition and export on actual NVIDIA | +| S8 | Pending; AMD unavailable | Same criteria on actual AMD | + +Protocols and stop criteria live in [the audit](skeptical-review.md#validation-protocols). +No pending experiment is relabeled as completed by this documentary review. + +## 6. Capacity model + +Use measured resource budgets, not only throughput. Tightly packed 4K RGBA16F is 63.28 MiB +per frame; three streams with eight such cached frames consume about 1.48 GiB before decoder +pools, intermediate targets and padding. This is a calculated lower-bound illustration, +not measured VRAM usage. [Inputs and calculations](skeptical-review.md#quantitative-checks). +On integrated GPUs, GPU-local allocation does not imply physically separate VRAM. + +## 7. Application decision + +Continue bounded Intel correctness work. Resolve Q1 and SDR/display handling before wiring +the final UI. Support claims must name tested hardware/drivers/media; untested AMD/NVIDIA +remain planned. Choosing a proxy codec also needs storage, seek, quality and compatibility +measurements; GPU compute decode alone does not justify FFv1/ProRes as the default. + +[Return to hardware-strategy.md](hardware-strategy.md) diff --git a/Docs/Research/hyprland-flicker-coverage.md b/Docs/Research/hyprland-flicker-coverage.md new file mode 100644 index 0000000..42e0f36 --- /dev/null +++ b/Docs/Research/hyprland-flicker-coverage.md @@ -0,0 +1,8 @@ +## Coverage and next action + +This pass inspected local code, installed component versions, native smoke +runs, Qt/Quickshell documentation and two Hyprland reports. It did not capture the +reported flicker, run the A/B matrix, or prove a cause. The cheapest decisive next +observation is a private compositor recording aligned with Qt frame and window +events during the existing resize stress. Add those diagnostics to a dedicated +resize audit before changing the rendering path or Hyprland configuration. diff --git a/Docs/Research/hyprland-flicker-gate.md b/Docs/Research/hyprland-flicker-gate.md new file mode 100644 index 0000000..5a8df75 --- /dev/null +++ b/Docs/Research/hyprland-flicker-gate.md @@ -0,0 +1,29 @@ +## Discriminating gate before a workaround + +On the same display, media fixture, tiling layout and resize script, collect: + +1. A 60 fps compositor recording of the OmaMovie rectangle during 30 repeated + half-width/full-width changes, 20 Projects/Edit/Settings switches and 10 + show/hide cycles. Keep the full recording and time-stamped event list. Inspect + every visible flash and label it: stretched old surface, blank entire app, + blank viewer only, stale UI, or unrelated layer. The current `gpu-screen-recorder` + and `ffmpeg` are available; use a private fixture and avoid recording other + windows or personal content. +2. Qt `frameSwapped`, `sceneGraphInvalidated`, `sceneGraphError`, window exposure, + size and device-pixel-ratio timestamps; viewer composite success/failure and + frame ID; Hyprland window geometry and layer-zone changes. Correlate by a + monotonic clock. Count gaps over two display periods (about 33 ms at 60 Hz) + during an expected redraw, and count blank/stale screen frames separately. +3. Repeat with hardware preview decode forced off (`OMA_PREVIEW_HARDWARE=0`) and + on, a Qt-only Vulkan sample window, and one other Wayland compositor if + available. Compare the same workload, not arbitrary normal use. Repeat with + and without Quickshell **only after arranging a reversible session-local test**; + do not alter the user's shell or window rules as part of the app test. + +Accept an app-side fix only when the recorded symptom disappears or materially +improves in repeated A/B runs and the same edits, playback and UI layout still +pass. Stop and classify as compositor-side if app commits are timely and correct +but only Hyprland's displayed surface flashes, with an independent Qt client +showing the same pattern. If shell presence changes the result, inspect its +specific layer geometry before proposing any rule. Full opacity controls wallpaper +blending; it has no demonstrated effect on this resize symptom. diff --git a/Docs/Research/hyprland-flicker-hypotheses.md b/Docs/Research/hyprland-flicker-hypotheses.md new file mode 100644 index 0000000..6fb9a18 --- /dev/null +++ b/Docs/Research/hyprland-flicker-hypotheses.md @@ -0,0 +1,27 @@ +## Decision and competing explanations + +Treat the reported flicker inside the OmaMovie window during repeated resizing +and screen changes as an open release defect. Three mechanisms can produce similar +symptoms: + +1. **OmaMovie/Qt presentation gap.** Its Qt Quick Vulkan swapchain may not present + a new-size frame promptly; its borrowed viewer image or shared-device queue may + also fail or stall. Prediction: a captured application surface contains a blank, + old-size or stale viewer frame, or Qt frame-swap timestamps show a gap correlated + with the event. The same defect may appear under another Wayland compositor. +2. **Hyprland texture expansion.** The compositor may scale the old surface while + waiting for the client to commit a new-size buffer. Prediction: the screen + recording shows stretched or flashing borders while the application's new + surface, once committed, has correct content. A different Qt app under the same + tiling resize should show a related effect. A Hyprland maintainer describes + this behavior in [discussion 14399](https://github.com/hyprwm/Hyprland/discussions/14399) + (May 2026); that report is an analogy, not proof about OmaMovie. +3. **Shell-layer geometry.** Quickshell's `PanelWindow` can reserve an + `exclusiveZone` in the compositor. A bar or overlay geometry change can resize + tiled clients independently of their content. Prediction: the effect tracks + layer-zone changes and differs in an otherwise identical run without the shell + layer. See [Quickshell PanelWindow](https://quickshell.org/docs/v0.2.1/types/Quickshell/PanelWindow/) + and the separate, unresolved [Hyprland report 15177](https://github.com/hyprwm/Hyprland/discussions/15177). + +These explanations can coexist. A visible flash alone does not identify which +surface was late. diff --git a/Docs/Research/hyprland-flicker-observations.md b/Docs/Research/hyprland-flicker-observations.md new file mode 100644 index 0000000..f3b282e --- /dev/null +++ b/Docs/Research/hyprland-flicker-observations.md @@ -0,0 +1,36 @@ +## Local observations + +- Installed: Hyprland 0.56.2, Qt 6.11.2, Quickshell 0.3.1, Mesa 26.2.2, Intel Iris Xe; + one 1920×1080, scale-1, approximately 60 Hz `eDP-1` monitor. `hyprctl layers -j` + shows `omarchy-background` and `omarchy-bar`. A process listing outside the + sandbox confirms `quickshell -n -p .../omarchy-v4.0.4/shell`. An earlier sandboxed + process query returned an empty result and was discarded. +- `make run-gui RUN_GUI_SMOKE=1` passed on this desktop. The smoke performs 24 + large resizes with Projects/Settings switches and 24 more around the layout + breakpoint. It checks the final layout and one nonempty `grabWindow()` image. + Its keyboard check was skipped because the window did not retain focus. This + is evidence of recovery, **not** absence of transient flicker or present stalls. +- An opt-in `OMA_PRESENT_TRACE=1` run outside the sandbox passed the same smoke, + including keyboard focus. It recorded 448 queued-frame events, 58 width changes, + 23 height changes and no scene-graph error. The trace records event times in + microseconds since window creation. This still does not identify what was + actually displayed by Hyprland. The first traced attempt aborted in the + sandbox before the application emitted events; it is not counted as an app + failure. Reproduce the trace with + `OMA_PRESENT_TRACE=1 make run-gui RUN_GUI_SMOKE=1 2> /tmp/omamovie-present-trace.log`. + Per-frame stderr logging perturbs timing, so compare a trace run with an + untraced capture before treating a small latency difference as meaningful. +- The app shares one Vulkan device between Qt Quick, its compositor and optional + hardware decode (`main.cpp`, `PreviewItem`, ADR-0005). The bridge gates workers + around Qt frames and the viewer wraps the compositor's `VkImage` in a + `QRhiTexture`. This is a plausible failure boundary, not a demonstrated fault. + Qt documents that Vulkan normally uses a threaded scene graph and that + [`frameSwapped()`](https://doc.qt.io/qt-6.8/qquickwindow.html) means queued for + presentation. Qt's [swapchain guidance](https://doc.qt.io/qt-6.11/qrhiswapchain.html) + says surface pixel size may differ from window size during resize. OmaMovie lets + Qt manage its own swapchain, so it should not attempt to recreate it from + `QWindow::size()` itself. +- The existing `grabWindow()` smoke cannot serve as a continuous presentation + oracle: Qt warns it is costly, and ADR-0005 records validation hazards from + capture on the shared Vulkan device. A compositor-level recording and + application frame timestamps are better complementary observations. diff --git a/Docs/Research/hyprland-flicker.md b/Docs/Research/hyprland-flicker.md new file mode 100644 index 0000000..bdae63d --- /dev/null +++ b/Docs/Research/hyprland-flicker.md @@ -0,0 +1,9 @@ +# OmaMovie resize flicker on Hyprland and Quickshell + +Research and local check, 2026-10-11. This is a diagnostic record, not a confirmed +root cause or a recommendation to change the user's compositor configuration. + +- [Decision and competing explanations](hyprland-flicker-hypotheses.md) +- [Local observations](hyprland-flicker-observations.md) +- [Discriminating gate before a workaround](hyprland-flicker-gate.md) +- [Coverage and next action](hyprland-flicker-coverage.md) diff --git a/Docs/Research/imovie.md b/Docs/Research/imovie.md index 7cecdda..ccf3b2a 100644 --- a/Docs/Research/imovie.md +++ b/Docs/Research/imovie.md @@ -1,229 +1,54 @@ -# Apple iMovie: UI/UX +# iMovie: documented interactions and UX hypotheses -> Research done on 2026-10-02. Sourced facts are linked in the [Sources](#sources) section. -> Items marked **(general observation)** come from broad knowledge of the product without a -> specific source in this research; verify before using them as requirements. -> -> The goal is to extract UX **principles**. `CLAUDE.md` forbids copying iMovie's visual identity -> or proprietary behavior. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +Contextual adjustment controls, editable named overlays and skimming are useful references. +They support prototype choices, not a finding that OmaMovie's proposed UI is already easy. +The claim that iMovie shares Final Cut's internal engine is withdrawn from architectural +justification: the inspected Apple guide establishes transfer, not implementation identity. -iMovie is simple because: +## 2. Documented behavior -1. the screen has **three fixed areas** (browser, viewer, timeline) and little else; -2. adjustment controls appear **in context**, in a bar above the viewer; -3. compositing effects are offered as **intent-named operations** (picture-in-picture, - cutaway, split screen, green screen), not as generic layers and parameters; -4. the timeline is **magnetic**: it leaves no gaps and avoids collisions; -5. there are **templates** (themes, trailers, storyboards, Magic Movie) for those who do not want to start from scratch; -6. underneath, since 2013, it uses the **Final Cut Pro X engine**, and a project can be sent to Final Cut Pro. +[Apple's Mac guide](https://support.apple.com/en-nz/guide/imovie/welcome/mac) lists trimming, +clip color, skimming, ratings, multiple-clip effects and conversion of trailers to movies. +Its examples put adjustments near the viewer. These are documented interactions; their +presence does not quantify discoverability or learnability for Omarchy users. -Item 6 is the most relevant for OmaMovie: it is exactly "simple UI, serious pipeline". +[Sending to Final Cut](https://support.apple.com/guide/imovie/send-projects-to-final-cut-pro-movcbf7e2a3f/mac) +copies project/media and maps at least one audio adjustment to a Gain filter. Trailers must +first be converted. This proves a supported workflow with conditions, not shared code, +unlimited capability, or lossless mapping of every effect. ---- +## 3. Foundations and model -## 2. History relevant to UX +Separate presentation from persisted edit semantics. A contextual drawer changes visible +controls; it must not become the owner of clip parameters. Named operations may emit normal +model commands; that is an OmaMovie design inference, not a description of Apple's internals. -| Year | Version | Change | -|---|---|---| -| 1999 | iMovie 1 | Launched with the iMac DV | -| 2004 | iMovie 4 | Non-destructive editing ("Direct Trimming") | -| 2005 | iMovie HD (5/6) | HDV support | -| 2007 | **iMovie '08** | Full rewrite by Randy Ubillos focused on speed. Introduced **skimming** and **Events** (clips grouped by day). **Heavily criticized**: removed timeline audio and plugins. David Pogue called it "an utter bafflement" | -| 2009–2010 | iMovie '09 / '11 | Brought removed features back; added **trailers** and the **Precision Editor** | -| 2013 | **iMovie 10** | New rewrite on the **Final Cut Pro X engine**; libraries | -| 2015 | 10.1 | 4K editing | -| 2020 | 10.2 | Apple silicon | -| 2022 | iOS 3.0 | **Storyboards** and **Magic Movie** | +Magnetism/ripple is a chosen editing policy over generic tracks. Specify linked audio, +connected overlays, gaps, locked tracks and undo transaction boundaries before implementing +it. A single simple-looking sequence can hide surprising moves on other tracks. -### The iMovie '08 lesson +## 4. Alternatives and proposed test -The rewrite brought good ideas (skimming, organization by events) but removed capabilities -users already had. The negative reaction forced Apple to put features back over the next two -versions. +Compare contextual drawer with a fixed side inspector; compare ripple default with ordinary +track placement. M6 tasks: import, split, trim, overlay, gain and undo at wide/half/narrow +sizes using mouse and keyboard. Record completion, mistakes, recovery, hidden-control +searches and surprise track movements. Prefer a design only after representative tasks +show no required action is inaccessible and improvement does not break precise editing. +No usability test was executed by this review. -**For OmaMovie:** simplifying the UI **must never mean removing capability** already shipped. -That is the "hide, do not remove" principle of `CLAUDE.md` (§11), with a concrete historical case. +Skimming requires cancelable decode/cache work, but every hover need not trigger a full seek. +Compare cached thumbnails with live decode; track request age and stale output, not just FPS. ---- +## 5. Removed arguments and application limits -## 3. Window layout - -According to the official guide, the window has three areas: - -- **Browser**: media and content library (transitions, titles, audio, backgrounds). -- **Viewer**: preview, with filters and effects applied. -- **Timeline**: the project sequence, video on top and audio below. - -Interaction details: - -- **A single divider resizes everything**: dragging the border between viewer and timeline up - or down adjusts all three areas proportionally. -- The **Libraries List** and the **browser** can be hidden (the "Content Library" toolbar button). -- **Window > Revert to Original Layout** restores the default layout. -- There are no free panels or workspaces. - -### Implications for OmaMovie - -- The target layout in `CLAUDE.md` (MediaPanel, PreviewPanel, TimelineView, Inspector, - TransportControls) is similar in spirit. To keep it simple: **few dividers, a fixed layout, - "restore layout" always available**. -- In Hyprland the user already manages windows in a tiling layout. A single window with a fixed - internal layout fits that better than floating panels. - ---- - -## 4. Contextual adjustments bar - -- The **adjustments bar** sits above the viewer. When a clip is selected in the browser or the - timeline, its buttons show the corresponding controls. -- Documented example (color): the **Color Balance** button and the **Color Correction** - button, which shows a multi-slider control, saturation and color temperature. -- Applied state is visible: buttons are highlighted when an automatic adjustment is applied to the clip. -- Interactive tools (e.g. the eyedropper) appear **in the viewer** when needed. -- The guide lists other adjustments of the same kind: auto enhance, crop, rotation, Ken Burns, - stabilization, filters, speed, volume. - -### Implications for OmaMovie - -- This is the **contextual Inspector** model of `CLAUDE.md` §11, with one detail to adopt: - **visually show which adjustments are active on the clip** (badge or highlight) without - opening each section. -- **Direct manipulation in the preview** (crop, position, eyedropper) beats numeric fields for - most users. Numeric values should exist in the inspector for precision. Technical implication: - the PreviewPanel needs interactive overlays that talk to the model through commands (with - undo), without keeping state of their own. - ---- - -## 5. Timeline and editing - -### Magnetic timeline - -The concept comes from Final Cut Pro X, whose engine iMovie uses: clips "magnetically" adjust -around a dragged clip, and when a clip is removed its neighbors close the gap. There are no -accidental gaps. - -### Trimming methods (documented) - -1. **Drag the clip edges** in the timeline. -2. **Clip Trimmer**: shows the unused part of the clip dimmed; lets you extend, shorten or slide - the used section without changing duration (equivalent to a **slip**). -3. **Precision Editor**: double click an edge; adjusts the start and end of clips and the - duration of transitions; supports **split edits** (audio and video with different cut - points, J-cut/L-cut). -4. **Range selection** (hold R + drag) and "Trim Selection". - -### Overlays as named operations - -Picture-in-picture, cutaway, split screen and green screen are offered as **high-level -effects**: the user places a clip above another and picks the intent. No need to understand -layers, masks or blend modes. Compositing capability is **limited** (no arbitrary multiple -video layers and no general keyframes) **(general observation)**. - -### Implications for OmaMovie - -- **Magnetic timeline as the default UI behavior**, implemented as ripple in the model. The - timeline model stays generic (free tracks, gaps allowed); "magnetism" is an editing policy - applied by the UI's commands. -- **Precision Editor = a friendly UI for roll and split edits.** It shows advanced trimming - can be simple with good visualization (showing the unused material). The command model in - `premiere-pro.md` §3 serves both audiences. -- **Named operations compiled to the generic compositor**: "Picture in picture" in the UI - becomes layers + transform + crop + border in the render graph. OmaMovie can offer iMovie's - presets **without** its layer limitation, because the compositor is generic. This applies - "simple UI, serious pipeline" directly. -- The preset must stay editable: after applying "PiP", the inspector shows normal - transform/crop, and the user can go beyond what the preset provided. - ---- - -## 6. Library and skimming - -- **Skimming** (since iMovie '08): hovering over a clip shows its content at a user-controlled - speed, without pressing play. -- Thumbnail size is adjustable with a slider, as is how much time each thumbnail represents and whether waveforms show. -- Clips can be **rated** (favorite/rejected) and filtered. -- Media is organized into **libraries** and **events**. - -### Implications for OmaMovie - -- Skimming is the interaction that most sets a "visual" library apart. **It needs - architecture**: fast decoding of arbitrary frames (seek), a thumbnail cache at several - densities, and work off the UI thread with aggressive cancellation (the mouse moves faster - than decode). This feeds the cache (§15) and job system (§13) requirements of `CLAUDE.md`. -- Clip ratings (favorite/rejected) are light metadata. A good case for SQLite (§17). - ---- - -## 7. Templates and automation - -- **Themes**: a visual style applied to the titles and transitions of the whole movie. -- **Trailers**: Apple templates per genre, with a shot list and titles; they can be converted into a normal project. -- **Storyboards** (iOS 3.0): ~20 suggested outlines (recipe, Q&A, product review, news report), - with tips per scene; reorderable and editable. -- **Magic Movie** (iOS 3.0): builds a video from selected clips, identifying dialogue, faces - and actions, and adds transitions, music and titles. - -### Implications for OmaMovie - -- The most important point: **a trailer can be converted into a normal project**. Templates - must produce ordinary timeline structures, not a closed special mode. In OmaMovie a template - would be a generator of commands/ProjectIR, without a separate project type. -- Templates and automatic generation are not a priority (initial non-goals), but the "template - → normal timeline" design costs little if planned. - ---- - -## 8. A path to professional tools - -- iMovie has used the Final Cut Pro X engine since 2013. -- The guide documents **sending projects to Final Cut Pro**. - -### Implications for OmaMovie - -- Validates the project's thesis: a simple UI on a professional engine, with no dead end when - the user grows. -- Difference for OmaMovie: Apple has two apps; OmaMovie wants **one app** in which advanced - capability is hidden, not moved into another product. That requires more discipline in the - contextual inspector and in progressive disclosure. - ---- - -## 9. Shortcuts - -The guide has a keyboard shortcuts page (window navigation, editing, playback). iMovie is -usable from the keyboard but mouse-oriented **(general observation)**. - -**For OmaMovie:** `CLAUDE.md` requires full keyboard editing, which means going beyond iMovie -here, closer to Premiere. - ---- - -## 10. What not to copy - -- Visual identity, icons, brand names ("Magic Movie", "Precision Editor") and trade dress. -- **Capability limits** that exist only to keep things simple (fixed number of layers, no - keyframes). OmaMovie hides complexity; it does not remove it. -- Ecosystem dependence (Photos, iCloud). - ---- - -## Sources - -- [Apple: iMovie User Guide for Mac](https://support.apple.com/guide/imovie/welcome/mac) -- [Apple: Change the window layout in iMovie on Mac](https://support.apple.com/guide/imovie/change-the-window-layout-movcab8cb6ef/mac) -- [Apple: Trim clips in iMovie on Mac](https://support.apple.com/guide/imovie/trim-clips-movf8b8fc9b2/mac) -- [Apple: Adjust a clip's color in iMovie on Mac](https://support.apple.com/guide/imovie/adjust-a-clips-color-movf2a3f0f42/mac) -- [Apple: Keyboard shortcuts in iMovie on Mac](https://support.apple.com/guide/imovie/keyboard-shortcuts-movd9d8f91e8/mac) -- [Apple: Send projects to Final Cut Pro](https://support.apple.com/guide/imovie/send-projects-to-final-cut-pro-movcbf7e2a3f/mac) -- [Apple: Final Cut Pro interface (Magnetic Timeline, browser, viewer)](https://support.apple.com/en-vn/guide/final-cut-pro/ver92bd100a/mac) -- [Apple: Intro to the Magnetic Timeline in Final Cut Pro for iPad](https://support.apple.com/it-it/guide/final-cut-pro-ipad/devd9b6a5715/ipados) -- [Wikipedia: iMovie](https://en.wikipedia.org/wiki/IMovie) -- [Engadget: Maybe iMovie '08 isn't such a bad change after all](https://www.engadget.com/2007-08-27-maybe-imovie-08-isnt-such-a-bad-change-after-all.html) -- [Joseph Dickerson: iMovie 08 – a step back?](https://www.josephdickerson.com/blog/2007/08/19/imovie-08-a-step-back/) -- [XDA: Apple iMovie 3.0 introduces Storyboards and Magic Movie](https://www.xda-developers.com/apple-imovie-3-features/) -- [Videomaker: iMovie 3.0 receives two major time-saving features](https://www.videomaker.com/news/imovie-3-0-receives-two-major-time-saving-features/) +The old iMovie '08 history/reaction narrative was not checked against contemporary primary +records and no longer proves a universal prohibition on removing features. Preservation of +shipped capability is a product preference; removal may need explicit migration/deprecation. +No Mac/iOS feature list is treated as interchangeable. Shortcut choices in `ui-design.md` +are OmaMovie assignments, not a certified translation of all Apple shortcuts. diff --git a/Docs/Research/local-source-record.md b/Docs/Research/local-source-record.md new file mode 100644 index 0000000..1710741 --- /dev/null +++ b/Docs/Research/local-source-record.md @@ -0,0 +1,31 @@ +## Local documentary sources + +[Environment snapshot and hashes](evidence/2026-10-03-local.txt) record FFmpeg, Qt, Mesa, +Omarchy package labels, the different installed Omarchy version-file label and inspected +script/header identities. They are observations of this machine, not upstream provenance. + +- `hwcontext_vulkan.h`: queue fields, semaphore values and locks (installed libavutil 61.1.101). +- Omarchy scripts: theme resolution/swap, capture directory/encoder intent, GPU package + selection; Lua window rules and base package list. Source inspected, installer not run. +- Repository baseline `2f6abf3`: `libs/gpu/src/device.cpp`, + `libs/media/src/vulkan_device.cpp`, `libs/compositor/src/color.cpp`, + `tests/compositor/test_compositors.cpp`, `tests/support/lsan.supp`, public APIs/file layout. + Code inspection is distinct from passing tests and performance measurement. The final + existing debug-suite run is retained separately in [test output](evidence/2026-10-03-make-test.txt); + it does not complete the proposed pilots. +- S1/S2 and implementation-plan timing paragraphs: previous experiment reports; not rerun. + Procedures exist, but raw output, repetitions and provenance are incomplete in the docs. + +## Failed access and exclusions + +Apple Final Cut magnetic-timeline URLs attempted in this review, the CapCut `/resource/speed-curve` +URL and a Microsoft Windows Essentials URL returned errors. They supply no evidence. +CapCut's general guide provided a separate accessible speed-curve passage. + +The original NVIDIA speed-ratio/forum, CapCut policy/pricing commentaries, review aggregators, +Movie Maker/iMovie histories and speculative future release details were not adopted as +verified evidence. This register does not imply every old link was checked or every product +installed. Vendor/help sources share their organization's lineage. No independent comparative +benchmark or representative user study was performed or found decisive in this bounded audit. + +[Return to sources.md](sources.md) diff --git a/Docs/Research/long-form-editing-alternatives.md b/Docs/Research/long-form-editing-alternatives.md new file mode 100644 index 0000000..48a2395 --- /dev/null +++ b/Docs/Research/long-form-editing-alternatives.md @@ -0,0 +1,16 @@ +## Alternatives and bounded applications + +| Problem observed | First candidate | Alternative and tradeoff | +|---|---|---| +| Large clip count slows edits or scroll | Retain sorted clip vectors; profile validation, snapshot copies and QML materialization. Pilot visible-range delegates/incremental model updates before altering timeline storage. | An ID/time index can speed lookup but adds mutation and consistency work. Qt documents [incremental models](https://doc.qt.io/qt-6/model-view-programming.html#performance-optimization-for-large-amounts-of-data) and [delegate reuse](https://doc.qt.io/qt-6/qml-qtquick-listview.html#reusing-items); their behavior is evidence of available mechanisms, not proof they fit this timeline. | +| Compressed long-GOP or high-resolution sources seek slowly | Pilot proxies with explicit original/proxy identity, measured generation/disk cost, bounded cache, missing-proxy fallback and original-media export. | An optimized edit-friendly source can help if proxy switches complicate quality checks. FFmpeg's [seek contract](https://ffmpeg.org/doxygen/8.1/group__lavf__decoding.html) is keyframe-based; actual delay is codec/GOP/device dependent. [Kdenlive proxy configuration](https://docs.kdenlive.org/en/getting_started/configure_kdenlive/configuration_proxy_clips.html) is a workflow example, not an OmaMovie speed result. | +| Effects, not decoding, miss preview deadlines | Cache rendered timeline *regions* keyed by source, edit revision, effects, color and preview settings; invalidate only affected ranges. | Source proxies alone retain the effects cost. Kdenlive explicitly distinguishes [timeline preview rendering](https://docs.kdenlive.org/en/tips_and_tricks/tips_and_tricks/timeline_preview_rendering.html) from proxies and says it improves playback, not edit operations. Cache stays disposable and export must be independently checked. | +| JSON load/save becomes costly | First remove avoidable copies, profile parsing vs DTO/restore/reimport, and test the 64 MiB cap against real generated projects. Keep JSON if acceptable. | SQLite as a project store offers transactions and indexed queries, but adds schema/migration, application-file and backup behavior. Its [application-file guidance](https://www.sqlite.org/appfileformat.html) supports it as an option; [WAL behavior](https://www.sqlite.org/wal.html) adds sidecars/checkpoints and network-filesystem limits. It is not an automatic upgrade from simdjson. SQLite remains plausible for a disposable media index. | +| Long export fails or drifts | Build a cancellable export job, write to a temporary destination, verify its decoded output and A/V sync before advertising completion; define failed-job cleanup/retry. | Segmenting or checkpointing an export can help after failures, but exact boundaries and joins add timestamp/GOP/codec complexity. FFmpeg's [segment muxer documentation](https://www.ffmpeg.org/ffmpeg-formats.html#segment-1) warns that split points depend on keyframes. Pilot only after one continuous export works. | + +Kdenlive and Qt documentation describe mechanisms, not comparative measurements on the +OmaMovie machine. SQLite's authors describe database capabilities, not a requirement for +this application. These sources share their own product/institution lineages; they are not +independent evidence of OmaMovie performance. + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing-capacity.md b/Docs/Research/long-form-editing-capacity.md new file mode 100644 index 0000000..c3a5089 --- /dev/null +++ b/Docs/Research/long-form-editing-capacity.md @@ -0,0 +1,27 @@ +## Local code observations and capacity check + +* `project::load` allocates the whole JSON text and the simdjson DOM, then builds a + `Document` and validated `Timeline` (`libs/project/src/document.cpp:822,1061`). The 64 MiB + input cap limits hostile input; it is **not** a useful-video-duration limit. Replacing + the parser does not remove DOM, DTO, timeline or QML copies. +* `Timeline::clip_at` binary-searches clips ordered by start (`libs/timeline/src/model.cpp:139`), + while `evaluate` visits every track and looks up media by linear search + (`libs/timeline/src/evaluate.cpp:185`). `Editor::execute` validates the whole timeline + after each edit (`libs/timeline/src/editor.cpp:9`). Those choices may be fine for small + projects; profile them before adding indexes with update/invalidation costs. +* `Session::afterEdit` makes a new full timeline snapshot and emits `sequenceChanged` + (`apps/omamovie/src/session.cpp:376,1689`). `Session::clips` and `audioTracks` materialize + all clips (`:1473`); multiple QML `Repeater`s instantiate delegates across the sequence + (`apps/omamovie/qml/Main.qml:1504,1611,1844`). This is a concrete scaling candidate + when clip count rises, independent of source duration. +* `VideoScheduler::start` recreates its `FrameSource`, and `stop` waits for the worker + (`apps/omamovie/src/video_scheduler.cpp:10,50`). `FrameSource` chooses forward decode or + seek and bounds its frame history (`apps/omamovie/src/frame_source.cpp:17,63,93`). Measure + rapid seeks and start/stop latency before changing decoder ownership. +* Waveform generation decodes the entire audio source at 100 buckets/s + (`libs/playback/src/waveform.cpp:65`; `waveform.hpp:40`). **Local arithmetic, not a memory + measurement:** two float arrays (peak and RMS) for one two-hour source occupy about + 5.49 MiB at that density; 24 hours occupy about 65.92 MiB, excluding vector capacity, + metadata and duplicate sources. Formula: `seconds × 100 × 2 × sizeof(float)`. + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing-decision.md b/Docs/Research/long-form-editing-decision.md new file mode 100644 index 0000000..65afa3f --- /dev/null +++ b/Docs/Research/long-form-editing-decision.md @@ -0,0 +1,14 @@ +## Conclusion and decision + +OmaMovie has no product reason to impose a short-video duration limit. A two-hour file +with three cuts and a two-hour project with thousands of clips stress different parts of +the system. Keep the versioned JSON project and simdjson parser for now. Complete export +and recovery, then measure timeline size, media seeking, preview, memory and export on +declared long-form workloads. Add proxies, preview renders, indexes or a different project +store only when a measured bottleneck justifies their cost. + +The first long-form promise should be **a recoverable two-hour edit on the reference Intel +machine**, with the exact source codecs and scene complexity stated. It is not a claim that +all long or professional productions work. The gate below is proposed and has not run. + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing-foundations.md b/Docs/Research/long-form-editing-foundations.md new file mode 100644 index 0000000..525d526 --- /dev/null +++ b/Docs/Research/long-form-editing-foundations.md @@ -0,0 +1,23 @@ +## Question, foundations and hypotheses + +Question: which changes let OmaMovie edit and deliver longer material without losing work or +making common actions unresponsive? Baseline: current JSON/`simdjson` project, in-memory +timeline, Qt Quick shell, software-decoded viewer and no export. Failure costs include lost +edits and a final video whose image or sound differs from the preview. + +The relevant foundation is a *quality scenario*: specify the workload and stimulus, then +measure the response rather than call an implementation “scalable” in isolation. The +[SEI scenario method](https://www.sei.cmu.edu/documents/704/2003_005_001_14213.pdf) +(Appendix A, pp. 43–44; 2003 technical report, accessed 2026-10-04) describes stimulus, +environment, response and response measure. Here the independent dimensions are source +duration, clip/track count, resolution/codec/GOP, effects, simultaneous streams, and output +duration. A parser benchmark measures only one dimension. + +| Hypothesis | Mechanism and current evidence | What would change the decision | +|---|---|---| +| H1: simdjson is sufficient for the native project | `libs/project/src/document.cpp` reads a bounded 64 MiB JSON file into memory and parses it with simdjson DOM; the JSON contains references and edits, not video frames. ADR-0007 reports exact round trips but no large-project timing. | Real projects near the cap or measured load/save memory/latency dominate the workflow after simpler representation fixes. | +| H2: clip count will hurt the UI before duration alone | `Session::clips()` and `audioTracks()` build fresh `QVariantList`s of every clip; `Main.qml` uses several `Repeater`s over them. An edit copies the timeline snapshot and emits whole-sequence change signals. This is a source-level risk, not a benchmark. | Large-clip fixtures show stable UI time and memory, or profiling identifies a different dominant cost. | +| H3: random access and effects need distinct remedies | FFmpeg seeks to a keyframe and decoding reaches the requested frame. Kdenlive documents proxies for source decoding and preview renders for effect-heavy sections. OmaMovie's viewer currently uses software decode; its `FrameSource` has bounded decoder/history caches. | Matched footage shows proxy generation cost exceeds seek benefit, or effects are cheap enough without a preview cache. | +| H4: completion/recovery outweigh parser speed for long work | Atomic manual save exists, but autosave, relink UI and export remain open in M7. A long export has more opportunities for interruption and A/V drift. | Complete long-form workflow and failure-injection evidence show these paths already reliable. | + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing-gate.md b/Docs/Research/long-form-editing-gate.md new file mode 100644 index 0000000..e9052ea --- /dev/null +++ b/Docs/Research/long-form-editing-gate.md @@ -0,0 +1,36 @@ +## Proposed gate, before optimizations + +Use a reproducible generated set plus real Omarchy/phone footage. Declare codec, GOP, +resolution, storage, driver, FFmpeg/Qt builds and project edit revision. Compare: (A) one +two-hour source with a few cuts, (B) two hours assembled from 5,000 short clips across +video/audio tracks, (C) a two-hour 4K long-GOP source with repeated random seeks, and +(D) a 10-minute section with costly effects. The 10-minute fixture is the control. +The 5,000-clip fixture is **synthetic stress**, not a claim about typical users. + +1. Record cold/warm open, save and reopen time; peak RAM; project bytes; parser, DTO, + validation, media reimport and UI-model phases separately. Require an exact project + round trip and explicit failure when the format cap is exceeded. No parser/store change + follows merely from total open time. +2. On the reference Intel machine, record p50/p95/p99 and maximum for split, trim, + undo, timeline pan/zoom, selecting a clip, play start and random seek; track UI-thread + stalls, decoder restarts, dropped frames, CPU/GPU/RAM and cache disk use. **Proposed + interaction target:** p95 under 100 ms and no single routine edit stall above 250 ms + in the 5,000-clip scenario. Revisit a threshold only as an explicit product decision, + not after seeing a favorable run. Profile the worst path before adding an index. +3. Compare identical source/output settings for current viewer, proxy and/or preview + render as each becomes available. Include generation time and disk budget. Accept a + cache only if it improves the affected p95/p99 or drops without changing result, + and deletion/failure of cached data leaves the original project usable. +4. Once export exists, run the full two-hour timeline with sound, effects and seeks. + Check the output with an independent decode, sampled content at cuts/transition + boundaries, audio continuity/sync at beginning/middle/end, cancellation and disk-full + recovery. A complete file plus `ffprobe` metadata alone is insufficient. +5. Force a crash or power-loss surrogate around save and autosave on the supported local + filesystem; verify recovery of the last acknowledged save and the documented autosave + state. Test missing/moved media and LUTs, relink, and a failed proxy cache. + +**Stop conditions:** no release claim for a workload that loses acknowledged edits, +silently changes output, uses unbounded memory/disk, or cannot produce a verified movie. +For claims of smooth playback, apply M4's frame-time/A/V criteria to the declared scene. + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing-sources.md b/Docs/Research/long-form-editing-sources.md new file mode 100644 index 0000000..0521562 --- /dev/null +++ b/Docs/Research/long-form-editing-sources.md @@ -0,0 +1,15 @@ +## Research record and limits + +Budget: one local code pass over project, timeline, viewer, waveform and QML paths; +four targeted online search passes covering FFmpeg, Qt, Kdenlive, SQLite and the SEI; +one arithmetic check. Stopped because the next decision is a workload benchmark, not another feature +list. No long-form runtime benchmark, user study, export or failure-injection test ran. +The arithmetic was executed locally with Python on 2026-10-04; its two-hour result is +`7200 × 100 × 2 × 4 / 2^20 = 5.49 MiB`. Online sources were inspected as HTML on +2026-10-04 except the SEI PDF, whose relevant Appendix A passage was available in text. +The cited FFmpeg API is 8.1 documentation; Qt pages are 6.12 unless their URL says +otherwise; Kdenlive pages are its 26.08 manual. Page update dates not shown are unknown. +The main uncertainty is the workload distribution and measured bottleneck on OmaMovie's +reference hardware. + +[Return to long-form-editing.md](long-form-editing.md) diff --git a/Docs/Research/long-form-editing.md b/Docs/Research/long-form-editing.md new file mode 100644 index 0000000..7784e16 --- /dev/null +++ b/Docs/Research/long-form-editing.md @@ -0,0 +1,28 @@ +# Long-form editing: where size actually matters + +> Documentary and source-code analysis, 2026-10-04. This is a research proposal, not +> a performance certification or a change to the native project-format ADR. + +## Conclusion and decision + +[Read this section](long-form-editing-decision.md) + +## Question, foundations and hypotheses + +[Read this section](long-form-editing-foundations.md) + +## Local code observations and capacity check + +[Read this section](long-form-editing-capacity.md) + +## Alternatives and bounded applications + +[Read this section](long-form-editing-alternatives.md) + +## Proposed gate, before optimizations + +[Read this section](long-form-editing-gate.md) + +## Research record and limits + +[Read this section](long-form-editing-sources.md) diff --git a/Docs/Research/movie-maker.md b/Docs/Research/movie-maker.md index 82a29ef..610ff1c 100644 --- a/Docs/Research/movie-maker.md +++ b/Docs/Research/movie-maker.md @@ -1,160 +1,53 @@ -# Microsoft Movie Maker (and successors): UI/UX +# Movie Maker and Clipchamp: bounded UI references -> Research done on 2026-10-02. Sourced facts are linked in the [Sources](#sources) section. -> Items marked **(general observation)** come from broad knowledge of the product without a -> specific source in this research. -> -> Covers Windows Movie Maker (2000–2009), Windows Live Movie Maker (2009–2017) and, as context, -> its successors: the Photos app Video Editor and Clipchamp. +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +A storyboard projection and contextual properties remain prototype candidates. The old +claim that Movie Maker 2012 zoom changes equal-width clips into duration-scaled rectangles +was not verified in a primary record. Do not implement semantic zoom on that historical +claim alone. -For many people Movie Maker was their first video editor. The useful lessons are: +## 2. Current documented baseline -1. **Storyboard and timeline as two views of the same project.** In the last version (2012) - they became one area with **zoom**: zoomed out it is a storyboard; zoomed in it is a timeline. -2. **A task-guided flow** (capture → edit → publish). -3. **AutoMovie**: predefined styles that assemble a movie automatically. -4. Negative lessons: **narrow format support** in the first version and **features removed** - between versions, the same mistake as iMovie '08. +[Microsoft's Clipchamp timeline guide](https://support.microsoft.com/en-us/clipchamp/how-to-work-with-the-timeline-in-clipchamp) +describes dragging library assets onto the timeline, rearranging, trimming, multiple assets +and properties such as audio. It establishes an interaction baseline, not causal evidence +that a similar arrangement will make OmaMovie usable. ---- +Library/viewer/timeline/properties is one way to make selection-dependent tools reachable. +The existing OmaMovie drawer remains a product choice; compare a side-panel alternative +rather than declaring a layout validated through visual resemblance. -## 2. History +## 3. Historical evidence boundary -| Date | Version | Notes | -|---|---|---| -| 2000-09-14 | 1.0 (Windows Me) | Criticized for its small feature set and for exporting only ASF | -| 2001 | 1.1 (Windows XP) | DV-AVI and WMV 8 export | -| 2002-11 | **2.0** | Large feature expansion; 60+ transitions and 37 effects; custom XML effects | -| 2004–2005 | 2.1 (XP SP2), MCE 2005 | DVD burning in Media Center Edition | -| 2007 | **6.0 (Vista)** | DirectX/Direct3D effects, HDV; **removed analog capture** and XML customization. Version 2.6 released for older hardware | -| 2009-08-19 | **Windows Live Movie Maker** | Rewrite: **ribbon** toolbar (Office 2007 style), **AutoMovie**, direct publishing to YouTube/Facebook. **Removed** stabilization and narration | -| 2010-08 | 2011 | Brought back HD video and webcam capture | -| 2012-04 | 2012 | H.264/MP4 as the default export; narration back | -| 2017-01-10 | — | **Discontinued** | -| Windows 10 | Video Editor (Photos app) | Replacement, with text-to-speech and OneDrive | -| 2021-09-08 | **Clipchamp** | Acquired by Microsoft; Windows 11's default editor; brings back the multitrack timeline | +The earlier version-by-version dates, format/export restrictions and removal/restoration +claims came mainly from secondary summaries. They were not needed to choose the next +engineering step and have been removed from active guidance. The attempted Microsoft +Windows Essentials URL was unavailable in this audit (source register). -In 2013 PCMag called it "possibly the simplest (and funnest) way to combine video clips". +Neither discontinuation nor a feature's disappearance establishes that architecture caused +product failure. Treat that causal story as unsupported, not a foundation for modularity. ---- +## 4. Storyboard hypothesis -## 3. Classic interface (versions 2.x–6.0) +An equal-width clip projection can help ordering but destroys the correspondence between +screen distance and timeline time. It needs explicit transition into duration-scaled mode, +a clearly mapped playhead, and gestures whose effects remain predictable. Free overlays +and split audio make a single-row storyboard especially ambiguous. -- **Task pane** on the left, organized in steps (capture video, edit movie, finish movie) - **(general observation; Wikipedia describes the layout in general terms)**. -- **Collections**: organization of imported media. -- Real-time **preview**. -- **Storyboard / Timeline** at the bottom, switchable: - - **Storyboard**: large fixed-size boxes for each clip or image, with smaller boxes between - them for transitions. Used to order the material. - - **Timeline**: each rectangle's length is proportional to its duration; supports trimming, - adjusting transition duration and shows the audio track. - - Separate tracks for video, audio/music and titles. +Compare conventional time zoom, a minimap, and semantic storyboard in M6/M8. Use identical +projects including unequal durations, multiple tracks, gaps and transitions. Accept only if +users can locate the same cut, reorder/undo without changing unintended tracks, and return +to precise time editing without losing context. Measure errors and navigation work; do not +assume fewer modes or fewer pixels is automatically simpler. Test is proposed, not run. -### What worked +## 5. Application -- A storyboard is great for the first assembly (scene order) and is less intimidating. -- A transition as a visible object **between** two clips, with its own box, makes the concept obvious. -- The step-by-step flow taught the editing process. - -### What did not work - -- Switching modes is a context switch: users must know which mode they are in to understand what they can do. -- The track set was fixed and limited. - ---- - -## 4. Windows Live Movie Maker (2009–2012) - -- A **ribbon** instead of menus, with tabs per category (Home, Animations, Visual Effects, - Project, View) **(general observation for the tab names)**. -- **A hybrid storyboard/timeline area with a zoom slider** in the bottom-right corner. With the - slider all the way left, each clip is a same-size rectangle (storyboard). Zooming in, the - rectangles start reflecting duration (timeline). -- **AutoMovie**: pick a style and the app builds the movie with title, credits, transitions and music. -- **Direct publishing** to platforms (YouTube, Facebook). -- Simplified editing: one main video track, no free multitrack **(general observation)**. - -### Implications for OmaMovie - -- **Semantic zoom** is the most reusable idea in this research. A single timeline component - with a zoom axis that goes from "storyboard" (one thumbnail per clip, uniform size, focus on - order) to "timeline" (proportional to time, focus on cuts). No separate mode and no context switch. - - Technical requirement: the TimelineView needs a layout that is not linearly scaled at the - zoomed-out extreme. The timeline model does not change; only the visual projection does. - - Needs measuring: thumbnails for every clip at minimum zoom require a cache and list virtualization. -- The ribbon is an Office pattern, not a video editor pattern. Do not adopt it; the contextual - inspector plays the same role with less fixed space. -- AutoMovie and templates: same conclusion as iMovie (`imovie.md` §7): produce a normal, editable timeline. - ---- - -## 5. Successors - -### Photos Video Editor (Windows 10) - -Replaced Movie Maker with an even simpler, storyboard-based approach, with text-to-speech and -OneDrive integration. Wikipedia notes that timeline-based editing only returned with Clipchamp, -so Windows went years without a built-in timeline editor. - -### Clipchamp (Windows 11) - -A three-column layout plus a timeline: - -- **Left sidebar with tabs**: Your media, Record & create (webcam, screen, text-to-speech), - Templates, Music & SFX, video/image libraries (stock), Graphics, Text, Transitions, Brand kit. -- **Preview** in the center. -- **Multitrack timeline** at the bottom. -- **Contextual properties panel on the right**: changes with the selected element, with tabs - for color, audio, filters, speed, transitions and text. -- Templates by target format (Instagram, TikTok, etc.) and AI-generated videos. -- Export at several resolutions (4K on the paid plan) and direct upload to social media. -- Reviews describe the interface as "refreshingly simple" and similar to Premiere in arrangement. - -### Implications for OmaMovie - -- Clipchamp arrived at the same layout OmaMovie plans: library on the left, preview in the - center, contextual inspector on the right, timeline at the bottom. That convergence validates - the design in `CLAUDE.md` §11. -- **A library with tabs per content type** (media, text, transitions, audio) is an alternative - to iMovie's "single browser". For OmaMovie, the version without stock content: - Media / Titles / Transitions / Effects. -- **Integrated screen/webcam recording** is a feature with real demand in simple editors. On - Omarchy/Wayland it would go through PipeWire and xdg-desktop-portal (ScreenCast). Not a - priority; record it as a future idea. -- Technical contrast: Clipchamp is built on web technology **(general observation)**. OmaMovie, - native and GPU-first, should compete on performance and on working offline without an account. - ---- - -## 6. Negative lessons - -| Mistake | Version | Lesson for OmaMovie | -|---|---|---| -| Exported only ASF | 1.0 | Broad format support is part of usability. FFmpeg solves it; do not restrict artificially | -| Removed analog capture | 6.0 | A platform change does not justify losing capability | -| Removed stabilization and narration | Live 2009 | A rewrite that removes features causes rejection (same as iMovie '08) | -| Removed effect customization | 6.0 and Live | Withdrawn extensibility does not come back. Do not promise extensibility (plugins) before it can be maintained, as `CLAUDE.md` already says | -| Discontinued without an equivalent successor | 2017 | Users spent years without a timeline on Windows. An architecture that needs a full rewrite tends to kill the product; hence the "grow without rewriting the core" rule | - -An internal memo from Bill Gates (January 2003), revealed in an antitrust case, complained about -how hard it was to download and install Movie Maker. **Lesson:** the first experience (install, -open, import) is part of the product. For OmaMovie: simple packaging for Arch/Omarchy and a -first run with no configuration. - ---- - -## Sources - -- [Wikipedia: Windows Movie Maker](https://en.wikipedia.org/wiki/Windows_Movie_Maker) -- [InformIT: Using Microsoft Movie Maker 2](https://informit.com/articles/article.aspx?p=370630) -- [USF Tech Ease: What is Windows Movie Maker](https://etc.usf.edu/techease/win/images/what-is-windows-movie-maker/) -- [O'Reilly: Customizing your Timeline view (Windows Movie Maker 2)](https://www.oreilly.com/library/view/microsoft-windows-movie/0321199545/0321199545_ch09lev1sec5.html) -- [XDA: How to use the Clipchamp video editor on Windows 11](https://www.xda-developers.com/how-to-use-clipchamp-video-editor-windows-11/) -- [ITPro: Clipchamp to be installed on Windows 11 by default](https://itpro.com/operating-systems/microsoft-windows/366289/clipchamp-video-editor-to-be-pre-installed-on-windows-11) -- [Help Desk Geek: How to use the Windows 11 video editor (Clipchamp)](https://helpdeskgeek.com/how-to-use-the-windows-11-video-editor-clipchamp/) -- [Windows Report: Clipchamp review](https://windowsreport.com/clipchamp-review/) +Keep storyboard as an M8 evaluation item. Keep broad media support, installation usability +and recoverable projects for their direct product value, independent of unverified history. +Prices, account/plan restrictions and browser performance were not measured and do not +support an OmaMovie performance advantage. diff --git a/Docs/Research/omarchy-adapters.md b/Docs/Research/omarchy-adapters.md new file mode 100644 index 0000000..1e61b3b --- /dev/null +++ b/Docs/Research/omarchy-adapters.md @@ -0,0 +1,32 @@ +## 5. Recordings + +Local `omarchy-capture-screenrecording` selects +`${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}`, passes auto codec selection, +60 fps CFR intent and CPU-encoding fallback. AAC is added only when audio devices are selected. +Therefore recordings may have **no audio**, and encoder intent is not a guarantee about the +file actually produced. Probe timestamps/codecs/color, including dropped frames/VFR inputs. + +The Recordings source must respect the directory override rather than assuming `~/Videos`. +Do not index a still-growing capture as a completed file without retry/stability handling. +Test actual locally generated captures and no-audio files; do not commit private recordings. + +## 6. Notifications, shell and packaging + +Standard D-Bus notifications and `.desktop`/MIME integration are preferred app boundaries. +Shell progress plugins and dynamic menu providers are later optional integrations. Their +old manifest/IPC examples were not revalidated as stable public contracts and are no longer +copypaste guidance. An OmaStore hook on one machine does not establish release installability; +validate the manifest/artifacts separately when publishing is actually in scope. + +The PKGBUILD remains the dependency source of truth. Read-only docs auditing does not +install packages, hooks, plugins, opacity rules or propose upstream changes automatically. + +## 7. Proposed verification + +In M6 test missing scripts, malformed/partial palettes, rapid theme changes, different fonts, +wide/half/narrow windows, custom recording directories, no-audio capture, and actual app_id. +Compare a standard Qt palette/file chooser baseline. Accept integration only if editing +remains usable when the optional platform input fails. These behavioral tests did not run +here; the evidence is installed-source inspection, not execution of the installer. + +[Return to omarchy-integration.md](omarchy-integration.md) diff --git a/Docs/Research/omarchy-integration.md b/Docs/Research/omarchy-integration.md index 569cb65..08d36bc 100644 --- a/Docs/Research/omarchy-integration.md +++ b/Docs/Research/omarchy-integration.md @@ -1,212 +1,53 @@ -# Omarchy integration +# Omarchy integration: installed evidence and adapter boundaries -> Research done on 2026-10-02 by **inspecting the local Omarchy 4.0.4 installation** -> (`/usr/share/omarchy`, `~/.config/omarchy`, `~/.local/state/omarchy`). Paths and formats may -> change between Omarchy versions. Every integration must have a fallback and live in a single -> app module (`CLAUDE.md` §11). +> Reviewed on 2026-10-03 with skeptical-research. This is non-normative research. +> Source metadata and access limits: [source register](sources.md). Decisions and open +> validation gates: [audit](skeptical-review.md). Product descriptions are not user studies. ---- +## 1. Conclusion -## 1. Summary +The installed Omarchy scripts provide useful theme, recording and opacity conventions. +They are version-sensitive integration evidence, not stable cross-version APIs. Keep them +in the app adapter with timeouts/fallbacks. No user/system configuration was modified. -Omarchy 4 offers concrete integration points that are stable enough for OmaMovie to use: +## 2. Provenance -| Point | Mechanism | Use in OmaMovie | -|---|---|---| -| **Theme** | `~/.local/state/omarchy/current/theme/colors.toml` + `omarchy-theme-color` | UI colors, live switching | -| **Window opacity** | Hyprland rules in Lua | **A 100% opaque window** (correct preview color) | -| **Screen recordings** | `gpu-screen-recorder` → `$XDG_VIDEOS_DIR` | A "Recordings" source in the library | -| **Shell** (Quickshell/QML) | Plugins with `manifest.json`, IPC | Export progress widget (optional) | -| **Omarchy menu** | `~/.config/omarchy/extensions/omarchy-menu.jsonc` | Shortcuts: new project, edit last recording | -| **Notifications** | `omarchy-notification-send` / D-Bus | "Export finished" | -| **Hooks** | `~/.config/omarchy/hooks/.d/` | React to theme and font changes | -| **Drivers** | Omarchy's per-vendor installer | Know which hardware path to expect | +On 2026-10-03 `pacman -Q omarchy` reports **4.0.4-1**, whereas +`/usr/share/omarchy/version` contains **4.0.0.alpha**. The mismatch is recorded, not resolved +by assuming a clean upstream release. [Environment and source hashes](evidence/2026-10-03-local.txt) +identify the installed files inspected; no upstream commit identity was available. -Product finding: **Kdenlive is installed by default on Omarchy** (`install/omarchy-base.packages`), -together with OBS, mpv, `gpu-screen-recorder` and `ffmpegthumbnailer`. OmaMovie competes for -that default editor slot. +The base package list contains Kdenlive. That supports an installer-default observation, +not a statement about all existing installations or demand for its replacement. The GPU +installer scripts select packages by detected hardware; installed Vulkan packages alone +do not guarantee every codec/profile works. ---- +## 3. Theme and font -## 2. Omarchy 4 technical context +The local `omarchy-theme-color` documents `--all` resolved key/tab/value output and reads +`~/.local/state/omarchy/current/theme/colors.toml`. Invoke occasionally off the hot path, +parse defensively, and keep semantic UI tokens/fallback palette in one place. -- Arch Linux + Hyprland; **the Hyprland configuration is written in Lua** (`default/hypr/*.lua`). -- **`omarchy-shell`**: a single **Quickshell** (QML) instance that hosts the bar, menus, panels, - notifications and overlays as plugins. **It is the same UI technology as OmaMovie (Qt Quick/QML).** -- More than 440 `omarchy-*` commands in `/usr/share/omarchy/bin`, with metadata (`omarchy:summary`, `omarchy:args`). -- Installed as a package (`omarchy 4.0.4-1`), with its own kernel (`linux-omarchy`). +The local `omarchy-theme-set` removes the current directory and then moves the staged one, +then writes `theme.name`. **This is not an atomic directory replacement**: there is a missing- +directory interval. Watch the parent, debounce, retry/re-register watches and retain the +last good palette during incomplete updates. Theme files must not tint preview imagery. ---- +The Omarchy font is an existing product choice. A shell `base-size` is not established as +an application font contract; use an app default until that mapping is tested. The adapter +must also work when scripts/files are absent in headless tests. -## 3. Theme +## 4. Opacity and display correctness -### Format -Each theme's `colors.toml` defines: -```toml -mode = "dark" -accent = "#89b4fa" -selection = "#45475a" -muted = "#585b70" -background = "#1e1e2e" # + dark_background, darker_background, lighter_background -foreground = "#cdd6f4" # + dark_foreground, light_foreground, bright_foreground -red/yellow/orange/green/cyan/blue/magenta/brown (+ bright_* variants) -``` +Local `default/hypr/windows.lua` tags ordinary windows for opacity `0.985 0.96`; the Resolve +rule removes that tag and sets `1 1`. These support an analogous documented app-specific +rule for the installed Lua configuration, not all Hyprland versions. A stable `omamovie` +Wayland app_id should be checked in the actual Qt window before shipping the rule. -### How a theme is applied (`omarchy-theme-set`) -1. Assembles the theme in `~/.local/state/omarchy/current/next-theme` (official theme + user overlay). -2. Generates configs from `*.tpl` templates (`{{ accent }}`, `{{ accent_rgb }}`, `{{ mix a b 30% }}`...). -3. **Atomic swap**: `mv next-theme → theme`, writes `theme.name`. -4. Sends the palette to the shell over IPC, restarts/retints known apps (`omarchy-theme-set-obsidian`, `-vscode`...). -5. Runs `omarchy-hook theme-set ` (scripts in `~/.config/omarchy/hooks/theme-set.d/`). +Full opacity removes wallpaper blending; it does not ensure color calibration, display +transfer, gamut or HDR correctness. Document the rule without installing it automatically. +Native Qt/Wayland and any compositor-specific syntax need versioned integration tests. -### Color resolver -`omarchy-theme-color --all` prints `keyvalue` for **every resolved color** (aliases, -legacy names, derived shades, light/dark mode detection). It is the same resolver the templates use. +## 5. Recordings -### Recommendation for OmaMovie -- **Read the palette with `omarchy-theme-color --all`**: no TOML parser dependency and the same - resolution as Omarchy. Fallback: read `colors.toml` directly; final fallback: a built-in - palette (the app must work outside Omarchy and in tests). -- **Live switching**: watch `~/.local/state/omarchy/current/` (the `theme` directory is - **replaced** with `mv`, so watch the parent; `theme.name` changes on every switch) with - `QFileSystemWatcher`, debounced. This avoids installing hooks in the user's directory. -- Map the palette to semantic UI tokens (panel background, selection, accent, secondary text) in - a single place (a `ThemeProvider` exposed to QML). -- **Never theme color-critical areas**: preview, scopes, color picker and thumbnails show the - real image. The theme only affects the surrounding interface. -- Fonts: `omarchy-font-current` and the `font-set.d` hook. - ---- - -## 4. Window opacity (critical for color) - -Omarchy applies translucency to **every** window: -```lua -o.window(".*", { tag = "+default-opacity" }) -o.window({ tag = "default-opacity" }, { opacity = "0.985 0.96" }) -``` -Omarchy itself makes an exception for DaVinci Resolve (`default/hypr/apps/davinci-resolve.lua`): -> "Kept fully opaque: the default translucency distorts colour-critical grading work." - -**OmaMovie needs the same exception.** A 96% opaque window blends the wallpaper into the preview -and invalidates any color judgment. - -- The app sets a **stable Wayland app_id**: `omamovie` (through `QGuiApplication::setDesktopFileName("omamovie")`). -- Required rule: - ```lua - o.window("omamovie", { tag = "-default-opacity", opacity = "1 1" }) - ``` -- Where to put it: short term, document it for users (Hyprland config in `~/.config/hypr`); - medium term, **propose upstream** a `default/hypr/apps/omamovie.lua`, as exists for Resolve. -- A Wayland client does not control the opacity applied by the compositor. - ---- - -## 5. Screen recordings - -`omarchy-capture-screenrecording` (default shortcut **ALT+PRINT**) uses `gpu-screen-recorder`: -``` -gpu-screen-recorder ... -k auto -f 60 -fm cfr -fallback-cpu-encoding yes -o -a