minicut 0.1.0

Local browser app for dataset video trimming and cropping

Minicut

Minicut is a local-first browser app for dataset preprocessing. It trims and crops videos, converts output FPS, and keeps original files unchanged.

What Is Implemented

• Workspace video discovery from a single directory (non-recursive).
• Workspace list with processed-file counts.
• Workspace list sorting by:
  • name
  • processed count
  • asc or desc order
• Active/selected source video highlighting in the workspace list.
• Original video editor with:
  • Photoshop-style crop rectangle (draw, move, edge/corner resize)
  • trim preview controls (preview range, seek begin, seek end)
  • custom play/pause and scrub controls
• Trim models:
  • begin second + duration in seconds
  • begin second + duration in frames (using output FPS)
• Output FPS conversion (default: 24).
• Processed video panel:
  • list all processed variants
  • preview selected output
  • open output directly
  • delete output
  • processed stats table
• Original and processed stats tables:
  • fps, duration, resolution, codec, format, size, created/modified timestamps
• Background in-process job execution with job polling/status updates.
• Automatic workspace refresh on job completion (including a follow-up refresh for count consistency).

Processing Behavior

• Output files are written to an output folder under the workspace.
  • Default output folder name: processed
• Source files are never overwritten.
• Output naming is collision-safe:
  • <stem>_processed.mp4
  • <stem>_processed_1.mp4
  • <stem>_processed_2.mp4
  • ...
• ffmpeg pipeline currently:
  • trim window (-ss, -to)
  • video filters: crop, fps
  • video codec: libx264
  • audio codec: aac

Requirements

• Python 3.11+
• ffmpeg on PATH
• ffprobe on PATH
• uv package manager

Install

uv sync

Run

uv run minicut

By default this uses:

• workspace: current directory
• output folder: processed
• host: 127.0.0.1
• port: 8765

Common CLI options

uv run minicut --workspace /path/to/videos
uv run minicut --workspace /path/to/videos --output-folder processed
uv run minicut --host 0.0.0.0 --port 8765
uv run minicut --no-open-browser

Basic Workflow

1. Start Minicut.
2. Select a source video from Workspace Videos.
3. Set trim mode, begin, duration, crop rectangle, and output FPS.
4. Optionally preview trim range in the original player.
5. Run processing.
6. Inspect output in Processed Videos and Processed Preview.
7. Repeat as needed; originals stay intact.

API Summary

Media endpoints:

• GET /api/media/videos
• GET /api/media/metadata
• GET /api/media/stats
• GET /api/media/file
• GET /api/media/processed-preview
• GET /api/media/processed-videos
• DELETE /api/media/processed-file

Job endpoints:

• POST /api/jobs/process
• GET /api/jobs/{job_id}

Safety Constraints

• Process source path must be inside the workspace directory.
• File serving is restricted to workspace or output directory.
• Delete is restricted to output directory only.

Development

Run tests:

uv run pytest

Known Limitations

• Workspace scan is non-recursive.
• Job queue is in-memory (no persistence across restart).
• Processing currently targets H.264/AAC MP4 output.