# SmartCut64: explicit rewrite and implementation plan

Status: engineering handover, not an implementation
Prepared: 2026-08-01
Working name: SmartCut64; perform a name/trademark search before release
Initial target: Windows 10/11 x64
Current FFmpeg baseline: FFmpeg 9.0 (`n9.0`, commit
`d32b387f2b0a484599d4587d651891f0c63c4238`)

## 1. Mission

Create a new clean-room, native 64-bit desktop editor for fast lossless cutting and frame-accurate smart rendering. Preserve source packets for every complete, independently reusable GOP and re-encode only boundary GOPs that cannot safely survive an edit. 

Because VideoReDo is a dead project following the passing of its original developer, a core objective of this project is to serve as its successor. **The GUI must directly and wholly replicate the VideoReDo user experience and layout.** The new native UI must mirror the visual layout, shortcut semantics, and core workflows of VideoReDo TVSuite to provide a seamless transition for legacy users. Copy any code as necessary from the VideoReDo TVSuite program.

Colour and HDR metadata are part of a frame's identity. They must travel through demux, decode, edit planning, boundary encode, mux, and validation without being silently dropped. The first advanced target is HEVC Main 10 in Matroska with HDR10, HDR10+, and single-layer Dolby Vision Profile 8.1.

## 2. Version 1.0 definition of success

Version 1.0 is complete only when all of these statements are true:

1. The GUI, command-line program, and media worker are native 64-bit processes.
2. The program opens, probes, indexes, seeks, frame-steps, previews, edits, and exports MPEG-2, H.264/AVC, and H.265/HEVC video.
3. MKV is a production-quality input and output container. MP4/MOV and MPEG-TS are added only after the MKV pipeline passes all tests.
4. Arbitrary video cuts are frame accurate.
5. Complete safe GOPs are packet-copied; no copied frame references a removed frame or an access unit before a discontinuity.
6. Replacement GOPs are independently decodable and transition cleanly into the next copied random-access unit.
7. Output PTS and DTS are valid, monotonic where required, and synchronized with audio, subtitles, chapters, and attachments.
8. HEVC Main 10 replacement frames remain 10-bit and preserve the source pixel format, range, primaries, transfer, matrix, chroma location, sample aspect ratio, mastering-display metadata, and content-light metadata.
9. HDR10+ output has the intended SMPTE ST 2094-40/ITU-T T.35 payload on every corresponding copied and replacement frame.
10. Dolby Vision Profile 8.1 output has one correctly aligned RPU for every output frame, including replacement frames, plus a correct Matroska Dolby Vision configuration record.
11. Every export undergoes an automatic structural probe, strict full decode, timestamp audit, and HDR/Dolby metadata audit before success is reported.
12. A file that fails validation is marked **FAILED VALIDATION** and is never presented as a successful deliverable.
13. **The GUI accurately replicates the layout, user workflows, and core interaction paradigms of the final VideoReDo release, providing immediate familiarity to legacy users.**

## 3. Product scope

### 3.1 Version 1.0 features

*   Windows x64 GUI that replicates the VideoReDo TVSuite interface, plus a feature-complete command-line interface.
*   One or more source clips arranged as kept segments without transitions.
*   Mark-in, mark-out, add/remove selection, cut mode, keep/scene mode, timecode entry, frame stepping, previous/next keyframe, thumbnails, undo/redo, autosave, and configurable keyboard shortcuts matching legacy workflows.
*   Output modes: keyframe-only lossless cut, smart render, and full transcode.
*   Smart rendering for MPEG-2, H.264, and HEVC.
*   8-bit and 10-bit 4:2:0. Permit 4:2:2/4:4:4 stream copy; enable boundary encoding for them only after explicit encoder tests exist.
*   Audio passthrough for AAC, AC-3, E-AC-3, MP2, MP3, FLAC, Opus, and PCM.
*   Text and bitmap subtitle passthrough/retiming where the output container allows.
*   Track selection and preservation of language, default, forced, hearing/visual impaired flags, titles, chapters, attachments, and Matroska tags.
*   A render-plan preview showing copied and encoded ranges before export.
*   A final report listing copied/encoded frame counts, metadata coverage, decode result, warnings, dependency versions, and output hash.

### 3.2 Dolby Vision support claims must be profile-specific

*   **Profile 8.1 single-layer:** full Version 1.0 target, including RPU on replacement frames and Matroska configuration signalling.
*   **Profile 8.4 single-layer:** add only after it passes the complete Profile 8.1 test suite with its own samples.
*   **Profile 5:** begin with safe-GOP copy-only output. Frame-accurate re-encoding requires a separate feasibility gate for the non-HDR10-compatible base layer.
*   **Profile 7 MEL/FEL:** safe-GOP copy-only editing may preserve complete original dual-layer access units. Re-encoding cannot recreate the enhancement-layer residual. An explicit conversion to Profile 8.1 may be offered later, with a prominent warning that MEL/FEL information is discarded.

Do not market a generic “Dolby Vision supported” label. Display the detected profile and the exact supported operation in the UI and output report.

### 3.3 Deliberately out of scope for Version 1.0

*   Generating a new Dolby Vision grade or artistic trims from SDR/HDR10.
*   Claiming Dolby certification or using Dolby branding as a product endorsement.
*   DRM-protected media.
*   Effects, colour correction, compositing, transitions, multicamera editing, optical flow, disc authoring, broadcast capture, or commercial detection.
*   Reproducing purely obsolete legacy TVSuite features (e.g., DVD burning), though all primary editing and navigation UI must be replicated.

## 4. Clean-room and licensing rules

These are project constraints, not legal advice. Obtain appropriate advice before commercial distribution.

1.  **Treat `G:\Documents\VideoReDoMkvPatchLab` and installed VideoReDo files as the strict reference standard for GUI replication and behavioral cloning. The UX must match.**
2.  Archive exact dependency source revisions, local patches, build flags, licences, and corresponding source packages alongside each binary release.

## 5. Fixed technology decisions

Create an Architecture Decision Record before changing any item in this list.

*   Language: C++20.
*   Application build: CMake presets and Ninja; MSVC x64 for application code.
*   GUI: Qt 6, dynamically linked. Select either Qt Quick or Widgets in ADR-002 and use it consistently to replicate the legacy interface.
*   Media: FFmpeg 9.0 64-bit shared libraries pinned to an exact source hash.
*   HEVC encoder: pinned libx265 software encoder for deterministic boundary work.
*   AVC encoder: pinned libx264, subject to GPL packaging.
*   MPEG-2 encoder: FFmpeg's native MPEG-2 encoder.
*   Dolby metadata: FFmpeg frame side data plus pinned `libdovi`; keep `dovi_tool` as an independent command-line verifier even if libdovi is linked.
*   HDR preview: libplacebo/Vulkan or another maintained HDR-aware renderer behind an `IPreviewRenderer` interface.
*   Tests: Catch2 or GoogleTest; select one in ADR-003 and pin it.
*   Dependencies: vcpkg manifest where suitable plus scripted, reproducible builds for FFmpeg/x264/x265/libdovi.
*   Control IPC: versioned, length-prefixed JSON over Windows named pipes.
*   Preview IPC: shared memory buffers with sequence number, pixel format, colour metadata, dimensions, stride, and lifetime acknowledgement.
*   Logs: JSON Lines plus a concise human-readable log.
*   Project/configuration files: versioned JSON validated against checked-in schemas and written atomically through temporary-file plus rename.

At each release checkpoint, check whether a newer stable FFmpeg supersedes 9.0.
Change the pin only after running the entire media suite. “Latest” always means
an exact, reproducible stable release, never an arbitrary nightly DLL.

## 6. Process and component architecture

Use three executables and several libraries:

```text
smartcut.exe                 Qt GUI; no direct FFmpeg types
    |
    | named-pipe control + shared-memory preview
    v
smartcut-worker.exe          FFmpeg owner; probe/index/decode/render/mux/verify

smartcut-cli.exe             headless client using the same worker protocol


## 7. Repository structure

Create a new repository at `G:\Documents\SmartCut64` with this initial layout:

```text
SmartCut64/
  CMakeLists.txt
  CMakePresets.json
  LICENSE
  README.md
  THIRD_PARTY.md
  SECURITY.md
  .clang-format
  .clang-tidy
  cmake/
  dependencies/
    manifests/
    patches/
    scripts/
    sources.lock.json
  schemas/
    project-v1.schema.json
    render-plan-v1.schema.json
    worker-protocol-v1.schema.json
    validation-report-v1.schema.json
  src/
    app/
    cli/
    worker/
    core/
    ipc/
    media_ffmpeg/
    smart_render/
    hdr/
    matroska/
    preview/
    validation/
  tests/
    unit/
    integration/
    fixtures/
    fixture_generators/
    private_manifest.example.json
  tools/
  docs/
    ARCHITECTURE.md
    FORMAT_SUPPORT.md
    SMART_RENDER_ALGORITHM.md
    HDR_METADATA.md
    TEST_MATRIX.md
    BUILDING.md
    RELEASE.md
    STATUS.md
    adr/
```

`docs/STATUS.md` is the resumable handover state. After every work session update:

- current milestone and task;
- completed commits and tests;
- exact commands run and results;
- unresolved defects and next action;
- dependency hashes;
- whether any output is safe for user testing.

## 8. Core data model

Do all timeline arithmetic as integers with an explicit rational timebase. Never
use floating-point seconds as an identity or edit boundary.

### 8.1 Source identity

`SourceIdentity` contains canonical path, byte length, modification time, first
and last block hashes, optional full hash, container format, stream count, and a
stable source UUID derived from these fields. Refuse to reuse an index when the
identity changes.

### 8.2 Video access-unit index

For every video access unit store at least:

- stream index and sequential packet/access-unit number;
- file position and packet byte length;
- PTS, DTS, duration, and source timebase;
- decoded display-frame number;
- frame type and key flag;
- codec-specific random-access type: H.264 IDR; HEVC IDR/CRA/BLA plus RASL/RADL;
- parameter-set hashes and whether VPS/SPS/PPS/sequence headers are in-band;
- GOP number, closed/open status, and conservative dependency-safe flags;
- pixel format, dimensions, range, colour fields, SAR, and interlace state;
- hashes/presence for mastering data, CLL, HDR10+, raw Dolby RPU, parsed Dolby
  metadata, A53 captions, and other relevant side data;
- decode error/corruption flags.

Use display frame number as the edit identity. Preserve PTS/DTS separately for
mapping and muxing. Duplicate PTS values must not collapse two frames.

### 8.3 Project and edit model

A project contains immutable source references plus an ordered list of kept
segments. Each segment uses `(source_uuid, video_stream, first_display_frame,
end_display_frame_exclusive)`. Store the user's requested edit separately from
the derived render plan. This allows regenerating a plan after dependency or
encoder upgrades.

All edits are commands with inverse commands for undo/redo. Autosave an append-only
journal and periodically compact it into the main project JSON.

### 8.4 Render plan

The planner outputs serializable operations such as:

```text
CopyVideoPackets(source, first_au, last_au, output_pts_base)
EncodeVideoBoundary(source, decode_start_au, first_output_frame,
                    last_output_frame, join_au, metadata_policy, encoder_profile)
CopyAudioPackets(source, first_packet, last_packet, output_pts_base)
RetimeSubtitleEvents(source, range, output_pts_base)
WriteTrackMetadata(track_map)
FinalizeContainer
ValidateOutput(validation_profile)
```

Every operation records the reason it exists. The GUI must be able to explain:
“frames 1000–1047 are re-encoded because frame 1000 is not a random-access unit.”

### 8.5 HDR metadata model

Create project-owned immutable types:

```text
ColorDescription(range, primaries, transfer, matrix, chroma_location)
Hdr10Static(mastering_display, max_cll, max_fall)
Hdr10Plus(raw_itu_t_t35, parsed_fields, payload_hash)
DoviConfig(version, profile, level, rpu_present, el_present,
           bl_compatibility_id)
DoviFrame(raw_rpu, parsed_metadata, rpu_hash, scene_refresh)
FrameMetadata(frame_id, color, hdr10_static, hdr10_plus, dovi, captions)
```

Keep raw payloads as well as parsed forms. Raw data enables exact comparison and
reinjection; parsed data enables validation and necessary edit-boundary changes.

## 9. Smart-render algorithm

Correctness takes priority over minimizing the last few encoded frames.

### 9.1 Random-access classification

Do not trust the container keyframe flag alone. Parse codec headers:

- H.264: identify IDR and recovery-point SEI; treat an ordinary I picture as
  unsafe unless dependency analysis proves otherwise.
- HEVC: distinguish IDR, BLA, CRA, RASL, and RADL. A CRA is safe only when leading
  pictures and references across the edit are handled correctly.
- MPEG-2: use sequence/GOP headers, closed-GOP flag, broken-link flag, and picture
  coding dependencies.

Start conservatively. False “needs re-encode” costs time; false “safe to copy”
creates broken video.

### 9.2 Segment planning

For each kept segment `[IN, OUT)`:

1. Find the first dependency-safe random-access unit at or after `IN`.
2. If `IN` is before that unit, decode from the preceding required random-access
   point for reference priming, but output only frames `IN` through the frame
   immediately before the next safe unit. Encode that head as a new closed GOP
   starting with an IDR.
3. Copy complete safe GOPs between the head and tail repair regions.
4. Find the last complete safe GOP that ends at or before `OUT`.
5. If copied frames near `OUT` would reference removed frames, replace the entire
   affected source GOP, beginning at its random-access unit and ending at the last
   kept frame. Flush the encoder so the new tail has no future dependency.
6. If head and tail repair windows overlap, encode the entire kept segment once.
7. At a discontinuity between source segments, force the next segment's first
   output frame to be independently decodable.

The implementation may later shrink repair windows using a proven reference
graph. It must never start with an optimistic one-frame repair heuristic.

### 9.3 Parameter-set transitions

Replacement and copied GOPs may use different encoder parameter sets. The plan
must:

- preserve resolution, bit depth, chroma, profile, tier/level, SAR, range, and
  colour fields;
- place encoder VPS/SPS/PPS immediately before every replacement HEVC IDR;
- place source VPS/SPS/PPS before the first copied HEVC random-access unit after
  a replacement, even when the original container stored them only as extradata;
- apply equivalent SPS/PPS handling for H.264 and sequence headers for MPEG-2;
- keep Matroska CodecPrivate valid and test in-band parameter-set changes across
  multiple independent decoders/players.

Add a regression test for parameter-set ID reuse with different contents. Do not
assume equal numeric IDs imply equal parameter sets.

### 9.4 Timestamp construction

Construct a fresh output timeline beginning at zero unless the user explicitly
requests source timecode preservation. For each segment:

- retain source frame durations as exact rationals;
- map display PTS to the output base;
- generate valid decode-order DTS for encoded packets from encoder output;
- rescale once at API boundaries using FFmpeg rational helpers;
- assert no illegal backward DTS, negative duration, overflow, or unexplained gap;
- retain a mapping from every output frame to its source frame for metadata and
  validation.

## 10. HDR and Dolby Vision rules

### 10.1 HDR10

For every replacement frame and encoder context:

- retain 10-bit pixel format without an intermediate 8-bit conversion;
- propagate limited/full range, BT.2020 primaries, PQ transfer, BT.2020
  non-constant matrix, chroma location, and SAR;
- attach mastering-display and content-light side data before opening x265;
- configure x265 VUI, `master-display`, `max-cll`, and HDR signalling from the
  canonical metadata model;
- validate both SPS/VUI values and actual SEI NAL units.

### 10.2 HDR10+

Capture the raw registered ITU-T T.35 payload and parsed
`AV_FRAME_DATA_DYNAMIC_HDR_PLUS` in display order before any frame leaves the
decoder. Associate it with `FrameId`, never merely with the most recent packet.

For copied frames, retain the original NAL payload. For replacement frames:

1. attach the corresponding parsed side data if the selected encoder path
   serializes it correctly;
2. independently parse the encoded access unit and confirm the expected payload;
3. if FFmpeg/libx265 does not serialize frame side data, implement a small tested
   HEVC prefix-SEI injector that serializes the stored T.35 payload and inserts it
   before the correct frame's VCL NAL units;
4. compare payload hashes frame by frame after muxing.

Do not accept ffprobe decoder carry-forward as proof. Inspect the actual NAL unit
for every replacement frame.

### 10.3 Dolby Vision Profile 8.1

During decode, preserve both raw `AV_FRAME_DATA_DOVI_RPU_BUFFER` and parsed
`AV_FRAME_DATA_DOVI_METADATA`. Modern FFmpeg's libx265 wrapper can generate an RPU
NAL from parsed frame metadata when Dolby Vision encoding is enabled; test this
instead of assuming it works for the selected x265 build.

For an edit:

1. subset the RPU sequence using output-to-source frame mapping;
2. ensure the first RPU after every discontinuity is self-sufficient. Dolby
   metadata can carry state; use libdovi to inspect/rewrite scene-refresh state
   where necessary;
3. attach the correct parsed metadata to each replacement frame before encode,
   or inject the verified raw/rewritten RPU with libdovi after encoding;
4. require exactly one RPU per output frame for the supported profile;
5. create/propagate `AV_PKT_DATA_DOVI_CONF` before the Matroska header is written;
6. verify output profile, level, `rpu_present_flag`, `el_present_flag`, and base
   layer compatibility ID independently with ffprobe and dovi_tool/libdovi;
7. reject output if frame count and RPU count differ or if an RPU is shifted.

For Profile 8.1, preserve original RPU semantics; do not generate a fresh grade.
Record in the output report that the base-layer pixels at repaired GOPs were
lossily re-encoded even though their original metadata was retained.

### 10.4 Metadata validation warning

Decoded-frame side data may be carried forward by a decoder from an earlier SEI
or RPU. Therefore all coverage tests must include raw access-unit parsing. The
acceptance condition is physical presence and correct alignment, not merely an
ffprobe `side_data_list` entry.

## 11. Audio, subtitle, and ancillary-data policy

Video frame accuracy does not imply sample-accurate compressed-audio splicing.
Implement and disclose the policy explicitly:

- Default: copy complete audio codec frames whose presentation overlaps the kept
  video interval, retime them, and report the resulting leading/trailing audio
  tolerance.
- Use Matroska codec delay/discard padding where supported and verified.
- Never split an AC-3/E-AC-3/AAC compressed frame at an arbitrary byte offset.
- Offer optional boundary audio re-encode only after per-codec tests. Preserve
  E-AC-3 by passthrough unless a properly licensed encoder is deliberately added.
- Detect encoder delay and priming samples for AAC/Opus.
- Trim/retime text subtitle events; split an event that crosses a removed region.
- Copy bitmap subtitle packets conservatively and warn where exact splitting is
  impossible.
- Preserve chapters/tags only when they fall in kept regions, retiming them to the
  new timeline.

## 12. Preview and user-interface requirements

The first usable preview may be SDR tone-mapped, provided the UI labels it
clearly. Native Windows HDR monitor output is a separate acceptance gate.

The main editor screen should contain:

- video preview;
- current source/output timecode and display frame number;
- scrub bar with keyframes, cuts, kept regions, and encoded-repair windows;
- track/HDR summary showing bit depth, colour fields, HDR type, DV profile, and
  whether the current frame has physical HDR10+/RPU data;
- mark-in, mark-out, add/remove selection, cut/keep toggle, previous/next frame,
  previous/next random-access unit, undo/redo, save, and export;
- an export-plan dialog showing expected copied/encoded frame counts and every
  metadata or audio limitation before starting.

The UI never performs media work directly. All long operations are cancellable,
emit progress, and survive worker restart where possible. Keyboard frame stepping
must move by display order rather than adding an assumed frame duration.

## 13. Command-line contract

Implement the CLI before the GUI. Required commands:

```text
smartcut-cli probe INPUT --json REPORT
smartcut-cli index INPUT --output INDEX
smartcut-cli frame INPUT --number N --output PNG --preview sdr
smartcut-cli plan PROJECT --output RENDER_PLAN
smartcut-cli render RENDER_PLAN --output OUTPUT --report REPORT
smartcut-cli verify OUTPUT --profile auto --report REPORT
smartcut-cli metadata INPUT --frames A:B --json REPORT
```

All commands return documented nonzero exit codes for invalid input, unsupported
profile, planning failure, render failure, validation failure, cancellation, and
internal error. JSON schemas are versioned and included in the repository.

## 14. Milestone execution plan

Do not skip a gate. Each milestone ends with a commit, updated `docs/STATUS.md`,
test evidence, and a decision to proceed or revise the architecture.

### M0 — Repository, governance, and reproducible skeleton

Tasks:

1. Create `G:\Documents\SmartCut64` and initialize Git.
2. Add the directory layout from Section 7.
3. Add licence, contribution, security, formatting, warning-as-error, and CI files.
4. Write ADR-001 process separation, ADR-002 UI toolkit/style, ADR-003 test
   framework, ADR-004 dependency/licensing model, and ADR-005 integer time model.
5. Create `sources.lock.json` with empty/pinned placeholders and a script that
   prints all resolved versions and hashes.
6. Build trivial `smartcut-cli`, `smartcut-worker`, and test executables as x64.
7. Add a CI assertion that fails if a produced PE file is not x64.

Gate: a clean checkout configures, builds, and runs unit tests on Windows x64
without relying on VideoReDo or unrecorded machine state.

### M1 — Pin and build the media dependencies

Tasks:

1. Pin FFmpeg 9.0 or the then-current stable release by tag and commit hash.
2. Pin x264, x265, libdovi/dovi_tool, Qt, renderer, and test framework.
3. Create reproducible 64-bit build scripts and archive configure output.
4. Build FFmpeg shared libraries with required decoders, demuxers, parsers,
   Matroska muxer, libx264, libx265, and no nonfree components.
5. Record licence impact of every FFmpeg configure flag in `THIRD_PARTY.md`.
6. Add runtime dependency discovery that rejects an unexpected FFmpeg major or
   mismatched DLL set.
7. Package symbols and generate an SBOM.

Gate: `smartcut-cli --versions` prints exact revisions/configure flags and loads
only bundled x64 dependencies. A redistributable source bundle can recreate them.

### M2 — Critical HDR/Dolby metadata round-trip laboratory

This is the first technical feasibility gate. Do not build the GUI first.

Build `smartcut-cli metadata-lab` to:

1. decode a selected HEVC range entirely in 10-bit;
2. inventory raw NALs and all FFmpeg frame/packet side data;
3. encode every selected frame with libx265;
4. attach HDR10 static, HDR10+, and Dolby metadata deliberately;
5. mux MKV with modern libavformat;
6. parse every output access unit independently;
7. produce a per-frame source/output metadata comparison.

Required private test classes:

- HDR10 Main 10 BT.2020/PQ with mastering and CLL data;
- HDR10+ Main 10 with changing per-frame/scene payloads;
- Dolby Vision Profile 8.1 with RPU on every frame and an HDR10 base layer;
- the user-owned Pillion sample may be listed in a private manifest but never
  copied into the repository.

For each class force at least five frames, including non-keyframes, through the
encoder. Verify physical NAL content, not decoder carry-forward.

Fallback decision tree:

- Missing HDR10 static SEI: fix encoder context/side-data configuration.
- Missing HDR10+ SEI: add a tested T.35 prefix-SEI serializer/injector.
- Missing or changed DV RPU: integrate libdovi raw RPU injection and rewrite the
  first RPU at discontinuities as required.
- Missing MKV DOVI configuration: ensure coded packet side data exists before
  `avformat_write_header`; add a focused modern-muxer test.

Gate: one forced-reencode MKV for each class strictly decodes; every output frame
has correct colour; HDR10+ payload hashes align; DV RPU count equals frame count;
the DOVI configuration record is present; no green/corrupt frames exist. If this
gate cannot pass, document the exact unsupported promise before proceeding.

### M3 — Probe, immutable metadata model, and source index

Tasks:

1. Implement RAII FFmpeg wrappers inside `media_ffmpeg` only.
2. Implement `probe` JSON with full stream, container, colour, HDR, DV profile,
   audio layout, subtitle, attachment, and chapter information.
3. Build the access-unit/frame index from Section 8.
4. Parse random-access NAL types rather than trusting container key flags.
5. Cache the index beside the project or in an application cache using source
   fingerprints and schema versions.
6. Add corruption detection and partial-index recovery.
7. Implement `metadata` reports and source-to-frame mapping.

Gate: indexed frame count/display order matches full decode on fixtures; random
access classifications pass hand-authored open/closed GOP cases; changed sources
invalidate their indexes.

### M4 — Frame-accurate seek, decode, preview, and audio clock

Tasks:

1. Seek to the prior safe decode point, flush the decoder, and decode forward to
   the requested display frame.
2. Add bounded decode and preview queues.
3. Implement CPU decode first; add D3D11VA/D3D12/Vulkan hardware decode only
   behind an interface and only when frame accuracy matches software decode.
4. Produce SDR tone-mapped preview frames with explicit labels.
5. Add audio playback and an audio-master preview clock.
6. Implement frame, second, and keyframe navigation without floating time math.
7. Create thumbnail caching with source/index fingerprints.

Gate: 10,000 randomized seeks across test files return the same decoded frame
hash as linear decode. Cancellation releases handles and memory promptly.

### M5 — Edit model and render planner

Tasks:

1. Implement kept-segment model, command undo/redo, project schema, autosave
   journal, and crash recovery.
2. Implement conservative GOP dependency classification.
3. Implement head/tail repair-window algorithm from Section 9.
4. Merge overlapping repair windows.
5. Plan video, audio, subtitle, chapter, and attachment operations.
6. Serialize plans with source fingerprints and dependency versions.
7. Add a text/JSON plan explainer.

Gate: pure unit tests cover cuts at every frame position in synthetic closed GOP,
open GOP, B-frame, CRA/RASL, multi-segment, and overlapping-window cases. Planner
never marks an unsafe fixture frame for copy.

### M6 — Keyframe-safe copy-only MKV editor

Tasks:

1. Execute `CopyVideoPackets` and track-copy operations with fresh timestamps.
2. Preserve codec private data, in-band parameter sets, HDR SEI/RPU NALs, DOVI
   configuration, language/flags, chapters, attachments, and tags.
3. Implement Matroska finalization/cues and cancellation behaviour.
4. Validate every result automatically.
5. Compare copied payloads byte-for-byte after removing container framing.

Gate: safe-GOP outputs contain byte-identical video/audio packet payloads, pass
strict decode, retain metadata counts/configuration, and play correctly in at
least mpv, VLC, and MPC-BE manual smoke tests.

### M7 — SDR and ordinary Main 10 boundary smart rendering

Tasks:

1. Implement decode/encode execution for head and tail repair windows.
2. Force closed replacement GOPs and insert parameter sets at every transition.
3. Join to copied H.264/HEVC/MPEG-2 random-access units.
4. Preserve bit depth and ordinary SDR colour descriptions.
5. Add configurable boundary quality with a conservative default.
6. Add PSNR/SSIM plus visual diagnostic contact sheets for repaired frames.
7. Test parameter-set changes and multiple cuts.

Gate: arbitrary-frame edits strictly decode, have valid timestamps, show no
stutter/green frames, preserve copied payloads, and transition correctly across
multiple independent decoders.

### M8 — HDR10 smart rendering

Tasks:

1. Carry HDR10 static and colour metadata through every replacement frame.
2. Verify encoder SPS/VUI and physical mastering/CLL SEI.
3. Preserve HDR data through parameter-set transitions.
4. Add an HDR10 validation profile and output-report coverage table.

Gate: every frame remains Main 10 BT.2020/PQ; every replacement random-access
unit contains the required physical HDR signalling; strict decode and tone-mapped
visual checks pass.

### M9 — HDR10+ smart rendering

Tasks:

1. Complete per-frame metadata association and cut-sequence transformation.
2. Serialize/inject the expected T.35 payload on every replacement access unit.
3. Preserve original payloads on copied units.
4. Compare per-frame payload hashes and parsed scene metadata.
5. Test cuts immediately before/after HDR10+ scene changes.

Gate: expected HDR10+ coverage is 100%; no frame obtains metadata only by decoder
carry-forward; hashes and alignment match the output-to-source map.

### M10 — Dolby Vision Profile 8.1 smart rendering

Tasks:

1. Preserve raw and parsed RPU data in display order.
2. Transform RPU sequences at removed frames/discontinuities with libdovi.
3. Generate or inject an RPU for every replacement frame.
4. Create the output DOVI configuration record before the Matroska header.
5. Add profile/level/compatibility checks and independent dovi_tool verification.
6. Test cuts at RPU scene boundaries and ordinary frames.
7. Confirm HDR10 fallback is valid when DV processing is disabled by a player.

Gate: RPU count equals video frame count; no RPU shift; replacement frames have
physical RPU NALs; output advertises Profile 8.1 correctly; HDR10 base-layer
validation passes; compatible players detect DV. Do not advance the public DV
claim without this gate.

### M11 — Complete audio, subtitle, and multi-track behaviour

Tasks:

1. Implement the policies in Section 11 for every in-scope codec.
2. Preserve multi-audio/subtitle ordering, names, language, and flags.
3. Add optional boundary audio re-encode only for explicitly supported encoders.
4. Test VFR, offset tracks, negative starting timestamps, encoder delay, missing
   durations, and subtitle events crossing cuts.
5. Add drift measurement at the beginning, every 10 minutes, and the end.

Gate: duration/track metadata is correct, no progressive AV drift occurs, and
reported boundary tolerance matches measured decoded audio.

### M12 — Desktop GUI

Tasks:

1. Build the UI from Section 12 on top of the stable CLI/worker protocol.
2. Add project create/open/save/recovery and recent-file handling.
3. Add keyboard-focused editing, timeline, thumbnails, HDR/profile status, plan
   preview, output profiles, progress/cancel, validation result, and log viewer.
4. Add accessibility names, scalable UI, high-DPI, light/dark themes, and keyboard
   operation for all editing functions.
5. Handle worker crash/restart without corrupting project state.

Gate: all core editing/export tests can be driven through UI automation, and the
GUI produces the same serialized plan as the equivalent CLI command.

### M13 — Hardening, performance, packaging, and release candidate

Tasks:

1. Run sanitizers on portable core code and Application Verifier/heap checks on
   Windows worker builds.
2. Fuzz demux/probe/index parsers with small malformed inputs where practical.
3. Add interrupted export, full disk, read-only source, network disconnect,
   corrupt packet, missing DLL, and invalid project tests.
4. Profile UHD memory. Keep queues bounded and document peak memory by workload.
5. Sign binaries, produce installer and portable package, symbols, SBOM, licence
   notices, corresponding source archive, and reproducible-build instructions.
6. Run the complete compatibility matrix and manual player tests.
7. Conduct independent legal/licensing review before distribution.

Gate: zero release-blocking defects; complete validation matrix; clean install
and uninstall; source/licence package matches binaries; release notes state all
unsupported DV profiles and audio limitations plainly.

## 15. Required test matrix

Maintain the matrix in machine-readable form. At minimum cross these dimensions:

- Containers: MKV first; later MP4/MOV and MPEG-TS.
- Video: MPEG-2, H.264, HEVC Main/Main10.
- Resolution: SD interlaced, 720p, 1080i/p, 2160p, 3840x2076 crop, odd legal
  dimensions.
- Rate: CFR and VFR; 23.976, 24, 25, 29.97, 50, 59.94.
- GOP: closed, open, long GOP, no B-frames, many B-frames, H.264 IDR, HEVC IDR,
  CRA with RASL/RADL, parameter-set change.
- Colour: limited/full BT.709, HDR10 BT.2020/PQ, HDR10+, HLG, and DV P8.1;
  include 4:2:0, 4:2:2, and 4:4:4 boundary fixtures where supported.
- Audio: all in-scope codecs, one/multiple tracks, delays, 2.0/5.1/7.1, different
  sample rates, missing duration.
- Subtitles: SRT/ASS, PGS/DVB where available, events crossing cuts.
- Edit: start, middle, end, adjacent cuts, one-frame segment, overlapping repair
  windows, multi-source, cut on/off random-access, cut on HDR scene boundary.

Every integration test records:

- input fingerprints and probe summary;
- requested kept frame ranges;
- rendered plan;
- copied/encoded access-unit counts;
- strict decoder output;
- packet/frame/timestamp counts;
- source-to-output frame mapping;
- colour/HDR/DV physical NAL coverage;
- audio drift/tolerance;
- output hash and dependency revisions.

## 16. Output validation algorithm

Validation is part of rendering, not an optional troubleshooting tool:

1. Reopen the finalized file with a fresh FFmpeg context.
2. Probe all tracks and compare them with the render plan.
3. Strictly decode every audio/video packet with warnings elevated appropriately.
4. Audit packet and frame counts, duration, PTS/DTS, gaps, overlaps, and overflow.
5. Parse every replacement and transition access unit for parameter sets and
   required NAL/SEI/RPU content.
6. Verify colour fields on every decoded video frame.
7. For HDR10+, compare payload hashes per mapped frame.
8. For DV, verify config fields, RPU count, RPU order, scene-refresh validity, and
   parsed per-frame hashes using libdovi/dovi_tool independently of FFmpeg.
9. Verify copied elementary payloads against source hashes.
10. Decode diagnostic boundary thumbnails and run plane-range/green-corruption
    detection; retain contact sheets for failed tests.
11. Emit a signed/versioned validation JSON and concise user report.

## 17. Performance and reliability targets

- No 32-bit components in the application path.
- For UHD Main 10, default total decoded-frame queues must not exceed a documented
  byte budget; begin with 16 frames or 2 GiB, whichever is lower, and tune with
  evidence.
- Cancellation acknowledgement within two seconds when not blocked in an
  uninterruptible operating-system call.
- Opening a file shows preliminary probe information before a full index completes.
- Indexing and rendering never require the whole video or all metadata in RAM.
- Partial outputs use a distinct suffix and are atomically promoted only after
  mux finalization and validation.
- A worker crash leaves the project and source untouched and produces a crash/log
  bundle with exact dependency versions.
- Never overwrite a source file. Reject identical canonical source/output paths.

## 18. Principal risks and required mitigations

1. **Open-GOP/reference mistakes:** start conservatively with full partial-GOP
   repair; add smaller windows only after dependency tests.
2. **Parameter-set collision at copied/encoded transitions:** insert explicit
   headers at both sides and test multiple decoders.
3. **HDR metadata appears present through decoder carry-forward:** validate raw
   physical NAL units per frame.
4. **Dolby metadata is stateful across a cut:** parse and rewrite first RPU after
   discontinuities with libdovi; test scene boundaries.
5. **HDR10+ is not serialized by the chosen libx265 path:** implement and test a
   narrowly scoped T.35 SEI injector.
6. **Profile 7 enhancement layer cannot be regenerated:** restrict to copy-only or
   explicit conversion; never imply preservation.
7. **Compressed-audio cuts are not sample accurate:** report tolerance and use
   tested discard-padding or boundary re-encode policies.
8. **Modern FFmpeg upgrade breaks wrappers:** isolate all FFmpeg types, pin exact
   versions, and require the full suite before upgrading.
9. **Licensing/patent/trademark exposure:** keep complete licence/source records,
   use open-source distribution by default, and obtain review before release.
10. **GUI distracts from media correctness:** do not begin M12 until M2 and core
    render gates pass.

## 19. Operating instructions for the implementing model/agent

1. Work only in `G:\Documents\SmartCut64`. Do not modify the VideoReDo clone or
   installed application.
2. Read this entire document and `docs/STATUS.md` at the beginning of every turn.
3. Work on the earliest incomplete milestone only, unless a recorded dependency
   blocks it.
4. Before editing, inspect existing changes and preserve unrelated user work.
5. Keep commits small and milestone-labelled, for example `M2: preserve raw DV
   RPU in frame metadata`.
6. Every bug fix requires a regression test that fails before the fix.
7. Record exact commands and results; do not write “tests pass” without naming
   the tests.
8. Do not claim HDR10+/DV success from ffprobe frame side data alone.
9. Do not start GUI implementation before the M2 metadata laboratory passes.
10. Do not silently weaken an acceptance gate. Record a proposed scope change and
    obtain the owner's approval.
11. Stop and request direction for a legal/licensing choice, proprietary SDK,
    unsupported DV profile promise, or change that would materially alter scope.
12. At the end of each turn, update `docs/STATUS.md` with the exact next task so a
    different model can resume without reconstructing context.

## 20. Exact first implementation session

The first implementing model should perform only these steps:

1. Confirm `G:\Documents\SmartCut64` does not contain unrelated user work.
2. Create the repository/layout in Section 7 and initialize Git.
3. Copy this plan into `docs/IMPLEMENTATION_PLAN.md` unchanged.
4. Create M0 ADRs, schemas as minimal versioned placeholders, `STATUS.md`, licence,
   third-party register, build files, and formatting configuration.
5. Create x64 stubs for CLI and worker plus one unit test.
6. Add a PE architecture check.
7. Configure/build/test from a clean build directory.
8. Commit M0 and update status with the full commands/output and M1 next task.

Do not download/build FFmpeg, design the GUI, or touch user media in the first
session. Establish the reproducible project skeleton first.

Suggested prompt to hand to the implementing model:

> Implement SmartCut64 by following `SmartCut64-REWRITE-IMPLEMENTATION-PLAN.md`.
> Work only in `G:\Documents\SmartCut64`; treat all VideoReDo files as read-only.
> Begin with Section 20 and milestone M0 only. Read the complete plan before
> acting, keep `docs/STATUS.md` current, use small commits, and do not weaken any
> HDR/Dolby validation gate. When M0 is fully tested and committed, report the
> exact artifacts, commands, test results, blockers, and the next M1 action.

## 21. Final release checklist

- All binaries verified x64.
- Exact FFmpeg/x264/x265/libdovi/Qt revisions and build flags recorded.
- Corresponding dependency sources and licence notices published.
- No nonfree FFmpeg build option.
- Full test matrix and private HDR/DV sample manifest executed.
- Physical HDR10+/RPU coverage verified, not inferred.
- MKV DOVI configuration verified independently.
- Strict full decode and timestamp audit pass.
- Manual mpv/VLC/MPC-BE playback passes at every repaired boundary.
- No source overwrite path.
- Installer/portable/uninstall/recovery tests pass.
- Unsupported Dolby profiles and audio tolerances shown in UI and release notes.
- Legal/licensing/trademark review completed for the intended distribution model.
