Project Documentation

quickCut

quickCut runs a direct URL-to-export workflow with optional scene auto-cut, manual segment control, and downloadable outputs for show and edit pipelines.

Core Flow Analyze, Auto-Cut, Export

Formats mp4, hap, dxv3

Runtime localhost:3000

Batch Limit 20 URLs per Job

What quickCut Solves

quickCut provides a focused path from source URL to production export with optional automatic scene splitting, reducing repetitive manual cut prep.

Single URL or Batch Optional Auto-Cut Direct Downloads

Quick Start

Install dependencies: yt-dlp, ffmpeg, ffprobe.
Optional auto-cut dependency: python3 + scenedetect.
Install project packages: npm install
Run app: npm start
Open http://localhost:3000

Main Workflow (Single URL)

Open New Job and paste one YouTube URL.
Click Analyze Source.
Choose codec and resolution in output settings.
Enable Auto-Cut when needed.
Click Start Export and download results from the completed row.

Segment Editing Controls

In/Out Precision

Use numeric In/Out fields and stacked full-width handles for precise boundary trimming.

Scene Actions

Use selected-scene shortcuts: I, O, M, X.

Playhead Tools

Split the selected segment at playhead, then apply edits before export.

Keyboard Nudges

, / . for fine moves, Shift + , / Shift + . for larger steps.

Batch + Output Behavior

Batch jobs process URLs sequentially.
Max 20 URLs per job.
Manual segment editing is single-item workflow only.
Outputs are written to local downloads/.
Scene split exports clip links when enabled.

Technical Stack

Frontend: static SPA in public/index.html.
Backend: Node.js + Express in server/index.js.
External tools: yt-dlp, ffmpeg, ffprobe.
Optional scene detection: python3 + PySceneDetect.

Architecture + API Surface

Analysis Endpoints

POST /api/analyze, GET /api/analyze/:analysisId, PATCH /api/analyze/:analysisId/segments.

Preview Streaming

GET /api/preview/:analysisId/video serves range-enabled MP4 preview.

Job + Download API

POST /api/jobs, GET /api/jobs/:jobId, item and clip download routes.

Health Diagnostics

GET /api/health reports dependency readiness and codec support.

Validation + Safety Rules

Segments must be sorted, non-overlapping, and duration >= 0.25s.
Max 300 segments per item, bounded by media duration.
YouTube host allowlist enforced for intake URLs.
Rate limit guardrail: 30 requests / 60 seconds per IP.
In-memory queue with one active worker at a time.

Troubleshooting Checklist

Dependency unavailable: verify binaries with version commands and restart app.
Port conflict: run PORT=3011 npm start.
Auto-cut unavailable: install scenedetect via pip.
QuickTime playback issues: prefer mp4 output.
Check runtime status quickly at /api/health.