Content Templates
Relevant source files
The following files were used as context for generating this wiki page:
Content Templates serve as the foundational configuration for the automated content creation pipeline. They define the visual style, motion characteristics, and linguistic tone used to generate social-ready assets for artists. By combining structured JSON guides with reference assets, these templates ensure consistency across AI-generated images, videos, and captions.
The template system is integrated into the create-content task, which orchestrates various AI models (via fal.ai and Recoup Chat API) to produce final rendered videos. Each template acts as a blueprint, specifying how prompts should be constructed and which artistic constraints to apply during the generation process.
Sources: src/tasks/createContentTask.ts:32-48, src/content/loadTemplate.ts:16-28
Template Architecture and Structure
Templates are stored as individual directories within a centralized templates directory. Each directory contains a set of JSON configuration files and asset subdirectories that define the template's behavior.
Core Components
A template consists of several key data structures:
- Style Guide: Defines the visual parameters including camera angles, lighting, environment, and realism constraints.
- Caption Guide: Outlines the persona, tone, and formatting rules for generated text.
- Reference Assets: Includes reference images for visual consistency and example captions for linguistic few-shot prompting.
- Moods and Movements: Lists of strings used to randomize and guide the video generation process.
Sources: src/content/loadTemplate.ts:32-68, src/content/templates/album-record-store/caption-guide.json:1-15
Directory Layout
The resolution logic searches for templates in a specific hierarchy, typically looking for a templates folder relative to the source or the current working directory.
The diagram shows the standard file structure of a content template directory.
Sources: src/content/loadTemplate.ts:47-68, src/content/resolveTemplatesDir.ts:14-22
Template Loading and Resolution
The system utilizes a multi-strategy approach to locate the templates directory, ensuring compatibility between local development (using tsx) and production deployments (where esbuild may alter directory structures).
Resolution Strategies
- Relative to Module: Attempts to resolve
../content/templatesfrom the current file's__dirname. - Relative to CWD: Falls back to
src/content/templatesfrom the process current working directory.
Sources: src/content/resolveTemplatesDir.ts:14-22
Data Structure: TemplateData
The loadTemplate function populates the following interface:
| Field | Type | Description |
|---|---|---|
name | string | The unique identifier/directory name of the template. |
imagePrompt | string | Base scene description derived from the style guide. |
usesFaceGuide | boolean | Whether to apply the artist's face-guide during generation. |
styleGuide | Record | JSON object containing camera, lighting, and subject rules. |
captionGuide | Record | JSON object containing tone and formatting rules for captions. |
referenceImagePaths | string[] | List of paths to physical images used as visual references. |
Sources: src/content/loadTemplate.ts:13-28, src/content/loadTemplate.ts:80-92
Prompt Engineering Logic
Templates drive the generation of complex prompts for AI models by concatenating base instructions with template-specific rules.
Image Prompt Construction
The system builds a full image prompt by merging a base scene description with "Style Rules" extracted from the style-guide.json. This includes camera type, lighting, expressions, and "AVOID" constraints to prevent unwanted artifacts.
const styleRules = [
cam?.type && `Shot on ${cam.type}`,
env?.lighting && `Lighting: ${env.lighting}`,
real?.priority && `IMPORTANT: ${real.priority}`,
env?.avoid && `NEVER: ${env.avoid}`,
].filter(Boolean);
return `${basePrompt}\n\nStyle rules:\n${styleRules.join(". ")}`;
Sources: src/content/loadTemplate.ts:121-144
Motion Prompt Generation
For video generation, the system randomly selects a movement and mood from the template's configuration to create a motion prompt. If no movements are defined, it defaults to a "nearly still" instruction to maintain high visual fidelity.
Sources: src/content/loadTemplate.ts:150-161
Caption Generation Constraints
Captions are governed by a caption-guide.json which specifies the "role" (e.g., the artist posting themselves) and strict formatting rules such as "lowercase only" or prohibiting specific marketing phrases like "out now".
Sources: src/content/templates/album-record-store/caption-guide.json:5-18
Integration in Content Pipeline
The createContentTask utilizes templates at multiple stages of the generation lifecycle.
The sequence shows how the Template Loader provides the necessary context for subsequent AI generation steps.
Sources: src/tasks/createContentTask.ts:77-135
Instruction Resolution
The pipeline determines the primary instruction (Face Swap vs. No Face) based on the usesFaceGuide boolean in the template and any customInstruction provided in the style guide.
| Condition | Resulting Instruction |
|---|---|
customInstruction exists | customInstruction value |
usesFaceGuide: true | FACE_SWAP_INSTRUCTION |
usesFaceGuide: false | NO_FACE_INSTRUCTION |
Sources: src/content/resolveImageInstruction.test.ts:25-50
Testing and Validation
The template system is supported by a local test pipeline (src/content/testPipeline.ts) that allows developers to run individual steps (image, video, caption) using a specific template without triggering a full background job. This ensures that template modifications can be validated quickly against actual AI model outputs.
Sources: src/content/testPipeline.ts:14-25, src/content/testPipeline.ts:68-80