Commit 388cf70

@@ -0,0 +1,90 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/crash/upvs/internal/config"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/pipeline"
+	"github.com/crash/upvs/internal/protect"
+	"github.com/spf13/cobra"
+)
+
+var fetchCmd = &cobra.Command{
+	Use:   "fetch",
+	Short: "Download video clips",
+	Long:  "Download clips listed in clip_index.json with concurrent workers and retry support.",
+	RunE:  runFetch,
+}
+
+func init() {
+	fetchCmd.Flags().StringVar(&dateStr, "date", "", "Target date YYYY-MM-DD (required)")
+	fetchCmd.Flags().IntVar(&cfg.Workers, "workers", config.DefaultWorkers, "Number of concurrent download workers")
+	fetchCmd.Flags().IntVar(&cfg.Retries, "retries", config.DefaultRetries, "Number of retry attempts per clip")
+	fetchCmd.MarkFlagRequired("date")
+}
+
+func runFetch(cmd *cobra.Command, args []string) error {
+	// Parse date
+	date, err := config.ParseDate(dateStr)
+	if err != nil {
+		return err
+	}
+	cfg.Date = date
+
+	// Validate required fields
+	if cfg.Host == "" {
+		return config.ErrMissingHost
+	}
+	if cfg.Username == "" || cfg.Password == "" {
+		return config.ErrMissingCredentials
+	}
+	if cfg.Camera == "" {
+		return config.ErrMissingCamera
+	}
+	if cfg.OutDir == "" {
+		return config.ErrMissingOutDir
+	}
+
+	// Create layout
+	layout := output.NewLayout(cfg.OutDir, cfg.Camera, cfg.DateString())
+
+	// Create client
+	var opts []protect.ClientOption
+	if cfg.TLSInsecure {
+		opts = append(opts, protect.WithTLSInsecure())
+	}
+	if cfg.DirectAPI {
+		opts = append(opts, protect.WithDirectAPI())
+	}
+	client := protect.NewClient(cfg.Host, opts...)
+
+	// Login
+	ctx := context.Background()
+	err = client.Login(ctx, cfg.Username, cfg.Password)
+	if err != nil {
+		return fmt.Errorf("login: %w", err)
+	}
+
+	// Run fetch
+	result, err := pipeline.Fetch(ctx, client, layout, pipeline.FetchConfig{
+		Workers: cfg.Workers,
+		Retries: cfg.Retries,
+	})
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Fetch complete: %d downloaded, %d skipped, %d failed\n",
+		result.Downloaded, result.Skipped, result.Failed)
+
+	if result.Failed > 0 {
+		fmt.Println("Failed clips:")
+		for _, e := range result.Errors {
+			fmt.Printf("  - %v\n", e)
+		}
+	}
+
+	return nil
+}

@@ -0,0 +1,69 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/crash/upvs/internal/config"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/pipeline"
+	"github.com/spf13/cobra"
+)
+
+var renderCmd = &cobra.Command{
+	Use:   "render",
+	Short: "Generate timelapse video",
+	Long:  "Render downloaded clips into a timelapse video using FFmpeg.",
+	RunE:  runRender,
+}
+
+func init() {
+	renderCmd.Flags().StringVar(&dateStr, "date", "", "Target date YYYY-MM-DD (required)")
+	renderCmd.Flags().IntVar(&cfg.TargetSecs, "target", config.DefaultTargetSecs, "Target output duration in seconds")
+	renderCmd.Flags().IntVar(&cfg.FPS, "fps", config.DefaultFPS, "Output frame rate")
+	renderCmd.Flags().IntVar(&cfg.CRF, "crf", config.DefaultCRF, "FFmpeg CRF quality (0-51, lower=better)")
+	renderCmd.Flags().StringVar(&cfg.Preset, "preset", config.DefaultPreset, "FFmpeg preset (ultrafast to veryslow)")
+	renderCmd.MarkFlagRequired("date")
+}
+
+func runRender(cmd *cobra.Command, args []string) error {
+	// Parse date
+	date, err := config.ParseDate(dateStr)
+	if err != nil {
+		return err
+	}
+	cfg.Date = date
+
+	// Validate required fields
+	if cfg.Camera == "" {
+		return config.ErrMissingCamera
+	}
+	if cfg.OutDir == "" {
+		return config.ErrMissingOutDir
+	}
+
+	// Create layout
+	layout := output.NewLayout(cfg.OutDir, cfg.Camera, cfg.DateString())
+
+	// Run render
+	ctx := context.Background()
+	result, err := pipeline.Render(ctx, layout, pipeline.RenderConfig{
+		TargetSecs:   cfg.TargetSecs,
+		FPS:          cfg.FPS,
+		CRF:          cfg.CRF,
+		Preset:       cfg.Preset,
+		MinSpeedMult: cfg.MinSpeedMult,
+		MaxSpeedMult: cfg.MaxSpeedMult,
+	})
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Render complete!\n")
+	fmt.Printf("  Output: %s\n", result.OutputPath)
+	fmt.Printf("  Speed factor: %.2fx\n", result.SpeedFactor)
+	fmt.Printf("  Duration: %.1f seconds\n", result.OutputDuration)
+	fmt.Printf("  Clips: %d/%d\n", result.Metadata.ValidClips, result.Metadata.TotalClips)
+
+	return nil
+}

@@ -0,0 +1,95 @@
+// Package cli implements the command-line interface.
+package cli
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+
+	"github.com/crash/upvs/internal/config"
+	"github.com/spf13/cobra"
+)
+
+var cfg = config.New()
+
+// Global flag variables for file-based password loading
+var passwordFile string
+
+// rootCmd is the base command.
+var rootCmd = &cobra.Command{
+	Use:   "upvs",
+	Short: "UniFi Protect Video Summarizer",
+	Long:  "Create ~10-minute timelapses from UniFi Protect camera recordings for a single day.",
+	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+		// Load password from file if specified
+		if passwordFile != "" && cfg.Password == "" {
+			err := cfg.LoadPasswordFromFile(passwordFile)
+			if err != nil {
+				return err
+			}
+		}
+
+		// Set up logging
+		level := slog.LevelInfo
+		if cfg.Verbose {
+			level = slog.LevelDebug
+		}
+		handler := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: level})
+		slog.SetDefault(slog.New(handler))
+
+		return nil
+	},
+}
+
+func init() {
+	// Silence usage and errors on failure - we handle error printing in Execute()
+	rootCmd.SilenceUsage = true
+	rootCmd.SilenceErrors = true
+
+	// Connection flags
+	rootCmd.PersistentFlags().StringVar(&cfg.Host, "host", "", "UniFi Protect URL (env: UPVS_HOST)")
+	rootCmd.PersistentFlags().StringVar(&cfg.Username, "username", "", "Username (env: UPVS_USERNAME)")
+	rootCmd.PersistentFlags().StringVar(&cfg.Password, "password", "", "Password (env: UPVS_PASSWORD)")
+	rootCmd.PersistentFlags().StringVar(&passwordFile, "password-file", "", "Path to file containing password")
+	rootCmd.PersistentFlags().BoolVar(&cfg.TLSInsecure, "tls-insecure", false, "Skip TLS verification")
+	rootCmd.PersistentFlags().BoolVar(&cfg.DirectAPI, "direct-api", false, "Use /api path (for direct NVR connection, not UniFi OS)")
+
+	// Target selection flags
+	rootCmd.PersistentFlags().StringVar(&cfg.Camera, "camera", "", "Camera ID or name")
+
+	// Output flags
+	rootCmd.PersistentFlags().StringVar(&cfg.OutDir, "out", "", "Output directory")
+	rootCmd.PersistentFlags().BoolVarP(&cfg.Verbose, "verbose", "v", false, "Enable debug logging")
+
+	// Bind environment variables
+	bindEnv("UPVS_HOST", &cfg.Host)
+	bindEnv("UPVS_USERNAME", &cfg.Username)
+	bindEnv("UPVS_PASSWORD", &cfg.Password)
+
+	// Add subcommands
+	rootCmd.AddCommand(scanCmd)
+	rootCmd.AddCommand(fetchCmd)
+	rootCmd.AddCommand(renderCmd)
+	rootCmd.AddCommand(runCmd)
+}
+
+// bindEnv sets a flag default from an environment variable if the flag is empty.
+func bindEnv(envVar string, target *string) {
+	if val := os.Getenv(envVar); val != "" && *target == "" {
+		*target = val
+	}
+}
+
+// Execute runs the root command.
+func Execute() {
+	err := rootCmd.Execute()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+// GetConfig returns the global configuration.
+func GetConfig() *config.Config {
+	return cfg
+}

@@ -0,0 +1,116 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/crash/upvs/internal/config"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/pipeline"
+	"github.com/crash/upvs/internal/protect"
+	"github.com/spf13/cobra"
+)
+
+var runCmd = &cobra.Command{
+	Use:   "run",
+	Short: "Run full pipeline (scan + fetch + render)",
+	Long:  "Execute all phases: enumerate events, download clips, and render timelapse.",
+	RunE:  runAll,
+}
+
+func init() {
+	runCmd.Flags().StringVar(&dateStr, "date", "", "Target date YYYY-MM-DD (required)")
+	runCmd.Flags().IntVar(&cfg.Workers, "workers", config.DefaultWorkers, "Number of concurrent download workers")
+	runCmd.Flags().IntVar(&cfg.Retries, "retries", config.DefaultRetries, "Number of retry attempts per clip")
+	runCmd.Flags().IntVar(&cfg.TargetSecs, "target", config.DefaultTargetSecs, "Target output duration in seconds")
+	runCmd.Flags().IntVar(&cfg.FPS, "fps", config.DefaultFPS, "Output frame rate")
+	runCmd.Flags().IntVar(&cfg.CRF, "crf", config.DefaultCRF, "FFmpeg CRF quality (0-51, lower=better)")
+	runCmd.Flags().StringVar(&cfg.Preset, "preset", config.DefaultPreset, "FFmpeg preset (ultrafast to veryslow)")
+	runCmd.MarkFlagRequired("date")
+}
+
+func runAll(cmd *cobra.Command, args []string) error {
+	// Parse date
+	date, err := config.ParseDate(dateStr)
+	if err != nil {
+		return err
+	}
+	cfg.Date = date
+
+	// Validate all required fields
+	err = cfg.Validate()
+	if err != nil {
+		return err
+	}
+
+	// Create layout and ensure directories
+	layout := output.NewLayout(cfg.OutDir, cfg.Camera, cfg.DateString())
+	err = layout.EnsureDirs()
+	if err != nil {
+		return err
+	}
+
+	// Create client
+	var opts []protect.ClientOption
+	if cfg.TLSInsecure {
+		opts = append(opts, protect.WithTLSInsecure())
+	}
+	if cfg.DirectAPI {
+		opts = append(opts, protect.WithDirectAPI())
+	}
+	client := protect.NewClient(cfg.Host, opts...)
+
+	// Login
+	ctx := context.Background()
+	err = client.Login(ctx, cfg.Username, cfg.Password)
+	if err != nil {
+		return fmt.Errorf("login: %w", err)
+	}
+
+	// Phase A: Scan
+	fmt.Println("=== Phase 1: Scanning events ===")
+	scanResult, err := pipeline.Scan(ctx, client, layout, cfg.Camera, cfg.Date)
+	if err != nil {
+		return fmt.Errorf("scan phase: %w", err)
+	}
+	fmt.Printf("Found %d events for camera %s\n\n", scanResult.EventCount, scanResult.Camera.Name)
+
+	if scanResult.EventCount == 0 {
+		fmt.Println("No events found for this day. Nothing to do.")
+		return nil
+	}
+
+	// Phase B: Fetch
+	fmt.Println("=== Phase 2: Downloading clips ===")
+	fetchResult, err := pipeline.Fetch(ctx, client, layout, pipeline.FetchConfig{
+		Workers: cfg.Workers,
+		Retries: cfg.Retries,
+	})
+	if err != nil {
+		return fmt.Errorf("fetch phase: %w", err)
+	}
+	fmt.Printf("Downloaded %d, skipped %d, failed %d\n\n",
+		fetchResult.Downloaded, fetchResult.Skipped, fetchResult.Failed)
+
+	// Phase C-E: Render (includes manifest and speed calculation)
+	fmt.Println("=== Phase 3: Rendering timelapse ===")
+	renderResult, err := pipeline.Render(ctx, layout, pipeline.RenderConfig{
+		TargetSecs:   cfg.TargetSecs,
+		FPS:          cfg.FPS,
+		CRF:          cfg.CRF,
+		Preset:       cfg.Preset,
+		MinSpeedMult: cfg.MinSpeedMult,
+		MaxSpeedMult: cfg.MaxSpeedMult,
+	})
+	if err != nil {
+		return fmt.Errorf("render phase: %w", err)
+	}
+
+	fmt.Println()
+	fmt.Println("=== Complete ===")
+	fmt.Printf("Output: %s\n", renderResult.OutputPath)
+	fmt.Printf("Duration: %.1f seconds (%.1fx speed)\n",
+		renderResult.OutputDuration, renderResult.SpeedFactor)
+
+	return nil
+}

@@ -0,0 +1,85 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/crash/upvs/internal/config"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/pipeline"
+	"github.com/crash/upvs/internal/protect"
+	"github.com/spf13/cobra"
+)
+
+var dateStr string
+
+var scanCmd = &cobra.Command{
+	Use:   "scan",
+	Short: "Enumerate events and create clip index",
+	Long:  "Scan a day's events from UniFi Protect and write clip_index.json.",
+	RunE:  runScan,
+}
+
+func init() {
+	scanCmd.Flags().StringVar(&dateStr, "date", "", "Target date YYYY-MM-DD (required)")
+	scanCmd.MarkFlagRequired("date")
+}
+
+func runScan(cmd *cobra.Command, args []string) error {
+	// Parse date
+	date, err := config.ParseDate(dateStr)
+	if err != nil {
+		return err
+	}
+	cfg.Date = date
+
+	// Validate required fields for scan
+	if cfg.Host == "" {
+		return config.ErrMissingHost
+	}
+	if cfg.Username == "" || cfg.Password == "" {
+		return config.ErrMissingCredentials
+	}
+	if cfg.Camera == "" {
+		return config.ErrMissingCamera
+	}
+	if cfg.OutDir == "" {
+		return config.ErrMissingOutDir
+	}
+
+	// Create layout and ensure directories
+	layout := output.NewLayout(cfg.OutDir, cfg.Camera, cfg.DateString())
+	err = layout.EnsureDirs()
+	if err != nil {
+		return err
+	}
+
+	// Create client
+	var opts []protect.ClientOption
+	if cfg.TLSInsecure {
+		opts = append(opts, protect.WithTLSInsecure())
+	}
+	if cfg.DirectAPI {
+		opts = append(opts, protect.WithDirectAPI())
+	}
+	client := protect.NewClient(cfg.Host, opts...)
+
+	// Login
+	ctx := context.Background()
+	err = client.Login(ctx, cfg.Username, cfg.Password)
+	if err != nil {
+		return fmt.Errorf("login: %w", err)
+	}
+
+	// Run scan
+	result, err := pipeline.Scan(ctx, client, layout, cfg.Camera, cfg.Date)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Scan complete: %d events for camera %s (%s)\n",
+		result.EventCount, result.Camera.Name, result.Camera.ID)
+	fmt.Printf("Clip index: %s\n", layout.ClipIndexPath())
+
+	return nil
+}

@@ -0,0 +1,129 @@
+// Package config defines the configuration for the upvs CLI.
+package config
+
+import (
+	"errors"
+	"fmt"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// Default values for configuration.
+const (
+	DefaultWorkers      = 4
+	DefaultRetries      = 3
+	DefaultTargetSecs   = 600 // 10 minutes
+	DefaultFPS          = 30
+	DefaultCRF          = 23
+	DefaultPreset       = "medium"
+	DefaultMinSpeedMult = 1.0
+	DefaultMaxSpeedMult = 2000.0
+)
+
+// Config holds all configuration for a pipeline run.
+type Config struct {
+	// Connection settings
+	Host        string
+	Username    string
+	Password    string
+	TLSInsecure bool
+	DirectAPI   bool // Use /api instead of /proxy/protect/api
+
+	// Target selection
+	Camera string
+	Date   time.Time
+
+	// Output settings
+	OutDir  string
+	Verbose bool
+
+	// Fetch settings
+	Workers int
+	Retries int
+
+	// Render settings
+	TargetSecs   int
+	FPS          int
+	CRF          int
+	Preset       string
+	MinSpeedMult float64
+	MaxSpeedMult float64
+}
+
+// New creates a Config with default values.
+func New() *Config {
+	return &Config{
+		Workers:      DefaultWorkers,
+		Retries:      DefaultRetries,
+		TargetSecs:   DefaultTargetSecs,
+		FPS:          DefaultFPS,
+		CRF:          DefaultCRF,
+		Preset:       DefaultPreset,
+		MinSpeedMult: DefaultMinSpeedMult,
+		MaxSpeedMult: DefaultMaxSpeedMult,
+	}
+}
+
+// Sentinel errors for configuration validation.
+var (
+	ErrMissingHost        = errors.New("host is required")
+	ErrMissingCredentials = errors.New("username and password are required")
+	ErrMissingCamera      = errors.New("camera is required")
+	ErrMissingDate        = errors.New("date is required")
+	ErrMissingOutDir      = errors.New("out directory is required")
+	ErrInvalidHost        = errors.New("invalid host URL")
+	ErrInvalidDate        = errors.New("invalid date format (expected YYYY-MM-DD)")
+)
+
+// Validate checks that all required fields are set and valid.
+func (c *Config) Validate() error {
+	if c.Host == "" {
+		return ErrMissingHost
+	}
+	_, err := url.Parse(c.Host)
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrInvalidHost, err)
+	}
+	if c.Username == "" || c.Password == "" {
+		return ErrMissingCredentials
+	}
+	if c.Camera == "" {
+		return ErrMissingCamera
+	}
+	if c.Date.IsZero() {
+		return ErrMissingDate
+	}
+	if c.OutDir == "" {
+		return ErrMissingOutDir
+	}
+	return nil
+}
+
+// LoadPasswordFromFile reads the password from a file if Password is empty.
+func (c *Config) LoadPasswordFromFile(path string) error {
+	if path == "" {
+		return nil
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("reading password-file: %w", err)
+	}
+	c.Password = strings.TrimSpace(string(data))
+	return nil
+}
+
+// ParseDate parses a date string in YYYY-MM-DD format.
+func ParseDate(s string) (time.Time, error) {
+	t, err := time.Parse("2006-01-02", s)
+	if err != nil {
+		return time.Time{}, ErrInvalidDate
+	}
+	return t, nil
+}
+
+// DateString returns the date formatted as YYYY-MM-DD.
+func (c *Config) DateString() string {
+	return c.Date.Format("2006-01-02")
+}

@@ -0,0 +1,132 @@
+package config
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestValidate(t *testing.T) {
+	validCfg := &Config{
+		Host:     "https://protect.local",
+		Username: "admin",
+		Password: "secret",
+		Camera:   "front-door",
+		Date:     time.Now(),
+		OutDir:   "/tmp/out",
+	}
+
+	err := validCfg.Validate()
+	if err != nil {
+		t.Errorf("expected valid config, got error: %v", err)
+	}
+}
+
+func TestValidate_MissingFields(t *testing.T) {
+	tests := []struct {
+		name     string
+		modify   func(*Config)
+		expected error
+	}{
+		{
+			name:     "missing host",
+			modify:   func(c *Config) { c.Host = "" },
+			expected: ErrMissingHost,
+		},
+		{
+			name:     "missing username",
+			modify:   func(c *Config) { c.Username = "" },
+			expected: ErrMissingCredentials,
+		},
+		{
+			name:     "missing password",
+			modify:   func(c *Config) { c.Password = "" },
+			expected: ErrMissingCredentials,
+		},
+		{
+			name:     "missing camera",
+			modify:   func(c *Config) { c.Camera = "" },
+			expected: ErrMissingCamera,
+		},
+		{
+			name:     "missing date",
+			modify:   func(c *Config) { c.Date = time.Time{} },
+			expected: ErrMissingDate,
+		},
+		{
+			name:     "missing out dir",
+			modify:   func(c *Config) { c.OutDir = "" },
+			expected: ErrMissingOutDir,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &Config{
+				Host:     "https://protect.local",
+				Username: "admin",
+				Password: "secret",
+				Camera:   "front-door",
+				Date:     time.Now(),
+				OutDir:   "/tmp/out",
+			}
+			tc.modify(cfg)
+
+			err := cfg.Validate()
+			if !errors.Is(err, tc.expected) {
+				t.Errorf("expected %v, got %v", tc.expected, err)
+			}
+		})
+	}
+}
+
+func TestParseDate(t *testing.T) {
+	tests := []struct {
+		input    string
+		valid    bool
+		expected string
+	}{
+		{"2024-01-15", true, "2024-01-15"},
+		{"2024-12-31", true, "2024-12-31"},
+		{"invalid", false, ""},
+		{"01-15-2024", false, ""},
+		{"2024/01/15", false, ""},
+	}
+
+	for _, tc := range tests {
+		result, err := ParseDate(tc.input)
+		if tc.valid {
+			if err != nil {
+				t.Errorf("ParseDate(%q) unexpected error: %v", tc.input, err)
+			}
+			if result.Format("2006-01-02") != tc.expected {
+				t.Errorf("ParseDate(%q) = %v, want %v", tc.input, result.Format("2006-01-02"), tc.expected)
+			}
+		} else {
+			if err == nil {
+				t.Errorf("ParseDate(%q) expected error, got nil", tc.input)
+			}
+		}
+	}
+}
+
+func TestLoadPasswordFromFile(t *testing.T) {
+	// Create temp file with password
+	dir := t.TempDir()
+	passFile := filepath.Join(dir, "password")
+	err := os.WriteFile(passFile, []byte("  my-secret-pass  \n"), 0600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := New()
+	err = cfg.LoadPasswordFromFile(passFile)
+	if err != nil {
+		t.Errorf("LoadPasswordFromFile error: %v", err)
+	}
+	if cfg.Password != "my-secret-pass" {
+		t.Errorf("expected 'my-secret-pass', got %q", cfg.Password)
+	}
+}

@@ -0,0 +1,35 @@
+// Package ffmpeg provides FFmpeg integration for timelapse generation.
+package ffmpeg
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// GenerateConcatFile creates an FFmpeg concat demuxer file.
+// Each path in the list is written as "file '<path>'" on its own line.
+// Paths are converted to absolute paths since ffmpeg's concat demuxer
+// resolves relative paths relative to the concat file's directory.
+func GenerateConcatFile(outputPath string, clipPaths []string) error {
+	var b strings.Builder
+
+	for _, path := range clipPaths {
+		// Convert to absolute path for ffmpeg concat demuxer
+		absPath, err := filepath.Abs(path)
+		if err != nil {
+			return fmt.Errorf("getting absolute path for %s: %w", path, err)
+		}
+		// Escape single quotes in path by replacing ' with '\''
+		escaped := strings.ReplaceAll(absPath, "'", "'\\''")
+		fmt.Fprintf(&b, "file '%s'\n", escaped)
+	}
+
+	err := os.WriteFile(outputPath, []byte(b.String()), 0644)
+	if err != nil {
+		return fmt.Errorf("writing concat file: %w", err)
+	}
+
+	return nil
+}

@@ -0,0 +1,90 @@
+package ffmpeg
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"strconv"
+)
+
+// RenderConfig holds FFmpeg rendering parameters.
+type RenderConfig struct {
+	ConcatFile   string
+	OutputPath   string
+	SpeedFactor  float64
+	FPS          int
+	CRF          int
+	Preset       string
+}
+
+// Render executes FFmpeg to create the timelapse.
+func Render(ctx context.Context, cfg RenderConfig) error {
+	// Build setpts filter for speed adjustment
+	// setpts=PTS/N makes video N times faster
+	setptsFilter := fmt.Sprintf("setpts=PTS/%s", strconv.FormatFloat(cfg.SpeedFactor, 'f', 6, 64))
+
+	args := []string{
+		"-f", "concat",
+		"-safe", "0",
+		"-i", cfg.ConcatFile,
+		"-vf", setptsFilter,
+		"-r", strconv.Itoa(cfg.FPS),
+		"-c:v", "libx264",
+		"-crf", strconv.Itoa(cfg.CRF),
+		"-preset", cfg.Preset,
+		"-pix_fmt", "yuv420p",
+		"-an", // No audio
+		"-y",  // Overwrite output
+		cfg.OutputPath,
+	}
+
+	cmd := exec.CommandContext(ctx, "ffmpeg", args...)
+
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("ffmpeg failed: %w\noutput: %s", err, string(output))
+	}
+
+	return nil
+}
+
+// Probe checks if a video file is valid using ffprobe.
+func Probe(ctx context.Context, path string) error {
+	args := []string{
+		"-v", "error",
+		"-show_entries", "format=duration",
+		"-of", "default=noprint_wrappers=1:nokey=1",
+		path,
+	}
+
+	cmd := exec.CommandContext(ctx, "ffprobe", args...)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("ffprobe failed: %w\noutput: %s", err, string(output))
+	}
+
+	return nil
+}
+
+// GetDuration returns the duration of a video file in seconds.
+func GetDuration(ctx context.Context, path string) (float64, error) {
+	args := []string{
+		"-v", "error",
+		"-show_entries", "format=duration",
+		"-of", "default=noprint_wrappers=1:nokey=1",
+		path,
+	}
+
+	cmd := exec.CommandContext(ctx, "ffprobe", args...)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return 0, fmt.Errorf("ffprobe failed: %w", err)
+	}
+
+	duration, err := strconv.ParseFloat(string(output[:len(output)-1]), 64)
+	if err != nil {
+		return 0, fmt.Errorf("parsing duration: %w", err)
+	}
+
+	return duration, nil
+}

@@ -0,0 +1,101 @@
+package manifest
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"time"
+)
+
+// NewClipIndex creates a new ClipIndex.
+func NewClipIndex(cameraID, cameraName, date string) *ClipIndex {
+	now := time.Now()
+	return &ClipIndex{
+		CameraID:   cameraID,
+		CameraName: cameraName,
+		Date:       date,
+		CreatedAt:  now,
+		UpdatedAt:  now,
+		Clips:      make([]*ClipEntry, 0),
+	}
+}
+
+// AddClip adds a clip entry to the index.
+func (ci *ClipIndex) AddClip(entry *ClipEntry) {
+	ci.Clips = append(ci.Clips, entry)
+	ci.UpdatedAt = time.Now()
+}
+
+// Sort orders clips by (start_ms, end_ms, event_id) for deterministic ordering.
+func (ci *ClipIndex) Sort() {
+	sort.Slice(ci.Clips, func(i, j int) bool {
+		a, b := ci.Clips[i], ci.Clips[j]
+		if a.StartMs != b.StartMs {
+			return a.StartMs < b.StartMs
+		}
+		if a.EndMs != b.EndMs {
+			return a.EndMs < b.EndMs
+		}
+		return a.EventID < b.EventID
+	})
+}
+
+// FindByEventID returns the clip entry with the given event ID, or nil.
+func (ci *ClipIndex) FindByEventID(eventID string) *ClipEntry {
+	for _, c := range ci.Clips {
+		if c.EventID == eventID {
+			return c
+		}
+	}
+	return nil
+}
+
+// Write saves the clip index to a JSON file.
+func (ci *ClipIndex) Write(path string) error {
+	ci.UpdatedAt = time.Now()
+	ci.Sort()
+
+	data, err := json.MarshalIndent(ci, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling clip index: %w", err)
+	}
+
+	err = os.WriteFile(path, data, 0644)
+	if err != nil {
+		return fmt.Errorf("writing clip index: %w", err)
+	}
+
+	return nil
+}
+
+// ReadClipIndex loads a clip index from a JSON file.
+func ReadClipIndex(path string) (*ClipIndex, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("reading clip index: %w", err)
+	}
+
+	var ci ClipIndex
+	err = json.Unmarshal(data, &ci)
+	if err != nil {
+		return nil, fmt.Errorf("parsing clip index: %w", err)
+	}
+
+	return &ci, nil
+}
+
+// WriteDayMetadata saves day metadata to a JSON file.
+func WriteDayMetadata(path string, meta *DayMetadata) error {
+	data, err := json.MarshalIndent(meta, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling day metadata: %w", err)
+	}
+
+	err = os.WriteFile(path, data, 0644)
+	if err != nil {
+		return fmt.Errorf("writing day metadata: %w", err)
+	}
+
+	return nil
+}

@@ -0,0 +1,94 @@
+// Package manifest defines types for tracking clip download state.
+package manifest
+
+import "time"
+
+// ClipStatus represents the download state of a clip.
+type ClipStatus string
+
+const (
+	StatusPending    ClipStatus = "pending"
+	StatusInProgress ClipStatus = "in_progress"
+	StatusComplete   ClipStatus = "complete"
+	StatusFailed     ClipStatus = "failed"
+	StatusSkipped    ClipStatus = "skipped"
+)
+
+// ClipEntry represents a single video clip from an event.
+type ClipEntry struct {
+	EventID     string     `json:"event_id"`
+	StartMs     int64      `json:"start_ms"`
+	EndMs       int64      `json:"end_ms"`
+	DurationMs  int64      `json:"duration_ms"`
+	EventType   string     `json:"event_type"`
+	SmartTypes  []string   `json:"smart_types,omitempty"`
+	Score       int        `json:"score"`
+	Status      ClipStatus `json:"status"`
+	FilePath    string     `json:"file_path,omitempty"`
+	FileSize    int64      `json:"file_size,omitempty"`
+	Error       string     `json:"error,omitempty"`
+	DownloadedAt *time.Time `json:"downloaded_at,omitempty"`
+}
+
+// DurationSecs returns the clip duration in seconds.
+func (c *ClipEntry) DurationSecs() float64 {
+	return float64(c.DurationMs) / 1000.0
+}
+
+// ClipIndex holds all clips for a day with metadata.
+type ClipIndex struct {
+	CameraID   string       `json:"camera_id"`
+	CameraName string       `json:"camera_name"`
+	Date       string       `json:"date"`
+	CreatedAt  time.Time    `json:"created_at"`
+	UpdatedAt  time.Time    `json:"updated_at"`
+	Clips      []*ClipEntry `json:"clips"`
+}
+
+// TotalDurationMs returns the sum of all clip durations in milliseconds.
+func (ci *ClipIndex) TotalDurationMs() int64 {
+	var total int64
+	for _, c := range ci.Clips {
+		total += c.DurationMs
+	}
+	return total
+}
+
+// TotalDurationSecs returns the sum of all clip durations in seconds.
+func (ci *ClipIndex) TotalDurationSecs() float64 {
+	return float64(ci.TotalDurationMs()) / 1000.0
+}
+
+// CompletedClips returns only clips with status Complete.
+func (ci *ClipIndex) CompletedClips() []*ClipEntry {
+	var completed []*ClipEntry
+	for _, c := range ci.Clips {
+		if c.Status == StatusComplete {
+			completed = append(completed, c)
+		}
+	}
+	return completed
+}
+
+// Stats returns counts by status.
+func (ci *ClipIndex) Stats() map[ClipStatus]int {
+	stats := make(map[ClipStatus]int)
+	for _, c := range ci.Clips {
+		stats[c.Status]++
+	}
+	return stats
+}
+
+// DayMetadata holds computed information about the day's timelapse.
+type DayMetadata struct {
+	CameraID      string    `json:"camera_id"`
+	CameraName    string    `json:"camera_name"`
+	Date          string    `json:"date"`
+	TotalClips    int       `json:"total_clips"`
+	ValidClips    int       `json:"valid_clips"`
+	TotalDuration float64   `json:"total_duration_secs"`
+	SpeedFactor   float64   `json:"speed_factor"`
+	TargetSecs    int       `json:"target_secs"`
+	OutputDuration float64  `json:"output_duration_secs"`
+	CreatedAt     time.Time `json:"created_at"`
+}

@@ -0,0 +1,116 @@
+// Package output manages the output directory structure.
+package output
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/crash/upvs/internal/sanitize"
+)
+
+// Layout manages paths within the output directory.
+type Layout struct {
+	root   string
+	camera string
+	date   string
+}
+
+// NewLayout creates a Layout for the given output directory, camera, and date.
+func NewLayout(outDir, camera, date string) *Layout {
+	return &Layout{
+		root:   outDir,
+		camera: sanitize.Filename(camera),
+		date:   date,
+	}
+}
+
+// EnsureDirs creates all required directories in the output structure.
+func (l *Layout) EnsureDirs() error {
+	dirs := []string{
+		l.MetadataDir(),
+		l.ClipsDir(),
+		l.ManifestsDir(),
+		l.TimelapseDir(),
+		l.LogsDir(),
+	}
+	for _, dir := range dirs {
+		err := os.MkdirAll(dir, 0755)
+		if err != nil {
+			return fmt.Errorf("creating directory %s: %w", dir, err)
+		}
+	}
+	return nil
+}
+
+// Root returns the root output directory.
+func (l *Layout) Root() string {
+	return l.root
+}
+
+// MetadataDir returns the path to the metadata directory.
+func (l *Layout) MetadataDir() string {
+	return filepath.Join(l.root, "metadata")
+}
+
+// CameraJSONPath returns the path to camera.json.
+func (l *Layout) CameraJSONPath() string {
+	return filepath.Join(l.MetadataDir(), "camera.json")
+}
+
+// DayJSONPath returns the path to day.json.
+func (l *Layout) DayJSONPath() string {
+	return filepath.Join(l.MetadataDir(), "day.json")
+}
+
+// ClipsDir returns the path to the clips directory for this camera/date.
+func (l *Layout) ClipsDir() string {
+	return filepath.Join(l.root, "clips", l.camera, l.date)
+}
+
+// ClipPath returns the path for a specific clip file.
+func (l *Layout) ClipPath(startMs, endMs int64, eventID string) string {
+	filename := fmt.Sprintf("clip_%d_%d_%s.mp4", startMs, endMs, sanitize.Filename(eventID))
+	return filepath.Join(l.ClipsDir(), filename)
+}
+
+// ClipPartialPath returns the path for a partial (in-progress) clip download.
+func (l *Layout) ClipPartialPath(startMs, endMs int64, eventID string) string {
+	return l.ClipPath(startMs, endMs, eventID) + ".partial"
+}
+
+// ManifestsDir returns the path to the manifests directory.
+func (l *Layout) ManifestsDir() string {
+	return filepath.Join(l.root, "manifests")
+}
+
+// ClipIndexPath returns the path to clip_index.json.
+func (l *Layout) ClipIndexPath() string {
+	return filepath.Join(l.ManifestsDir(), "clip_index.json")
+}
+
+// ConcatTxtPath returns the path to concat.txt for FFmpeg.
+func (l *Layout) ConcatTxtPath() string {
+	return filepath.Join(l.ManifestsDir(), "concat.txt")
+}
+
+// TimelapseDir returns the path to the timelapse output directory.
+func (l *Layout) TimelapseDir() string {
+	return filepath.Join(l.root, "timelapse")
+}
+
+// TimelapsePath returns the path to the final timelapse video.
+func (l *Layout) TimelapsePath() string {
+	filename := fmt.Sprintf("%s_%s_timelapse.mp4", l.camera, l.date)
+	return filepath.Join(l.TimelapseDir(), filename)
+}
+
+// LogsDir returns the path to the logs directory.
+func (l *Layout) LogsDir() string {
+	return filepath.Join(l.root, "logs")
+}
+
+// RunLogPath returns the path to run.log.
+func (l *Layout) RunLogPath() string {
+	return filepath.Join(l.LogsDir(), "run.log")
+}

@@ -0,0 +1,166 @@
+package pipeline
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"time"
+
+	"github.com/crash/upvs/internal/manifest"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/protect"
+	"github.com/crash/upvs/internal/retry"
+	"github.com/crash/upvs/internal/workerpool"
+)
+
+// FetchConfig holds configuration for the fetch phase.
+type FetchConfig struct {
+	Workers int
+	Retries int
+}
+
+// FetchResult holds the output of the fetch phase.
+type FetchResult struct {
+	Downloaded int
+	Skipped    int
+	Failed     int
+	Errors     []error
+}
+
+// Fetch downloads clips concurrently with retry support.
+func Fetch(ctx context.Context, client *protect.Client, layout *output.Layout, cfg FetchConfig) (*FetchResult, error) {
+	clipIndex, err := manifest.ReadClipIndex(layout.ClipIndexPath())
+	if err != nil {
+		return nil, fmt.Errorf("reading clip index: %w", err)
+	}
+
+	slog.Info("starting fetch",
+		slog.Int("clips", len(clipIndex.Clips)),
+		slog.Int("workers", cfg.Workers))
+
+	result := &FetchResult{}
+	tasks := make([]workerpool.Task, 0, len(clipIndex.Clips))
+	cameraID := clipIndex.CameraID
+
+	for _, clip := range clipIndex.Clips {
+		// Skip if already complete
+		if clip.Status == manifest.StatusComplete {
+			if fileExists(clip.FilePath) {
+				result.Skipped++
+				continue
+			}
+		}
+
+		task := func(ctx context.Context) error {
+			return downloadClip(ctx, client, cameraID, clip, cfg.Retries)
+		}
+		tasks = append(tasks, task)
+	}
+
+	if len(tasks) == 0 {
+		slog.Info("no clips to download")
+		return result, nil
+	}
+
+	pool := workerpool.New(cfg.Workers)
+	results := pool.RunWithProgress(ctx, tasks, func(completed, total int) {
+		slog.Info("fetch progress",
+			slog.Int("completed", completed),
+			slog.Int("total", total))
+	})
+
+	// Count results
+	for _, r := range results {
+		if r.Error != nil {
+			result.Failed++
+			result.Errors = append(result.Errors, r.Error)
+		} else {
+			result.Downloaded++
+		}
+	}
+
+	// Save updated clip index
+	err = clipIndex.Write(layout.ClipIndexPath())
+	if err != nil {
+		return result, fmt.Errorf("writing clip index: %w", err)
+	}
+
+	slog.Info("fetch complete",
+		slog.Int("downloaded", result.Downloaded),
+		slog.Int("skipped", result.Skipped),
+		slog.Int("failed", result.Failed))
+
+	return result, nil
+}
+
+func downloadClip(ctx context.Context, client *protect.Client, cameraID string, clip *manifest.ClipEntry, maxRetries int) error {
+	partialPath := clip.FilePath + ".partial"
+
+	// Clean up any existing partial file
+	os.Remove(partialPath)
+
+	clip.Status = manifest.StatusInProgress
+
+	retryCfg := retry.DefaultConfig()
+	retryCfg.MaxAttempts = maxRetries
+
+	err := retry.Do(ctx, retryCfg, func() error {
+		return doDownload(ctx, client, cameraID, clip, partialPath)
+	})
+
+	if err != nil {
+		clip.Status = manifest.StatusFailed
+		clip.Error = err.Error()
+		return fmt.Errorf("downloading clip (event_id=%s): %w", clip.EventID, err)
+	}
+
+	// Atomic rename
+	err = os.Rename(partialPath, clip.FilePath)
+	if err != nil {
+		clip.Status = manifest.StatusFailed
+		clip.Error = err.Error()
+		return fmt.Errorf("renaming clip (event_id=%s): %w", clip.EventID, err)
+	}
+
+	// Get file size
+	info, err := os.Stat(clip.FilePath)
+	if err == nil {
+		clip.FileSize = info.Size()
+	}
+
+	now := time.Now()
+	clip.DownloadedAt = &now
+	clip.Status = manifest.StatusComplete
+	clip.Error = ""
+
+	return nil
+}
+
+func doDownload(ctx context.Context, client *protect.Client, cameraID string, clip *manifest.ClipEntry, partialPath string) error {
+	f, err := os.Create(partialPath)
+	if err != nil {
+		return fmt.Errorf("creating file: %w", err)
+	}
+	defer f.Close()
+
+	err = client.DownloadClip(ctx, cameraID, clip.StartMs, clip.EndMs, f)
+	if err != nil {
+		return err
+	}
+
+	err = f.Sync()
+	if err != nil {
+		return fmt.Errorf("syncing file: %w", err)
+	}
+
+	return nil
+}
+
+func fileExists(path string) bool {
+	info, err := os.Stat(path)
+	if err != nil {
+		return false
+	}
+	return info.Size() > 0
+}

@@ -0,0 +1,85 @@
+package pipeline
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"github.com/crash/upvs/internal/ffmpeg"
+	"github.com/crash/upvs/internal/manifest"
+	"github.com/crash/upvs/internal/output"
+)
+
+// ManifestResult holds the output of the manifest phase.
+type ManifestResult struct {
+	ValidClips    int
+	TotalDuration float64 // seconds
+}
+
+// BuildManifest filters valid clips and generates the FFmpeg concat file.
+func BuildManifest(ctx context.Context, layout *output.Layout) (*ManifestResult, error) {
+	clipIndex, err := manifest.ReadClipIndex(layout.ClipIndexPath())
+	if err != nil {
+		return nil, fmt.Errorf("reading clip index: %w", err)
+	}
+
+	slog.Info("building manifest", slog.Int("total_clips", len(clipIndex.Clips)))
+
+	var validPaths []string
+	var totalDurationMs int64
+
+	for _, clip := range clipIndex.Clips {
+		if clip.Status != manifest.StatusComplete {
+			continue
+		}
+
+		// Verify file exists and is valid
+		if !fileExists(clip.FilePath) {
+			slog.Warn("clip file missing",
+				slog.String("event_id", clip.EventID),
+				slog.String("path", clip.FilePath))
+			continue
+		}
+
+		// Optionally verify with ffprobe
+		err := ffmpeg.Probe(ctx, clip.FilePath)
+		if err != nil {
+			slog.Warn("clip invalid",
+				slog.String("event_id", clip.EventID),
+				slog.String("error", err.Error()))
+			clip.Status = manifest.StatusFailed
+			clip.Error = "invalid video file"
+			continue
+		}
+
+		validPaths = append(validPaths, clip.FilePath)
+		totalDurationMs += clip.DurationMs
+	}
+
+	if len(validPaths) == 0 {
+		return nil, fmt.Errorf("no valid clips to render")
+	}
+
+	err = ffmpeg.GenerateConcatFile(layout.ConcatTxtPath(), validPaths)
+	if err != nil {
+		return nil, err
+	}
+
+	// Update clip index with any status changes
+	err = clipIndex.Write(layout.ClipIndexPath())
+	if err != nil {
+		return nil, err
+	}
+
+	totalDuration := float64(totalDurationMs) / 1000.0
+
+	slog.Info("manifest built",
+		slog.Int("valid_clips", len(validPaths)),
+		slog.Float64("total_duration_secs", totalDuration),
+		slog.String("concat_path", layout.ConcatTxtPath()))
+
+	return &ManifestResult{
+		ValidClips:    len(validPaths),
+		TotalDuration: totalDuration,
+	}, nil
+}

@@ -0,0 +1,114 @@
+package pipeline
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/crash/upvs/internal/ffmpeg"
+	"github.com/crash/upvs/internal/manifest"
+	"github.com/crash/upvs/internal/output"
+)
+
+// RenderConfig holds configuration for the render phase.
+type RenderConfig struct {
+	TargetSecs   int
+	FPS          int
+	CRF          int
+	Preset       string
+	MinSpeedMult float64
+	MaxSpeedMult float64
+}
+
+// DefaultRenderConfig returns default render configuration.
+func DefaultRenderConfig() RenderConfig {
+	return RenderConfig{
+		TargetSecs:   600,
+		FPS:          30,
+		CRF:          23,
+		Preset:       "medium",
+		MinSpeedMult: 1.0,
+		MaxSpeedMult: 2000.0,
+	}
+}
+
+// RenderResult holds the output of the render phase.
+type RenderResult struct {
+	OutputPath     string
+	SpeedFactor    float64
+	OutputDuration float64
+	Metadata       *manifest.DayMetadata
+}
+
+// Render executes FFmpeg to create the timelapse.
+func Render(ctx context.Context, layout *output.Layout, cfg RenderConfig) (*RenderResult, error) {
+	// Build manifest first
+	manifestResult, err := BuildManifest(ctx, layout)
+	if err != nil {
+		return nil, err
+	}
+
+	// Calculate speed
+	speedCfg := SpeedConfig{
+		TargetSecs:   cfg.TargetSecs,
+		MinSpeedMult: cfg.MinSpeedMult,
+		MaxSpeedMult: cfg.MaxSpeedMult,
+	}
+	speedFactor, outputDuration := CalculateSpeed(manifestResult.TotalDuration, speedCfg)
+
+	slog.Info("starting render",
+		slog.Float64("speed_factor", speedFactor),
+		slog.Float64("expected_duration", outputDuration),
+		slog.String("output", layout.TimelapsePath()))
+
+	// Run FFmpeg
+	ffmpegCfg := ffmpeg.RenderConfig{
+		ConcatFile:  layout.ConcatTxtPath(),
+		OutputPath:  layout.TimelapsePath(),
+		SpeedFactor: speedFactor,
+		FPS:         cfg.FPS,
+		CRF:         cfg.CRF,
+		Preset:      cfg.Preset,
+	}
+
+	err = ffmpeg.Render(ctx, ffmpegCfg)
+	if err != nil {
+		return nil, fmt.Errorf("rendering timelapse: %w", err)
+	}
+
+	// Read clip index to get camera info
+	clipIndex, err := manifest.ReadClipIndex(layout.ClipIndexPath())
+	if err != nil {
+		return nil, fmt.Errorf("reading clip index: %w", err)
+	}
+
+	// Save day metadata
+	dayMeta := &manifest.DayMetadata{
+		CameraID:       clipIndex.CameraID,
+		CameraName:     clipIndex.CameraName,
+		Date:           clipIndex.Date,
+		TotalClips:     len(clipIndex.Clips),
+		ValidClips:     manifestResult.ValidClips,
+		TotalDuration:  manifestResult.TotalDuration,
+		SpeedFactor:    speedFactor,
+		TargetSecs:     cfg.TargetSecs,
+		OutputDuration: outputDuration,
+		CreatedAt:      time.Now(),
+	}
+
+	err = manifest.WriteDayMetadata(layout.DayJSONPath(), dayMeta)
+	if err != nil {
+		return nil, err
+	}
+
+	slog.Info("render complete",
+		slog.String("output", layout.TimelapsePath()))
+
+	return &RenderResult{
+		OutputPath:     layout.TimelapsePath(),
+		SpeedFactor:    speedFactor,
+		OutputDuration: outputDuration,
+		Metadata:       dayMeta,
+	}, nil
+}

@@ -0,0 +1,103 @@
+// Package pipeline implements the timelapse generation phases.
+package pipeline
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"time"
+
+	"github.com/crash/upvs/internal/manifest"
+	"github.com/crash/upvs/internal/output"
+	"github.com/crash/upvs/internal/protect"
+)
+
+// ScanResult holds the output of the scan phase.
+type ScanResult struct {
+	Camera     *protect.Camera
+	ClipIndex  *manifest.ClipIndex
+	EventCount int
+}
+
+// Scan enumerates events for a day and creates the clip index.
+func Scan(ctx context.Context, client *protect.Client, layout *output.Layout, cameraRef string, date time.Time) (*ScanResult, error) {
+	slog.Info("resolving camera", slog.String("camera", cameraRef))
+
+	camera, err := client.ResolveCamera(ctx, cameraRef)
+	if err != nil {
+		return nil, fmt.Errorf("resolving camera: %w", err)
+	}
+
+	slog.Info("camera resolved",
+		slog.String("id", camera.ID),
+		slog.String("name", camera.Name))
+
+	// Save camera info
+	err = writeCameraJSON(layout.CameraJSONPath(), camera)
+	if err != nil {
+		return nil, err
+	}
+
+	slog.Info("fetching events",
+		slog.String("camera_id", camera.ID),
+		slog.String("date", date.Format("2006-01-02")))
+
+	events, err := client.ListDayEvents(ctx, camera.ID, date)
+	if err != nil {
+		return nil, fmt.Errorf("listing events: %w", err)
+	}
+
+	slog.Info("events found", slog.Int("count", len(events)))
+
+	// Build clip index
+	dateStr := date.Format("2006-01-02")
+	clipIndex := manifest.NewClipIndex(camera.ID, camera.Name, dateStr)
+
+	for _, event := range events {
+		entry := &manifest.ClipEntry{
+			EventID:    event.ID,
+			StartMs:    event.Start,
+			EndMs:      event.End,
+			DurationMs: event.End - event.Start,
+			EventType:  event.Type,
+			SmartTypes: event.SmartTypes,
+			Score:      event.Score,
+			Status:     manifest.StatusPending,
+			FilePath:   layout.ClipPath(event.Start, event.End, event.ID),
+		}
+		clipIndex.AddClip(entry)
+	}
+
+	clipIndex.Sort()
+
+	err = clipIndex.Write(layout.ClipIndexPath())
+	if err != nil {
+		return nil, err
+	}
+
+	slog.Info("clip index written",
+		slog.String("path", layout.ClipIndexPath()),
+		slog.Int("clips", len(clipIndex.Clips)))
+
+	return &ScanResult{
+		Camera:     camera,
+		ClipIndex:  clipIndex,
+		EventCount: len(events),
+	}, nil
+}
+
+func writeCameraJSON(path string, camera *protect.Camera) error {
+	data, err := json.MarshalIndent(camera, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling camera: %w", err)
+	}
+
+	err = os.WriteFile(path, data, 0644)
+	if err != nil {
+		return fmt.Errorf("writing camera.json: %w", err)
+	}
+
+	return nil
+}

@@ -0,0 +1,53 @@
+package pipeline
+
+import (
+	"log/slog"
+)
+
+// SpeedConfig holds parameters for speed calculation.
+type SpeedConfig struct {
+	TargetSecs   int     // Target output duration (default 600 = 10 min)
+	MinSpeedMult float64 // Minimum speed multiplier (default 1.0)
+	MaxSpeedMult float64 // Maximum speed multiplier (default 2000.0)
+}
+
+// DefaultSpeedConfig returns default speed configuration.
+func DefaultSpeedConfig() SpeedConfig {
+	return SpeedConfig{
+		TargetSecs:   600,
+		MinSpeedMult: 1.0,
+		MaxSpeedMult: 2000.0,
+	}
+}
+
+// CalculateSpeed computes the speed factor to achieve target duration.
+// Returns the clamped speed factor and expected output duration.
+func CalculateSpeed(totalDurationSecs float64, cfg SpeedConfig) (speedFactor float64, outputDuration float64) {
+	if totalDurationSecs <= 0 {
+		return cfg.MinSpeedMult, 0
+	}
+
+	targetDuration := float64(cfg.TargetSecs)
+
+	// speed = total / target
+	speedFactor = totalDurationSecs / targetDuration
+
+	// Clamp to allowed range
+	if speedFactor < cfg.MinSpeedMult {
+		speedFactor = cfg.MinSpeedMult
+	}
+	if speedFactor > cfg.MaxSpeedMult {
+		speedFactor = cfg.MaxSpeedMult
+	}
+
+	// Calculate actual output duration with clamped speed
+	outputDuration = totalDurationSecs / speedFactor
+
+	slog.Info("speed calculated",
+		slog.Float64("total_duration_secs", totalDurationSecs),
+		slog.Int("target_secs", cfg.TargetSecs),
+		slog.Float64("speed_factor", speedFactor),
+		slog.Float64("output_duration_secs", outputDuration))
+
+	return speedFactor, outputDuration
+}

@@ -0,0 +1,81 @@
+package pipeline
+
+import (
+	"math"
+	"testing"
+)
+
+func TestCalculateSpeed(t *testing.T) {
+	tests := []struct {
+		name           string
+		totalDuration  float64
+		cfg            SpeedConfig
+		expectedSpeed  float64
+		expectedOutput float64
+	}{
+		{
+			name:          "exact target",
+			totalDuration: 6000, // 100 minutes
+			cfg: SpeedConfig{
+				TargetSecs:   600,
+				MinSpeedMult: 1.0,
+				MaxSpeedMult: 2000.0,
+			},
+			expectedSpeed:  10.0,
+			expectedOutput: 600.0,
+		},
+		{
+			name:          "less than target",
+			totalDuration: 300, // 5 minutes
+			cfg: SpeedConfig{
+				TargetSecs:   600,
+				MinSpeedMult: 1.0,
+				MaxSpeedMult: 2000.0,
+			},
+			expectedSpeed:  1.0, // Clamped to min
+			expectedOutput: 300.0,
+		},
+		{
+			name:          "very long duration",
+			totalDuration: 86400, // 24 hours
+			cfg: SpeedConfig{
+				TargetSecs:   600,
+				MinSpeedMult: 1.0,
+				MaxSpeedMult: 2000.0,
+			},
+			expectedSpeed:  144.0, // 86400 / 600
+			expectedOutput: 600.0,
+		},
+		{
+			name:          "exceeds max speed",
+			totalDuration: 2000000, // Very long
+			cfg: SpeedConfig{
+				TargetSecs:   600,
+				MinSpeedMult: 1.0,
+				MaxSpeedMult: 100.0,
+			},
+			expectedSpeed:  100.0, // Clamped to max
+			expectedOutput: 20000.0,
+		},
+		{
+			name:          "zero duration",
+			totalDuration: 0,
+			cfg:           DefaultSpeedConfig(),
+			expectedSpeed: 1.0,
+			expectedOutput: 0,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			speed, output := CalculateSpeed(tc.totalDuration, tc.cfg)
+
+			if math.Abs(speed-tc.expectedSpeed) > 0.001 {
+				t.Errorf("speed = %v, want %v", speed, tc.expectedSpeed)
+			}
+			if math.Abs(output-tc.expectedOutput) > 0.001 {
+				t.Errorf("output duration = %v, want %v", output, tc.expectedOutput)
+			}
+		})
+	}
+}

@@ -0,0 +1,63 @@
+package protect
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+// Bootstrap fetches system information including all cameras.
+func (c *Client) Bootstrap(ctx context.Context) (*BootstrapResponse, error) {
+	req, err := c.newRequest(ctx, "GET", "/bootstrap", nil)
+	if err != nil {
+		return nil, fmt.Errorf("creating request: %w", err)
+	}
+
+	var resp BootstrapResponse
+	err = c.doJSON(req, &resp)
+	if err != nil {
+		return nil, fmt.Errorf("fetching bootstrap: %w", err)
+	}
+	return &resp, nil
+}
+
+// ResolveCamera finds a camera by ID or name.
+// If the input matches a camera ID exactly, that camera is returned.
+// Otherwise, it searches by name (case-insensitive partial match).
+// Returns ErrCameraNotFound if no match, ErrMultipleCameras if ambiguous.
+func (c *Client) ResolveCamera(ctx context.Context, idOrName string) (*Camera, error) {
+	bootstrap, err := c.Bootstrap(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// First try exact ID match
+	for i := range bootstrap.Cameras {
+		if bootstrap.Cameras[i].ID == idOrName {
+			return &bootstrap.Cameras[i], nil
+		}
+	}
+
+	// Then try name match (case-insensitive)
+	var matches []*Camera
+	searchLower := strings.ToLower(idOrName)
+	for i := range bootstrap.Cameras {
+		nameLower := strings.ToLower(bootstrap.Cameras[i].Name)
+		if nameLower == searchLower || strings.Contains(nameLower, searchLower) {
+			matches = append(matches, &bootstrap.Cameras[i])
+		}
+	}
+
+	switch len(matches) {
+	case 0:
+		return nil, fmt.Errorf("%w: %s", ErrCameraNotFound, idOrName)
+	case 1:
+		return matches[0], nil
+	default:
+		names := make([]string, len(matches))
+		for i, cam := range matches {
+			names[i] = fmt.Sprintf("%s (%s)", cam.Name, cam.ID)
+		}
+		return nil, fmt.Errorf("%w: %s matches: %s", ErrMultipleCameras, idOrName, strings.Join(names, ", "))
+	}
+}

@@ -0,0 +1,208 @@
+package protect
+
+import (
+	"bytes"
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/cookiejar"
+	"time"
+)
+
+// Sentinel errors for API operations.
+var (
+	ErrUnauthorized    = errors.New("unauthorized: invalid credentials")
+	ErrNotFound        = errors.New("resource not found")
+	ErrRateLimited     = errors.New("rate limited")
+	ErrServerError     = errors.New("server error")
+	ErrCameraNotFound  = errors.New("camera not found")
+	ErrMultipleCameras = errors.New("multiple cameras match name")
+	ErrNotLoggedIn     = errors.New("not logged in: call Login() first")
+)
+
+// Client is a UniFi Protect API client.
+type Client struct {
+	baseURL    string
+	apiPath    string // "/proxy/protect/api" or "/api"
+	csrfToken  string
+	loggedIn   bool
+	httpClient *http.Client
+}
+
+// ClientOption configures a Client.
+type ClientOption func(*Client)
+
+// WithTLSInsecure disables TLS certificate verification.
+func WithTLSInsecure() ClientOption {
+	return func(c *Client) {
+		if c.httpClient.Transport == nil {
+			c.httpClient.Transport = &http.Transport{}
+		}
+		if t, ok := c.httpClient.Transport.(*http.Transport); ok {
+			t.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
+		}
+	}
+}
+
+// WithTimeout sets the HTTP client timeout.
+func WithTimeout(d time.Duration) ClientOption {
+	return func(c *Client) {
+		c.httpClient.Timeout = d
+	}
+}
+
+// WithDirectAPI uses /api path instead of /proxy/protect/api.
+// Use this when connecting directly to a Protect NVR/Cloud Key
+// rather than through UniFi OS gateway.
+func WithDirectAPI() ClientOption {
+	return func(c *Client) {
+		c.apiPath = "/api"
+	}
+}
+
+// NewClient creates a new UniFi Protect API client.
+func NewClient(baseURL string, opts ...ClientOption) *Client {
+	jar, _ := cookiejar.New(nil)
+	c := &Client{
+		baseURL: baseURL,
+		apiPath: "/proxy/protect/api", // Default for UniFi OS
+		httpClient: &http.Client{
+			Timeout: 30 * time.Second,
+			Jar:     jar,
+		},
+	}
+	for _, opt := range opts {
+		opt(c)
+	}
+	return c
+}
+
+// APIPath returns the current API path prefix.
+func (c *Client) APIPath() string {
+	return c.apiPath
+}
+
+// Login authenticates with UniFi Protect using username/password.
+// This obtains a session cookie that will be used for subsequent requests.
+func (c *Client) Login(ctx context.Context, username, password string) error {
+	creds := map[string]any{
+		"username":   username,
+		"password":   password,
+		"rememberMe": false,
+		"token":      "",
+	}
+	body, err := json.Marshal(creds)
+	if err != nil {
+		return fmt.Errorf("encoding credentials: %w", err)
+	}
+
+	url := c.baseURL + "/api/auth/login"
+	req, err := http.NewRequestWithContext(ctx, "POST", url, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("creating login request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	slog.Debug("http request",
+		slog.String("method", req.Method),
+		slog.String("url", req.URL.String()))
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("login request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	slog.Debug("http response",
+		slog.Int("status", resp.StatusCode))
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		slog.Debug("login response body", slog.String("body", string(respBody)))
+		if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+			return fmt.Errorf("%w: %s", ErrUnauthorized, string(respBody))
+		}
+		return fmt.Errorf("login failed with status %d: %s", resp.StatusCode, string(respBody))
+	}
+
+	// Extract CSRF token from response header
+	if token := resp.Header.Get("X-Csrf-Token"); token != "" {
+		c.csrfToken = token
+		slog.Debug("obtained CSRF token")
+	}
+
+	c.loggedIn = true
+	slog.Debug("login successful")
+	return nil
+}
+
+// newRequest creates an HTTP request with session cookies and CSRF token.
+// The path should be relative (e.g., "/bootstrap", not "/api/bootstrap").
+func (c *Client) newRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error) {
+	url := c.baseURL + c.apiPath + path
+	req, err := http.NewRequestWithContext(ctx, method, url, body)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if c.csrfToken != "" {
+		req.Header.Set("X-Csrf-Token", c.csrfToken)
+	}
+	return req, nil
+}
+
+// do executes a request and handles common error responses.
+func (c *Client) do(req *http.Request) (*http.Response, error) {
+	slog.Debug("http request",
+		slog.String("method", req.Method),
+		slog.String("url", req.URL.String()))
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+
+	slog.Debug("http response",
+		slog.Int("status", resp.StatusCode))
+
+	switch resp.StatusCode {
+	case http.StatusOK, http.StatusPartialContent:
+		return resp, nil
+	case http.StatusUnauthorized, http.StatusForbidden:
+		resp.Body.Close()
+		return nil, ErrUnauthorized
+	case http.StatusNotFound:
+		resp.Body.Close()
+		return nil, ErrNotFound
+	case http.StatusTooManyRequests:
+		resp.Body.Close()
+		return nil, ErrRateLimited
+	default:
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		resp.Body.Close()
+		if resp.StatusCode >= 500 {
+			return nil, fmt.Errorf("%w: %d: %s", ErrServerError, resp.StatusCode, string(body))
+		}
+		return nil, fmt.Errorf("unexpected status %d: %s", resp.StatusCode, string(body))
+	}
+}
+
+// doJSON executes a request and decodes the JSON response.
+func (c *Client) doJSON(req *http.Request, v any) error {
+	resp, err := c.do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	err = json.NewDecoder(resp.Body).Decode(v)
+	if err != nil {
+		return fmt.Errorf("decoding response: %w", err)
+	}
+	return nil
+}