story-repair

/story-repair — Scene/Shot Repair Director

Overview

Use this when Alex gives repair notes for an existing video-story project. The director's cut overlays SCENE N · SHOT M, so Alex can say things like “repair scene 2 shot 4: make the dog face camera and keep the red jacket.”

Inputs to Extract

• Project ID or URL. If missing, use the most recent video-story project if unambiguous; otherwise ask for the project link/ID.
• Target scene numbers.
• Target shot numbers or scene+shot tuples.
• Repair instruction: visual, continuity, motion, dialogue, pacing, style, safety/NSFW workaround.
• Whether to regenerate frames, video, lipsync, final clean cut, and/or director's cut.

API

Base:

BASE=http://localhost:4015
TOKEN="$HERMES_AUTOMATION_TOKEN"

Session-specific implementation notes and examples are kept in references/social-creative-telegram-repair.md. Consult it when working on Telegram-driven repair loops, review-video overlays, or frame-specific repairs.

Production map:

curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/production-map" \
  -H "Authorization: Bearer $TOKEN"

Repair:

curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/repair" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "instructions": "...",
    "shots": [{"scene_number": 2, "shot_number": 4}],
    "regenerate_frames": true,
    "regenerate_video": true,
    "lipsync": true,
    "directors_cut": true
  }'

Status:

curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/repair-status" \
  -H "Authorization: Bearer $TOKEN"

Director's cut / review video:

# Legacy director's cut
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/assemble-directors-cut" \
  -H "Authorization: Bearer $TOKEN"

# Preferred labeled review export: writes final_video_review.mp4 and overlays SCENE N · SHOT M + timing.
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/assemble-review-video" \
  -H "Authorization: Bearer $TOKEN"

curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/review-video" \
  -H "Authorization: Bearer $TOKEN"

Single-frame repair for precise notes:

# Use when Alex asks for only a first/last frame, e.g. “last frame of the last shot”.
# 1) Resolve scene/shot from the production map or DB.
# 2) Set only the relevant *_frame_prompt_addition and clear only that frame URL + that shot video.
# 3) Generate only that frame.
curl -sS -X POST "$BASE/api/shots/$SHOT_ID/generate-single-frame" \
  -H 'Content-Type: application/json' \
  -d '{"frame_type":"last"}'

# 4) Regenerate only that shot video, then rebuild review/clean exports.
curl -sS -X POST "$BASE/api/shots/$SHOT_ID/generate-video"
curl -sS -X POST "$BASE/api/projects/$PROJECT_ID/assemble"

Repair Strategy

• Fetch the production map first so the repair is anchored in current scenes, shots, characters, sets, props, and references.
• For review workflows, prefer the assemble-review-video export over the legacy director's cut: it creates a dedicated labeled review MP4 (final_video_review.mp4) with SCENE N · SHOT M overlays while preserving the clean final_video.mp4.
• If Alex asks for “the last frame of the last shot/scene” or another frame-specific edit, do not use the broad /repair endpoint first. Resolve the target shot, set only first_frame_prompt_addition or last_frame_prompt_addition, clear only that frame URL and that shot’s video URL/status, then run generate-single-frame and generate-video for that shot.
• After a single-frame edit, rebuild both the labeled review video and clean final export so Alex can compare the change in context.
• Verify the export tail actually changed: Video Story’s Frames/Assets UI can show the regenerated frame while the exported MP4 still uses a stale local clip cache. Extract/inspect the affected exported frame or clip after assembly before telling Alex the repair landed.
• If Alex names only a scene, repair all shots in that scene.
• If Alex names a shot without scene and shot numbers repeat, ask or infer from context.
• Preserve canon: character identity, wardrobe, environment, prop continuity.
• Prefer precise prompt additions over broad style changes.
• For bad motion, simplify action and camera movement rather than overprompting.
• For lip sync failures, regenerate video and lipsync only dialogue shots.
• After repair, produce a new director's cut unless Alex asks for clean final only.

Response Format

• Repair started: project + target scene/shot list + directive summary.
• While pending: percent/message from repair status.
• Complete: review video or director's cut URL/path + ask for next notes by scene/shot label. If the repair was frame-specific, also mention the clean final export path.

Pitfalls

• Telegram repair loops need an explicit pending edit context keyed by chat/thread/user or by the review item; callback data should stay compact (vsedit:<verb>:<review_id>) and larger state should live in durable app/gateway state.
• Exact scene/shot references are reliable now. Semantic notes like “the part where Jupiter appears” should fetch the production map, infer likely targets, and ask for confirmation if confidence is low.
• Provider-side video generation can fail transiently (for example remote CUDA OOM). Treat this as retryable for the same single-shot generation; the durable lesson is to retry the shot, not to broaden the repair scope.
• Export assembly may reuse stale local shot clips from uploads/<project>/export/temp even after a frame/shot is regenerated, especially when the remote object key/URL is overwritten in place. Cache validation must consider the shot’s current source clip/version, and manual verification should delete the affected shot_<start_time>*, normalized clip, and video_only.mp4 temp artifacts before rebuilding if needed.
• Avoid overwriting the original Creative-approved output silently. Repair iterations should produce review/final variants with provenance whenever the output is being handed back into Hermes Creative.

Verification Checklist

• [ ] Project/targets resolved.
• [ ] Production map checked.
• [ ] Repair API accepted request.
• [ ] Status polled to completion or reported actionable failure.
• [ ] Director's cut updated when requested.
• [ ] Clean export rebuilt when requested.
• [ ] A frame/clip from the rebuilt MP4 was extracted or visually inspected to prove the changed asset is actually present in the export, not only in the timeline/asset views.