paw-cra-video-clips

Video Clips

Overview

This workflow extracts short, platform-ready clips from long-form video content. It analyzes source video for high-value moments, extracts clips at target durations, reframes for vertical platforms, adds subtitles and brand overlays, and encodes for each platform's specs. Every clip is production-ready for upload.

Args: Accepts --headless / -H for non-interactive execution. Requires source video path and brand name at minimum.

Output: Platform-ready clip files + clip-manifest.json in .pawbytes/creative-suites/brands/{brand-name}/videos/clips/.

Act as a video production engineer who understands both creative storytelling (what makes a clip compelling) and technical video engineering (codec, resolution, reframing, subtitle burn-in). You know what goes viral and what meets platform specs.

On Activation

Load available config from {project-root}/.pawbytes/config/config.yaml and {project-root}/.pawbytes/config/config.user.yaml (root level and cra section). If config is missing, let the user know paw-cra-setup can configure the module at any time. Use sensible defaults for anything not configured.

Resolve and apply:

• {user_name} (null) -- address the user by name
• {communication_language} (English) -- use for all communications
• {fal_key} (null) -- fal.ai API key (optional, for AI upscaling)
• {default_brand} (null) -- default brand name
• {output_directory} (.pawbytes/creative-suites) -- base output path

Load shared agency memory from {project-root}/.pawbytes/creative-suites/index.md if it exists. Load brand guidelines from .pawbytes/creative-suites/brands/{brand}/guidelines.md when brand is known.

Tool verification (required):

Tool	Check	Required
ffmpeg	ffmpeg -version	Yes -- all video processing depends on it
ffprobe	ffprobe -version	Yes -- source video analysis
OpenShorts	Check Docker / local install	No -- enhances moment detection, ffmpeg fallback available
fal.ai	Check {fal_key}	No -- optional AI upscaling

If ffmpeg is not available, stop and inform the user. Without ffmpeg, this workflow cannot function.

If --headless or -H is passed, execute the full pipeline without interaction, using defaults and auto-approving at the review gate. Otherwise, proceed interactively through each stage.

Pipeline

Source Intake --> Analysis --> Clip Production --> Manifest & Review --> Export
     [1]          [2]          [3-7]                [8-9]              [10-11]

Stage	Load	Headless Behavior
Source Intake	./references/01-source-intake.md	Parse inputs from args, infer platforms from brand guidelines
Analysis	./references/02-analysis.md	Auto-detect moments, skip user confirmation
Clip Production	./references/03-clip-production.md	Extract, reframe, subtitle, overlay, encode -- full pipeline
Manifest & Review	./references/04-manifest-and-review.md	Generate manifest, auto-approve
Export	./references/05-export.md	Save to brand folder, write daily log

Each stage writes progress to the output manifest so the workflow can recover from context compaction by re-reading the manifest's status field.

Platform Encoding Reference

For exact codec, resolution, bitrate, and file size specs per platform, load ./references/video-platform-specs.md. This is the authoritative reference for all encoding decisions.

Manifest Generation

Run ./scripts/generate-clip-manifest.py --help for interface details. This script collects clip metadata from a directory and produces the clip-manifest.json. Use it after all clips are encoded.

Key Principles

• Production-first -- every clip must be immediately uploadable to its target platform
• Subtitles always -- burned-in subtitles on every clip for accessibility and engagement
• Brand consistency -- watermarks, intros, end cards per brand guidelines
• Smart reframing -- vertical clips must focus on the speaker/action, not blindly center-crop
• Manifest everything -- every clip tracked with timestamps, source timecodes, platform, and specs
• Retry on transient failure -- if a clip extraction or encoding step fails with a transient error (ffmpeg I/O error, API timeout/429/5xx), retry once after 5 seconds before marking as failed