UGC Script Generator for Veo 3

A React/Express application that transforms UGC (User Generated Content) scripts into AI-ready video segments with integrated Google Veo 3 support. The system uses OpenAI GPT-4 to intelligently split scripts into 8-second segments with detailed character descriptions, clothing specifications, and continuity markers.

What This Skill Does

This skill helps you work with a full-stack application that:

1. **Processes UGC scripts** using OpenAI GPT-4 to create video-ready segments

2. **Generates detailed JSON** with 300-500+ word character descriptions per segment

3. **Integrates with Google Veo 3** for AI video generation (Gemini API or Vertex AI)

4. **Maintains visual continuity** across segments with precise transition planning

5. **Supports multiple modes**: Standard, Enhanced Continuity, and Continuation modes

6. **Exports bulk results** as downloadable ZIP files

Architecture

**Backend (Express)**

**Frontend (React)**

Step-by-Step Instructions

1. Environment Setup

Before running any commands, verify the `.env` file exists with required keys:

```bash

OPENAI_API_KEY=sk-...

Choose ONE Google authentication method:

GOOGLE_GEMINI_API_KEY=... # Option A: Gemini API (Recommended)

GOOGLE_APPLICATION_CREDENTIALS=... # Option B: Vertex AI

VERTEX_PROJECT_ID=...

VERTEX_LOCATION=us-central1

```

2. Installation

Install all dependencies for both server and client:

```bash

npm run install-all

```

3. Development Workflow

For active development with hot reload:

```bash

npm run dev:watch

```

For standard development (manual refresh):

```bash

npm run dev

```

4. Production Build

Build the React client and start the production server:

```bash

npm run build

npm start

```

5. Working with OpenAI Prompt Templates

The system uses four key templates in the project:

**ugc-template.md** - Standard 300+ word descriptions

**veo3-enhanced-continuity.md** - Enhanced 500+ word descriptions

**veo3-continuation-minimal.md** - Continuation mode (after first segment)

**veo3-json-guidelines.md** - Base requirements for all formats

6. API Development

When modifying API endpoints:

1. **Read existing routes** in `api/routes/` to understand current patterns

2. **Update service files** in `api/services/` for external integrations

3. **Test manually** via development server (no automated tests configured)

4. **Document changes** in API_DOCS.md

Key endpoints:

7. Frontend Component Updates

When modifying React components:

1. **Check App.js** for tab navigation and state management

2. **Update forms** in ScriptForm.js for new input fields

3. **Modify VideoGenerator.js** for Veo 3 integration changes

4. **Enhance ResultsDisplay.js** for new JSON format displays

5. **Test in browser** with hot reload (dev:watch)

8. Debugging Tips

9. Adding New Features

Follow this pattern:

1. **Plan the change** - Identify affected files (backend vs frontend)

2. **Update backend** - Add routes/services if API changes needed

3. **Update frontend** - Modify components for new UI/behavior

4. **Update templates** - Adjust OpenAI prompts if segment format changes

5. **Test manually** - Verify end-to-end flow works

6. **Update docs** - Document new features in API_DOCS.md and CLAUDE.md

10. Common Tasks

**Add a new segment format:**

1. Create new template .md file with prompt structure

2. Add new route in `api/routes/`

3. Update OpenAI service to reference new template

4. Add UI option in ScriptForm.js

**Modify segment timing:**

1. Update prompt templates with new duration

2. Adjust word count calculations in openaiService.js

3. Update validation logic in frontend

**Change authentication method:**

1. Update .env with new credentials

2. Modify veo3Service.js to use different auth flow

3. Test video generation still works

Constraints and Notes

Example Usage

**Starting development:**

```bash

npm run install-all

npm run dev:watch

Open browser to http://localhost:3001

```

**Building for production:**

```bash

npm run build

npm start

Server ready on port 3001

```

**Testing API directly:**

```bash

curl -X POST http://localhost:3001/api/health

curl -X POST http://localhost:3001/api/generate \

-H "Content-Type: application/json" \

-d '{"script": "Your UGC script here...", "settings": {...}}'

```