# How the Documentary Montage Pipeline Uses Real Footage and Free Stock Sources

> Learn how the Documentary Montage Pipeline builds video montages using real footage from free stock sources like Pexels and Archive.org. This retrieval-first workflow avoids paid generation APIs.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The Documentary Montage Pipeline is a retrieval-first workflow that constructs thematic video montages entirely from free, publicly-available archives like Pexels, Archive.org, and NASA, enforcing strict guardrails that prohibit paid generation APIs.**

The **Documentary Montage Pipeline** in the OpenMontage repository eliminates synthetic video generation costs by orchestrating a multi-stage retrieval system. Instead of calling expensive AI generation APIs, it queries curated free-stock libraries using CLIP-based semantic search to assemble coherent video essays from real footage.

## The Five-Stage Retrieval Architecture

The pipeline operates through five specialized "director" skills that progressively transform a thematic brief into a rendered video. Each stage is implemented as a markdown skill file in the `skills/pipelines/documentary-montage/` directory.

### Idea Director: Defining the Source Whitelist

The **Idea Director** captures the production brief and establishes the free-stock foundation. In [`skills/pipelines/documentary-montage/idea-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/idea-director.md), the brief schema requires a `sources_allowed` array that enumerates permissible providers such as **Pexels**, **Archive.org**, **NASA**, **Wikimedia Commons**, and **Unsplash**【L66-L70】.

This stage also enforces content policies by setting `generated_clips_allowed: false`, guaranteeing that all visual material originates from real footage rather than synthetic generation【L68-L70】. The brief additionally mandates a music bed and end-tag, both sourced from free collections unless explicitly opted out【L80-L94】.

### Scene Director: Crafting Searchable Slot Descriptions

The **Scene Director** translates abstract themes into concrete retrieval targets called *slots*. Located in [`skills/pipelines/documentary-montage/scene-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/scene-director.md), this stage generates CLIP-searchable descriptions and 2-3 query strings per slot that mirror natural language stock-footage searches【L91-L107】.

For example, a slot targeting vintage urban footage might generate:

```json
{
  "description": "rain streaking across a bus window, passengers soft focus, blue hour lighting",
  "queries": [
    "rain bus window close up",
    "city rain night interior",
    "wet glass street bus"
  ],
  "preferred_sources": ["pexels", "archive_org"]
}

```

The scene director also handles **era-aware routing** through the `era_mix` field (options: "modern", "vintage", or "any"), which biases the `preferred_sources` selection toward era-appropriate archives【L40-L66】. A "vintage" setting automatically prioritizes `archive_org` or NARA collections, while "modern" favors Pexels or Unsplash【L64-L70】.

### Asset Director: Executing Corpus Retrieval

The **Asset Director** performs the actual footage retrieval by invoking the **corpus builder** for each slot. This stage queries the providers specified in `preferred_sources` and ranks results using CLIP similarity scores against the slot description.

The retrieval logic filters exclusively against the `sources_allowed` whitelist defined in the brief, ensuring compliance with the project's zero-cost constraint. The highest-ranking clips from each query set are selected for assembly.

### Edit Director: Constraining the Assembly

The **Edit Director** enforces disciplined editing rules on the retrieved footage. As defined in [`skills/pipelines/documentary-montage/edit-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/edit-director.md), the pipeline limits transitions to approximately four per montage to maintain documentary authenticity【L125-L135】.

It applies **L-cuts** (audio-leading video transitions) to maintain pacing coherence between disparate footage sources, creating the illusion of continuous narrative flow despite clips originating from different archives.

### Compose Director: Rendering the Final Output

The **Compose Director** handles final rendering using **Remotion**, overlaying the mandatory end-tag and music bed specified in the brief. This stage ensures all composited elements respect the original source licenses and attribution requirements from the free-stock providers.

## Free-Stock Integration Guardrails

The pipeline implements three critical guardrails to prevent cost-bearing generation and ensure ethical sourcing:

### Explicit Source Whitelist Validation

Every brief must contain at least one entry in `sources_allowed`, and the scene director validates that each slot references an available provider before executing queries【L68-L70】. This prevents runtime failures from querying unavailable APIs.

### Era-Aware Source Routing

The `era_mix` parameter creates intelligent routing rules that match visual style to archive content. When set to "vintage", the system automatically weights queries toward Archive.org and NASA repositories, while "modern" prioritizes contemporary stock libraries【L64-L70】.

### Zero-Paid-Generation Policy

The `generated_clips_allowed` boolean flag defaults to `false` in production configurations, creating a hard constraint that the asset director cannot call paid video generation APIs. This architectural decision ensures the pipeline operates entirely within free-tier limits【L68-L70】.

## Configuration Example

A complete brief configuration targeting a 90-second social documentary appears as:

```json
{
  "topic": "The hidden science of rain",
  "thematic_question": "What does rain reveal about urban life?",
  "tone": "elegiac",
  "duration_seconds": 90,
  "shape": "list",
  "sources_allowed": [
    "pexels",
    "archive_org",
    "nasa",
    "wikimedia",
    "unsplash"
  ],
  "generated_clips_allowed": false,
  "era_mix": "any",
  "target_platform": "social_short"
}

```

The **corpus builder** executes retrieval through Python-like interfaces:

```python
clips = corpus_builder.search(
    description=slot["description"],
    queries=slot["queries"],
    sources=slot["preferred_sources"]
)

```

## Summary

- The **Documentary Montage Pipeline** uses a **retrieval-first architecture** that queries free-stock providers instead of generating synthetic video.
- Five specialized directors (**Idea**, **Scene**, **Asset**, **Edit**, **Compose**) handle the progression from brief to rendered video.
- Supported free sources include **Pexels**, **Archive.org**, **NASA**, **Wikimedia Commons**, and **Unsplash**.
- The `generated_clips_allowed: false` flag enforces a strict **zero-paid-generation policy**.
- **Era-aware routing** via `era_mix` automatically selects vintage or modern archives based on thematic requirements.
- All retrieval logic is governed by explicit source whitelists defined in [`idea-director.md`](https://github.com/calesthio/OpenMontage/blob/main/idea-director.md) and validated in [`scene-director.md`](https://github.com/calesthio/OpenMontage/blob/main/scene-director.md).

## Frequently Asked Questions

### How does the pipeline ensure it only uses free footage and not paid generation APIs?

The pipeline enforces this through a configuration flag `generated_clips_allowed` set to `false` in the brief schema located in [`skills/pipelines/documentary-montage/idea-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/idea-director.md)【L68-L70】. This boolean creates a hard constraint that the Asset Director must query only the providers listed in `sources_allowed`, preventing any calls to paid generation endpoints.

### What free stock sources does the Documentary Montage Pipeline support?

According to the source code in [`skills/pipelines/documentary-montage/idea-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/idea-director.md), the pipeline supports **Pexels**, **Archive.org**, **NASA**, **Wikimedia Commons**, and **Unsplash**【L66-L70】. The Scene Director can specify `preferred_sources` per slot to bias retrieval toward specific providers based on the desired visual era.

### How does the pipeline handle different visual eras like vintage versus modern footage?

The pipeline implements **era-aware source routing** through the `era_mix` parameter in the brief. When set to "vintage", the Scene Director in [`skills/pipelines/documentary-montage/scene-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/documentary-montage/scene-director.md) automatically biases `preferred_sources` toward archival repositories like Archive.org and NARA【L64-L70】. The "modern" setting prioritizes contemporary libraries like Pexels, while "any" allows mixing across eras.

### What editing constraints does the pipeline apply to maintain documentary coherence?

The Edit Director enforces strict limits of approximately **four transitions per montage** and mandates **L-cuts** (where audio leads video across cuts) to maintain pacing continuity【L125-L135】. These constraints prevent over-editing that would distract from the authentic feel of the retrieved real footage.