Plan cinematic edit generation workflow

2026-07-10 14:15:12 +02:00 · 2026-07-10 14:15:12 +02:00 · bd7b209f8e
parent 7fd92a72df
commit bd7b209f8e
1 changed files with 952 additions and 0 deletions
--- a/docs/cinematic-video-editing-service-plan.md
+++ b/docs/cinematic-video-editing-service-plan.md
@ -0,0 +1,952 @@
+# Cinematic Video Editing Service Implementation Plan
+
+## Goal
+
+Extend the video clipping service so it can turn a folder or set of existing clips into a new cinematic promotional video.
+
+Primary use case:
+
+- input: about 35 Porsche clips
+- output: one cinematic MP4 video
+- style: appealing, exciting, premium automotive promo
+- additions: music, sound effects, voiceover praising the Porsche, transitions, timing, and color treatment
+
+The expensive AI model should do high-value creative planning only. The service should do the heavy media work with deterministic tools such as FFmpeg. A lower-cost coding model should be able to implement this plan milestone by milestone.
+
+## Core Principle
+
+Do not send full-resolution video through an AI model.
+
+Use the service to extract compact metadata and preview assets:
+
+- durations
+- codecs
+- dimensions
+- frame thumbnails
+- contact sheets
+- low-resolution preview proxies
+- optional audio loudness data
+- optional scene or motion scores
+
+Then use AI to generate:
+
+- creative direction
+- shot selection
+- edit decision list
+- voiceover script
+- music and sound effect cue list
+- final render instructions
+
+The service renders the final video from the plan.
+
+## Non-Goals
+
+- Browser-based nonlinear editor UI.
+- Manual timeline editing interface.
+- Real-time collaborative editing.
+- Full professional color grading system.
+- Training custom AI models.
+- Passing raw full-resolution video to an LLM.
+
+## Proposed Workflow
+
+```text
+Input clips
+  -> analyze media with ffprobe and ffmpeg
+  -> extract thumbnails and low-resolution proxies
+  -> build compact clip manifest
+  -> AI creates cinematic storyboard and edit decision list
+  -> service validates the plan
+  -> service generates or imports voiceover, music, and SFX assets
+  -> service renders final MP4 with ffmpeg
+  -> service stores render output and manifest
+```
+
+## Output Targets
+
+Default final render:
+
+- container: MP4
+- video codec: H.264
+- audio codec: AAC
+- resolution: same as source if all clips match, otherwise configurable default `1920x1080`
+- frame rate: same as source if all clips match, otherwise configurable default `30`
+- audio sample rate: `48000`
+- max duration: configurable, default `60` seconds
+
+For Porsche promo videos, default creative structure:
+
+```text
+0-5s: hook, hero reveal, engine or impact sound
+5-15s: exterior beauty shots and badge/details
+15-30s: driving motion, acceleration, road energy
+30-45s: interior, craftsmanship, handling, lifestyle shots
+45-55s: strongest montage sequence
+55-60s: final hero shot and short tagline
+```
+
+## Data Model
+
+Add package:
+
+```text
+src/main/java/org/example/videoclips/editing
+```
+
+Suggested domain records:
+
+```java
+record EditProject(
+        String id,
+        String name,
+        EditProjectStatus status,
+        Path inputDirectory,
+        Path outputDirectory,
+        Instant createdAt,
+        Instant updatedAt
+) {}
+
+enum EditProjectStatus {
+    CREATED,
+    ANALYZING,
+    ANALYZED,
+    PLANNING,
+    PLANNED,
+    RENDERING,
+    RENDERED,
+    FAILED
+}
+
+record ClipAnalysis(
+        String clipId,
+        Path sourcePath,
+        double durationSeconds,
+        String videoCodec,
+        String audioCodec,
+        int width,
+        int height,
+        double frameRate,
+        List<Path> thumbnails,
+        Path contactSheet,
+        Path proxyPath,
+        double motionScore,
+        double brightnessScore,
+        double sharpnessScore
+) {}
+
+record EditDecision(
+        String clipId,
+        double sourceStartSeconds,
+        double sourceEndSeconds,
+        double timelineStartSeconds,
+        double timelineEndSeconds,
+        String transitionIn,
+        String transitionOut,
+        double playbackSpeed,
+        String visualTreatment,
+        String reason
+) {}
+
+record AudioCue(
+        String type,
+        String assetKey,
+        double timelineStartSeconds,
+        double timelineEndSeconds,
+        double gainDb,
+        String notes
+) {}
+
+record VoiceoverLine(
+        String text,
+        double timelineStartSeconds,
+        double timelineEndSeconds,
+        String delivery
+) {}
+
+record EditPlan(
+        String projectId,
+        String style,
+        double targetDurationSeconds,
+        List<EditDecision> decisions,
+        List<AudioCue> audioCues,
+        List<VoiceoverLine> voiceover,
+        String renderProfile,
+        String summary
+) {}
+```
+
+For the first implementation, these can be JSON files on disk. Do not start with JPA unless project persistence is required by the user later.
+
+## API Contract
+
+Add REST endpoints under `/v1/edit-projects`.
+
+### Create Edit Project
+
+`POST /v1/edit-projects`
+
+Request:
+
+```json
+{
+  "name": "porsche-cinematic",
+  "inputDirectory": "./output/clips/20240708_173213",
+  "targetDurationSeconds": 60,
+  "style": "cinematic-porsche-promo",
+  "voiceoverEnabled": true,
+  "musicEnabled": true,
+  "soundEffectsEnabled": true
+}
+```
+
+Response:
+
+```json
+{
+  "projectId": "edit_01JZABCDE",
+  "status": "CREATED"
+}
+```
+
+Validation:
+
+- `name`: required, filesystem-safe after normalization
+- `inputDirectory`: required and must exist
+- `targetDurationSeconds`: `15..600`
+- `style`: required, initially allow `cinematic-porsche-promo`
+
+### Analyze Clips
+
+`POST /v1/edit-projects/{projectId}:analyze`
+
+Behavior:
+
+- scans project input directory
+- accepts valid video files only
+- runs `ffprobe`
+- extracts thumbnails
+- creates contact sheets
+- optionally creates low-resolution proxy files
+- writes `analysis.json`
+
+Response:
+
+```json
+{
+  "projectId": "edit_01JZABCDE",
+  "status": "ANALYZED",
+  "clipCount": 35,
+  "analysisPath": "./output/edit-projects/edit_01JZABCDE/analysis.json"
+}
+```
+
+### Generate Storyboard Prompt
+
+`POST /v1/edit-projects/{projectId}:storyboard-prompt`
+
+Behavior:
+
+- reads `analysis.json`
+- produces a compact AI prompt
+- includes clip summaries, thumbnail references, timing constraints, and output schema
+- writes `storyboard-prompt.md`
+
+Response:
+
+```json
+{
+  "projectId": "edit_01JZABCDE",
+  "promptPath": "./output/edit-projects/edit_01JZABCDE/storyboard-prompt.md"
+}
+```
+
+### Save Edit Plan
+
+`PUT /v1/edit-projects/{projectId}/plan`
+
+Request:
+
+```json
+{
+  "style": "cinematic-porsche-promo",
+  "targetDurationSeconds": 60,
+  "decisions": [],
+  "audioCues": [],
+  "voiceover": [],
+  "renderProfile": "mp4-h264-aac-1080p",
+  "summary": "Cinematic Porsche promo edit."
+}
+```
+
+Behavior:
+
+- validates the AI-generated edit plan
+- ensures all clip IDs exist
+- ensures source time ranges are inside clip durations
+- ensures timeline ranges do not overlap incorrectly
+- writes `edit-plan.json`
+
+### Render Edit
+
+`POST /v1/edit-projects/{projectId}:render`
+
+Behavior:
+
+- reads `edit-plan.json`
+- renders the final video with FFmpeg
+- mixes music, SFX, and voiceover if available
+- writes final MP4 and `render-manifest.json`
+
+Response:
+
+```json
+{
+  "projectId": "edit_01JZABCDE",
+  "status": "RENDERED",
+  "outputPath": "./output/edit-projects/edit_01JZABCDE/final.mp4",
+  "durationSeconds": 60
+}
+```
+
+### Read Project
+
+`GET /v1/edit-projects/{projectId}`
+
+Return current status, paths, timestamps, and error details if failed.
+
+## File Layout
+
+For local filesystem implementation:
+
+```text
+output/edit-projects/<project-id>/
+  project.json
+  analysis.json
+  storyboard-prompt.md
+  edit-plan.json
+  render-manifest.json
+  final.mp4
+  thumbnails/
+    <clip-id>_0001.jpg
+    <clip-id>_0002.jpg
+  contact-sheets/
+    <clip-id>.jpg
+  proxies/
+    <clip-id>.mp4
+  audio/
+    voiceover.wav
+    music.wav
+    sfx/
+```
+
+## Configuration
+
+Add YAML config under `video-clipping.editing`.
+
+```yaml
+video-clipping:
+  editing:
+    enabled: true
+    project-directory: ./output/edit-projects
+    ffmpeg-binary: ffmpeg
+    ffprobe-binary: ffprobe
+    thumbnail-count-per-clip: 5
+    contact-sheet-columns: 5
+    proxy-enabled: true
+    proxy-width: 640
+    target-duration-seconds: 60
+    output-width: 1920
+    output-height: 1080
+    output-frame-rate: 30
+    audio-sample-rate: 48000
+    video-bitrate: 12000k
+    audio-bitrate: 192k
+```
+
+## FFmpeg Commands
+
+### Probe Clip
+
+```bash
+ffprobe -v error \
+  -show_entries format=duration \
+  -show_entries stream=codec_type,codec_name,width,height,r_frame_rate \
+  -of json \
+  clip_00001.mp4
+```
+
+### Extract Thumbnail
+
+Use timestamps spread across clip duration.
+
+```bash
+ffmpeg -hide_banner -y \
+  -ss 3.2 \
+  -i clip_00001.mp4 \
+  -frames:v 1 \
+  -q:v 2 \
+  thumbnails/clip_00001_0001.jpg
+```
+
+### Create Contact Sheet
+
+```bash
+ffmpeg -hide_banner -y \
+  -i clip_00001.mp4 \
+  -vf "fps=1/2,scale=320:-1,tile=5x5" \
+  -frames:v 1 \
+  contact-sheets/clip_00001.jpg
+```
+
+### Create Proxy
+
+```bash
+ffmpeg -hide_banner -y \
+  -i clip_00001.mp4 \
+  -vf "scale=640:-2" \
+  -c:v libx264 -preset veryfast -crf 28 \
+  -c:a aac -b:a 96k \
+  proxies/clip_00001.mp4
+```
+
+### Render Final Video
+
+First implementation should use a concat-based render:
+
+1. Trim each selected segment into an intermediate file.
+2. Normalize resolution, frame rate, pixel format, and audio.
+3. Concatenate intermediates.
+4. Mix music, SFX, and voiceover.
+5. Write final MP4.
+
+This is simpler and easier for a lower-cost coding model than building one huge `filter_complex` command.
+
+Intermediate segment command:
+
+```bash
+ffmpeg -hide_banner -y \
+  -ss <sourceStart> \
+  -to <sourceEnd> \
+  -i <sourceClip> \
+  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,format=yuv420p" \
+  -r 30 \
+  -c:v libx264 -preset veryfast -crf 18 \
+  -c:a aac -b:a 192k -ar 48000 \
+  <work>/segment_0001.mp4
+```
+
+Concat command:
+
+```bash
+ffmpeg -hide_banner -y \
+  -f concat \
+  -safe 0 \
+  -i concat.txt \
+  -c copy \
+  <work>/timeline-video.mp4
+```
+
+Final mix command:
+
+```bash
+ffmpeg -hide_banner -y \
+  -i <work>/timeline-video.mp4 \
+  -i audio/music.wav \
+  -i audio/voiceover.wav \
+  -filter_complex "[1:a]volume=0.25[music];[2:a]volume=1.0[voice];[0:a][music][voice]amix=inputs=3:duration=first:dropout_transition=2[a]" \
+  -map 0:v -map "[a]" \
+  -c:v copy \
+  -c:a aac -b:a 192k \
+  final.mp4
+```
+
+Add SFX later after the basic music and voiceover mix works.
+
+## AI Storyboard Prompt Requirements
+
+The generated prompt should instruct the AI to output strict JSON only.
+
+Required input context:
+
+- project style
+- target duration
+- clip IDs
+- duration per clip
+- dimensions and frame rate
+- extracted thumbnail paths or descriptions
+- any motion, brightness, and sharpness scores
+- known constraints
+
+Required output schema:
+
+```json
+{
+  "style": "cinematic-porsche-promo",
+  "targetDurationSeconds": 60,
+  "summary": "string",
+  "decisions": [
+    {
+      "clipId": "clip_00001",
+      "sourceStartSeconds": 0.0,
+      "sourceEndSeconds": 2.5,
+      "timelineStartSeconds": 0.0,
+      "timelineEndSeconds": 2.5,
+      "transitionIn": "cut",
+      "transitionOut": "crossfade",
+      "playbackSpeed": 1.0,
+      "visualTreatment": "high contrast warm cinematic grade",
+      "reason": "hero front angle"
+    }
+  ],
+  "voiceover": [
+    {
+      "text": "This Porsche turns precision into emotion.",
+      "timelineStartSeconds": 3.0,
+      "timelineEndSeconds": 6.0,
+      "delivery": "confident cinematic narrator"
+    }
+  ],
+  "audioCues": [
+    {
+      "type": "music",
+      "assetKey": "cinematic-driving-bed",
+      "timelineStartSeconds": 0.0,
+      "timelineEndSeconds": 60.0,
+      "gainDb": -12.0,
+      "notes": "build energy toward final montage"
+    }
+  ]
+}
+```
+
+Prompt rules:
+
+- Never reference clip paths directly in final viewer-facing text.
+- Keep total timeline duration within the requested target duration.
+- Use at least 12 clips if enough usable clips exist.
+- Avoid using any single source clip for more than 20% of the final runtime.
+- Prefer a strong first 5 seconds.
+- End with the strongest exterior or motion shot.
+- Voiceover should praise the car without sounding exaggerated or fake.
+
+## Voiceover And Audio
+
+First implementation can support imported audio assets only:
+
+- user places `music.wav` and `voiceover.wav` under project `audio/`
+- service mixes those files into the final render
+
+Second implementation can add generated voiceover:
+
+- create `voiceover-script.txt`
+- call an external TTS provider or OpenAI audio model outside the core renderer
+- save `voiceover.wav`
+- keep generation behind an interface so it can be mocked in tests
+
+Suggested interface:
+
+```java
+interface VoiceoverGenerator {
+    Path generateVoiceover(String projectId, List<VoiceoverLine> lines);
+}
+```
+
+Suggested first adapter:
+
+```text
+NoopVoiceoverGenerator
+```
+
+It writes the script only and requires an imported audio file.
+
+## Milestones
+
+1. [ ] Add editing configuration under `video-clipping.editing`.
+2. [ ] Add filesystem project store for `project.json`, `analysis.json`, `edit-plan.json`, and render output.
+3. [ ] Add edit project domain records and status enum.
+4. [ ] Add `POST /v1/edit-projects` and `GET /v1/edit-projects/{projectId}`.
+5. [ ] Add clip discovery for project input directories.
+6. [ ] Add `ffprobe` analysis and validation for all input clips.
+7. [ ] Add thumbnail extraction.
+8. [ ] Add contact sheet generation.
+9. [ ] Add optional proxy generation.
+10. [ ] Add `analysis.json` writing and reading.
+11. [ ] Add storyboard prompt generation from `analysis.json`.
+12. [ ] Add strict JSON edit plan schema and validation.
+13. [ ] Add `PUT /v1/edit-projects/{projectId}/plan`.
+14. [ ] Add simple segment rendering without transitions.
+15. [ ] Add concat-based final timeline rendering.
+16. [ ] Add music and voiceover audio mixing.
+17. [ ] Add render manifest with command metadata and output details.
+18. [ ] Add basic transition support: cut, crossfade, fade in, fade out.
+19. [ ] Add SFX cue support.
+20. [ ] Add optional generated voiceover adapter interface.
+21. [ ] Add structured logs and metrics for analysis, planning, and rendering durations.
+22. [ ] Add integration test with generated fixture clips and a short edit plan.
+23. [ ] Add documentation for running a local cinematic edit.
+24. [ ] Run `mvn verify` and update this checklist.
+
+## Milestone Details
+
+### Milestone 1: Editing Configuration
+
+Files:
+
+- `src/main/java/org/example/videoclips/config/VideoClippingProperties.java`
+- `src/main/resources/application.yml`
+
+Add nested properties class:
+
+```java
+private final Editing editing = new Editing();
+
+public Editing getEditing() {
+    return editing;
+}
+```
+
+Add fields matching the YAML in this plan.
+
+Tests:
+
+- add a focused config binding test or extend an existing Spring context test
+- verify defaults bind correctly
+
+Acceptance criteria:
+
+- application starts with editing config present
+- editing can be disabled with `video-clipping.editing.enabled=false`
+
+### Milestone 2: Filesystem Project Store
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/EditProjectStore.java`
+- `src/main/java/org/example/videoclips/editing/FileSystemEditProjectStore.java`
+
+Responsibilities:
+
+- create project directories
+- read/write JSON files with Jackson
+- normalize project IDs and reject path traversal
+- expose methods for project, analysis, plan, and manifest paths
+
+Tests:
+
+- creates expected folder structure
+- rejects invalid project IDs
+- round-trips `project.json`
+
+Acceptance criteria:
+
+- no direct filesystem writes from controllers
+- all project path creation goes through the store
+
+### Milestone 3: Domain Records
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/EditProject.java`
+- `src/main/java/org/example/videoclips/editing/EditProjectStatus.java`
+- `src/main/java/org/example/videoclips/editing/ClipAnalysis.java`
+- `src/main/java/org/example/videoclips/editing/EditPlan.java`
+- `src/main/java/org/example/videoclips/editing/EditDecision.java`
+- `src/main/java/org/example/videoclips/editing/AudioCue.java`
+- `src/main/java/org/example/videoclips/editing/VoiceoverLine.java`
+
+Tests:
+
+- JSON serialization for representative records
+
+Acceptance criteria:
+
+- records serialize with stable camelCase JSON
+- no business logic in records beyond validation helpers if needed
+
+### Milestone 4: Project API
+
+Files:
+
+- `src/main/java/org/example/videoclips/api/EditProjectController.java`
+- `src/main/java/org/example/videoclips/api/dto/CreateEditProjectRequest.java`
+- `src/main/java/org/example/videoclips/api/dto/EditProjectResponse.java`
+
+Tests:
+
+- create project success
+- reject missing input directory
+- reject invalid target duration
+- get project success
+- get missing project returns `404`
+
+Acceptance criteria:
+
+- API returns project ID and status
+- project state is persisted to `project.json`
+
+### Milestone 5-10: Analysis Pipeline
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/EditProjectAnalyzer.java`
+- `src/main/java/org/example/videoclips/editing/FfmpegClipInspector.java`
+- `src/main/java/org/example/videoclips/editing/ThumbnailExtractor.java`
+- `src/main/java/org/example/videoclips/editing/ContactSheetGenerator.java`
+- `src/main/java/org/example/videoclips/editing/ProxyGenerator.java`
+
+Implementation notes:
+
+- reuse patterns from `FolderVideoValidator` and `FolderFfmpegClipper`
+- keep process execution behind package-private interfaces for tests
+- sanitize process output before logging
+- process clips in deterministic filename order
+
+Tests:
+
+- analysis ignores non-video files
+- invalid videos are reported in analysis errors
+- command construction is correct
+- output JSON includes all analyzed clips
+- proxy generation can be disabled
+
+Acceptance criteria:
+
+- `analysis.json` is enough for an AI prompt without reading raw video
+- failure of one invalid clip does not fail the entire project if at least one valid clip exists
+
+### Milestone 11: Storyboard Prompt
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/StoryboardPromptGenerator.java`
+
+Tests:
+
+- prompt includes clip IDs, durations, target duration, style, and JSON schema
+- prompt excludes raw absolute system paths unless explicitly configured
+
+Acceptance criteria:
+
+- generated prompt can be pasted into an AI model
+- model output requirements are strict JSON
+
+### Milestone 12-13: Edit Plan Validation
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/EditPlanValidator.java`
+- `src/main/java/org/example/videoclips/api/dto/SaveEditPlanRequest.java`
+
+Validation rules:
+
+- all clip IDs exist in `analysis.json`
+- `sourceStartSeconds >= 0`
+- `sourceEndSeconds > sourceStartSeconds`
+- source range is inside clip duration
+- timeline ranges are non-negative
+- timeline ranges do not overlap unless the transition requires overlap
+- final duration is within target duration tolerance
+- playback speed is between `0.25` and `4.0`
+- only supported transitions are accepted
+
+Tests:
+
+- accepts valid plan
+- rejects unknown clip ID
+- rejects out-of-range source timestamps
+- rejects overlapping timeline decisions
+- rejects unsupported transition
+
+Acceptance criteria:
+
+- renderer never receives an invalid plan
+
+### Milestone 14-17: Render Pipeline
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/EditRenderer.java`
+- `src/main/java/org/example/videoclips/editing/FfmpegEditRenderer.java`
+- `src/main/java/org/example/videoclips/editing/RenderManifest.java`
+
+Implementation sequence:
+
+1. create working directory
+2. render each selected decision into normalized segment MP4
+3. write `concat.txt`
+4. concatenate segments into `timeline-video.mp4`
+5. mix audio when audio files exist
+6. write `final.mp4`
+7. write `render-manifest.json`
+
+Tests:
+
+- command construction for segment render
+- command construction for concat
+- command construction for audio mix
+- render fails if no decisions exist
+- manifest is written on success
+
+Acceptance criteria:
+
+- final MP4 exists after render
+- render manifest includes input clip IDs, output path, duration, and command summaries
+
+### Milestone 18-19: Transitions And SFX
+
+Start simple.
+
+Supported transitions:
+
+- `cut`
+- `fade-in`
+- `fade-out`
+- `crossfade`
+
+Supported SFX cues:
+
+- imported WAV files only
+- cue has asset key, start time, gain, and optional fade
+
+Tests:
+
+- unsupported transition rejected
+- SFX file missing is a validation error
+- final mix includes SFX input when cue exists
+
+Acceptance criteria:
+
+- basic cinematic polish is possible without needing a full timeline engine
+
+### Milestone 20: Voiceover Generation Hook
+
+Files:
+
+- `src/main/java/org/example/videoclips/editing/VoiceoverGenerator.java`
+- `src/main/java/org/example/videoclips/editing/NoopVoiceoverGenerator.java`
+
+Behavior:
+
+- first version writes `voiceover-script.txt`
+- does not call external APIs
+- later adapters can call TTS providers
+
+Tests:
+
+- script file generated from voiceover lines
+- noop adapter does not fail when TTS is disabled
+
+Acceptance criteria:
+
+- service supports the workflow without requiring paid audio generation
+
+### Milestone 21: Logs And Metrics
+
+Logs:
+
+- `event=edit_project_created`
+- `event=edit_analysis_started`
+- `event=edit_analysis_completed`
+- `event=storyboard_prompt_generated`
+- `event=edit_plan_saved`
+- `event=edit_render_started`
+- `event=edit_render_completed`
+- `event=edit_render_failed`
+
+Metrics:
+
+- `video.clipping.edit.projects.created`
+- `video.clipping.edit.analysis.duration`
+- `video.clipping.edit.render.duration`
+- `video.clipping.edit.render.failures`
+
+Tests:
+
+- metrics binder test if custom metrics are added
+- at minimum, unit tests should cover event-producing paths
+
+Acceptance criteria:
+
+- an operator can see which stage failed and how long rendering took
+
+### Milestone 22: Integration Test
+
+Create generated fixture clips with FFmpeg:
+
+- three 3-second clips
+- different colors or test patterns
+- simple audio tones
+
+Test flow:
+
+1. create project
+2. analyze clips
+3. save a short edit plan
+4. render final video
+5. probe final video
+6. assert duration is greater than zero
+
+Skip test when `ffmpeg` or `ffprobe` is unavailable.
+
+Acceptance criteria:
+
+- proves the end-to-end renderer works on a machine with FFmpeg installed
+
+## Lower-Cost Model Implementation Instructions
+
+Follow these rules when assigning this plan to a cheaper coding model:
+
+- Implement exactly one milestone at a time.
+- Run the relevant tests after each milestone.
+- Update the checklist in this file after each completed milestone.
+- Commit after each milestone if the repository is in a clean, test-passing state.
+- Do not refactor unrelated packages.
+- Reuse existing patterns from the folder scheduler for process execution, logging, and tests.
+- Keep the first renderer deterministic and simple.
+- Do not add external AI, TTS, or music-provider calls until the filesystem workflow works.
+
+Suggested prompt for the lower-cost coding model:
+
+```md
+You are implementing `docs/cinematic-video-editing-service-plan.md`.
+
+Implement the next unchecked milestone only. Keep the change scoped. Use existing patterns from the folder scheduler package where possible. Add tests for the milestone. Run the relevant Maven test command. Update the milestone checkbox only when tests pass. Do not implement future milestones early.
+```
+
+## Cost Strategy
+
+The service should reduce expensive AI usage by producing compact artifacts.
+
+Recommended AI input:
+
+- `analysis.json`
+- contact sheet images
+- optional short low-resolution proxy snippets
+- target duration and style
+
+Avoid AI input:
+
+- full-resolution video files
+- every frame from every clip
+- raw uncompressed audio
+
+Expected token ranges:
+
+- metadata-only storyboard: `5k-15k`
+- metadata plus contact sheets: `30k-100k`
+- dense frame analysis: `150k-400k+`
+
+The target architecture should keep normal cinematic edit planning in the `30k-100k` range before rendering.
+
+## Completion Criteria
+
+The feature is complete when:
+
+- a user can create an edit project from an existing folder of clips
+- the service can analyze clips and generate `analysis.json`
+- the service can generate a storyboard prompt
+- a valid edit plan can be saved
+- the service can render one final MP4
+- music and voiceover can be mixed into the output
+- a realistic FFmpeg integration test passes
+- the plan checklist is fully checked