Stream Clipper v1.4

Overview

Stream Clipper is a multi-platform live stream clipper tool designed to capture video segments from YouTube, Twitch, and Kick. It allows users to set specific durations, pick video qualities, and generate downloadable MP4s directly from a live stream. Additionally, it supports direct one-click server-side proxy uploads to file-hosting services like Catbox, qu.ax, and Videy.

Features

• Multi-Platform Support: Extract clips from YouTube, Twitch, and Kick live streams.
• DVR Rewind: A rewind slider UI allows users to capture moments from earlier in the stream (up to 120 seconds back via the UI, with the backend supporting up to 300 seconds). The backend utilizes a startOffset parameter to seek directly into the HLS DVR buffer for precise historical clipping.
• Advanced YouTube Extraction: Uses yt-dlp to hit the YouTube Android player_client innertube API. This bypasses PO Token requirements for VPS/datacenter IPs and avoids the channel-page scraper that frequently causes 404 errors.
• Direct HLS Capture: Pre-resolves Twitch and Kick streams to direct HLS URLs, passing them straight to native FFmpeg for highly reliable live-edge clipping instead of relying on yt-dlp section downloads.
• Direct Uploads: Instantly push clipped MP4 files to Catbox, qu.ax, or Videy through dedicated server-side proxy routes.
• Live Previews: Embedded iframe support to preview streams before clipping, featuring a mobile-friendly touch shield to prevent layout issues.
• Automated Cleanup: Background jobs run every 30 minutes to automatically remove stale MP4 clips and temporary raw files, keeping disk usage strictly bounded.
• Database Analytics: Powered by SQLite (in WAL mode for concurrency), the database tracks clip counts, unique users, and total stream durations, and features updated migrations for startOffset and original URL logging.
• Rate Limiting & Security: Built-in per-IP rate limiters prevent API abuse (capped at 5 clips per minute), paired with session-based authentication to keep the master API key entirely off the frontend.

Prerequisites

If you are setting this up manually or natively, ensure your system has the following installed:

• Node.js v18 or higher (Node 20 LTS recommended)
• yt-dlp (latest version)
• FFmpeg
• SQLite3
• Or simply use Docker (see below).

Docker Deployment (Recommended)

The most reliable and isolated way to deploy Stream Clipper is via Docker.

1. Make sure Docker and Docker Compose are installed on your host system.
2. Clone the repository and copy the example environment file:

   cp .env.example .env

3. Configure your .env file with your API keys and secure CLIPPER_API_KEY.
4. Build and start the container in detached mode:

   docker compose up -d --build

Docker Architecture Notes

• Persistent Volumes: The Compose file automatically creates isolated volumes for your SQLite database (clipper-db), generated MP4 clips (clipper-clips), temp processing files (clipper-temp), and logs (clipper-logs) so you don't lose data on container rebuilds.
• Security Constraints: The container drops all unused Linux capabilities (cap_drop: ALL) to limit the blast radius if the app misbehaves.
• Resource Limits: To prevent FFmpeg from starving your host server, the container is hard-capped at 1GB of memory and 2 CPU cores.
• Networking: By default, the app is exposed purely to 127.0.0.1:4242. It is highly recommended to route external traffic through a reverse proxy (like Nginx) to handle HTTPS.

Automated Deployment (Ubuntu/Debian)

If you prefer a native, non-Docker installation, a comprehensive deployment script is included to provision a server from scratch. It automatically installs Nginx, Let's Encrypt (Certbot), PM2, FFmpeg, Node.js 20, and yt-dlp.

chmod +x deploy.sh
sudo ./deploy.sh

You can also apply strict SSH, UFW, and Fail2ban security rules (including custom Nginx 4xx flood filters to catch bad bots and scanners) using the included hardening script:

chmod +x harden.sh
sudo ./harden.sh

Environment Variables

Configure the application by setting up a .env file in the root directory. Key variables utilized include:

• PORT: The port the app runs on (default: 4242).
• CLIPPER_API_KEY: Required 32+ character admin security token.
• CLIPPER_BROWSER_KEY: (Optional) Separate token used for browser sessions.
• MAX_CLIP_SECONDS: Maximum allowable duration for a single clip (default: 300).
• API Credentials: YOUTUBE_API_KEY, KICK_CLIENT_ID, KICK_CLIENT_SECRET, CATBOX_USERHASH, VIDEY_API_KEY, and VIDEY_API_SECRET.

Manual Installation & Development

To run the application locally without Docker or the automated deployment script:

1. Clone the repository and run npm install --omit=dev.
2. Ensure your .env is fully populated with the required keys.
3. Start the server in development mode using node clipper.js or npm run dev.
4. The application will be accessible locally at http://localhost:4242.

License

This project is licensed under the GNU General Public License v3.0.