Disclaimer: This is not an officially supported Google product.

Scene Machine: Storyboard-Driven Generative AI Video Ad Creation

Scene Machine is a Google Cloud-based, open-source workbench that leverages generative AI models to facilitate storyboard-driven video ad creation. While its primary use case is transforming product or service images (such as in retail, food delivery, or travel) into video ads, it also serves as a robust video prototyping platform for rapidly sharing and iterating on ideas.

TL;DR

• Production Speed: Automates and parallelizes scene generation, reducing a lengthy asset workflow to minutes.
• Target Audience: Advertisers, developers, and creative teams seeking a video generation workbench built natively on Google Cloud.
• Key Technology: Harnesses Gemini for intelligent prompt design and the Veo model for high-fidelity, parallel image-to-video generation. The entire workflow is orchestrated through a single intuitive web interface.

---

How it works • Technical Requirements • Deployment • Using Scene Machine • Alternatives • Developers' Guide

---

How it Works

< TL;DR • Top • Technical Requirements >

Tip

For a step-by-step guide with screen recordings, see docs/walkthrough.md.

Scene Machine guides users through four core stages to turn a set of static images into a video asset.

1. Setup (Storyboard Generation)

Upload images and business context (such as target audience and brand guidelines) to have Gemini automatically generate a structured, prompt-driven storyboard. Users can optionally apply predefined Creative Templates to guide scene structure, or start with an empty storyboard to build the timeline manually.

2. Storyboard (Video Generation & Scene-by-Scene Iteration)

The backend sends parallel video generation requests to Google's Veo model, significantly reducing the total time required. Users refine the ad by iterating on prompts and candidate variations scene-by-scene. The timeline can be expanded at any point by generating new scenes (via text-to-video or image-to-video) or by uploading existing video slates. This process is entirely non-destructive, allowing users to adjust, trim, and reorder assets without losing previously generated video scenes.

3. Composition (Transitions, Audio, and Brand Overlays)

Once scenes are finalized, users can enhance their ad in the Composition stage by adding transitions between scenes, custom background audio tracks (music or voice-overs), and precise pixel-positioned image overlays (such as brand logos).

4. Output (Rendering & Export)

Users compile all timeline assets by rendering the video, which is then available for review or direct MP4 download. Crucially, the history panel preserves all older rendered versions, enabling users to maintain and compare multiple creative variants (e.g., short vs. long versions) within the same project.

Technical Requirements

< How it Works • Top • Deployment >

To deploy this application, you need a project on Google Cloud Platform without any existing App Engine apps.

• Scene Machine's user interface is implemented as an Angular/TypeScript application running on App Engine.
• The actual processing is performed by Remix Engine, a modular Python application on Cloud Run. See the Developers' Guide for details.

Scene Machine sends workflow definitions to Remix Engine, which orchestrates its functional modules (e.g. turning images into videos) and reports back on results.

Google Cloud APIs Used

The following APIs are used by Scene Machine:

• Agent Platform API ( aiplatform.googleapis.com ): Used for accessing Gemini and Veo models for text, image, and video generation.
• API Gateway API ( apigateway.googleapis.com ): Used to create and manage the API Gateway that routes traffic to the backend.
• Artifact Registry API ( artifactregistry.googleapis.com ): Used to store the Docker container images for the backend service.
• Cloud Build API ( cloudbuild.googleapis.com ): Used to build the container images for Cloud Run.
• Compute Engine API ( compute.googleapis.com ): Enabled to guarantee the default Compute Engine service account exists (used for IAM role bindings during deploy).
• Cloud Tasks API ( cloudtasks.googleapis.com ): Used for managing task queues for asynchronous processing (e.g., video generation).
• Cloud Firestore API ( firestore.googleapis.com ): Used for the database storing application state and configurations.
• Cloud Run API ( run.googleapis.com ): Used to host and run the backend service.
• Service Control API ( servicecontrol.googleapis.com ): Required by API Gateway for managed services.
• Identity-Aware Proxy (IAP) API ( iap.googleapis.com ): Used to secure the application and manage access.
• Firebase API ( firebase.googleapis.com ): Used for Firebase integration, project management, and rules deployment.
• Identity Toolkit API ( identitytoolkit.googleapis.com ): Used for Firebase Authentication and managing user domains.
• App Engine Admin API ( appengine.googleapis.com ): The UI is deployed to App Engine.
• API Keys API ( apikeys.googleapis.com ): Used to create and manage API keys for the API Gateway (see deploy.sh line 229).
• Cloud Storage API ( storage.googleapis.com ): Used for storing assets, examples, and generated content.
• Cloud Logging API ( logging.googleapis.com ): Used for application logging (referenced in requirements.in ).

Please note that most of the APIs are enabled automatically when you run the deployment script. Cloud Storage and Cloud Logging are normally enabled by default. If your organization disables these APIs, you will need to enable them manually.

Permissions required for the deploying user

roles/owner on the target project is sufficient and is the simplest option.

If your organization's policies require narrower scopes, the following roles are the minimum required to deploy Scene Machine:

Role	Why it's needed
roles/apigateway.admin	API Gateway
roles/appengine.appAdmin	gcloud app deploy
roles/appengine.appCreator	gcloud app create
roles/artifactregistry.admin	Artifact Registry repo + images
roles/compute.viewer	View the services and setttings in the project
roles/cloudbuild.builds.editor	Cloud Build, triggered by gcloud run deploy --source (deploy.sh)
roles/cloudtasks.admin	Cloud Tasks queues
roles/datastore.admin	Firestore database creation
roles/firebase.admin	Firebase project/app/rules/storage link
roles/iam.roleAdmin	Create the custom SceneMachineUser role
roles/iam.serviceAccountAdmin	Service-account IAM bindings
roles/iam.serviceAccountUser	actAs during Run/App Engine deploy
roles/iap.admin	Configure IAP users
`roles/iap.settingsAdmin	Setup & configure IAP
`roles/oauthconfig.editor	Configuring the OAuth consent screen
roles/resourcemanager.projectIamAdmin	Project-level IAM bindings
roles/run.admin	Cloud Run services
roles/servicemanagement.admin	Create and deploy the API Gateway
roles/serviceusage.apiKeysAdmin	Create the API key
roles/serviceusage.serviceUsageAdmin	Enable APIs
roles/storage.admin	GCS buckets + objects

All users of the deployed app (including the deployer) require the custom projects/$PROJECT/roles/SceneMachineUser role — see Adding Users.

Deployment

< Technical Requirements • Top • Adding Users >

Prerequisites

• Google Cloud Project: A project on Google Cloud Platform with billing enabled and ideally without any existing App Engine apps. (Note: If an App Engine app already exists, deployment will proceed but will overwrite the default service, and you will not be able to change the region.)
• Permissions: We recommend having the Project Owner role on the Google Cloud project to conduct the deployment successfully.
• Node.js: Ensure you have Node.js (≥v22) installed.
• Git: Ensure you have git installed.
• Google Cloud SDK (gcloud): Ensure you have the Google Cloud CLI installed and initialized.
• Firebase Tools: Install with npm i -g firebase-tools.
• Firebase Login: Run firebase login to authenticate before beginning deployment.
• envsubst: Ensure you have envsubst installed (typically via the gettext package, e.g., sudo apt-get install gettext on Debian/Ubuntu, brew install gettext on macOS).

Step-by-Step Deployment

1. Clone the Repository

   git clone https://github.com/google-marketing-solutions/scene-machine
   cd scene-machine

2. Configure the Application

   • Create config.txt from the template:

     cp config.template.txt config.txt

   • Edit config.txt in your favorite editor (e.g., nano config.txt).

   Variables defined in config.txt: You can check available models and their regions to ensure you are using the most up to date models available in your selected region.

   Variable Name	Description	Recommended Values / Notes
   PROJECT	Your Google Cloud Platform Project ID.	Required
   REGION	Deployment region for various GCP resources.	e.g., us-central1
   GEMINI_MODEL	Text generation model for prompts and analysis.	gemini-3.5-flash
   GEMINI_REGION	Region for model invocation.	Check locations availability. Recommended global.
   VEO_MODEL	Video generation model.	veo-3.1-generate-001
   VEO_REGION	Region for Veo model invocation.	Check availability. Recommended global.
   IMAGE_MODEL	Image model for outpainting and image generation.	gemini-3-pro-image (Nano Banana Pro), gemini-3.1-flash-image (Nano Banana 2)
   IMAGE_MODEL_REGION	Region for image model invocation.	Check availability. Recommended global.
   API_GATEWAY_REGION	Region for API Gateway deployment.	Supported: us-central1, europe-west1, etc.
   APP_ENGINE_REGION	Region for App Engine application.	Supported locations listed in config.
   GCS_BUCKET	Storage bucket name for storing project images and assets.	Must be globally unique. Auto-generated by default.
   FIRESTORE_DB	Firestore database ID used by the backend modules.	Defaults to scene-machine.
   FIRESTORE_DB_UI	Firestore database ID used by the user interface.	Defaults to scene-machine-ui.
   ARTIFACT_REPO	Artifact Repository ID to store artifacts.	Defaults to scene-machine.
   API_GATEWAY	API Gateway ID for the application endpoint.	Defaults to scenemachine-api-gateway.
   TASKS_QUEUE_PREFIX	Prefix for Cloud Task queue names.	Max lengths apply. Support letters, hyphen, numbers.
   BACKEND_SERVICE_NAME	Service name for the application backend on GCP.	Defaults to remix-engine-backend.
   CUSTOM_DOMAIN	Custom domain for the application user interface.	Optional. e.g., scene-machine.my-company.com

   • Important Notes for Configuration:
     • Naming: Use alphanumerical names (with hyphens) for entities like databases.
     • Storage: If using an existing bucket, it must use a non-hierarchical namespace.
     • Locations: Match model availability (e.g. Veo might not be available in all regions). Check Google Cloud AI Platform documentation for locations.
     • Model Lifespans: Prefer using current models as older ones are discontinued over time. Check Google Cloud AI Platform documentation for model lifespans.

3. Execute Deployment

   The Scene Machine deployment consists of the backend services (databases, Cloud Run, API Gateway, queues) and the frontend UI application (Angular app on App Engine). By default, both components are built and deployed together using a single unified script:

   ./deploy.sh

   If you want to deploy only one of the components, you can pass the respective targeting flag:

   • Deploy Backend Only: ./deploy.sh --backend-only
   • Deploy UI Only: ./deploy.sh --ui-only

Tip

Troubleshooting Firebase deployment failures: If ./deploy.sh fails at the Firebase step with an error like Error: Project not found, it usually means the Firebase CLI cannot access the project or terms have not been accepted.

How to fix it:

1. Check Login: Ensure you are logged in by running firebase login in your terminal.
2. Manual Fallback (Accept Terms): If still failing, go to the Firebase Console.
3. Click Add Project and select your existing Google Cloud project from the dropdown list.
4. Follow the prompts to add Firebase resources. This process will guide you through accepting the necessary terms of service.
5. Once completed in the console, return to your terminal and re-run ./deploy.sh.

4. Set up OAuth consent screen:

   • In your Google Cloud console, go to API & Services > Credentials > OAuth consent screen.
   • Click Get Started.
   • Follow the steps to configure the consent screen. Choose a name for the application you're creating, e.g. Scene Machine.
   • You can choose Internal for the User Type if only users from your organization will use the app.

5. Add Firebase Sign-In Provider

   • Go to the Firebase console, select your project then click Authentication > Sign-in method.
   • Click Add new provider, choose Google then enable and save it.

6. Link Storage Bucket to Firebase — two sequential actions are required on the same Firebase Storage page.

   • Open the Firebase console → select your project → Databases & Storage → Storage.

   (a) Initialize Firebase Storage (one-time per project): - Click Get started and walk through the wizard. This creates the project's default <project>.firebasestorage.app bucket, which the Firebase CLI requires; without it the storage deploy fails with Firebase Storage has not been set up on project. - Production mode is fine. - Note: No-cost locations are only available in the USA.

   (b) Register your project bucket with Firebase Storage: - After (a) finishes the bucket dropdown appears at the top of the page (it doesn't exist until a bucket exists). - Click the dropdown → + Add bucket → Import existing Google Cloud Storage buckets. - Select your project bucket (the one referenced by GCS_BUCKET in config.txt) → confirm.

7. Deploy UI

   • If you did not deploy both backend and UI together, run:

     ./deploy.sh --ui-only

   • If requested, perform any required manual steps indicated by the script (e.g. linking buckets or configuring OAuth).

Tip

Steps 4–6 can be completed in parallel with ./deploy.sh --ui-only running. The script polls every 15s (or prompts you for the OAuth consent screen) and continues automatically once each manual action is done. After ./deploy.sh finishes you can launch ./deploy.sh --ui-only immediately and complete steps 4–6 in browser tabs while it waits.

Target Options and Non-Interactive (Agent) Deployment

By default, ./deploy.sh will deploy both the backend and UI. You can use targeting flags to deploy them individually:

• Deploy Backend Only: ./deploy.sh --backend-only
• Deploy UI Only: ./deploy.sh --ui-only
• Local Development Build: ./deploy.sh --ui-only --local (or ./deploy.sh --ui-only local) to build the Angular application files locally without triggering an App Engine deployment.

To run the script in a non-interactive/headless environment (such as an AI agent like Google Antigravity or Claude), use the --non-interactive flag to auto-confirm target configuration prompts:

./deploy.sh --non-interactive
# Or for a targeted headless deployment:
./deploy.sh --non-interactive --backend-only

Important

First-Time Deployments Cannot be Automated: An automated/headless deployment cannot be performed on a completely fresh project. The user must complete several manual setup actions on the Google Cloud and Firebase consoles (e.g., configuring the OAuth consent screen, enabling the Google sign-in provider, linking the bucket to Firebase Storage, and enabling IAP). When these checks are hit in headless mode, the script will abort immediately and output the URLs where you need to complete the setup. Once the project is manually initialized, subsequent deployments can be fully automated.

8. Set up Identity-Aware Proxy:
   • In the App Engine settings, under "Identity-Aware Proxy" select "Configure Now".
   • Turn on Identity-Aware Proxy for "App Engine app".
   • In the ⋮ menu, select "Settings", then "Custom OAuth", then "Auto-generate credentials".
     • Note: You will not need to download the credentials.

Once successfully deployed, the script will output the URL where Scene Machine is available. Note this down to open it in your browser.

To help debug problems with the deployment scripts, you can change their top line set -eu to set -eux, which will output every single command executed.

Adding Users

< Deployment • Top • Using Scene Machine >

Each person intending to use Scene Machine needs to be given the "Scene Machine User" role in the Google Cloud project in which the tool is deployed. The deployment script's final summary outputs a ready-to-paste gcloud command for this; you can also run it directly:

gcloud projects add-iam-policy-binding $PROJECT \
  --member="user:USER_EMAIL@example.com" \
  --role="projects/$PROJECT/roles/SceneMachineUser"

Or grant it via the IAM console → + Grant Access → enter user email → role: Scene Machine User (under "Custom") → Save.

Using Scene Machine

< Adding Users • Top • Caveats >

Tip

For a step-by-step guide with screen recordings, see docs/walkthrough.md.

It covers how to set up a project name and resolution, upload product images, apply compositional Creative Templates, trim video candidates, and add custom branding slates, transitions, audio tracks, and image overlays.

Technical problems

In case the tool does not behave as expected, there are various ways to narrow down the reason, though some require deep technical understanding to discover or even fix:

• In case of an error, a message appears with a link to a graphical view of the generation process. Here, red nodes indicate failures, so that clicking on the output connectors at the bottom of the topmost failing node might given an indication of what went wrong.
• In your web browser, check for error messages of the UI: in Chrome, for example, use the Console view of the Developer Tools.
• In GCP, you can use Error reporting or the Logs Explorer to look for problems. (You may need the latter as some problems are classified as a warning rather than an error.)
• In Firestore, each workflow execution has a collection named after the execution ID, which is prefixed by its date and time. Some debugging can hence take place by reviewing the content of pertinent entries in the database you configured (listed here).
• In Cloud Tasks, you can check if any of the used queues are full.

To get more information about the inner workings of the tool, refer to the Developers' Guide.

Caveats

< Using Scene Machine • Top • Alternatives to Scene Machine >

Data access

All saved projects are available to all other users of the same instance of Scene Machine.

Potential data loss

Projects are auto-saved a few seconds after each modification, but the state of ongoing generation processes isn't saved. So, if you navigate elsewhere or close the browser window

• only a few seconds after a change or
• while a storyboard or video is being generated,

that change or generation will be lost.

Storage accrual

By default, the tool does not delete any files from Cloud Storage: input files are retained because you might reuse them, intermediate content is kept to save time and cost in case the same input is processed again, and with output it's unclear until when you might need it. To limit the cost that comes with this accumulation, you can set up an object lifecycle rule by which content can be deleted based on files' relative age or absolute creation date. Rules can be defined here:

• https://console.cloud.google.com/storage/edit-bucket/[BUCKET_NAME]

An alternative to deletion is moving to a cheaper storage class that comes with lower availability and a generally lower price, albeit with a condition to store them for minimum periods.

Either option is problematic because a file's creation date says nothing about when it was last used, and there may be input files (like for a logo overlay) that are written once and needed 'forever'. For files larger than 128kB, Autoclass (which comes with its own little fee) can be enabled to auto-relegate objects after a period without use. This can be combined with lifecycle rules to actually delete files that were relegated.

Quotas

A Google Cloud project has certain throughput limits defined per service and location. Content-generation requests made more quickly than allowed by that quota are rejected and need to be retried. Scene Machine attempts to deal with this by assuming some default quotas and queueing tasks appropriately, the lowest-throughput class being that for video generation. Check out the documentation of such quotas to see how to change them. If you do, it would make sense to adapt the default configuration in deploy.sh – just search for "queues" and change the vaules according to the documentation of rate limits and retry parameters.

Alternatives to Scene Machine

< Caveats • Top

There is a vast array of tools to generate video ads automatically, ranging from animations of static assets with Auto-generated video ads for Responsive Search Ads to the creation of generic GenAI video using Flow or Vids. As the capabilities of the tools and the models they use are in continuous flux, it makes no sense to list them here.

One reason for Scene Machine to exist is for its authors to have a base from which to derive bespoke tools for individual advertisers. The existence of others with a similar service proposition, even if more comprehensive or better supported, will not necessarily mean that work on this one is discontinued.