ExactCut Video Tools

Achieve truly lossless video cuts without losing a single frame!

---

The Problem with "Lossless" Video Editing

Have you ever tried to cut a video "losslessly" using popular tools like mkvmerge or stream-copying with FFmpeg, only to find that your cuts aren't exactly where you placed them? You might notice:

• Lost Frames at the Start: Your video segment begins after your intended start point, skipping valuable frames.
• Inaccurate End Points: While less common, the end point might also shift, slightly altering your desired duration.
• Keyframe Limitations: Traditional "lossless" methods are forced to cut only at keyframes (I-frames). If your desired cut point falls between keyframes, the tool must jump to the next available keyframe to avoid corrupting the video stream. This is why you lose frames!
• Complex Proxy Workflows: If you edit with proxy videos for performance, manually aligning cuts for your high-resolution source can be a nightmare.
• Open GOP Codec Challenges: Modern codecs like x265 (HEVC) use "Open GOP" structures, which can lead to visual corruption at cut-in points if not handled perfectly, often requiring you to cut even further back.

This leads to frustrating workarounds, re-editing, or compromising on precision – a major headache for anyone serious about video editing.

---

The ExactCut Solution: Precision Without Compromise

ExactCut Video Tools offers a groundbreaking solution that bypasses these limitations. By intelligently combining the power of VirtualDub2, Python scripting, and FFmpeg-generated frame logs, this suite of tools allows you to:

• Define Cuts Exactly Where You Want Them: Place your cut points precisely in VirtualDub2, even on proxy videos.
• Automate Keyframe Alignment: Our Python script (vdscript_range_adjuster.py) analyzes detailed frame data from FFmpeg to automatically adjust your cut ranges to "legal frame boundaries" (I-frames and P-frames).
• Ensure No Frames Are Lost: The script meticulously ensures that your output segments retain every single desired frame, providing truly lossless cuts at both the start and end of each segment.
• Streamlined Proxy Workflow: Cut effortlessly on low-resolution proxies, and the script handles the precise alignment for your high-resolution source footage automatically.
• Handle Complex Codecs: Specifically designed to manage issues with "Open GOP" codecs (like x265) by offering intelligent adjustment options that prevent corruption at cut points.

With ExactCut Video Tools, the tedious and error-prone process of manual keyframe alignment is a thing of the past. You gain full control and peace of mind that your video edits are pixel-perfect and truly lossless.

---

Key Features

• Zero Frame Loss: Guarantees no frames are lost at the beginning or end of your cut segments.
• Frame-Accurate Cuts: Precisely aligns cut points to the nearest "legal frame boundaries" (I-frames and specific P-frames) using FFmpeg frame logs.
• Automated Adjustment: Eliminates the need for manual keyframe hunting and adjustment.
• Proxy Editing Ready: Define cuts on your lightweight proxy videos; the script translates and adjusts for your full-resolution source.
• Open GOP Codec Support: Smart adjustments (e.g., opting for the "2nd previous I-frame") to prevent corruption with x265 and similar codecs.
• VirtualDub2 Integration: Designed to work seamlessly with cutlists generated by this powerful editor.
• Flexible Output: Generate adjusted VirtualDub2 scripts or convert to other formats like Cuttermaran project files or MKVToolNix GUI cutlists.
• Batch Processing: Process multiple video cutlists efficiently.

---

Prerequisites

Before you begin, ensure you have the following installed:

• Python: Version 3.13.2 or newer (tested with this version, others may work).
• FFmpeg: A recent build (for remuxing & also generating frame logs).
• VirtualDub2: For creating your initial cutlists.
• HandBrake: For proxy video creation.
• MKVToolNix GUI: For exporting the edited video.

---

How to Use

ExactCut Video Tools streamlines your workflow into 10 steps:

Step 1: Prepare Your Videos for Frame Accuracy Make sure your videos are MP4 for optimal frame accuracy. If they are not, remux them to that format using FFmpeg. If you are not sure about how to use FFmpeg, you can use a tool like LosslessCut (Export options > Output container format:). This step is crucial for consistent frame indexing across the workflow. Hint: If you already have LosslessCut, you also have FFmpeg! ("LosslessCut-win-x64\resources\ffmpeg.exe"). That version is perfectly fine for our needs :)

• Exceptions:
  • For MPEG-1/2 videos, you should use vdscript_to_cpf_v1.1.0.py instead of vdscript_to_mkvtoolnix.py. The vdscript_to_cpf tool is available at: https://github.com/CluelessCoder73/vdscript_to_cpf.
  • For DivX/XviD AVI files, you might prefer using VirtualDub2 itself for the final export if you want to retain the AVI container format for compatibility with older players.
• Important: For codecs which are not supported by the MP4 format, you can try MKV (or the original container), but just be aware that you may lose frames. The number is minuscule, but it goes against the very premise behind the creation of these tools: "Cut as close to the wanted ranges as possible without losing ANY frames!".

Step 2: Organize Source Videos (Optional for vdscript_info.py users)

• NOTE: This step is only necessary if you plan on using vdscript_info.py!
• Put all your source videos into separate folders according to their frame rates (e.g., 23.976, 25, etc.). This helps vdscript_info.py process them correctly.

Step 3: Create Proxy Videos (Optional)

• Create lower-resolution proxy versions of your videos using HandBrake. Use one of the custom presets provided with ExactCut Video Tools.
• Customization Tips:
  • You may want to raise the "Constant Quality" values; the provided presets are set at "RF 16" (high quality). "RF 22" or higher will be good enough for most proxy uses.
  • You may also want to lower the "Resolution Limit" (e.g., from the default "720p HD").
  • Important: All filters are turned off in the presets. If your source video is interlaced, you will need to enable deinterlacing in HandBrake!
  • Crucial: DO NOT save proxy videos to the same folder as your input source files!

Step 4: Prepare the Core Scripts

• Go to the scripts folder, open frame_log_extractor.bat in a text editor and specify the full path to ffmpeg.exe within the script. Save the modified version for future use.
• Now, copy the contents of the scripts folder into your "source videos" folder. Omit vdscript_info.py if not required.

Step 5: Generate Frame Logs

• Run frame_log_extractor.bat.
• Be patient: This process will take a significant amount of time as it processes every video file it finds in the folder.
• Internal FFmpeg Command: The .bat file uses the following FFmpeg command internally to extract the necessary frame data:

  ffmpeg -i "your_video_file.mp4" -vf showinfo -f null - 2>&1 | findstr /i "n:" > "your_video_file.mp4_frame_log.txt"

• Each generated frame log file will have the same name as its corresponding video (including extension), with _frame_log.txt appended (e.g., my_video.mp4_frame_log.txt). These logs contain the essential frame type (I, P, B) and frame number information required for precise adjustments.

Step 6: Edit Your Proxy Videos in VirtualDub2

• Open a proxy video (or original MP4 if you skipped proxy creation) with VirtualDub2. You can use either the 32-bit or 64-bit version; the output vdscript is identical. (For performance, the 64-bit version is generally recommended).
• Efficient Editing Tips:
  • Scan at high speed using SHIFT + LEFT and SHIFT + RIGHT.
  • Go even faster by using ALT + LEFT and PGDN.
  • Use the HOME and END keys to mark your start and end points for each selection you want to delete. NOTE: VirtualDub2 is endpoint exclusive — meaning that the frame you end the selection on is NOT included in the selection!.
• Save Your Cutlist: Once your editing is complete, go to File > Save processing settings... (CTRL + S).
• Crucial: MAKE SURE to check "Include selection and edit list" in the save dialog. Otherwise, your cuts will NOT be saved! VirtualDub2 should remember this setting for future sessions.
• Naming Convention: The vdscript must be saved with the format source_video_filename.extension.vdscript. So, if your source video is called whatever.mp4, your final saved vdscript should be called whatever.mp4.vdscript.

Step 7: Adjust Ranges

• Run vdscript_range_adjuster.py.
• The script will automatically process every vdscript file in the directory (provided it has a corresponding frame log file).
• The outputted files will have _adjusted.vdscript appended (e.g., whatever.mp4_adjusted.vdscript). These adjusted scripts now contain the precise frame ranges aligned to legal frame boundaries.

Step 8: Verify Adjustments (Optional)

• Run vdscript_info.py for a detailed "before & after" comparison of your cut ranges. This tool can also be useful for verifying that the final output will have the correct number of frames.

Step 9: Generate MKVToolNix Cutlists

• Execute the following command in your terminal:

  python vdscript_to_mkvtoolnix.py --merge

• To get non-concatenated parts instead: Omit --merge for individual parts (e.g., python vdscript_to_mkvtoolnix.py). This can be useful for analyzing each individual part to determine if frames have been handled correctly.
• Note: vdscript_to_mkvtoolnix.py only processes files with _adjusted.vdscript appended. It outputs a single file called batch_cutlist.txt containing the cut string(s) ready for MKVToolNix GUI.

Step 10: Export Your Edited Video with MKVToolNix GUI

• Open MKVToolNix GUI.
• Add your original MP4 video file (NOT the proxy!) to the "Source files" section.
• Go to the "Output" tab.
• Under "Splitting", select "By parts based on frame/field numbers".
• Paste the cutlist string from batch_cutlist.txt (without quotes/filename, it's just the string of numbers) into the input field.
• Start multiplexing.
• Important Note on Output Frame Count & Audio:
  • The output video file generated by MKVToolNix GUI may occasionally have a few extra frames compared to the exact number of frames defined by the adjusted input ranges. This is a characteristic of how MKVToolNix handles certain container behaviors (e.g., ensuring a complete GOP) when multiplexing video and audio together.
  • If you require the ABSOLUTE EXACT number of frames for the video stream in your final output, you will need to disable the audio track within MKVToolNix GUI during this step (uncheck the audio track under "Tracks, chapters and tags" section).
  • You would then process the audio separately:
    1. Open the original MP4 video in VirtualDub2.
    2. Load the _adjusted.vdscript.
    3. Choose audio "Full processing mode" and save it as a WAV file.
    4. Compress the WAV file using Audacity or any other audio conversion program to your desired format.
    5. Finally, mux the "video-only" MKV (from MKVToolNix GUI) and your newly processed audio into your desired final container format. This ensures that the video stream is precisely cut while giving you control over the audio.

---

VERIFYING THAT THE SOURCE & PROXY MATCH:

VERY IMPORTANT! - Do NOT get your original videos & proxy videos mixed up! Always ensure your proxy video matches the frame count of its corresponding source video for accurate results.

To verify a match:

1. Open your whatevervideo_frame_log.txt file (e.g., my_video.mp4_frame_log.txt).
2. Go to the second-to-last line (the last line of actual frame data). Somewhere in this line, it will say, e.g., n:58357. This is the index of the last actual frame in your video stream.
3. Now, open your proxy video in VirtualDub2, and hit the [End] key. This will bring you to the last frame of the video.
4. The display at the bottom of VirtualDub2 should say, e.g., Frame 58358. This is the total number of frames in your proxy video.
5. This total frame count in VirtualDub2 SHOULD be +1 compared to that last frame index reported in the frame log (n:58357 vs Frame 58358), because in VirtualDub2, the last displayed frame is always an "empty" frame.
6. DO NOT directly compare the proxy video's frame count with the actual source video file's frame count itself (e.g., using mkvinfo or ffprobe). The frame counts might often match, but NOT ALWAYS! The critical thing (in terms of frame accuracy for this workflow) is that your FFmpeg-generated frame logs and your proxy videos (as displayed in VirtualDub2) match perfectly.

---

Configuration

The vdscript_range_adjuster.py script offers several configurable parameters at the bottom of the file to fine-tune its behavior:

• directory: Specify the working directory (defaults to the script's location).
• i_frame_offset: Control how many I-frames to go back for start points (useful for open GOP codecs like x265).
• merge_ranges_option: Enable/disable merging of overlapping or very close ranges.
• min_gap_between_ranges: Define the minimum frame gap for merging ranges.
• short_cut_mode: Adjusts endpoint behavior (True for shorter segments, False for full GOPs).

---