Content Templates
Relevant source files
The following files were used as context for generating this wiki page:
Content Templates are a core component of the Recoup CLI's content creation pipeline. They define the stylistic and structural parameters used to generate automated video content for artists. These templates allow users to select pre-configured settings—such as "artist-caption-bedroom"—which govern the visual "mood" and setting of the generated media.
The system is designed as a thin wrapper over the Recoup REST API, facilitating the retrieval of available templates, validation of artist assets against template requirements, and the triggering of content generation runs. Users can interact with these templates through the recoup content subcommand group.
Sources: src/commands/content.ts:1-12, src/commands/content/templatesCommand.ts:1-30, tests/commands/content.test.ts:31-40
Architecture and Command Structure
The content template functionality is organized under a hierarchical command structure using commander.js. The content command serves as the parent container for several specialized subcommands that interact with the template system.
The diagram above illustrates the relationship between CLI subcommands and their corresponding REST API endpoints.
Sources: src/commands/content.ts:6-11, src/client.ts:7-60
Key Components
| Component | Responsibility | Source |
|---|---|---|
templatesCommand | Fetches and displays the list of available content templates from the API. | src/commands/content/templatesCommand.ts |
validateCommand | Checks if a specific artist has the necessary assets to utilize content templates. | src/commands/content/validateCommand.ts |
createCommand | Triggers the actual generation process using a selected template and configuration options. | src/commands/content/createCommand.ts |
client.ts | Handles authenticated GET and POST requests to the Recoup API using the x-api-key. | src/client.ts |
Template Listing and Discovery
Users can discover available templates using the templates subcommand. The CLI performs a GET request to /api/content/templates and returns a list of template objects.
Data Model: Template Object
Each template returned by the API typically contains the following fields:
- name: A unique identifier for the template (e.g.,
artist-caption-bedroom). - description: A human-readable summary of the template's style (e.g., "Moody purple bedroom setting").
Sources: src/commands/content/templatesCommand.ts:15-26, tests/commands/content.test.ts:33-36
Content Creation Workflow
The workflow for using a template involves validation followed by creation. This ensures that the generation process does not fail due to missing artist assets.
This sequence shows the typical interaction flow from validation to triggering a content run.
Sources: src/commands/content/validateCommand.ts:11-20, src/commands/content/createCommand.ts:28-48, tests/commands/content.test.ts:46-59
Creation Parameters
When creating content from a template, the CLI supports several configuration options that modify the template's behavior:
| Option | Type | Default | Description |
|---|---|---|---|
--artist | String | (Required) | The Artist account ID. |
--template | String | artist-caption-bedroom | The name of the template to apply. |
--caption-length | Enum | short | Options: short, medium, long. |
--batch | Integer | 1 | Number of videos to generate in parallel. |
--lipsync | Boolean | false | Enables lipsync mode for the generated content. |
--upscale | Boolean | false | Enhances image and video quality. |
--songs | String | undefined | Comma-separated list of song slugs to include. |
Sources: src/commands/content/createCommand.ts:10-25, tests/commands/content.test.ts:70-82
Validation and Error Handling
The validation system checks the ready status of an artist. If ready is false, the API returns a missing array detailing which files or assets are required by the templates but are currently unavailable for that artist.
Implementation Detail: Caption Length Validation
The CLI enforces strict validation for the --caption-length flag before sending the request to the API, ensuring it matches one of the allowed values: short, medium, or long.
const ALLOWED_CAPTION_LENGTHS = new Set(["short", "medium", "long"]);
// ...
if (!ALLOWED_CAPTION_LENGTHS.has(opts.captionLength)) {
throw new Error("--caption-length must be one of: short, medium, long");
}
Sources: src/commands/content/createCommand.ts:7-31, src/commands/content/validateCommand.ts:24-29
Conclusion
Content Templates provide a standardized way for users to generate high-quality, stylistically consistent media for artists via the Recoup platform. By leveraging the validate and create subcommands, developers can automate the production of video content while ensuring all prerequisite artist assets are in place.