Page 1 of 25

System Requirements Document

1. Introduction

This System Requirements Document defines the Mantrian Global AI Creative Studio / YouTube Builder / Shorts Engine. The engine generates 30–45 second vertical YouTube Shorts/Reels from a transcript, a prompt/topic, a YouTube URL, or a file upload.

The product targets output at 1080x1920, 9:16, approximately 30–45 seconds, with professional voiceover, synchronized captions, premium futuristic cinematic visuals, practical/real-world/monetizable subject matter, and visuals tightly synchronized with narration.

The user's explicit directive for this build is to build the best world-class Shorts engine without any premium subscriptions. The user is satisfied with the current voiceover and captions; the remaining problem is visual generation and direction. The engine must reach a world-class commercial-director standard, framed by the user as: "If I give you a one-billion-dollar budget, how would you make the shot?" The desired output must feel like a premium AI-generated commercial, not a low-budget stock-footage assembly.

Futuristic is a STYLE, not a SUBJECT. The engine must not equate futuristic with robots, humanoids, holograms, glowing brains, generic neural networks, or blue nodes unless the narration explicitly requires them.

Page 2 of 25

2. System Overview

The Shorts Engine is a local, Windows/PowerShell-based Python pipeline driven by a CLI entry point. It ingests text, transcript, YouTube URL, or file upload; produces a creative treatment and story meaning; converts meaning into visual events and cinematic shots; selects a visual medium per shot; sources or generates exact assets; applies camera and editorial direction; renders a vertical Short; and runs director-level QC.

The authoritative creative contract is the shot contract. Search queries are execution mechanisms only and cannot override creative intent. Pexels and Pixabay are suppliers, not directors. Stock footage may be used only when it is an exact semantic match. When exact footage is unavailable, the engine must generate the shot or use deliberate cinematic procedural/Blender fallback.

The rendered MP4 is the source of truth. Rendered artifact > manifest > tests. The engine must not accept "tests pass," semantic relevance scores, "director QC passes," or "six mediums used" as proof of creative quality.

The system runs on a free-tier architecture with no premium subscriptions and no paid services unless explicitly approved. Media sources are Pexels Video, Pixabay Video, AVRO free-tier providers, optional AI image fallback, and optional AI video providers such as Fal/Runway when configured. Blender is installed locally. DaVinci Resolve is installed locally but is not integrated as an automatic renderer.

Page 3 of 25

Source Content Inventory

Identity: chat_media/1e085730-bcee-495b-97f9-5c1905cee686/c1211bc1_MANTRIAN_SHORTS_ENGINE_COMPLETE_HANDOFF.txt — Mantrian Shorts Engine Complete Handoff.
Authority and uses: Authoritative uploaded continuation/handoff document used as a content source, domain context, and feature reference alongside this SRD.
Media reference: Uploaded on 2026-09-19T18:57:50.964505+00:00; source path: chat_media/1e085730-bcee-495b-97f9-5c1905cee686/c1211bc1_MANTRIAN_SHORTS_ENGINE_COMPLETE_HANDOFF.txt.
Content status: The complete uploaded document text is unavailable in this SRD input. Requirements attributed to the handoff are represented in this SRD; any source facts not explicitly represented here remain unverified and MUST NOT be invented.

3. Functional Requirements as Story Points

3.1 Ingestion and Generation Modes

As a creator, I want to generate a 30–45 second vertical YouTube Short/Reel so that I can publish to Shorts/Reels.
As a creator, I want to generate a Short from a transcript so that spoken content can be converted into a vertical video.
As a creator, I want to generate a Short from a prompt/topic so that I can start from a written idea.
As a creator, I want to generate a Short from a YouTube URL so that an existing video can seed the Short.
As a creator, I want to generate a Short from a file upload so that external source material can be used as input.
As a creator, I want to run python main.py short --text ... --duration ... --count ... --style ... --debug so that generation is repeatable from the command line.
As a creator, I want the exact acceptance render command to execute with the specified text, --duration 45, --count 1, --style futuristic, and --debug so that final acceptance is reproducible.

Page 4 of 25

3.2 Output Format and Delivery Requirements

As a creator, I want output at 1080x1920 resolution so that the Short matches vertical platform specs.
As a creator, I want output at 9:16 aspect ratio so that the Short fills the vertical frame.
As a creator, I want output duration between approximately 30 and 45 seconds so that the Short fits platform norms.
As a creator, I want output rendered at 30fps so that motion is smooth and platform-compatible.
As a creator, I want professional voiceover in the output so that the Short feels broadcast-quality.
As a creator, I want synchronized captions in the output so that spoken narration is readable.
As a creator, I want existing good voiceover and captions preserved so that accepted quality is not regressed.
As a creator, I want premium futuristic cinematic visuals so that the Short feels like a high-end AI commercial.
As a creator, I want practical, real-world, monetizable content so that the Short has commercial value.
As a creator, I want visuals tightly synchronized with every spoken idea so that no narration is visually ignored.
As a creator, I want the engine to reach a world-class commercial-director standard so that output stands with premium AI-generated commercials.
As a creator, I want the engine to operate as if answering "If I give you a one-billion-dollar budget, how would you make the shot?" so that every shot is planned with maximum creative ambition.
As a creator, I want output quality comparable to Sora/Runway/Midjourney-like quality so that generated visuals match state-of-the-art generative aesthetics.
As a creator, I want output quality comparable to premium AI-product advertisements so that the Short looks like a brand-grade commercial.
As a creator, I want output quality comparable to cinematic commercial filmmaking so that framing, lighting, and motion read as professional film work.
As a creator, I want output that matches the supplied reference video's level of craft so that the engine closes the gap to the reference standard.

Page 5 of 25

3.3 Director Layers

As a creator, I want a STORY DIRECTOR layer so that narration is converted into story meaning before any visual is chosen.
As a creator, I want a VISUAL CONCEPT DIRECTOR layer so that visual ideas are derived from meaning rather than keywords.
As a creator, I want a SHOT DIRECTOR layer so that every visual idea becomes a concrete, filmable cinematic shot.
As a creator, I want a CAMERA / MOTION DIRECTOR layer so that camera movement carries narrative and emotional purpose.
As a creator, I want a VISUAL MEDIUM SELECTOR so that each shot is rendered in the correct medium (real footage, device shot, UI simulation, motion graphics, hybrid composite, procedural render, or AI generation).
As a creator, I want an EDIT DIRECTOR layer so that pacing, sequencing, and transitions are intentional.
As a creator, I want a RETENTION DIRECTOR layer so that engagement and watch-through are actively engineered.
As a creator, I want a DIRECTOR-LEVEL QC layer so that creative failures can be detected and rejected.
As a creator, I want a creative treatment generated before shot planning so that shots inherit a coherent concept.
As a creator, I want shot planning generated from the creative treatment so that planning is grounded in the concept.
As a creator, I want shot-originated semantic queries so that asset searches derive from shot intent.
As a creator, I want medium selection performed per shot so that each shot gets the right execution mode.
As a creator, I want continuity determined per shot so that adjacent shots connect.
As a creator, I want anti-repetition rules applied across shots so that no two shots repeat needlessly.
As a creator, I want motion directives attached to shots so that movement is specified, not incidental.
As a creator, I want a CTA included where appropriate so that the Short drives follow-through.

Page 6 of 25

3.4 Pipeline and Shot Contract

As a creator, I want the pipeline to follow NARRATION → STORY MEANING → VISUAL EVENT → CINEMATIC SHOT → MEDIUM/EXECUTION → EXACT ASSET OR GENERATION → CAMERA → EDIT RHYTHM → RENDER → DIRECTOR QC so that creative intent survives to the render.
As a creator, I want the engine to reject the bad pipeline NARRATION → KEYWORDS → STOCK SEARCH → FIRST RELEVANT CLIP → LOOP/ZOOM → RENDER so that keyword-matching is not the visual logic.
As a creator, I want the engine to ask "what should the viewer SEE to understand and FEEL this idea?" rather than "what Pexels video matches these words?" so that visual relevance is semantic, not lexical.
As a creator, I want visual keywords to never stand in for a Visual Concept Director so that concept creation is a real layer.
As a creator, I want lexical query relevance to never be treated as visual relevance so that scoring does not mislead acceptance.
As a creator, I want the shot contract to be authoritative so that downstream search queries cannot override creative intent.
As a creator, I want search queries to be execution mechanisms only so that the contract remains the source of creative truth.
As a creator, I want the shot contract to propagate through the pipeline so that no stage silently flattens it.
As a creator, I want collapsible shot contracts to stop collapsing into literal_see/composition and then flattening so that shot detail is preserved end to end.
As a creator, I want literal workflow decomposition so that workflow-heavy narration becomes a proper sequence.
As a creator, I want deterministic proof-card fallback available so that missing assets degrade safely.
As a creator, I want the engine to stop forcibly overwriting the medium for scenes with three or more clauses with a fixed sequence such as hybrid_composite, simulated_ui, motion_graphics, simulated_ui, hybrid_composite so that complex workflows are not automatically forced into deterministic graphics.
As a creator, I want multi-action sentences to become sequences of visual actions so that a single narration line yields multiple shots.
As a creator, I want every spoken idea to have a corresponding visual EVENT so that narration and image are one.
As a creator, I want every shot to have a unique visual reason so that no shot is filler.

Page 7 of 25

3.5 Per-Shot Contract Attributes

As a creator, I want every shot to receive a defined narrative purpose.
As a creator, I want every shot to receive a defined emotion.
As a creator, I want every shot to receive a defined visual objective.
As a creator, I want every shot to receive a defined subject.
As a creator, I want every shot to receive a defined physical action.
As a creator, I want every shot to receive a defined cause.
As a creator, I want every shot to receive a defined action.
As a creator, I want every shot to receive a defined result.
As a creator, I want every shot to receive a defined shot type.
As a creator, I want every shot to receive defined framing.
As a creator, I want every shot to receive defined camera direction.
As a creator, I want every shot to receive defined lens/depth direction.
As a creator, I want every shot to receive defined lighting direction.
As a creator, I want every shot to receive defined foreground/background direction.
As a creator, I want every shot to receive a defined transition relationship.
As a creator, I want every shot to receive defined continuity requirements.
As a creator, I want every shot to receive defined visual proof.
As a creator, I want every shot to receive a defined asset strategy.
As a creator, I want every shot to receive a defined fallback strategy.

Page 8 of 25

3.6 Visual Mediums and Asset Sourcing

As a creator, I want Pexels Video sourcing so that provider footage can be used when it is an exact semantic match.
As a creator, I want Pixabay Video sourcing so that a second provider can supply exact matches.
As a creator, I want AVRO free-tier provider support so that additional free media can be sourced.
As a creator, I want optional AI image fallback so that missing assets can be generated instead of faked with stock.
As a creator, I want optional AI video provider support (Fal/Runway) when configured so that real AI video generation is used when actually available.
As a creator, I want AI image fallback enabled so that image generation is available as a fallback medium.
As a creator, I want AI art preferred when configured so that generative visuals take priority where appropriate.
As a creator, I want Pexels and Pixabay treated as suppliers, not directors, so that the shot contract drives selection.
As a creator, I want stock media used only when it is an exact semantic match so that generic filler never ships.
As a creator, I want the engine to never use generic person, phone, office, business, technology, or robot footage as filler so that no irrelevant clip reaches the render.
As a creator, I want the engine to generate the shot or use deliberate cinematic procedural/Blender fallback when exact footage is unavailable so that a gap never becomes irrelevant stock.
As a creator, I want the engine to stop retrying generic stock after provider failure on specific workflow shots so that failed exact matches fall through to generation rather than filler.

Page 9 of 25

3.7 Cinematic Grammar and Editorial Rules

As a creator, I want the preferred workflow grammar REAL WORLD HOOK → DEVICE/EVENT → DIGITAL ACTION → STATE CHANGE → NEXT ACTION → RESULT → HUMAN PAYOFF so that workflow Shorts read as a coherent story.
As a creator, I want cause/action/result events to drive sequence construction so that each beat shows progression.
As a creator, I want cinematic scales applied where appropriate so that shot size supports meaning.
As a creator, I want camera language visibly executed so that declared movement actually appears in the render.
As a creator, I want hybrid workflow sequencing so that a shot can move between real-world and digital contexts.
As a creator, I want deterministic hybrid/device execution when it serves the shot so that hybrid moments are handled deliberately.
As a creator, I want continuity maintained across shots so that the viewer never loses spatial or logical thread.
As a creator, I want hook/payoff rules applied so that the opening earns attention and the ending delivers.
As a creator, I want the hook to be a film event, not a title card, so that the first seconds are cinematic.
As a creator, I want pattern interrupts to be motivated so that cuts have in-story reasons.
As a creator, I want visual storytelling at the level of the reference video so that the Short is narrated by images.
As a creator, I want visible camera movement at reference-video level so that motion is purposeful.
As a creator, I want device interaction shown on screen so that software actions are visible, not described.
As a creator, I want UI integration shown at reference-video level so that interfaces are integrated into the cinematic image.
As a creator, I want depth in the frame so that shots have foreground/background separation.
As a creator, I want scale changes across the sequence so that rhythm varies visibly.
As a creator, I want match cuts so that transitions are editorially motivated.
As a creator, I want motivated transitions so that cuts are earned by story logic.
As a creator, I want a real-world → digital → real-world flow so that digital action is anchored in physical reality.
As a creator, I want the engine to never ping-pong clips so that footage is not played forward then backward.
As a creator, I want the engine to never reverse a clip to extend duration so that duration is never faked.
As a creator, I want the engine to never repeatedly loop a tiny source window so that reuse is not visible.
As a creator, I want clips not to be reused so that no source appears as filler in multiple shots.
As a creator, I want the engine to stop looping a clip multiple times before moving on so that pacing comes from editorial rhythm.
As a creator, I want the engine to stop producing arbitrary cuts so that edits follow the beat.
As a creator, I want the engine to stop producing a static-image slideshow, including prompt/topic mode outputs made of static images with zoom/fade, so that output is genuinely cinematic.
As a creator, I want full-screen UI not overused so that the Short does not collapse into interface graphics.
As a creator, I want no generic robots so that abstract AI imagery does not substitute for meaning.
As a creator, I want no abstract AI imagery so that the shot contract's literal visual is honored.
As a creator, I want engagement engineered as a first-class requirement so that the output maintains attention throughout.

Page 10 of 25

3.8 Deterministic UI / Workflow / Graphic Scenes and Debug Label Removal

As a creator, I want deterministic UI/workflow scenes available so that email, calendar, CRM, and workflow state changes can be rendered deterministically when the shot calls for it.
As a creator, I want an email deterministic scene that shows email received → processing → understood so that inbox events are visually represented.
As a creator, I want a calendar deterministic scene that shows calendar searching → slot selected → match found so that scheduling is visually represented.
As a creator, I want a CRM card deterministic scene that shows CRM stale → fields updated → saved so that CRM state changes are visually represented.
As a creator, I want a workflow deterministic scene that shows workflow received → processing → action → complete so that process completion is visually represented.
As a creator, I want starting and ending state shown in deterministic UI scenes so that state change is legible.
As a creator, I want a PROCESS indicator in deterministic UI scenes so that in-progress state is visible.
As a creator, I want REQUEST / UNDERSTAND / RESPOND text elements in deterministic UI scenes so that the understand-respond cycle is labeled.
As a creator, I want a progress bar in deterministic UI scenes so that completion fraction is visible.
As a creator, I want the "MANTRIAN / LIVE STATE" overlay label kept out of the final video so that internal tooling labels do not ship.
As a creator, I want internal debug labels removed from the final video so that the output looks like a premium commercial, not an internal build.
As a creator, I want graphic scene titles such as "THE NEXT MOVE", "PRODUCT VIEW", "THE IDEA", "MANTRIAN", "CONNECTED SYSTEM", and "MOTION" never used as a substitute for cinematic footage so that placeholder graphic grammar does not reach the viewer.
As a creator, I want deterministic hybrid scenes to stop drawing a synthetic dark device/card with PIL as the finished shot so that deterministic output is not presentation-card grammar.
As a creator, I want no presentation cards used as cinematic footage so that UI/graphic grammar never stands in for film.
As a creator, I want the deterministic compositor to stop bypassing Pixabay/stock through hardcoded UI/workflow routes when an exact match exists so that provider footage is reachable for those shots.
As a creator, I want the deterministic renderer route to stop bypassing Pexels/Pixabay unconditionally so that exact-match stock is considered before deterministic fallback.
As a creator, I want build_execution_scene() to stop bypassing provider asset paths for deterministic execution so that provider assets can be used when matched.
As a creator, I want the previous blue/black panel grammar removed from renders so that the rejected visual language does not return.

Page 11 of 25

3.9 Captions, Titles, and Frame Presentation

As a creator, I want phrase-level captions rather than aggressive word-by-word popping so that captions read smoothly.
As a creator, I want title and spoken caption layers separated so that narration text is not duplicated as a title.
As a creator, I want duplicate caption layers eliminated so that only one caption layer renders.
As a creator, I want lower captions not clipped so that all caption text is fully visible.
As a creator, I want the TITLE_CARD_S = 0 configuration to not cause spoken text to become a giant feature/title layer so that title-card suppression does not corrupt captions.
As a creator, I want the giant title layer removed from output so that narration text does not obscure the frame.

3.10 Rendering and Render Routing

As a creator, I want MoviePy as the configured renderer so that rendering works on the current free-tier setup.
As a creator, I want Blender discovery so that the engine can find and use a locally installed Blender.
As a creator, I want Blender procedural rendering so that procedural shots can be generated locally.
As a creator, I want Blender fallback to create actual animated cinematic scenes, not a single PNG so that the fallback is genuinely usable as footage.
As a creator, I want Blender-enabled rendering behind a config flag so that Blender can be turned on or off.
As a creator, I want the shot-aware ffmpeg render path to fully preserve the shot contract so that detail is not normalized away.
As a creator, I want the ffmpeg render path to stop normalizing and hard-cutting clips so that editorial intent survives.
As a creator, I want micro-shot timing so that shot lengths match the beat.
As a creator, I want minimum duration enforced so that Shorts meet platform and narrative requirements.
As a creator, I want a minimum short duration of 30 seconds enforced so that outputs meet the configured floor.
As a creator, I want routing/QC so that each shot is dispatched to the correct render path.
As a creator, I want DaVinci Resolve left as a locally installed, non-integrated tool so that no unapproved automatic renderer enters the pipeline.

Page 12 of 25

3.11 Validation, Director QC, and Acceptance

As a creator, I want director QC to be capable of failing creative failures so that QC is not a rubber stamp.
As a creator, I want cinematic QC on generated sequences so that cinematic quality is checked, not just technical validity.
As a creator, I want motion validation to stop passing a moving presentation card just because frame-difference is sufficient so that technical validity does not equal creative quality.
As a creator, I want rendered-frame extraction so that QC can inspect actual frames.
As a creator, I want the rendered artifact treated as the source of truth so that rendered artifact > manifest > tests.
As a creator, I want to refuse "tests pass" as acceptance proof.
As a creator, I want to refuse "semantic relevance = 0.89" as acceptance proof.
As a creator, I want to refuse "director QC passes" as acceptance proof.
As a creator, I want to refuse "six mediums used" as acceptance proof.
As a creator, I want a mute-audio, hide-captions acceptance test so that visual comprehension is verified independently of narration.
As a creator, I want the mute-audio/hide-captions test to communicate CUSTOMER REQUEST → EMAIL → UNDERSTANDING → CALENDAR → AVAILABLE SLOT → REPLY → CRM → TASK → COMPLETION → HUMAN PAYOFF so that the workflow story is legible from images alone.
As a creator, I want the mute-audio/hide-captions success test to communicate: a customer sends a request, the system receives it, the AI understands it, the calendar is checked, a free slot is found, the reply is sent, the CRM is updated, a follow-up task is created, the workflow completes, and the human is freed for higher-value work.
As a creator, I want the acceptance output to look like a premium commercial, not person → phone → person → money → phone → office.
As a creator, I want the acceptance output to look like a premium commercial, not blue panel → UI card → node animation → UI card.
As a creator, I want the acceptance output to look like a premium commercial, not static image + zoom.
As a creator, I want the acceptance output to look like a premium commercial, not the same clip forward/backward.
As a creator, I want the acceptance output to have no repeated phone footage.
As a creator, I want the acceptance output to have no generic stock.
As a creator, I want the acceptance output to have no loops.
As a creator, I want the acceptance output to have no ping-pong playback.
As a creator, I want the acceptance output to have no presentation cards.
As a creator, I want the acceptance output to have no generic robots.
As a creator, I want the acceptance output to have no static-image slideshow.
As a creator, I want the acceptance output to preserve captions and voiceover.
As a creator, I want a multi-action narration line such as "It finds the open slot, books the meeting, creates all required tasks, and assigns them to the right person automatically" turned into a visual sequence: calendar search, busy slots rejected, available slot selected, booking confirmation, task creation, task assignment, completed state — never one generic clip.
As a creator, I want scene classification to stop misclassifying workflow narration (for example, CRM/email automation classified as motivation_self and given journal-writing or runner-silhouette imagery) so that narration context drives the visual route.
As a creator, I want malformed stock queries such as "small business owner finds finds open slot office close up" eliminated so that broken queries never reach providers.
As a creator, I want malformed stock queries such as "close up person performing complete real money walking out door task focused hands" eliminated so that broken queries never reach providers.
As a creator, I want verbs removed from query subjects so that provider queries describe shots, not actions-run-together.
As a creator, I want calendar and task actions to get explicit visual state so that scheduling/task steps have defined visuals.
As a creator, I want physical provider queries scored against the director's physical context rather than narration keywords alone so that scoring reflects shot intent.

Page 13 of 25

3.12 Inspection, Debug Bundle, and Continuation Workflows

As a continuation developer, I want the latest output bundle to include temp files, clips, director QC frames, metadata, debug data, scene manifest, and script so that every step of a render can be analyzed.
As a continuation developer, I want every step of the latest output bundle analyzed so that root causes are identified rather than assumed.
As a continuation developer, I want the newest output artifacts located, specifically short.mp4, metadata.json, validation.json, scene_manifest.json, director QC frames, the debug bundle, and clips.
As a continuation developer, I want to run git status so that uncommitted edits are identified.
As a continuation developer, I want to run git diff --stat so that edit scope is measured.
As a continuation developer, I want to run git diff -- engine/creative_director.py engine/literal_visuals.py engine/pipeline.py engine/assembler.py engine/scenes.py engine/cinematic.py engine/validation.py so that exact code changes are reviewed.
As a continuation developer, I want to run git log -1 --oneline so that the latest commit is known.
As a continuation developer, I want to inspect the actual MP4 and the complete bundle before changing code when the acceptance render finished.
As a continuation developer, I want to inspect the exact failure/log and not immediately start another expensive render when the acceptance render did not finish.
As a continuation developer, I want the engine to avoid wasting usage on broad architecture explanation so that effort goes to the decisive visual fix.
As a continuation developer, I want the project to run a single acceptance render using the exact acceptance command so that results stay comparable.
As a continuation developer, I want to avoid running a second render when the single authorized attempt exits without an artifact, and instead report that exact blocker.
As a continuation developer, I want environment probes to confirm PEXELS_API_KEY, PIXABAY_API_KEY, AI_IMAGE_FALLBACK, RENDERER, and BLENDER_ENABLED so that setup state is known before rendering.
As a continuation developer, I want to identify any edited file that is not clearly visible in review excerpts using git status/git diff so that no edit is missed.

Page 14 of 25

3.13 Configuration and Provider Setup

As a creator, I want PEXELS_API_KEY configured so that Pexels sourcing works.
As a creator, I want PIXABAY_API_KEY configured so that Pixabay sourcing works.
As a creator, I want AI_IMAGE_FALLBACK = true so that AI image fallback is available.
As a creator, I want PREFER_AI_ART = true so that AI art is preferred where configured.
As a creator, I want RENDERER = moviepy so that MoviePy is the default render path.
As a creator, I want BLENDER_ENABLED = true so that Blender procedural rendering is available.
As a creator, I want TITLE_CARD_S = 0 so that no title card is prepended.
As a creator, I want MIN_SHORT_DURATION_S = 30 so that outputs meet the minimum duration floor.
As a creator, I want LLM rotation Gemini → OpenRouter → Groq → xAI → Hugging Face → Cloudflare → OmniRoute → Ollama local so that free-tier LLM access continues through provider fallback.
As a creator, I want LLM rotation timeout behavior to be documented so that long LLM stages are not misdiagnosed as compositor failure.
As a creator, I want Blender located at C:\Program Files\Blender Foundation\Blender 5.2\blender.exe so that Blender renders resolve on this machine.
As a creator, I want DaVinci Resolve located at C:\Program Files\Blackmagic Design\DaVinci Resolve\Resolve.exe so that its local installation is known but not wired into automatic rendering.

3.14 Application Identity, Access, and Workstation Requirements

As a first-use Creator / Operator, I want self-service enrollment before protected generation work so that I can begin using the engine without an invitation or provisioning boundary.
As a returning Creator / Operator, Creative Director / Reviewer, or Continuation Developer, I want verification before accessing protected generation, render, review, or handoff work so that identity continuity is maintained across durable render records and output bundles.
As an authenticated user, I want protected application destinations for Generate, Renders, Render Details, Acceptance Review, Handoff, and Settings so that generation work, rendered artifacts, review decisions, continuation evidence, and provider configuration are not exposed publicly.
As a Creator / Operator, I want authorization to use Generate, Renders, Render Details, and Settings so that I can create, revisit, inspect, and configure my Shorts work.
As a Creative Director / Reviewer, I want authorization to use Acceptance Review so that creative acceptance and rejection remain a dedicated review responsibility.
As a Continuation Developer, I want authorization to use Generate, Render Details, and Handoff so that I can inspect, resume, and report on the accepted continuation workflow.
As an authorized user, I want secrets masked and never displayed in application pages, logs, render artifacts, or output bundles so that configured provider credentials are never exposed.
As a creator, I want environment probes for PEXELS_API_KEY, PIXABAY_API_KEY, AI_IMAGE_FALLBACK, RENDERER, and BLENDER_ENABLED, plus free-tier provider and LLM-rotation availability, completed before generation so that a render does not begin with an unknown execution setup.

4. User Personas

Page 15 of 25

4.1 Creator / Operator

The primary persona. Runs the CLI with text, transcript, YouTube URL, or file upload; sets duration, count, and style; requests futuristic output; and inspects the resulting MP4 and bundle. This persona is satisfied with voiceover and captions and is focused on visual quality, engagement, and cinematic output.

4.2 Creative Director / Reviewer

The persona applying the commercial-director standard. Performs the mute-audio/hide-captions acceptance test, judges the rendered artifact against reference-video craft (visual storytelling, camera movement, continuity, device interaction, UI integration, depth, scale changes, match cuts, motivated transitions, real-world → digital → real-world flow), and rejects outputs that fail creative QC.

4.3 Continuation Developer

The persona resuming work in a new account or session. Inspects repository state via git, locates the newest output artifacts, determines whether the acceptance render completed, inspects the MP4 and bundle before changing code, and continues from the exact documented state without restarting architecture.

Integration and provider systems — Pexels, Pixabay, AVRO free-tier providers, optional Fal/Runway AI video providers, the LLM rotation providers, Blender, MoviePy, ffmpeg, and DaVinci Resolve — act as system actors or outbound recipients, not as personas.

Page 16 of 25

4.4 Application Pages, Access, and Component Coverage

The application provides a cinematic control-room interface over the local Windows/PowerShell CLI pipeline. Landing, Login, and Sign Up are public. Generate, Renders, Render Details, Acceptance Review, Handoff, and Settings require authenticated access and the authorization defined in Section 3.14.

Page Content and Component Coverage

Landing: Explains that the Mantrian Global AI Creative Studio / YouTube Builder / Shorts Engine transforms text, transcript, YouTube URL, or file upload into a 30–45 second vertical Short/Reel at a commercial-director standard without premium subscriptions. It owns the immersive hero, product statement, PowerShell-style command field, directing-stage rail, and transitions into Login or Sign Up.
Login: Owns returning-user verification for Creator / Operator, Creative Director / Reviewer, and Continuation Developer and returns the verified user to their protected working destination.
Sign Up: Owns first-use self-service enrollment for the Creator / Operator before protected generation work begins.
Generate: Owns source intake for text, transcript, YouTube URL, or file upload; duration, count, style, and debug controls; environment/provider readiness; the generated script, treatment, shot contracts, and initiation of the single authorized acceptance render.
Renders: Owns the independently revisitable render history and browse view for short.mp4, metadata.json, validation.json, scene_manifest.json, director QC frames, debug bundle, clips, script, and temp files.
Render Details: Owns focused inspection of one rendered Short, with the MP4 presented as the acceptance source of truth alongside its shot contracts, director QC frames, validation, scene manifest, debug data, clips, script, and temp files.
Acceptance Review: Owns the Creative Director / Reviewer's mute-audio/hide-captions review of the rendered MP4, prohibited-artifact checks, creative rejection, and recorded creative failure regardless of test, relevance-score, or QC-pass status.
Handoff: Owns the Continuation Developer's repository inspection, newest-artifact discovery, acceptance-render completion determination, environment probes, exact-failure inspection, and exact-blocker report when no artifact exists.
Settings: Owns the free-tier provider configuration and masked status of PEXELS_API_KEY, PIXABAY_API_KEY, AI_IMAGE_FALLBACK, PREFER_AI_ART, RENDERER, BLENDER_ENABLED, TITLE_CARD_S, MIN_SHORT_DURATION_S, local Blender and DaVinci Resolve paths, and LLM rotation chain.

Landing Hero Motion Brief

Input → transformation → outcome thesis: Raw narration, transcript, URL, or uploaded source enters the directing pipeline; the system resolves story meaning into shot contracts, assets, camera direction, editorial rhythm, and QC; the outcome is a physically dominant finished 9:16 commercial Short.
Focal subject: A towering, slightly angled vertical film frame at approximately 82vh, occupying the right 58% of the viewport and showing one richly lit commercial frame with a warm orange practical highlight.
Visible layers: A narrow narration strip, camera-path arc, phrase-caption track with lime synchronization ticks, compact PowerShell command field, and far-left stage rail reading NARRATION → STORY → SHOT → EDIT → QC.
Composed first frame: Open on a black full-viewport production bay. The left 42% contains an oversized two-line Space Grotesk statement at 96px, with “SHORTS” clipped by a horizontal orange render bar; the 9:16 film frame and its editorial layers establish depth without cards, robots, neural imagery, or decorative holograms.
Opening and loop: Use Motion for React (motion/react) or GSAP for a staged cinematic opening: narration enters, the camera path draws, caption ticks synchronize, and the orange render bar resolves into the active film frame. In the restrained story loop, the playhead pulls layers through the frame, the active shot contract focuses while surrounding information recedes, and scanning light crosses the active frame; no floating particles or generic spinner loops are permitted.
Interaction: Hover or focus on a stage rail item may bring its corresponding editorial layer forward; activating the command field or primary action routes to authentication or generation without changing the hero's core narrative.
Responsive behavior: Preserve the vertical film frame as the focal element on narrow screens, stack the statement and command field ahead of it, and convert the stage rail and editorial layers into an ordered, readable process sequence without clipping caption tracks.
Reduced-motion fallback: Present the composed production-bay first frame with static layer positions, visible stage status, and no spatial transition, scanning light, autoplay, or continuous animation.

Page 17 of 25

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

Dimensionality and implementation: A real-time WebGL/R3F hero is required by the creative direction and MUST use a contained Three.js/React Three Fiber scene rather than a decorative 3D background.
Scene subject: A sculptural stack of sharply clipped 9:16 film frames, camera-path arcs, edit markers, narration strips, and phrase-caption strips arranged around the primary vertical commercial frame.
Spatial composition: The primary frame remains on the right at a slight angle; editorial layers sit materially in front of and behind it with restrained parallax, controlled charcoal occlusion, orange active-frame edge light, and lime synchronization ticks.
Story movement: On scroll, the hero frame turns edge-on and resolves into the central production workspace, as if a projector gate pulls a contact sheet into the directing console; this MUST be a crafted spatial transition, not a centered SaaS heading-and-button reveal.
Materials and lighting: Use near-black planes, charcoal depth, warm orange practical light, film-white type elements, and only restrained pale-cyan lens/timecode glints; never introduce a blue UI primary, neon node mesh, robot, humanoid, glowing brain, or hologram.
Performance and responsiveness: Keep the scene focused on one hero composition, pause or simplify offscreen and on constrained devices, and retain readable HTML text and controls outside the canvas.
Reduced-motion and non-WebGL fallback: Render the same composed first frame as layered DOM/SVG artwork with no automatic spatial movement while preserving the statement, film-frame hierarchy, command field, and stage rail.

5. Core User Flows

5.1 Creator Generates a Short from Text

Creator runs python main.py short --text "<prompt>" --duration 45 --count 1 --style futuristic --debug.
The engine ingests the text and produces a script with title, hook, stakes, body, and CTA.
The engine builds a creative treatment.
The engine extracts story meaning and visual events per spoken idea.
The engine produces a shot contract per shot with narrative purpose, emotion, visual objective, subject, physical action, cause, action, result, shot type, framing, camera, lens/depth, lighting, foreground/background, transition relationship, continuity, visual proof, asset strategy, and fallback.
The engine selects a medium per shot.
The engine sources exact assets from Pexels, Pixabay, AVRO, or AI image/video providers; if no exact match exists, it generates the shot or uses cinematic procedural/Blender fallback.
The engine applies camera direction, edit rhythm, continuity, anti-repetition, and motion directives.
The engine renders to 1080x1920, 9:16, 30fps, 30–45 seconds with voiceover and synchronized captions.
The engine runs director QC, extracts rendered frames, and writes the output bundle (MP4, metadata, validation, scene manifest, QC frames, debug, clips).

Page 18 of 25

5.1a Creator Enrolls or Returns to Protected Work

A first-use Creator / Operator opens Landing and selects Sign Up before attempting protected generation work.
The application completes self-service enrollment and establishes an authenticated session without exposing secrets.
A returning Creator / Operator, Creative Director / Reviewer, or Continuation Developer uses Login for verification.
The application authorizes the verified user only to the protected destinations assigned to their accepted workflow.
Before a Creator / Operator starts generation, Generate confirms environment probes and free-tier provider/LLM-rotation availability.
The Creator / Operator begins the generation workflow; a Creative Director / Reviewer proceeds to Acceptance Review; and a Continuation Developer proceeds to Handoff or the relevant Render Details record.

5.2 Creative Director Performs Acceptance

Reviewer mutes audio and hides captions.
Reviewer watches the rendered MP4 and checks comprehension of CUSTOMER REQUEST → EMAIL → UNDERSTANDING → CALENDAR → AVAILABLE SLOT → REPLY → CRM → TASK → COMPLETION → HUMAN PAYOFF.
Reviewer checks for absence of generic stock, loops, ping-pong playback, repeated phone footage, presentation cards, generic robots, and static-image slideshow.
Reviewer checks for presence of continuity, visible camera movement, match cuts, motivated transitions, device interaction, UI integration, depth, and scale changes.
Reviewer rejects the render if the artifact fails — regardless of tests, relevance scores, or QC pass status — and records the creative failure.

5.3 Continuation Developer Resumes Work

Developer runs git status, git diff --stat, git diff -- engine/creative_director.py engine/literal_visuals.py engine/pipeline.py engine/assembler.py engine/scenes.py engine/cinematic.py engine/validation.py, and git log -1 --oneline.
Developer identifies all recently edited files, including any file not clearly visible in prior review excerpts.
Developer locates the newest short.mp4, metadata.json, validation.json, scene_manifest.json, director QC frames, debug bundle, and clips.
If the acceptance render finished, the developer inspects the MP4 and the full bundle before changing any code.
If the acceptance render did not finish, the developer inspects the exact failure/log and does not immediately start another expensive render.
Developer reports the exact blocker if no artifact exists.

Page 19 of 25

5.4 Engine Recovers from Missing Exact Footage

A shot's asset strategy requires an exact semantic match.
Provider search returns no exact match.
The engine declines generic filler footage and stops retrying generic stock for that workflow shot.
The engine generates the shot or invokes cinematic procedural/Blender fallback.
Blender fallback produces an actual animated cinematic scene, not a single PNG.
The shot proceeds through camera, editorial rhythm, and render stages with the contract intact.

6. Visuals, Colors, and Theme

The source material specifies a premium futuristic cinematic theme but not a fixed color palette. The theme must serve the required visual quality and must avoid the rejected blue/black presentation-card grammar.

Base: deep near-black cinematic base with high dynamic range so screens, devices, and real-world environments read with contrast.
Palette: restrained, shot-motivated colors drawn from the real environment of each shot; no fixed category palette; no default blue-node/neural-network look.
Futuristic intent expressed through lighting, lens choice, depth, motion, and interface integration — not through robots, humanoids, holograms, glowing brains, generic neural networks, or blue nodes.
Real-world palette: natural office, device, and human-tone grading so business/workflow scenes feel practical and monetizable.
Digital palette: interface and state-change elements integrated into the frame rather than shown as flat cards.
Captions: readable, un-clipped, single-layer, phrase-level styling that does not duplicate narration as a title.
Debug/overlay styling: internal labels such as "MANTRIAN / LIVE STATE" and graphic titles such as "THE NEXT MOVE", "PRODUCT VIEW", "THE IDEA", "MANTRIAN", "CONNECTED SYSTEM", and "MOTION" are not permitted in the final video.

Application background: #090A0C dominant near-black void, approximately 68%, with #15171B charcoal working surfaces at approximately 22%; the generic indigo/blue-on-white SaaS template is forbidden.
Application signal colors: warm film-white text #F4F0E8, signal orange #FF5A36 for primary action and active render state, acid lime #B7F529 only for approved, passing, synchronized, and live states, and restrained #A8E8E0 at 10% opacity only for lens lines or timecode glints.
Application typography: Space Grotesk 600–700 with tight -0.045em tracking for decisive cinematic headings; IBM Plex Sans for body copy; IBM Plex Mono with tabular numerals for vertical-output labels and timecode.
Application shape language: deep rectangular planes with 14px outer radii, 8px internal control radii, hairline #31353C borders, sharply clipped 9:16 frame windows, and thin orange edge light only around the active render, selected shot, or current playhead.
Application layout: a three-rail directing workstation with ordered pipeline and stage status on the left, dominant 9:16 preview or shot canvas in the center, active shot contract/camera/source/QC proof on the right, and an editorial-score timeline along the bottom.
Application motion: use deliberate 500–900ms physical easing for scene transitions and 120–180ms feedback for controls; render states pulse as scanning light across a film frame, never as floating particles or generic loading spinners.

Page 20 of 25

7. Signature Design Concept

The signature design concept is the shot contract as the single source of creative truth, expressed through a real-world → digital → real-world cinematic flow.

Each shot's contract defines narrative purpose, emotion, visual objective, subject, physical action, cause, action, result, shot type, framing, camera, lens/depth, lighting, foreground/background, transition relationship, continuity, visual proof, asset strategy, and fallback. Every stage — medium selection, asset sourcing, camera, editing, rendering, QC — must honor this contract, and no keyword query may override it.

Signature behaviors that distinguish the engine:

Every spoken idea maps to a visual EVENT, not a keyword search.
The hook is a film event, not a title card.
Workflow narration is sequenced as REAL WORLD HOOK → DEVICE/EVENT → DIGITAL ACTION → STATE CHANGE → NEXT ACTION → RESULT → HUMAN PAYOFF.
Pexels and Pixabay are suppliers, never directors.
The MP4 is the proof; scores and passes are not.

Page 21 of 25

8. Interaction Model & Motion Direction

Camera movement must visibly execute meaningful cinematic language and must be declared per shot.
Motion must serve narrative and emotion; movement for its own sake is not acceptable.
Match cuts and motivated transitions are the preferred transition vocabulary.
Continuity is maintained between adjacent shots.
Multi-action sentences become motion sequences, not single holds.
Micro-shot timing controls rhythm; minimum duration prevents under-length output.
Ping-pong playback is prohibited.
Reversing a clip to extend duration is prohibited.
Repeatedly looping a tiny source window is prohibited.
Reusing clips across shots is prohibited.
Static-image slideshow output, including static images with zoom/fade, is prohibited.
Full-screen UI is used deliberately and not overused.
Frame depth (foreground/background separation) and scale changes are part of the motion language.
Pattern interrupts must be motivated by story logic.

Page 22 of 25

9. Non-Functional Requirements

Cost: free-tier architecture; no premium subscriptions; no paid services unless explicitly approved.
Security: no secret exposure at any point.
Platform: Windows / PowerShell execution environment.
Documentation: PROJECT.md must be updated after changes and any architecture work must not be restarted from scratch.
Toolchain discovery: Blender and DaVinci Resolve must be discoverable at their configured local paths.
Reliability: LLM rotation must tolerate per-provider timeout behavior without being misdiagnosed as a compositor failure.
Quality authority: the rendered artifact outranks manifest data and test results; rendered artifact > manifest > tests.
Quality standard: one-billion-dollar creative standard; premium AI-commercial quality; mute-audio/hide-captions comprehension.
Provider discipline: stock providers are used only for exact semantic matches; generic person/phone/office/business/technology/robot footage is never used as filler.
Continuation discipline: the engine must be resumable from a handoff state; no architecture restart; no duplicated expensive renders.
QC honesty: director QC must be able to fail a render on creative grounds, and motion validation must not pass a moving presentation card on frame-difference alone.
Usage economy: avoid wasting usage on broad architecture explanation; inspect before changing; one acceptance render at a time.

Page 23 of 25

10. Tech Stack

Language/runtime: Python.
CLI entry point: main.py with the short command and --text, --duration, --count, --style, --debug flags.
Platform shell: Windows / PowerShell.

Application UI: React + TypeScript cinematic control-room interface for Landing, authentication, generation, render inspection, acceptance review, handoff, and settings.
Application motion: Motion for React (motion/react) or GSAP for DOM/SVG interface choreography.
Landing 3D hero: Three.js with React Three Fiber (R3F) for the direction-derived, contained WebGL production-bay composition, with DOM/SVG fallback for reduced motion and unavailable WebGL.

Renderer: MoviePy (RENDERER = moviepy).
Shot-aware render path: ffmpeg_render.py.
Procedural/final fallback renderer: Blender (BLENDER_ENABLED = true), located at C:\Program Files\Blender Foundation\Blender 5.2\blender.exe.
Locally installed, non-integrated tool: DaVinci Resolve at C:\Program Files\Blackmagic Design\DaVinci Resolve\Resolve.exe.
Compositing/graphics utilities: PIL, used for composing shots (not as a substitute for cinematic footage).
Media providers: Pexels Video, Pixabay Video, AVRO free-tier providers.
Optional generative providers: AI image fallback (AI_IMAGE_FALLBACK = true), AI art preference (PREFER_AI_ART = true), and optional AI video providers (Fal/Runway when configured).
LLM providers (free-tier rotation): Gemini → OpenRouter → Groq → xAI → Hugging Face → Cloudflare → OmniRoute → Ollama local.
Engine modules: engine/creative_director.py, engine/cinematic.py, engine/literal_visuals.py, engine/pipeline.py, engine/assembler.py, engine/scenes.py, engine/scene_manifest.py, engine/validation.py, engine/blender_renderer.py, engine/api/pixabay.py, engine/api/avro.py.
Configuration: config.py.
Project documentation: PROJECT.md, AGENTS.md.

Page 24 of 25

11. Assumptions and Constraints

The project is the Mantrian Global AI Creative Studio / YouTube Builder / Shorts Engine.
Work continues from an existing codebase; architecture must not be restarted.
The single acceptance render was started but its completion/artifact was not confirmed before the previous session ended; the current project state and latest edits must be inspected first.
Three files were edited in the last session: engine/creative_director.py (+62 −16), engine/literal_visuals.py (+15 −11), and a third file not clearly identified in the review excerpt, which must be identified via git status/git diff.
Free-tier architecture is mandatory; no paid services unless explicitly approved.
No premium subscriptions are permitted as part of this build.
No secret exposure is permitted.
Execution environment is Windows / PowerShell.
PROJECT.md must be updated after changes.
Configuration: PEXELS_API_KEY configured; PIXABAY_API_KEY configured; AI_IMAGE_FALLBACK = true; PREFER_AI_ART = true; RENDERER = moviepy; BLENDER_ENABLED = true; TITLE_CARD_S = 0; MIN_SHORT_DURATION_S = 30.
Blender is installed locally; DaVinci Resolve is installed locally but not integrated as an automatic renderer.
The user is satisfied with voiceover and captions; only visual generation/direction is in scope for the fix.
Futuristic is a style, not a subject.
The MP4 is the source of truth for acceptance.
Don't restart architecture; inspect the current project and latest edits first.

Page 25 of 25

12. Glossary

Shorts Engine: The Mantrian YouTube Builder component that generates 30–45 second vertical Shorts/Reels.
Shot Contract: The per-shot authoritative specification covering narrative purpose, emotion, visual objective, subject, physical action, cause, action, result, shot type, framing, camera, lens/depth, lighting, foreground/background, transition relationship, continuity, visual proof, asset strategy, and fallback.
Visual Event: The concrete thing the viewer sees for a spoken idea.
Story Director: The layer that converts narration into story meaning.
Visual Concept Director: The layer that derives visual ideas from meaning rather than keywords.
Shot Director: The layer that turns a visual idea into a concrete cinematic shot.
Camera / Motion Director: The layer that assigns purposeful camera movement.
Visual Medium Selector: The layer that chooses the execution medium per shot.
Edit Director: The layer that governs pacing, sequencing, and transitions.
Retention Director: The layer that engineers engagement and watch-through.
Director-Level QC: The layer that can fail a render for creative — not only technical — shortcomings.
Ping-Pong: Playing a clip forward then backward within a shot; prohibited.
Presentation Card: Flat UI/graphic frame used as a stand-in for cinematic footage; prohibited.
Hybrid Composite: A shot combining real-world and digital/device elements.
UI Simulation: A deterministic interface rendering used as a shot medium.
Procedural Fallback: A locally generated cinematic scene (for example via Blender) used when no exact asset exists.
Workflow Grammar: REAL WORLD HOOK → DEVICE/EVENT → DIGITAL ACTION → STATE CHANGE → NEXT ACTION → RESULT → HUMAN PAYOFF.
Acceptance Test: Mute audio, hide captions, and verify the viewer still understands the workflow story.
Free-Tier Rotation: The ordered LLM/provider fallback chain operating without paid tiers.
Director QC Frames: Extracted render frames used to inspect actual output.
Output Bundle: The generated short.mp4, metadata.json, validation.json, scene_manifest.json, director QC frames, debug bundle, clips, script, and temp files.
PROJECT.md: The living project documentation that must be updated after changes.

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

No user flows yet.

The User Flow Agent will generate per-persona navigation diagrams after SRD updates.

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

No user flows yet.

The User Flow Agent will generate per-persona navigation diagrams after SRD updates.

shorts-engine

Comments (0)