vsdirty 0.1.0__py3-none-any.whl

vsdirty/admask.py

@@ -0,0 +1,480 @@
+import vapoursynth as vs
+from typing import Optional
+
+core = vs.core
+
+if not (hasattr(vs.core, 'cas') or hasattr(vs.core, 'fmtc') or hasattr(vs.core, 'akarin')):
+    raise ImportError("'cas', 'fmtc' and 'akarin' are mandatory. Make sure the DLLs are present in the plugins folder.")
+
+
+def _get_stdev(avg: float, sq_avg: float) -> float:
+    return abs(sq_avg - avg ** 2) ** 0.5
+
+#fatta dalla IA e anche male, ma fa il suo la cambierò in futuro forse
+def _soft_threshold(clip: vs.VideoNode, thr: float, steepness: float = 20.0) -> vs.VideoNode:
+    """
+    Applies a soft threshold to the clip.
+    Values below thr accept a penalty that decays exponentially based on the distance from thr.
+    formula: x < thr ? x * exp((x - thr) * steepness) : x
+    """
+    from .adutils import scale_binary_value
+    
+    core = vs.core
+    
+    thr_scaled = scale_binary_value(clip, thr, return_int=False)
+    
+    if clip.format.sample_type == vs.INTEGER:
+        max_val = (1 << clip.format.bits_per_sample) - 1
+        diff_expr = f"x {thr_scaled} - {max_val} /"
+    else:
+        diff_expr = f"x {thr_scaled} -"
+
+    return core.akarin.Expr(
+        [clip],
+        f"x {thr_scaled} >= x "
+        f"{diff_expr} {steepness} * exp x * "
+        f"?"
+    )
+
+def auto_thr_high(stddev):
+    if stddev >0.900:
+        stdev_min, stdev_max = 0.800, 1.000
+    else:
+        stdev_min, stdev_max = 0.400, 1.000
+    thr_high_min, thr_high_max = 0.005, 1.000
+    norm = min(max((stddev - stdev_min) / (stdev_max - stdev_min), 0.000), 1.000)
+    return (thr_high_max * ((thr_high_min / thr_high_max) ** norm))
+
+def luma_mask (
+        clip: vs.VideoNode,
+        min_value: float = 17500,
+        sthmax: float = 0.95,
+        sthmin: float = 1.4,
+)-> vs.VideoNode :
+    from .adutils import plane
+    
+    luma = plane(clip, 0)
+    lumamask = core.std.Expr(
+        [luma],
+        "x {0} < x {2} * x {0} - 0.0001 + log {1} * exp x + ?".format(min_value, sthmax, sthmin)
+    )
+    lumamask = lumamask.std.Invert()
+
+    return lumamask
+
+def luma_mask_man (
+        clip: vs.VideoNode,
+        t: float = 0.3,
+        s: float = 5,
+        a: float = 0.3,
+)-> vs.VideoNode :
+    """
+    Custom luma mask that uses a different approach to calculate the mask (Made By Mhanz).
+    This mask is sensitive to the brightness of the image producing a smooth transition between dark and bright areas of th clip based on brightness levels.
+    The mask exalt bright areas and darkens dark areas, inverting them.
+    
+    Curve graph https://www.geogebra.org/calculator/cqnfnqyk
+    
+    :param clip:            Clip to process (only the first plane will be processed).
+    :param s:               
+    :param t:               Threshold that determines what is considered light and what is dark.
+    :param a:               
+    :return:                Luma mask.
+    """
+    from .adutils import plane
+    
+    luma = plane(clip, 0)
+    f=1/3
+
+    maxvalue = (1 << clip.format.bits_per_sample) - 1
+    normx = f"x 2 * {maxvalue} / "
+
+    lumamask = core.std.Expr(
+        [luma],
+        f"x "                  # Mettiamo x sullo stack per la moltiplicazione finale
+        f"{normx} {t} < "            # x < b ?
+        # - Ramo TRUE → f(x):
+        f"{normx} {t} - {normx} {t} - 2 pow {s} * {a} + {f} pow / 1 + "
+        # - Ramo FALSE → h(x):
+        f"{normx} {t} - {normx} {t} - 2 pow {s} * 5 * {a} + {f} pow / 1 + "
+        # - Operatore ternario:
+        f"? "
+        # - moltiplica per x:
+        f"*"
+    )
+
+    lumamask = lumamask.std.Invert()
+
+    return lumamask
+
+def luma_mask_ping(
+        clip: vs.VideoNode,
+        low_amp: float = 0.8,
+        thr: float = 0.196,
+) -> vs.VideoNode:
+    """
+    Custom luma mask that uses a different approach to calculate the mask (Made By PingWer).
+    This mask is sensitive to the brightness of the image, producing a constant dark mask for bright areas, 
+    a constant white mask for very dark areas, and a exponential transition between these extremes based on brightness levels.
+
+    Curve graph https://www.geogebra.org/calculator/fxbrx4s4
+
+    :param clip:            Clip to process (only the first plane will be processed).
+    :param low_amp:         General preamplification value, but more sensitive for values lower than thr.
+    :param thr:             Threshold that determines what is considered bright and what is dark.
+    :return:                Luma mask.
+    """
+
+    core = vs.core
+    import math
+    from .adutils import scale_binary_value, plane
+
+    bit_depth = clip.format.bits_per_sample
+    max_val = (1 << bit_depth) - 1
+
+    thr_scaled = scale_binary_value(clip, value=thr, bit=bit_depth, return_int=False)
+
+    high_amp = (math.exp(low_amp - 1) + low_amp * math.exp(low_amp)) / (math.exp(low_amp) - 1)
+
+    expr = (
+        f"x {max_val} / "
+        f"dup {thr_scaled} < "
+        f"{thr_scaled} 1 + - exp {low_amp} + "
+        f"{high_amp} {high_amp} dup {thr_scaled} 1 - - log {high_amp} * exp {low_amp} + / - "
+        f"? "
+        f"x *"
+    )
+
+    cc = core.akarin.Expr([plane(clip, 0)], expr)
+
+    cc = core.std.Invert(cc)
+
+    return cc
+
+def unbloat_retinex(
+    clip: vs.VideoNode,
+    sigma: list[float] = [25, 80, 250],
+    lower_thr: float = 0.001,
+    upper_thr: float = 0.005,
+    fast: bool = True
+    ) -> vs.VideoNode:
+    """
+    Multi-Scale Retinex (MSR) optimized for edge enhancement and dynamic range compression.
+    
+    Uses Gaussian blur (via vsrgtools.gauss_blur) with optional downscaling optimization
+    for large sigma values. The output is a normalized [0, 1] Float32 grayscale clip
+    suitable for edge detection or as a preprocessing step for masking.
+    
+    :param clip:        Input clip. Must be Grayscale (GRAY format).
+    :param sigma:       List of sigma values for multi-scale blur. Default: [25, 80, 250].
+                        Larger values capture coarser illumination variations.
+    :param lower_thr:   Quantile threshold for black level (0-1). Default: 0.001 (0.1%).
+                        Used to ignore dark outliers during final normalization.
+    :param upper_thr:   Quantile threshold for white level (0-1). Default: 0.001 (0.1%).
+                        Used to ignore bright outliers during final normalization.
+    :param fast:        Enable downscaling optimization for large sigmas. Default: True.
+                        Significantly faster with minimal quality loss.
+    :return:            Processed Float32 Grayscale clip with enhanced local contrast.
+    
+    :raises ValueError: If input clip is not Grayscale.
+    """
+    from vstools import depth
+    from vsrgtools import gauss_blur
+    
+    if clip.format.color_family != vs.GRAY:
+        raise ValueError("unbloat_retinex: Input must be a Grayscale clip.")
+    
+    if clip.format.sample_type != vs.FLOAT:
+        luma = depth(clip, 32)
+    else:
+        luma = clip
+        
+    stats = luma.std.PlaneStats()
+    luma_norm = core.akarin.Expr([luma, stats], "x y.PlaneStatsMin - y.PlaneStatsMax y.PlaneStatsMin - 0.000001 max /")
+
+    sigmas_sorted = sorted(sigma)
+    sigmas_to_blur = sigmas_sorted[:-1] if fast else sigmas_sorted
+        
+    blurs = []
+    w, h = luma_norm.width, luma_norm.height
+    
+    for s in sigmas_to_blur:
+        if fast and s > 6:
+            ds_ratio = max(1, s / 3)
+            ds_w, ds_h = max(1, int(w / ds_ratio)), max(1, int(h / ds_ratio))
+            
+            if ds_ratio > 2:
+                down = luma_norm.resize.Bicubic(ds_w, ds_h)
+                
+                s_down = s / ds_ratio
+                blurred_down = gauss_blur(down, sigma=s_down)
+                
+                blurred = blurred_down.resize.Bicubic(w, h)
+            else:
+                 blurred = gauss_blur(luma_norm, sigma=s)
+        else:
+             blurred = gauss_blur(luma_norm, sigma=s)
+        blurs.append(blurred)
+        
+    inputs = [luma_norm] + blurs
+    
+    def get_char(i):
+        if i == 0: return 'x'
+        if i == 1: return 'y'
+        if i == 2: return 'z'
+        if i == 3: return 'a'
+        return chr(ord('a') + (i - 3))
+
+    terms = []
+    for i in range(1, len(inputs)):
+        c = get_char(i)
+        terms.append(f"{c} 0 <= 1 x {c} / 1 + ?")
+        
+    if fast:
+        terms.append("x 1 +")
+
+    expr_code = " ".join(terms)
+    if len(terms) > 1:
+         expr_code += " " + " ".join(["+"] * (len(terms) - 1))
+         
+    slen = len(sigma)
+    expr_code += f" log {slen} /"
+    
+    msr = core.akarin.Expr(inputs, expr_code)
+    
+    if hasattr(core, 'vszip') and (lower_thr > 0 or upper_thr > 0):
+        msr_stats = core.vszip.PlaneMinMax(msr, lower_thr, upper_thr)
+        min_key, max_key = 'psmMin', 'psmMax'
+    else:
+        msr_stats = msr.std.PlaneStats()
+        min_key, max_key = 'PlaneStatsMin', 'PlaneStatsMax'
+
+    balanced = core.akarin.Expr([msr, msr_stats], f"x y.{min_key} - y.{max_key} y.{min_key} - 0.000001 max /")
+    
+    return balanced
+
+
+def advanced_edgemask(
+    clip: vs.VideoNode,
+    ref: Optional[vs.VideoNode] = None,
+    sigma1: float = 3,
+    retinex_sigma: list[float] = [50, 200, 350],
+    sigma2: float = 1,
+    sharpness: float = 0.8,
+    kirsch_weight: float = 0.5,
+    kirsch_thr: float = 0.35,
+    edge_thr: float = 0.02,
+    **kwargs
+) -> vs.VideoNode:
+    """
+    Advanced edge mask combining Retinex preprocessing with multiple edge detectors.
+    
+    This mask uses BM3D denoising + Multi-Scale Retinex to enhance edges before detection,
+    then combines Sobel, Prewitt, TCanny and Kirsch edge detectors for robust edge detection.
+    
+    :param clip:                Clip to process (YUV or Gray).
+    :param ref:                 Optional reference clip for denoising.
+    :param sigma1:              BM3D sigma for initial denoising. Default: 3.
+    :param retinex_sigma:       Sigma values for Multi-Scale Retinex. Default: [50, 200, 350].
+    :param sigma2:              Nlmeans strength for post-Retinex denoising. Default: 1.
+    :param sharpness:           CAS sharpening amount (0-1). Default: 0.8.
+    :param kirsch_weight:       Weight for Kirsch edges in final blend (0-1). Default: 0.7.
+    :param kirsch_thr:          Kirsch threshold. Default: 0.25.
+    :param edge_thr:            Threshold for edge combination logic (0-1). Default: 0.02.
+    :param kwargs:              Additional arguments for Retinex.
+    :return:                    Edge mask (Gray clip).
+    """
+    from vstools import get_y, depth
+    from vsdenoise import nl_means
+    from vsmasktools import Morpho, Kirsch
+    from .adfunc import mini_BM3D
+    from .adutils import scale_binary_value
+    
+    core = vs.core
+    
+    if clip.format.color_family == vs.RGB:
+        raise ValueError("advanced_edgemask: RGB clips are not supported.")
+    
+    if clip.format.color_family == vs.GRAY:
+        luma = clip
+    else:
+        luma = get_y(clip)
+    
+    luma = depth(luma, 16)
+
+    if ref is not None:
+        if ref.format.color_family == vs.RGB:
+            raise ValueError("advanced_edgemask: RGB reference clips are not supported.")
+        
+        if ref.format.color_family == vs.GRAY:
+            ref_y = ref
+        else:
+            ref_y = get_y(ref)
+            
+        if ref_y.format.bits_per_sample != 16:
+            ref_y = depth(ref_y, 16)
+        clipd = mini_BM3D(luma, sigma=sigma1, ref=ref_y, radius=1, profile="HIGH", planes=0)
+    else:
+        clipd = mini_BM3D(luma, sigma=sigma1, radius=1, profile="HIGH", planes=0)
+    
+    msrcpa = depth(unbloat_retinex(
+        depth(clipd, 32), 
+        sigma=retinex_sigma,
+        fast=True,
+        **kwargs
+    ), 16, dither_type="none")
+    
+    msrcp = nl_means(msrcpa, h=sigma2, a=2)
+    
+    if sharpness > 0:
+        msrcp = core.cas.CAS(msrcp, sharpness=sharpness, opt=0, planes=0)
+        clipd = core.cas.CAS(clipd, sharpness=sharpness, opt=0, planes=0)
+    
+    preSobel = core.akarin.Expr([
+        get_y(msrcp).std.Sobel(),
+        get_y(clipd).std.Sobel(),
+    ], "x y max")
+    
+    prePrewitt = core.akarin.Expr([
+        get_y(msrcp).std.Prewitt(),
+        get_y(clipd).std.Prewitt(),
+    ], "x y max")
+    
+    edges = core.akarin.Expr([preSobel, prePrewitt], "x y +")
+    
+    tcanny = core.akarin.Expr([
+        core.tcanny.TCanny(get_y(msrcp), mode=1, sigma=0),
+        core.tcanny.TCanny(get_y(clipd), mode=1, sigma=0)
+    ], "x y max")
+    
+    kirco = core.akarin.Expr([
+        Kirsch.edgemask(get_y(msrcp), clamp=False, lthr=kirsch_thr),
+        Kirsch.edgemask(get_y(clipd), clamp=False, lthr=kirsch_thr)
+    ], "x y max")
+    
+    edge_thr_scaled = scale_binary_value(edges, edge_thr, return_int=True)
+    mask = core.akarin.Expr(
+        [edges, tcanny, kirco], 
+        f"x y + {edge_thr_scaled} < x y + z {kirsch_weight} * + x y + ?"
+    )
+
+    return mask
+
+
+def hd_flatmask(
+    clip: vs.VideoNode,
+    ref: Optional[vs.VideoNode] = None,
+    sigma1: float = 3,
+    retinex_sigma: list[float] = [50, 200, 350],
+    sigma2: float = 1,
+    sharpness: float = 0.8,
+    edge_thr: float = 0.55,
+    texture_strength: float = 2,
+    edges_strength: float = 0.02,
+    blur: float = 2,
+    expand: int = 3,
+    **kwargs
+) -> vs.VideoNode:
+    """
+    Advanced edge mask combining Retinex preprocessing with multiple edge detectors.
+    
+    This mask uses BM3D denoising + Multi-Scale Retinex to enhance edges before detection,
+    then combines Sobel, Prewitt, TCanny and Kirsch edge detectors for robust edge detection.
+    
+    :param clip:                Clip to process (YUV or Gray).
+    :param ref:                 Optional reference clip for denoising.
+    :param sigma1:              BM3D sigma for initial denoising. Default: 3.
+    :param retinex_sigma:       Sigma values for Multi-Scale Retinex. Default: [50, 200, 350].
+    :param sigma2:              Nlmeans strength for post-Retinex denoising. Default: 1.
+    :param sharpness:           CAS sharpening amount (0-1). Default: 0.8.
+    :param edge_thr:            Threshold for edge combination logic (0-1). This allows to separate edges from texture. Default: 0.55. 
+    :param texture_strength:    Texture strength for mask (0-inf). Values above 1 decrese the strength of the texture in the mask, lower values increase it. The max value is theoretical infinite, but there is no gain after some point. Default: 0.8. 
+    :param edges_strength:      Edges strength for mask (0-1). Basic multiplier for edges strength. Default: 0.03.
+    :param blur:                Blur amount for mask (0-1). Default: 2.
+    :param expand:              Expand amount for mask (0-1). Higher value increases the size of the texture in the mask. Default: 3.
+    :param kwargs:              Additional arguments for Retinex.
+    :return:                    Edge mask (Gray clip) where dark values are texture and edges, bright values are flat areas.
+    """
+
+    from vstools import depth
+    from vsdenoise import nl_means
+    from vsmasktools import Morpho, Kirsch, XxpandMode
+    from .adfunc import mini_BM3D
+    from .adutils import scale_binary_value, plane
+    from vsrgtools import gauss_blur
+    
+    core = vs.core
+    
+    if clip.format.color_family == vs.RGB:
+        raise ValueError("advanced_edgemask: RGB clips are not supported.")
+    
+    if clip.format.color_family == vs.GRAY:
+        luma = clip
+    else:
+        luma = plane(clip, 0)
+    
+    luma = depth(luma, 16)
+
+    if ref is not None:
+        if ref.format.color_family == vs.RGB:
+            raise ValueError("advanced_edgemask: RGB reference clips are not supported.")
+        
+        if ref.format.color_family == vs.GRAY:
+            ref_y = ref
+        else:
+            ref_y = plane(ref, 0)
+            
+        if ref_y.format.bits_per_sample != 16:
+            ref_y = depth(ref_y, 16)
+        clipd = mini_BM3D(luma, sigma=sigma1, ref=ref_y, radius=1, profile="HIGH", planes=0)
+    else:
+        clipd = mini_BM3D(luma, sigma=sigma1, radius=1, profile="HIGH", planes=0)
+
+    msrcpa = depth(unbloat_retinex(
+        depth(clipd, 32), 
+        sigma=retinex_sigma,
+        fast=True,
+        **kwargs
+    ), 16, dither_type="none")
+    
+    msrcp = nl_means(msrcpa, h=sigma2, a=2)
+    
+    if sharpness > 0:
+        msrcp = core.cas.CAS(msrcp, sharpness=sharpness, opt=0, planes=0)
+        clipd = core.cas.CAS(clipd, sharpness=sharpness, opt=0, planes=0)
+    
+    edges = core.akarin.Expr([
+        msrcp.std.Sobel(),
+        clipd.std.Sobel(),
+        msrcp.std.Prewitt(),
+        clipd.std.Prewitt()
+    ], "x y max z a max +")
+
+    if edge_thr > 0:
+        edges = _soft_threshold(edges, edge_thr, 10)
+    
+    tcanny = core.akarin.Expr([
+        core.tcanny.TCanny(msrcp, mode=1, sigma=0),
+        core.tcanny.TCanny(clipd, mode=1, sigma=0)
+    ], "x y max")
+    tcanny = core.std.Minimum(tcanny)
+
+    edgescombo = Morpho.inflate(core.akarin.Expr([edges, tcanny], "x y +"), iterations=2)
+    
+    kirco = core.akarin.Expr([
+        Kirsch.edgemask(msrcp),
+        Kirsch.edgemask(clipd)
+    ], "x y +")
+
+    edges_expanded = Morpho.expand(edgescombo, mode=XxpandMode.ELLIPSE, sw=1, sh=1)
+    kirco_diff = core.akarin.Expr([kirco, edges_expanded], "x y -")
+    kirco_expanded = Morpho.expand(kirco_diff, mode=XxpandMode.ELLIPSE, sw=expand, sh=expand)
+
+    edgescombo = core.akarin.Expr(edgescombo.std.Invert(), f"x {scale_binary_value(luma, edges_strength, return_int=True)} +")
+    kirco_expanded = luma_mask_man(kirco_expanded, t=0.001, s=texture_strength, a=0.5)
+
+    mask = core.akarin.Expr([edgescombo.std.Invert(), kirco_expanded.std.Invert()], "x y +")
+
+    mask = gauss_blur(mask, blur)
+
+    return mask

vsdirty/adutils.py

@@ -0,0 +1,208 @@
+import vapoursynth as vs
+from typing import SupportsIndex, Optional, List, Tuple, Union
+
+def plane(
+    clip: vs.VideoNode,
+    index: SupportsIndex
+    ) -> vs.VideoNode:
+	"""
+	Returns a plane from the given clip at the specified index.
+
+	:param clip: The input video clip.
+	:param index: The index of the plane to return.
+	:return: A new video clip containing only the specified plane.
+	"""
+	return vs.core.std.ShufflePlanes(clip, index.__index__(), vs.GRAY)
+
+def scale_binary_value(
+        clip: vs.VideoNode,
+        value: float,
+        return_int: bool = True,
+        bit: Optional[int] = None,
+        )-> float:
+    """
+    Scales a value based on the bit depth of the clip.
+
+    :param clip:         Clip to process.
+    :param value:        Value to scale (0.0 - 1.0).
+    :param return_int:   Whether to return an integer value. Default is True (will be ignore if the input clip is Float).
+    :param bit:          Bit depth of the clip. If None, the bit depth of the clip will be used. Default is None.
+    :return:             Scaled value.
+    """
+    if bit is None and clip is not None:
+        if clip.format is None:
+            raise ValueError("scale_binary_value: Clip must have a defined format.")
+        
+        if clip.format.bits_per_sample is None:
+            raise ValueError("scale_binary_value: Clip must have a defined bit depth.")
+        
+        bit = clip.format.bits_per_sample
+
+    if not (0.0 <= value <= 1.0):
+        raise ValueError("scale_binary_value: Value must be between 0.0 and 1.0.")
+    
+    if clip.format.sample_type == vs.FLOAT or bit==32:
+        # For float clips, return the value as is
+        return value
+
+    max_val = (1 << bit) - 1
+
+    if return_int:
+        return int(value * max_val)
+    else:
+        return value * max_val
+
+def _detect_ranges(
+    diff: vs.VideoNode, 
+    thr: float
+) -> List[Tuple[int, int]]:
+    core = vs.core
+    stats = core.std.PlaneStats(diff)
+    
+    indices = []
+    warned_missing = False
+    for n in range(diff.num_frames):
+        f = stats.get_frame(n)
+        pmax = f.props.get('PlaneStatsMax')
+        
+        if pmax is None:
+            if not warned_missing:
+                print(f"Warning: PlaneStatsMax missing at frame {n}")
+                warned_missing = True
+            continue
+            
+        if pmax > thr:
+            indices.append(n)
+
+    detected_ranges = []
+    if indices:
+        start = prev = indices[0]
+        for i in indices[1:]:
+            if i == prev + 1:
+                prev = i
+            else:
+                detected_ranges.append((start, prev))
+                start = prev = i
+        detected_ranges.append((start, prev))
+    
+    return detected_ranges
+
+def diff_and_swap(
+    clipa: vs.VideoNode, 
+    clipb: vs.VideoNode, 
+    thr: float = 35000.0, 
+    discard_first: int = 0, 
+    discard_last: int = 0,
+    ranges: Optional[Union[List[int], List[Tuple[int, int]]]] = None,
+    precise_swapping: bool = False
+):
+	"""
+	Compares two clips (clipa and clipb) frame by frame based on Luma.
+	Identifies ranges of frames where the maximum absolute difference exceeds a certain threshold.
+
+	This function is useful for "patching" a source (clipb) with frames from 
+	another source (clipa) where differences are significant (e.g. artifacts, 
+	corruption, or different versions).
+
+	:param clipa:           The "correction" clip (e.g. WEB).
+	:param clipb:           The "base" clip (e.g. BD).
+	:param thr:             16-bit threshold applied to PlaneStatsMax. Default 35000.
+	:param discard_first:   Number of detected ranges to discard from the beginning (ignored if explicit ranges are used).
+	:param discard_last:    Number of detected ranges to discard from the end (ignored if explicit ranges are used).
+	:param ranges:          Manual range control.
+                               - None: Detects ranges, prints the map and uses ALL of them.
+                               - [-1]: Discards ALL ranges (returns original clipb, no calculation).
+                               - [int, ...]: Detects ranges, prints the map and uses only those at the specified indices.
+                               - [(start, end), ...]: Uses ONLY these explicit ranges, SKIPS DETECTION.
+	:param precise_swapping: If True, replaces only the differing pixels (diff > threshold -> expand -> blur -> mask).
+                               If False (default), replaces the entire frame in the detected ranges.
+	
+	:return:                A tuple `(merged, selected)` where `merged` is clipb with replacements from clipa, and 
+                            `selected` is a clip containing only the frames from clipa used for replacement 
+                            (or None if no frames were swapped).
+	"""
+	from vstools import depth, replace_ranges
+	core = vs.core
+
+	if not isinstance(clipa, vs.VideoNode) or not isinstance(clipb, vs.VideoNode):
+		raise vs.Error("diff_and_swap: both inputs must be VideoNode")
+
+	if not isinstance(discard_first, int) or not isinstance(discard_last, int) or discard_first < 0 or discard_last < 0:
+		raise vs.Error('diff_and_swap: discard_first/discard_last must be non-negative integers')
+
+	if clipa.format.id != clipb.format.id:
+		raise vs.Error("diff_and_swap: both clips must have the same format")
+
+	if clipa.format.color_family != vs.YUV or clipb.format.color_family != vs.YUV:
+		raise vs.Error("diff_and_swap: only YUV clips are supported")
+
+	clipa = depth(clipa, 16)
+	clipb = depth(clipb, 16)
+	
+	min_frames = min(clipa.num_frames, clipb.num_frames)
+	clipa_t = clipa.std.Trim(0, min_frames - 1) if clipa.num_frames != min_frames else clipa
+	clipb_t = clipb.std.Trim(0, min_frames - 1) if clipb.num_frames != min_frames else clipb
+
+	final_ranges = []
+	explicit_ranges = False
+
+	if ranges is not None and len(ranges) == 1 and ranges[0] == -1:
+		return clipb, None
+
+	if ranges is not None and len(ranges) > 0 and isinstance(ranges[0], tuple):
+		explicit_ranges = True
+		final_ranges = ranges
+		print(f"diff_and_swap: Using explicit ranges: {final_ranges}")
+
+	if precise_swapping:
+		diff_clip = core.std.Expr([clipa_t, clipb_t], "x y - abs")
+		
+		binary_thr = scale_binary_value(diff_clip, 4/255, bit=diff_clip.format.bits_per_sample) 
+		mask = diff_clip.std.Binarize(binary_thr)
+		mask = mask.std.Maximum().std.BoxBlur(hradius=1, vradius=1)
+		
+		replacement = core.std.MaskedMerge(clipb_t, clipa_t, mask)
+	else:
+		diff_clip = core.std.Expr([plane(clipa_t, 0), plane(clipb_t, 0)], "x y - abs")
+		replacement = clipa_t
+
+	if not explicit_ranges:
+		detected_ranges = _detect_ranges(diff_clip, thr)
+
+		if detected_ranges:
+			if discard_first:
+				detected_ranges = detected_ranges[discard_first:]
+			if discard_last:
+				if discard_last >= len(detected_ranges):
+					detected_ranges = []
+				else:
+					detected_ranges = detected_ranges[:len(detected_ranges) - discard_last]
+
+		if detected_ranges:
+			print("diff_and_swap Detected Range Map:")
+			for i, (s, e) in enumerate(detected_ranges):
+				print(f"Range {i}: {s} - {e} (Frames: {e-s+1})")
+		else:
+			print("diff_and_swap: No ranges detected.")
+
+		if ranges is None:
+			final_ranges = detected_ranges
+		else:
+			for idx in ranges:
+				if not isinstance(idx, int):
+					print(f"diff_and_swap Warning: Invalid index '{idx}' ignored.")
+					continue
+				if 0 <= idx < len(detected_ranges):
+					final_ranges.append(detected_ranges[idx])
+				else:
+					print(f"diff_and_swap Warning: Index {idx} out of bounds of detected ranges.")
+
+	if final_ranges:
+		merged = replace_ranges(clipb_t, replacement, final_ranges)
+		segments = [replacement.std.Trim(a, b) for a, b in final_ranges]
+		selected = core.std.Splice(segments)
+	else:
+		merged = clipb_t
+		selected = None
+
+	return merged, selected