Installation

There are two supported ways to install AdSlicer. Most users should download a compiled release. Developers, contributors, and users who need a custom build can compile the application from source.

Compiled Release Workflow

1. Open GitHub Releases.
2. Choose the newest stable release.
3. Download the package matching your operating system.
4. Extract or mount the package, then move AdSlicer into your normal Applications or Programs location.
5. Launch AdSlicer and choose an input video plus an output directory.

Build-from-Source Summary

git clone https://github.com/schwwaaa/AdSlicer.git
cd AdSlicer
chmod +x build.sh
./build.sh setup-bins
./build.sh mac-universal   # macOS universal application
# or
./build.sh windows         # Windows x86_64

See Building from Source for prerequisites, development mode, sidecar setup, and target-specific commands.

Quick Start

1. Choose your input

Select a single video file, or switch to Batch Folder mode and select a directory. All matching video files inside will be queued.

2. Set your output folder

A subfolder is created per input file — you'll never lose track of which output came from which tape. Results are never overwritten; re-processing appends _1, _2, etc.

3. Pick a preset

Open the Presets menu and choose the one closest to your source material. See Preset System for descriptions.

4. Dry run first

Enable Dry Run before committing to a full export. This runs the full detection pipeline and writes all logs, but cuts no media. Review detect.json and check dataset.jsonl for cuts where only sig_black_boundary fired and confidence is below 0.90 — those are the weakest detections and worth inspecting first.

5. Final export

Disable Dry Run. Enable Re-encode for frame-accurate archival cuts (H.264/AAC). Run.

Recommended workflow:

  1. Enable Dry Run
  2. Review activity log and detect.json
  3. Adjust parameters if needed, re-run dry
  4. Disable Dry Run, enable Re-encode
  5. Run final export

Output Structure

Embedding chapter markers

Keep segments become Content N chapters; commercial blocks become Advertisement N. Embed into the show file:

ffmpeg -i show.mp4 -i logs/chapters.ffmeta \
  -map_metadata 1 -c copy show_with_chapters.mp4

Recognized by VLC, mpv, Kodi, and any player that reads ffmpeg metadata.

How It Works

Each commercial candidate passes through four independent detection passes in sequence. Every signal that fires is recorded against the interval and reflected in its confidence score.

Detection Passes

Scoring Guards

Confidence Score

Every CutInterval carries a confidence float (0.0–1.0) and a signals list. The activity log renders confidence as a star rating:

All Parameters

Input / Output

Black Frame Detection

Cut Behaviour

Advanced Detection (Comskip-derived)

Verbosity

Preset System

AdSlicer ships with three built-in presets and a full save/load system.

Built-in Presets

Preset Menu

Presets
  ── BUILT-IN ──────────────
  Broadcast strict
  Default
  VHS noisy
  ── MY PRESETS ────────────
  my_custom_settings
  ──────────────────────────
  Save Current as Preset…
  ──────────────────────────
  Open User Presets Folder…
  Reload Presets

User Preset Locations

Use Presets → Open User Presets Folder… to open this location. Drop any .json file there and use Reload Presets to make it appear in the menu.

Preset File Format

Plain JSON. _preset sets the menu label; _description sets the tooltip. Unrecognized keys are silently ignored.

{
  "_preset": "My custom VHS settings",
  "_description": "Tuned for my specific deck and capture card.",
  "blackMinDur": 0.10,
  "pixTh": 0.08,
  "picTh": 0.98,
  "mergeGap": 1.5,
  "minCommercial": 5,
  "maxCommercial": 240,
  "silenceNoiseDb": -40,
  "requireDiv5": false
}

Adding a Built-in Preset to the Build

Drop a .json file into src-tauri/presets/ and rebuild. The tauri.conf.json resources glob picks it up — no code changes needed.

Tips & Tricks

AdSlicer works best as a review-assisted archival tool: analyze first, inspect the uncertain boundaries, then render only after the plan looks correct. These practices reduce accidental content loss and make large tape collections much faster to process.

Fast, Safe Review Workflow

1. Import the full recording.
2. Run detection with Dry Run enabled.
3. Inspect suspect short intervals and low-confidence boundaries first.
4. Adjust only the settings needed for the source.
5. Repeat the dry run until the detection plan is trustworthy.
6. Enable Re-encode for the final frame-accurate archival export.
7. Sort the rendered outputs into shows, commercials, promos, station IDs, and other archival categories.

Choose Speed or Precision Intentionally

Source-Specific Tricks

Noisy or Near-Black VHS Transitions

• Raise pixTh slightly and lower picTh so analog black does not have to be perfectly clean.
• Increase mergeGap when a black separator flickers or contains brief tracking noise.
• Keep requireDiv5 disabled when tape timing has drifted away from exact broadcast durations.

Protect Openings and End Credits

• Use alwaysKeepFirst to protect cold opens, station intros, and leading material.
• Use alwaysKeepLast to protect credits, post-credit tags, and tape-end material.
• Increase minShowSegment when short dark scenes are being mistaken for breaks.

Organize the Output Immediately

• Keep the generated logs/ folder with every processed tape; it is the audit trail for how the result was produced.
• Rename or catalog commercials only after the automatic segmentation is complete.
• Use chapters.ffmeta, EDL, CSV, or JSON output when another archival or editorial tool needs the boundary data.

Tuning Guide

Thresholds may require tuning for darker or noisier analog captures. Always Dry Run first and review dataset.jsonl before committing to export.

Too many false positives (content being cut)

• Raise blackMinDur (0.15–0.25) — require longer slugs
• Raise picTh (0.99) — require nearly pure black frames
• Increase minShowSegment (60–120 s) — prevent short content being consumed
• Enable requireDiv5 for clean broadcast — non-multiples of 30 s are not real ad breaks
• Raise minCommercial — filter breaks too short to be real commercials
• Check dataset.jsonl for cuts where only sig_black_boundary fired — weakest detections

Missed commercials (breaks not detected)

• Lower blackMinDur (0.06–0.08) — accept shorter slugs
• Raise pixTh (0.10–0.14) — more permissive black definition
• Lower picTh (0.90–0.95) — allow noisier black frames
• Increase mergeGap for flickering VHS slug patterns
• Lower sceneThreshold (0.25–0.35) — catch more cuts within blocks

Noisy or degraded VHS

• Raise pixTh + lower picTh — the standard analog adjustment
• Raise uniformMaxStddev (12–18) — VHS black slugs are never truly uniform
• Set removeBefore 0.1 — recovers content clipped by ambiguous slug entry points
• Disable requireDiv5 — VHS timing is irregular
• Lower silenceNoiseDb to -35 dB — VHS audio floor is noisier

Clean off-air broadcast

• Enable requireDiv5 — US TV commercials are exact 15/30/60/90 s units
• Set alwaysKeepFirst 15 and alwaysKeepLast 15 — protect cold opens and credits
• Lower uniformMaxStddev to 5–6 — broadcast slates are near-perfect
• Raise sceneThreshold to 0.45 — hard cuts only; avoid dissolve false positives

Recommended workflow

1. Run with dryRun enabled — review detect.json and the activity log
2. Check dataset.jsonl — confidence below 0.90 or only sig_black_boundary firing is worth inspecting
3. Adjust parameters and re-run dry until the plan is correct
4. Remove dryRun and enable reencode for final archival export

ML Dataset Output

Every run writes logs/dataset.jsonl — one JSON object per line, one line per segment, 74 columns. Load it directly:

import pandas as pd
df = pd.read_json("logs/dataset.jsonl", lines=True)

Column Groups

Identity (4 cols)

Timing (9 cols)

Signal Indicators — all 0.0 or 1.0 (11 cols)

Classification (3 cols)

Usage Examples

import pandas as pd
from sklearn.ensemble import RandomForestClassifier

df = pd.read_json("logs/dataset.jsonl", lines=True)

# Feature matrix
X = df[[
    "dur_s", "dur_norm", "start_norm",
    "black_left_dur_s", "black_right_dur_s",
    "silence_coverage", "has_silence_overlap",
    "scene_change_rate", "scene_change_rate_vs_avg",
    "sig_black_boundary", "sig_silence_overlap",
]]
y = df["label_int"]

# Compare across parameter tuning runs
runs = pd.concat([
    pd.read_json("run1/logs/dataset.jsonl", lines=True),
    pd.read_json("run2/logs/dataset.jsonl", lines=True),
])
runs.groupby("param_scene_threshold")["run_commercial_ratio"].mean()

# Inspect low-confidence cuts
df[(df["label"] == "commercial") & (df["confidence"] < 0.9)]

Use Cases

AdSlicer is designed for recordings where the commercials, program material, transitions, and broadcast artifacts are all historically useful—but need to be separated into practical, reviewable outputs.

Preserving a Complete Broadcast and a Clean Viewing Copy

A collector digitizes an off-air movie, sports broadcast, or television block from VHS. AdSlicer preserves the original capture, creates a clean show master, isolates commercial blocks, and writes detection metadata so both versions remain traceable to the same source.

Processing Large VHS and Broadcast Collections

An archive, library, preservation group, or individual collector has hundreds of related tapes. A representative tape is tuned first, its settings are saved as a preset, and batch mode then produces consistent folder structures and diagnostics across the collection.

Recovering Vintage Commercials, Promos, and Station IDs

Commercial blocks can be exported as separate clips for historical research, brand studies, broadcast design reference, compilation editing, or cataloging. The program is not merely deleting advertisements—it is separating two valuable classes of archival material.

Preparing Ad-Free Program Masters

Editors and collectors can create watchable copies of cartoons, movies, music programs, news, and episodic television while retaining the source capture and isolated advertisements elsewhere in the project.

Boundary Review and Quality Control

Detection logs identify short, weak, or unusual candidate intervals that deserve attention. Reviewers can focus on suspect boundaries instead of manually scrubbing through every hour of the recording.

Building Research and Machine-Learning Datasets

The structured dataset.jsonl, detect.json, CSV, EDL, and run manifest outputs provide labeled timing, confidence, signal, and parameter data for commercial-detection research, comparative testing, and future model development.

Creating Editorial Compilations

Once commercial blocks are extracted, an editor can sort clips by brand, year, network, product category, visual style, or campaign. The same workflow also supports promo reels, station-identification collections, and historical broadcast packages.

Integrating With Other Archive Tools

EDL, chapter metadata, CSV, and JSON outputs can be handed to media players, command-line processes, database ingest tools, or nonlinear editors without forcing every downstream system to repeat the detection pass.

Building from Source

This path is intended for developers, contributors, and users who need a custom application build. Users who only want to run AdSlicer should use the compiled package described under Installation.

Prerequisites

• Git
• Rust and Cargo
• Tauri CLI
• Platform build tools for macOS or Windows
• curl or wget, plus unzip

Clone the repository

git clone https://github.com/schwwaaa/AdSlicer.git
cd AdSlicer
chmod +x build.sh

First-time sidecar setup

Download the static FFmpeg and FFprobe binaries that Tauri bundles with the application. The target-specific filenames are required before compilation.

./build.sh setup-bins

Dev mode

cd src-tauri
cargo tauri dev

Release builds

ffmpeg and ffprobe are bundled automatically. Users need no external dependencies.

Adding a built-in preset

Drop a .json file into src-tauri/presets/ and run ./build.sh. The tauri.conf.json resources glob picks it up — no code changes needed.