youtube-studio-flow/documentation/YouTube Studio Flow/01 - Architecture/07 - Render Engine.md

Render Engine

Two Services

VideoRenderService

Location: backend/src/shared/render-engine/video-render.service.ts

The single source of truth for description rendering. Responsible for fetching all required data:

• Description blocks (from blockOrder)
• Block overrides and variable values (from VideoConfig)
• Team variables
• Campaign blocks (active ones are appended regardless of blockOrder)
• Team date format and timezone
• Playlists (for {video.playlists} token)
• Collaborators (for {collab.*} tokens)

Then delegates computation to RenderEngineService.

Used by: youtube-sync.processor, render.processor, videos.service.ts renderDescription()

RenderEngineService

Location: backend/src/shared/render-engine/render-engine.service.ts

Pure computation. Takes RenderInput, returns { rendered: string, hash: string }.

Used directly by: video-configs.service.ts renderPreview(), templates.service.ts renderPreview() — these callers already have all data fetched.

Block Rendering by Type

Block Type	Rendering Behavior
STATIC	Raw content output, zero token substitution
VARIABLE	Resolves {custom_var}, {video.*}, {collab.*} tokens
CAMPAIGN	Auto-appended at end when campaign.startAt ≤ now ≤ campaign.endAt
COLLABORATOR	Cloned once per assigned collaborator, joined with \n\n (or \n if compact)
CONDITIONAL	Evaluates condition JSON against video data
GLOBAL, REPEATABLE	Deprecated; render as VARIABLE

Freetext Entries

blockOrder may contain IDs prefixed freetext: (e.g. freetext:abc123). These have no corresponding DescriptionBlock row. Their content comes entirely from blockOverrides[id].content. The compact flag for freetext entries also comes from blockOverrides[id].compact.

Token Resolution

Resolution happens in three distinct passes per block, applied sequentially:

1. Custom variable pass — resolveVariables(content, effectiveVars) replaces {custom_token} placeholders. effectiveVars is built by merging team variables and video-level values: { ...teamVariables, ...variableValues }. Video-level values win on any name collision — last-write-wins from the spread. System tokens (video.*, collab.*) are explicitly skipped here.
2. Video token pass — resolveVideoVars() replaces {video.*} tokens using the video's own fields.
3. Collaborator token pass — resolveCollaborators() or expandCollaboratorBlock() replaces {collab.*} tokens.

Effective priority (highest → lowest):

1. System tokens ({video.*}, {collab.*}) — always win; cannot be shadowed by any variable name
2. Video-level variables (VideoConfig.variableValues) — override team variables on conflict
3. Team variables (TeamVariable table) — baseline for custom tokens

Because system tokens are skipped in pass 1 and resolved in dedicated passes afterwards, naming a team or video variable video.title has no effect — it is silently ignored and the actual video title is substituted instead.

DescriptionBlock.variableDefinitions declares which tokens a block expects but is never read by the render engine — it is metadata only (see Backlog).

Any token in SYSTEM_VARIABLE_TOKENS set is skipped by resolveVariables() and handled by its dedicated resolver. If you add a new {video.*} or {collab.*} token, it must be registered in the system variables registry.

System Variable Tokens

Video tokens:

Token	Resolves to
{video.title}	Video title
{video.tags}	Comma-separated tag list
{video.category}	YouTube category name (e.g. Gaming). Falls back to the raw numeric ID if the category is not in the known map. There is no {video.categoryId} token.
{video.scheduledAt}	Scheduled publish date (date token — supports |format)
{video.recordingDate}	Recording date (date token — supports |format)
{video.gameTitle}	Game title field
{video.language}	Default language code
{video.playlists}	Comma-separated list of playlist titles (e.g. Gaming, Tutorials)
{video.playlistLinks}	Comma-separated list of full YouTube playlist URLs (e.g. https://www.youtube.com/playlist?list=PLxxx)

Collaborator tokens: {collab.name}, {collab.youtube}, {collab.twitch}, {collab.instagram}, {collab.tiktok}, {collab.twitter}, {collab.bluesky}, {collab.discord}, {collab.aliases}, {collab.notes}

Note: {collab.youtube} resolves to the full URL (https://www.youtube.com/@handle), not just the handle.

Multi-Collaborator Rendering

Two different behaviors apply depending on block type:

In VARIABLE, CONDITIONAL, CAMPAIGN, and freetext blocks

{collab.*} tokens resolve against the first collaborator in Video.collaboratorIds whose record is found in the loaded collaborator list. If no collaborator is assigned, all {collab.*} tokens are left unreplaced.

This means if a video has three collaborators, {collab.name} in a VARIABLE block only produces the first collaborator's name — not all three.

In COLLABORATOR blocks

The block's content template is expanded once per assigned collaborator, in the order they appear in collaboratorIds. Each expansion resolves all {collab.*} tokens against that specific collaborator. The resulting strings are joined with \n\n (double newline), or \n if the block has compact: true.

Example — with two collaborators (Alice, Bob) and a COLLABORATOR block containing:

🎮 {collab.name} — {collab.youtube}

Renders as:

🎮 Alice — https://www.youtube.com/@alice

🎮 Bob — https://www.youtube.com/@bob

If a collaborator has no value for a given token (e.g. no youtubeLink), that token resolves to an empty string.

Hash Computation

hashMetadata() in shared/render-engine/hash.ts hashes these fields: title, description, tags, categoryId, privacyStatus, defaultLanguage, defaultAudioLanguage, selfDeclaredMadeForKids, embeddable, license, recordingDate.

The hash is stored as Video.lastSyncedHash after a successful YouTube push. hasPendingChanges is computed by comparing current state hash against lastSyncedHash.

Date Format Override Syntax

Date tokens support an inline format override using | as a separator:

{video.scheduledAt|DD.MM.YYYY}
{video.recordingDate|MMMM D, YYYY}

Only date tokens support this. The two date tokens are video.scheduledAt and video.recordingDate. All other video.* and collab.* tokens are non-date (kind: 'simple') — the regex captures the |format portion for all tokens but non-date resolvers ignore it.

Format string tokens (custom implementation, not strftime or moment.js):

Token	Output
YYYY	4-digit year (e.g. 2024)
YY	2-digit year (e.g. 24)
MMMM	Full month name (e.g. January)
MMM	Short month name (e.g. Jan)
MM	Zero-padded month (e.g. 01)
M	Month without padding (e.g. 1)
DD	Zero-padded day (e.g. 05)
D	Day without padding (e.g. 5)

Priority: inline token format → team dateFormat setting → YYYY-MM-DD (hard default).

Invalid format strings are silently passed through as-is. Any character or sequence not matching a known token is output verbatim — no error, no warning.

Null date: If the date field is null or undefined (e.g. video.recordingDate not set), the token resolves to an empty string regardless of format.

Date Formatting Implementation

applyDateFormat() in render-engine.service.ts uses a single-pass regex replacement to avoid re-substitution bugs. Do not convert to chained .replace() calls.

Related

• 02 - Backend
• 02 - Description Engine (features)