Subclip

Build me the closest honest personal substitute for Subclip, not a platform clone. Requirements:

- Use Python 3.12 + FastAPI for a localhost web app, with a plain JavaScript frontend,
  FFmpeg for media work, and faster-whisper for word-level transcription.
- I can import MP4, MOV, WebM, MP3, or WAV files, see a synced transcript beside the
  video preview, and click any word to seek to its timestamp.
- Deleting transcript ranges creates an undoable cut list. Detect silences longer than
  500 ms and let me accept or reject each suggested cut before rendering.
- Let me edit subtitle text and timing, import or export SRT, and apply one ASS style
  file with font, colors, outline, position, and words-per-line controls.
- Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the
  source, and show FFmpeg progress plus a useful failure message.
- Store projects as JSON under ~/SubclipDIY/projects and renders under
  ~/SubclipDIY/exports, with a recent-projects page and a delete-project action.
- Bind to localhost only. No accounts, uploads, telemetry, or network calls after the
  faster-whisper model has been downloaded.
- Deliberately exclude ONNX models in the browser, Remotion client or server rendering,
  native apps, cloud dubbing, render queues, publishing, an MCP server, and public APIs.
- Add unit tests for cut-list merging and subtitle grouping, plus one smoke test that
  imports a short fixture and produces a playable MP4.
- Include a README with setup for Python and FFmpeg, model-size guidance, data paths,
  supported formats, and an honest warning about CPU transcription and render speed.

# AGENTS.md — Build guide for Subclip

## Project scope
Build only the closest consolation: import a video, transcribe it locally, cut by editing the transcript or removing silence, style subtitles, and export an MP4 and SRT.

Catalogue verdict: no. Subclip is not a realistic vibe-coded replacement. A narrow transcript cutter is buildable, but the product is a multi-surface post-production system: ONNX models running locally in the browser, client-side and server-side Remotion rendering, cloud AI and media jobs, native macOS and iOS experiences, plus an MCP server and developer APIs. Reproducing and operating those surfaces is a platform project, not a one-shot build.
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
- Python 3.12
- FFmpeg
- faster-whisper
- desktop with enough storage for source media and renders
- GPU optional

## Stack and architecture
- Use Python 3.12 + FastAPI for a localhost web app, with a plain JavaScript frontend, FFmpeg for media work, and faster-whisper for word-level transcription.
- Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Interface for this AI post-production platform workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: ONNX model packaging and hardware-accelerated in-browser inference.

## Agent implementation rules
- Project rule, data: Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Project rule, behavior: Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message.
- Project rule, recovery: Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message.

## 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 post-production platform operation with sample or user-owned data: Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message.
- Show a concrete result or export: Let me edit subtitle text and timing, import or export SRT, and apply one ASS style file with font, colors, outline, position, and words-per-line controls.
- State the practical limit: ONNX model packaging and hardware-accelerated in-browser inference.

## Engineering roadmap
1. Phase 1, architecture and data: Use Python 3.12 + FastAPI for a localhost web app, with a plain JavaScript frontend, FFmpeg for media work, and faster-whisper for word-level transcription. Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
2. Phase 2, implement: Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message.
3. Phase 3, implement: Store projects as JSON under ~/SubclipDIY/projects and renders under ~/SubclipDIY/exports, with a recent-projects page and a delete-project action.
4. Phase 4, review and output: Add unit tests for cut-list merging and subtitle grouping, plus one smoke test that imports a short fixture and produces a playable MP4. Let me edit subtitle text and timing, import or export SRT, and apply one ASS style file with font, colors, outline, position, and words-per-line controls.
5. Phase 5, recovery and acceptance: Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the source, and show FFmpeg progress plus a useful failure message. 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: ONNX model packaging and hardware-accelerated in-browser inference.

## Paid-product capabilities outside this build
- ONNX model packaging and hardware-accelerated in-browser inference
- coordinated client-side and server-side Remotion rendering
- native macOS and iOS apps and their release pipelines
- production dubbing, voice cloning, storage, and render queues
- MCP server, developer APIs, NLE exports, and publishing integrations

## Implementation prompt
Build me the closest honest personal substitute for Subclip, not a platform clone. Requirements:

- Use Python 3.12 + FastAPI for a localhost web app, with a plain JavaScript frontend,
  FFmpeg for media work, and faster-whisper for word-level transcription.
- I can import MP4, MOV, WebM, MP3, or WAV files, see a synced transcript beside the
  video preview, and click any word to seek to its timestamp.
- Deleting transcript ranges creates an undoable cut list. Detect silences longer than
  500 ms and let me accept or reject each suggested cut before rendering.
- Let me edit subtitle text and timing, import or export SRT, and apply one ASS style
  file with font, colors, outline, position, and words-per-line controls.
- Export MP4 in 16:9, 9:16, or 1:1 with center-crop or blur-pad. Never overwrite the
  source, and show FFmpeg progress plus a useful failure message.
- Store projects as JSON under ~/SubclipDIY/projects and renders under
  ~/SubclipDIY/exports, with a recent-projects page and a delete-project action.
- Bind to localhost only. No accounts, uploads, telemetry, or network calls after the
  faster-whisper model has been downloaded.
- Deliberately exclude ONNX models in the browser, Remotion client or server rendering,
  native apps, cloud dubbing, render queues, publishing, an MCP server, and public APIs.
- Add unit tests for cut-list merging and subtitle grouping, plus one smoke test that
  imports a short fixture and produces a playable MP4.
- Include a README with setup for Python and FFmpeg, model-size guidance, data paths,
  supported formats, and an honest warning about CPU transcription and render speed.

## 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.