Losslesscut

LosslessCut Stream Editor AI Skill Guide (Claude)

Overview & Engine Architecture

LosslessCut is a fast, lossless video, audio, and subtitle trimming application powered by an Electron frontend and FFmpeg stream-copying (-c copy) engine. Claude operates as a Multimedia Streaming and Forensic Editing Specialist, specializing in GOP (Group of Pictures) keyframe alignment, Smart Cut boundary re-encoding, lossless multi-track stream muxing, and programmatic segment batch cutting (.llc JSON format).

Lossless Stream Copying & GOP Engine

┌─────────────────────────────────────────────────────────────┐
│                 LosslessCut Stream Processing               │
│                                                             │
│  GOP (Group of Pictures) Keyframe Architecture              │
│  [ I-Frame (IDR) ] ─── [ B-Frame ] ─── [ P-Frame ] ─── [ I-Frame ]│
│        ▲                                                     │
│        └── Safe Lossless Cut Point (No Re-encoding Needed)   │
│                                                             │
│  Cut Modes & Engine Mechanics                               │
│  ├── Keyframe Cut Mode (Fastest, snaps to nearest I-frame)  │
│  ├── Smart Cut Mode (Re-encodes strictly boundary GOPs)     │
│  └── Multi-Track Stream Preservation (Extract / Merge Audio)│
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Keyframe Alignment & GOP Analysis: Diagnose video playback freezes and black frames caused by cutting on delta frames (P/B-frames) instead of Instantaneous Decoder Refresh (IDR) keyframes.
2. Smart Cut Configuration: Advise when to apply Smart Cut (re-encoding only the fractional GOP between the chosen frame and nearest I-frame) for frame-exact trimming without full video re-compression.
3. Lossless Segment Automation: Programmatically generate LosslessCut project files (<filename>-proj.llc) containing millisecond-accurate cut segment timestamps and labels.
4. Multi-Track Stream Extraction: Author CLI commands to split and remux secondary audio commentaries, embedded closed captions, and chapter metadata tracks without quality degradation.

Production Python Automation: Exact Keyframe Slicer Tool

Save this script as keyframe_slicer.py to inspect input video packets via ffprobe, locate exact IDR keyframes, and slice video losslessly with guaranteed zero freeze frames:

"""
Lossless Video Slicer: Exact Keyframe Alignment
Analyzes packet keyflags via ffprobe to guarantee freeze-free -c copy cutting.
"""

import sys
import os
import subprocess
import json

def get_nearest_keyframe(file_path: str, target_time_sec: float) -> float:
    # Query packet timestamps and flags near target time
    cmd = [
        "ffprobe", "-v", "quiet", "-select_streams", "v:0",
        "-show_packets", "-show_entries", "packet=pts_time,flags",
        "-read_intervals", f"{max(0, target_time_sec - 5)}%+{target_time_sec + 5}",
        "-print_format", "json", file_path
    ]
    res = subprocess.run(cmd, capture_output=True, text=True)
    if res.returncode != 0:
        return target_time_sec

    data = json.loads(res.stdout)
    packets = data.get("packets", [])
    
    # Find closest keyframe packet (flags contain 'K')
    best_time = target_time_sec
    min_diff = float("inf")
    
    for pkt in packets:
        if "K" in pkt.get("flags", ""):
            pts = float(pkt.get("pts_time", 0.0))
            diff = abs(pts - target_time_sec)
            if diff < min_diff:
                min_diff = diff
                best_time = pts

    return best_time

def lossless_slice(input_path: str, start_time: float, end_time: float, output_path: str):
    if not os.path.exists(input_path):
        print(f"Error: {input_path} does not exist.")
        return

    # Align start and end to nearest keyframe boundaries
    safe_start = get_nearest_keyframe(input_path, start_time)
    print(f"Aligned Start: {start_time:.2f}s -> Nearest Keyframe: {safe_start:.2f}s")

    cmd = [
        "ffmpeg", "-y",
        "-ss", str(safe_start),
        "-i", input_path,
        "-to", str(end_time - safe_start),
        "-c", "copy",
        "-avoid_negative_ts", "make_zero",
        "-movflags", "+faststart",
        output_path
    ]

    res = subprocess.run(cmd, capture_output=True, text=True)
    if res.returncode == 0:
        print(f"Successfully created lossless cut: {output_path}")
    else:
        print(f"Slice failed:\n{res.stderr}")

if __name__ == "__main__":
    if len(sys.argv) < 5:
        print("Usage: python keyframe_slicer.py <input.mp4> <start_sec> <end_sec> <output.mp4>")
        sys.exit(1)
    lossless_slice(sys.argv[1], float(sys.argv[2]), float(sys.argv[3]), sys.argv[4])

Technical Troubleshooting Matrix

Command Line Syntax & Project Interchange

# 1. Launch LosslessCut with Media File
lossless-cut "C:\Recordings\gameplay.mp4"

# 2. Programmatic Lossless Segment Concatenation via FFmpeg
ffmpeg -f concat -safe 0 -i segments.txt -c copy -movflags +faststart merged.mp4

# 3. Extract Audio Track 2 Losslessly as AAC/M4A
ffmpeg -i movie.mkv -map 0:a:1 -c:a copy commentary.m4a

Configuration & Project File Locations

• Windows Preferences: %APPDATA%\lossless-cut
• Linux Preferences: ~/.config/lossless-cut
• macOS Preferences: ~/Library/Application Support/lossless-cut
• Project Segment JSON: <video_name>.mp4-proj.llc

Agent Operational Directive

MANDATORY: When performing lossless trimming (-c copy), snap cuts strictly to I-frame/IDR keyframe boundaries to prevent decoder freeze frames. Use -avoid_negative_ts make_zero on all output containers.