youtube-studio-flow/documentation/YouTube Studio Flow/02 - Features/02 - Description Engine.md

Description Engine

User Perspective

The description engine generates video descriptions from reusable building blocks. Instead of writing descriptions manually for each video, users define blocks (intro, CTA, social links, sponsor copy) and assemble them into templates. Each video can then use a template as its starting point, overriding individual blocks or variables as needed.

Blocks (/blocks)

A block is a named, reusable piece of description content. Types:

• Static: Plain text, rendered as-is. No token substitution. Suitable for boilerplate that never changes.
• Variable: Text with {token} placeholders. Tokens are resolved from team variables, video fields, or collaborator data.
• Campaign: Like Variable but linked to a Campaign. Auto-included in descriptions during the campaign's date window — no manual placement needed.
• Collaborator: Expanded once per assigned collaborator. The block's content is used as a template, cloned for each collaborator in VideoConfig.collaboratorIds, with {collab.*} tokens resolved per-collaborator. Clones are joined with a blank line (or single newline if compact).
• Conditional: Shown only when its condition evaluates to true.

Blocks have a compact toggle: when compact is off, a blank line is inserted before the block's content during rendering.

Templates (/templates)

A template defines the default block assembly for a type of video. It contains:

• Default block order: which blocks appear and in what sequence
• Default variable values: pre-filled values for variable tokens
• Video fields: default metadata values (privacy, category, tags, etc.) applied when assigned
• Rules: required links for lint checking

Applying a template to a video copies the block order, variable values, and optionally the video field defaults.

Variable Tokens

In Variable-type blocks, {token} placeholders are replaced at render time:

• {video.title}, {video.tags}, {video.category}, {video.gameTitle}, {video.language} — from the video record
• {video.scheduledAt}, {video.recordingDate} — dates; support inline format override (see below)
• {video.playlists} — comma-separated list of playlist titles the video belongs to
• {video.playlistLinks} — comma-separated list of full YouTube playlist URLs the video belongs to
• {collab.name}, {collab.youtube}, {collab.twitch}, {collab.instagram}, {collab.tiktok}, {collab.twitter}, {collab.bluesky}, {collab.discord}, {collab.aliases}, {collab.notes} — from the first assigned collaborator only (see below). Note: {collab.youtube} resolves to the full URL (https://www.youtube.com/@handle), not just the handle.
• {my_variable} — from team-level variables or video-level variable value overrides

Collaborator Token Behavior with Multiple Collaborators

In VARIABLE, CONDITIONAL, CAMPAIGN, and freetext blocks: {collab.*} tokens always resolve to the first collaborator in the video's collaboratorIds list. If a video has multiple collaborators, tokens in non-COLLABORATOR blocks only reflect collaborator #1.

In COLLABORATOR blocks: the block is cloned once per collaborator, each clone resolved against that collaborator's data, then joined with a blank line. This is the correct way to list multiple collaborators — one COLLABORATOR block produces one entry per person.

Practical rule: use a COLLABORATOR block whenever the content should repeat for each collaborator. Use {collab.*} tokens in other block types only when you have exactly one collaborator, or you intentionally want only the first.

Date Token Format Overrides

Date tokens ({video.scheduledAt} and {video.recordingDate}) support an inline format string using | as a separator:

{video.scheduledAt|DD.MM.YYYY}   → e.g. 05.03.2024
{video.recordingDate|MMMM D, YYYY} → e.g. March 5, 2024

Available format tokens: YYYY (4-digit year), YY (2-digit), MMMM (full month), MMM (short month), MM (zero-padded month), M (month), DD (zero-padded day), D (day).

Without an inline override, the team's date format setting is used. If no team format is set, the default is YYYY-MM-DD. If the date field is not set on the video, the token resolves to an empty string.

No other tokens support the |format syntax — it is silently ignored on non-date tokens.

Freetext Entries

In the video editor, users can add freetext sections directly in the block order without creating a named block. These appear as free-form text areas in the editor and are stored with IDs prefixed freetext:.

Developer Perspective

Render Path

1. VideoRenderService.render(videoId) fetches all data
2. Builds ordered list of blocks from VideoConfig.blockOrder
3. Appends active CAMPAIGN blocks at the end (regardless of order)
4. For each block: applies blockOverrides, resolves tokens
5. Joins blocks with blank lines (unless compact: true)
6. Returns { rendered: string, hash: string }

Key Files

• backend/src/shared/render-engine/video-render.service.ts — data fetching + orchestration
• backend/src/shared/render-engine/render-engine.service.ts — pure rendering logic
• backend/src/shared/system-variables/system-variables.registry.ts — system token registry

Adding a New System Token

1. Add the token to SYSTEM_VARIABLES[] in system-variables.registry.ts
2. Add it to SYSTEM_VARIABLE_TOKENS Set
3. Implement resolution in the appropriate resolver in RenderEngineService
4. Without step 2, resolveVariables() will attempt to resolve it as a team/video variable and fail silently

Block Versioning

DescriptionBlock has a BlockVersion history table. Every content change creates a new version snapshot. Version number increments on each save.

Related

• 07 - Render Engine (architecture)
• 03 - Blocks API
• 04 - Templates API
• 06 - Collaborators