Episode format reference

Every key of episode.yaml, generated from the schema that validates it (episodeJsonSchema() in packages/core/src/jsonschema.ts). Objects are strict: an unknown key is error V-1 with a "did you mean" hint. reelforge schema writes the same schema as JSON for editor autocompletion.

Type time is a time expression: 12.5s, l7, l7.end, l7:'word', l7:'word'#2, l7.3, @scene, @scene.end, each with an optional offset such as +0.4. See Writing episodes for examples and the components reference for props.

Episode identity: meta

Key	Type	Default	Required	Limits	Description
meta	object		yes		Episode identity and publishing texts
meta.id	string		yes	pattern ^[a-z0-9][a-z0-9_-]*$	Slug of the episode (folder name)
meta.series	string	""			Series name shown in the header
meta.title	string	""			Episode title
meta.episode	integer	1		≥ 1	Episode number shown in the header
meta.preset	string	"tiktok"			Platform layout: tiktok, reels, shorts or your own preset
meta.theme	string	"default"			Theme name in themes/, or a relative path
meta.lang	string	"ar-EG"			Voice-over language, e.g. en-US (left to right) or ar-EG (right to left)
meta.publish	object				Texts written to out/publish.md
meta.publish.cover	string				Short cover text
meta.publish.caption	string				Post caption
meta.publish.hashtags	string[]	[]			Hashtags
meta.publish.pinned	string				Pinned comment

Audio: audio

Key	Type	Default	Required	Limits	Description
audio	object	{}			Voice, sound effects and mastering
audio.voice	string	"voice.wav"			Voice recording, relative to the episode folder
audio.sfx	auto | none | manual	"auto"			auto: components play their default sounds; manual: only listed sounds
audio.sfx_gain_db	number	-16		≥ -60, ≤ 12	Sound effect level in dB
audio.duck	boolean	true			Lower the effects under the voice
audio.denoise	boolean	false			Remove background noise from the voice (RNNoise)
audio.extra	object[]	[]			Extra sounds at given times
audio.extra[].at	time		yes
audio.extra[].sound	whoosh | hit | ding | err | glitch | tick | tap | typing		yes
audio.extra[].gain_db	number

Script: script

Key	Type	Default	Required	Limits	Description
script	object[]		yes	min 1 items	Spoken lines; ids default to l1, l2, …
script[].id	string			pattern ^[A-Za-z_][A-Za-z0-9_]*$	Line id used in time expressions
script[].text	string		yes		What you say, one sentence
script[].caption	string	"auto"			auto, none or a custom caption text
script[].break	string[]	[]			Force a caption break before these words

Chapters: chapters

Key	Type	Default	Required	Limits	Description
chapters	object[]	[]			Chapter labels on the progress bar and in publish.md
chapters[].at	time		yes
chapters[].label	string		yes

Scenes: scenes

Key	Type	Default	Required	Limits	Description
scenes	object[]		yes	min 1 items	Scenes in order; each starts at a time and ends where the next starts
scenes[].id	string		yes	pattern ^[A-Za-z_][A-Za-z0-9_]*$
scenes[].at	time		yes		Start time (usually a line, e.g. l3)
scenes[].end	time				End time (default: next scene start)
scenes[].glow	string | object[]				Background glow color, or a list of timed colors
scenes[].glow[].at	time		yes
scenes[].glow[].color	string		yes
scenes[].transition	crossfade | cut | slide-up | zoom | push | blur	"crossfade"			How the scene replaces the previous one
scenes[].camera	still | drift | push-in | pull-out	"still"			One slow camera move across the scene
scenes[].layout	stage | full	"stage"			stage (between header and captions) or full (whole canvas)
scenes[].row	object				Lay out elements side by side
scenes[].row.gap	integer			≥ 0
scenes[].row.align	start | center | end
scenes[].row.x	integer
scenes[].row.y	integer
scenes[].row.w	integer			> 0
scenes[].row.h	integer			> 0
scenes[].column	object				Stack elements vertically
scenes[].column.gap	integer			≥ 0
scenes[].column.align	start | center | end
scenes[].column.x	integer
scenes[].column.y	integer
scenes[].column.w	integer			> 0
scenes[].column.h	integer			> 0
scenes[].columns	integer			≥ 1, ≤ 6	Split the stage into lanes (elements pick one with col)
scenes[].gutter	integer			≥ 0

Elements: scenes[].elements

Key	Type	Default	Required	Limits	Description
scenes[].elements	object[]	[]			Components shown in the scene
scenes[].elements[].use	string		yes		Component name (see the components reference)
scenes[].elements[].id	string			pattern ^[A-Za-z_][A-Za-z0-9_-]*$	Element id (for arrows, states and the editor)
scenes[].elements[].props	map	{}			Component props; strict per component
scenes[].elements[].place	object				Box in stage coordinates (1080 × 1000)
scenes[].elements[].place.x	integer
scenes[].elements[].place.y	integer
scenes[].elements[].place.w	integer			> 0
scenes[].elements[].place.h	integer			> 0
scenes[].elements[].place.center	boolean
scenes[].elements[].place.anchor	top | bottom | center | left | right
scenes[].elements[].place.margin	integer
scenes[].elements[].size	object				Size inside a row/column helper
scenes[].elements[].size.w	integer			> 0
scenes[].elements[].size.h	integer			> 0
scenes[].elements[].col	integer			≥ 0
scenes[].elements[].layer	base | overlay				overlay draws on top and skips the overlap rule (V-8)
scenes[].elements[].z	integer
scenes[].elements[].enter	object				When and how the element appears
scenes[].elements[].enter.at	time				Enter time, best on a word: "l3:'bucket'"
scenes[].elements[].enter.anim	pop | rise | slide-l | slide-r | fade | draw | type | count | flip | glitch | stamp | zoom | blur | wipe | spring | drop | reveal | none				Enter animation
scenes[].elements[].enter.dur	number			> 0
scenes[].elements[].enter.ease	smooth | snappy | gentle | linear				Easing curve
scenes[].elements[].enter.s0	number
scenes[].elements[].enter.dy	number
scenes[].elements[].enter.dist	number
scenes[].elements[].enter.cps	number			> 0
scenes[].elements[].enter.caret	boolean
scenes[].elements[].enter.rot	number
scenes[].elements[].enter.amp	number
scenes[].elements[].exit	object				When and how the element leaves
scenes[].elements[].exit.at	time		yes
scenes[].elements[].exit.anim	fade | pop | rise | sink | slide-l | slide-r | zoom | blur | wipe | none
scenes[].elements[].exit.dur	number			> 0
scenes[].elements[].states	object[]	[]			Prop changes over time
scenes[].elements[].states[].at	time		yes
scenes[].elements[].states[].set	map		yes
scenes[].elements[].fx	object[]	[]			Effects: shake, flash, glitch, pulse, bump
scenes[].elements[].fx[].at	time		yes
scenes[].elements[].fx[].do	shake | flash | glitch | pulse | bump		yes
scenes[].elements[].fx[].amp	number
scenes[].elements[].fx[].dur	number			> 0
scenes[].elements[].fx[].color	string
scenes[].elements[].fx[].rate	number			> 0
scenes[].elements[].fx[].target	self | camera
scenes[].elements[].fx[].sound	whoosh | hit | ding | err | glitch | tick | tap | typing | none
scenes[].elements[].sfx	auto | none | object[]	"auto"			none, or a list of sounds at times
scenes[].elements[].sfx[].at	time		yes
scenes[].elements[].sfx[].sound	whoosh | hit | ding | err | glitch | tick | tap | typing		yes
scenes[].elements[].sfx[].gain_db	number