BlitzReels

Build the closest honest personal substitute for BlitzReels in an empty repository.
Use exactly Node.js 22, TypeScript, React, Remotion, SQLite, FFmpeg, and the OpenAI API.
Run as a single-user local web app with one documented command.
The core loop is import one user-owned long video, transcribe it, rank five clip candidates, edit one, and export 9:16 MP4.
Preserve the original file and store projects, transcripts, candidates, and edits in SQLite.
Use ffprobe for duration and stream metadata before accepting a file.
Extract audio with FFmpeg and transcribe it with word timestamps.
Ask a text model for five 30 to 90 second candidates with exact boundaries, titles, hooks, and reasons.
Reject overlapping or out-of-range candidates and show the model output as suggestions, never facts.
Let the user adjust in and out points, edit caption text, and preview the vertical composition.
Use a static center crop with a manual horizontal offset; do not claim subject tracking.
Render burned captions from verified word timings with one readable style.
Export through Remotion to a new file and never overwrite source media.
Show import, probing, transcription, analysis, preview, rendering, success, and recoverable failure states.
Persist job state so an interrupted transcription or render can be retried safely.
Put the OpenAI key in .env, ship .env.example, and never log secrets or transcript contents.
Add safe filenames, upload size limits, input validation, and explicit local data deletion.
Write focused tests for time-range validation, candidate overlap, caption grouping, and project persistence.
Add one end-to-end smoke test using a tiny generated video fixture.
Create a README with setup, FFmpeg installation, architecture, data location, costs, backup, and limitations.
Deliberately exclude smart reframing, B-roll generation, voice isolation, silence cleanup, and a complete multitrack NLE.
Deliberately exclude the public API, CLI, agent integrations, accounts, teams, cloud rendering, share pages, and social publishing.
Do not call this a BlitzReels clone; label it a narrow local clip finder and exporter.
Run the tests and a real sample render before finishing, then report the exact commands and output path.

# AGENTS.md — Build guide for BlitzReels

## Project scope
Import one long video, transcribe it, rank clip candidates, let the user adjust boundaries and captions, then export a 9:16 MP4.

Catalogue verdict: no. A toy clip finder is a one-session build. A credible BlitzReels replacement is not: the product combines reliable long-video ingestion, timestamp-accurate AI selection, smart reframing, a complete nonlinear editor, browser preview and export parity, public API and CLI contracts, agent integrations, storage, and render orchestration. Its founder reports that the production system took a year even with prior Remotion experience and paid templates.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node.js 22
- FFmpeg and ffprobe
- OpenAI API key in .env
- local disk space for source and rendered media

## Stack and architecture
- Use exactly Node.js 22, TypeScript, React, Remotion, SQLite, FFmpeg, and the OpenAI API.
- Preserve the original file and store projects, transcripts, candidates, and edits in SQLite.
- Interface for this AI video repurposing and nonlinear video editing workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Show import, probing, transcription, analysis, preview, rendering, success, and recoverable failure states.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: reliable ingestion and recovery for large or malformed recordings.

## Agent implementation rules
- Project rule, data: Preserve the original file and store projects, transcripts, candidates, and edits in SQLite.
- Project rule, behavior: Run as a single-user local web app with one documented command.
- Project rule, recovery: Show import, probing, transcription, analysis, preview, rendering, success, and recoverable failure states.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this AI video repurposing and nonlinear video editing operation with sample or user-owned data: Run as a single-user local web app with one documented command.
- Show a concrete result or export: Export through Remotion to a new file and never overwrite source media.
- State the practical limit: reliable ingestion and recovery for large or malformed recordings.

## Engineering roadmap
1. Phase 1, architecture and data: Use exactly Node.js 22, TypeScript, React, Remotion, SQLite, FFmpeg, and the OpenAI API. Preserve the original file and store projects, transcripts, candidates, and edits in SQLite.
2. Phase 2, implement: Run as a single-user local web app with one documented command.
3. Phase 3, implement: Render burned captions from verified word timings with one readable style.
4. Phase 4, review and output: Export through Remotion to a new file and never overwrite source media.
5. Phase 5, recovery and acceptance: Show import, probing, transcription, analysis, preview, rendering, success, and recoverable failure states. Verify this invariant with a saved fixture: The original hash must remain unchanged; cuts and captions must stay aligned after export despite a variable input frame rate. State the practical limit: reliable ingestion and recovery for large or malformed recordings.

## Paid-product capabilities outside this build
- reliable ingestion and recovery for large or malformed recordings
- production-tuned clip selection and timestamp alignment
- subject-aware speaker and screen reframing
- complete NLE, caption styles, paid templates, and keyframed timeline editing
- public API, CLI, agent integrations, cloud rendering, retries, and share workflows

## Implementation prompt
Build the closest honest personal substitute for BlitzReels in an empty repository.
Use exactly Node.js 22, TypeScript, React, Remotion, SQLite, FFmpeg, and the OpenAI API.
Run as a single-user local web app with one documented command.
The core loop is import one user-owned long video, transcribe it, rank five clip candidates, edit one, and export 9:16 MP4.
Preserve the original file and store projects, transcripts, candidates, and edits in SQLite.
Use ffprobe for duration and stream metadata before accepting a file.
Extract audio with FFmpeg and transcribe it with word timestamps.
Ask a text model for five 30 to 90 second candidates with exact boundaries, titles, hooks, and reasons.
Reject overlapping or out-of-range candidates and show the model output as suggestions, never facts.
Let the user adjust in and out points, edit caption text, and preview the vertical composition.
Use a static center crop with a manual horizontal offset; do not claim subject tracking.
Render burned captions from verified word timings with one readable style.
Export through Remotion to a new file and never overwrite source media.
Show import, probing, transcription, analysis, preview, rendering, success, and recoverable failure states.
Persist job state so an interrupted transcription or render can be retried safely.
Put the OpenAI key in .env, ship .env.example, and never log secrets or transcript contents.
Add safe filenames, upload size limits, input validation, and explicit local data deletion.
Write focused tests for time-range validation, candidate overlap, caption grouping, and project persistence.
Add one end-to-end smoke test using a tiny generated video fixture.
Create a README with setup, FFmpeg installation, architecture, data location, costs, backup, and limitations.
Deliberately exclude smart reframing, B-roll generation, voice isolation, silence cleanup, and a complete multitrack NLE.
Deliberately exclude the public API, CLI, agent integrations, accounts, teams, cloud rendering, share pages, and social publishing.
Do not call this a BlitzReels clone; label it a narrow local clip finder and exporter.
Run the tests and a real sample render before finishing, then report the exact commands and output path.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.