Clipper John

Local Podcast Video Clipper & Acoustic Signal Highlight Extraction Engine

Clipper John is a local desktop application and acoustic signal analyzer designed for automated highlight extraction from long-form video podcasts, interviews, and streams. It computes RMS energy profiles through continuous FFmpeg PCM pipes, applies digital signal processing (DSP) peak detection algorithms, and slices video segments losslessly with zero cloud dependencies.

---

Technical Architecture & DSP Pipeline

Media Ingestion (MP4/MKV/WebM)
         │
         ▼
FFmpeg PCM s16le Audio Pipe (16 kHz Mono)
         │
         ▼
Vectorized RMS Energy Chunking (NumPy)
         │
         ▼
Prominence Peak Extraction (SciPy find_peaks)
         │
         ▼
Temporal Windowing & Overlap Suppression
         │
         ▼
Lossless Stream Extraction / NVENC Hardware Re-Encode

1. Memory-Constrained PCM Streaming

Audio streams are decoded on-the-fly via uncompressed 16-bit PCM s16le pipes at 16 kHz:

• Constant memory footprint (< 200 MB) regardless of source video length (tested on 5+ hour recordings).
• Bypasses intermediate uncompressed WAV disk writes.

2. Algorithmic Highlight Extraction

• Computes vectorized Root-Mean-Square (RMS) amplitude envelopes across parameterized time windows: $$\text{RMS} = \sqrt{\frac{1}{N}\sum_{i=1}^N x[i]^2}$$
• Uses scipy.signal.find_peaks with configurable prominence, distance, and threshold gates to identify heightened conversational or audience reaction moments while suppressing baseline noise.

3. Hardware-Accelerated Lossless Slicing

• Extracts high-interest segments using keyframe-accurate stream copying (-c copy) or GPU-accelerated encoding (h264_nvenc, hevc_nvenc, libx264).

---

Project Structure

clipper-john/
├── src/
│   ├── engine/
│   │   ├── downloader.py      # Stream ingestion and local file handler
│   │   ├── renderer.py        # FFmpeg video extraction and re-encoding
│   │   └── signal_analyzer.py # Vectorized RMS energy & peak detection engine
│   ├── utils/
│   │   └── binary_helper.py   # Bundled and system FFmpeg resolver
│   └── main.py                # PySide6 desktop interface and telemetry charts
├── requirements.txt           # Python dependencies (PySide6, numpy, scipy, yt-dlp)
├── build_spec.spec            # PyInstaller binary packaging specification
└── README.md

---

Installation & Setup

Prerequisites

• Python 3.10+
• FFmpeg installed and accessible in PATH (or placed in the project root)

Setup Instructions

# Clone the repository
git clone https://github.com/valliente/clipper-john.git
cd clipper-john

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Launch application
python src/main.py

---

License

Distributed under the MIT License. See LICENSE for details.