# Imported AI clip assembly for hybrid Shorts rendering

Use this when a Shorts/Retention-Studio pipeline cannot or should not generate realistic clips fully inside the local renderer. The durable pattern is to let the system create deterministic shot plans, prompts, and placeholder paths, then let a human manually generate a few realistic clips in PixVerse/Pika/Hailuo/Kling/etc. and drop them into a known folder for final assembly.

## Pipeline pattern

```text
mechanism shot plan
-> render manifest / asset plan
-> provider handoff prompts
-> manual AI-video generation
-> imported clip assembly plan
-> hybrid final renderer
```

The local renderer remains responsible for deterministic elements: mechanism animations, captions, overlays, timing, SFX, and FFmpeg assembly. Imported AI clips are inputs, not the whole video.

## Import contract

Use a stable per-video directory and scene-numbered files, for example:

```text
data/imported_ai_clips/<video_slug>/scene_01.mp4
data/imported_ai_clips/<video_slug>/scene_02.mp4
```

The assembly planner should map each scene to one of:

- `imported_ai_clip` — expected clip exists and passes basic file/path checks.
- `local_renderer_fallback` — cinematic/importable scene is missing, so renderer can still produce a placeholder or procedural fallback.
- `local_renderer` — scene is intentionally rendered locally, e.g. mechanism animation or kinetic captions.

## Quality rules

- Keep provider clips short, usually 3–6 seconds, and assemble them into a larger retention timeline locally.
- Do not bake captions, logos, subtitles, fake UI text, or watermarks into provider clips; captions belong in the local renderer.
- Preserve `static_card_limit = 0` for final videos. Static/card previews are only storyboards.
- Prefer imported AI clips for cinematic human/object/context beats; prefer local renderer for x-ray/system-layer reveals, numbers, captions, and explainers.
- Record counts in the assembly artifact: imported clip count, local fallback count, local-renderer count.

## Provider availability notes

If a provider's current product status or free-tier availability was checked during a session, store it as a dated note in generated artifacts or a reference file with an explicit "re-check before use" warning. Do not turn temporary provider availability into a permanent refusal. The skill-level rule is: verify current provider docs before relying on a paid/free video source, then build a handoff path that can swap providers.

## Testing checks

Add tests that assert:

- expected import paths are deterministic from the video slug and scene IDs.
- cinematic scenes can become `imported_ai_clip` when files exist.
- missing cinematic scenes become `local_renderer_fallback`, not a crash.
- mechanism and kinetic-caption scenes remain `local_renderer`.
- generated assembly plans include provider/source notes and counts.
- no final scene mode degenerates into a static slideshow/card format.

## Pitfalls

- Do not block final-render development just because manual AI clips are not ready; fallback scenes keep the pipeline testable.
- Do not let provider-generated text enter the video. It will often be wrong or ugly; generate captions locally.
- Do not overfit to one provider. The assembly contract should accept clips from any source as long as they match the import path and technical requirements.