gui-video-clipper/README.md

# GUI Video Clipper

A macOS desktop app for clipping segments from online videos. Paste a URL, scrub the timeline, mark your clips, and export — without manually downloading the video first.

## Features

- **URL Input** — Paste a YouTube (or other supported) URL and start working immediately
- **Video Preview** — Scrub, seek, and frame-step through the video with full transport controls
- **Mark In/Out** — Set clip boundaries with keyboard shortcuts (I/O) or transport buttons
- **Timeline** — Visual timeline with waveform display and thumbnail strip
- **Clip Export** — Export clips in lossless (stream copy) or precise (re-encode) modes
- **Captions** — Download subtitles, preview with karaoke-style highlighting, burn into exports
- **Setup Wizard** — Automatically detects and installs required dependencies (ffmpeg, yt-dlp)

## Prerequisites

- **macOS** (primary target platform)
- **Node.js** (v18+)
- **Rust** toolchain ([rustup.rs](https://rustup.rs))

ffmpeg and yt-dlp are detected (and can be installed) automatically by the built-in setup wizard on first launch.

## Build & Run

```bash
# Install frontend dependencies
npm install

# Development (hot-reload)
npm run tauri dev

# Production build
npm run tauri build
```

## Release Build

```bash
npm run release
```

This runs the full Tauri production build, ad-hoc code signs the `.app` bundle, and copies the output to `dist/release/`.

The resulting `GUI Video Clipper.app` can be launched directly or dragged to `/Applications`.

## Architecture

GUI Video Clipper is built with [Tauri v2](https://v2.tauri.app/) (Rust backend) and [Svelte 5](https://svelte.dev/) (TypeScript frontend).

### Backend (Rust)

- **Video Resolver** — Resolves URLs via yt-dlp, extracts metadata and stream URLs
- **Download Manager** — Manages preview and high-quality downloads with progress tracking
- **Media Server** — Local HTTP server for streaming video to the frontend player
- **Waveform Generator** — Extracts audio waveform data at multiple zoom tiers via ffmpeg
- **Thumbnail Extractor** — Generates timeline thumbnail strips from keyframes
- **Export Pipeline** — Handles clip extraction with ffmpeg (lossless and precise modes)
- **Subtitle Downloader** — Fetches and converts subtitles for preview and burn-in

### Frontend (Svelte 5 + TypeScript)

- **Timeline** — Canvas-based timeline with waveform, thumbnails, and clip region rendering
- **Transport Controls** — Play/pause, seek, frame-step, shuttle (J/K/L), keyboard shortcuts
- **Video Player** — HTML5 video element connected to the local media server
- **Export Dialog** — Configure and execute clip exports with progress tracking
- **Caption Settings** — Font, color, shadow, and positioning controls for subtitle burn-in

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Make your changes
4. Run checks: `npm run check`
5. Commit with a descriptive message
6. Open a pull request

## License

[MIT](LICENSE)